拆解 LiteLLM，统一 API 背后的控制面

7 月 3 日下午，我打开 LiteLLM 仓库的时候，第一眼看到的不是那句「100+ LLMs」。

是 52,492 个 star，9,419 个 fork，还有默认分支 litellm_internal_staging 上当天 07:48 UTC 的 push。

这个信号挺强。

一个只做「统一 API」的 Python 包，很难长成这个规模。因为统一 API 这件事，听起来性感，落地却很苦。OpenAI、Anthropic、Gemini、Bedrock、Azure、Vertex AI，每家都有自己的鉴权、字段、错误、流式返回、工具调用、缓存计费和奇怪边角。

你想想看，一个团队如果只是偶尔调一下模型，直接用官方 SDK 就好了。为什么还要在中间加一层 gateway？

答案藏在 LiteLLM 的源码里。

它真正解决的不是「怎么少写几行 SDK 代码」，而是「当公司里所有 Agent、应用和自动化脚本都开始调用模型时，谁来管路由、预算、失败、审计和供应链风险」。

这才是 LiteLLM 的第一性原理。

先别把它当 SDK

LiteLLM 的 README 给了一个很漂亮的定位，它是一个开源 AI Gateway，可以用 OpenAI 格式调用 100+ LLM providers，也可以直接作为 Python SDK 使用。

这个说法没错，但有点太温和。

我更愿意把它看成一个「LLM 控制面」。数据面是一次具体的模型请求，控制面决定这次请求能不能发、发给谁、失败后怎么退、花了多少钱、日志写到哪里、谁来负责。

ARCHITECTURE.md 写得很直白，proxy 接住 OpenAI SDK、Anthropic SDK 或普通 HTTP client 的请求，然后把它交给 LiteLLM SDK，再去打真实 provider。AI Gateway 这一层负责 authentication、rate limiting、budgets 和 routing，SDK 这一层负责 provider calls、request/response transformations 和 streaming。

所以它不是一条简单的转发管道。

它是一张闸门。

这张闸门大概分三层。

第一层是 litellm/proxy/，这里管 API key、JWT、OAuth、virtual key、team、user、budget、spend log。litellm/proxy/auth/user_api_key_auth.py 开头就把职责写清楚了，它检查用户传给 LiteLLM Proxy 的 API Key，返回 UserAPIKeyAuth。文件里能看到它同时处理 OpenAI 的 Authorization header、Azure 的 API-Key header、Anthropic 和 Google AI Studio 的专用 header。

第二层是 litellm/router.py，这里管 model list、fallback、cooldown、routing strategy、Redis cache、deployment health。这个文件太长了，但看 Router.__init__ 的参数就能明白它在做什么，fallbacks、context_window_fallbacks、content_policy_fallbacks、allowed_fails、cooldown_time、routing_strategy、provider_budget_config 全在这里收口。

第三层是 provider translation。litellm/llms/custom_httpx/llm_http_handler.py 的 completion 方法是一个很好的入口，它先通过 ProviderConfigManager.get_provider_chat_config 找到 provider config，再调用 validate_environment、get_complete_url、transform_request、sign_request，然后把响应交给 transform_response。

这几个函数名连起来，其实就是 LiteLLM 的骨架。

先识别你要去哪家，再把 OpenAI 口径翻译成那家的口径，打出去，拿回来，再翻译成统一响应。

真正麻烦的是「翻译」

很多人第一次看 LiteLLM，会觉得它就是把 model='anthropic/claude-sonnet-4-20250514' 这种前缀拆一下。

其实吧，这只是入口。

litellm/litellm_core_utils/get_llm_provider_logic.py 里的 get_llm_provider 负责把 model name、custom provider、api base、dynamic api key 这些线索拼起来。这里有一个很有意思的安全注释，早期如果用简单的 endpoint in api_base 判断 provider，攻击者可以构造 https://attacker.com/api.groq.com/openai/v1 这类地址，诱导 proxy 把服务器环境变量里的 GROQ key 发到攻击者域名。

现在代码用 _endpoint_matches_api_base 解析 hostname 和 path，要求 hostname 精确匹配，path 也要按 segment 边界匹配。

