Skip to content

上线前的工程检查 ​

本篇要点:能在上线评审会上拿出一张有阈值、有验证方式、能签字的检查表,并说清每一条不达标会出什么事。 前置文章:《进阶:Java 与 Python 模型服务协作》把 Java 网关和 Python 推理服务的边界划好了,这一章检查这条链路在流量、故障、账单和监管四件事上是否站得住。

为什么需要它 ​

2026 年 3 月,一个客服问答功能灰度到 5%。上线两小时,P99 从 1.2 秒涨到 11 秒,随后接口大面积 503。回滚之后复盘,根因不是模型慢,是一行配置。

Spring AI 的重试默认值是这样的:spring.ai.retry.max-attempts 默认 10,退避初始 2 秒、倍数 5、上限 3 分钟。按这个参数,第一次失败等 2 秒,第二次 10 秒,第三次 50 秒,第四次 250 秒,以此类推。一个 429 进去,十个请求的线程在里面待十几分钟。上游限流本来是为了保护自己,我们的重试把它变成了自我加压。

这份参数表在 Spring AI 的 OpenAI 文章里写得清清楚楚,只是没人翻到那一页。默认值不是错的,它假设的是「偶发网络抖动」;而 429 是「对方明确要求你慢下来」,语义完全相反。

这一章把上线前必须过的检查整理成可执行的清单。不是「注意性能」这种话,是「这一项填多少、怎么验、不通过会怎样」。

核心概念 ​

时间预算:从入口倒推,逐跳扣减 ​

时间预算(timeout budget)指一次用户请求允许消耗的总时长,以及它如何分配给链路上的每一跳。

做法是先从入口定一个数,再往下减,而不是每层各自拍一个超时。表 12-1 是一个可以照着填的例子。

环节预算依据超了怎么办
入口(网关)8000ms 总预算用户 10 秒内会关页面直接 503,不进下游
检索(向量库)1200msP99 实测 700ms,留 1.7 倍跳过检索,改为纯模型回答
模型生成5500ms512 token × 约 10ms/token切断,返回已生成部分
工具调用1000ms下游 3 次重试之内不再重试,把失败写进上下文
回写与渲染300ms本地操作记日志,不影响返回

表 12-1 一次 8 秒请求的时间预算分解(下面四项加起来正好是入口的 8000ms)

反例:每一层都配 8 秒。四跳串起来最坏 32 秒,而用户在第 10 秒就走了。剩下的 22 秒里,系统还在为一个已经离开的人烧 GPU。

熔断:先定义什么算失败 ​

熔断器(circuit breaker)有三个状态:关闭(closed,正常放行)、打开(open,直接拒绝)、半开(half-open,放几个探针试探)。

关键不在三个状态,在「什么算一次失败」。这套判定写错,熔断器会变成故障放大器。

  • 算失败:超时、5xx、429、连接被拒。
  • 不算失败:400 参数错误(是我的 bug,不是下游的)、用户主动取消、内容审核拒绝。
  • 绝对不算:舱满(bulkhead full)和熔断器自己抛的拒绝异常。把这两个计入失败率,会出现「舱一满就熔断、一熔断更多请求被拒」的连锁。Resilience4j 里要用 ignoreExceptions 显式排掉。

四道闸门的顺序如图 12-1 所示,顺序本身就是设计:配额和限流放最前,因为它们最便宜;熔断和隔离舱放后面,因为它们要看下游的真实状态。顺序颠倒的代价很实在——先占线程再判断配额,等于用最贵的资源去做最便宜的判断。

图 12-1 请求经过的四道闸门,以及失败如何汇入两条降级出口

成本:三层上限,缺一层都会漏 ​

单请求上限(max-tokens)挡住的是「一次调用写出一万字」。租户日配额挡住的是「一个客户把你的月度预算用光」。全局日预算挡住的是「所有人都正常使用,加起来超了」。

三层要分别配,因为它们的失效方式不同:只配单请求上限,批量任务能跑出天文数字;只配全局预算,一个大客户能把当天额度吃到见底,别的客户全部不可用。

