LiteLLM 常见错误：超时、预算警报与提供商故障

LiteLLM 常见错误：超时、预算警报与提供商故障

大多数 LiteLLM 常见错误起初看起来像是提供商问题：请求超时、预算警报始终未到达，或者原本正常的模型突然返回 404 或 503。最快的修复方法是在更改重试策略或切换模型之前，先确定发生故障的控制层。

使用本指南区分客户端截止时间、LiteLLM 网关策略、模型配置、提供商容量和支出执行。本指南包含一个小型事件处理流程，可针对超时、预算控制和提供商故障重复使用。

快速解答：保留一个失败请求，对错误进行分类，使用最小调用重现它，并且一次只更改一个控制项。从 LiteLLM 的标准化异常类型、请求元数据和调用 ID 开始，而不只是查看 HTTP 状态。

LiteLLM 会将许多提供商故障映射为与 OpenAI 兼容的异常类型，并在异常中公开 HTTP 状态、消息和源提供商。当您保留原始错误上下文，而不是将其替换为通用的 500 时，LiteLLM 常见错误会更容易排查。有关当前映射，请参阅 LiteLLM 异常映射参考。

LiteLLM 常见错误矩阵

此表是这篇 LiteLLM 常见错误指南的主要价值内容：它将模糊的网关故障转化为下一步需要进行的具体观察。

五分钟 LiteLLM 常见错误分诊流程

在编辑 config.yaml 前，保存一个具有代表性的失败案例。根据需要对密钥和提示内容进行脱敏，但请保留运行字段。

1. 捕获请求身份信息。记录时间戳、环境、路由、请求的 model、HTTP 状态、LiteLLM 异常类型、错误消息、提供商名称和客户端尝试次数。
2. 捕获网关身份信息。如果存在，请保存 x-litellm-call-id。LiteLLM 将此标头记录为在日志系统中跟踪请求的最佳标识。同时记录 x-litellm-model-id、x-litellm-model-api-base，以及响应中公开的版本标头。LiteLLM 日志记录文档列出了当前标头。
3. 对故障进行分类。它是无效请求、身份验证/权限问题、预算/速率限制、超时，还是上游服务故障？不要将所有 4xx 错误放入同一个重试类别。
4. 进行一次最小化的非生产环境复现。使用与应用程序相同的虚拟密钥和公共 model_name。在测试基本请求之前，先移除应用程序特定的并发设置和工具调用。
5. 一次只更改一个层。在同一次部署中同时进行模型名称修正、超时调整和回退变更，会使最终结果无法解释。

以下是适用于与 OpenAI 兼容的 LiteLLM 代理的通用最小探测：

curl -i --request POST "$LITELLM_PROXY_URL/v1/chat/completions" \
  --header "Authorization: Bearer $LITELLM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "support-chat",
    "messages": [{"role": "user", "content": "Reply with OK."}],
    "max_tokens": 16
  }'

重点不在于 support-chat 是一个通用模型名称，而在于测试必须使用网关中配置的公开名称，然后保留响应标头和正文，以便与失败的应用程序请求进行比较。

超时错误：找出实际触发的截止时间

超时是最容易误导人的LiteLLM 常见错误之一，因为请求可能在多个层级过期：

• 调用方可能先取消请求。
• LiteLLM 部署或路由器可能应用了更短的截止时间。
• 代理的 request_timeout 可以终止长时间运行的上游调用。
• 提供商、负载均衡器或网络路径可能会关闭请求。
• 流式响应可能成功开始，然后在数据块之间停滞。

LiteLLM 的异常映射将超时故障记录为 openai.APITimeoutError。对于原生和透传路由，当前的超时文档说明了请求、部署、路由器和代理设置之间的优先级顺序。在应用配置更改之前，请检查与您的部署版本相匹配的文档版本。

从截止时间预算开始，而不是设置更大的数值

选择您的用户流程能够容忍的总延迟，然后从后向前分配。例如，交互式体验可以为排队、一次重试和响应渲染预留时间，而不是让上游调用消耗整个用户可见的截止时间。

# 说明性起点——请根据您的工作负载和 LiteLLM 版本进行调整。
litellm_settings:
  request_timeout: 60
  set_verbose: false
  json_logs: true

此示例有意采取保守设置：它为代理提供了有界的故障模式，而不是让连接一直挂起。LiteLLM 的生产环境指南建议设置请求超时并使用结构化生产日志。

发生超时时，请按顺序回答以下问题：

不要让自动超时无限期重试。只有在工作可以安全地重复执行，且替代尝试仍能在调用方的截止时间内完成时，重试才是合理的。如果请求会触发工具、写入数据或开始用户可见的流，请先定义幂等性和重新启动语义。

