[Bug]: Built-in LLM Passthrough Routes Fail with SERVER_ROOT_PATH

问题场景

用户在 LiteLLM Proxy 上设置了 SERVER_ROOT_PATH（例如 /litellm），并通过反向代理访问。反向代理按 ASGI 规范保留完整路径前缀转发请求，即客户端请求 /litellm/vertex_ai/v1/... 时，代理原样转发该完整路径。此时 LiteLLM 的内置 LLM passthrough 路由全部返回 404，而 /v1/chat/completions、/health、/ui 等端点正常。

报错原文

{"detail": "Pass-through endpoint v1/projects/.../models/...:generateContent not found. This could have been deleted or not yet added to the proxy."}

原因分析

Starlette 在路由匹配前会在内部就地修改 scope["path"]，把 root_path 前缀剥离，使得普通路由能够正确匹配。但 LiteLLM 的内置 passthrough 路由在实现中并未使用这个已被 Starlette 剥离后的路径，而是仍然基于原始完整路径去找 passthrough 端点，导致查找失败并返回 404。

换句话说，普通路由依赖 Starlette 的 scope["path"] 修改结果，passthrough 路由却绕过了该修改，两者对 root_path 的处理不一致。这是 LiteLLM 内部实现问题，不是用户配置错误，也不是反向代理的锅——反向代理保留前缀才是 ASGI 规范下的正确行为，LiteLLM UI 也依赖这一行为。

环境排查

• 确认 LiteLLM 版本：Issue 评论指出问题在 v1.103.0 仍存在，需确认是否已包含 fix/server-root-path-passthrough 的合并。
• 确认反向代理配置：是否保留了 SERVER_ROOT_PATH 前缀（保留是正确行为，不要改成剥离）。
• 确认 SERVER_ROOT_PATH 的实际取值，以及请求 URL 中的前缀是否与之完全一致。
• 确认是否曾应用 PR #19467（移除了 root_path=server_root_path）：该变更已被 PR #19790 回滚以修复 UI，若当前代码仍处于回滚前状态，需一并检查。
• Issue 未提供 Python、CUDA、PyTorch、显卡等信息，无需确认这些项目。

解决步骤

1. 先确认当前 LiteLLM 版本，如果低于包含 fix/server-root-path-passthrough 修复的版本，升级到已合并该修复的版本。若升级后仍复现，说明该修复未覆盖你的版本或未生效。
2. 如果无法直接升级，可参考 Issue 中给出的对比分支 umut-polat:fix/server-root-path-passthrough，将其合并到本地部署分支后重新构建镜像（此步骤属于社区修复方案，需自行验证）。
3. 不要在反向代理侧通过剥离前缀来“绕过”问题。Issue 明确说明剥离前缀会破坏 LiteLLM UI，并曾引发事故。
4. 如果线上已被迫用剥离前缀临时恢复，应及时改回保留前缀，并等待/应用 LiteLLM 侧的正式修复，避免 UI 再次失效。

验证方法

在保留路径前缀转发的前提下，向设置 SERVER_ROOT_PATH 后的 passthrough 路由发起请求，例如 /litellm/vertex_ai/v1/...，确认不再返回 Pass-through endpoint ... not found，而是进入对应上游 provider 的调用逻辑。同时确认 /ui 仍能正常访问，避免修复 passthrough 时把 UI 弄坏。

参考来源

BerriAI/litellm #22272

AI 工具推荐

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

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

了解 GamsGo AI

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