超限之后做什么,是产品决策不是技术决策。可选的动作:拒绝新请求但允许在途完成、返回缓存答案并标注时间、降级到小模型、转人工。选哪个都要写进文档,并且演练过。

数据出境:三条路径,一个清单 ​

《个人信息保护法》第 38 条给了三条路径:通过国家网信部门的安全评估、签订个人信息出境标准合同并备案、通过个人信息保护认证。2024 年的《促进和规范数据跨境流动规定》又给了一些豁免场景(例如非关键信息基础设施运营者、一年内累计向境外提供不满 10 万人且不含敏感个人信息),具体适用以现行规定和属地网信办口径为准,见国家互联网信息办公室。

技术上要做的三件事:最小化(只发必要的字段,别把整张工单丢过去)、脱敏(手机号、身份证、地址在进 prompt 之前替换成占位符)、区域化端点(用区域内 endpoint,别让 SDK 默认走全球域名)。

最容易漏的是「顺手发出去的东西」:APM 的 trace 里带 prompt 原文、日志里打了完整响应、评测集把真实工单存到了境外对象存储。这些都不经过模型调用代码,所以代码评审看不见。

灰度:四层要能分别回滚 ​

一个 AI 功能的「版本」不止代码一层。至少四层:代码、prompt 模板、模型别名、检索索引。

回滚能力按层独立评估。代码能回滚但 prompt 存在数据库里改了就回不去,等于没有回滚。索引换了一版 embedding 模型却不能切回旧索引,等于把整个知识库押在一次发布上。

判断标准很朴素:出问题时,你能不能在不发版的前提下,十分钟内让系统回到上一个已知良好状态。 四层里任何一层做不到,这一项就不算通过。

动手实践 ​

版本基线:JDK 17+、Spring Boot 4.1.x、Spring AI 2.0.x、Resilience4j 2.x(Boot 3 用 resilience4j-spring-boot3,Boot 4 的 starter 名以官方文档为准)、Micrometer + Actuator。截至 2026 年 11 月,Spring AI 2.0.x 对应 Spring Boot 4.0/4.1,重试与超时属性见官方 OpenAI Chat 配置表;模型单价与上下文长度随厂商调整,这里不写具体数字。

步骤 1:先把重试和超时收到合理值 ​

yaml
spring:
  ai:
    retry:
      max-attempts: 2                 # 默认 10,一个 429 能挂住线程十几分钟
      backoff:
        initial-interval: 500ms
        multiplier: 2
        max-interval: 3s
      on-client-errors: false         # 4xx 不重试,直接抛 NonTransientAiException
      exclude-on-http-codes: 429      # 对方要求你慢下来,重试等于加压
    openai:
      timeout: 20s
      max-retries: 1                  # SDK 自己还有一层重试,别叠成 2×2

resilience4j:
  circuitbreaker:
    instances:
      chat:
        sliding-window-type: COUNT_BASED
        sliding-window-size: 20
        minimum-number-of-calls: 10
        failure-rate-threshold: 50
        wait-duration-in-open-state: 30s
        permitted-number-of-calls-in-half-open-state: 3
        ignore-exceptions:   # 这三类不是下游故障,计入失败率会让熔断器误判
          - io.github.resilience4j.bulkhead.BulkheadFullException
          - io.github.resilience4j.ratelimiter.RequestNotPermitted
          - io.github.resilience4j.circuitbreaker.CallNotPermittedException
  bulkhead:
    instances:
      chat:
        max-concurrent-calls: 16
        max-wait-duration: 0
  ratelimiter:
    instances:
      chat:
        limit-for-period: 50
        limit-refresh-period: 1s
        timeout-duration: 0

运行结果:启动后 /actuator/circuitbreakers 能看到 chat 实例状态为 CLOSED,/actuator/metrics/resilience4j.circuitbreaker.state 有数值。把上游地址改成一个不存在的端口,连续失败 10 次(等于 minimum-number-of-calls)之后状态转 OPEN,此后请求不再打到下游。

步骤 2:给调用加熔断、限流和降级 ​

java
package top.mqxu.ai.guard;

import io.github.resilience4j.bulkhead.annotation.Bulkhead;
import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;
import io.github.resilience4j.ratelimiter.annotation.RateLimiter;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;

