张彦峰ZYF头像
跑通一次不等于扛住一天:不用框架,Java 原生调用大模型 API 的请求装配、认证治理、流式解析、四层超时与重试限流封面图

跑通一次不等于扛住一天:不用框架,Java 原生调用大模型 API 的请求装配、认证治理、流式解析、四层超时与重试限流

目录

一、为什么值得先用原生 HTTP 客户端写一遍

(一)被一行 SDK 调用藏起来的六个决定

(二)原生实现要自己覆盖的九个关注点

(三)本文的口径、版本与边界

1、"原生"指的是什么

2、数值与字段名的口径

3、不在讨论范围内的东西

二、先把一次调用的形状看清楚

(一)一次非流式调用的十一个阶段

1、能被自己消掉的三段

2、只能等、但必须量出来的两段

3、自己制造、又自己承担的两段

4、十一段里只有两段是大模型特有的

(二)流式与非流式:同一次请求的两种读法

1、四个维度的差别

2、流式还是一种探活手段

(三)大模型接口与普通 REST 接口的七点不同

三、请求装配:把一次调用写成可复现的数据

(一)客户端的对象模型:哪些是单例,哪些是一次性的

1、进程级单例的四样东西

2、每次调用新建的四样东西

3、一个必须写进评审清单的形态

(二)请求头:六个必须写、三个别乱写

1、必须显式写的三个

2、压缩协商这一条值得单独说

3、幂等标识不是为了"不重复",而是为了"可对账"

4、三个别手工设置的头

(三)请求体的六个部分

1、按"改动理由"分组

2、输出上限必须显式给

3、流式打开时要一并请求用量统计

(四)不引 JSON 库这件事该做到什么程度

1、三档取舍

2、手写转义最容易漏掉的五处

(五)请求指纹:缓存键、幂等键与回放键的共同来源

1、五个部分

2、录制、回放、变异、断言

3、为什么不能拿真实接口做回归测试

四、认证与密钥:最容易写错也最贵的一段

(一)三种认证形态

1、三种形态对客户端的要求

2、短期令牌的三条规则

3、一个高频事故

(二)密钥不该出现的七个地方

1、七个地方

2、共同的根因与一次性的解法

(三)加载顺序与不停机轮换

1、五个来源的优先顺序

2、一次不停机轮换的五个阶段

五、流式输出:事件流不是"把响应体分几次读"

(一)事件流的报文语法

1、四条语法规则

2、三个"看起来像规则、其实不是"的假设

3、为什么空行是最重要的那个字符

(二)响应体处理器的四种选法

1、四种的差别

2、阻塞输入流:最直观,代价要算清楚

3、自定义订阅者的两个坑

(三)增量解析器的状态机

1、解析器必须自己维护的四样状态

2、三条决定正确性的迁移

3、解析循环的骨架

(四)半个汉字:只在生产偶发的那一类缺陷

1、现场

2、为什么本地联调不会暴露

3、按字节缓冲顺带消掉的两类问题

(五)把一串增量拼回一个完整回复

1、三条规则

2、工具调用的分片拼装

3、聚合器的出口应该是什么

(六)状态码 200 之后才失败的四种形态

1、四种形态

2、把判定写成一个显式函数

3、一个真实的失真链条

(七)取消要穿过的四道边界

1、四道边界

2、把取消写成一件必然发生的事

3、为什么在模型调用上取消的价值更大

六、超时:一个数字管不住一次流式调用

(一)四层超时各自覆盖哪一段

1、四层的分工与基线

2、标准库自带的那个超时管的是哪一段

3、第三层为什么必须自己写

(二)流式的三条时钟

1、三条时钟的分工

2、只设总时长会漏掉什么

3、只设帧间空闲会漏掉什么

(三)把超时表达成截止时间

1、传时长与传截止时间的差别

2、七点一秒还要再分一次

3、实现上的两个细节

4、把四层超时挂到截止时间上

(四)一次完整的预算演算

1、从服务等级目标倒推

2、演算暴露出来的一个常见错配

七、重试:模型调用的重试和普通接口不一样

(一)重试判据表

1、四档判据

2、"谨慎"这一档为什么单独存在

3、表要落在代码里的什么位置

(二)已经吐出一半才失败:三种收尾策略

1、三种策略

2、选哪一种由三个已知量决定

3、一个反直觉的结论

(三)退避、抖动与服务端提示的优先级

1、四步串行的决定顺序

2、抖动不是可选的装饰

3、与剩余预算取小这一步最容易被省掉

(四)重试放大与重试预算

1、乘法是怎么来的

2、成本账

3、从重试次数换成重试预算

4、两个必须同时存在的刹车

八、限流:被调方的额度与本地的闸门

(一)三种额度口径

1、三种口径各自什么时候先触发

2、一条换算关系就能判断自己会先撞上哪堵墙

3、只按请求数限流会发生什么

4、正确做法是三个闸门同时存在

(二)按词元计量的令牌桶:预估与回填

1、四个阶段

2、代码形状

3、三个实现细节

4、多实例怎么分

(三)被拒绝的三种来源

1、三种来源必须分开记

2、一条必须写进看板的比值

3、等还是拒

4、被拒绝这件事要能被上层区分

九、异常处理:把失败翻译成可决策的结果

(一)从 Java 异常到业务结论

1、八类异常的翻译

2、解包与分类是两件必须一起做的事

3、中断这一条值得单独强调

(二)不要把失败降级成成功

1、四种降级形态

2、共同特征与共同解法

十、把它们装成一个客户端

(一)一次调用要穿过的九层

1、从外到内的九层

2、三处次序的理由

3、九层可以合并,次序不能改

(二)同步与异步两套入口

1、为什么两套都要有

2、共用策略链的写法

(三)一份可以直接读的骨架

1、包结构

2、配置项的数量

3、代码量的量级

十一、观测与验证:怎么证明这套客户端是对的

(一)一次调用要留下的十四个字段

1、四组字段

2、两个最常被漏掉的字段

3、日志里绝对不该出现的三样东西

(二)四张看板

1、时延分解看板

2、结局分布看板

3、额度与闸门看板

4、成本看板

(三)故障注入矩阵

1、十二种现场

2、为什么应该是单元测试而不是集成测试

3、还应该补两个并发场景

4、如果只能写一个测试

(四)把判断固化成门禁

1、三条可以自动化的门禁

2、两条只能靠评审的

十二、什么时候该换成现成的封装

(一)五条判据

1、五条

2、反过来,继续自写是合理的

(二)一条折中路线

1、把自写的部分收缩到策略层

2、这条路线的实现形态

十三、反模式清单与一页纸

(一)十八个反模式

(二)如果只能记住三条

十四、结语:从"调得通"到"说得清"

参考资料

协议与规范

Java 平台与标准库

超时、重试、退避与过载治理

模型接口的流式、限流与错误语义

可观测性与成本归账

密钥与日志安全

测试与故障注入


干货分享,感谢您的阅读!

把大模型接口接进一个 Java 服务,第一版通常只要二十行:起一个 HTTP 客户端、拼一段 JSON、把回复读出来。

这二十行在联调环境里表现完美——每次都成功、每次都快、每次都返回完整的内容。问题来了,从上线那天开始:流式输出偶发乱码、超时设了却不生效、一次依赖抖动引发二十七倍的重试、月底账单比调用量预期高出三成、看板上的成功率永远是百分之百而客户在投诉"回复说到一半"。这些现象没有一个是模型本身造成的,它们全部来自客户端这一层的工程缺口。

这次我们不依赖任何网络框架与服务商封装,只用 JDK 自带的 HTTP 客户端,把一次大模型调用从请求装配、认证治理、事件流解析、四层超时、重试判据、额度闸门一直写到异常翻译与可观测字段,并给出一份可以直接抄走的装配次序、判据表与故障注入矩阵。

模型调用的难点不在"调得通",而在"失败时说得清"。

一、为什么值得先用原生 HTTP 客户端写一遍

(一)被一行 SDK 调用藏起来的六个决定

用服务商提供的封装起步没有任何问题。绝大多数团队的第一次接入都应该这么做——它能在半小时内验证"这条业务路径到底值不值得做",而这个问题比任何工程细节都重要。

问题出在下一步:验证通过之后,那一行 client.chat(prompt) 被原样保留进了生产代码,而它背后的六个决定连同各自的默认值,一起被当成了不存在。

第一个决定是连接怎么复用。每次调用是新建连接还是走连接池、池子多大、空闲多久回收、走不走多路复用协议——这些决定的是握手开销与端口耗尽风险。第二个决定是密钥从哪里来。写在配置文件、环境变量还是凭据服务,轮换时正在飞行的请求怎么办——这些决定的是一次泄露的爆炸半径。第三个决定是流式怎么分帧。按行读还是按字节读、空行怎么算一帧、一个汉字被切成两半时会发生什么——这些决定的是首字延迟与乱码概率。第四个决定是超时算哪一段。连接、首字节、字节间空闲、整体上限,封装给的那一个数字管的究竟是哪一段。第五个决定是失败要不要重来。哪些状态码可以重试、退避多久、已经吐出一半的回答要不要作废重来。第六个决定是额度按什么计量。按请求数、按词元数还是按并发数,本地闸门和对方的账本是不是同一个口径。

这六个决定有一个共同点:默认值在联调阶段全部够用,在生产的第一次抖动里全部不够用。联调只跑几十次、每次都成功、每次都快,默认值在这种流量下不会暴露任何问题;生产是每天几十万次、其中千分之几会慢十倍、万分之几会在传到一半时断开,六个默认值会同时开始生效,而它们生效的方式互相耦合——超时不对导致重试被触发,重试没有预算导致额度被吃光,额度被吃光导致更多超时。排查的时候,你面对的不是六个独立的问题,而是一个互相供能的循环。

自己用原生客户端写一遍的价值,不在于最终一定要用自写的版本上线,而在于把这六个决定从"默认值"变成"显式选择"。做完这件事之后,即使换回封装,你也知道该去配置它的哪几个参数、以及为什么。

(二)原生实现要自己覆盖的九个关注点

把"自己实现"这件事拆开,会得到九个关注点。它们不是并列的九个待办项,而是分成三层、自下而上互相支撑的结构。

传输层有三个关注点:连接与协议、认证与密钥、报文装配。这一层和"调的是不是大模型"完全无关——同样的代码去调一个订单查询接口也成立。

协议层有三个关注点:流式分帧、失败语义、结果聚合。这一层开始和"这是一个会流式输出的接口"有关,它处理的是事件流的语法、状态码之外的失败判定、以及把几百个增量片段拼回一个完整回复。

策略层有三个关注点:时间预算、重试与放大、额度与闸门。这一层和"线上要扛住"有关,它处理的是四层超时的分工、截止时间的传递、可重试判据、退避与预算、以及三种量纲的限流。

