上线前的工程检查
本篇要点:能在上线评审会上拿出一张有阈值、有验证方式、能签字的检查表,并说清每一条不达标会出什么事。 前置文章:《进阶: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,不进下游 |
| 检索(向量库) | 1200ms | P99 实测 700ms,留 1.7 倍 | 跳过检索,改为纯模型回答 |
| 模型生成 | 5500ms | 512 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:先把重试和超时收到合理值
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:给调用加熔断、限流和降级
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 分钟内联系你";
}
}运行结果:
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:成本上限落成代码
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;
}
}运行结果:
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:把回滚练一遍
# 切流量:只改网关读到的版本号,分多少比例由网关按租户哈希算(见[《进阶: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)运行结果:
0.0410.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 工程开发。