LiteLLM max_parallel_requests 超限为什么直接返回 429

LiteLLM 返回的这类 429，很多时候不是上游模型厂商拒绝，而是 Router 发现某个 deployment 的并发槽位已经全部占用。它不会把请求放进隐藏队列，而是在入口立即拒绝，所以调用方看到的是“快失败”的 429。

官方地址：https://docs.litellm.ai/docs/routing

max_parallel_requests 的槽位与429是什么关系

把一个 deployment 想成只有若干个并发席位。配置为 2 时，前两个请求进入在途状态，第三个请求到达时如果两个席位都未释放，LiteLLM 就在路由层返回 429。这个判断发生在真正调用供应商之前，因此不能用“供应商配额还很充足”来解释它。

典型错误信息会提到 all max_parallel_requests slots in use、model group 和当前上限。它回答的是“网关现在没有空闲席位”，不是“模型服务一定过载”。

按配置优先级算出真正生效的上限

先看 deployment 自己的 litellm_params，再看 Router 默认值。可按下面的顺序检查：

model_list:
  - model_name: chat-model
    litellm_params:
      model: openai/gpt-model
      api_key: os.environ/OPENAI_API_KEY
      max_parallel_requests: 8  # 中文注释：为这个部署设置八个并发槽位
router_settings:
  default_max_parallel_requests: 20  # 中文注释：只给未单独配置的部署兜底
  num_retries: 0  # 中文注释：排查阶段让槽位拒绝尽快暴露

排查阶段可以先把 num_retries 设为 0，让调用方直接看到第一次拒绝；否则 Router 的重试或 fallback 可能让日志看起来像“偶发变慢”。这不是把重试永久关闭，而是先获得清晰信号。

单进程上限不等于整个集群共享上限

LiteLLM 文档说明，deployment 的并发上限按进程计数。一个 Proxy worker 配置为 8，并不自动表示整个 Kubernetes 集群只有 8 个共享槽位；多个 worker 或 pod 可能各自拥有一套计数。反过来，如果你期待跨实例统一硬上限，就要采用文档支持的集中协调配置，并单独验证部署方式。

因此，日志排查至少记录三项：命中的 model group、worker 或 pod 身份、请求开始和结束时间。只看客户端的 429 数量，无法判断是单实例太小、流量分布不均，还是调用方瞬时并发过高。

先分清网关429，再决定怎么处理

供应商也会返回 429，但两者处理路径不同。LiteLLM 自己的并发拒绝通常在消息中指出 deployment 槽位；供应商限流则会出现具体供应商异常或上游限流字段。不要因为状态码相同就盲目增加 max_parallel_requests，否则只会把压力更快推给上游。

处理方案可以按目标选择：

• 需要更高吞吐：在确认供应商额度和模型服务能力后，调大部署上限或增加同模型部署。
• 需要平滑突发：在业务侧建立有界队列，把排队时间和取消策略放在可观测的位置。
• 需要快速失败：保留 num_retries: 0，让调用方根据明确的 429 做退避。
• 需要容错：配置同一 model group 的 fallback，但要监控 fallback 是否把拥塞转移成上游限流。

常见问题

调大默认值后，显式值为什么没变化？

因为 deployment 自己的 max_parallel_requests、rpm 或 tpm 优先级更高，默认值只负责没有单独配置的部署。

429一定会等待到有空闲槽位吗？

不会。这个并发限制路径是立即拒绝，不是内置等待队列；需要排队时，应在业务侧或专用队列端点实现。

怎么判断是不是供应商限流？

查看错误消息、供应商异常类型、响应头和 LiteLLM 调用标识；若消息明确写出部署槽位全占用，优先按网关并发问题处理。