LiteLLM 故障排除指南：10 分钟定位 90% 调用报错的完整排查流程

LiteLLM 故障排除指南10 分钟定位 90% 调用报错的完整排查流程【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm调用模型突然报错先别慌。照下面的顺序走先看错误速查表定位类型再开 DEBUG 日志拿证据最后按对应路径处置。LiteLLM 以统一 OpenAI 格式调用 100 LLM API排错时最值钱的信息是——异常对象本身会告诉你llm_provider和model等于自带了一半答案。先对症状LiteLLM 报错速查表错误类型典型表现message 特征一句话处置参考路径AuthenticationError401 /Invalid API key先核对环境变量与 key 格式再看模型是否开通litellm/exceptions.pyNotFoundError404 / 模型名不存在对照支持列表改模型名检查 provider 前缀litellm/llms/Timeout读/写超时无响应体调大request_timeout读litellm_debug_info看卡点litellm/exceptions.pyRateLimitError429 / RPM、TPM 超限配num_retries或用 Router 多部署分流litellm/router.pyContextWindowExceededErrorprompt 超出最大上下文截断历史对话或换长上下文模型litellm/exceptions.pyServiceUnavailableError503 / 上游过载属临时故障靠重试 fallback 模型兜底litellm/exceptions.py一行命令开启详细日志LITELLM_LOGDEBUG拿到报错先开调试再猜原因。老参数litellm.set_verbose已弃用标准做法是设环境变量# 全局开启 DEBUG 日志代理进程同样生效 export LITELLM_LOGDEBUG开完后每次调用都会打印请求参数、响应头和 provider 侧的原始错误401/404 类问题基本一眼定位。另一个高频开关是LITELLM_DETAILED_TIMINGtrue它把各阶段耗时拆开打印超时问题卡在连接还是卡在读响应不用再猜。另外记住litellm 的异常全部继承自 openai 对应异常类型openai.AuthenticationError等你现有的except openai.APIError捕获逻辑可以直接复用异常实例上还挂着llm_provider、model、response三个字段排查时优先看这三个。认证失败 3 分钟排查法401 到底是谁拒的现象AuthenticationError: Invalid API key。第一步看异常的llm_provider字段确认 401 来自哪个上游。字段值和你的预期对不上比如配了 bedrock 却报 openai说明 deployment 的 provider 前缀写错先改配置再谈密钥。第二步验证 key 真的被读到、格式没被污染import os raw os.environ.get(OPENAI_API_KEY, ) print(len(raw), raw[:4], raw[-4:]) # 长度、首尾片段都对得上才谈key 无效多一个空格也是 401第三步确认账号已开通目标模型。不少 provider 要单独启用模型或权限位key 本身完全正常。排查顺序记牢报错方 → 环境变量值 → 模型开通状态 → 最后才换 key。超时与限流别硬重试timeout 和 429 的正确姿势Timeout异常带litellm_debug_info字段直接指出卡在哪一步别只盯着网络问题四个字。处置上给全局request_timeout留出真实延迟余量import litellm from litellm import Router litellm.request_timeout 60 # 慢模型长推理、流式单独放宽 litellm.num_retries 2 # 同部署内自动重试 # 429 和超时的根治方案多部署分流 跨模型兜底 router Router( model_list[ {model_name: glm-4.5, litellm_params: {model: openai/glm-4.5, api_base: https://a.example/v1}}, {model_name: glm-4.5, litellm_params: {model: openai/glm-4.5, api_base: https://b.example/v1}}, ], num_retries2, fallbacks[{glm-4.5: [deepseek-chat]}], )⚠️ 特别注意 429RateLimitError是统一限流异常上游 provider、vendor 批量端点、litellm 代理自己的限流器并发、动态速率、预算都会抛它。拿到 429 先看 message 判断是谁限的流别一上来就降调用量——如果是代理侧预算触发降速解决不了问题。代理模式排障Router 多部署与 fallback 怎么查代理模式下每次请求都经过 Router 做部署选择和故障切换单点 429/超时不会直接失败这既是好事也让日志更难读。建议按这三步走打开代理审计日志确认这次请求尝试了哪些 deployment、在哪一步失败、fallback 有没有触发对照代理配置确认目标模型注册了至少 2 个 deployment新增模型时确认它已写进 model_prices_and_context_window.json否则成本记为 0 或校验报错——这类不报 500 但行为不对的问题最容易被忽略。监控侧把 Prometheus 或 OpenTelemetry 回调接上限流和 5xx 趋势提前暴露不用等工单。接入实现都在 litellm/integrations/ 目录下按名字找即可。上线前自查清单照着勾出错时有据可查✅ API key 走环境变量注入本地脚本里打印过长度和首尾片段✅ 模型名与上游控制台完全一致provider 前缀正确✅request_timeout按最慢模型的真实延迟设置过不是默认值✅ 限流RPM/TPM配置与实际调用量核对过代理侧限流器阈值不是默认值✅ 代理模式至少 2 个同模型 deploymentfallbacks配了跨模型兜底✅ 审计日志能看到完整请求轨迹deployment、失败步、fallback 触发✅ 监控回调Prometheus / OTEL已接入429 与 5xx 有告警✅ 排障时LITELLM_LOGDEBUG能随时打开且不把 key 打进日志按这个顺序查绝大多数线上报错 10 分钟内能定位到根因剩下的疑难杂症把 DEBUG 日志带上再研究比对着空报错猜快得多。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考