[Bug]: Vertex AI models show as “Unhealthy” in Model Health Status dashboard since v1.84.0

问题场景

用户将 LiteLLM Proxy 从 v1.83.10 升级到 v1.84.0 或更高版本后，在 Model Health Status dashboard 中看到 Vertex AI 模型被标记为 “Unhealthy”。但在单个模型详情页点击 “Test Connection” 能成功，客户端 chatbot 也能正常调用模型。该问题同样出现在 Microsoft Foundry、OpenAI、Amazon 以及 vLLM 部署的模型上。

报错原文

[Bug]: Vertex AI models show as "Unhealthy" in Model Health Status dashboard since v1.84.0

{"healthy_endpoints":[],"unhealthy_endpoints":[],"healthy_count":0,"unhealthy_count":0}

INFO:     [IP Address]:45718 - "GET /health?model_id=[Model ID] HTTP/1.1" 503 Service Unavailable

原因分析

维护者在调查后确认了根因：在 v1.84.0 中，health_endpoint 会使用 user_api_key_dict.models 过滤 _llm_model_list。当 API key 携带 all-proxy-models / all-team-models 这类 sentinel，或者携带 access-group 名称时，这些值无法匹配任何真实的 model_name，过滤结果变为 []，最终响应就是 {"healthy_count": 0, "unhealthy_count": 0}。关键判断点是两个计数都为 0：如果是健康检查实际执行后失败，unhealthy_endpoints 应当有内容，而不是空数组。维护者表示 staging 已通过 restrict_to_allowed_models 部分修复 sentinel 情况，剩余缺口是 access groups。评论中提到的 empty API key / Malformed API Key 报错，维护者判断为另一个独立的 k8s probe 问题，即探针打到需要认证的 /health，而不是公开的 /health/liveliness。

环境排查

• 确认 LiteLLM Proxy 版本：Issue 中 v1.84.0、v1.85.0、v1.86.0、v1.86.2 均报告受影响，v1.83.10 正常。
• 确认触发模型访问的 API key 是否带有 all-proxy-models、all-team-models sentinel，或 access-group 名称。
• 确认 config.yaml 的 general_settings 中是否配置了 background_health_checks 与 health_check_interval；v1.83.10 未配置也可正常工作。
• 检查健康检查接口返回的 JSON，重点看 healthy_count 与 unhealthy_count 是否同时为 0。
• 如果使用 OpenShift 或最新 Helm chart，另行检查是否存在约每 30 秒一次的 empty API key / Malformed API Key 日志；维护者认为这是独立的 k8s probe 配置问题。
• Issue 未提供操作系统、Python、CUDA、显卡、PyTorch 等版本信息，无需强行核对。

解决步骤

1. 先确认问题现象：访问 Model Health Status dashboard，确认返回的 JSON 是否为 {"healthy_endpoints":[],"unhealthy_endpoints":[],"healthy_count":0,"unhealthy_count":0}；同时点击单个模型的 “Test Connection” 验证模型实际可用。
2. 检查 LiteLLM 版本是否位于 v1.84.0 及以上的受影响范围。如果业务允许，可暂时回退到 v1.83.10 规避；Issue 中有用户表示仍在 v1.83.10 上运行。
3. 如果已经启用或打算启用背景健康检查，可在 config.yaml 的 general_settings 中加入并调整：

general_settings:
  background_health_checks: true
  health_check_interval: 300

4. 为控制背景健康检查的 token 消耗，可参考 Issue 中用户配置的环境变量 BACKGROUND_HEALTH_CHECK_MAX_TOKENS = "16" 与 BACKGROUND_HEALTH_CHECK_MAX_TOKENS_REASONING = "500"。Issue 中另有用户反馈，即使设置这些变量，问题仍然存在。
5. 如果不想承担背景健康检查可能带来的费用，可移除 background_health_checks，并等待官方修复。注意：重新运行健康检查也可能失败。
6. 如果是 OpenShift 等环境中的 empty API key 日志，应检查 k8s 探针是否打到了需要认证的 /health，而应改为公开的 /health/liveliness。该问题与本 Issue 的健康状态计数问题分开处理。
7. 关注维护者提到的修复：基于 staging 分支的小修复与回归测试，覆盖 access group 场景。在修复发布前，不要仅凭 dashboard 显示 “Unhealthy” 就认定模型不可用。

验证方法

完成配置调整后，重新打开 Model Health Status dashboard，确认返回中的 healthy_count 不再为 0，并且模型不再显示 “Unhealthy”。同时再次点击模型详情页的 “Test Connection”，确认模型实际调用成功。如果使用背景健康检查，需要等待一个 health_check_interval 周期后再观察状态是否更新。Issue 中提到 “re-run health check also fails”，因此如果重新检查仍失败，说明当前绕过配置未生效，应等待官方修复。

参考来源

BerriAI/litellm #28206

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。