自下而上地写,而不是自上而下地补,理由很具体:传输层写错,协议层看到的是"偶发的连接重置";协议层写错,策略层看到的是"偶发的解析失败";而策略层会把这两种失真忠实地放大成重试风暴。排查时呈现出来的症状,和真实原因隔着两层——这正是模型调用故障最难查的原因,它们的现象几乎总是出现在离根因最远的那一层。

本文后面的章节顺序就是这三层的顺序。

(三)本文的口径、版本与边界

1、"原生"指的是什么

本文中的"原生"指不引入 HTTP 客户端框架、响应式框架、模型服务商提供的封装,以及任何把重试与限流藏在注解背后的治理框架。允许引入的只有一个 JSON 序列化库。

这条线的划法有理由:它正好切在"看见之后能改变设计的东西"与"看见了也没有收益的东西"之间。连接复用、流式分帧、超时分层、重试判据、额度计量,都属于前者——看清楚之后你会改设计;而 JSON 的转义规则属于后者——看清楚之后唯一合理的动作也是换成库实现。如果所在环境确实禁止任何第三方依赖,第三章会给出一个可落地的最小代价方案。

代码基于 Java 11 起随标准库提供的 HTTP 客户端。文中涉及虚拟线程的地方会单独说明,它会改变第五章的一个结论。

2、数值与字段名的口径

文中出现的超时基线、额度数值、词元数、放大倍数、成本比例等取值都是量级示意,用来说明设计意图与相对关系,不是任何具体服务商的真实参数。落地时应以自身的压测结论与所调用服务的文档为准。

请求体与响应体的字段名在不同服务商之间存在差异。文中展示的是结构与语义,不是具体命名——比如"输出上限"这个概念在不同接口里可能叫不同的名字,但它在超时估算与成本控制中的作用是一样的。

3、不在讨论范围内的东西

三类东西本文不展开。第一类是提示词工程与模型选型——它们决定"说什么",本文只讨论"怎么把这句话可靠地送出去、再可靠地收回来"。第二类是向量检索、会话状态、多模态上传这些需要服务端资源生命周期管理的能力——它们会让客户端复杂度上一个台阶,第十二章会给出判据。第三类是上层的编排与工作流——一次调用的工程性质,和把十次调用编排起来的工程性质,是两个话题。

二、先把一次调用的形状看清楚

(一)一次非流式调用的十一个阶段

"这个接口耗时三秒"是一句无法下手的描述。把它切开,一次非流式调用有十一个阶段:解析域名、建立连接、协商加密、发送请求头、发送请求体、服务端排队、模型推理、接收响应头、接收响应体、反序列化、业务映射。

1、能被自己消掉的三段

解析域名、建立连接、协商加密加起来约占一次冷调用的六分之一。这三段的特点是:它们在稳态下应该接近于零,因为连接会被复用、会话会被恢复、域名解析结果会被缓存。

如果它们没有接近零,原因几乎总是同一个——客户端被写成了每次调用新建一个。这个写法在示例代码里非常常见,因为示例代码只调一次,看不出区别。放进一个每秒几十次调用的服务里,它会同时带来三个后果:每次都付一遍握手与协商的开销;连接无法复用,本地端口按调用量线性消耗;客户端内部的选择器线程与执行器随之增长,几分钟内耗尽文件句柄。

2、只能等、但必须量出来的两段

服务端排队与模型推理这两段占一次调用的八成以上,而它们在客户端只表现为一段沉默——请求已经发出,响应还没回来,无法区分对方是在排队还是在生成。

区分办法有两个。一个是看响应头里是否带排队相关的提示,不同服务商的支持程度不一样。另一个更通用:开启流式,看首字到达的时刻。首字来得慢说明卡在排队,首字很快但后续输出很慢说明是生成速率问题。这两种情况的处理方向完全相反——前者要减流量、换额度等级或者换区域,后者要缩短输出、换模型或者接受更长的预算。

这也是第六章把"首字超时"单列一层的原因:它不只是一个保护机制,它还是一个可观测量。

3、自己制造、又自己承担的两段

反序列化与业务映射发生在拿到完整响应之后,通常被算进"接口耗时"。一次长回复的反序列化会产生数百 KB 的临时对象,并发高时体现为回收压力上升;业务映射里的校验、截断、落库、记账同样要花时间。

把这两段单独计时,是区分"对方慢"与"自己慢"最省事的一刀。这一刀不需要任何额外工具,只需要在调用前后各取一次时刻,代价接近于零。

4、十一段里只有两段是大模型特有的

其余九段和调用任何一个远程 HTTP 接口完全一样。这个事实有两个推论。

第一个推论是:不必因为"这是 AI 接口"就放弃已有的 HTTP 工程经验,绝大部分依然适用。连接复用、代理与域名解析的排查手法、结构化日志与调用埋点、熔断与隔离的骨架、以及"先量出来再调参数"这条纪律,全都直接可用。

第二个推论是:真正需要新写的东西,是针对服务端排队与模型推理这两段的——按词元计量的额度、按输出长度伸缩的超时、以及在这两段中途失败时如何收尾。后面十一章基本都在处理这两段带来的连锁反应。

(二)流式与非流式:同一次请求的两种读法

同一个请求,加不加流式开关,总耗时可能完全一样,但用户感知、失败面、超时口径与重试代价全都不同。

1、四个维度的差别

感知差别最直观:非流式下用户盯着一个转圈,全程没有任何进展信息;流式下几百毫秒后就有字出现。同样的总时长,等待感差一个量级。

超时口径的差别是本文第六章的主线。非流式下一个"整体超时"够用;流式下整体超时会误杀长回答——一段三千词元的回复本来就要跑四十秒,而它是正常的。必须改成首字超时加帧间空闲超时,再叠一个总时长上限。

失败面的差别是第五章第六节的主题。非流式下失败几乎都在响应头,状态码就是结论;流式下状态码是 200 之后仍可能失败,错误藏在某一帧的负载里,或者干脆表现为"流没了"。

重试代价的差别是第七章第二节的主题。非流式重试等于重做一次;流式已经吐出八成再断,重试要重新计一次完整输入词元,并且用户已经看过前半段。

2、流式还是一种探活手段

有一条推论容易被忽略:流式不只是交互优化。

非流式调用在服务端卡住时,客户端只能靠一个总超时兜底,而这个总超时必须按最坏情况给,于是通常给得很大——十秒、三十秒、甚至更长。在这个窗口里,客户端无法区分"对方正在认真生成"与"对方已经死了"。

流式把"对方是否还在工作"变成了每隔几十毫秒一次的可观测事件。一旦帧停止到达,几百毫秒内就可以判定异常。这个性质让流式在纯后台场景里也有价值——即使没有人在看输出,边收边判也比一次性等更早发现故障。

代价是解析复杂度,以及第五章要处理的一整套边界情况。这个交换在大多数场景里是划算的。

(三)大模型接口与普通 REST 接口的七点不同

七点不同可以概括成一句话:这是一个时延分布极宽、按用量计费、按用量限流、可分段返回、可在成功之后失败、结果不确定、且重试不免费的 HTTP 接口。

响应时延分布从几百毫秒到几十秒,与输出长度近似成正比——推论是超时不能按固定值给,要按预期输出长度伸缩。计费按输入与输出词元分别计算,两者单价还不一样——推论是每次调用都要记账,重试要算进成本。限流同时按每分钟请求数与每分钟词元数计量,取先触发者——推论是本地闸门必须按词元计量,否则永远对不上。输出可分段到达,每帧是一个增量片段——推论是要写增量解析器,并处理半个汉字的情形。失败可能出现在响应头返回 200 之后——推论是错误判定要贯穿整个响应体。同样入参可能得到不同出参——推论是回放测试要打桩,断言不能写死全文。重试本身安全,但会重复产生费用与时延——推论是需要重试预算,而不只是重试次数。

必须重写、不能照抄的只有四件事:超时的分层、限流的量纲、重试的预算、以及错误判定的贯穿性。除此之外的部分,既有的 HTTP 工程经验都可以直接搬过来。

把这个边界划清楚,可以避免两种常见的过度反应:一种是"AI 接口很特殊,我们要重新设计一套治理体系",另一种是"不就是个 HTTP 接口吗,按老一套来"。两种都会付出代价,而代价的形式不同——前者是过度工程,后者是线上故障。

三、请求装配:把一次调用写成可复现的数据

(一)客户端的对象模型:哪些是单例,哪些是一次性的

标准库的 HTTP 客户端把对象分成两组,分错组是本章最贵的一个错误。

1、进程级单例的四样东西

客户端本身持有连接池、选择器线程与执行器,创建成本高。连接池按"协议加主机加端口"分组复用,空闲连接的保活时长由系统属性控制。执行器承载异步回调与响应体订阅者的运行——不显式指定时用的是公共并行池,这意味着一次长时间的流式订阅会占住公共池里的一个线程,而这个池同时还在跑并行流与其他异步任务,表现为"不相关的任务一起变慢"。加密上下文负责会话复用,让重连只需要一次往返。

这四样都应该在进程启动时创建一次,之后全程复用。

2、每次调用新建的四样东西

请求对象不可变,由构造器装配后不能再改;它自带的超时只覆盖"到响应头为止",这一点在第六章会展开。请求体发布器是请求体的来源,重试时必须能被重新订阅——所以不要用只能读一次的流作为请求体,否则第二次尝试会发出一个空体,而服务端返回的错误信息通常与"请求体为空"毫无关系。响应体处理器决定响应体怎么被消费,流式与非流式的根本差别就在这里选。响应对象在流式下的含义需要特别注意:拿到它只意味着响应头已经到了,响应体此刻一个字节都还没读。

3、一个必须写进评审清单的形态

推荐形态可以压缩成三句话:客户端做成一个单例,注入自建的有界执行器;连接超时写在客户端上,请求超时写在请求上;响应体处理器按"是否流式"在调用处选择。

这三句话对应的是三类最常见的事故:每次调用新建客户端导致的端口耗尽、共用默认执行器导致的无关任务变慢、以及把非流式处理器用在流式调用上导致的"首字延迟等于总耗时"。

(二)请求头:六个必须写、三个别乱写

1、必须显式写的三个

认证头不写直接被拒,没有讨论空间。内容类型头不写会让部分网关按纯文本解析请求体,报出一个和真实原因相去甚远的错误。接受类型头不写时,服务端可能按默认协商返回另一种形态——非流式调用写 JSON,流式调用写事件流类型。

2、压缩协商这一条值得单独说

客户端默认会带上压缩协商,服务端也乐意压缩。非流式下这没有问题——客户端会在把响应体交给你之前解压完毕。

但如果你为了流式而自己按字节读响应体,拿到的就是压缩后的字节流。解析器会在第一帧就失败,且错误信息通常是"非法的 JSON 起始字符"——这个提示指向的方向完全错误,会让排查者去检查请求体、检查服务商状态、甚至怀疑对方返回了 HTML 错误页。