这个细节很小。

但它说明 LiteLLM 已经不是「能调用模型」的问题了。它站在网关位置，手里握着一堆 provider key，任何 provider 识别逻辑都可能变成凭证外泄风险。

再往下看，provider translation 更像一组插件。litellm/llms/base_llm/chat/transformation.py 定义了 BaseConfig，强制子类实现 get_supported_openai_params、map_openai_params、validate_environment、transform_request、transform_response 等方法。具体 provider 的文件在 litellm/llms/{provider}/chat/transformation.py 下面展开。

我数了一下，provider_endpoints_support.json 现在有 169 个 provider slug。README 说 100+，源码里实际已经比这个更夸张。

这就解释了为什么 LiteLLM 会越来越像基础设施。provider 越多，统一 API 越不是「写一个 if else」能解决的事。每家 provider 都会在参数、鉴权、流式、错误码、工具调用、结构化输出上有一堆例外。

LiteLLM 做的选择是，把例外封进 provider config。

这样上层只看 OpenAI 形状，下层各自做脏活。

Router 是它从库变成网关的地方

如果只看 Python SDK，LiteLLM 当然有价值，但这个价值没有那么难替代。

真正让我觉得它值得拆的，是 router。

litellm/router.py 的 Router.__init__ 支持 7 种 routing strategy，simple-shuffle、least-busy、usage-based-routing、latency-based-routing、cost-based-routing、usage-based-routing-v2 和 lar1。它还维护 model_name_to_deployment_indices、team_model_to_deployment_indices、deployment_latency_map、failed_calls、cooldown_cache、health_state_cache。

这不是 SDK 代码的味道。

这是生产系统的味道。

你在公司内部接一个 OpenAI 兼容 endpoint，真正要担心的不是一次调用能不能成功。你要担心的是，某个 Azure deployment 今天抽风，某个模型上下文不够，某个 provider 预算烧穿，某个团队突然把请求打爆，某个 fallback 把安全策略绕过去。

LiteLLM 的 router 把这些问题放到同一个对象里。

async_function_with_fallbacks 的实现很能说明它的思路。正常情况下，它先跑 async_function_with_retries，成功后给响应加 fallback header，失败后才进入 async_function_with_fallbacks_common_utils。它不是简单重试，而是把普通 fallback、context window fallback、content policy fallback 分开处理。

这个区分很关键。

上下文超长，不应该和 provider 500 用同一种退路。内容策略触发，也不应该被普通 fallback 随便吞掉。你要的是「按失败类型选择下一步」，不是「坏了就换一个模型试试」。

说真的，这就是 LLM 网关最容易被低估的地方。调用模型的代码只有一行，但这一行背后需要一套调度系统。

钱不是日志字段，是路由条件

LiteLLM 还有一块很实用的设计，预算不是调用结束后才看的报表，而是调用前会影响路由的条件。

litellm/router_strategy/budget_limiter.py 里有个 RouterBudgetLimiting。文件注释说得很直接，它是一个 filter，接收 healthy deployments，然后过滤掉已经超过 budget limit 的 deployment。它可以和 weighted pick、lowest latency、simple shuffle 这些策略一起用。

这句话背后的工程含义挺重。

大部分团队一开始做 LLM 成本治理，会先做日志。每次请求花多少钱，记到数据库里，月底看账单。

但日志是事后系统。

如果一个 Agent 写坏了循环，或者某个用户把昂贵模型当 cheap model 用，事后日志只能告诉你已经烧了多少钱。LiteLLM 的做法是把 provider budget、deployment budget、request tag budget 都放进 pre-call filter。_filter_out_deployments_above_budget 会检查 provider_spend、deployment_spend、tag spend，超过就跳过。

换个角度看，成本在这里变成了路由输入。

这很务实。

而且它没有把所有写库操作塞进请求主路径。litellm/proxy/db/db_spend_update_writer.py 的 DBSpendUpdateWriter 负责把 spend increment 写进内存队列或 Redis，再从 Redis 或内存队列提交到数据库。update_database 会构造 spend log payload，然后用 asyncio.create_task 跑批量更新。

