聊一个最近在内部工具链里出镜率很高的项目LiteLLM。简单说它是一套开源的 LLM API 网关/代理核心能力是把 OpenAI、Anthropic、Azure OpenAI、各类国产模型、本地部署模型全部收拢到一个 OpenAI 兼容接口后面然后由它统一转发、计费、限流、做 Key 管理和日志。之所以想写它是我发现自己前后给三拨团队搭过类似的“模型路由层”前两次都是自己手搓第三次才换成 LiteLLM结果后面维护成本直接少了一个量级。如果你正在处理“多个大模型供应商、多把 API Key、业务代码里散落一堆 SDK”的问题这篇文章应该能帮你省掉不少弯路。这个项目的定位很明确它不是模型训练框架也不是模型评测工具而是一个“站在业务代码和模型供应商之间的代理层”。适合谁来用后端工程师、平台/工具链开发者、小团队的技术负责人只要你不想在业务代码里反复改供应商切换逻辑LiteLLM 就值得试试。下面我按自己从安装到落地排查的真实路径来拆。1. “多模型直连”的混乱现场为什么需要网关层1.1 没有代理层时代码里会发生什么假设你的项目要同时用 OpenAI 的 GPT 系列和一个国产大模型。最直观的写法是引入两家 SDK然后写两套请求函数import openai from some_national_sdk import ChatClient openai_client openai.OpenAI(api_keysk-xxx) national_client ChatClient(api_keysk-yyy) def chat_gpt(messages, modelgpt-4o): resp openai_client.chat.completions.create(modelmodel, messagesmessages) return resp.choices[0].message.content def chat_national(messages, modelglm-4): resp national_client.chat.completions.create(modelmodel, messagesmessages) return resp.choices[0].message.content刚开始没什么问题。但两周后需求就来了模型要统一走 Azure OpenAI、供应商要加一个、某一家的模型要按团队限额、要统计每个部门花了多少钱、要记录每次请求的 token 数。这时候你会发现自己陷入了几个麻烦。第一各家 SDK 的模型名、参数、返回结构差异很大业务逻辑被两家 SDK 的细节牢牢绑死。第二API Key 直接散落在代码和配置里发给谁都不放心。第三账单分散在好几个平台月底想算一笔总账得先人工导出再对表。第四改一次供应商就要改业务代码发版周期跟着变长。这还只是用了两家如果五家呢最讽刺的是这些问题其实都不是业务问题它们全是“接入层”的基础设施问题。可它们偏偏在每一个团队里反复出现。所以就有了一个朴素的思路在业务代码和模型供应商之间塞一个“模型网关”所有下游细节都收敛到它身上。1.2 加代理层而不是改业务代码代理层的核心价值一句话说就是“把不稳定的下游和稳定的上游隔离开”。业务代码只认一个 OpenAI 兼容接口供应商怎么换、Key 怎么轮换、限流怎么做、费用怎么统计那都是网关的事。我后来总结过这三个模型网关的硬性标准接口兼容性要强最好是 OpenAI 的接口风格因为团队里随便拉个人都会用。配置驱动换模型、调参数尽量不写死代码。可观测性要好能清楚看到每次请求花的 token、费用、成功失败状态。LiteLLM 在这三点上做得相当平衡。它本身就是一个 Python 服务你用pip install litellm[proxy]装起来后跑起来就是一个本地 API 服务默认端口是 4000接口风格直接对齐 OpenAI 的/chat/completions、/embeddings、/models。业务端只需要把base_url改成http://your-gateway:4000其余几乎不用动。1.3 LiteLLM 在同类方案里为什么值得优先看现在类似的工具不算少比如 One API、new-api 这类也有商业的网关产品。LiteLLM 的优势主要有三个。一是纯粹它本身是命令行工具加 Python SDK没有绑死管理后台想接自己的运维体系很容易。二是配置灵活config.yaml里可以定义模型列表、供应商参数、重试策略、预算规则几乎全量能力都通过配置暴露出来。三是生态兼容面广主流的 OpenAI 兼容服务、Anthropic 风格接口、Azure OpenAI 的资源模式它都支持。当然它不是没有缺点。管理后台默认比较朴素不像商业化网关那样有一大堆图表文档有时候更新得比功能慢一些新特性需要自己去翻源码或者 issues。但对于自己搭内网工具链来说这些完全不是阻碍。2. 动手前必须先搞懂的基础概念2.1 三个关键名词代理服务、模型别名、供应商路由上手 LiteLLM 之前有三个概念必须先整明白否则配置起来会一脸懵。第一个叫 Proxy Server也就是你最终跑起来的那个 HTTP 服务。它本身不产模型只负责接收请求、按规则路由到真实供应商、再把响应吐回来。你可以把它理解成一个“模型交换机”业务侧连接的永远是这个交换机。第二个叫模型别名model_name。在 LiteLLM 的配置里model_name是“你给业务方看的名字”而真实的供应商模型名写在model字段里。比如你可以在配置里写model_name: gpt-4o真实model: openai/gpt-4o-2024-11-20也可以写model_name: my-assistant真实model: anthropic/claude-3-5-sonnet-20241022。这一步解决了所有团队都会遇到的痛点业务环境不跟着上游命名走。第三个叫供应商路由。LiteLLM 内部通过模型名前缀识别供应商openai/、anthropic/、azure/、bedrock/、ollama/等。如果你只有一个本地 Ollama 模型配置里就要写ollama/llama3.1后面接真实请求时它会去http://localhost:11434找 Ollama 服务。刚入门的人最容易在这里卡住直接拿供应商模型名当作model_name用然后发现请求 404。记住在 LiteLLM 的世界里model_name是个逻辑标识你可以随便起名重点是把映射关系配对。2.2 config.yaml 里到底该写什么LiteLLM 的配置采用 YAML 格式三个核心区块很常用model_list、litellm_settings、general_settings。model_list是模型路由表必填。每条至少包含model_name和litellm_params后者里面必须有model这个键表示真实模型标识。还可以附加api_key、api_base、temperature等默认参数。litellm_settings是通用参数区比如设置drop_params、request_timeout、num_retries、fallbacks这些。我的经验是超时和重试放这里全局调比在每条模型里重复写要省事。general_settings是一些服务级设置比如master_key代理自己的访问密钥、database_urlPostgreSQL 连接串用于持久化日志和预算数据、otlp或prometheus相关开关。2.3 一个最小配置实例解析先看一个能跑通的最小配置我建议新手从这里起步model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: sk-your-openai-key general_settings: master_key: sk-litellm-master-key这个配置表示业务方只要用modelgpt-4o调用你的代理代理就会去请求 OpenAI 的真实gpt-4o并且代理自身要求请求头里带Authorization: Bearer sk-litellm-master-key。你把这文件保存为config.yaml然后执行litellm --config config.yaml --port 4000服务起来后本地就多了一个 OpenAI 兼容服务。如果你这时候用原来的 OpenAI SDK 去调只是把base_url换成http://localhost:4000行为上几乎感觉不到变化。这就是我能想到的最平滑引入方式。3. 从零跑通统一接口的完整实操3.1 安装与启动一次装到位官方推荐用虚拟环境跑因为 LiteLLM 依赖的包挺多直接装进全局环境容易和项目现有依赖打架。我个人用的是 uv不过用 pip 也一样python -m venv .venv source .venv/bin/activate pip install litellm[proxy]这里提醒一句装[proxy]扩展非常关键。如果只装litellm你拿到的是 SDK 而不会有litellm命令的 proxy 入口。第一次装的时候我就吃过这个亏命令行敲litellm --config ...直接提示找不到命令后来才发现要装 proxy 扩展。启动写法也值得单独说。直接litellm --config config.yaml会让服务走默认端口 4000但我在实践中更喜欢固定端口并开详细日志litellm --config config.yaml --port 4000 --detailed_debug--detailed_debug只建议排查问题的时候开平时别开日志量太大。3.2 让现有 OpenAI SDK 直接指向代理代理跑起来后模拟业务端的调用。我强烈建议用一个最简单的 Python 脚本来验证通路别一上来就接生产代码from openai import OpenAI client OpenAI( api_keysk-litellm-master-key, # 注意这里是 master_key base_urlhttp://localhost:4000/v1 # 注意结尾的 /v1 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好请回复ok}], ) print(resp.choices[0].message.content)这里最容易踩的坑是base_url的路径。OpenAI SDK 会默认在 base_url 后面拼/chat/completions所以如果你的 base_url 写了http://localhost:4000实际请求可能变成http://localhost:4000/chat/completions但 LiteLLM 的 OpenAI 兼容路径其实是/v1/chat/completions。我第一次测试时直接 404后来把 base_url 改成http://localhost:4000/v1才通。官方文档也一直强调这个细节。3.3 多模型路由、负载均衡与兜底策略单模型跑通只是开胃菜网关的价值在多模型场景才真正体现。下面是我常用的一套多模型配置model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llm litellm_params: model: ollama/llama3.1 api_base: http://localhost:11434 litellm_settings: request_timeout: 60 num_retries: 2这里有一个非常实用的配置细节api_key可以写成os.environ/变量名的形式让 LiteLLM 从环境变量里读 Key。好处是敏感信息不进 YAML方便直接把配置文件放版本库。负载均衡怎么配同一个model_name下面写多条litellm_params记录即可model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY1 - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY2LiteLLM 会自动在这些记录间做轮询两个 Key 轮流被使用。这招在供应商单 Key 限流时极其有效。我实测过在同样请求频率下双 Key 轮询能把 429 的概率大幅压低。兜底策略也很有用。所谓 fallback就是 A 模型失败时自动转 B 模型。可以在litellm_settings里加litellm_settings: fallbacks: [ {gpt-4o: [claude]} ]意思是gpt-4o请求失败时自动改走claude。这个功能在生产环境很救命尤其是某些供应商晚上高峰期随机返回 5xx 的时候。3.4 重试、超时与参数透传的实测心得关于重试和超时我在实际使用中的体会是不要盲目加大num_retries。LiteLLM 默认在某些场景下会对 429、5xx 做重试如果配得太大上游一旦开始抖动你的代理层会瞬间堆积大量请求反而放大问题。我一般把num_retries保持在 2 到 3超时控制在 60 到 120 秒之间因为大模型流式响应本身耗时就不短。另一个值得说的点是参数透传。业务端请求里带的temperature、max_tokens、top_p这些参数LiteLLM 默认会原样传给上游。但如果业务侧总是传一些当前模型不支持的最新参数上游就会报错。解决办法是在litellm_settings里开drop_params: true让 LiteLLM 自动丢弃当前模型不支持的参数而不是直接把错误抛回业务端。这个开关我建议所有团队都打开它能吞掉一大类“同一个业务参数换模型就报错”的兼容性问题。4. Key 管理、预算控制与团队协作网关如何管钱4.1 虚拟 Key 机制别再把上游 Key 撒给所有人LiteLLM 有一个很核心的能力虚拟 Key。它的工作方式是这样的你在代理里创建一把虚拟 Key比如sk-1234这把 Key 和真实的上游 Key 完全无关。业务方调代理时用的是虚拟 Key代理内部拿着虚拟 Key 去映射真实上游 Key再请求供应商。这样上游真实 Key 永远保存在代理服务这一侧不会进入业务环境。创建虚拟 Key 有几种方式最常用的是调用 LiteLLM 自己的接口。假设代理服务跑在本机 4000 端口用master_key调curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o], max_budget: 20, budget_duration: 30d }返回里会带一把key这就是给业务方用的虚拟 Key。它的好处很多可以随时吊销、可以限制可用模型、可以设置预算上限。团队里再也不用有人问“谁手里有 OpenAI Key”。4.2 预算、限流与团队配额怎么设预算控制是网关最实用的部分之一。我通常会按团队或者项目建 Key然后给每个 Key 设置独立的max_budget。上面的命令里max_budget: 20表示这张 Key 最多花 20 美元budget_duration: 30d表示这个额度是 30 天周期到期自动重置。还可以设置每分钟的请求速率限制curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o], max_budget: 50, budget_duration: 30d, rpm_limit: 60, tpm_limit: 100000 }rpm_limit是每分钟请求数tpm_limit是每分钟 token 数。我踩过的一个坑是只设置了max_budget没设rpm_limit某个定时任务在高峰期瞬间打出大量请求差点把月度预算几分钟内烧穿。所以强烈建议任何面向自动化任务发放的虚拟 Key至少把rpm_limit配上。4.3 费用统计与日志月底再也不用自己对表预算控制只是前菜真正让我觉得“早就该用网关”的时刻是查账。没有网关的时候月底要跑三四个平台的后台导出账单。有了 LiteLLM 之后每条请求的 token 消耗、成本估计、模型名、请求状态都打到日志里还能直接查询。查询某张 Key 的消费记录curl -X GET http://localhost:4000/spend/logs?keysk-1234 \ -H Authorization: Bearer sk-litellm-master-key如果要持久化这些日志官方推荐接 PostgreSQL。在general_settings里配好database_url重启后日志和预算数据都会落库。我实测下来如果只是临时用SQLite 也能顶一阵子但一旦多台机器或者要查复杂费用报表还是尽早切 PostgreSQL否则后面数据量上来迁移很痛苦。这里要特别提醒一个坑预算扣费的准确性依赖数据库记录。如果你服务只用内存跑Key 的剩余额度在重启后会复位可能造成“明明没超预算却被拒绝服务”的情况。所以凡是涉及预算、团队配额的生产部署数据库必须配好。5. 常见问题与排查技巧实录5.1 请求返回 404、模型不存在这个是我遇到频率最高的问题。业务端报model not found或Unknown model时百分之八十是model_name没对上。你在请求里传的模型名必须和config.yaml中model_list里的model_name完全一致而不是真实供应商模型名。排查套路很简单先看model_list里的model_name是什么再对比请求里的model字段最后看代理启动日志里有没有模型映射异常。也可以用curl -X GET http://localhost:4000/model/info \ -H Authorization: Bearer sk-litellm-master-key这条命令会返回代理当前注册的所有模型名是排查模型映射问题的第一利器。5.2 请求一直超时或 502分几种情况。如果所有模型都超时先查代理服务本身到外网的连通性再查 DNS 解析。如果只有某个供应商超时那大概率是上游接口地址问题。用国内服务器部署时这个问题尤其容易被忽略一些海外模型接口的延迟和稳定性完全取决于网络链路代理层能做的就是调大超时、开重试但链路质量本身代理解决不了。另外很多模型供应商官方要求 SSL 证书验证。如果你的代理跑在内网环境且上游接口用的证书不被系统信任可以在litellm_params里对特定模型设置ssl_verify: false。注意这只建议在自己能控制可信链的内网用公网环境别轻易关验证安全更重要。5.3 上游 Key 一直报鉴权失败这个问题通常是环境变量没被加载。配置里写了os.environ/OPENAI_API_KEY但启动服务的进程里没有这个环境变量。排查方法很简单在终端里先echo $OPENAI_API_KEY确认有没有值没有就先 export或者写进.env文件再用--config启动时加载。还有一个细节如果同时在litellm_params和系统环境变量都配置了 KeyLiteLLM 优先读取litellm_params里的值。这会导致你改了环境变量但请求还在用旧 Key误以为设置没生效。5.4 上游频繁 429代理服务跟着抖429 通常是触发了供应商的速率限制。除了前面说的多 Key 负载均衡另一个实用技巧是在代理里开启智能重试。LiteLLM 本身支持按Retry-After头等待后重试。还有一种思路是给模型配置更低的并发上限从源头削峰litellm_settings: max_parallel_requests: 20这个参数控制代理层同时处理多少个请求超过的直接排队或返回 429。我在内部工具里设成 20 之后上游 429 明显少了而且代价只是排队等待时间变长而不是失败率上升。5.5 日志、指标接入不成功生产部署时团队通常希望把代理的指标接到现有监控。LiteLLM 提供 Prometheus 端点/metrics你只需要在general_settings里打开general_settings: master_key: sk-litellm-master-key otel: true然后用 Prometheus 抓取http://localhost:4000/metrics即可。需要注意的是打开otel: true后会有额外的可观测性依赖如果你的环境里没搭好相关后端可能会在启动时报错。可以先不开等监控体系真正需要再补。一些实战后的个人体会LiteLLM 真正改变我工作习惯的地方不是省掉了那几行切换供应商的代码而是让“模型资源”变成了一种可管理、可计量、可分配的东西。以前模型是被硬编码在各个业务服务里的现在它是一个统一入口后面接什么模型业务方根本不需要感知。从搭建第一天起我就在配置里把所有模型都起成稳定的逻辑别名之后上游模型迭代升级我只改网关配置业务代码一行不动。最后分享一个很实用的小技巧如果你把多个供应商的“同能力模型”都映射到同一个model_name下业务代码里只写一个模型名网关自动做负载均衡和故障转移这种感觉非常爽。但这套玩法要想稳前提是先把日志、预算、超时这些基础配置搭扎实。我的建议是别想着一步到位先从一台模型一个 Key 跑通最小链路开始再逐步加模型、加负载、加预算。基础设施这东西稳比花哨重要得多。 
长河君 · 2026/10/13 5:24:10 · 阅读 1.2k 用LiteLLM统一管理多模型API：从网关配置到预算控制实战
聊一个最近在内部工具链里出镜率很高的项目LiteLLM。简单说它是一套开源的 LLM API 网关/代理核心能力是把 OpenAI、Anthropic、Azure OpenAI、各类国产模型、本地部署模型全部收拢到一个 OpenAI 兼容接口后面然后由它统一转发、计费、限流、做 Key 管理和日志。之所以想写它是我发现自己前后给三拨团队搭过类似的“模型路由层”前两次都是自己手搓第三次才换成 LiteLLM结果后面维护成本直接少了一个量级。如果你正在处理“多个大模型供应商、多把 API Key、业务代码里散落一堆 SDK”的问题这篇文章应该能帮你省掉不少弯路。这个项目的定位很明确它不是模型训练框架也不是模型评测工具而是一个“站在业务代码和模型供应商之间的代理层”。适合谁来用后端工程师、平台/工具链开发者、小团队的技术负责人只要你不想在业务代码里反复改供应商切换逻辑LiteLLM 就值得试试。下面我按自己从安装到落地排查的真实路径来拆。1. “多模型直连”的混乱现场为什么需要网关层1.1 没有代理层时代码里会发生什么假设你的项目要同时用 OpenAI 的 GPT 系列和一个国产大模型。最直观的写法是引入两家 SDK然后写两套请求函数import openai from some_national_sdk import ChatClient openai_client openai.OpenAI(api_keysk-xxx) national_client ChatClient(api_keysk-yyy) def chat_gpt(messages, modelgpt-4o): resp openai_client.chat.completions.create(modelmodel, messagesmessages) return resp.choices[0].message.content def chat_national(messages, modelglm-4): resp national_client.chat.completions.create(modelmodel, messagesmessages) return resp.choices[0].message.content刚开始没什么问题。但两周后需求就来了模型要统一走 Azure OpenAI、供应商要加一个、某一家的模型要按团队限额、要统计每个部门花了多少钱、要记录每次请求的 token 数。这时候你会发现自己陷入了几个麻烦。第一各家 SDK 的模型名、参数、返回结构差异很大业务逻辑被两家 SDK 的细节牢牢绑死。第二API Key 直接散落在代码和配置里发给谁都不放心。第三账单分散在好几个平台月底想算一笔总账得先人工导出再对表。第四改一次供应商就要改业务代码发版周期跟着变长。这还只是用了两家如果五家呢最讽刺的是这些问题其实都不是业务问题它们全是“接入层”的基础设施问题。可它们偏偏在每一个团队里反复出现。所以就有了一个朴素的思路在业务代码和模型供应商之间塞一个“模型网关”所有下游细节都收敛到它身上。1.2 加代理层而不是改业务代码代理层的核心价值一句话说就是“把不稳定的下游和稳定的上游隔离开”。业务代码只认一个 OpenAI 兼容接口供应商怎么换、Key 怎么轮换、限流怎么做、费用怎么统计那都是网关的事。我后来总结过这三个模型网关的硬性标准接口兼容性要强最好是 OpenAI 的接口风格因为团队里随便拉个人都会用。配置驱动换模型、调参数尽量不写死代码。可观测性要好能清楚看到每次请求花的 token、费用、成功失败状态。LiteLLM 在这三点上做得相当平衡。它本身就是一个 Python 服务你用pip install litellm[proxy]装起来后跑起来就是一个本地 API 服务默认端口是 4000接口风格直接对齐 OpenAI 的/chat/completions、/embeddings、/models。业务端只需要把base_url改成http://your-gateway:4000其余几乎不用动。1.3 LiteLLM 在同类方案里为什么值得优先看现在类似的工具不算少比如 One API、new-api 这类也有商业的网关产品。LiteLLM 的优势主要有三个。一是纯粹它本身是命令行工具加 Python SDK没有绑死管理后台想接自己的运维体系很容易。二是配置灵活config.yaml里可以定义模型列表、供应商参数、重试策略、预算规则几乎全量能力都通过配置暴露出来。三是生态兼容面广主流的 OpenAI 兼容服务、Anthropic 风格接口、Azure OpenAI 的资源模式它都支持。当然它不是没有缺点。管理后台默认比较朴素不像商业化网关那样有一大堆图表文档有时候更新得比功能慢一些新特性需要自己去翻源码或者 issues。但对于自己搭内网工具链来说这些完全不是阻碍。2. 动手前必须先搞懂的基础概念2.1 三个关键名词代理服务、模型别名、供应商路由上手 LiteLLM 之前有三个概念必须先整明白否则配置起来会一脸懵。第一个叫 Proxy Server也就是你最终跑起来的那个 HTTP 服务。它本身不产模型只负责接收请求、按规则路由到真实供应商、再把响应吐回来。你可以把它理解成一个“模型交换机”业务侧连接的永远是这个交换机。第二个叫模型别名model_name。在 LiteLLM 的配置里model_name是“你给业务方看的名字”而真实的供应商模型名写在model字段里。比如你可以在配置里写model_name: gpt-4o真实model: openai/gpt-4o-2024-11-20也可以写model_name: my-assistant真实model: anthropic/claude-3-5-sonnet-20241022。这一步解决了所有团队都会遇到的痛点业务环境不跟着上游命名走。第三个叫供应商路由。LiteLLM 内部通过模型名前缀识别供应商openai/、anthropic/、azure/、bedrock/、ollama/等。如果你只有一个本地 Ollama 模型配置里就要写ollama/llama3.1后面接真实请求时它会去http://localhost:11434找 Ollama 服务。刚入门的人最容易在这里卡住直接拿供应商模型名当作model_name用然后发现请求 404。记住在 LiteLLM 的世界里model_name是个逻辑标识你可以随便起名重点是把映射关系配对。2.2 config.yaml 里到底该写什么LiteLLM 的配置采用 YAML 格式三个核心区块很常用model_list、litellm_settings、general_settings。model_list是模型路由表必填。每条至少包含model_name和litellm_params后者里面必须有model这个键表示真实模型标识。还可以附加api_key、api_base、temperature等默认参数。litellm_settings是通用参数区比如设置drop_params、request_timeout、num_retries、fallbacks这些。我的经验是超时和重试放这里全局调比在每条模型里重复写要省事。general_settings是一些服务级设置比如master_key代理自己的访问密钥、database_urlPostgreSQL 连接串用于持久化日志和预算数据、otlp或prometheus相关开关。2.3 一个最小配置实例解析先看一个能跑通的最小配置我建议新手从这里起步model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: sk-your-openai-key general_settings: master_key: sk-litellm-master-key这个配置表示业务方只要用modelgpt-4o调用你的代理代理就会去请求 OpenAI 的真实gpt-4o并且代理自身要求请求头里带Authorization: Bearer sk-litellm-master-key。你把这文件保存为config.yaml然后执行litellm --config config.yaml --port 4000服务起来后本地就多了一个 OpenAI 兼容服务。如果你这时候用原来的 OpenAI SDK 去调只是把base_url换成http://localhost:4000行为上几乎感觉不到变化。这就是我能想到的最平滑引入方式。3. 从零跑通统一接口的完整实操3.1 安装与启动一次装到位官方推荐用虚拟环境跑因为 LiteLLM 依赖的包挺多直接装进全局环境容易和项目现有依赖打架。我个人用的是 uv不过用 pip 也一样python -m venv .venv source .venv/bin/activate pip install litellm[proxy]这里提醒一句装[proxy]扩展非常关键。如果只装litellm你拿到的是 SDK 而不会有litellm命令的 proxy 入口。第一次装的时候我就吃过这个亏命令行敲litellm --config ...直接提示找不到命令后来才发现要装 proxy 扩展。启动写法也值得单独说。直接litellm --config config.yaml会让服务走默认端口 4000但我在实践中更喜欢固定端口并开详细日志litellm --config config.yaml --port 4000 --detailed_debug--detailed_debug只建议排查问题的时候开平时别开日志量太大。3.2 让现有 OpenAI SDK 直接指向代理代理跑起来后模拟业务端的调用。我强烈建议用一个最简单的 Python 脚本来验证通路别一上来就接生产代码from openai import OpenAI client OpenAI( api_keysk-litellm-master-key, # 注意这里是 master_key base_urlhttp://localhost:4000/v1 # 注意结尾的 /v1 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好请回复ok}], ) print(resp.choices[0].message.content)这里最容易踩的坑是base_url的路径。OpenAI SDK 会默认在 base_url 后面拼/chat/completions所以如果你的 base_url 写了http://localhost:4000实际请求可能变成http://localhost:4000/chat/completions但 LiteLLM 的 OpenAI 兼容路径其实是/v1/chat/completions。我第一次测试时直接 404后来把 base_url 改成http://localhost:4000/v1才通。官方文档也一直强调这个细节。3.3 多模型路由、负载均衡与兜底策略单模型跑通只是开胃菜网关的价值在多模型场景才真正体现。下面是我常用的一套多模型配置model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llm litellm_params: model: ollama/llama3.1 api_base: http://localhost:11434 litellm_settings: request_timeout: 60 num_retries: 2这里有一个非常实用的配置细节api_key可以写成os.environ/变量名的形式让 LiteLLM 从环境变量里读 Key。好处是敏感信息不进 YAML方便直接把配置文件放版本库。负载均衡怎么配同一个model_name下面写多条litellm_params记录即可model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY1 - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY2LiteLLM 会自动在这些记录间做轮询两个 Key 轮流被使用。这招在供应商单 Key 限流时极其有效。我实测过在同样请求频率下双 Key 轮询能把 429 的概率大幅压低。兜底策略也很有用。所谓 fallback就是 A 模型失败时自动转 B 模型。可以在litellm_settings里加litellm_settings: fallbacks: [ {gpt-4o: [claude]} ]意思是gpt-4o请求失败时自动改走claude。这个功能在生产环境很救命尤其是某些供应商晚上高峰期随机返回 5xx 的时候。3.4 重试、超时与参数透传的实测心得关于重试和超时我在实际使用中的体会是不要盲目加大num_retries。LiteLLM 默认在某些场景下会对 429、5xx 做重试如果配得太大上游一旦开始抖动你的代理层会瞬间堆积大量请求反而放大问题。我一般把num_retries保持在 2 到 3超时控制在 60 到 120 秒之间因为大模型流式响应本身耗时就不短。另一个值得说的点是参数透传。业务端请求里带的temperature、max_tokens、top_p这些参数LiteLLM 默认会原样传给上游。但如果业务侧总是传一些当前模型不支持的最新参数上游就会报错。解决办法是在litellm_settings里开drop_params: true让 LiteLLM 自动丢弃当前模型不支持的参数而不是直接把错误抛回业务端。这个开关我建议所有团队都打开它能吞掉一大类“同一个业务参数换模型就报错”的兼容性问题。4. Key 管理、预算控制与团队协作网关如何管钱4.1 虚拟 Key 机制别再把上游 Key 撒给所有人LiteLLM 有一个很核心的能力虚拟 Key。它的工作方式是这样的你在代理里创建一把虚拟 Key比如sk-1234这把 Key 和真实的上游 Key 完全无关。业务方调代理时用的是虚拟 Key代理内部拿着虚拟 Key 去映射真实上游 Key再请求供应商。这样上游真实 Key 永远保存在代理服务这一侧不会进入业务环境。创建虚拟 Key 有几种方式最常用的是调用 LiteLLM 自己的接口。假设代理服务跑在本机 4000 端口用master_key调curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o], max_budget: 20, budget_duration: 30d }返回里会带一把key这就是给业务方用的虚拟 Key。它的好处很多可以随时吊销、可以限制可用模型、可以设置预算上限。团队里再也不用有人问“谁手里有 OpenAI Key”。4.2 预算、限流与团队配额怎么设预算控制是网关最实用的部分之一。我通常会按团队或者项目建 Key然后给每个 Key 设置独立的max_budget。上面的命令里max_budget: 20表示这张 Key 最多花 20 美元budget_duration: 30d表示这个额度是 30 天周期到期自动重置。还可以设置每分钟的请求速率限制curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o], max_budget: 50, budget_duration: 30d, rpm_limit: 60, tpm_limit: 100000 }rpm_limit是每分钟请求数tpm_limit是每分钟 token 数。我踩过的一个坑是只设置了max_budget没设rpm_limit某个定时任务在高峰期瞬间打出大量请求差点把月度预算几分钟内烧穿。所以强烈建议任何面向自动化任务发放的虚拟 Key至少把rpm_limit配上。4.3 费用统计与日志月底再也不用自己对表预算控制只是前菜真正让我觉得“早就该用网关”的时刻是查账。没有网关的时候月底要跑三四个平台的后台导出账单。有了 LiteLLM 之后每条请求的 token 消耗、成本估计、模型名、请求状态都打到日志里还能直接查询。查询某张 Key 的消费记录curl -X GET http://localhost:4000/spend/logs?keysk-1234 \ -H Authorization: Bearer sk-litellm-master-key如果要持久化这些日志官方推荐接 PostgreSQL。在general_settings里配好database_url重启后日志和预算数据都会落库。我实测下来如果只是临时用SQLite 也能顶一阵子但一旦多台机器或者要查复杂费用报表还是尽早切 PostgreSQL否则后面数据量上来迁移很痛苦。这里要特别提醒一个坑预算扣费的准确性依赖数据库记录。如果你服务只用内存跑Key 的剩余额度在重启后会复位可能造成“明明没超预算却被拒绝服务”的情况。所以凡是涉及预算、团队配额的生产部署数据库必须配好。5. 常见问题与排查技巧实录5.1 请求返回 404、模型不存在这个是我遇到频率最高的问题。业务端报model not found或Unknown model时百分之八十是model_name没对上。你在请求里传的模型名必须和config.yaml中model_list里的model_name完全一致而不是真实供应商模型名。排查套路很简单先看model_list里的model_name是什么再对比请求里的model字段最后看代理启动日志里有没有模型映射异常。也可以用curl -X GET http://localhost:4000/model/info \ -H Authorization: Bearer sk-litellm-master-key这条命令会返回代理当前注册的所有模型名是排查模型映射问题的第一利器。5.2 请求一直超时或 502分几种情况。如果所有模型都超时先查代理服务本身到外网的连通性再查 DNS 解析。如果只有某个供应商超时那大概率是上游接口地址问题。用国内服务器部署时这个问题尤其容易被忽略一些海外模型接口的延迟和稳定性完全取决于网络链路代理层能做的就是调大超时、开重试但链路质量本身代理解决不了。另外很多模型供应商官方要求 SSL 证书验证。如果你的代理跑在内网环境且上游接口用的证书不被系统信任可以在litellm_params里对特定模型设置ssl_verify: false。注意这只建议在自己能控制可信链的内网用公网环境别轻易关验证安全更重要。5.3 上游 Key 一直报鉴权失败这个问题通常是环境变量没被加载。配置里写了os.environ/OPENAI_API_KEY但启动服务的进程里没有这个环境变量。排查方法很简单在终端里先echo $OPENAI_API_KEY确认有没有值没有就先 export或者写进.env文件再用--config启动时加载。还有一个细节如果同时在litellm_params和系统环境变量都配置了 KeyLiteLLM 优先读取litellm_params里的值。这会导致你改了环境变量但请求还在用旧 Key误以为设置没生效。5.4 上游频繁 429代理服务跟着抖429 通常是触发了供应商的速率限制。除了前面说的多 Key 负载均衡另一个实用技巧是在代理里开启智能重试。LiteLLM 本身支持按Retry-After头等待后重试。还有一种思路是给模型配置更低的并发上限从源头削峰litellm_settings: max_parallel_requests: 20这个参数控制代理层同时处理多少个请求超过的直接排队或返回 429。我在内部工具里设成 20 之后上游 429 明显少了而且代价只是排队等待时间变长而不是失败率上升。5.5 日志、指标接入不成功生产部署时团队通常希望把代理的指标接到现有监控。LiteLLM 提供 Prometheus 端点/metrics你只需要在general_settings里打开general_settings: master_key: sk-litellm-master-key otel: true然后用 Prometheus 抓取http://localhost:4000/metrics即可。需要注意的是打开otel: true后会有额外的可观测性依赖如果你的环境里没搭好相关后端可能会在启动时报错。可以先不开等监控体系真正需要再补。一些实战后的个人体会LiteLLM 真正改变我工作习惯的地方不是省掉了那几行切换供应商的代码而是让“模型资源”变成了一种可管理、可计量、可分配的东西。以前模型是被硬编码在各个业务服务里的现在它是一个统一入口后面接什么模型业务方根本不需要感知。从搭建第一天起我就在配置里把所有模型都起成稳定的逻辑别名之后上游模型迭代升级我只改网关配置业务代码一行不动。最后分享一个很实用的小技巧如果你把多个供应商的“同能力模型”都映射到同一个model_name下业务代码里只写一个模型名网关自动做负载均衡和故障转移这种感觉非常爽。但这套玩法要想稳前提是先把日志、预算、超时这些基础配置搭扎实。我的建议是别想着一步到位先从一台模型一个 Key 跑通最小链路开始再逐步加模型、加负载、加预算。基础设施这东西稳比花哨重要得多。