流式调用显式声明不接受压缩,可以直接消掉这一整类排查。代价是带宽,而事件流的内容本来就是小块文本,压缩收益有限。

3、幂等标识不是为了"不重复",而是为了"可对账"

模型接口通常不承诺按幂等键去重,重试仍然会真实产生一次推理与一次计费。所以带上它的目的不是防重复。

目的是对账。带上它之后,你的调用日志、对方的用量明细、以及一次线上申诉,可以围绕同一个标识对齐。取值建议由"业务实体标识加用途加请求体指纹"拼成:同一次逻辑调用的所有重试共享一个值,换了提示词或参数就自然换一个值。

4、三个别手工设置的头

连接管理头写成关闭会让连接复用彻底失效——这个字段在很多"照着教程抄"的代码里出现,因为教程里的例子只调一次。内容长度头与实际体长不一致时,请求会被截断或挂起,它应该由请求体发布器计算。用户标识头不要伪装成浏览器,写成"应用名斜杠版本"即可——伪装的后果是被识别成脚本流量,触发更严格的额度策略。

(三)请求体的六个部分

1、按"改动理由"分组

模型标识与消息数组决定"说什么"。工具声明与采样参数决定"怎么说"。长度约束与流式开关决定"花多少钱"。

这个分组不是为了好看,而是为了让三类改动互不干扰。改一句提示词不该触发一次参数评审,调一次温度也不该改动模板文件,而把输出上限从五百调到两千,影响的是超时公式与成本预算,需要另一批人知晓。

在代码里这意味着:提示词模板与采样参数分属两套配置,长度约束由调用方按用途显式传入而不是写在模板里。

2、输出上限必须显式给

不设输出上限有三个后果,一个比一个隐蔽。

第一个后果是时延不可预测。一次本该两百词元的回复,在模型"话多"的时候可能输出两千词元,耗时翻十倍。第二个后果是成本不可预测,理由相同。第三个后果最隐蔽:输出上限是超时估算的输入。第六章会给出首字超时与总时长上限的估算方式,它们都需要知道"这次最多输出多少"。没有这个数,超时只能按全局最坏情况给,于是所有调用共用一个很大的值,等于放弃了时延控制。

3、流式打开时要一并请求用量统计

流式下用量统计通常需要显式开启,否则最后一帧里没有词元数字段。拿不到真实用量的后果是,第八章的令牌桶只能靠本地估算回填,而估算与账单的偏差会随上下文长度迅速放大——短请求偏差百分之几,八千词元的长上下文偏差可能到百分之二十。

一个简单的检查:如果你的成本看板上的数字和账单对不上超过一成,第一个要查的就是这个开关。

(四)不引 JSON 库这件事该做到什么程度

1、三档取舍

完全手写是指请求体用字符串拼接生成,响应用一个自写的小解析器读。它适用的场景很窄:只发一两种固定请求、且响应只取一两个字段的探针程序。

只手写出、用库读入是一个折中:请求体用模板加转义函数拼,响应交给一个成熟的库。请求体的转义仍然要自己保证正确,但复杂度比写解析器低一个量级。它适用于请求形态稳定、响应结构多变的场景。

引一个库是绝大多数生产场景的答案:序列化与反序列化都交给库,自己只写传输、流式、超时、重试与限流。成本是一个几百 KB 的依赖,收益是省掉一整类低级缺陷。

2、手写转义最容易漏掉的五处

反斜杠与双引号最常想到,也最常只处理了后者。换行、回车与制表符在提示词里粘进一段日志就会命中。小于 0x20 的控制字符必须转成六字符形式,否则整个请求体非法。行分隔符与段分隔符这两个字符在 JSON 规范里合法、在某些解析路径里不合法。代理对——用户粘贴的表情符号是两个码元,按码元截断会产生半个字符。

这五处里任意一处漏掉,表现都是同一种:偶发的"请求体无法解析",而且只在特定用户的特定输入上复现。这类缺陷的排查成本远高于一个依赖的引入成本,这是本文把 JSON 库放在"允许引入"一侧的全部理由。

(五)请求指纹:缓存键、幂等键与回放键的共同来源

1、五个部分

指纹由模型标识、消息数组、采样参数、工具声明、输出约束五段按固定顺序拼接后取摘要得到,取前十六位即可。

有一个容易漏掉的输入:提示词模板的版本号。如果模板文本本身就在消息数组里,那么改模板会自然改变指纹;但如果模板在服务端渲染、或者有一部分内容来自外部配置,就必须把版本号显式算进去,否则改了模板却命中旧缓存。

2、录制、回放、变异、断言

指纹算出来之后,四件事就有了共同的钥匙。

录制是在预发环境把真实调用完整落盘:请求指纹、请求体、响应帧序列、每帧到达的相对时刻、用量与状态码。敏感字段在落盘前替换成占位符。

回放是让本地桩服务按指纹查出录制文件,按原始时刻间隔逐帧吐出。于是"首字慢三秒"这种现象可以在单元测试里被稳定复现。

变异是在回放的基础上注入故障:首字前断开、中途断开、某一帧是错误负载、末帧缺失、帧间空闲超过阈值。第十一章的故障注入矩阵就建立在这一步上。

断言的对象不是回复原文,而是"是否聚合出完整回复""是否按预期分类了错误""是否在预算内结束"。

3、为什么不能拿真实接口做回归测试

五条理由,每一条单独都足够。输出不确定,同一句输入两次调用的回复不一样,断言只能写得极弱。费用真实,一次完整回归跑几百个用例,每次合并请求都要付一次。额度真实,并行跑测试会把生产共用的额度吃掉。故障不可控,你没法要求对方在第七帧之后断开连接。离线不可跑,没有网络或没有额度时整条流水线直接红掉。

桩服务不需要是一个像样的服务——一个几十行的本地 HTTP 处理器足够,关键是它要提供六个开关:正常流式、正常非流式、指定状态码拒绝、指定位置断开、指定帧间隔延迟、返回畸形负载。有了它,后面六到九章里所有的时钟、判据与闸门,都可以被写成断言。

四、认证与密钥:最容易写错也最贵的一段

(一)三种认证形态

1、三种形态对客户端的要求

承载令牌是一个长期有效的密钥,放进请求头一次性带上。客户端要做的只有三件事:取值、拼头、脱敏。风险是一旦泄露,在轮换前全程有效,而且无法按请求限定权限范围。

短期令牌要先用长期凭据换一个带过期时间的令牌,到点续签。客户端要做的多了四件:缓存令牌、提前续签、并发续签去重、失效时单次重取。风险是续签风暴与时钟偏移。

请求签名要按规范化的请求内容算签名,签名随请求一起发送。客户端要做规范化、排序、摘要、时间戳、随机数,一步都不能错。风险是本机时钟偏差直接导致全量失败——而这个失败的表现是"认证错误",排查者的第一反应永远是去检查密钥。

2、短期令牌的三条规则

提前量:不要等过期才续签,按有效期的三分之二触发,给一次失败留出重试窗口。

并发去重:同一时刻只允许一个线程在续签,其余线程等待同一个结果,而不是各自发起一次。

失效兜底:拿到认证失败时允许强制刷新一次,然后重放原请求;第二次仍失败就按不可重试处理,避免和刷新逻辑形成循环。

3、一个高频事故

把"提前续签"写成"每次调用都检查并可能续签",两者的区别在并发下被放大。

前者由一个后台任务驱动,后者由每一个业务线程驱动。当令牌恰好在流量高峰时到期,后者会让数百个线程同时发现"过期了",同时去换新令牌——认证服务先被打垮,然后所有业务调用一起失败。

正确形态是:读取用本地缓存,续签由单一持有者完成。实现上可以是一个定时任务,也可以是"第一个发现需要续签的线程抢到一个标志位,其余线程继续用旧令牌"——后者的好处是不需要额外的调度资源,且在令牌尚未真正过期的窗口里,业务完全不受影响。

(二)密钥不该出现的七个地方

1、七个地方

源码常量——一次提交就永久留在历史里,删掉那一行不等于删掉那次提交。提交进仓库的配置文件——"只是本地用的"最终都会被提交,模板文件里也不要写真实值。构建产物——打进镜像或包里的值,凡是能拿到产物的人都能拿到。日志——请求头整体打印是最常见的一种,异常堆栈里的请求对象同理。异常信息——把响应体原样塞进异常消息,认证失败时会把密钥回显出来。链路追踪——自动采集的请求头属性里,认证头默认往往是被采集的。客户端可见处——浏览器、移动端、前端环境变量,只要能被反编译就等于公开。

2、共同的根因与一次性的解法

七个地方的共同根因是:密钥被当成了一个"字符串配置项",于是它享受了和超时时长、重试次数一样的待遇——可以被打印、被序列化、被上报。

把它包成一个专门的类型,重写它的字符串表示,这一整类问题会一次性消失:

public final class Secret {
    private final char[] value;

    public Secret(char[] v) { this.value = v.clone(); }

    char[] reveal() { return value; }            // 包级可见,只给装配请求头的那一行用

    @Override public String toString() { return "Secret(****)"; }
    // 不提供 getter,不实现 Serializable
    // 日志、链路属性、异常消息拿到的永远是掩码
}

配套四条纪律:只在装配请求头的那一行调用取值方法;把敏感头名写进一份拒绝清单,日志与链路采集统一过这份清单;仓库历史要扫描,提交前钩子挡住新的、定期扫描找出旧的;把"密钥能否被打印"写成一条单元测试,断言日志输出里不含密钥前缀——这比靠评审可靠得多。

(三)加载顺序与不停机轮换

1、五个来源的优先顺序

凭据服务优先级最高,它支持按需拉取与租约续期,泄露后可单点作废。容器注入的文件次之,由编排平台挂载,轮换时文件内容原地变化,需要监听文件变更。环境变量再次,进程启动时固定,轮换必须重启,且会出现在进程信息里。本地配置文件仅用于开发环境,必须在忽略清单里。命令行参数在生产禁止使用——同机任何进程都能看到。

先命中者生效,命中之后不再向下查找,并把"命中来源"记进启动日志。只记来源,不记值。这一条日志的价值在排查时非常高:它能在三十秒内回答"这个实例用的是哪一把钥匙"。

2、一次不停机轮换的五个阶段

签发新钥匙(新旧同时有效)、推送到凭据源、进程热加载、确认全量切换、作废旧钥匙。双钥匙并存窗口至少要覆盖一次完整发布周期加上最长请求耗时。

把第四步省掉,就是最常见的那次事故。"推送完成"不等于"生效完成":有实例在重启中、有实例的监听失败了、有请求已经带着旧钥匙在路上。提前作废旧钥匙的后果是全量认证失败,而此时新钥匙已经在配置里,排查者的第一反应往往是"配置没问题啊",于是把时间花在网络与服务商状态上。