源码注释里还有一句很扎眼的话，直接写着不用 Redis buffer 的路径在 1K RPS+ 生产环境会造成 deadlocks，建议高并发时走 Redis 再提交 DB。

这不是宣传文案。

这是踩过坑的人写出来的代码。

和同类方案比，它更像「企业内网入口」

如果只想找一个统一模型入口，OpenRouter 很顺手。它像托管模型市场，把不同模型聚到一个 API 里。

如果你更关心观测和调试，Helicone 这类工具更像 LLM observability 层，日志、trace、成本、调试体验会是重点。

Portkey 也在做 AI Gateway，而且产品形态更完整，控制台、guardrail、缓存、实验这些能力都很清楚。

LiteLLM 的特别之处在于，它把开源自托管这件事做得很深。你可以把它放进自己的网络边界，让它接住内部团队的所有模型调用，再用 config、DB、Redis 和 proxy hooks 控制模型、预算、路由和审计。

简单对比一下。

坦白讲，LiteLLM 的优势不是 UI 最漂亮，也不是概念最轻。

它的优势是你能读到它怎么处理那些脏活。

但别把它当成无成本银弹

LiteLLM 的边界也很清楚。

第一个边界是复杂度。你把它放进调用链以后，provider 出错、LiteLLM 翻译出错、router 选错、预算过滤、缓存命中、DB 写入延迟，都可能影响一次请求。它帮你统一了入口，但也增加了一个需要自己运维的中间层。

第二个边界是信任。get_llm_provider_logic.py 那段 api base 匹配修复说明，gateway 持有 provider key，本身就是高价值攻击面。再加上 2025 年 open issue 里还有一个高评论安全事件，标题是 litellm PyPI package v1.82.7 + v1.82.8 compromised，这类供应链事故会让任何准备把它放进生产链路的团队多想几秒。

不是说不能用。

是要按基础设施的标准用。

第三个边界是 license。根目录 LICENSE 写着，enterprise/ 之外的内容按 MIT license 提供，但 enterprise/README.md 和 enterprise/LICENSE.md 明确写了 enterprise 目录是商业许可，生产使用需要有效的 Enterprise license。GitHub API 对这个仓库返回的 license 是 NOASSERTION，原因也在这里。

所以如果你只用开源 proxy 和 SDK，问题不大。如果你依赖 enterprise 目录下的 SSO、项目标签、route disable、企业回调控制这些能力，就不能只看根目录 MIT。

还有一个文档层面的提醒。README 里写了 8ms P95 latency at 1k RPS，并链接到 benchmark。这个数字可以作为参考，但我不会把它当成任何部署的性能承诺。因为 LiteLLM 的真实延迟取决于你启用的 auth、DB、Redis、logging、guardrail、router 策略和 provider 本身。

老实说，网关性能从来不是一个数字。

它是一组开关。

最值得偷走的，是 Control Plane Pattern

我看完 LiteLLM 以后，最大的收获不是「下次要不要用它」。

而是一个可以迁移的模式，我叫它 Control Plane Pattern。

当一个能力从单点工具变成组织级基础设施时，不要只封装调用 API。你要把它拆成三层。

入口层，统一鉴权、身份、租户和请求格式。

调度层，处理路由、fallback、预算、冷却、健康检查。

适配层，把统一语义翻译成具体 vendor 的协议，再把 vendor 响应翻译回来。

LiteLLM 把这三层都做进了代码里。proxy 是入口，router 是调度，llms/{provider}/transformation.py 是适配。

这个结构很朴素，但很能打。

如果你的团队现在只有两三个模型调用点，直接用官方 SDK 就够了，别急着上 gateway。多一个中间层，就多一份运维账。

但如果你已经有十几个 Agent、多个业务线、几套 provider key、不同团队预算，还希望一处切换模型、一处看日志、一处限制成本，那 LiteLLM 就不只是一个库了。

它更像 AI 应用进入生产以后，迟早会补上的那块控制面。

我一直觉得，AI 工程的难点正在从「模型能不能回答」转向「一群模型调用能不能被管理」。

LiteLLM 押的就是这个转向。

这也是它为什么会从一个 Python SDK，长成一个 52k star 的 AI Gateway。