网关集成的五个坑:我们踩过你不用再踩
2026-11-13
网关集成的五个坑:我们踩过你不用再踩
代理网关看着像一层薄封装,直到你遇到第一个慢的、重复的、或者账单算错的
生产请求。下面是我们真正被咬过的失败模式,按出现顺序排。
1. 从响应体估 token,而不是读上游 usage
len(body)/4 数 token 不是计量,是占星。它在多语言内容上漂移、无视你注入的
system prompt、在代码内容上一路少算。v0.4 计量改为优先读上游 usage(JSON 与
SSE 末块),无真值时标 estimated——这个标记才是重点,因为没人能审计的账单
比没有账单更糟。抄任何 token 预算代码之前,先读
2. 对重试收费
网络重试是互联网的基本功能。如果重试重跑上游再计一次费,一个抖动的分钟能让
客户账单翻倍。幂等用 X-Request-Id,在转发上游之前检查,重放请求复用第一次
的结果和第一条台账。视频端点同理:创建任务在上游真的花钱,账单跟第一次调用走,
不跟最倒霉那次走。
3. 赌一个你没有的流式
「支持流式」+ 全文缓冲,生产环境里客户端会用体验惩罚你:逐 token UI 卡死,
假设分块节奏的代理超时算错。如果是缓冲,就在文档里明说,让客户端按真实能力
集成。我们文档里写的是缓冲式 SSE,明示。
4. 让版本变成一个 header
路由不编码版本和模式,某个未来的工程师就会加一个把两者交叉的配置开关。路径
编码(/intl/a/...、/intl/b/...)让边界出现在每行日志、每张 bug 截图里。
国内版禁止转售,由服务它的同一条路径执行——没有开关可配错。
5. 把价格和配额当成一个数字
统一费率计 token 的网关,在上游有分模型价格的那一刻崩塌。我们成本侧工作活
下来的模式:目录价、折扣、结算基准分层;收入会计和成本会计永不共模块;公共
构建在部署前扫描成本字段泄漏。设计在内网计量与账单文档(不公开),契约级规则
在 API 参考 可见。
元错误
五个坑共享一个形状:系统对 demo 是对的,对第二个客户是未定义的。把计量和失败
路径按「你还没有的那个客户」设计,第一个客户自然上道。想要契约级版本,从
开始。