Demo 里调大模型 API 三行代码,生产里是另一头怪兽:限流 429 随机砸脸、网络抖动断流、token 账单月底吓人、API 密钥不敢进仓库。LLM API 工程(把模型调用当作不可靠、昂贵、有配额的外部依赖来建设的工程实践)这一章把生产化的六件事一次配齐——它是 22 章的收口,也是 23 章框架层的地基。
LLM 网关的错误要分两类处理。可重试:429 限流(按 Retry-After 头等待)、5xx 网关侧抖动、网络超时——用指数退避加抖动(每次重试等待时间翻倍并加随机量,避免集体同时重试)策略,三到五次封顶。不可重试:400 参数错误(重试一万次还是错)、401 密钥失效(该报警不该重试)、内容审核拒绝(改输入而不是重发)——这类错误重试纯属浪费配额。区分动作本身就是工程判断:见到 429 先看 Retry-After 头(服务端明示等多久,比自算退避准)、见到 401 触发密钥巡检告警、见到 400 把请求体落日志排字段问题——错误码是指南针,不是噪声。写法上一行兜底:
.retryWhen(Retry.backoff(3, Duration.ofSeconds(1)) // 最多3次
.jitter(0.5) // 抖动防齐射
.filter(e -> retryable(e)) // 只重试可重试错误
.onRetryExhaustedThrow(TimeoutException::new))
超时必须分层:连接超时秒级、读取超时按流式与非流式分开(流式首字可以快,总时长放宽),非流式整调超时按 P99 设——超时矩阵的思路与 16.3 的 Feign 超时治理完全同构:超时不是全局一个数,是每个下游一份契约,这里下游就是模型。
你的 TPM/RPM 配额是固定的,超额就 429。两层控制:信号量限并发(同时进行的模型请求数封顶,保护下游也保护自己线程池——7.3 的教训在 AI 场景同样成立);令牌桶控速率(按 token 速率平滑放行,应对 TPM 限制),Guava RateLimiter 或 Sentinel(16.5)都能担纲。再往上一层是排队降级:高峰期请求进队列、预计等待超时的直接返回降级话术——「稍后再试」好过把用户挂死在超时上;按租户/用户维度再切一刀配额,单个重度用户或异常脚本就不会吃光全站额度(限流的三层结构与 16.5 的流量防护完全同构,只是被保护的对象换成了模型配额)。多账号/多 key 轮转是灰色的省配额手段,商用前先读服务商条款,别把公司账号玩进黑名单。
成本三板斧。计量:每次调用记录 usage(prompt_tokens、completion_tokens),按模型单价折算入账——按功能维度聚合,哪个功能烧钱一目了然。预算与告警:日/月预算线加告警,Prompt 被攻击或死循环调用工具时,费用曲线会垂直起飞,没有告警就是月底见尸;告警之外再加硬熔断(单请求 token 上限、单用户日配额),把「异常消耗」在分钟级拦住。省法:Prompt 瘦身(System Prompt 去冗词、历史裁剪——23.2 的记忆策略同时是省钱策略)、缓存命中(前缀相同部分走 Prompt 缓存半价,System Prompt 固定不变就是在给缓存创造命中条件)、模型分级(简单分类用小模型,难任务才上旗舰——核心性价比哲学:不是每道题都值得用最贵的脑子,分类抽取这类任务小模型的准确率差距常在个位数百分比,价差却是十倍)。
密钥管理三原则:不进代码仓库(与 18.1、19.5 同一条红线,用 {{API_KEY}} 占位符,真实值从环境变量或配置中心注入);服务端代理(前端永不直连模型 API——密钥泄露在浏览器里等于公开钱包,前端调自家后端,后端持钥转发);可轮转(密钥泄露能快速换新,多环境隔离)。多模型路由是架构层面的保险:抽象统一的调用接口(23.1 的 ChatModel 就是这个抽象),主模型故障或限流时按优先级降级到备用模型,A 厂停服切 B 厂只改配置——把「单一供应商风险」变成一次配置变更。每次降级切换还要记一条日志:路由可观测,故障复盘时才有「什么时候切的、为什么切」的时间线。观测收尾:调用量、延迟(首字/全程)、错误率、token 成本四个指标进监控(16.6 的面板上加四条线),LLM 调用才配叫「生产依赖」。
LLM API 工程的心法是「把模型当又贵又不稳的外部依赖」:错误分类后再重试、并发速率两层限、usage 记账加预算告警、密钥服务端代理、多模型路由兜底——做完这六件事,AI 功能才从「演示能跑」长成「生产敢上」,22 章的地基到此浇筑完毕。