LiteLLM 概念原理版本LiteLLM 1.50 |作者Pozicaiman |日期2026-07-27定位统一 LLM API 网关与 SDK以 OpenAI 兼容格式调用 100 大模型提供商关键词LLM Proxy、统一 API、路由网关、成本追踪、负载均衡适用版本Python 3.8 / LiteLLM 1.50一、什么是 LiteLLMLiteLLM 是一个开源的统一 LLM API 网关与 SDK它以 OpenAI 兼容的标准格式屏蔽底层各提供商接口差异让开发者用一套代码即可调用 100 家大模型服务商。其覆盖范围既包括商业闭源模型OpenAI GPT、Anthropic Claude、Google Gemini、Cohere、Replicate也包括企业云服务Azure OpenAI、AWS Bedrock、Vertex AI还涵盖开源与自托管方案HuggingFace、Ollama、vLLM、SGLang。通过 LiteLLM业务代码不再与任何单一模型厂商绑定更换模型只需调整一行配置而无需改动调用逻辑。LiteLLM 由两个核心产品组成LiteLLM Python SDKlitellm包一个轻量级 Python/JS 库开发者可以在代码中直接 import 使用通过litellm.completion()、litellm.embedding()等函数以统一签名调用任意模型。它适合嵌入式集成、脚本调用、单机应用场景。LiteLLM Proxy Serverlitellm proxy一个基于 FastAPI/uvicorn 构建的独立网关服务对外暴露 OpenAI 兼容的 REST API。它适合企业级部署提供虚拟密钥认证、预算管控、限流降级、日志审计、负载均衡等治理能力是团队统一管理多模型资源的控制平面。LiteLLM 解决的核心痛点包括厂商锁定更换模型需重写大量适配代码、接口不一致各厂商请求/响应结构、流式协议、鉴权方式各异、成本管理缺失无法按团队/项目/密钥维度追踪 token 消耗与费用、限流与降级困难突发流量打爆配额、主模型故障无自动切换、缺乏统一治理密钥散落、无审计、无缓存。LiteLLM 通过统一翻译层 路由控制层 治理平面三位一体的设计系统性解决这些问题。1.1 与同类方案对比对比维度直接调用各厂商 APILangChainOpenRouterLiteLLM统一 API 格式✗ 各厂商各异✓ 部分统一✓ OpenAI 格式✓ OpenAI 格式最完整独立 Proxy 模式✗ 无✗ 仅库✓ 云服务✓ 自托管/云托管成本追踪✗ 需自建✗ 弱✓ 平台级✓ Key/Team/Model 多维速率限制✗ 依赖厂商✗ 无✓ 平台级✓ 自定义多维限流故障 Fallback✗ 手动处理✓ 链式✗ 弱✓ 多级自动降级响应缓存✗ 自建✓ 内存✗ 无✓ Redis/内存自托管部署—✓ 库即可✗ SaaS only✓ 完全自主可控多语言 SDK—✓ Py/JS✓ REST✓ Py/JS/REST从对比可见直接调用成本最高、可维护性最差LangChain 偏编排框架、治理能力弱OpenRouter 是托管 SaaS、数据需过第三方LiteLLM 在统一性 治理 自主可控三方面综合最强是企业自建 LLM 网关的主流首选。二、核心概念理解 LiteLLM 的关键在于掌握以下术语它们构成配置与运行时的基础对象模型。术语英文说明LiteLLM SDKLiteLLM SDKPython/JS 软件开发包提供completion/embedding/image_generation等统一函数在代码内直接调用 LLMLiteLLM ProxyLiteLLM Proxy基于 FastAPI/uvicorn 的网关服务进程对外暴露 OpenAI 兼容 REST API承载认证、路由、限流、日志等治理能力LiteLLM RouterLiteLLM Router路由层组件负责模型选择、负载均衡、故障转移、重试策略是 Proxy 的核心调度大脑ModelModelLLM 提供商与模型名的组合标识如gpt-4、claude-3-opus、gemini-1.5-proModel AliasModel Alias用户友好的别名映射到实际模型组如aliasfast→model_groupgpt-3.5业务侧只感知别名DeploymentDeployment一个具体的可调用部署实例格式为provider/model如azure/gpt-4、anthropic/claude-3-opus一个模型组可含多个部署Virtual KeyVirtual KeyLiteLLM Proxy 签发的虚拟密钥绑定预算、速率限制、允许模型列表是客户端访问 Proxy 的凭证Model GroupModel Group模型组将多个 Deployment 聚合为一个逻辑单元用于在多实例间做负载均衡FallbackFallback兜底模型当主模型组返回错误如限流 429、超时、内容过滤时自动切换到的备用模型CacheCache响应缓存支持 Redis 与内存两种后端按 cache key 命中后直接返回跳过上游调用以降本提速Budget TrackingBudget Tracking预算追踪按 Virtual Key / Team / Model 维度累计 token 用量与费用超预算可阻断请求GuardrailsGuardrails内容护栏对输入 Prompt 与输出结果做 PII 脱敏、敏感词过滤、越狱检测等安全合规校验对象关系业务客户端持有一把Virtual Key请求到达Proxy后经认证与限流由Router根据Model Alias定位到Model Group在组内多个Deployment间按策略负载均衡命中Cache则直接返回否则翻译后调用上游失败时走Fallback全程由Budget Tracking计费、Guardrails守护内容安全。三、工作原理3.1 端到端请求处理流程下图展示客户端一次chat/completions请求在 LiteLLM Proxy 内部的完整流转包含认证、路由、缓存、限流、翻译、调用、计费、降级等关键阶段。Logger / Budget上游 LLM ProviderTranslator 翻译层Rate LimiterCache (Redis)Router 路由层Auth 模块LiteLLM ProxyClientLogger / Budget上游 LLM ProviderTranslator 翻译层Rate LimiterCache (Redis)Router 路由层Auth 模块LiteLLM ProxyClientalt[密钥无效/超预算][校验通过]alt[超过限流][限流通过]alt[有可用 Fallback][无 Fallback / 重试耗尽]alt[上游成功][上游失败 (429/5xx/超时)]alt[缓存命中][缓存未命中]POST /chat/completions (OpenAI 格式 Virtual Key)1校验 Virtual Key2401 / 4033错误响应4传递请求 Key 策略5解析 Model Alias → Model Group6查询 cache key7命中响应8直接返回9200 (from cache)10速率限制检查11触发 Fallback12切换到 Fallback 模型13放行14选择 Deployment 翻译请求15OpenAI 格式 → Provider 专属格式16调用上游 API17Provider 原始响应18翻译回 OpenAI 格式19写入缓存 (按 TTL)20记录用量 计费21OpenAI 格式响应22200 OK23错误24上报错误25判断是否可 Fallback26切换 Deployment 重试27调用备用 Provider28响应29OpenAI 格式响应30200 OK (via fallback)31透传错误32错误响应 (OpenAI 格式)33整个流程的精髓在于对客户端完全透明——无论后端是 GPT、Claude 还是自托管 vLLM客户端始终只看到一套 OpenAI 格式而所有治理逻辑认证、路由、缓存、限流、降级、计费都收敛在 Proxy 内部业务代码保持极简。3.2 四大核心机制详解1统一 API 翻译机制LiteLLM 的翻译层是屏蔽厂商差异的关键。其核心思想是以 OpenAI Chat Completions schema 为通用语每个 Provider 对应一个翻译器Translator模块负责请求与响应的双向转换。请求翻译将 OpenAI 标准字段messages、temperature、max_tokens、tools、stream映射到目标厂商的专属字段。例如 Anthropic Claude 需要将systemmessage 抽离为独立system参数Bedrock 需将消息体包装为anthropic_versionmessages的嵌套结构Gemini 需将role:assistant转为role:model并将tools转为function_declarations。响应翻译将厂商返回的非标准结构归一化为 OpenAIChatCompletion/ChatCompletionChunk对象统一choices[0].message.content、usage.prompt_tokens、finish_reason等字段流式响应也统一为 SSEdata:行格式。能力差异处理当目标模型不支持某项能力如 Vision、Tool Calling、JSON Mode时翻译层会做能力降级或抛出明确错误避免运行时静默失败。得益于翻译层开发者调用litellm.completion(modelclaude-3-opus, messages[...])与调用modelgpt-4的代码完全一致仅model字段不同。2路由与负载均衡机制LiteLLM Router 是 Proxy 的调度核心支持多种路由策略以适配不同业务目标加权路由Weighted Routing为每个 Deployment 配置weight按权重比例分配流量适合灰度发布或异构算力混部。延迟路由Latency-Based Routing基于历史响应延迟如 p95动态选择最快的 Deployment适合对首字延迟敏感的实时对话场景。Router 周期性统计每个 Deployment 的滚动延迟并排序。成本路由Cost-Based Routing在满足质量约束下优先选择单价更低的模型配合model_group将贵/便宜模型分组按预算策略调度。轮询 / 最少连接经典负载均衡策略适合同构多实例均匀分流。区域/标签路由通过labels将请求路由到特定区域或租户专属部署满足数据驻留与合规要求。当某 Deployment 连续失败或延迟劣化时Router 会触发熔断Cooldown暂时剔除该实例并将后续请求转向 Fallback 模型组实现故障自愈。3缓存机制缓存机制用于对相同输入直接返回历史结果显著降低成本与延迟后端支持Redis生产推荐跨进程共享、持久化与内存缓存单进程开发调试用。Redis 模式下多个 Proxy 实例共享缓存池。Cache Key 构造默认由model messages 部分参数如 temperature、tools哈希生成可通过cache_key自定义支持按用户、按会话隔离。TTL 与淘汰每个缓存项可设 TTL如 600s到期自动失效Redis 侧依赖其内置 LRU/TTL 淘汰。缓存控制粒度支持全量缓存、按cache_control标记的局部缓存Prompt Caching复用长前缀以及读写策略分离只读、只写、读写。命中率优化对语义相近但字面不同的输入可结合 Embedding 做语义缓存需额外配置进一步提升复用率。4成本追踪机制成本追踪是 LiteLLM 治理平面的基础实现用得起、管得住Token 计数响应返回后从 Provider 响应中提取usage.prompt_tokens/completion_tokensProvider 未返回时由 LiteLLM 本地 tokenizer 估算作为计费基础。定价计算LiteLLM 内置 100 模型的input_cost_per_token/output_cost_per_token价格表model_cost配置按当前模型实时计算单次调用费用自托管模型可自定义成本通常设为 0 或电费摊销。预算维度费用按Virtual Key → Team → Model → Project多维聚合写入数据库Postgres 推荐支持按时间窗口查询与导出。预算强制为 Key/Team 设置max_budget与budget_duration如每日 100 美元超预算后 Proxy 直接拒绝请求并返回 403无需等月底账单爆雷。告警与审计可配置阈值告警如消耗达 80% 通知所有调用记录含模型、token、费用、延迟、状态码构成完整审计链路便于成本归因与异常排查。通过上述四大机制协同LiteLLM 将调用 LLM这一原本碎片化的工程问题升级为可观测、可治理、可演进的平台能力。
01-概念原理
LiteLLM 概念原理版本LiteLLM 1.50 |作者Pozicaiman |日期2026-07-27定位统一 LLM API 网关与 SDK以 OpenAI 兼容格式调用 100 大模型提供商关键词LLM Proxy、统一 API、路由网关、成本追踪、负载均衡适用版本Python 3.8 / LiteLLM 1.50一、什么是 LiteLLMLiteLLM 是一个开源的统一 LLM API 网关与 SDK它以 OpenAI 兼容的标准格式屏蔽底层各提供商接口差异让开发者用一套代码即可调用 100 家大模型服务商。其覆盖范围既包括商业闭源模型OpenAI GPT、Anthropic Claude、Google Gemini、Cohere、Replicate也包括企业云服务Azure OpenAI、AWS Bedrock、Vertex AI还涵盖开源与自托管方案HuggingFace、Ollama、vLLM、SGLang。通过 LiteLLM业务代码不再与任何单一模型厂商绑定更换模型只需调整一行配置而无需改动调用逻辑。LiteLLM 由两个核心产品组成LiteLLM Python SDKlitellm包一个轻量级 Python/JS 库开发者可以在代码中直接 import 使用通过litellm.completion()、litellm.embedding()等函数以统一签名调用任意模型。它适合嵌入式集成、脚本调用、单机应用场景。LiteLLM Proxy Serverlitellm proxy一个基于 FastAPI/uvicorn 构建的独立网关服务对外暴露 OpenAI 兼容的 REST API。它适合企业级部署提供虚拟密钥认证、预算管控、限流降级、日志审计、负载均衡等治理能力是团队统一管理多模型资源的控制平面。LiteLLM 解决的核心痛点包括厂商锁定更换模型需重写大量适配代码、接口不一致各厂商请求/响应结构、流式协议、鉴权方式各异、成本管理缺失无法按团队/项目/密钥维度追踪 token 消耗与费用、限流与降级困难突发流量打爆配额、主模型故障无自动切换、缺乏统一治理密钥散落、无审计、无缓存。LiteLLM 通过统一翻译层 路由控制层 治理平面三位一体的设计系统性解决这些问题。1.1 与同类方案对比对比维度直接调用各厂商 APILangChainOpenRouterLiteLLM统一 API 格式✗ 各厂商各异✓ 部分统一✓ OpenAI 格式✓ OpenAI 格式最完整独立 Proxy 模式✗ 无✗ 仅库✓ 云服务✓ 自托管/云托管成本追踪✗ 需自建✗ 弱✓ 平台级✓ Key/Team/Model 多维速率限制✗ 依赖厂商✗ 无✓ 平台级✓ 自定义多维限流故障 Fallback✗ 手动处理✓ 链式✗ 弱✓ 多级自动降级响应缓存✗ 自建✓ 内存✗ 无✓ Redis/内存自托管部署—✓ 库即可✗ SaaS only✓ 完全自主可控多语言 SDK—✓ Py/JS✓ REST✓ Py/JS/REST从对比可见直接调用成本最高、可维护性最差LangChain 偏编排框架、治理能力弱OpenRouter 是托管 SaaS、数据需过第三方LiteLLM 在统一性 治理 自主可控三方面综合最强是企业自建 LLM 网关的主流首选。二、核心概念理解 LiteLLM 的关键在于掌握以下术语它们构成配置与运行时的基础对象模型。术语英文说明LiteLLM SDKLiteLLM SDKPython/JS 软件开发包提供completion/embedding/image_generation等统一函数在代码内直接调用 LLMLiteLLM ProxyLiteLLM Proxy基于 FastAPI/uvicorn 的网关服务进程对外暴露 OpenAI 兼容 REST API承载认证、路由、限流、日志等治理能力LiteLLM RouterLiteLLM Router路由层组件负责模型选择、负载均衡、故障转移、重试策略是 Proxy 的核心调度大脑ModelModelLLM 提供商与模型名的组合标识如gpt-4、claude-3-opus、gemini-1.5-proModel AliasModel Alias用户友好的别名映射到实际模型组如aliasfast→model_groupgpt-3.5业务侧只感知别名DeploymentDeployment一个具体的可调用部署实例格式为provider/model如azure/gpt-4、anthropic/claude-3-opus一个模型组可含多个部署Virtual KeyVirtual KeyLiteLLM Proxy 签发的虚拟密钥绑定预算、速率限制、允许模型列表是客户端访问 Proxy 的凭证Model GroupModel Group模型组将多个 Deployment 聚合为一个逻辑单元用于在多实例间做负载均衡FallbackFallback兜底模型当主模型组返回错误如限流 429、超时、内容过滤时自动切换到的备用模型CacheCache响应缓存支持 Redis 与内存两种后端按 cache key 命中后直接返回跳过上游调用以降本提速Budget TrackingBudget Tracking预算追踪按 Virtual Key / Team / Model 维度累计 token 用量与费用超预算可阻断请求GuardrailsGuardrails内容护栏对输入 Prompt 与输出结果做 PII 脱敏、敏感词过滤、越狱检测等安全合规校验对象关系业务客户端持有一把Virtual Key请求到达Proxy后经认证与限流由Router根据Model Alias定位到Model Group在组内多个Deployment间按策略负载均衡命中Cache则直接返回否则翻译后调用上游失败时走Fallback全程由Budget Tracking计费、Guardrails守护内容安全。三、工作原理3.1 端到端请求处理流程下图展示客户端一次chat/completions请求在 LiteLLM Proxy 内部的完整流转包含认证、路由、缓存、限流、翻译、调用、计费、降级等关键阶段。Logger / Budget上游 LLM ProviderTranslator 翻译层Rate LimiterCache (Redis)Router 路由层Auth 模块LiteLLM ProxyClientLogger / Budget上游 LLM ProviderTranslator 翻译层Rate LimiterCache (Redis)Router 路由层Auth 模块LiteLLM ProxyClientalt[密钥无效/超预算][校验通过]alt[超过限流][限流通过]alt[有可用 Fallback][无 Fallback / 重试耗尽]alt[上游成功][上游失败 (429/5xx/超时)]alt[缓存命中][缓存未命中]POST /chat/completions (OpenAI 格式 Virtual Key)1校验 Virtual Key2401 / 4033错误响应4传递请求 Key 策略5解析 Model Alias → Model Group6查询 cache key7命中响应8直接返回9200 (from cache)10速率限制检查11触发 Fallback12切换到 Fallback 模型13放行14选择 Deployment 翻译请求15OpenAI 格式 → Provider 专属格式16调用上游 API17Provider 原始响应18翻译回 OpenAI 格式19写入缓存 (按 TTL)20记录用量 计费21OpenAI 格式响应22200 OK23错误24上报错误25判断是否可 Fallback26切换 Deployment 重试27调用备用 Provider28响应29OpenAI 格式响应30200 OK (via fallback)31透传错误32错误响应 (OpenAI 格式)33整个流程的精髓在于对客户端完全透明——无论后端是 GPT、Claude 还是自托管 vLLM客户端始终只看到一套 OpenAI 格式而所有治理逻辑认证、路由、缓存、限流、降级、计费都收敛在 Proxy 内部业务代码保持极简。3.2 四大核心机制详解1统一 API 翻译机制LiteLLM 的翻译层是屏蔽厂商差异的关键。其核心思想是以 OpenAI Chat Completions schema 为通用语每个 Provider 对应一个翻译器Translator模块负责请求与响应的双向转换。请求翻译将 OpenAI 标准字段messages、temperature、max_tokens、tools、stream映射到目标厂商的专属字段。例如 Anthropic Claude 需要将systemmessage 抽离为独立system参数Bedrock 需将消息体包装为anthropic_versionmessages的嵌套结构Gemini 需将role:assistant转为role:model并将tools转为function_declarations。响应翻译将厂商返回的非标准结构归一化为 OpenAIChatCompletion/ChatCompletionChunk对象统一choices[0].message.content、usage.prompt_tokens、finish_reason等字段流式响应也统一为 SSEdata:行格式。能力差异处理当目标模型不支持某项能力如 Vision、Tool Calling、JSON Mode时翻译层会做能力降级或抛出明确错误避免运行时静默失败。得益于翻译层开发者调用litellm.completion(modelclaude-3-opus, messages[...])与调用modelgpt-4的代码完全一致仅model字段不同。2路由与负载均衡机制LiteLLM Router 是 Proxy 的调度核心支持多种路由策略以适配不同业务目标加权路由Weighted Routing为每个 Deployment 配置weight按权重比例分配流量适合灰度发布或异构算力混部。延迟路由Latency-Based Routing基于历史响应延迟如 p95动态选择最快的 Deployment适合对首字延迟敏感的实时对话场景。Router 周期性统计每个 Deployment 的滚动延迟并排序。成本路由Cost-Based Routing在满足质量约束下优先选择单价更低的模型配合model_group将贵/便宜模型分组按预算策略调度。轮询 / 最少连接经典负载均衡策略适合同构多实例均匀分流。区域/标签路由通过labels将请求路由到特定区域或租户专属部署满足数据驻留与合规要求。当某 Deployment 连续失败或延迟劣化时Router 会触发熔断Cooldown暂时剔除该实例并将后续请求转向 Fallback 模型组实现故障自愈。3缓存机制缓存机制用于对相同输入直接返回历史结果显著降低成本与延迟后端支持Redis生产推荐跨进程共享、持久化与内存缓存单进程开发调试用。Redis 模式下多个 Proxy 实例共享缓存池。Cache Key 构造默认由model messages 部分参数如 temperature、tools哈希生成可通过cache_key自定义支持按用户、按会话隔离。TTL 与淘汰每个缓存项可设 TTL如 600s到期自动失效Redis 侧依赖其内置 LRU/TTL 淘汰。缓存控制粒度支持全量缓存、按cache_control标记的局部缓存Prompt Caching复用长前缀以及读写策略分离只读、只写、读写。命中率优化对语义相近但字面不同的输入可结合 Embedding 做语义缓存需额外配置进一步提升复用率。4成本追踪机制成本追踪是 LiteLLM 治理平面的基础实现用得起、管得住Token 计数响应返回后从 Provider 响应中提取usage.prompt_tokens/completion_tokensProvider 未返回时由 LiteLLM 本地 tokenizer 估算作为计费基础。定价计算LiteLLM 内置 100 模型的input_cost_per_token/output_cost_per_token价格表model_cost配置按当前模型实时计算单次调用费用自托管模型可自定义成本通常设为 0 或电费摊销。预算维度费用按Virtual Key → Team → Model → Project多维聚合写入数据库Postgres 推荐支持按时间窗口查询与导出。预算强制为 Key/Team 设置max_budget与budget_duration如每日 100 美元超预算后 Proxy 直接拒绝请求并返回 403无需等月底账单爆雷。告警与审计可配置阈值告警如消耗达 80% 通知所有调用记录含模型、token、费用、延迟、状态码构成完整审计链路便于成本归因与异常排查。通过上述四大机制协同LiteLLM 将调用 LLM这一原本碎片化的工程问题升级为可观测、可治理、可演进的平台能力。