让每个实例上报当前钥匙的指纹前八位,这一步只需要半天就能建好,它把第四步从"靠感觉"变成"可判定"。

五、流式输出:事件流不是"把响应体分几次读"

(一)事件流的报文语法

1、四条语法规则

行以"字段名加冒号加空格"开头,字段只有四个:数据、事件类型、标识、重连建议。冒号后的第一个空格要去掉,第二个空格是内容的一部分。

空行才是一帧的结束。连续多行数据字段属于同一帧,按换行拼接;没有空行就没有帧,缓冲区必须继续等。

以冒号开头的行是注释,常被用作心跳,必须被识别并丢弃。把它当成数据去解析 JSON 会直接抛异常——症状是每隔十几秒抛一次解析异常,而内容看起来一切正常。

结束标记是一个约定,不是语法。事件流本身没有"结束"的概念,结束标记由具体服务定义,所以解析器要可配置。

2、三个"看起来像规则、其实不是"的假设

假设一:一次网络读取正好对应一帧。不成立——一次读可能拿到半帧,也可能拿到三帧半。这是第四节那类缺陷的根源。

假设二:每帧都是合法 JSON。不成立——注释行、结束标记、以及服务端在出错时插入的错误帧都不是。

假设三:帧的顺序等于内容的顺序。这一条对文本成立,但工具调用的参数是按索引分片的,拼装时要按索引归组而不是按到达顺序追加。第五节会展开。

3、为什么空行是最重要的那个字符

空行是唯一的帧边界。如果服务端在生成过程中被杀掉,最后一帧很可能只发出了半行,而客户端此时读到的是一段合法的前缀。

只按"读到一行就解析"写的解析器,会把这半行当成一帧去解析并抛异常,于是一次"连接被截断"被翻译成了"协议不兼容"——而这两者的重试策略正好相反。

按"见到空行才交付"写的解析器,会正确地停在缓冲区里,然后由帧间空闲超时收场,并且缓冲区非空这个事实本身就是"被截断"的证据。

(二)响应体处理器的四种选法

1、四种的差别

整体转字符串的处理器在响应体全部落地后才返回,不能做流式,长回复会一次性进堆。它是非流式调用的默认选择。

按行推送的处理器在响应头到达即返回,之后逐行回调。它可以做流式,但只到"行"这一级——自己拿不到字节边界,无法自己判定帧间空闲,也无法发现"缓冲区里剩着半行"。

转输入流的处理器在响应头到达即返回,控制权最完整。读取是阻塞的,必须自己管线程与关闭。

自定义订阅者在响应头到达即返回,之后按字节块回调,天然带背压。它要正确实现请求与取消,写错会静默挂起。

2、阻塞输入流:最直观,代价要算清楚

它的好处是代码读起来就是一个循环,异常与关闭都走熟悉的语法结构。

代价是每一次进行中的流式调用都要占住一个线程,而这个线程绝大部分时间在等下一帧——它是一个纯等待的线程。并发一百路流式调用就需要一百个这样的线程。

这里有一个重要的版本差异:在虚拟线程可用的运行时上,这个代价几乎消失,阻塞写法重新成为首选——一个等待中的虚拟线程只占极少的内存,不占用操作系统线程。在只能用平台线程的环境里,超过几十路并发就应该换成订阅者写法。

3、自定义订阅者的两个坑

第一个坑是背压。订阅者必须显式地请求下一批数据,忘记请求表现为"收到几帧之后就再也不动了",而且没有任何异常。

第二个坑是异常传播。在回调里抛出的异常不会冒泡到调用方,它会让整个响应体订阅以"异常完成"收场;如果没有把它接到结果的完成阶段上,调用方会一直等下去。

两个坑的共同症状都是"卡住",而不是"报错"。这也是第六章第二节把帧间空闲超时列为必需的原因之一——它同时兜住了网络异常与自己代码里的这两个坑。

(三)增量解析器的状态机

1、解析器必须自己维护的四样状态

字节缓冲区,装着上一次没读完的半行。当前帧的字段累积,多行数据要拼起来。是否已见到结束标记,用于区分"正常结束"与"连接被截断"。最后一次收到字节的时刻,帧间空闲超时靠它判定。

这四样状态决定了解析器必须是一个对象,而不能是一个静态方法。这是一个容易被忽略的设计约束——很多实现把解析写成工具方法,然后发现没地方放"是否见过结束标记"。

2、三条决定正确性的迁移

第一条:读到的行是注释时,必须被丢弃并回到行缓冲,不能进入帧累积,更不能去解析 JSON。

第二条:连接结束时若缓冲区非空,说明被截断,必须走异常终止而不是正常结束。写错的症状是回复莫名少了最后一句,而调用方认为本次调用成功。

第三条:读到流的末尾却没见过结束标记,同样是异常终止。写错的症状是服务端限流中断了生成,而客户端把半截回复当成完整结果落库。

后两条的共同点是:它们区分的不是"成功"与"报错",而是"成功"与"看起来像成功"。这正是本文标题那句话的具体形态。

3、解析循环的骨架

while ((n = in.read(buf)) > 0) {
    lastByteAt = System.nanoTime();                  // 帧间空闲时钟在这里续期
    acc.write(buf, 0, n);                            // 先进字节缓冲,不要急着转字符串
    int idx;
    while ((idx = indexOfLineBreak(acc)) >= 0) {     // 按字节找换行,避免半个汉字
        String line = takeLine(acc, idx);            // 只有完整一行才转成字符串
        if (line.isEmpty()) {                        // 空行 = 帧边界
            emit(frame);
            frame.reset();
        } else if (line.charAt(0) == ':') {
            // 注释行(心跳),丢弃;注意时钟已经在上面续期过了
        } else {
            frame.append(parseField(line));
        }
    }
}
if (acc.size() > 0 || !sawDone) {
    throw new TruncatedStreamException(aggregated, acc.size(), sawDone);
}

三个细节值得注意。时钟续期放在读到字节之后、解析之前——心跳帧虽然不产生内容,但它证明连接活着,必须让它续期。交付的单位是帧而不是行。最后那个截断异常带上了已聚合的内容——第七章第二节的三种收尾策略全都需要它。

(四)半个汉字:只在生产偶发的那一类缺陷

1、现场

一个汉字在常见编码下占三个字节。如果每读到一个字节块就转成字符串再拼接,而网络分包边界恰好落在这三个字节中间,会发生两次不可逆的损失:第一块结尾的字节单独转换时得到一个替换字符,原字节永久丢失;第二块开头的剩余字节同样无法还原,再得到一个替换字符。

最终结果是本该三个字的地方变成一个字加两个问号,并且只在这一次分包边界下发生。

2、为什么本地联调不会暴露

本地或同机房调用时,一帧通常在一次读取里就到齐,边界天然落在帧之间。跨地域、经过代理、或者在网络抖动时,同一段响应会被切成完全不同的块,边界才会落进字符内部。

所以这类缺陷的分布特征很鲜明:某一个地域、某一段时间、某几条回复里出现问号,重放同样的请求又复现不了。它的排查成本极高,而修复成本极低——只要一开始就按字节缓冲。

3、按字节缓冲顺带消掉的两类问题

第一,按字节找换行还能正确处理"回车加换行"与"单独换行"两种行结束形态,而按字符串分割往往只处理了后者。

第二,字节缓冲区天然给出了"还剩多少没解析完"这个量,连接结束时它非空就说明被截断——这正是上一节那条关键迁移的判据来源。

换句话说,"按字节缓冲"这一个决定同时解决了三个看起来不相关的问题。这类决定在工程里不多见,遇到了就应该毫不犹豫地采纳。

(五)把一串增量拼回一个完整回复

1、三条规则

文本内容按顺序追加。注意片段可能是空字符串,也可能只有一个空格,不要用"非空"作为过滤条件——那会把回复里的空格吃掉。

工具调用按索引归组。一次回复可能并行发起多个工具调用,每帧带的是"第几个调用的第几段参数",必须按索引归进对应的构造器再追加,而不是全部拼成一个字符串。

用量统计只取末帧。输入与输出词元数通常只在最后一帧出现,中间帧里没有这个字段,把它写成"每帧累加"会得到零。

2、工具调用的分片拼装

Map<Integer, ToolCallBuilder> calls = new TreeMap<>();
for (Frame f : frames) {
    for (ToolCallDelta d : f.toolCalls()) {
        ToolCallBuilder b = calls.computeIfAbsent(
                d.index(), i -> new ToolCallBuilder());
        if (d.id()   != null) b.id(d.id());       // 通常只在首片出现
        if (d.name() != null) b.name(d.name());   // 通常只在首片出现
        if (d.args() != null) b.appendArgs(d.args());
    }
}
// 参数是一段被切碎的 JSON 文本,只有全部片段到齐后才可解析

四个容易写错的地方。用列表下标代替索引字段——某些实现的索引不是从零连续的,用下标会错位。边收边解析参数——参数是被切碎的 JSON 文本,中途解析必然失败。把工具调用的名字当成每帧都有——它通常只在第一片出现,用后一帧覆盖会把名字清空。忽略结束原因——它区分"正常说完""达到长度上限""要调用工具""被内容策略拦截",这四种的后续处理完全不同。

3、聚合器的出口应该是什么

不是一个字符串,而是一次调用的全部事实:完整文本、工具调用列表、结束原因、输入词元数、输出词元数、首字时刻、末帧时刻、帧数。

八个字段里有五个和"内容"无关,它们是第十一章可观测性的来源。把它们留在聚合器里、而不是散落在各处,是让观测成本接近于零的关键——聚合器本来就要遍历每一帧,顺手记录时刻与计数不增加任何额外开销。

(六)状态码 200 之后才失败的四种形态

1、四种形态

错误帧:响应头 200,前几帧正常,某一帧的负载是一个错误对象。成因是服务端在生成中途触发了额度、内容策略或内部异常。判定方式是每帧解析后检查错误字段,命中即终止并按对应类别抛出。

无声截断:流正常结束,但没有结束标记,缓冲区里可能还剩半行。成因是连接被中间设备或服务端切断。判定方式是流结束时检查两个条件。

长度截断:一切正常结束,结束原因是"达到长度上限"。这不是错误,但结果不完整,上层要决定是续写还是提示。

空回复:帧都收到了,拼出来是空字符串。成因是被内容策略拦截或者模型选择不回答。不能当成成功写进业务字段,否则会出现"回复为空"的工单。

2、把判定写成一个显式函数

六个条件的合取:状态码是 2xx、未收到任何错误帧、见到了结束标记、缓冲区已清空、结束原因是正常完成、聚合文本非空。

第一个条件是必要不充分的,而很多实现只检查了它。