@Service
public class AiCallGuard {

    private static final Logger log = LoggerFactory.getLogger(AiCallGuard.class);

    private final ChatClient chatClient;

    public AiCallGuard(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    // 切面顺序固定为 Retry > CircuitBreaker > RateLimiter > Bulkhead
    @CircuitBreaker(name = "chat", fallbackMethod = "degrade")
    @RateLimiter(name = "chat")
    @Bulkhead(name = "chat")
    public String answer(String tenantId, String question) {
        return chatClient.prompt()
                .user(question)
                .call()
                .content();
    }

    // 降级方法必须同签名 + 一个异常参数,且写在同一个类里
    String degrade(String tenantId, String question, Throwable t) {
        log.warn("模型不可用,转人工 tenant={} cause={}", tenantId, t.toString());
        return "当前咨询量较大,已为你创建工单,人工顾问会在 30 分钟内联系你";
    }
}

运行结果:

text
2026-11-16T21:31:45.411+08:00  WARN 8123 --- [nio-8080-exec-6] t.m.a.guard.AiCallGuard : 模型不可用,转人工 tenant=T-2041 cause=CallNotPermittedException
{"answer":"当前咨询量较大,已为你创建工单,人工顾问会在 30 分钟内联系你"}

$ curl -s localhost:8080/actuator/circuitbreakers | jq '.circuitBreakers.chat.state'
"OPEN"

注意 degrade 里没有再去调模型,也没有调外部接口。降级路径要能在「所有下游都挂了」的前提下工作,否则它只是把故障推后一步。《进阶:Java 与 Python 模型服务协作》说过降级不能走公网 API,这里同理。

步骤 3:成本上限落成代码 ​

java
package top.mqxu.ai.guard;

import java.time.Duration;
import java.time.LocalDate;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;

@Component
public class BudgetGuard {

    private static final Logger log = LoggerFactory.getLogger(BudgetGuard.class);

    // 示例值,按自己的账单倒推:日预算 ÷ 单价 ≈ 可用 token 数
    private static final long DAILY_TOKEN_QUOTA = 2_000_000L;

    private final StringRedisTemplate redis;

    public BudgetGuard(StringRedisTemplate redis) {
        this.redis = redis;
    }

