W2 教程超时、重试与错误分类 —— 让 AI 调用不再偶发卡死本周交付物一个LlmClient能把模型调用这件事变得像数据库调用一样可预期 —— 超时可控、失败可分类、重试有边界、日志可追溯。前置要求W1 已完成能成功调一次模型能看到 token 数。本周耗时4 小时主块 2 小时轻任务。0. 先看这个为什么 W2 比 W1 重要W1 你做到的是能跑。但能跑和能上线之间隔着一段所有后端都熟悉、但在 AI 场景里被重新发明的路。看三个真实会发生的事场景 A某天下午三点网关开始限流返回 429。你的接口没有任何处理直接把 429 抛给了前端。前端弹系统错误。用户重试了三次还是错。客服收到 8 个投诉。你排查了两小时发现网关那边只返了 3 秒错误 —— 实际影响却被放大成了半小时。场景 B你把max_tokens从 1024 改成 2048但参数名拼错了一个字母。网关返回 400。框架自带的重试机制不知道 400 不该重试于是老老实实重试了 2 次。你的日志里出现 3 条一模一样的报错留给排查者的第一印象是是不是网关挂了三次而不是我的代码写错了。场景 C大促期间有一个请求卡在等模型响应上因为没人设读超时。这个线程一直不释放。线程池满了。整个服务不可用但 CPU 和内存都正常监控上什么也看不出来。你重启了服务问题消失 —— 然后在下个流量高峰再次出现。这三个场景的共同点是它们都不是 AI 的问题是分布式调用的老问题。你作为后端已经知道该怎么处理 HTTP 调用W2 要做的是把这套经验迁移到 LLM 调用上并且识别出 LLM 特有的那几个差异点。1. 两层超时为什么必须设两个注意超时时间是有两个概念一个是连接超时connectTimeout建议配置3秒如果不配置系统会等很长时间一个是请求超时readTimeout建议配置30秒如果不配置系统会一直等着响应这是 LLM 调用和普通 HTTP 调用最大的差异点也是最多人踩的坑。普通 REST 调用通常 100ms 返回。你设一个 5 秒超时够了。但 LLM 调用是 3~30 秒量级而且它的失败方式有两种对应两个完全不同的阶段阶段发生什么该设哪个超时不设的后果TCP 握手你的机器要连上网关。网关宕机、DNS 挂了、防火墙挡了connectTimeout建议3 秒操作系统默认可能等 75 秒。3 个并发就把 Tomcat 线程池拖死等模型说话连接已建立请求已发出模型正在推理可能需要 20 秒readTimeout建议30 秒看模型大小线程永远挂着直到网关那边超时断开。可能是几分钟只设一个会怎样大多数 HTTP 客户端库如果只给一个叫timeout的参数它通常只作用于读超时或者只作用于连接超时视库而定。这就是为什么我明明设了超时还是卡死了。在 LangChain4j 里怎么写OpenAiChatModel.builder()上有两个位置需要设OpenAiChatModel.builder().baseUrl(b.baseUrl).apiKey(b.apiKey).modelName(b.modelName).timeout(b.readTimeout)// ← 读超时.httpClientBuilder(newJdkHttpClientBuilder().connectTimeout(b.connectTimeout)// ← 连接超时.readTimeout(b.readTimeout)).build();注意两点.timeout(...)是 LangChain4j 自己的参数.httpClientBuilder(...)里的才是底层 HTTP 客户端的。两个都要设因为你不知道框架内部哪个生效。JdkHttpClientBuilder来自langchain4j-http-client-jdk。这个包在 W1 的 pom 里已经显式声明了 —— 如果你跳过了那一步现在会报找不到符号。它是 runtime scope 的传递依赖编译期不可见必须自己写进 pom。怎么验证它真的生效这是本周的第一个动手环节。不要靠读文档相信它生效了要制造故障。FaultGateway里有一个#[slow]场景收到请求后睡 5 秒再返回。你把readTimeout设成 800ms如果超时真的生效你应该在约 0.8 秒后拿到一个TIMEOUT错误而不是等 5 秒拿到正常响应。这个验证在后面的故障演练里会自动跑场景 6实测结果attempts2总耗时约 1.6 秒800ms × 2 次 少量退避。数字对得上说明超时生效。2. 框架自带的 maxRetries为什么不能直接用OpenAiChatModel有一个maxRetries参数默认值是 2。看起来框架帮我重试了我不用管实际上它有三个行为会让你在生产里吃亏。我读了RetryUtils.withRetry的源码行为是这样的行为一只放弃NonRetriableException其他全重试抛出 NonRetriableException → 立即放弃 抛出其他任何异常 → 重试其他任何异常包括什么包括你自己的NullPointerException、ClassCastException、参数拼写错误导致的IllegalArgumentException。这意味着你写错一行代码同一次调用里这段坏代码被执行 3 遍。日志里出现 3 条报错。你排查时会先怀疑网关不稳定然后才想到看自己的代码。正确的做法是反过来默认可重试白名单式地认定哪些不该重试。因为不认识的错误重试 3 遍代价远大于收益。行为二退避参数是固定的 1 秒起步delay * 1.5^retry 0~20% 加性抖动delay默认 1000ms。问题在于这个退避不感知网关的Retry-After头。如果网关明确告诉你请等 10 秒框架还是按 1 秒、1.5 秒的节奏重试你会在网关还没恢复的时候继续打它 —— 从重试变成攻击。行为三没有总时限maxRetries2意味着最多 3 次尝试。按 1 秒 1.5 秒的退避算加上每次调用的耗时一次逻辑调用最长可能拖到 10 秒以上如果每次调用本身要 3 秒。你没法回答这个接口最长多久返回这个问题。这在前端体验上是致命的用户不知道自己是该等还是该刷新。所以这一周的第一件事在LlmClient里写.maxRetries(0)// 关掉框架重试重试权收归自己然后自己写循环。这样你才知道每一次重试发生在什么时候、为什么、等了多久。3. 错误三分法RETRIABLE / NEED_HUMAN / FATAL这是 W2 的核心思想。所有错误不管它叫什么名字、来自哪一层最后都必须落进这三类之一。分类含义该怎么做典型错误RETRIABLE现在不行等一会可能行退避后重试429、500、502、503、读超时、连接重置NEED_HUMAN重试多少次都一样得有人改东西立刻失败上报400参数错、401密钥错、404模型名错、余额不足FATAL内容本身不行换时间也没用立刻失败且不要记成服务故障内容审核拦截、超出上下文长度为什么是三类而不是两类很多人只分可重试 / 不可重试。这不够因为NEED_HUMAN和FATAL的处理方式完全不同NEED_HUMAN→ 要告警要进值班流程因为这是配置或代码问题不修就一直错。FATAL→不要告警。内容被审核拦截是业务正常的一部分用户发了违规内容如果把它算进服务错误率你的可用性看板会莫名其妙地变红然后所有人开始忽略告警。ErrorKind这个枚举里有个方法专门表达这个区别publicenumErrorKind{RETRIABLE(true),NEED_HUMAN(false),FATAL(false);privatefinalbooleanretryable;publicbooleanretryable(){returnretryable;}/** 只有这一类算服务自身的故障才该进错误率看板 */publicbooleancountsAsServiceFault(){returnthisRETRIABLE;}}分类逻辑怎么写ErrorClassifier用了三层判断顺序很重要第一层LangkChain4j 的异常类型。框架已经把一部分异常分好了类直接用RetriableException ├─ RateLimitException → 429 ├─ TimeoutException → 超时 ├─ InternalServerException → 5xx └─ UnresolvedModelServerException NonRetriableException ├─ InvalidRequestException → 400 ├─ AuthenticationException → 401 └─ ModelNotFoundException → 404第二层网络异常。这些框架不一定包成自己的类型需要遍历cause链找IOException/SocketTimeoutException/ConnectException。第三层消息文本兜底。只有当上面两层都没命中时才用靠关键字匹配rate limit、insufficient_quota等。最关键的约定写在 Javadoc 里三层都没命中时默认归为NEED_HUMAN不是RETRIABLE。理由一个你不认识的异常重试 3 遍只会让日志更乱、用户等更久、问题被藏得更深。让它快速失败、暴露出来是更负责任的选择。这条规则和框架默认什么都重试正好相反是有意的。4. 退避策略从全抖动到下界抖动这部分是本周唯一一处我在实测中发现原方案有问题、然后改掉了实现的地方。值得单独说因为它是很好的例子看起来正确的教科书方案在你的场景下可能是错的。标准方案长什么样重试退避的经典做法叫exponential backoff with jitter指数退避 抖动AWS 那篇著名的博客推荐的是full jitter等待时间 random(0, min(cap, base * 2^attempt))好处是抖动范围大多个客户端同时失败时重试时间点分散得开不会形成第二次冲击波。它的问题我在写 W2 的故障演练第 8 个场景时想验证总预算 500ms 的护栏会不会提前截断。设置了baseDelay 2秒、totalBudget 500ms预期是预算不够第一次失败就直接放弃attempts 1。实测结果是attempts 2。排查发现full jitter 取的是random(0, 2000ms)这次抽到了63ms。63ms 第一次调用的耗时还是小于 500ms 的预算所以预算检查放行了于是打了第二次。63ms 的退避等于没有退避。对一个正在限流的网关来说这恰恰是我们最该避免的行为 —— 你说你在退避重试实际上你在连续猛打。改成了什么// 取下界抖动在 [capped*(1-ratio), capped] 之间随机longlow(long)(capped*(1.0-jitterRatio));longpickThreadLocalRandom.current().nextLong(Math.max(1,low),capped1);baseDelay 2秒、ratio 1.0时等待落在[1秒, 2秒]。既保留了不同客户端错开的好处又保证退避真的在退避。这个改动告诉你的三件事教科书方案有前提假设。Full jitter 假设你的目的是最大化分散但你的真实目的可能是既要分散、又要真的等待。目的不同公式该不同。断言要写你真正想保证的事。场景 8 的断言最后写的是attempts maxAttempts远少于 5 次而不是attempts 1。因为我要保证的是预算护栏生效不是恰好重试一次。写死成 1下次调baseDelay就会误报失败然后你开始怀疑正确的代码。实测才能发现。这个 bug 靠读代码是看不出来的 —— 代码完全符合 full jitter 的定义。是跑了、断言了、数字对不上才把它逼出来的。5. 结构化的调用日志W1 的CostMeter记了 token 和成本。W2 在此基础上加两个字段都是后面几周会反复用到的trace_id每次逻辑调用生成一个同一次调用里的所有重试共用一个 trace_id。为什么重要假设某次调用重试了 3 次最后成功。你在日志里搜这 3 条记录如果它们没有共同标识你没法判断这是 1 次调用重试了 3 次还是3 次独立调用各失败 1 次。这两个结论指向完全不同的排查方向。实现很简单publicstaticStringnewTraceId(){returnLong.toHexString(System.nanoTime())-Long.toHexString(ThreadLocalRandom.current().nextLong());}不是 UUID 是因为可读、短、本地生成无依赖。W18 接 OpenTelemetry 时会换成标准的 W3C trace context但现在这样就够用。prompt_version每次调用带上 prompt 的版本号v1.0.0。W7 开始你会改 prompt改完之后效果变好还是变坏没有这个字段你根本对不上账。PII 脱敏顺序是有讲究的电商场景的日志里会出现手机号、身份证、银行卡、订单号。直接打日志 数据泄露。CallLog.maskPii的实现正则的顺序不能换rr.replaceAll((?!\\d)(\\d{6})\\d{8}(\\d{3}[0-9Xx])(?!\\d),$1********$2);// 身份证 18 位rr.replaceAll((?!\\d)(\\d{4})\\d{8,12}(\\d{4})(?!\\d),$1********$2);// 银行卡rr.replaceAll((?!\\d)(1[3-9]\\d)\\d{4}(\\d{4})(?!\\d),$1****$2);// 手机号 11 位rr.replaceAll(\\bSN(\\d{4})\\d{8}(\\d{4})\\b,SN$1********$2);// 订单号为什么身份证必须在手机号前面一个 18 位身份证号比如110101199003078888它的前 11 位11010119900匹配不上手机号规则手机号要求1[3-9]开头第 2 位是 1不匹配1。这个例子碰巧安全。但如果身份证是13810119900307888 8—— 第 2 位是 3 —— 前 11 位13810119900完全符合手机号格式。如果先跑手机号规则身份证的前 11 位会被当成手机号脱敏成138****9900剩下3078888裸露在日志里。既泄露了信息又让脱敏后的字符串完全无法追溯。所以顺序是长的、格式严格的先匹配。身份证18 位固定→ 银行卡16~20 位→ 手机号11 位。另一条注意所有正则都用了(?!\d)和(?!\d)前后向断言。不加的话一个 30 位的流水号会从中截取 11 位当手机号脱敏结果面目全非。6. 故障演练8 个场景8 条断言这是 W2 的验收方式。不是跑一下没报错是断言每个场景下kind、code、attempts三个值精确匹配。为什么要用假网关因为真实网关不会按需返回 429。你没法控制它什么时候限流、什么时候慢。等它自然发生可能等一周而且发生时你正在处理别的事。FaultGateway是一个本地 HTTP 服务端口 18082靠请求体里的标记切换行为标记行为用来验证#[429]永远返回 429重试到上限后放弃#[429x2]前 2 次 429第 3 次正常重试真的能救回来#[500]永远 500可重试但重试完还是失败#[400]永远 400不该重试#[401]永远 401不该重试#[slow]睡 5 秒读超时生效#[reset]直接断开连接网络抖动#[ok]正常返回基线启动方式和 W1 的假网关一样。selfcheck-w2.sh会自动启停。实测结果8/8 通过PASS 限流永远429 失败 kindRETRIABLE codeRATE_LIMIT attempts3期望 3 PASS 限流2次后恢复 成功attempts3期望 3 PASS 服务端错误永远500 失败 kindRETRIABLE codeSERVER_ERROR attempts2期望 2 PASS 参数错误400 失败 kindNEED_HUMAN codeBAD_REQUEST attempts1期望 1 PASS 鉴权失败401 失败 kindNEED_HUMAN codeAUTH_FAILED attempts1期望 1 PASS 读超时慢响应 失败 kindRETRIABLE codeTIMEOUT attempts2期望 2 PASS 连接重置 失败 kindRETRIABLE codeUNKNOWN attempts2期望 2 PASS 预算耗尽的快速失败 attempts1应 5耗时2ms看第 4、5 行attempts1。这就是分类器在起作用 —— 400 和 401 被识别为NEED_HUMANshouldRetry返回 false一次都不重试。如果这里显示 3说明分类错了你的日志会被垃圾报错填满。看第 2 行attempts3且成功。这是重试存在的全部意义网关抖了 2 次第 3 次好了用户什么都没感觉到。演练过程中修的三个真问题这部分比结果本身更值得读 —— 因为这三个问题都很典型。问题 1网关的恢复计数器在场景间串了第一次跑场景 2#[429x2]失败attempts1直接成功。日志显示scene429 hit#5 (已达恢复次数返回正常)。原因FaultGateway用RECOVER_AFTER记录失败几次后恢复HITS记录这个场景被打了几次。这两个都是全局的。场景 1 已经把429打了 3 次场景 2 再进来时hit从 4 开始早过了RECOVER_AFTER2的门槛于是第一次就拿到 200。这是测试用例之间没有互相隔离。修法不是改断言那是掩盖问题而是在每个 drill 开始前调/__reset清空网关状态privatestaticvoidresetGateway(){/* POST /__reset */}这条教训值得记住当你发现一个测试结果不对第一反应应该是我的测试写对了吗而不是我的代码错了吗。这次是测试的错。但如果顺序反了你会去改一段正确的重试代码把它改坏。问题 2full jitter 让退避失效第 4 节已详述场景 8 期望attempts1实测attempts2因为抖动抽到了 63ms。改实现为下界抖动。问题 3我猜的错误码和框架实际给的码不一样写断言时我凭印象猜读超时的 code 是READ_TIMEOUT连接重置是CONNECTION_CLOSED。实测出来是读超时 →TIMEOUT框架的TimeoutException被识别了连接重置 →UNKNOWN底层是IOException: HTTP/1.1 header parser received no bytes三层判断都没命中落到默认兜底。猜 API 名字是最常见的时间浪费。正确做法是先跑一次、把实际的kind/code打出来、再拿真实值写断言。这也是为什么W2FailureDrill的失败信息里会把实际值和期望值并排打出来 —— 就是为了这个。7. 把 LlmClient 用起来W1 的W1CostLab是直接用ChatModel的。现在换成LlmClient你会得到重试、日志、trace_idLlmClientclientLlmClient.builder().fromEnv()// 读 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL.scene(after-sales-qa)// 场景名日志里和后面的成本看板都靠它.promptVersion(v1.0.0).readTimeout(Duration.ofSeconds(30)).retryPolicy(RetryPolicy.interactive()).build();try{LlmClient.Resultrclient.chat(我买的手机屏幕碎了能退吗);System.out.println(r.text());System.out.println(attemptsr.attempts() 耗时r.latencyMs()ms 成本r.costCny());}catch(LlmCallExceptione){switch(e.kind()){caseRETRIABLE-{/* 已经重试过了还是不行 → 走降级返回兜底话术 */}caseNEED_HUMAN-{/* 告警这是配置/代码问题 */}caseFATAL-{/* 内容问题正常拒绝不要告警 */}}}两个预设策略按场景选预设maxAttemptsbaseDelaymaxDelaytotalBudget适合RetryPolicy.interactive()3300ms4s20s用户在线等比如客服对话RetryPolicy.batch()41s20s90s后台跑批比如批量给历史工单打标降级接口chatOrEmpty()失败时不抛异常返回Optional.empty()。适合拿不到 AI 结果就用规则兜底的场景。8. 本周自测清单跑cd教程/W1-W4/ecom-agent-labbashselfcheck-w2.sh逐条对照全部打勾才算过输出结尾是通过 8 / 8场景 4400和场景 5401显示attempts1—— 证明不该重试的错误一次都没重试场景 22次后恢复显示成功attempts3—— 证明重试真的救回了一次失败场景 6读超时的后端日志里latency_ms在 800ms 附近不是 5000ms —— 证明读超时生效网关统计里400: 1、401: 1—— 网关侧确认只收到 1 次请求随便找一条成功日志能看到trace_id/prompt_version/scene/input_tokens/output_tokens/cost_cny六个字段加练选做20 分钟把你 W1 用的真实网关接进来跑W1CostLab那 20 条售后问题但用LlmClient。然后故意把apiKey改错一个字符观察是不是只失败 1 次不是 3 次、kind是不是NEED_HUMAN。故意把readTimeout设成 200ms比模型响应速度快观察attempts是否等于maxAttempts、总耗时是否被totalBudget拦住。这两条能验证在真实网关上你的分类器和退避逻辑一样成立。9. 一个必须说清楚的取舍RetryPolicy里的retryAfterOf()目前是显式的空实现privatestaticDurationretryAfterOf(Throwablee){// 若你的网关会把 Retry-After 塞进错误消息这里可以加解析。// 留成显式的空实现比假装支持更诚实。returnnull;}LangChain4j 没有把 HTTP 响应头暴露到异常里所以拿不到Retry-After。我选择留一个空方法 注释而不是写一段看起来会解析、实际永远返回 null的代码。如果你们的网关会返回Retry-After并且你希望利用它两条路简单版让网关把秒数塞进错误消息比如Too many requests, retry after 3s用正则从e.getMessage()里捞。彻底版不依赖 LangChain4j 的 model 层自己用java.net.http.HttpClient直接发 OpenAI 兼容请求你能拿到完整的HttpResponse。代价是失去 LangChain4j 的抽象后面接 memory、tool 都要自己实现。我建议现在选简单版。因为 W2 的目标是调用可控不是完美利用每一个 HTTP 头。等 W8 你开始做多模型路由时如果那时还觉得需要再换。10. 常见问题QmaxRetries(0)会不会有副作用A不会。它只是关掉框架内部的循环。你的循环在外面次数由RetryPolicy.maxAttempts控制。唯一的注意点maxRetries0意味着框架不再重试你的循环必须写对否则一次都不重试。用selfcheck-w2.sh验证。Q为什么LlmClient不自己处理Retry-After要留给上层A因为它拿不到。见第 9 节。这不是设计选择是 API 限制所以我把它显式暴露出来而不是藏起来。Qtrace_id用nanoTime random跨机器会不会撞A会。但当前阶段不影响 —— 你在单机排查。W18 接 OpenTelemetry 时会替换成标准 trace context。现在用 UUID 的代价是日志变长、不可读收益不抵。Qattempts到底指总共调了几次还是重试了几次A总共调了几次从 1 开始。attempts1表示一次成功没重试attempts3表示失败了 2 次、第 3 次成功。这个定义写在Result的字段注释里别改。Q读超时设 30 秒会不会太长A看你模型。W1 实测那 20 条售后问题耗时 2995~15057msP95 约 10 秒。30 秒给了 3 倍余量。如果你用更小的模型比如 7B 级可以降到 10 秒。但不要低于你的 P99—— 否则正常慢请求会被当故障重试白白增加成本。Q我的网关连不上FaultGateway能测什么A不能用。FaultGateway是 W2 自带的独立假网关监听 18082 端口跟你的真实网关没有任何关系。如果你想验证真实网关的错误分类需要让网关那边配合返回各种错误码 —— 或者等 W4 自己做一层 mock 网关。当前先跑通自带演练。11. 三个待核实项和 W1 一样这些需要你在自己环境里确认不要当成已知事实你们的错误码是不是标准 OpenAI 格式。ErrorClassifier的消息兜底匹配是照着 OpenAI 的错误文案写的rate limit、insufficient_quota。如果内部网关的中文错误消息是请求过于频繁匹配不上会落到NEED_HUMAN默认分支 —— 结果是限流时不重试效果变差但不危险。建议拿到真实网关的 429 响应体看文案必要时往ErrorClassifier的消息模式里加一条。网关会不会主动断开长连接。如果网关侧有 60 秒的空闲连接回收而你的readTimeout设了 60 秒以上实际超时由网关决定你的配置形同虚设。建议问一下网关的同学或者故意发一个必然很慢的请求超长 prompt看多久被断开。JdkHttpClientBuilder是不是你想要的 HTTP 客户端。它是 JDK 自带的零额外依赖缺点是连接池行为不如 OkHttp 可调比如 no proxy、keep-alive 时长。如果你的网关在代理后面可能需要换成OkHttpClientBuilder要加langchain4j-http-client-okhttp依赖。建议W2 先用 JDK 的跑通等遇到实际问题再换。12. 本周小结你现在有一个LlmClient两层超时 分类重试 总预算 结构化日志一个ErrorClassifier三分类默认不重试一个RetryPolicy指数退避 下界抖动 Retry-After预留一个FaultGateway8 种故障按需复现不花钱一个W2FailureDrill8 条断言实证你的逻辑对不对下一周W3预告Prompt 工程与结构化输出。你会把自由文本回复变成能直接塞进业务对象里的 JSON并且处理模型不听话的情况返回的 JSON 缺字段、多字段、格式错。W2 的分类器和重试在那里会派上新用场 —— 因为模型输出格式不对也需要重试策略。附文件清单ecom-agent-lab/ ├── pom.xml ├── cp.txt # mvn dependency:build-classpath -Dmdep.outputFilecp.txt ├── selfcheck-w1.sh ├── selfcheck-w2.sh # ← 本周验收 ├── w1-cost-log.csv ├── src/main/java/com/company/lab/ │ ├── W1Hello.java # W1第一次成功调用 │ ├── CostMeter.java # W1成本计算 │ ├── W1CostLab.java # W120 条售后问题实测 │ ├── FakeGateway.java # W1简易假网关18081 │ ├── FaultGateway.java # W2故障注入网关18082 │ ├── ErrorKind.java # W2三分类枚举 │ ├── LlmCallException.java # W2统一异常 │ ├── ErrorClassifier.java # W2三层分类 │ ├── RetryPolicy.java # W2退避策略 │ ├── CallLog.java # W2结构化日志 PII 脱敏 │ ├── LlmClient.java # W2主交付物 │ └── W2FailureDrill.java # W28 场景演练附实测数据速查写简历/汇报时可用W2 演练的实测结论可直接作为我做过什么的素材8 种故障场景全部按预期分类400/401 场景确认零重试attempts1429 场景确认重试 3 次后放弃恢复型场景确认第 3 次成功读超时设为 800ms 时端到端耗时约 1.6 秒2 次尝试证明超时配置生效发现并修复 full jitter 导致退避失效的问题实测抖动后可低至 63ms改为下界抖动后最短 1000ms建立测试用例隔离规范每个 drill 前重置网关状态避免计数器串扰导致假红
W2 教程超时、重试与错误分类 —— 让 AI 调用不再偶发卡死本周交付物一个LlmClient能把模型调用这件事变得像数据库调用一样可预期 —— 超时可控、失败可分类、重试有边界、日志可追溯。前置要求W1 已完成能成功调一次模型能看到 token 数。本周耗时4 小时主块 2 小时轻任务。0. 先看这个为什么 W2 比 W1 重要W1 你做到的是能跑。但能跑和能上线之间隔着一段所有后端都熟悉、但在 AI 场景里被重新发明的路。看三个真实会发生的事场景 A某天下午三点网关开始限流返回 429。你的接口没有任何处理直接把 429 抛给了前端。前端弹系统错误。用户重试了三次还是错。客服收到 8 个投诉。你排查了两小时发现网关那边只返了 3 秒错误 —— 实际影响却被放大成了半小时。场景 B你把max_tokens从 1024 改成 2048但参数名拼错了一个字母。网关返回 400。框架自带的重试机制不知道 400 不该重试于是老老实实重试了 2 次。你的日志里出现 3 条一模一样的报错留给排查者的第一印象是是不是网关挂了三次而不是我的代码写错了。场景 C大促期间有一个请求卡在等模型响应上因为没人设读超时。这个线程一直不释放。线程池满了。整个服务不可用但 CPU 和内存都正常监控上什么也看不出来。你重启了服务问题消失 —— 然后在下个流量高峰再次出现。这三个场景的共同点是它们都不是 AI 的问题是分布式调用的老问题。你作为后端已经知道该怎么处理 HTTP 调用W2 要做的是把这套经验迁移到 LLM 调用上并且识别出 LLM 特有的那几个差异点。1. 两层超时为什么必须设两个注意超时时间是有两个概念一个是连接超时connectTimeout建议配置3秒如果不配置系统会等很长时间一个是请求超时readTimeout建议配置30秒如果不配置系统会一直等着响应这是 LLM 调用和普通 HTTP 调用最大的差异点也是最多人踩的坑。普通 REST 调用通常 100ms 返回。你设一个 5 秒超时够了。但 LLM 调用是 3~30 秒量级而且它的失败方式有两种对应两个完全不同的阶段阶段发生什么该设哪个超时不设的后果TCP 握手你的机器要连上网关。网关宕机、DNS 挂了、防火墙挡了connectTimeout建议3 秒操作系统默认可能等 75 秒。3 个并发就把 Tomcat 线程池拖死等模型说话连接已建立请求已发出模型正在推理可能需要 20 秒readTimeout建议30 秒看模型大小线程永远挂着直到网关那边超时断开。可能是几分钟只设一个会怎样大多数 HTTP 客户端库如果只给一个叫timeout的参数它通常只作用于读超时或者只作用于连接超时视库而定。这就是为什么我明明设了超时还是卡死了。在 LangChain4j 里怎么写OpenAiChatModel.builder()上有两个位置需要设OpenAiChatModel.builder().baseUrl(b.baseUrl).apiKey(b.apiKey).modelName(b.modelName).timeout(b.readTimeout)// ← 读超时.httpClientBuilder(newJdkHttpClientBuilder().connectTimeout(b.connectTimeout)// ← 连接超时.readTimeout(b.readTimeout)).build();注意两点.timeout(...)是 LangChain4j 自己的参数.httpClientBuilder(...)里的才是底层 HTTP 客户端的。两个都要设因为你不知道框架内部哪个生效。JdkHttpClientBuilder来自langchain4j-http-client-jdk。这个包在 W1 的 pom 里已经显式声明了 —— 如果你跳过了那一步现在会报找不到符号。它是 runtime scope 的传递依赖编译期不可见必须自己写进 pom。怎么验证它真的生效这是本周的第一个动手环节。不要靠读文档相信它生效了要制造故障。FaultGateway里有一个#[slow]场景收到请求后睡 5 秒再返回。你把readTimeout设成 800ms如果超时真的生效你应该在约 0.8 秒后拿到一个TIMEOUT错误而不是等 5 秒拿到正常响应。这个验证在后面的故障演练里会自动跑场景 6实测结果attempts2总耗时约 1.6 秒800ms × 2 次 少量退避。数字对得上说明超时生效。2. 框架自带的 maxRetries为什么不能直接用OpenAiChatModel有一个maxRetries参数默认值是 2。看起来框架帮我重试了我不用管实际上它有三个行为会让你在生产里吃亏。我读了RetryUtils.withRetry的源码行为是这样的行为一只放弃NonRetriableException其他全重试抛出 NonRetriableException → 立即放弃 抛出其他任何异常 → 重试其他任何异常包括什么包括你自己的NullPointerException、ClassCastException、参数拼写错误导致的IllegalArgumentException。这意味着你写错一行代码同一次调用里这段坏代码被执行 3 遍。日志里出现 3 条报错。你排查时会先怀疑网关不稳定然后才想到看自己的代码。正确的做法是反过来默认可重试白名单式地认定哪些不该重试。因为不认识的错误重试 3 遍代价远大于收益。行为二退避参数是固定的 1 秒起步delay * 1.5^retry 0~20% 加性抖动delay默认 1000ms。问题在于这个退避不感知网关的Retry-After头。如果网关明确告诉你请等 10 秒框架还是按 1 秒、1.5 秒的节奏重试你会在网关还没恢复的时候继续打它 —— 从重试变成攻击。行为三没有总时限maxRetries2意味着最多 3 次尝试。按 1 秒 1.5 秒的退避算加上每次调用的耗时一次逻辑调用最长可能拖到 10 秒以上如果每次调用本身要 3 秒。你没法回答这个接口最长多久返回这个问题。这在前端体验上是致命的用户不知道自己是该等还是该刷新。所以这一周的第一件事在LlmClient里写.maxRetries(0)// 关掉框架重试重试权收归自己然后自己写循环。这样你才知道每一次重试发生在什么时候、为什么、等了多久。3. 错误三分法RETRIABLE / NEED_HUMAN / FATAL这是 W2 的核心思想。所有错误不管它叫什么名字、来自哪一层最后都必须落进这三类之一。分类含义该怎么做典型错误RETRIABLE现在不行等一会可能行退避后重试429、500、502、503、读超时、连接重置NEED_HUMAN重试多少次都一样得有人改东西立刻失败上报400参数错、401密钥错、404模型名错、余额不足FATAL内容本身不行换时间也没用立刻失败且不要记成服务故障内容审核拦截、超出上下文长度为什么是三类而不是两类很多人只分可重试 / 不可重试。这不够因为NEED_HUMAN和FATAL的处理方式完全不同NEED_HUMAN→ 要告警要进值班流程因为这是配置或代码问题不修就一直错。FATAL→不要告警。内容被审核拦截是业务正常的一部分用户发了违规内容如果把它算进服务错误率你的可用性看板会莫名其妙地变红然后所有人开始忽略告警。ErrorKind这个枚举里有个方法专门表达这个区别publicenumErrorKind{RETRIABLE(true),NEED_HUMAN(false),FATAL(false);privatefinalbooleanretryable;publicbooleanretryable(){returnretryable;}/** 只有这一类算服务自身的故障才该进错误率看板 */publicbooleancountsAsServiceFault(){returnthisRETRIABLE;}}分类逻辑怎么写ErrorClassifier用了三层判断顺序很重要第一层LangkChain4j 的异常类型。框架已经把一部分异常分好了类直接用RetriableException ├─ RateLimitException → 429 ├─ TimeoutException → 超时 ├─ InternalServerException → 5xx └─ UnresolvedModelServerException NonRetriableException ├─ InvalidRequestException → 400 ├─ AuthenticationException → 401 └─ ModelNotFoundException → 404第二层网络异常。这些框架不一定包成自己的类型需要遍历cause链找IOException/SocketTimeoutException/ConnectException。第三层消息文本兜底。只有当上面两层都没命中时才用靠关键字匹配rate limit、insufficient_quota等。最关键的约定写在 Javadoc 里三层都没命中时默认归为NEED_HUMAN不是RETRIABLE。理由一个你不认识的异常重试 3 遍只会让日志更乱、用户等更久、问题被藏得更深。让它快速失败、暴露出来是更负责任的选择。这条规则和框架默认什么都重试正好相反是有意的。4. 退避策略从全抖动到下界抖动这部分是本周唯一一处我在实测中发现原方案有问题、然后改掉了实现的地方。值得单独说因为它是很好的例子看起来正确的教科书方案在你的场景下可能是错的。标准方案长什么样重试退避的经典做法叫exponential backoff with jitter指数退避 抖动AWS 那篇著名的博客推荐的是full jitter等待时间 random(0, min(cap, base * 2^attempt))好处是抖动范围大多个客户端同时失败时重试时间点分散得开不会形成第二次冲击波。它的问题我在写 W2 的故障演练第 8 个场景时想验证总预算 500ms 的护栏会不会提前截断。设置了baseDelay 2秒、totalBudget 500ms预期是预算不够第一次失败就直接放弃attempts 1。实测结果是attempts 2。排查发现full jitter 取的是random(0, 2000ms)这次抽到了63ms。63ms 第一次调用的耗时还是小于 500ms 的预算所以预算检查放行了于是打了第二次。63ms 的退避等于没有退避。对一个正在限流的网关来说这恰恰是我们最该避免的行为 —— 你说你在退避重试实际上你在连续猛打。改成了什么// 取下界抖动在 [capped*(1-ratio), capped] 之间随机longlow(long)(capped*(1.0-jitterRatio));longpickThreadLocalRandom.current().nextLong(Math.max(1,low),capped1);baseDelay 2秒、ratio 1.0时等待落在[1秒, 2秒]。既保留了不同客户端错开的好处又保证退避真的在退避。这个改动告诉你的三件事教科书方案有前提假设。Full jitter 假设你的目的是最大化分散但你的真实目的可能是既要分散、又要真的等待。目的不同公式该不同。断言要写你真正想保证的事。场景 8 的断言最后写的是attempts maxAttempts远少于 5 次而不是attempts 1。因为我要保证的是预算护栏生效不是恰好重试一次。写死成 1下次调baseDelay就会误报失败然后你开始怀疑正确的代码。实测才能发现。这个 bug 靠读代码是看不出来的 —— 代码完全符合 full jitter 的定义。是跑了、断言了、数字对不上才把它逼出来的。5. 结构化的调用日志W1 的CostMeter记了 token 和成本。W2 在此基础上加两个字段都是后面几周会反复用到的trace_id每次逻辑调用生成一个同一次调用里的所有重试共用一个 trace_id。为什么重要假设某次调用重试了 3 次最后成功。你在日志里搜这 3 条记录如果它们没有共同标识你没法判断这是 1 次调用重试了 3 次还是3 次独立调用各失败 1 次。这两个结论指向完全不同的排查方向。实现很简单publicstaticStringnewTraceId(){returnLong.toHexString(System.nanoTime())-Long.toHexString(ThreadLocalRandom.current().nextLong());}不是 UUID 是因为可读、短、本地生成无依赖。W18 接 OpenTelemetry 时会换成标准的 W3C trace context但现在这样就够用。prompt_version每次调用带上 prompt 的版本号v1.0.0。W7 开始你会改 prompt改完之后效果变好还是变坏没有这个字段你根本对不上账。PII 脱敏顺序是有讲究的电商场景的日志里会出现手机号、身份证、银行卡、订单号。直接打日志 数据泄露。CallLog.maskPii的实现正则的顺序不能换rr.replaceAll((?!\\d)(\\d{6})\\d{8}(\\d{3}[0-9Xx])(?!\\d),$1********$2);// 身份证 18 位rr.replaceAll((?!\\d)(\\d{4})\\d{8,12}(\\d{4})(?!\\d),$1********$2);// 银行卡rr.replaceAll((?!\\d)(1[3-9]\\d)\\d{4}(\\d{4})(?!\\d),$1****$2);// 手机号 11 位rr.replaceAll(\\bSN(\\d{4})\\d{8}(\\d{4})\\b,SN$1********$2);// 订单号为什么身份证必须在手机号前面一个 18 位身份证号比如110101199003078888它的前 11 位11010119900匹配不上手机号规则手机号要求1[3-9]开头第 2 位是 1不匹配1。这个例子碰巧安全。但如果身份证是13810119900307888 8—— 第 2 位是 3 —— 前 11 位13810119900完全符合手机号格式。如果先跑手机号规则身份证的前 11 位会被当成手机号脱敏成138****9900剩下3078888裸露在日志里。既泄露了信息又让脱敏后的字符串完全无法追溯。所以顺序是长的、格式严格的先匹配。身份证18 位固定→ 银行卡16~20 位→ 手机号11 位。另一条注意所有正则都用了(?!\d)和(?!\d)前后向断言。不加的话一个 30 位的流水号会从中截取 11 位当手机号脱敏结果面目全非。6. 故障演练8 个场景8 条断言这是 W2 的验收方式。不是跑一下没报错是断言每个场景下kind、code、attempts三个值精确匹配。为什么要用假网关因为真实网关不会按需返回 429。你没法控制它什么时候限流、什么时候慢。等它自然发生可能等一周而且发生时你正在处理别的事。FaultGateway是一个本地 HTTP 服务端口 18082靠请求体里的标记切换行为标记行为用来验证#[429]永远返回 429重试到上限后放弃#[429x2]前 2 次 429第 3 次正常重试真的能救回来#[500]永远 500可重试但重试完还是失败#[400]永远 400不该重试#[401]永远 401不该重试#[slow]睡 5 秒读超时生效#[reset]直接断开连接网络抖动#[ok]正常返回基线启动方式和 W1 的假网关一样。selfcheck-w2.sh会自动启停。实测结果8/8 通过PASS 限流永远429 失败 kindRETRIABLE codeRATE_LIMIT attempts3期望 3 PASS 限流2次后恢复 成功attempts3期望 3 PASS 服务端错误永远500 失败 kindRETRIABLE codeSERVER_ERROR attempts2期望 2 PASS 参数错误400 失败 kindNEED_HUMAN codeBAD_REQUEST attempts1期望 1 PASS 鉴权失败401 失败 kindNEED_HUMAN codeAUTH_FAILED attempts1期望 1 PASS 读超时慢响应 失败 kindRETRIABLE codeTIMEOUT attempts2期望 2 PASS 连接重置 失败 kindRETRIABLE codeUNKNOWN attempts2期望 2 PASS 预算耗尽的快速失败 attempts1应 5耗时2ms看第 4、5 行attempts1。这就是分类器在起作用 —— 400 和 401 被识别为NEED_HUMANshouldRetry返回 false一次都不重试。如果这里显示 3说明分类错了你的日志会被垃圾报错填满。看第 2 行attempts3且成功。这是重试存在的全部意义网关抖了 2 次第 3 次好了用户什么都没感觉到。演练过程中修的三个真问题这部分比结果本身更值得读 —— 因为这三个问题都很典型。问题 1网关的恢复计数器在场景间串了第一次跑场景 2#[429x2]失败attempts1直接成功。日志显示scene429 hit#5 (已达恢复次数返回正常)。原因FaultGateway用RECOVER_AFTER记录失败几次后恢复HITS记录这个场景被打了几次。这两个都是全局的。场景 1 已经把429打了 3 次场景 2 再进来时hit从 4 开始早过了RECOVER_AFTER2的门槛于是第一次就拿到 200。这是测试用例之间没有互相隔离。修法不是改断言那是掩盖问题而是在每个 drill 开始前调/__reset清空网关状态privatestaticvoidresetGateway(){/* POST /__reset */}这条教训值得记住当你发现一个测试结果不对第一反应应该是我的测试写对了吗而不是我的代码错了吗。这次是测试的错。但如果顺序反了你会去改一段正确的重试代码把它改坏。问题 2full jitter 让退避失效第 4 节已详述场景 8 期望attempts1实测attempts2因为抖动抽到了 63ms。改实现为下界抖动。问题 3我猜的错误码和框架实际给的码不一样写断言时我凭印象猜读超时的 code 是READ_TIMEOUT连接重置是CONNECTION_CLOSED。实测出来是读超时 →TIMEOUT框架的TimeoutException被识别了连接重置 →UNKNOWN底层是IOException: HTTP/1.1 header parser received no bytes三层判断都没命中落到默认兜底。猜 API 名字是最常见的时间浪费。正确做法是先跑一次、把实际的kind/code打出来、再拿真实值写断言。这也是为什么W2FailureDrill的失败信息里会把实际值和期望值并排打出来 —— 就是为了这个。7. 把 LlmClient 用起来W1 的W1CostLab是直接用ChatModel的。现在换成LlmClient你会得到重试、日志、trace_idLlmClientclientLlmClient.builder().fromEnv()// 读 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL.scene(after-sales-qa)// 场景名日志里和后面的成本看板都靠它.promptVersion(v1.0.0).readTimeout(Duration.ofSeconds(30)).retryPolicy(RetryPolicy.interactive()).build();try{LlmClient.Resultrclient.chat(我买的手机屏幕碎了能退吗);System.out.println(r.text());System.out.println(attemptsr.attempts() 耗时r.latencyMs()ms 成本r.costCny());}catch(LlmCallExceptione){switch(e.kind()){caseRETRIABLE-{/* 已经重试过了还是不行 → 走降级返回兜底话术 */}caseNEED_HUMAN-{/* 告警这是配置/代码问题 */}caseFATAL-{/* 内容问题正常拒绝不要告警 */}}}两个预设策略按场景选预设maxAttemptsbaseDelaymaxDelaytotalBudget适合RetryPolicy.interactive()3300ms4s20s用户在线等比如客服对话RetryPolicy.batch()41s20s90s后台跑批比如批量给历史工单打标降级接口chatOrEmpty()失败时不抛异常返回Optional.empty()。适合拿不到 AI 结果就用规则兜底的场景。8. 本周自测清单跑cd教程/W1-W4/ecom-agent-labbashselfcheck-w2.sh逐条对照全部打勾才算过输出结尾是通过 8 / 8场景 4400和场景 5401显示attempts1—— 证明不该重试的错误一次都没重试场景 22次后恢复显示成功attempts3—— 证明重试真的救回了一次失败场景 6读超时的后端日志里latency_ms在 800ms 附近不是 5000ms —— 证明读超时生效网关统计里400: 1、401: 1—— 网关侧确认只收到 1 次请求随便找一条成功日志能看到trace_id/prompt_version/scene/input_tokens/output_tokens/cost_cny六个字段加练选做20 分钟把你 W1 用的真实网关接进来跑W1CostLab那 20 条售后问题但用LlmClient。然后故意把apiKey改错一个字符观察是不是只失败 1 次不是 3 次、kind是不是NEED_HUMAN。故意把readTimeout设成 200ms比模型响应速度快观察attempts是否等于maxAttempts、总耗时是否被totalBudget拦住。这两条能验证在真实网关上你的分类器和退避逻辑一样成立。9. 一个必须说清楚的取舍RetryPolicy里的retryAfterOf()目前是显式的空实现privatestaticDurationretryAfterOf(Throwablee){// 若你的网关会把 Retry-After 塞进错误消息这里可以加解析。// 留成显式的空实现比假装支持更诚实。returnnull;}LangChain4j 没有把 HTTP 响应头暴露到异常里所以拿不到Retry-After。我选择留一个空方法 注释而不是写一段看起来会解析、实际永远返回 null的代码。如果你们的网关会返回Retry-After并且你希望利用它两条路简单版让网关把秒数塞进错误消息比如Too many requests, retry after 3s用正则从e.getMessage()里捞。彻底版不依赖 LangChain4j 的 model 层自己用java.net.http.HttpClient直接发 OpenAI 兼容请求你能拿到完整的HttpResponse。代价是失去 LangChain4j 的抽象后面接 memory、tool 都要自己实现。我建议现在选简单版。因为 W2 的目标是调用可控不是完美利用每一个 HTTP 头。等 W8 你开始做多模型路由时如果那时还觉得需要再换。10. 常见问题QmaxRetries(0)会不会有副作用A不会。它只是关掉框架内部的循环。你的循环在外面次数由RetryPolicy.maxAttempts控制。唯一的注意点maxRetries0意味着框架不再重试你的循环必须写对否则一次都不重试。用selfcheck-w2.sh验证。Q为什么LlmClient不自己处理Retry-After要留给上层A因为它拿不到。见第 9 节。这不是设计选择是 API 限制所以我把它显式暴露出来而不是藏起来。Qtrace_id用nanoTime random跨机器会不会撞A会。但当前阶段不影响 —— 你在单机排查。W18 接 OpenTelemetry 时会替换成标准 trace context。现在用 UUID 的代价是日志变长、不可读收益不抵。Qattempts到底指总共调了几次还是重试了几次A总共调了几次从 1 开始。attempts1表示一次成功没重试attempts3表示失败了 2 次、第 3 次成功。这个定义写在Result的字段注释里别改。Q读超时设 30 秒会不会太长A看你模型。W1 实测那 20 条售后问题耗时 2995~15057msP95 约 10 秒。30 秒给了 3 倍余量。如果你用更小的模型比如 7B 级可以降到 10 秒。但不要低于你的 P99—— 否则正常慢请求会被当故障重试白白增加成本。Q我的网关连不上FaultGateway能测什么A不能用。FaultGateway是 W2 自带的独立假网关监听 18082 端口跟你的真实网关没有任何关系。如果你想验证真实网关的错误分类需要让网关那边配合返回各种错误码 —— 或者等 W4 自己做一层 mock 网关。当前先跑通自带演练。11. 三个待核实项和 W1 一样这些需要你在自己环境里确认不要当成已知事实你们的错误码是不是标准 OpenAI 格式。ErrorClassifier的消息兜底匹配是照着 OpenAI 的错误文案写的rate limit、insufficient_quota。如果内部网关的中文错误消息是请求过于频繁匹配不上会落到NEED_HUMAN默认分支 —— 结果是限流时不重试效果变差但不危险。建议拿到真实网关的 429 响应体看文案必要时往ErrorClassifier的消息模式里加一条。网关会不会主动断开长连接。如果网关侧有 60 秒的空闲连接回收而你的readTimeout设了 60 秒以上实际超时由网关决定你的配置形同虚设。建议问一下网关的同学或者故意发一个必然很慢的请求超长 prompt看多久被断开。JdkHttpClientBuilder是不是你想要的 HTTP 客户端。它是 JDK 自带的零额外依赖缺点是连接池行为不如 OkHttp 可调比如 no proxy、keep-alive 时长。如果你的网关在代理后面可能需要换成OkHttpClientBuilder要加langchain4j-http-client-okhttp依赖。建议W2 先用 JDK 的跑通等遇到实际问题再换。12. 本周小结你现在有一个LlmClient两层超时 分类重试 总预算 结构化日志一个ErrorClassifier三分类默认不重试一个RetryPolicy指数退避 下界抖动 Retry-After预留一个FaultGateway8 种故障按需复现不花钱一个W2FailureDrill8 条断言实证你的逻辑对不对下一周W3预告Prompt 工程与结构化输出。你会把自由文本回复变成能直接塞进业务对象里的 JSON并且处理模型不听话的情况返回的 JSON 缺字段、多字段、格式错。W2 的分类器和重试在那里会派上新用场 —— 因为模型输出格式不对也需要重试策略。附文件清单ecom-agent-lab/ ├── pom.xml ├── cp.txt # mvn dependency:build-classpath -Dmdep.outputFilecp.txt ├── selfcheck-w1.sh ├── selfcheck-w2.sh # ← 本周验收 ├── w1-cost-log.csv ├── src/main/java/com/company/lab/ │ ├── W1Hello.java # W1第一次成功调用 │ ├── CostMeter.java # W1成本计算 │ ├── W1CostLab.java # W120 条售后问题实测 │ ├── FakeGateway.java # W1简易假网关18081 │ ├── FaultGateway.java # W2故障注入网关18082 │ ├── ErrorKind.java # W2三分类枚举 │ ├── LlmCallException.java # W2统一异常 │ ├── ErrorClassifier.java # W2三层分类 │ ├── RetryPolicy.java # W2退避策略 │ ├── CallLog.java # W2结构化日志 PII 脱敏 │ ├── LlmClient.java # W2主交付物 │ └── W2FailureDrill.java # W28 场景演练附实测数据速查写简历/汇报时可用W2 演练的实测结论可直接作为我做过什么的素材8 种故障场景全部按预期分类400/401 场景确认零重试attempts1429 场景确认重试 3 次后放弃恢复型场景确认第 3 次成功读超时设为 800ms 时端到端耗时约 1.6 秒2 次尝试证明超时配置生效发现并修复 full jitter 导致退避失效的问题实测抖动后可低至 63ms改为下界抖动后最短 1000ms建立测试用例隔离规范每个 drill 前重置网关状态避免计数器串扰导致假红