这个函数不应该返回布尔值,而应该返回一个带类别的结果对象:完整成功、长度截断、内容拦截、连接截断、服务端错误、额度拒绝、客户端取消。七个类别分别对应不同的后续动作——重试、续写、告警、降级、静默——而布尔值会把这七种压成一种,让上层只能做一件事:抛异常。

类别信息同时也是看板的分组维度,它决定了故障发生时能不能一眼看出是哪一类。

3、一个真实的失真链条

判定只看状态码,于是截断的回复被记为成功;成功率看板始终是百分之百;客户投诉"回复说到一半";排查者先怀疑提示词,再怀疑模型质量;几天后才有人去看原始帧,发现流在第七十帧断了。

整条链上唯一的缺陷只有第一步,但它把所有下游信号都变成了噪声。这就是"错误降级"在流式场景下的具体形态——失败被降级成了一次成功,而一次被记成成功的失败,比一次明确的失败危险得多。

(七)取消要穿过的四道边界

1、四道边界

业务层:调用方放弃等待,或者上游请求已经断开。它只是自己不再等,对下层没有任何影响。

结果凭证:取消代表结果的那个凭证,让等待者立刻得到取消结果。若不向下传播,网络读取仍在继续。

响应体订阅:取消订阅或关闭输入流,让底层停止读取并释放缓冲。漏掉这道,连接会一直挂在池里,并持续消耗额度。

连接:对方仍在生成时,只有关闭连接才能让它停下来。漏掉这道,服务端会把整段生成完,词元照常计费。

2、把取消写成一件必然发生的事

CompletableFuture<Result> f = client.sendAsync(req, handler);

ScheduledFuture<?> guard = timer.schedule(
        () -> f.completeExceptionally(new DeadlineExceeded()),
        budget.remainingMillis(), TimeUnit.MILLISECONDS);

f.whenComplete((r, e) -> {
    guard.cancel(false);        // 正常完成时撤掉守卫,避免调度队列膨胀
    handler.closeQuietly();     // 关闭输入流 / 取消订阅,两条路径都要走
});

三个容易漏掉的现场。超时守卫任务本身没有被取消——每一次正常完成的调用都会在调度器里留一个到点才会触发的任务,高峰期调度队列迅速膨胀。异常路径上没有关流——只在正常完成分支里写了关闭,而超时与异常恰恰是最需要关闭的两条路径。把关闭写在调用线程上——关闭一个正在被底层读取的流可能短暂阻塞,放在业务线程上会让"超时返回"本身也变慢。

3、为什么在模型调用上取消的价值更大

普通接口取消晚一点,浪费的是对方的一点点计算。模型调用取消晚一点,浪费的是真金白银——一次被放弃的长回复,如果没有关闭连接,服务端会把剩下的两千个词元生成完,并按正常价格记账。

在高并发场景里,"超时后没关流"这一个缺陷,足以让账单和调用量对不上三成以上。而这个偏差在看板上的表现是"成本异常",很少有人会把它和取消逻辑联系起来。

六、超时:一个数字管不住一次流式调用

(一)四层超时各自覆盖哪一段

1、四层的分工与基线

连接超时覆盖"从发起连接到连接可用",基线两秒。它能抓到网络不可达、对端拒绝、握手挂起。要注意的是:复用连接时这一层根本不生效,所以它管不住任何已建连的请求——这是很多人设了它却发现没用的原因。

首字超时覆盖"从发出请求到收到第一个字节",基线十秒。它能抓到服务端排队过长、额度耗尽后的静默等待。这一层要按"模型加上下文长度"分档,而不是全局一个值。

帧间空闲超时覆盖"相邻两个字节块之间的最大间隔",基线十五秒。它能抓到生成中途卡住、连接半死、中间设备静默丢包。它是流式独有的,也是唯一能发现"连接还在但没数据"的机制。

总时长上限覆盖"从发起调用到全部收完",基线九十秒。它是兜底而不是主力:给得太小会误杀长回答,太大则失去意义。

2、标准库自带的那个超时管的是哪一段

请求对象上的超时覆盖的是"从发出请求到收到响应头",也就是第二层。

它不覆盖响应体的接收过程。这一点在非流式下无关紧要,因为响应体紧接着响应头一起到;但在流式下,响应头几乎立刻返回,之后几十秒的接收过程完全不在它的管辖范围内。

换句话说:给流式调用设一个大的请求超时,感觉上很安全,实际上什么都没保护。这是本章最需要记住的一句话,它解释了相当一部分"明明设了超时却挂了几分钟"的现场。

3、第三层为什么必须自己写

标准库没有提供"相邻字节块之间的最大间隔"这种语义,因为它对普通 HTTP 没有意义——普通 HTTP 的响应体是一次性写出的。

实现方式不复杂:解析循环每收到一个字节块就更新一次时刻,一个周期性任务检查"当前时刻减去最后收到时刻"是否超过阈值,超过就取消凭证并关闭流。周期取阈值的四分之一即可。

一个实现要点:用一个共享的调度器,不要为每次调用开一个定时器。几百路并发流式调用各开一个定时器,会让调度开销本身成为问题;而共享调度器上的检查任务极轻——它只做一次减法和一次比较。

(二)流式的三条时钟

1、三条时钟的分工

首字超时回答"对方开始干活了吗"。帧间空闲超时回答"对方还在干活吗"。总时长上限回答"这件事还值得等吗"。

三个问题的答案对应三种完全不同的处理:第一个超时通常意味着排队或额度问题,可以重试;第二个超时意味着连接或生成异常,重试要谨慎;第三个超时意味着预算用尽,不应该重试。

把三者合成一个"超时"异常,等于丢掉了这个分类信息,而第七章的判据表正好需要它。

2、只设总时长会漏掉什么

假设总时长给了九十秒。对方在第三秒吐出第一个字,然后连接半死:字节再也不来,但连接没有关闭。

此时首字超时已经过去,帧间空闲超时如果不存在,这次调用会安静地占着一个线程、一条连接、以及一份并发额度,直到第九十秒。

在高并发下,这类"僵尸流"会先耗光并发额度。而它的表现在看板上是"并发数居高不下"与"限流拒绝增多",两者都不指向真实原因。

3、只设帧间空闲会漏掉什么

假设帧间空闲给了十五秒。对方以每十四秒一帧的速度稳定输出,每一帧都在阈值之内,空闲时钟永远不触发。一段两百帧的回复因此可以合法地跑上四十分钟。

这正是总时长上限存在的理由:它不负责发现故障,只负责给"合法但过分"的情形划一条线。

两条都设上之后,还剩一个问题:总时长上限该给多大。答案在下一节——它不该是一个配置常量,而该是从上游预算里分出来的一段。

(三)把超时表达成截止时间

1、传时长与传截止时间的差别

传时长时,每一跳都从零开始计时。一条四跳的链路上,每一跳都声明"我的超时是八秒",最坏情况下最外层的调用方要等三十二秒——而它自己声明的超时是八秒。

传截止时间时,每一跳减去自己的开销后继续往下传。网关剩余八秒,扣掉自己的零点二秒后把七点八秒传给工单核心;工单核心扣掉零点三秒后把七点五秒传给智能编排;智能编排扣掉零点四秒后把七点一秒传给模型网关。总耗时有上界。

2、七点一秒还要再分一次

模型网关拿到的不是"可以花七点一秒",而是"这次调用的截止时刻"。它要在这个预算内完成:选路与鉴权约零点一秒,首字超时给二点五秒,剩下约四点五秒留给生成。

如果按经验,这个模型在当前上下文长度下首字就要三秒,那么应该直接降级,而不是发起——发起也是超时,但会白白占用一次额度、一条连接,并且在对方侧真实产生一次推理。

这个动作叫提前放弃。它省下的不是自己的时间,而是下游的容量:在依赖变慢时,上游的请求会大量堆积,如果每个都照发不误,下游会在它们全部超时之后才开始恢复;而提前放弃能让下游的队列立刻变短。在模型调用上它还额外有一层价值——没发出去的请求不产生任何费用。

3、实现上的两个细节

第一,截止时间在进程内要用单调时钟计算,不要用挂钟时间——后者会被校时调整,一次时间同步可能让所有在途请求同时"超时"或者同时"永不超时"。

第二,跨进程传递时只能传挂钟时刻或剩余毫秒数,两端时钟不一致会引入偏差。更稳的做法是传剩余毫秒数,由接收方立刻换算成自己的单调时钟截止点,并在换算时扣掉一个估计的单程网络时延。

4、把四层超时挂到截止时间上

四层超时不是四个独立的配置项,它们都应该和剩余预算取小:

Deadline dl = ctx.deadline();                 // 来自上游,已换算成本机单调时钟
long remain = dl.remainingMillis();
if (remain < MIN_WORTH_TRYING) {
    throw new BudgetExhausted(remain);        // 提前放弃
}

long firstByte = Math.min(cfg.firstByteMs(estimatedInputTokens), remain);
long idle      = Math.min(cfg.idleMs(), remain);
long total     = remain;                      // 总时长上限直接就是剩余预算

这段代码解释了一个常见的困惑:"总时长上限到底该配多少"。在有截止时间的体系里,它不需要配——它就是剩余预算。配置项里只需要留首字超时与帧间空闲超时这两个,而首字超时还应该是输入长度的函数。

(四)一次完整的预算演算

1、从服务等级目标倒推

假设工单摘要这个功能对外承诺"九十五分位在八秒内返回",链路是四跳,模型调用是最后一跳。

第一步,扣掉链路自身开销。四跳各自的处理与序列化开销约零点九秒,剩七点一秒。

第二步,扣掉重试预留。如果允许一次重试,就要把预算切成两段——但不是均分。合理的切法是:第一次尝试给五秒,若失败且剩余时间大于两秒则重试一次,第二次尝试用完剩下的。均分成两个三点五秒的后果是第一次尝试的成功率被人为压低,反而增加了重试率。

第三步,在五秒里分配首字与生成。按历史数据,这个场景的首字时延九十五分位是一点八秒,于是首字超时给二点五秒(留一点余量),剩下二点五秒给生成。

第四步,反推输出上限。如果这个模型的稳态生成速率约每秒四十词元,二点五秒对应一百词元——那么输出上限就不该设到五百,因为设了也用不完,反而会让长回复在超时边缘徘徊。把输出上限设成一百二十,并在提示词里明确要求简短,两者要一致。

2、演算暴露出来的一个常见错配

上面第四步经常暴露一个错配:业务方希望摘要详细,于是输出上限设得很大;同时又承诺很短的响应时间。两个要求在生成速率这个物理约束下不可能同时满足。

这个矛盾在没有做预算演算时不会显现,它会以"偶发超时"的形式出现在线上,然后被当成稳定性问题去查。做一次演算,它就变成了一个明确的产品取舍:要么放宽时限,要么缩短输出,要么换一个更快的模型并接受质量差异。

把这个演算写进设计文档,比任何超时参数本身都有价值。

七、重试:模型调用的重试和普通接口不一样

