05 · 症状倒推：看到 X 该查 Y¶
本文是运维入口——按你最先看到的"症状"分类，给出该往哪里查、可能是什么原因、紧不紧急、怎么处理。不重复前 4 篇的概念定义，重在给你下一步该执行的具体动作。
阅读路径建议： - 急性事件中：直接跳到 §9 Case Study，对号入座 - 平时熟悉：从 §1 症状分类 看起 - 想知道命令清单：§10 工具命令速查
1. 症状分类¶
按"谁先报警"切入：
flowchart TD
Sym{你先看到什么?}
Sym -->|"客户端报了 HTTP 错误"| C1["§2 按客户端 status_code"]
Sym -->|"客户端报了奇怪的 message"| C2["§3 按客户端 message 关键字"]
Sym -->|"Prometheus 某指标涨了"| C3["§4 按 Prometheus 指标"]
Sym -->|"PaaS / 容器日志告警"| C4["§5 按 proxy 日志关键字"]
Sym -->|"用户说 慢 / 卡住"| C5["§6 不是错但行为异常"]
Sym -->|"知道是某 provider 的问题"| C6["§7 按 provider 排查"]
Sym -->|"想做事前演练"| C7["§8 故障注入与验证"]
style Sym fill:#cef2. 按客户端 status_code¶
2.1 客户端报 400¶
| 子症状 | 可能原因 | 立即查 | 处理 |
|---|---|---|---|
error.message 含 litellm.BadRequestError: |
用户 payload 错（缺字段 / 类型错 / model 名错） |
看 message 后半的具体上游错 | 修客户端代码；不是 deployment 问题 |
error.message 含 litellm.ContextWindowExceededError: |
用户消息 + max_tokens 超模型 context | message 含 Model: xxx 看是哪个 model |
配 context_window_fallbacks 自动切大 context 模型；见 03 §6.1 |
error.message 含 litellm.ContentPolicyViolationError: |
上游内容审核拒绝 | message 含 <Provider>Exception 看是哪家拒了 |
配 content_policy_fallbacks 切到审核宽松的模型；或调整 prompt |
error.message 含 litellm.UnsupportedParamsError: |
客户端传了当前 provider 不支持的字段 | 看 message 提示的字段名 | 客户端去掉那个字段，或 drop_params: true 配置自动丢弃 |
error.message 含 litellm.LiteLLMUnknownProvider: |
model 字段写错（如 gtp-4 拼写错） |
看 message 里 model=xxx |
客户端修 |
error.code == "400" 但 message 含 403 字样 |
vertex_ai 字符串 "403" → BadRequestError 的已知坑 | 看是不是 vertex 模型 | 接受这个映射；实际是 403 权限问题 |
⚠️ 不要给 400 类告警配 PaaS L3 报警——用户错频率高，会淹掉真故障告警。
2.2 客户端报 401¶
| 子症状 | 可能原因 | 立即查 | 处理 |
|---|---|---|---|
message 含 litellm.AuthenticationError: |
上游 key 真的错 | 看 message 含 Model: xxx 找 deployment |
检查 deployment 的 api_key 是否过期；看 docs/cooldown/01-mechanism.md §3.4 路径 1.4（401 立即冷） |
message 含 Not allowed to access model due to tags configuration |
tag-based routing 拦截 | 看 03 §8.2 | 检查 key/team 的 tag 配置 |
| 客户端的 LiteLLM API key 本身错了 | proxy auth 层拦的，不是上游 401 | 看 proxy 日志 Invalid auth / Auth Error |
业务方更新 key |
| Master Key 错 | 调 management API 时常见 | 看 LITELLM_MASTER_KEY env |
配 / 重启 |
2.3 客户端报 403¶
| 子症状 | 可能原因 | 立即查 | 处理 |
|---|---|---|---|
message 含 litellm.PermissionDeniedError: |
上游 403——API key 没开通该模型/region | 看 message 找 deployment | 上游 console 检查 key 权限 |
| 403 在 vertex_ai 经常报成 400（§4.5） | 字符串 "403" 优先匹配走 BadRequestError | 看 message 是否含 vertex_ai | 是已知坑，实际还是权限问题 |
2.4 客户端报 404¶
| 子症状 | 可能原因 | 立即查 | 处理 |
|---|---|---|---|
message 含 litellm.NotFoundError: 且 Model: 是正常 model_group 名 |
上游说 deployment 不存在（model_id 错 / region 错） | 看 deployment 配置 | 修 deployment 的 model 字段 |
message 含 model_not_found |
OpenAI 风格的 404 | 同上 | 同上 |
error.code == "404" 但 model_group 完全不在 config 里 |
客户端请求的 model 你没配 | grep proxy_server_config.yaml 找 model_name |
加配置 / 改客户端 model 字段 |
2.5 客户端报 408¶
| 子症状 | 可能原因 | 处理 |
|---|---|---|
message 含 litellm.Timeout: |
LiteLLM httpx 客户端超时（本地） | 看 request_timeout 配置；上游可能慢 |
| 同时上游 504 高发 | 上游真的慢 | 上游服务方处理 |
| LiteLLM Retried: N times 且 N == num_retries | retry 全失败 | 看上游真实可用性；是否配 fallback 救援 |
2.6 客户端报 429¶
⚠️ 429 最容易误判——LiteLLM 有 3 个不同来源会返 429。
| 子症状 | 真实来源 | 立即查 | 处理 |
|---|---|---|---|
message 含 litellm.RateLimitError: + 上游 provider |
真上游限流 | message 含 Retry-After: N |
等退避；或加 deployment 分流 |
message 含 No deployments available for selected model |
所有 deployment 都在 cooldown（03 §8.1） | redis-cli KEYS 'deployment:*:cooldown' \| wc -l |
大量 deployment cooldown → 上游真挂；调 cooldown_time |
message 含 Deployment over user-defined ratelimit. |
你的 user/team/key 自己限流 | 看 LiteLLM_TeamTable / 用户级 rpm/tpm 配置 |
调用户额度 |
header x-litellm-attempted-retries: 0 |
retry 都没机会 → 是 cooldown 或限流前置拦 | 同上 | 同上 |
✅ 快速判定法：
2.7 客户端报 500¶
⚠️ 500 是最杂的——含 6 种来源。
| 子症状 | 真实来源 | 立即查 | 处理 |
|---|---|---|---|
message 含 litellm.InternalServerError: 且 provider 名清楚 |
上游真返 500 | 看 docs/cooldown/ | 等上游；或 fallback |
message 含 litellm.APIConnectionError: |
LiteLLM 这边连不上 上游 | 看本机 DNS / 网络 / 上游 host | 检查 proxy 容器网络 |
message 含 litellm.APIConnectionError: 但能 ping 通上游 |
provider 分支漏处理（02 §4 / §5） | 看是不是 cloudflare / vllm / nlp_cloud / 上游真返非常规 status | 改 02 §8 接入 checklist 加 status 处理 |
error.code = "500" 但 message 含上游 502 Bad Gateway |
历史 bug 或某 provider 没把 502 映射对 | 看 02-provider-mapping.md 矩阵；具体 provider 的 502 行号 | 修映射 |
message 含 litellm.APIResponseValidationError: |
上游 200 但响应格式错（schema 校验失败） | 看 message 里的 raw_response | 上游 SDK 异常 / 模型乱输出；可能是 structured output 的问题 |
| 内部代码崩 | 通常带 traceback |
看 proxy stdout traceback | 看 LiteLLM 自己 bug |
2.8 客户端报 502 / 503 / 504¶
| status | message 模板 | 处理 |
|---|---|---|
| 502 | litellm.BadGatewayError: |
上游网关挂；Router 应该已经 cooldown；看 fallback |
| 503 | litellm.ServiceUnavailableError: |
上游不可用；类似 502 |
| 503 (流式) | litellm.MidStreamFallbackError: |
流式中途断；保留 generated_content 给 fallback |
| 504 | litellm.Timeout: 或 litellm.APIError(status_code=504): |
上游 gateway timeout；类似 408 |
2.9 message 完全看不懂¶
如果你看到 error.message 是一串 traceback 或非 LiteLLM 前缀的字符串：
- 可能没经过
exception_type——看是不是 guardrail / proxy auth / DB 抛的 - grep proxy 日志找该 request_id（在 header
x-litellm-request-id） - 看 03 §8.3 的特殊错误
3. 按客户端 message 关键字¶
3.1 "No deployments available" / "No healthy deployment available"¶
最高频的"看起来像 429 其实不是" 错误。
立即诊断：
# 1. Redis 看 cooldown key 数量
redis-cli KEYS 'deployment:*:cooldown' | wc -l
# 2. 看具体哪些 deployment 在 cooldown
redis-cli KEYS 'deployment:*:cooldown'
# 3. 单个 key 看详情
redis-cli GET 'deployment:25a8bd00-...:cooldown'
# value 含 exception_received / status_code / cooldown_time
# 4. 看 proxy 日志最近 5 分钟有哪些 cooldown 触发
grep -E "cool_down|_set_cooldown" /var/log/litellm/proxy.log | tail -30
可能根因：
| 现象 | 根因 | 处理 |
|---|---|---|
| 多个 model_id 都在 cooldown | 上游真挂了 | 等恢复 / fallback / 扩 deployment |
| 大量 401 cooldown | API key 被吊销 / 过期 | 换 key 重启 |
| 大量 429 cooldown | 上游全局限流 | 加 region / 加 deployment / 减流量 |
| 单 deployment 反复 cooldown | 该 deployment 配错（model 名错 / region 错） | 看 deployment 配置 |
| 单 model_group 整体 cooldown | model_group 全部挂掉 | 配 fallbacks 切到别的 group |
3.2 "Trying to fallback b/w models" 反复出现¶
说明 fallback 链都在失败。看 04 §3.1 grep 关键词 找：
grep -E "Trying to fallback|Error occurred while trying to do fallbacks|No fallback model group found" /var/log/litellm/proxy.log
可能原因：
- fallback model_group 自己也挂了 → 看 03 §6 fallback 配置；fallback 是不是同一片故障域？
- max_fallbacks 太小 → 调大 ROUTER_MAX_FALLBACKS env
- ContextWindowExceededError 没配 context_window_fallbacks → 见 03 §6.1
3.3 "LiteLLM Retried: 0 times"¶
看到这个说明没有 retry 就抛了。可能：
- 异常 status_code 不在 _should_retry 白名单（4xx 非 408/429）
- should_retry_this_error 8 条特殊规则之一命中（看 03 §4）
- 当前 model_group 只有 1 个 deployment + AuthenticationError（规则 6）
- 没有健康 deployment（规则 7）
3.4 "Received Model Group=X. Available Model Group Fallbacks=Y"¶
LiteLLM 主动在 message 里挂的 fallback 提示。说明已经尝试过 fallback 但全失败，message 末尾告诉你配的 fallbacks 是什么。如果 Available Model Group Fallbacks=None，没配。
4. 按 Prometheus 指标¶
4.1 litellm_proxy_failed_requests_metric 涨¶
业务真受影响了——客户端最终没拿到 success。
排查顺序：
1. 看 exception_class label 区分异常类型
2. litellm_llm_api_failed_requests_metric 涨吗？
- 涨 → 上游真有故障，retry/fallback 没救回
- 不涨 → 是 proxy 层错（auth / guardrail / cooldown 拦的）
3. litellm_deployment_failure_responses 按 model_id 看是哪台
4. litellm_deployment_cooled_down 是不是同时涨 → 健康问题
PromQL 示例：
# 哪个异常类涨最快
topk(5, sum(rate(litellm_proxy_failed_requests_metric[5m])) by (exception_class))
# 哪个用户的请求失败最多
topk(10, sum(rate(litellm_proxy_failed_requests_metric[5m])) by (hashed_api_key, team_alias))
# 失败率
sum(rate(litellm_proxy_failed_requests_metric[5m])) by (requested_model)
/
sum(rate(litellm_proxy_total_requests_metric[5m])) by (requested_model)
4.2 litellm_llm_api_failed_requests_metric 涨但 proxy_failed 不涨¶
→ 健康信号。retry 和 fallback 救回了大部分故障。但仍说明上游不稳。
可以监控但不要 page。
4.3 litellm_deployment_cooled_down 涨¶
某 deployment 反复进 cooldown。结合：
# 哪些 deployment 在 flapping
topk(5, rate(litellm_deployment_cooled_down[10m])) by (litellm_model_name, model_id, exception_status)
exception_status 告诉你冷却的原因（401/429/5xx）。
4.4 litellm_deployment_failed_fallbacks 涨¶
fallback 链也炸了。说明你的 fallback model_group 配置可能有问题——切到的目标也挂了。
sum(rate(litellm_deployment_failed_fallbacks[5m])) by (requested_model, fallback_model, exception_class)
4.5 litellm_deployment_state == 2 (outage)¶
某 deployment 完全故障状态。一般跟 cooldown 同步——cooldown 触发时 gauge 被设。
5. 按 proxy 日志关键字¶
完整 grep 模板见 04 §3.1。
5.1 看到 "litellm.APIConnectionError"¶
最危险——可能掩盖了真正的 5xx：
看 message 后半。如果含上游 provider 名 + 5xx 字样（如 vllm / cloudflare），可能是 02 §4 描述的不一致 bug——provider 分支漏处理上游真实 5xx，落到全局兜底 → APIConnectionError。
处理： 1. 短期：监控告警把这个 provider 的 APIConnectionError 单独画一条 2. 长期：按 02 §8 接入新 provider 的最小 checklist 补全该 provider 分支
5.2 看到 "Error occurred while trying to do fallbacks"¶
fallback 内部失败。看 04 §3.3 样本 B。可能是：
- fallback model_group 没配
- fallback model_group 自己全 cooldown
- fallback 链超过 max_fallbacks 截断
5.3 看到 "Got 'XxxError'. No xxx_fallback set"¶
这是 Router 自己提示——告诉你当前异常类型本来有专用 fallback 配置可用，但你没配。
| 日志 | 该配什么 |
|---|---|
Got 'ContextWindowExceededError'. No context_window_fallback set |
context_window_fallbacks: [{model_group: [large_ctx_model]}] |
Got 'ContentPolicyViolationError'. No content_policy_fallback set |
content_policy_fallbacks: [{model_group: [other_provider_model]}] |
5.4 看到 traceback 但没有 LiteLLM 异常前缀¶
→ 异常没经过 exception_type 映射。可能：
- guardrail hook 抛的（04 §6 PaaS 告警字段 表里没列）
- proxy auth / DB / Redis 异常
- LiteLLM 自己 bug
查 traceback 顶端找抛出位置。
6. 不是错但行为异常¶
6.1 用户说"卡住，没响应"¶
可能：
1. 流式响应慢/断——litellm_llm_api_time_to_first_token_metric 看首 token 延迟
2. 整体超时——request_timeout 默认很大；上游真的慢
3. No deployments available 静默 retry——LiteLLM 重试 cooldown 时 _time_to_sleep_before_retry 按退避，可能等很久
# 看具体请求的 standard_logging_payload
psql -c "SELECT startTime, endTime, standard_logging_payload->>'status', standard_logging_payload->'error_information' FROM \"LiteLLM_SpendLogs\" WHERE request_id = '<id>'"
6.2 用户说"成功率很低但没看到错误"¶
可能 retry 救回了大部分失败，但每次都重试增加延迟 + 上游花钱：
# retry 比例
sum(rate(litellm_llm_api_failed_requests_metric[5m])) / sum(rate(litellm_proxy_total_requests_metric[5m]))
6.3 整体延迟突然变高¶
histogram_quantile(0.95, sum(rate(litellm_request_total_latency_metric_bucket[5m])) by (le, requested_model))
可能：
- 单 deployment 慢但 retry 救回 → 看 litellm_llm_api_latency_metric 按 model_id
- 大量 retry → 看 §6.2
- cooldown 太多导致 fallback 链长 → 看 §3.1
7. 按 provider 排查¶
| Provider | 已知坑 | 排查重点 |
|---|---|---|
vertex_ai / gemini |
字符串 "403" → BR；曾经 502 → APIConnectionError（2bee019 修复） | 看 GCP IAM；429 quota；project 配置 |
bedrock |
500 用 ServiceUnavailableError（02 §4.3） |
AWS credentials；region；模型 ARN |
sagemaker |
credentials 错被映射为 BR（02 §4.6） | endpoint 状态；IAM；instance type |
azure |
content policy 走 body.error.inner_error.code | api_version；deployment 名 vs model 名 |
cloudflare |
几乎裸奔，5xx → APIConnectionError（02 §4.1） | 单独监控；考虑加自定义映射 |
vllm |
只处理 status_code==0（02 §4.7） | 其它错全部 → APIConnectionError，cooldown 失效 |
nlp_cloud |
500/503 用 APIError、504 用 SU（02 §4.4） | 监控时按 exception_class 看；status_code 不准 |
cohere |
500 用 InternalServerError（02 §4.3） |
Connection error 走 RL（小坑） |
openai 系（58 个 provider 共用） |
完整度最高 | 看你具体接的是 moonshot/dashscope/groq 哪个，可能有 provider-specific 字段 |
8. 故障注入与验证¶
事前演练——主动制造异常，验证 cooldown / retry / fallback 配置是否生效。
8.1 验证 401 cooldown 路径¶
把某 deployment 的 api_key 改成无效值：
model_list:
- model_name: gemini-1.5-pro
litellm_params:
model: vertex_ai/gemini-1.5-pro
api_key: INVALID_TEST_KEY_DO_NOT_USE
发请求：
curl -X POST http://localhost:4000/v1/chat/completions \
-H "Authorization: Bearer $LITELLM_KEY" \
-d '{"model":"gemini-1.5-pro","messages":[{"role":"user","content":"hi"}]}'
预期：
- 客户端拿到 401（路径 1.4 立即 cooldown）
- redis-cli KEYS 'deployment:*:cooldown' 出现该 deployment_id
- 立即再请求 → 看 x-litellm-attempted-retries 看是否 retry 别的 deployment
8.2 验证 context_window_fallbacks¶
YAML 配：
发一个超 GPT-4o context 但 Gemini 能吃下的请求。预期客户端 200 OK，response header x-litellm-model-id 指向 Gemini deployment。
8.3 验证 502 → BadGatewayError → cooldown¶
用 toxiproxy / 简单的反向代理拦截上游响应改 502：
verify response: error.code == "502"
verify cooldown: redis-cli KEYS 'deployment:*:cooldown' 含目标 deployment_id
如果客户端拿到 500 而不是 502，可能是该 provider 分支没把 502 映射对，看 02 §4。
8.4 验证 mock exception¶
router.py:5201 _handle_mock_testing_rate_limit_error——LiteLLM 自带 mock 测试 hook。文档可能滞后；grep mock_testing_rate_limit_error 看用法。
9. Case Study：5 个真实场景全链路¶
Case 1：客户端报 429 但上游不限流¶
症状：用户报 error.code = "429"、message 含 "No deployments available"。
链路：
1. proxy 日志：No deployments available for selected model, Try again in 5 seconds. ... cooldown_list=[<23 个 model_id>]
2. Redis：redis-cli KEYS 'deployment:*:cooldown' | wc -l → 23
3. 看具体 cooldown 原因：
redis-cli GET 'deployment:<某 id>:cooldown'
# → {"exception_received": "...", "status_code": "401", ...}
api_key 真的全错了。Vault key 自动轮转，但 proxy 没拿到新 key。
5. 处理：重启 proxy 让它拉新 key；或热更 config。
预防：
- Prometheus 告警 litellm_deployment_cooled_down{exception_status="401"} 涨
- key 轮转后立即跑健康检查
Case 2：500 涨但找不到上游故障¶
症状：litellm_proxy_failed_requests_metric{exception_class="APIConnectionError"} 持续涨，上游 console 没看到异常。
链路：
1. grep litellm.APIConnectionError 找 message，发现是 cloudflare provider 的请求
2. 看 02 §4.1 cloudflare——cloudflare provider 分支几乎裸奔，任何 status_code 不是 400/401 之外的都 fall-through 到全局兜底 → APIConnectionError
3. 实际上 cloudflare workers ai 返了 524（Cloudflare 自家的 timeout），但分支没处理
4. 处理：按 02 §8 checklist 加 cloudflare 524 → Timeout 映射
5. 或临时：单独 Prometheus 告警 + Grafana panel 把 provider=cloudflare + APIConnectionError 拆出来
Case 3：fallback 链莫名其妙不生效¶
症状：配了 fallbacks: [{gpt-4o: [claude-3-sonnet]}]，gpt-4o 失败时客户端仍报 502。
链路：
1. 看 message 里有没有 Trying to fallback b/w models——没有
2. 看 should_retry_this_error 规则（03 §4）：
- 规则 5：RateLimitError + 无健康 + 有 fallback → raise（让 fallback 接手）——本次是 BadGatewayError，不触发
3. 看 retry 流程：502 进 _should_retry 返 True → retry 2 次还失败 → 应该进 fallback
4. 但 message 里 Available Model Group Fallbacks=None——说明 Router 拿不到 fallbacks
5. 根因：调用方传了 fallbacks=None 在 kwargs 里，覆盖了 Router 默认配置
6. 处理：客户端不传 fallbacks 字段，或 Router 配置用 default_fallbacks
Case 4：监控显示成功率高但用户抱怨延迟¶
症状：业务方说"明明 200 但等了 30 秒"。
链路：
1. 看 histogram_quantile(0.95, sum(rate(litellm_request_total_latency_metric_bucket[5m])) by (le)) → P95 = 32s
2. 看 litellm_llm_api_failed_requests_metric → 高（说明 retry 很多）
3. 看 metadata.attempted_retries 在 SLP 里 → 平均 3 次重试
4. 看 litellm_deployment_failure_responses{exception_class="Timeout"} → 涨
5. 根因：上游 deployment 真的慢（接近 timeout），LiteLLM 一直在 retry + 退避算
6. 处理：减少 num_retries 让失败更快返；或上游处理；或换 deployment
Case 5：某 deployment 反复 cooldown 又恢复¶
症状：litellm_deployment_cooled_down{model_id="xxx"} 每分钟涨 1-2 次。
链路：
1. redis-cli KEYS 'deployment:xxx:cooldown'——隔几秒能看到一次；TTL 5 秒
2. 看 cooldown value：status_code=429、exception_received 含 Quota exceeded
3. 根因：该 deployment quota 真的紧 + cooldown 默认 5 秒太短，5s 后 retry 又撞 quota → 又 cooldown → 循环
4. 处理：
- 临时：cooldown_time: 60 让它冷却久一点
- 长期：加 deployment 分流；或调整 litellm_settings.max_parallel_requests 限制本端发送速率
10. 工具命令速查¶
Redis（cooldown 相关）¶
# cooldown key 总数
redis-cli KEYS 'deployment:*:cooldown' | wc -l
# 看具体 key
redis-cli KEYS 'deployment:*:cooldown'
# 看某 key 的 value
redis-cli GET 'deployment:<id>:cooldown'
# 看某 key 的 TTL
redis-cli TTL 'deployment:<id>:cooldown'
# 手动清掉某 key（测试用,不要 prod 用）
redis-cli DEL 'deployment:<id>:cooldown'
# 看所有 deployment 失败计数（V1 模式 InMemoryCache 不在 Redis,只能看 V2 路径 4 的）
redis-cli KEYS 'deployment:*:fails'
PostgreSQL（SLP / SpendLogs）¶
-- 最近 1 小时失败请求 + 异常类
SELECT
"request_id",
"model",
standard_logging_payload->'error_information'->>'error_class' AS exc_class,
standard_logging_payload->'error_information'->>'error_code' AS code,
"startTime"
FROM "LiteLLM_SpendLogs"
WHERE
standard_logging_payload->>'status' = 'failure'
AND "startTime" > NOW() - INTERVAL '1 hour'
ORDER BY "startTime" DESC
LIMIT 50;
-- 按异常类聚合
SELECT
standard_logging_payload->'error_information'->>'error_class' AS exc_class,
COUNT(*) AS n
FROM "LiteLLM_SpendLogs"
WHERE standard_logging_payload->>'status' = 'failure'
AND "startTime" > NOW() - INTERVAL '1 hour'
GROUP BY 1 ORDER BY n DESC;
-- 看某 deployment 在某时间段的失败率
SELECT
standard_logging_payload->>'model_id' AS model_id,
COUNT(*) FILTER (WHERE standard_logging_payload->>'status' = 'failure') AS failures,
COUNT(*) AS total
FROM "LiteLLM_SpendLogs"
WHERE "startTime" > NOW() - INTERVAL '15 minutes'
GROUP BY 1;
Prometheus / PromQL¶
# 失败率（按 model_group）
sum(rate(litellm_proxy_failed_requests_metric[5m])) by (requested_model)
/
sum(rate(litellm_proxy_total_requests_metric[5m])) by (requested_model)
# 哪些 deployment 正在 cooldown
sum(litellm_deployment_state) by (litellm_model_name, model_id)
# 值 = 2 表示完全 outage,1 表示 partial
# 上游故障 vs 客户端故障
(sum(rate(litellm_llm_api_failed_requests_metric[5m]))
-
sum(rate(litellm_proxy_failed_requests_metric[5m])))
# 值 = 被 retry/fallback 救回的次数
# fallback 成功比
sum(rate(litellm_deployment_successful_fallbacks[5m]))
/
(sum(rate(litellm_deployment_successful_fallbacks[5m])) + sum(rate(litellm_deployment_failed_fallbacks[5m])))
Proxy 日志 grep¶
# 所有 LiteLLM 异常
grep -E 'litellm\.\w+Error:' /var/log/litellm/proxy.log
# 只看 5xx 相关
grep -E 'litellm\.(InternalServerError|ServiceUnavailableError|BadGatewayError):' /var/log/litellm/proxy.log
# APIConnectionError 单独看（最容易掩盖真错）
grep 'litellm.APIConnectionError' /var/log/litellm/proxy.log | head -50
# fallback 链
grep -E 'Trying to fallback|No fallback model group|Error occurred while trying to do fallbacks' /var/log/litellm/proxy.log
# cooldown 触发
grep -iE 'cool.?down' /var/log/litellm/proxy.log | grep -v 'cooldown_list='
# 按 request_id 查全链路
REQID="<header x-litellm-request-id>"
grep "$REQID" /var/log/litellm/proxy.log
客户端验证¶
# 强制 401 测试 cooldown
curl -X POST http://localhost:4000/v1/chat/completions \
-H "Authorization: Bearer INVALID_KEY" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}]}' \
-i 2>&1 | grep -iE 'x-litellm|status|error'
# 看 response header
curl -X POST http://localhost:4000/v1/chat/completions \
-H "Authorization: Bearer $K" \
-d '...' \
-o response.json -D headers.txt
grep x-litellm headers.txt
11. 推荐处置流程（运维 SOP 草稿）¶
flowchart TD
Alert["告警触发<br/>(PaaS / Prometheus)"]
Triage{先看症状}
Triage -->|"4xx 涨"| BR["看 [§2.1-2.6]<br/>多数是用户错<br/>不紧急"]
Triage -->|"5xx 涨"| Five["看 §2.7"]
Triage -->|"429 涨"| RL{"x-litellm-attempted-retries?"}
RL -->|"= 0"| ND["看 §3.1<br/>cooldown 风暴"]
RL -->|"> 0"| TrueRL["真上游限流<br/>看上游 console"]
Five --> Conn{"是 APIConnectionError 吗?"}
Conn -->|是| MapBug["看 §5.1<br/>可能是映射坑"]
Conn -->|否| TrueDown["上游真挂<br/>看 cooldown 是否生效"]
BR --> Done
TrueRL --> Done
ND --> Cooldown["看 docs/cooldown/<br/>调 cooldown_time"]
MapBug --> Fix["补全 provider 映射<br/>看 02-provider-mapping §8"]
TrueDown --> FB{"配了 fallback 吗?"}
FB -->|是| WatchFB["看 litellm_deployment_failed_fallbacks"]
FB -->|否| AddFB["立即加 fallbacks<br/>看 03 §6"]
Done["归档 / 总结"]
Cooldown --> Done
Fix --> Done
WatchFB --> Done
AddFB --> Done
style Alert fill:#fdd
style Done fill:#dfd文档系列回顾¶
走到这里，整个 LiteLLM 错误体系已经全覆盖：
| 文件 | 解决什么 |
|---|---|
| README.md | 入口、整体观 |
| 01-exception-catalog.md | 看到一个异常类名，它是什么 |
| 02-provider-mapping.md | 不同上游怎么映射成 LiteLLM 异常；跨 provider 不一致 |
| 03-router-behavior.md | Router 接到异常会做什么（retry / fallback） |
| 04-where-to-see.md | 客户端 / 日志 / 监控分别看到什么 |
| 05-troubleshooting-by-symptom.md | 从症状反查根因（本文） |
互补文档： - docs/cooldown/ — cooldown 机制本身的实现细节 - docs/health-check/（如有）— 心跳机制（跟 cooldown 解耦）
EOF