对于因 429 驱动的排队或容量问题而表现为高延迟的情况，请将本节与 Flatkey 的RPM、TPM 和重试指南结合阅读。超时可能是过载准入控制的症状，而不是请求持续时间设置的问题。

预算警报：区分通知与强制执行

预算行为导致了不成比例数量的LiteLLM 常见错误，因为团队经常将三种不同的控制手段都归为“警报”。它们不可互换。

第一个预算检查：是否有数据库？

LiteLLM 当前的预算文档明确指出：其代理预算是根据从数据库读取的支出来强制执行的。在无数据库部署中，配置的全局 max_budget 不会作为可靠的支出上限；虚拟密钥、团队和用户预算行为同样依赖数据库。

这会导致一种常见的故障模式：团队设置了 max_budget，看到了启动警告或配置值，并假设生产流量会在达到阈值时停止。没有所需的支出跟踪设置，它不会成为可靠的控制措施。

# Illustrative policy only. Validate with a non-production key before rollout.
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  fail_closed_budget_enforcement: true

litellm_settings:
  max_budget: 100
  budget_duration: 30d

应将 fail_closed_budget_enforcement 视为一项可靠性决策，而不是可直接复制粘贴的修复方案。当前 LiteLLM 文档说明，当无法验证支出时，更严格的预算检查可能会拒绝请求；在广泛启用之前，请先针对你的部署测试数据库和 Redis 的故障行为。

测试预算路径，而不只是仪表板

在非生产环境中使用一次性密钥或团队，并验证以下顺序：

1. 确认代理可以读取和写入支出存储。
2. 在正确的范围内创建一个刻意设定得较小的硬预算：密钥、团队、用户、项目或终端用户。
3. 通过代理发送一个最小请求。
4. 发送第二个必须跨过阈值的请求。
5. 分别检查返回的异常、支出记录、重置窗口和告警渠道。
6. 确认应用程序能处理预算拦截，而不会将其当作瞬态提供商过载来重试。

LiteLLM 还记录了预算窗口和按模型设置的预算控制。请明确重置计划：每日防护措施和每月上限解决的是不同风险。

Azure 预算警报和 AWS 预算警报是后备措施，而非替代方案

次要关键词 Azure 预算警报 和 AWS 预算警报 很重要，因为云提供商的计费警报覆盖的是不同边界。它们可以针对提供商账户或订阅支出发出警告，包括绕过 LiteLLM 的流量。它们不能替代网关级别的决策，即当前是否应允许此请求、密钥、租户或模型进入。

适当时应同时使用这两个层级：

• LiteLLM 预算策略保护网关能够识别的路由和租户。
• Azure 预算警报或 AWS 预算警报监控上游云账户支出。
• 网关使用量账本会对两者进行核对，并暴露绕过预期路径的流量。

对于 OpenAI 支出，LiteLLM 的支出捕获率检查可以将跟踪到的支出与 OpenAI Organization Costs API 进行比较。它目前具有提供商特定的前提条件，因此在将其视为通用的多提供商核对功能之前，请阅读带版本的文档。

如果运营需求超出单个 LiteLLM 部署，请参阅统一 AI 计费仪表板评估指南，了解应围绕密钥、预算、分配、警报和核对提出的问题。

提供商故障：分别验证公开模型名称和上游部署

提供商故障是最明显的LiteLLM 常见错误，但它们通常是网关配置错误。客户端通常会调用你公开的 model_name。随后，LiteLLM 会将该名称解析为提供商模型、部署、端点、凭据和提供商特定参数。

model_list:
  - model_name: support-chat       # The name the client requests
    litellm_params:
      model: azure/<deployment-name>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

model_name 和 litellm_params.model 是刻意区分的不同概念。当客户端收到无效模型错误时，首先将确切请求的名称与 model_name 进行比较。LiteLLM 的模型管理文档区分了公开模型名称与提供商模型，并为已配置模型提供了连接测试工作流。

提供商故障决策表

异常类型应决定下一步操作。LiteLLM 的异常参考文档将 401、402、403、404、408、429、500 和 503 情况映射为标准化类别；它还会公开提供商特定字段，以便进行更深入的调查。

重试、回退与冷却：在不掩盖事故的情况下恢复

重试和回退可以减少可见的失败，但也可能将配置错误转化为延迟、成本或重复工作。良好的LiteLLM 常见错误处理方式，会对无效配置与短暂的提供商中断采用不同策略。

LiteLLM 记录了一种有用的划分方式：

• 重试会尝试在当前模型组内恢复。
• 回退会在配置的重试次数耗尽后转移到另一个模型组。
• 冷却会隔离发生故障的部署，同时让健康的替代方案保持可用。

以下是一个基于 LiteLLM 提供商故障转移指南的小型示例配置：