(一)重试判据表

1、四档判据

可以重试的有五类:连接被拒或域名解析失败、连接建立后立即重置、首字超时、服务端内部错误、额度拒绝。前四类用指数退避加抖动,额度拒绝优先采用响应给的等待时长。

需要谨慎的有两类:帧间空闲超时、流被截断。它们在技术上完全安全,但有一个别处没有的特征——本次调用已经产生了真实成本,而重试要把这份成本再付一遍。

只允许一次的有一类:认证失败。强制刷新令牌后重放一次,失败即停,避免和刷新逻辑形成循环。

不要重试的有四类:总时长上限触发、请求非法、内容被策略拦截、客户端主动取消。它们的共同点是重试一定还是失败,或者重试本身就违背了调用方的意图。

2、"谨慎"这一档为什么单独存在

对一个上下文八千词元、输出两百词元的调用来说,重试的代价接近于一次全新调用,而不是"补上剩下的一点点"——因为输入词元会被完整地重新计算一次。

所以这一档的默认策略是:只重试一次,并且只在已产出内容不足一定比例时重试。这个比例的判断依据在下一节。

3、表要落在代码里的什么位置

落在协议层与策略层之间的那一次转换上:协议层负责把各种失败归成表里的一行,策略层只读这一行的三个字段——能否重试、怎么退避、附加动作。

这样做有两个收益。新增一种失败形态时只需要加一行,而不需要去改重试逻辑本身。更重要的是,这张表可以被直接写成参数化测试:十二行就是十二个用例,每个用例断言策略层的决策,而不需要真的发起任何网络调用。

(二)已经吐出一半才失败:三种收尾策略

1、三种策略

整段作废重来:丢弃已收到的片段,用原请求重新发起一次。代价是输入词元再付一遍,用户看到的文字会整段闪回重写。适用于已产出很少、或者结果要整段落库不能半截的场景。

保留半截并标注:把已聚合的文本作为结果返回,并带上"未完成"的标记。代价是上层必须真的处理这个标记。适用于结果给人看、且人能判断的场景。

续写补全:把已产出的内容作为上文,请求模型从断点继续。代价是需要额外一轮调用,衔接处可能重复或断裂,且需要提示词显式支持续写。适用于长文本生成且中断位置靠后的场景。

2、选哪一种由三个已知量决定

已产出比例:已收到的输出词元数除以输出上限。低于一成倾向重来,高于七成倾向续写。

剩余预算:截止时间减去当前时刻。不够再跑一次完整调用时,只能在保留与放弃之间选。

结果去向:给人看还是进业务字段。进业务字段的一律不能保留半截,给人看的可以保留并标注。

三个量在失败发生的那一刻都是可算的,所以这个选择可以完全自动化,不需要人工配置每个场景。

3、一个反直觉的结论

"保留半截"看起来最省钱,实际上常常是最贵的一种。

因为残缺的回复会被下游当成完整结果继续处理:它可能被写进工单的处置说明、被当成知识库的候选条目、或者被直接发给客户。只有当上层确实会处理"未完成"这个标记时,这一档才成立;否则它就是把一次可见的失败换成了一次不可见的错误。

落地建议是把三种策略做成一个按用途配置的枚举,而不是一个全局开关:坐席草稿用"保留并标注",自动分类用"整段作废重来",长文档摘要用"续写补全"。同一个客户端支持三种并不复杂——关键是聚合器要把"已产出内容"与"中断位置"一并交出来,而不是在失败时直接丢掉。

(三)退避、抖动与服务端提示的优先级

1、四步串行的决定顺序

第一步,响应里有等待提示就直接采用。第二步,没有就按该类别的退避策略算。第三步,加一次抖动。第四步,与剩余预算取小。

四步是串行的:前一步有结论也要继续走完后两步。抖动与预算裁剪对所有来源都适用,包括服务端明确给出的等待时长——因为同一批被拒绝的请求会拿到同一个等待时长,不加抖动就会在那一刻同时重发。

2、抖动不是可选的装饰

设想一次依赖抖动让三十台实例上的请求同时失败。不加抖动时,它们会在完全相同的时刻发起第一次重试,然后在完全相同的时刻发起第二次——退避确实拉长了间隔,但也把三十次请求精确地对齐成了三个尖峰。对一个刚刚恢复的依赖来说,这三个尖峰往往足以把它再打垮一次。

加抖动的正确做法是:在"零到本次退避时长"之间取一个随机值,而不是在退避时长上下浮动一个小比例。前者能把尖峰摊平成一段均匀分布,后者只能把尖峰变胖一点。

这一条在模型调用上尤其重要,因为额度是按分钟窗口计量的:尖峰会让整个窗口的额度在一瞬间被吃光,于是本来只是"慢"的依赖,变成了"被限流"的依赖。

3、与剩余预算取小这一步最容易被省掉

省掉之后的现象是:一次调用在超时返回给上游之后,底层还在按退避表安静地等着发第三次重试。它占着线程、占着连接,并且很可能真的发出去并产生费用——而那次结果已经没有任何人会读。

正确写法是:每次准备重试前,先判断"当前时刻加退避时长加一次调用的预期耗时"是否超过截止时刻,超过就直接放弃。三个加数缺一不可——只判断退避时长会让最后一次重试注定超时。

(四)重试放大与重试预算

1、乘法是怎么来的

工单核心对编排失败重试三次,智能编排对模型失败重试三次,模型客户端对传输失败重试三次。一次业务请求在最坏情况下变成二十七次模型调用。

如果这次故障的原因恰好是额度不足,那么这二十七倍会让额度在下一个窗口里同样耗尽——故障自我维持,即使根因已经消失。

2、成本账

一次"谨慎重试"的成本构成:首次调用付了输入八千词元加已产出的一千四百输出词元;重试再付一次输入八千词元加两千输出词元。同一个结果,付了两份输入。

这个比例随上下文长度变化:上下文越长,重试越亏。对短请求(比如意图分类,输入一百词元)重试几乎免费;对长上下文请求(比如全文摘要)重试的边际成本接近百分之百。

推论是:重试策略应该按用途分档,而不是全局统一。短请求可以重试三次,长上下文请求最多一次。

3、从重试次数换成重试预算

按次数配置的问题在于:它对"大家一起失败"这种情况完全没有约束力。三次就是三次,无论此刻有多少请求正在重试。

预算的写法是:维护一个滑动窗口,统计窗口内的首发请求数与重试请求数,当"重试数除以首发数"超过设定比例(常见取百分之十)时,拒绝发起新的重试,直接返回失败。

它的效果是:零星失败照常重试,全面故障时重试自动关停。

在模型调用上,这个比例还应该同时受费用约束——把"本分钟重试消耗的词元数"也纳入窗口统计,超过预算同样停止重试。这条约束在长上下文场景下比请求数约束更早生效,也更贴近真实代价。

4、两个必须同时存在的刹车

第一个刹车是重试预算,它管的是"本层最多额外发出多少请求"。第二个刹车是只在最内层重试,它管的是"这条链上有几个地方在重试"。

只有第一个时,三层各自都遵守百分之十的预算,叠起来仍然是百分之三十三。只有第二个时,单层的重试在全面故障下仍会持续放大。

两个一起用,才能把二十七倍压回到一点一倍左右——这个数字应该出现在故障演练的验收项里,而不只是设计文档里。

八、限流:被调方的额度与本地的闸门

(一)三种额度口径

1、三种口径各自什么时候先触发

每分钟请求数在"请求短、并发高"时先触发,典型场景是意图分类、情绪判断、字段抽取这类小请求。本地对应一个按请求计数的令牌桶。

每分钟词元数在"上下文长、回复长"时先触发,典型场景是工单摘要、知识问答、长文档结构化。本地对应一个按词元计量的令牌桶。

并发请求数在"单次耗时长"时先触发,典型场景是流式长回复与推理型模型。本地对应一个信号量。

2、一条换算关系就能判断自己会先撞上哪堵墙

每分钟词元数等于每分钟请求数乘以(平均输入词元加平均输出词元);并发数等于每秒请求数乘以平均单次耗时。

代入一组数字:每分钟一百二十次调用、平均输入两千词元、输出三百词元、单次耗时六秒。得到每分钟二十七万六千词元,并发十二。

对照一组常见额度:请求数额度每分钟五百,用了百分之二十四;词元数额度每分钟三十万,用了百分之九十二;并发额度五十,用了百分之二十四。

结论一目了然:这个流量形态会先撞上词元墙,而请求数与并发都还有大量余量。

3、只按请求数限流会发生什么

本地闸门设在每分钟四百次,看板上"限流拒绝数"长期为零,于是所有人都相信限流没有生效、也不需要关注。

而真实情况是:请求在第二十秒就撞上了词元墙,服务端开始返回额度拒绝,客户端按可重试处理并开始退避重试,重试又消耗额度——一个自我维持的循环。

看板上呈现的是"对方不稳定",实际是自己的闸门量纲错了。这是本章最需要警惕的一种失真:闸门存在、闸门没报警、闸门完全没起作用,三者可以同时成立。

4、正确做法是三个闸门同时存在

请求数闸门与词元数闸门各是一个令牌桶,并发闸门是一个信号量。一次调用要同时通过三者才能发出,任一不通过就进入等待或被拒绝。

三者的容量按"服务商给的额度乘以一个安全系数"设定,安全系数取零点八到零点九,留出估算误差与多实例分配误差的空间。

并发闸门还有一个额外作用:它是本地资源的保护伞,防止在途的流式调用把线程与连接占满。即使服务商不限制并发,这个闸门也应该存在。

(二)按词元计量的令牌桶:预估与回填

1、四个阶段

预估:输入词元可以精确算——把请求体里的消息按分词器算一遍;输出词元只能估,取输出上限或者该场景的历史分位数。

扣减:用"输入加预估输出"向桶申请,申请不到就等待或拒绝。此时记下本次申请的数量,它是后面回填的基准。

调用:正常发起。流式时在末帧拿到真实用量,非流式时在响应体里拿,拿不到就退回本地估算值。

回填:真实用量小于预估就把差额还回桶里,大于预估就从桶里再扣一次。回填必须在成功与失败两条路径上都执行,否则桶会慢慢漏干。

2、代码形状

long estimated = countInputTokens(req) + req.maxTokens();
Lease lease = tokenBucket.acquire(estimated, deadline);
try {
    Result r = call(req);
    lease.settle(r.usage().total());              // 真实用量回填
    return r;
} catch (Exception e) {
    lease.settle(partialUsageOr(estimated, e));   // 失败路径也要结算
    throw e;
} finally {
    lease.release();                              // 归还并发许可
}

3、三个实现细节

第一,预估偏保守:用输出上限而不是历史均值。宁可少发几次也不要反复被服务端拒绝——被拒绝的代价包含一次往返与一次重试决策,而少发几次的代价只是一点点吞吐。