    /** 调用前预扣,调用后按实际 usage 补差。false 表示配额已用尽 */
    public boolean tryReserve(String tenantId, long estimatedTokens) {
        String key = "ai:budget:" + tenantId + ":" + LocalDate.now();
        Long used = redis.opsForValue().increment(key, estimatedTokens);
        if (used != null && used == estimatedTokens) {
            // 只在第一次写入时设过期,否则每次刷新都会把 TTL 往后推
            redis.expire(key, Duration.ofDays(2));
        }
        if (used != null && used > DAILY_TOKEN_QUOTA) {
            log.warn("租户日配额用尽 tenant={} used={} quota={}",
                     tenantId, used, DAILY_TOKEN_QUOTA);
            return false;
        }
        return true;
    }
}

运行结果:

text
2026-11-16T21:33:10.117+08:00  WARN 8123 --- [nio-8080-exec-11] t.m.a.guard.BudgetGuard : 租户日配额用尽 tenant=T-3312 used=2004106 quota=2000000

# 查当前累计用量
$ redis-cli GET "ai:budget:T-2041:2026-11-16"
"413772"

两个坑要提前处理。一是预扣之后调用失败要退还(decrement),否则一次故障会把当天配额吃掉大半。二是 INCRBY 只保证不超发,不保证准确:并发下实际用量会略低于预扣值,所以配额要留 5% 余量,别把账算死。

步骤 4:把回滚练一遍 ​

bash
# 切流量:只改网关读到的版本号,分多少比例由网关按租户哈希算(见[《进阶:Java 与 Python 模型服务协作》](/guide/java-ai/java-ai-python-interop.html) pickAlias)
kubectl set env deploy/ai-gateway PROMPT_VERSION=v2 --namespace=ai
kubectl set env deploy/ai-gateway MODEL_ALIAS=invoice-vision-canary --namespace=ai

# 回滚:四层分别回,先摘模型,再回 prompt,最后才考虑回代码
kubectl set env deploy/ai-gateway MODEL_ALIAS=invoice-vision --namespace=ai
kubectl set env deploy/ai-gateway PROMPT_VERSION=v1 --namespace=ai

# 验证:同一批租户的答案要回到上一版形态,且错误率回到基线
curl -s localhost:8080/actuator/metrics/ai.chat.error.rate | jq '.measurements[0].value'   # 自定义指标,埋点见[《可观测与护栏:成本、延迟与安全》](/guide/java-ai/java-ai-observability-guardrails.html)

运行结果:

text
0.041

0.041 是基线错误率。回滚后 3 分钟内回到这个数才算回滚成功;如果 10 分钟后还高,说明故障不在这一层,继续往下摘。

步骤 5:对着表签字 ​

检查项通过标准验证方式
重试max-attempts ≤ 2,429 在排除列表注入 429 打一遍,看线程是否堆积
超时客户端超时 < 服务端超时,逐跳递减用 tc 注入 3 秒延迟
熔断失败率 50%、打开 30 秒、半开 3 探针手动停上游 30 秒
成本三层上限都有,超限行为已确认压测跑满单租户配额
合规出境字段清单已签字,脱敏有单测抽查 trace 与日志样本
灰度5% → 25% → 100%,每档看 30 分钟按租户维度看错误率与成本
回滚四层各演练过一次,总时长 ≤ 10 分钟真回滚一次并计时

表 12-2 上线前检查清单(可直接作为评审签字页)

常见误解 ​

很多人以为重试能提高可用性,所以次数越多越稳。实际上在 429 和超时场景里,重试是把故障放大:上游已经过载,你的每一次重试都在给它加一份负载,同时占着自己的线程。Spring AI 默认 10 次不是 bug,它面向的是偶发网络抖动;面向限流的正确做法是把次数压到 2 次以内、退避上限压到几秒,并把 429 直接排除。

很多人以为降级就是返回一句「服务繁忙,请稍后再试」。实际上降级要有产品语义:能不能给一个有时效标注的缓存答案、能不能缩小上下文重问一次、能不能只返回检索到的原文让用户自己判断、能不能转人工。而且降级分支必须演练过——没演练过的降级,在真故障里大概率自己先抛异常。

很多人以为数据合规是模型厂商的事,签完 DPA 就结束了。实际上真正出境的是那些「顺手发出去的东西」:APM 的 trace 里带 prompt 原文、日志里打了完整响应、评测集把真实工单存到了境外对象存储、灰度对比把两侧输出都写进了第三方表格。这些路径不经过模型调用代码,代码评审看不见,只能靠字段清单和日志抽样来查。

小结 ​

  • 时间预算从入口倒推、逐跳扣减;每一层都配同一个超时,等于没有超时。
  • 熔断要先定义什么算失败:429 和超时算,400 和用户取消不算,舱满和熔断器自己的拒绝绝对不算。
  • 成本三层上限(单请求、租户日配额、全局日预算)的失效方式各不相同,缺一层就有一个能烧穿账单的缺口。
  • 数据出境三条路径要按现行规定确认适用,技术侧做最小化、脱敏、区域化端点,并把日志和 trace 一并纳入清单。
  • 回滚要看四层:代码、prompt、模型别名、检索索引;十分钟内回不到已知良好状态,这一项就是没通过。
  • 《进阶:Java 与 Python 模型服务协作》的隔离舱解决「一个租户拖垮所有人」,这一章的预算和熔断解决「一次故障拖垮一整天」,两者配合才构成完整的失败处理。

相关主题 ​

这十二篇技术文章到这里收尾。接下来值得做的是三件让这套东西持续有效的事:把表 12-2 变成 PR 模板里的勾选项,让每次涉及模型的改动都过一次;把《AI 功能的测试策略》的录制回放接进 CI,让 prompt 改动有回归可依;把《可观测与护栏:成本、延迟与安全》的 Micrometer 指标接到成本看板,让预算变成可观测的数字而不是月底的惊讶。类目首页在 Java AI 工程开发。