20 篇博文 含有标签「rate-limiting」

响应头显示你还有每分钟 480,000 个 token 的剩余额度。但在你仅消耗了 240,000 个之后，429 错误就降临了。你的调度器一直在根据一个运行环境根本不会遵守的数字进行自动扩缩，墙上的燃尽图显示的是文档里的理论值，而限流器执行的却是另一套完全不同的规则。

这种故障往往需要很长时间才能被察觉，因为路径上的每个组件都在执行其宣称的功能。供应商返回了一个响应头。你的客户端解析了它。你的调度器读取了它。你的仪表盘绘制了它。这些层级都没有损坏。真正出问题的是那个假设：即响应头是一份契约。

你的聊天产品已经在 1.5 秒的 p99 延迟 SLO 下平静地运行了数月。请求率平稳，prompt 大小平稳，模型也未曾改变。接着，在某个周二下午，p99 突然飙升至 4.8 秒并保持在那里。值班排查发现聊天路径（chat path）没有任何异常：同样的每分钟请求数，同样的中位 prompt 长度（约 800 token），SDK 的重试行为也完全一致。聊天服务当天的部署日志为空。故障持续了六个小时。

原因出在另一个团队的代码库中。那天早上，一个长文本摘要功能上线了，使用的是同一个组织密钥（organization key），其平均 prompt 为 12,000 token。他们的请求率并不高 —— 每分钟仅几百次 —— 但每次调用消耗共享的每分钟 token（TPM）预算的速度比你的快 15 倍。供应商的限流在聊天路径上触发了，因为聊天路径与摘要团队共用同一个刚刚被掏空的“桶”。没人动过你的代码，没人超出计划的容量，而你的 SLO 现在却成了你的团队从未读过的工作负载的函数。

故障始于 14:03，服务商返回了 429 错误，并带有一个 JSON 响应体，内容为 {"status": "ok", "data": null}。这个客户端库是六个月前由一个被坑过两次的人匆忙写成的——一次是因为网关返回了带有 error 字段的 HTTP 200，另一次是因为服务商在请求实际成功时返回了 HTTP 500。所以，这个库学会了信任响应体，而不是状态码。状态码要求限流，响应体却说继续。客户端相信了响应体，发出了下一个请求，又得到了一个带有 ok 的 429，再次发送，到 14:11 时，服务商的熔断器已将该账户在该小时的剩余时间内列入了黑名单。

服务商并没有完全撒谎。429 是真实的。但在响应流水线的某个环节，一个默认的封装层覆盖了限流负载——这是一个来自包装服务的通用 {"status": "ok"}，用于填充缺失字段，并应用在了一个该包装服务无法识别的错误之上。状态码是正确的，请求头是正确的，响应体是错误的，而响应体正是客户端读取的部分。

你的重试逻辑在遇到 429 时会退避。当延迟上升时，你的队列深度告警会触发。在这两个信号之间，存在一个供应商负载区间，此时正确的做法是“减速 20%”——而供应商唯一会告诉你的是那个姗姗来迟的二进制限流信号。对于智能体集群协作来说，最有用的信号恰恰是没有任何推理 API 真正公开的那个。

429 是墓碑，而不是警告。当你收到它时，供应商已经认定你的流量过载，你已经浪费了一次请求的 Token 计数，而且——如果你与其他消费者共享租户——他们可能也收到了。有趣的故障模式不是 429 本身；而是它发生前的几秒钟，那时全世界的客户端都在“一切正常”和“你被切断”之间盲目飞行。

你的试用版提供了“每天 100 次生成”。你的定价团队模拟了一个感兴趣的用户花一周时间进行体验。但第一个将智能体（agent）指向端点的试用者，在 70 秒内就用完了当天的配额，19 分钟内用完了每周配额，并在第二天午餐前耗尽了季度的推理预算。没有人收到警报，因为唯一设置的警报只在试用用户转化为付费用户时才会触发。

试用限制在制定时并没有错。它们针对的是不再适用于当前典型用户的用法分布。在六个月前的定价审查与今天早上的新用户注册之间，用户群体已经从点击按钮的人类转向了不知疲倦的程序。仪表盘上的数字不再代表你设定它们时的含义。

速率限制从来就不是一种公平性原语。它只是一个逐渐“演化”而来的销售工程指标——是三年前某个解决方案工程师在客户接入期间随手写进文档、被复制到套餐定义中，且由于从未有人触发过而从未被重新审视的一个数字。这个限制写着“每分钟 100 次请求”，其真实含义是“超出了任何理性的集成方案的需求”，因为当时平台上的每一个集成都是由人类在键盘前驱动的后端服务，而人类每分钟敲不了 100 次字。