第二,回填要在失败路径上执行。中途失败时已经产生的输出词元同样计费,只在成功路径回填会让桶的账面与真实账单越差越远。这个偏差是单向的,会随时间累积。

第三,桶的补充速率按分钟窗口折算成每毫秒,不要真的每分钟整点补一次。整点补充会制造出周期性的尖峰——所有等待中的请求在整点那一刻同时被放行,然后在下一个整点之前全部被拒绝。

4、多实例怎么分

静态均分:每个实例分到总额度除以实例数。零成本,但扩缩容时要重算,且闲置实例的份额被浪费。

集中计数:用一个共享计数服务做统一扣减。准确,但每次调用多一次往返,且该服务成为新的单点。

本地加反馈:本地按均分起步,根据服务端返回的额度剩余提示动态调整。复杂度中等,是多数场景的落点。

第三种的实现要点是"只收紧、缓放松":发现剩余额度偏低时立刻调低本地速率,发现充裕时缓慢调高。非对称的调整曲线可以避免多个实例同时放松导致的振荡。

(三)被拒绝的三种来源

1、三种来源必须分开记

本地闸门拒绝发生在请求发出之前,含义是"按自己的账本,这次发出去多半会被拒"。代价是零——没有网络往返,没有费用。它应该在看板上单独一条曲线,而且它不算故障。

服务端额度拒绝发生在请求到达服务端之后,含义是"本地账本与对方账本对不上"。代价是一次往返,通常不计费。它持续大于零,说明本地闸门标定错了。

网关或中间层拒绝发生在自建网关、服务网格或代理上,与模型服务无关。它是最容易被误记成服务端拒绝的一类,而两者的退避策略不同。

2、一条必须写进看板的比值

服务端额度拒绝数除以本地闸门拒绝数。

这个比值接近零,说明本地闸门标定得当,绝大多数超额在本地就被挡住了。这个比值持续大于一,说明本地闸门形同虚设,真正在限流的是对方。

它比两条绝对值曲线更容易判读,也更容易设成告警——因为它对流量规模不敏感。

3、等还是拒

三条判断依据。

看剩余预算:截止时间减去当前时刻,再减去一次调用的预期耗时。不够就直接拒绝——排队等到超时是最浪费的一种失败,它同时消耗了等待时间和线程。

看队列长度:队列必须有界,且界要按"预算除以平均耗时"算。无界队列会把所有请求都变成超时失败,而且失败得非常慢。

看调用用途:面向交互的调用宁可快速失败并降级,后台批处理可以排较长的队。同一个客户端要支持两种,靠的是调用时传入的用途标识。

4、被拒绝这件事要能被上层区分

返回一个通用异常,上层只能统一降级;返回带类别与建议等待时长的结果,上层才能做出不同的选择:交互场景直接返回兜底文案,批处理场景把任务重新入队并推迟,而重试逻辑则据此决定是退避重试还是彻底放弃。

这一条和第五章第六节的"判定函数返回类别而不是布尔值"是同一个原则的两次应用:在信息最充分的那一层把类别确定下来,不要让上层去反推。

九、异常处理:把失败翻译成可决策的结果

(一)从 Java 异常到业务结论

1、八类异常的翻译

连接类 IO 异常翻译成"瞬时故障,可重试"。业务代码不该区分"连接被拒"与"连接重置",那是传输层的细节。

请求超时异常翻译成"首字超时,可重试"。要记住它只覆盖响应头,不能用来判断整体是否超时。

自定义的空闲超时翻译成"流中断,谨慎重试"。标准库没有这个概念,必须自己定义并命名——命名很重要,因为它会出现在日志与看板的分组里。

组合凭证的包装异常必须先解包再分类。直接判断包装异常的类型,会把所有异步失败归成同一类,判据表整张作废。

线程中断异常翻译成"取消,不重试"。吞掉它而不恢复中断标志,会让优雅停机失效。

反序列化异常翻译成"协议不兼容,不重试"。常见成因是错误体被当成正常体解析,所以要先看状态码。

自定义的截断异常翻译成"流中断,谨慎重试"。它是"成功"与"失败"之间的第三种结局。

业务层的额度拒绝不是异常。把它做成异常会让正常路径依赖异常控制流——在高频拒绝的场景下,构造异常栈的开销会变得可观。

2、解包与分类是两件必须一起做的事

static Throwable unwrap(Throwable t) {
    while ((t instanceof CompletionException
            || t instanceof ExecutionException)
           && t.getCause() != null) {
        t = t.getCause();
    }
    return t;
}

分类之前必须先解包,否则所有异步失败都会被归成同一个"组合凭证异常"。这个缺陷的隐蔽之处在于:同步路径上一切正常,只有异步路径会出错,而两条路径通常由同一套测试覆盖不全。

一个实用的补充:解包之后如果仍然拿不到可识别的类型,把原始异常的类名与消息记进结果对象,而不是直接归成"未知错误"。线上出现新的失败形态时,这条记录是唯一的线索。

3、中断这一条值得单独强调

线程中断异常在很多代码里被当成一个普通异常捕获,然后记一条日志了事。

它的特殊之处在于:捕获它的同时,线程的中断标志被清除了。如果不调用一次恢复中断标志的方法,调用栈上层的停机逻辑将永远等不到这个信号,表现为"服务关不掉"——而这个现象和模型调用看起来毫无关系,排查时几乎不会有人往这个方向想。

正确处理是三步:恢复中断标志、关闭底层的流与连接、把它翻译成"取消"类别并立刻返回,不做任何重试。

(二)不要把失败降级成成功

1、四种降级形态

返回空字符串而不是抛出:调用方拿到空回复,写进业务字段,几天后有人问"为什么这些工单的摘要是空的"。

捕获后记一条日志然后返回默认值:默认值在下游被当成真实数据参与计算。

把截断的回复当成完整结果:第五章第六节那条完整的失真链条。

把"限流拒绝"记成"调用成功但结果为空":成功率看板保持完美,而容量问题被隐藏。

2、共同特征与共同解法

四种的共同特征是:它们都让一次失败在系统里留下的痕迹小于它的真实影响。

共同解法也只有一条:让结果对象带类别,让调用方显式处理每一类。 Java 的类型系统可以帮上忙——把结果做成一个密封的接口,实现类分别是完整成功、长度截断、内容拦截、连接截断、服务端错误、额度拒绝、客户端取消,调用方用模式匹配处理。漏掉一类,编译器会提醒。

这个约束比任何评审清单都可靠,因为它在编译期生效,而不是在评审时靠人记得。

十、把它们装成一个客户端

(一)一次调用要穿过的九层

1、从外到内的九层

业务入口,把用途、租户与截止时间放进调用上下文。预算守卫,剩余时间不足以完成一次调用就直接放弃。额度闸门,请求数、词元数、并发三个桶同时通过才放行。重试循环,按判据表决定是否再来一次,受重试预算约束。熔断,统计的是单次尝试的成败。单次超时,四层时钟在这里生效。认证装配,取密钥、拼请求头。传输,标准 HTTP 客户端,连接复用在这一层。流式解析,分帧、聚合、逐帧检查错误与用量。

2、三处次序的理由

熔断在重试内侧。熔断的统计窗口里应该装"单次尝试"的成败,而不是"一次业务调用最终成不成功"。放在重试外侧时,三次失败的尝试只会往窗口里写一个失败,熔断器看到的错误率被稀释到三分之一,于是它在依赖已经全面故障时仍然保持闭合。放在内侧,每一次尝试都计入统计,熔断打开之后重试循环立刻得到快速失败,整条链的反应时间从秒级降到毫秒级。

超时在重试内侧。在内侧,每次尝试各自享有一份超时;在外侧,一个总超时被三次尝试瓜分,第三次通常只剩几百毫秒,注定失败。但内侧还有一个必要的补充:每次尝试的超时要与剩余总预算取小,否则三次各八秒会让总耗时突破二十四秒,而上游只答应等八秒——这正是第二层预算守卫存在的理由。

额度闸门在重试外侧,但计数点在重试内侧。闸门管的是"本实例向对方发出的总量",重试发出的请求同样消耗额度,所以它必须把重试也罩进去;而它的令牌应该按每次尝试扣减,而不是按每次业务调用扣减。这是九层里唯一一个"位置在外、计数在内"的机制,实现时要特别注意。

3、九层可以合并,次序不能改

在一个只有几百行的客户端里,九层通常会被合并成三四个类。合并本身没有问题——把预算守卫与额度闸门写在同一个方法里,把认证装配与传输写在一起,都很常见。

不能改的是次序关系。判断合并是否安全的方法很简单:把合并后的代码按执行顺序展开,检查上面三条次序约束是否仍然成立。

(二)同步与异步两套入口

1、为什么两套都要有

同步入口用于绝大多数业务调用:代码直观、异常传播自然、调试方便。在虚拟线程可用的运行时上,它没有任何吞吐代价。

异步入口用于两类场景:一是需要并行发起多个模型调用并聚合(比如同时做分类与摘要),二是需要在回调里做流式转发(比如把模型输出实时推给前端)。

两套入口应该共用同一条策略链,区别只在最内层的传输调用与结果承载方式。如果两套入口各写一遍重试与限流,它们迟早会漂移——而漂移的表现是"同步路径正常、异步路径偶发异常",排查成本很高。

2、共用策略链的写法

把策略链写成一个接受"一次尝试"的高阶函数,尝试本身返回一个结果凭证。同步入口在最外层等待凭证,异步入口直接返回凭证。

// 策略链只认凭证,不关心调用方式
CompletableFuture<Result> execute(Ctx ctx, Supplier<CompletableFuture<Result>> attempt);

// 同步入口
Result call(Ctx ctx, Request req) {
    return execute(ctx, () -> transport.sendAsync(ctx, req)).join();
}

// 异步入口
CompletableFuture<Result> callAsync(Ctx ctx, Request req) {
    return execute(ctx, () -> transport.sendAsync(ctx, req));
}

同步入口的 join 会把异常包装一层,所以它必须紧接着调用第九章那个解包函数——这是两套入口里唯一需要区别对待的地方。

(三)一份可以直接读的骨架

1、包结构

传输包放客户端单例、连接配置、请求装配与响应体处理器。协议包放事件流解析器、聚合器、错误映射与结果类型。策略包放预算、闸门、重试、熔断与判据表。领域包放面向业务的门面与用途配置。

四个包的依赖方向是单向的:领域依赖策略,策略依赖协议,协议依赖传输。反向依赖一次都不应该出现——如果出现了,通常意味着某个策略需要传输层的细节,而正确的做法是把这个细节提升成协议层的一个结果字段。

2、配置项的数量

一个写得好的原生客户端,对外暴露的配置项应该在十二个以内:连接超时、首字超时基线、首字超时的长度系数、帧间空闲超时、请求数额度、词元数额度、并发额度、安全系数、重试预算比例、退避基数、最大退避、熔断错误率阈值。