model_list:
  - model_name: primary-chat
    litellm_params:
      model: openai/<primary-model>
      api_key: os.environ/PRIMARY_PROVIDER_KEY

  - model_name: backup-chat
    litellm_params:
      model: azure/<backup-deployment>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

litellm_settings:
  num_retries: 1
  request_timeout: 30
  fallbacks: [{"primary-chat": ["backup-chat"]}]
  allowed_fails: 3
  cooldown_time: 30

仅使用有意触发的非生产提供商错误来验证此配置。LiteLLM 的文档警告说，较旧的模拟回退标志不会测试代理请求；真实且受控的故障才是验证代理的合适方式。

除非您已明确设计了单独的响应方式，否则不要将 404、身份验证、权限、架构和内容策略情况纳入通用重试循环。LiteLLM 的路由文档支持针对特定错误的重试策略，包括对 NotFoundError 设置零次重试；这可以避免无效模型名称演变为缓慢的事故。

启用跨提供商回退前，请验证产品契约：

• 上下文窗口行为和工具调用语义
• 结构化输出和响应格式支持
• 数据驻留、保留及客户策略要求
• 安全行为和内容策略预期
• 延迟与成本边界
• 下游副作用的幂等性

回退应在请求完成后可观测，而非悄无声息。LiteLLM 记录了支出日志元数据中的字段，例如已尝试的回退和原始模型组。请监控回退率、最终成功率、重试/回退增加的延迟，以及实际处理该请求的路由成本。

如需了解更广泛的路由设计，请参阅 Flatkey 的回退路由实践指南。同一条规则仍然适用：只有当替代方案仍符合工作流契约时，才进行路由。

适用于 LiteLLM 问题的事故就绪检查清单

在关闭事故或宣布某个LiteLLM 常见错误已修复之前，请执行此检查清单。

何时简化路由层面

有些团队选择 LiteLLM，是因为它能集中管理模型配置、使用情况和可靠性策略。另一些团队则希望减少需要运营的网关基础设施。正确答案取决于谁负责路由策略、提供商凭据、预算执行和事故响应闭环。

当应用需要在支持的模型路由之间提供兼容 OpenAI 的集成接口，同时将路由、使用情况审查和计费更紧密地整合在一起时，Flatkey 非常有用。它不会消除对超时、预算拦截或提供商错误进行分类的需求；它减少了应用需要维护的、针对不同提供商的客户端集成数量。当您想评估这种运营模式时，可从一个 API 密钥用于多个 AI 模型或Flatkey API 快速入门开始。

如需完整的设置演练和配置示例，请参阅我们的LiteLLM 代理指南。

常见问题

所有 LiteLLM 常见错误都可以安全重试吗？

不可以。身份验证、权限、无效模型、不支持的参数、预算以及大多数计费失败都需要修正配置或账户设置。仅重试明确的暂时性情况，并设置较小的尝试次数和时间预算，且仅在操作可以安全重复时进行重试。

为什么 max_budget 无法阻止我的 LiteLLM 代理中的支出？

首先确认代理具有预算强制执行所需的、由数据库支持的支出跟踪功能。然后确认流量会到达 LiteLLM，而不是直接调用提供商，并确认配置的密钥、团队、用户或项目正是实际发出请求的范围。LiteLLM 的预算文档解释了数据库要求和范围行为。

Azure 预算警报或 AWS 预算警报是否足以防止应用超支？

它们是有用的提供商账户兜底措施，但不会决定是否应接受某个特定网关请求。保留提供商计费警报，然后在已知请求上下文的位置增加经过测试的网关预算和应用级产品限制。

对于失败的 LiteLLM 调用，我应该保存哪些信息？

保存经脱敏处理的错误正文、标准化异常类、HTTP 状态、提供商名称、请求的模型、时间戳、环境、客户端尝试次数，以及可用时的 x-litellm-call-id。避免记录 API 密钥以及敏感的提示词/响应内容。

回退机制会掩盖错误配置吗？

会。回退可以让客户请求成功，同时主路由仍持续失败。因此，回退率、路由特定错误、最终模型组、延迟和成本都需要配置警报或仪表板。应将不断上升的回退率视为运营信号，而不是已经完成的修复。

最终要点

解决LiteLLM 常见错误的持久方法不是通用的重试次数或更长的超时时间，而是一套可重复执行的运营闭环：捕获实际故障、识别策略层、验证最小且安全的变更，并通过受控测试证明恢复路径。这样可以使超时保持可控、预算警报保持有效，并让提供商故障足够可见以便修复。

来源

• LiteLLM 异常映射
• LiteLLM 预算和速率限制
• LiteLLM 提供商故障转移和回退
• LiteLLM 路由、重试、冷却期和并发
• LiteLLM 生产环境最佳实践
• LiteLLM 日志记录
• LiteLLM 支出捕获率检查