然后，一个付费租户将一个智能体（agent）指向了该端点。智能体不会打字。它不会为了阅读响应而停顿。它没有需要在请求之间渲染的 UI。它执行一个规划循环，每一个推理步骤调用一次 API，而模型制定一个推理步骤只需要大约 30 毫秒的实际时间。智能体在 3 秒内就触及了每分钟的限额，在 3 分钟内触及了每小时的限额，而在轮值工程师的咖啡还没变凉之前，它就已经耗尽了每日配额。在限流仪表盘更新之前，技术支持的升级请求就已经送达了。

你的网关给每个 tenant 干净利落地强制执行每秒 100 次请求的限制。dashboard 显示每个 tenant 都舒舒服服地在那个上限之下。但模型 provider 寄来的账单告诉你,你的支出上限照样被打穿了。rollout 电话会议上没有人能给出一个干净的解释。

答案在于限流器和账单衡量的是不同的东西。当用户点击一个按钮时,限流器看到的是一次"用户请求"。而 provider 看到的是一次 planner 调用、三次工具结果反思、一次因更严格 JSON schema 触发的格式修正重试,以及一次最终综合——每一次都带着自己的内部重试预算,在瞬时 429 或 500 回来时就会触发。一次点击可以扇出成三十次模型调用。限流器只数到一次。桶以它被设计容量的三十倍漏水。

在 HTTP 边界上对 agentic 系统做限流,就像在高速公路入口立速限标志,而入口里面的车却在自我繁殖。除非限流器理解了这个循环,否则循环就会绕过它。

当你的应用程序第一次从模型供应商那里收到 429 错误时，发生了一些重要的事情，但几乎没人注意到。并不是错误本身，而是接下来执行的那行代码。也许你的 HTTP 客户端会以指数退避进行重试。也许它会降级到更小的模型。也许它会将请求排队，或者直接丢弃，又或者显示一个永远无法解决的加载动画。无论它做什么，这种行为现在就是你的容量策略。它决定了当供不应求时，哪些用户能获得服务，哪些用户的体验会降级。

而且，几乎可以肯定你并没有亲自制定过这个策略。它是由编写 SDK 封装的人、重试装饰器，或者是某人从教程中复制的三行 try/except 代码决定的。在负载下，你的系统中最重要的决策——当无法兼顾所有任务时该怎么办——正由一段没人审视过的代码作为容量决策来执行。

这篇文章的观点是，你应该把这段代码视为它的真实面貌：一个负载削减策略和一个容量计划，而不是一个错误处理器。429 并不是问题所在。问题在于你已经将系统在资源竞争下的行为设计，外包给了库的默认设置。

频率限制（Rate limit）过去曾是一个基础设施细节。当你遇到 429 错误，你会使用退避算法（backoff）重试，将溢出的请求排队，而 On-call 频道之外的人甚至根本不知道这回事。用户看到的响应只是比平时慢了几百毫秒。这就是故事的全部。

对于智能体（agentic）功能，这个故事不再适用。当一个智能体在执行多步计划的过程中，中途触及了供应商的每分钟 Token 数（TPM）上限时，失败并不会停留在基础设施层。它会表现为一个半成品的答案、一个在最后一次调用前卡住的工具循环，或者让用户盯着一个永远无法解决的加载动画。配额不再仅仅是后端容量数字，而变成了一个产品必须围绕其进行设计的约束条件 —— 就像产品围绕结账流程或空状态进行设计一样。

凌晨 2 点，一个定时报告生成任务向共享的 API 密钥并行发出五十个 LLM 请求。等到早上 9 点的产品演示开始时，每一个实时对话补全都在悄无声息地超时。错误仪表板一片绿色，日志里没有 429 错误。模型确实在返回响应——只是慢了十秒，而这个功能的 SLA 是两秒。

这就是配额饥饿。它不像故障，它看起来只是"今天 AI 有点慢"。

我认识的一个团队构建了一个带有智能体循环的金融助手。第一周，API 费用是 127 美元。第十一周，费用飙升至 47,000 美元——同样的系统，同样的功能，范围上没有任何有意的变化。智能体触及了速率限制，重试逻辑忠实地进行了重试，循环没有熔断器，成本在悄无声息中不断累积，直到有人注意到他们设置得太高的计费告警。

这不是一个 bug 的故事，而是一个架构的故事。团队的思维模型将速率限制视为需要被动处理的错误。他们构建的系统完全反映了这种模型。那 47,000 美元的那一周，正是系统按设计运行的结果。

你的 AI 功能在测试中运行完美。单轮问答，毫无问题。但在生产环境中，当真实用户进行一场 10 轮调试对话时，它却失败了——不是因为模型出了问题，而是因为你的速率限制器是为一个完全不同的世界设计的。

标准 API 速率限制是专为无状态 REST 调用设计的粗糙工具。每个请求被视为一个独立的、大致等量的消耗单元。对于 CRUD 端点而言，这种模型运行良好，因为每次调用确实具有可比性。但对于多轮对话，这种模型就行不通了——每一个后续轮次的成本都在递增，一次用户交互可能触发数十次内部模型调用，而会话中途被切断造成的损害，远比一次失败的单次查询严重得多。