总时长上限不在其中——它来自截止时间。重试次数也不在其中——它由预算推导。这两个"本该有"的配置项的消失,恰好是这套设计成立的标志。

3、代码量的量级

对接一个服务商、只用文本能力、支持流式与非流式、包含上述全部机制的客户端,代码量通常在六百行以内,其中事件流解析约一百二十行、策略链约两百行、其余是装配与类型定义。

这个数量级很重要:它是"值得自己写"与"应该换成现成封装"之间的分界线。第十二章会展开。

十一、观测与验证:怎么证明这套客户端是对的

(一)一次调用要留下的十四个字段

1、四组字段

身份与归属四个:调用标识(本次尝试唯一)、请求指纹(同一逻辑调用的重试共享)、租户与用途(成本归账与限流分组)、模型标识(换模型对比的分组维度)。

时间四个:发起时刻(单调时钟)、首字时刻(区分排队与生成)、末帧时刻(算生成速率)、总耗时(含全部重试)。

规模与成本三个:输入词元数、输出词元数(两者都来自响应而不是估算)、帧数(异常少说明被截断)。

结局三个:结果类别(七类之一,不是布尔值)、尝试次数(放大倍数的来源)、闸门等待时长(本地排队的代价)。

2、两个最常被漏掉的字段

第一个是首字时刻。没有它,"慢"这个现象无法被拆成"排队慢"与"生成慢",而这两者的处理方向完全相反——前者要减流量或换额度等级,后者要缩短输出或换模型。

第二个是尝试次数。没有它,看板上的调用量是"尝试数"而不是"业务调用数",于是故障期的曲线同时反映了流量与放大倍数,两个变量搅在一起无法判读。

这两个字段的采集成本都接近于零,唯一的原因是没人在设计时想到。而它们在故障时的价值,高于其余十二个字段的总和。

3、日志里绝对不该出现的三样东西

完整的提示词与完整的回复:它们是业务数据,可能含个人信息,且体积会让日志系统在高峰期成为瓶颈。需要时应存到专门的取证存储,并按分级授权访问。

认证头,无论哪种形态。

原样转贴的错误响应体:认证类错误的响应体里经常回显密钥前缀。

把这三条写进日志封装层,而不是靠每个调用点自觉——这是第四章那条"包成专门类型"原则在日志侧的延续。

(二)四张看板

1、时延分解看板

三条线:首字时延、生成时长、总耗时。

首字抬升而生成不变,指向对方排队。生成时长抬升而首字不变,指向输出变长或对方降速。两条都不变而总耗时抬升,指向重试在起作用。三条都抬升,指向流量或额度问题。

一张图,四种结论。如果只能加一张看板,加这一张。

2、结局分布看板

按七个结果类别堆叠。"完整成功"之外的每一类都应该有独立曲线。

其中"连接截断"这条线值得单独关注:它悄悄上涨通常意味着中间设备的空闲连接策略与流式长回复不兼容,而这个问题在其他任何指标上都看不出来。

3、额度与闸门看板

四条线:本地拒绝、服务端拒绝、闸门等待时长、词元用量。加一条比值曲线:服务端拒绝除以本地拒绝,持续大于一即告警。

4、成本看板

按租户与用途分组的词元数与估算金额,再加一条"重试消耗占比"。后者超过一成通常意味着判据表需要收紧,或者某一类失败被错误地归进了可重试档。

(三)故障注入矩阵

1、十二种现场

连接直接被拒、响应头迟迟不来、首字很快之后卡住、中途断开、缺少结束标记、错误帧、畸形负载、半个多字节字符、注释行与心跳、额度拒绝带等待提示、认证失败、超长回复。

每一种都应该有一条断言——断言的不是"不失败",而是"失败得对"。比如"中途断开"这一条,断言的是结果类别等于"连接截断",而不是断言调用成功。

2、为什么应该是单元测试而不是集成测试

它们不需要真实网络,也不需要真实模型——桩服务在同一个进程里起一个本地端口即可。跑一整轮不到两秒,可以放进每次提交的流水线。

相比之下,把它们写成需要外部环境的集成测试,结果是"偶尔跑一次,红了就注释掉"。客户端这一层的所有关键判据,恰好都能用这种成本写成断言,这是一个应该被利用的巧合。

3、还应该补两个并发场景

第一,同时发起两百路流式调用,然后全部注入卡住:断言线程数、连接数与并发额度在空闲超时之后回到基线。这一条能抓出漏掉的关闭,而单条测试完全覆盖不到。

第二,令牌在高并发中途过期:断言续签只发生一次,并且没有业务调用因为续签而失败。

4、如果只能写一个测试

写"发三帧后停止写入"这一条。

它同时检验四件事:帧间空闲时钟是否在走、取消是否穿过了全部四道边界、已产出内容是否被正确交出、以及结果类别是否不是"成功"。这四件里任意一件写错,都会在生产上表现为一类难查的故障。

(四)把判断固化成门禁

1、三条可以自动化的门禁

第一条,密钥不可打印:断言日志输出里不含密钥前缀,断言结果对象的字符串表示里不含原值。

第二条,判据表全覆盖:参数化测试遍历判据表的每一行,断言策略层的决策与表一致。新增一行而忘了实现,测试会红。

第三条,配置项数量不超标:断言对外暴露的配置项在十二个以内。这一条看起来奇怪,但它能有效阻止"遇到问题就加一个开关"这种缓慢的腐化。

2、两条只能靠评审的

超时是否挂在截止时间上,而不是配置常量。以及关闭逻辑是否在异常路径上也执行。

这两条无法用测试覆盖,因为它们的错误形态是"多了一条没走到的路径",而测试只能覆盖走到的路径。它们应该出现在代码评审清单的前两行。

十二、什么时候该换成现成的封装

(一)五条判据

1、五条

供应商数量超过两个:每家的字段命名、流式语法、错误结构、额度口径都不一样,自写意味着要维护多套协议层,而这部分知识没有任何复用价值。

需要多模态:图片、音频与文件上传引入分块编码与大体积请求体,请求体的构造复杂度上一个台阶。

需要服务端状态:会话、文件、向量库这类有生命周期的资源,自写要额外维护一套资源管理,而它和本文讨论的调用工程没有关系。

团队里只有一个人懂:自写客户端里最难的是流式与超时那两段,只有一个人能改的代码,在他休假时等于不能改。

开始重造治理能力:当你发现自己在写熔断器、连接池统计、配置热更新这类东西时,说明已经越过了边界——这些是通用能力,不该重写。

2、反过来,继续自写是合理的

只对接一个供应商、只用文本能力、调用形态稳定在两三种、并且团队需要对时延与成本有精确控制时,自写客户端的总代码量通常在六百行以内,而它换来的是每一处行为都可解释。

很多线上问题的排查时间差别,就在"能不能读懂那六百行"。

(二)一条折中路线

1、把自写的部分收缩到策略层

交给现成封装的是:协议差异、字段映射、多模态与服务端资源、流式语法细节。

自己保留的是:超时的四层划分、重试判据与预算、额度的三个闸门、以及可观测字段。

理由很清楚:前者是"和谁对接"的知识,会随供应商变化而作废;后者是"怎么扛住"的知识,换任何供应商都保留。

2、这条路线的实现形态

把服务商封装当成第九层(传输加解析),在它外面套上自己的策略链。绝大多数封装都提供了同步与异步两种调用形态,把它们包成第十章那个"一次尝试"的高阶函数即可。

需要注意一个细节:很多封装自带重试与超时,接入时必须先把它们关掉,否则会和外层的策略链叠加,形成第七章那种乘法放大。这个检查应该写进接入清单的第一条。

十三、反模式清单与一页纸

(一)十八个反模式

请求装配四个:每次调用新建一个客户端;把请求体用字符串拼接而不转义;不设输出上限;请求体用只能读一次的流,重试时发出空体。

认证与密钥四个:密钥写进源码或提交进仓库;把请求头整体打印进日志;令牌由每个业务线程各自续签;作废旧密钥不等全量实例确认。

流式解析四个:按字符串分块拼接,切出半个汉字;读到一行就当成一帧;把注释行当数据去解析;流结束时不检查结束标记与缓冲区。

时间与取消四个:只设一个总超时;把请求超时当成整体超时用;超时后不关闭流与连接;超时守卫任务不取消。

重试与限流两个:默认所有失败都重试;只按请求数限流,不按词元数。

(二)如果只能记住三条

第一,超时不是一个数——流式调用至少需要首字、帧间空闲、总时长三条时钟同时在走,而它们应该全部挂在上游传下来的截止时间上。

第二,状态码 200 不等于成功——结束标记、缓冲区、结束原因、文本长度,四项都要检查,判定结果要带类别而不是布尔值。

第三,重试不是免费的——它会把输入词元再付一遍,所以必须有预算而不只是次数,并且要按用途分档。

十四、结语:从"调得通"到"说得清"

把大模型接口接进一个 Java 服务,第一版二十行代码就够了。本文写了十三章,讨论的全部是这二十行之外的东西——而这些东西加起来,恰好构成了"能上线"与"能长期运行"之间的全部差距。

回过头看,这十三章处理的其实只有三件事。

第一件是把一个不可见的过程切成可见的段。一次调用的十一个阶段、流式的三条时钟、四组可观测字段,做的都是同一件事:让"慢了"和"失败了"这两个笼统的判断,变成可以指向具体一段的结论。系统的可运维性,本质上取决于它能把问题定位到多细的粒度。

第二件是把临场判断变成查表。重试判据表、失败形态的七个类别、故障注入矩阵的十二行,做的也是同一件事:把"这种情况该怎么办"从每次遇到时现想,变成一次性写清楚、之后只需要查。这类表格的价值不在于它比人聪明,而在于它不会在凌晨三点忘掉某一行。

第三件是让失败留下与它真实影响相称的痕迹。不要把截断当成功,不要把限流记成空结果,不要把七种结局压成一个布尔值。一次被正确记录的失败,比一百次被记录成功的失败更有价值——因为前者会被修复,后者只会积累。

至于本文开头那个问题——到底该不该自己写——答案其实不重要。重要的是,把这十三章的内容过一遍之后,无论你最终用的是自写的六百行,还是服务商提供的封装,你都知道那六个决定分别被做成了什么样,以及在什么情况下需要把它改回来。

这大概就是"不用框架写一遍"这件事最实在的收益:它不一定改变你最后用什么,但它一定改变你怎么用。

参考资料

协议与规范

Java 平台与标准库

超时、重试、退避与过载治理

模型接口的流式、限流与错误语义

可观测性与成本归账

密钥与日志安全

测试与故障注入

转载自 CSDN-专业IT技术社区

原文链接:https://blog.csdn.net/xiaofeng10330111/article/details/166794408

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--