1. 先说结论别直接并发打 Claude API中间最好加一层调度不少团队刚接入 Claude API 时低流量测试都挺顺一旦开始跑批量任务、多用户同时使用或者让 Agent 并发调用问题就来了429、超时、重试失败、队列越堆越长各种情况都会出现。这类问题很多时候并不是“服务器不够”也不是简单把并发数调低一点就能彻底解决。更稳妥的做法是在业务系统和 Claude API 之间加一个调用调度层用队列 多维限速 自适应重试来控制请求节奏。比较推荐的调用链路大概是这样业务请求 ↓ 参数校验与 token 预估 ↓ 任务队列 ↓ 优先级调度 ↓ RPM / ITPM / OTPM 多维限速器 ↓ Claude API 调用 ↓ 响应头校准 ↓ 失败重试 / 熔断 / 降级 ↓ 结果返回或异步回调这套设计的重点不是做到“永远不排队”而是把原本不可控的失败变成可控的等待。对于 Claude API 这种并发调用场景如果让业务线程直接一股脑去请求 API失败率上升其实是迟早的事。2. 为什么 Claude API 并发一高就容易失败很多开发者一开始会有个误解只要自己的 RPM 没超过限制就不应该触发 429。实际并没有这么简单。Claude API 的限速不是单纯的 QPS 模型而是多个维度一起限制。常见的问题主要有下面这些。第一是把 RPM 当成了瞬时并发额度。比如限制是 50 RPM并不代表你可以在 1 秒内同时发出 50 个请求。更安全的理解是平均下来大概每 1.2 秒放行 1 个请求而且还要同时考虑 token 消耗。第二只控制请求数没有管 token。Claude API 通常会同时受到 RPM、ITPM、OTPM 等限制。如果你只按请求次数限流那么长 prompt 或大输出任务依然可能很快把 token 额度打满。另外max_tokens设置太大也很常见。输出 token 的限制通常会参考max_tokens做预算。也就是说即便最终没有生成那么多 token过大的max_tokens也可能提前占用 OTPM 额度。还有一种情况是短时间突刺。分钟级总量没超不代表短时间内集中打出去就没问题。比如前 5 秒把一整分钟的请求量都发完就很容易触发限流。429 之后立刻重试也会放大问题。如果多个 worker 同时收到 429又马上重试就会形成第二波冲击失败率反而更高。再比如长 prompt 和短 prompt 混在同一个并发池里。长 prompt 会消耗大量 ITPM很可能把短请求也拖慢甚至一起拖失败。最后如果完全不读取 rate limit 响应头只靠本地固定 QPS 去跑本地限速器就很难跟上服务端真实额度的变化。3. 先搞清三个限速维度RPM、ITPM、OTPM在设计 Claude API 限速之前最好先把三个核心指标弄清楚。不然很容易出现“明明请求数没超为什么还是 429”的情况。RPM每分钟请求数RPM 控制的是单位时间内允许发送多少个请求。它适合限制请求频率但没法体现每个请求的 token 成本。比如下面两个请求在 RPM 里都只算 1 次一个短问答输入 1000 tokens输出 500 tokens一个长文分析输入 30000 tokens输出 3000 tokens。但它们对额度的压力显然完全不是一个量级。ITPM每分钟输入 tokenITPM 控制的是输入 token 的消耗速度。长上下文、批量文档分析、多轮对话历史都会明显增加 ITPM 压力。如果只按请求数限流短 prompt 和长 prompt 会被同等对待这就很容易出现一种情况请求数看起来没超但 token 已经超了。OTPM每分钟输出 tokenOTPM 管的是输出 token 的预算。这里尤其要注意max_tokens它不是设得越大越安全。如果所有请求都把max_tokens拉得很高在并发场景下就会提前占用输出 token 预算OTPM 很可能成为瓶颈。具体的 RPM、ITPM、OTPM 限额会受到账号、模型、层级以及平台策略影响。工程实现里不要把公开文章里的旧数字写死最好以 Anthropic Console、官方文档、响应头或者你所使用接入平台的最新说明为准。4. 并发数到底应该怎么估“降低并发”这句话听起来没错但不够可执行。真正要回答的是到底降到多少可以先用 RPM 粗略估算一个安全发送速率安全请求速率 ≈ RPM / 60 × 安全系数假设某个模型可用 RPM 是 50理论 QPS 50 / 60 ≈ 0.83 安全系数 0.7 建议放行速率 ≈ 0.58 QPS换句话说比较稳的节奏大概是约每 1.7 秒放行 1 个请求然后再根据平均请求耗时估算 worker 数建议 worker 数 ≈ 安全 QPS × 平均请求耗时秒数如果平均耗时是 8 秒worker 数 ≈ 0.58 × 8 ≈ 4.6那一开始可以先设置成 4 或 5 个 worker。不过要注意worker 数只是并发执行的上限不能把它当成唯一的控制手段。一个请求能不能真正出队应该由 RPM、ITPM、OTPM 三个限速器一起判断。5. 推荐架构用队列接住突刺用限速器控制出队在生产环境里不太建议业务请求直接调用 Claude API。原因很现实业务流量通常不均匀用户点击、批处理任务、定时任务、Agent 循环调用都可能在短时间内打出一波突刺。队列在这里的作用很明显比如接住瞬时流量控制请求出队节奏支持不同优先级把重试任务隔离出来避免业务线程长时间阻塞队列满的时候触发 backpressure也就是反压。常见实现可以用 Redis Queue、BullMQ、Celery、Kafka、SQS、Sidekiq 等。小规模系统一开始用内存队列也可以但要提前想清楚进程重启、任务丢失、横向扩展这些问题。更稳一点的做法是业务系统只负责提交任务真正的 Claude 调用由一个网关或 worker 集群统一处理包括排队、限速、调用、重试和监控。6. 队列怎么分层实时、普通、批量、重试不要把所有请求都塞进一个 FIFO 队列里。不同任务对延迟、成本和失败的容忍度都不一样最好分层处理。实时队列实时队列适合用户正在页面上等结果的任务比如短问答、轻量生成、交互式操作。这类任务的特点是低延迟、短超时、高优先级。普通队列普通队列适合可以等几秒到几十秒的任务比如摘要、改写、结构化提取。它们可以接受排队但不能无限期等待。批量队列批量队列更适合文档批处理、离线分析、批量生成等任务。这类任务通常 token 消耗比较大建议异步执行完成后再通过回调、站内信或轮询把结果返回给用户。重试队列重试任务一定要单独管理不能失败后立刻回到主队列里抢占新请求。尤其是 429、5xx、网络超时这类错误应该经过退避之后再重新入队并适当降低优先级避免形成重试风暴。队列必须有上限队列不是垃圾桶不能无限堆。至少要设置这些规则最大队列长度最大等待时间用户取消机制超时丢弃策略队列满时的拒绝策略。当队列长度超过阈值时可以返回业务级 429 或 503提示用户稍后再试也可以把任务转成异步处理。这就是 backpressure目的很简单别让整个系统被拖垮。7. 多维限速器怎么设计请求数、输入 token、输出 token 都要管Claude API 的限速不能只做 QPS。更合理的方式是至少维护三个限速器请求数限速器控制 RPM 输入 token 限速器控制 ITPM 输出 token 限速器控制 OTPM请求准备出队时最好同时满足这三个条件RPM 有额度 ITPM 有额度 OTPM 有额度伪代码可以这样理解while queue not empty: job queue.peek() estimated_input estimate_input_tokens(job.prompt) reserved_output job.max_tokens if rpm_limiter.allow(1) and input_token_limiter.allow(estimated_input) and output_token_limiter.allow(reserved_output): queue.pop() call_claude(job) else: sleep_until_next_available_slot()任务入队前也要做 token 预算不能等到出队才发现放不出去任务类型input token 估算max_tokens队列优先级说明短问答1k-3k1k高用户等待敏感摘要5k-20k2k中ITPM 压力较高长文生成3k-8k4k-8k低OTPM 压力高批量分析10k1k-3k低更适合异步队列另外建议按模型拆分限速器。不同模型的限制可能不同如果全部混在一个限速池里后面排查问题会很麻烦。对于多租户系统还应该在业务层增加用户级、租户级配额防止某个用户一下子把额度吃光。8. 429 后不要立刻重试重试和退避要设计好重试确实能提高成功率但设计不好也会放大故障。关键是要分清错误类型。适合重试的情况包括429等待 reset 时间或者使用指数退避后再重试5xx / 529指数退避加上 Jitter网络超时可以有限次数重试连接中断要看请求是否幂等再决定要不要重试。不建议原样重试的情况也不少400通常是参数错误重试没意义401 / 403应该检查 API Key、权限或账号状态413 或上下文过长要缩短输入而不是原样再发一次业务校验失败最好在入队前就拦住。比较常用的策略可以是最大重试次数2-3 次 基础等待1-2 秒 退避方式exponential backoff jitter 429 优先参考 reset header 重试任务必须重新进入队列如果是流式响应中途断开后要不要重试还得看业务能不能接受重复输出。比如涉及扣费、写库、发消息的场景就需要额外设计幂等键避免重复执行带来新问题。9. 如何读取 Claude API 的 rate limit 响应头做自适应限速本地限速器再怎么设计本质上也只是估算。服务端返回的响应头通常更接近真实状态。常见可以关注这些字段anthropic-ratelimit-requests-remaining anthropic-ratelimit-requests-reset anthropic-ratelimit-input-tokens-remaining anthropic-ratelimit-input-tokens-reset anthropic-ratelimit-output-tokens-remaining anthropic-ratelimit-output-tokens-reset这些字段不应该只是打印到日志里看一眼而是要真正参与调度。比如 remaining 低于阈值时就要主动减速。如果请求数或 token 剩余额度快耗尽了应该暂停一会儿或者降低出队速率。reset 时间可以用来判断该等多久。尤其是收到 429 后优先参考 reset header而不是盲目 sleep 一个固定时间。多个维度之间要看最紧的那个。比如 RPM 还有不少额度但 ITPM 马上见底那就应该按 ITPM 的 reset 时间暂停。服务端响应也应该优先于本地估算。本地 token 估算可能不准响应头正好可以用来校准限速器。另外这些信息一定要进日志和监控。排查“为什么 RPM 没满却还是 429”时remaining 和 reset 往往就是关键证据。如果你使用的是第三方 Claude API 兼容接入服务比如 ClaudeAPI 这类平台也应该以对应平台的最新说明、响应头和控制台信息为准。第三方平台通常会提供兼容接入、多线路选择、中文支持、企业充值、开票或基础技术协助等能力但不要默认它完全等同于 Anthropic 官方也不要期待所谓“绝对不限速”或“绝对稳定”。10. 常见错误设计这些做法会让失败率更高下面这些设计在 Claude API 并发调用里很常见但风险也确实很高只加线程池不加限速器只控制 RPM不控制 ITPM 和 OTPM429 后马上重试所有任务都共用一个 FIFO 队列max_tokens永远设到最大队列无限堆积没有最大等待时间用户取消后任务还继续执行不按模型拆分限速器不记录 rate limit 响应头重试任务和新任务抢同一个高优先级队列把 prompt cache 当成万能方案忽略 token 预算。prompt cache 在一些场景下确实可以降低成本或者提升效率。但它不能替代限速器。只要涉及长上下文、高并发、批量调用还是需要明确做 token 预算和出队控制。11. 上线后要看哪些指标限速设计有没有效果不能只看“报没报错”。更靠谱的做法是把关键指标都监控起来。建议至少关注这些Claude API 总请求量成功率429 比例5xx / 529 比例平均重试次数队列长度队列等待时间 P50 / P95 / P99请求耗时 P50 / P95 / P99input token 消耗速率output token 消耗速率各模型请求占比各模型失败率按用户或租户拆分的 token 消耗被主动拒绝的任务数超时丢弃任务数rate limit remaining 和 reset 的变化趋势。如果优化后 429 确实降低了但队列 P99 等待时间暴涨那说明你只是把失败变成了长时间排队。这个时候就要继续做任务分级、异步化、降级或者考虑申请更高额度。12. 总结一套更可落地的 Claude API 并发调用策略Claude API 并发请求失败率高通常不是某一个点出了问题而是整个调用链路缺少调度层。可以根据流量阶段选择不同方案低并发本地限速 指数退避 Jitter中并发队列 worker pool RPM / ITPM / OTPM 多维限速高并发独立 Claude 调用网关 分模型限速 分租户配额 监控告警批量任务异步队列 最大等待时间 backpressure所有重试必须重新入队不能立刻再次请求。归根结底别把 Claude API 当成普通 HTTP 接口无限并发调用。比较靠谱的 Claude API 限速设计应该同时控制请求数、输入 token 和输出 token用队列吸收突刺用响应头动态校准再用监控验证效果。这样做之后并发场景下的 429、超时和重试风暴就不再是随机爆炸的问题而会变成可预期、可排查、也更容易扩展的工程问题。