做 AI 应用这段时间，我最大的感受不是模型不够多，而是“接模型”这件事本身变成了一个工程问题。今天要聊的 litellm，就是一套开源的 LLM 统一接入层，业内常叫它 LLM 网关。它把各家模型服务商五花八门的接口格式收敛成一套通用协议，同时把密钥管理、成本统计、负载均衡、失败重试这些“绕不开但没人想手搓”的脏活累活也一并包了。
如果你正在做多模型切换、给团队搭内部工具平台，或者只是不想让业务代码被某一家的 SDK 绑死，这篇内容应该对你有用。我会从“为什么非要加一层网关”讲起，再拆核心机制，然后直接给你一套能跑的部署配置，最后把我在实际使用中踩过的坑和排查思路都列出来。
1. 先搞清楚：litellm 到底在替我们解决什么问题
1.1 多服务商并存，接口各自为战
早期做 AI 应用，大家基本是“选一家大模型，然后一直用它”。业务代码直接调那家的 SDK，跑得通就算完事。但随着各家模型能力各有侧重、价格也在动态变化，现实的节奏变成了“这个任务适合 A 家、那个任务适合 B 家、某些场景必须用本地私有化部署的模型”。
这时候最头疼的不是“模型效果谁更好”，而是接口形态根本不统一。有的服务商走 chat/completions 风格，有的走 messages 风格，还有的坚持自己的一套流式格式。字段叫法也不一致，有的叫 max_tokens，有的叫 max_new_tokens，有的叫 top_p，有的叫 temperature 但取值范围不同。你为了同时接三家的模型，就得维护三套请求封装、三套错误处理、三套流式解析逻辑。
代码里到处是 if provider == xxx 的分支，每接入一个新服务商，业务代码就要跟着动一遍。这其实是典型的“点对点集成”陷阱：每个业务模块直接与每个服务商建立连接，连接数量是乘积增长，维护成本自然失控。
1.2 直接把服务商 SDK 接到业务代码里，为什么不行
很多人会问：那我每个服务商单独接一个 SDK，不也挺好吗？短期看可以，长期看有几个问题绕不过去。
第一是切换成本。假设今天 A 家模型涨价或者效果下降，你想切到 B 家，但凡业务代码里散落着几十处 SDK 调用，改造范围就不是改一个配置项能做到的。第二是密钥管理。真实密钥要下发给每个后端服务甚至每个客户端，泄露面变大，出了问题要挨个换，排查链路非常长。第三是缺少统一的统计口径。你根本不知道每个业务线、每个功能模块到底花了多少钱、消耗了多少 token，月底对账全靠翻控制台。
这些痛点本质上都是同一个问题的不同侧面：缺少一个统一的“接缝”。深度技术社区里有句话叫“在变化点附近加一层抽象”，而大模型服务商的多变，恰好就是最大的变化点。
1.3 litellm 的定位：模型前面的统一调度台
litellm 的核心思路，就是在这个“接缝”位置上放一个独立的服务。它自己充当中间层：对外，它暴露一套统一的接口协议和接入地址；对内，它负责把请求翻译成各服务商能理解的形式，再发出去。
从架构视角看，它同时承担三件事。第一是协议翻译：你只管用同一套协议调用，剩下的格式转换它来做。第二是请求调度：同一个模型名可以配多个实际后端，主用、备用、按权重分流都由网关控制。第三是治理能力：密钥、配额、预算、统计都挂在网关这一层，而不是散落在每段业务代码里。
这里要强调一下，litellm 不是模型托管服务，它自己不跑大模型。它更像是一个“红绿灯与调度中心”：红绿灯统一了车辆通行的规则，调度中心负责把车流量分配到不同的道路上。你的业务车流只要认准一个路口进出，后面路况再复杂，都不用司机挨个记。
2. 核心机制拆解：翻译、路由与记账
2.1 协议翻译层：把不同厂商的“方言”变成一种通用语言
litellm 对外暴露的接口，走的是业界最主流的 chat/completions 风格协议。为什么选这个而不自己发明一套？因为当前社区里大量的 Agent 框架、开源应用、前端套件都已经天然兼容这套协议，你选它作为对外标准，意味着几乎所有现成工具都能零改动接入你的网关。
真正的工作量在“对内翻译”。同一个请求进来之后，litellm 会根据你在配置里写明的服务商前缀（比如哪个是某家的、哪个是另一个家的），自动转换参数。有的家不支持某参数，网关会把它剥离；有的家的返回结构和默认枚举值不同，网关在响应侧再做一次映射。更细节的地方还包括用量字段的换算：有的家只返回 prompt_tokens 和 completion_tokens，有的家把缓存命中单独拆开算，litellm 需要把这些差异整合成结构一致的返回，你在下游拿到的永远是你熟悉的长相，不会因为切了模型而把调用方的解析逻辑打乱。
这也解释了为什么它叫“Lite LLM”而不是“统一客户端”。它把注意力放在服务端收敛，而不是每个项目里都引入一个巨型 SDK。这也更贴合微服务场景：十几个服务共享同一个网关，而不是每个服务都重复集成一遍各家逻辑。
2.2 路由与降级：不是简单的换模型，而是一整套调度策略
多模型场景下，最常见的需求其实就是“兜底”。主模型因为限流或故障挂了，能不能自动切到备胎？某个模型对单用户并发有配额限制，能不能把请求分摊到多个同配置的实例上？这些如果你自己写，其实就是再写一个流量治理系统，工程量相当可观。
在 litellm 中，你可以在 model_list 里把一个逻辑模型映射到多个实际部署。网关默认会做轮询或按配置的权重分发。某一个后端连续失败达到阈值之后，它会自动把后续请求引到下一个可用后端，这个过程对调用方完全透明。
降级策略同样配置化。比如你有一个逻辑名 main-model，背后可以先试 A 家，失败就自动切 B 家，再失败切本地私有化部署的模型。每一层的模型名、密钥、超时都可以单独指定。这样做的价值在于：可用性逻辑从业务代码中剥离，挪到配置层。以后调整兜底顺序，不需要改任何 Java、Go 或 Python 代码，只动 YAML 配置然后重启即可。
2.3 成本与用量统计：让每一笔调用都有账可查
网关存在的另一个理由是“记账”。各家模型计费规则差异很大：有的按输入输出分开计费，有的要按缓存命中折扣，还有的按图像/音频额外计费。如果没有中间层统一记录，那你做预算就非常被动。
litellm 在每次调用之后会记录模型名、请求来源、密钥归属、token 用量、当时的模型单价以及本次估算成本。写进数据库后，你就能按业务线、按团队、按模型甚至按单个密钥去查明细。这个能力在团队协作场景里特别好用：月底不用再手动翻服务商控制台，直接在网关里导出一份谁用了多少、花了多少钱的清单就行。
2.4 密钥与权限隔离：真实密钥不出网关
我见过不少团队把服务商真实密钥直接写在后端服务的环境变量里，一旦某个服务日志泄露，整批密钥都要吊销重发。litellm 的解决办法是引入“虚拟密钥”体系：真实服务商密钥只保存在网关注入的配置或环境变量里，团队成员拿到的是一把由网关签发的虚拟密钥。
虚拟密钥能绑定到某个团队或某个项目，可以限制它只能调用哪些模型、每分钟最多多少次、每个月最多多少预算。超过限制直接拒绝。这样即使某个前端密钥被泄露，影响范围也只是一个受限的虚拟密钥，而不是真金白银的服务商主账号。权限收敛到“最小可用范围”，这才是生产环境该有的姿势。
3. 实操部署：从零开始跑起一个 litellm 网关
3.1 安装与最小配置
最直接的安装方式是用 Python 包管理工具装，一条命令：
pip install litellm装完之后不用写一行代码，它自带的命令行入口就能起服务。真正的核心是配置文件，我建议从一开始就建一个 config.yaml，因为它会把路由、密钥、参数全部集中管理，比散在环境变量里清爽得多。
一个最小可跑的配置长这样：
model_list: - model_name: main-mock litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: local-chat litellm_params: model: ollama_chat/qwen2.5 api_base: http://127.0.0.1:11434解释一下关键字段。model_name 是你在应用里用的逻辑名，它跟真实服务商模型名完全解耦；litellm_params.model 是真实请求的模型标识，写法通常是“服务商前缀/模型名”；api_key 支持用 os.env/环境变量名 的方式从环境变量里取，不硬编码进配置文件；如果是本地模型，像 ollama_chat 这种前缀，还会配上 api_base 指向本地服务地址。
这样的好处是，业务层永远只认 main-mock 和 local-chat 这两个名字。哪怕某天你想把 main-mock 从这家换成另一家，改动只在配置文件里，调用方的代码一个字符都不用动。
3.2 启动服务并用命令验证
配置写好后，一条命令起服务：
litellm --config ./config.yaml --port 4000日志里会打印出网关监听地址和管理后台地址。首次启动如果你没设置访问主密钥，它会生成一把临时主密钥，建议你提前在配置里固定一个，方便后边做权限控制。
验证网关是否正常，最直接的办法是用 curl 打一发：
curl http://127.0.0.1:4000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-xxxx" \ -d '{ "model": "main-mock", "messages": [{"role": "user", "content": "你好，用一句话介绍你自己"}] }'正常情况下，你收到的响应结构和你直接请求原服务商是高度一致的，里面同样包含 choices、message、usage 这些字段。注意我用的模型名是配置里的逻辑名，而不是服务商原模型名，这说明路由已经在网关层完成了映射。
3.3 业务侧接入：只需改一个 base_url
这是 litellm 让我觉得最舒服的地方：业务侧接入成本极低。只要你项目里用的是主流的 OpenAI 风格 SDK 客户端，几乎只需要改两个东西，一是 base_url 指到网关地址，二是 api_key 换成网关下发的虚拟密钥。
下面这段示意代码以当前社区最通用的 Python 客户端为例：
from openai import OpenAI client = OpenAI( base_url="http://127.0.0.1:4000/v1", api_key="sk-litellm-virtual-key", ) response = client.chat.completions.create( model="main-mock", messages=[{"role": "user", "content": "讲个短笑话"}], ) print(response.choices[0].message.content)如果你手里还有别的服务在使用，不用改它们的鉴权方式，只要把地址和密钥换掉就能从“直连原服务商”平滑切到“走网关”。像这样统一入口之后，以后切换任何模型，对下游服务来说都只是网关内部的一次路由变化。
3.4 生产环境怎么挂：Docker 和数据库
本地跑通只是第一步，真放到生产环境，通常还要解决两件事：进程托管和状态存储。
litellm 官方提供了镜像，Docker Compose 里大致是这样：
services: litellm: image: ghcr.io/berriai/litellm:main-stable ports: - "4000:4000" environment: - DATABASE_URL=postgresql://user:password@db:5432/litellm volumes: - ./config.yaml:/app/config.yaml command: ["--config", "/app/config.yaml", "--port", "4000"]为什么生产环境要配数据库？因为虚拟密钥、团队信息、调用记录、成本统计这些状态必须持久化。不配数据库的话，密钥只存在内存里，重启就丢，记账功能也无法支持查询历史。建议直接把 PostgreSQL 挂上，虽然多一个组件，但换来的是一套完整的运营管理能力。
启动之后，你可以打开管理后台，在那里生成虚拟密钥、设置模型价格、查看实时日志。这些操作都有界面，团队里非开发人员也能上手。
4. 进阶配置实战：重试、负载均衡与统计
4.1 多副本负载均衡配置
当某个逻辑模型需要支撑的并发超过单一后端实例的配额时，可以这样配：
model_list: - model_name: load-balanced litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY model_info: mode: completions - model_name: load-balanced litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY_2 model_info: mode: completions同一个 model_name 重复出现两次，意味着这个逻辑名下有两个可用实例。网关会按轮询算法把请求分发给这两个后端。你甚至可以其中一个指向正式型号、另一个指向便宜的备用型号，实现按成本的混跑调度。
这个特性在应对突增流量时特别管用。因为扩容只是加一段配置，不需要动应用代码，也不需要让业务方知道背后有几个实例。对调用方来说，它们看到的始终是同一个模型名。
4.2 失败重试与降级的参数调优
litellm 也允许配置重试次数和降级路径。下面这段示意展示了一个常见的兜底结构：
model_list: - model_name: main-route litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: fallback-route litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY router_settings: retry_policy: timeout: 2 server_error: 2 rate_limit: 3 fallbacks: - main-route: [fallback-route]我来解释一下参数意图。retry_policy 里 timeout 表示请求超时时的重试次数，server_error 表示服务端 5xx 错误的执行重试，rate_limit 表示限流时允许重试的次数。合理设置的重试可以有效缓解偶发超时，但不要盲目调大，重试过多反而会放大请求压力。
fallbacks 是关键：当 main-route 在重试后仍然失败，网关会把请求转发给 fallback-route。这个“主-备”模式在没有人工盯着的时候是很有用的。我建议你实际压测时故意关掉主模型的密钥，观察请求是否在几秒内切到备用模型，这样可以验证降级链路是真的通的，而不是只会写进配置。
4.3 成本统计的正确打开方式
默认情况下，litellm 能记录大致的 token 用量，但“大致”不等于“金额”。要看到准确的成本数字，必须把各家模型的单价告诉网关。
两种方式。一种是在配置文件的模型条目里用 model_info 字段直接标注单价，另一种是通过管理后台的模型价格维护界面录入。示例：
model_list: - model_name: main-mock litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY model_info: input_cost_per_token: 0.00000015 output_cost_per_token: 0.0000006 mode: completions单价字段的单位是“每 token 美元”。很多刚上手的人这里会踩坑：忘记录价格，导致成本报表全是 0，或者录入的单价数量级不对，导致统计金额偏离实际账单。我建议每次接入新模型时，第一时间把官方价格页面的单价抄进配置，顺手在网关里跑一个最小请求，确认用量记录从 0 变成非 0 再往下做。
另外要注意，价格会调整，如果服务商改了报价，别只改服务商控制台里的配置，网关这边的单价也记得同步更新，不然对账时你会发现两边永远差一截。
4.4 与现有 AI 应用框架的配合
当前主流的 Agent 框架和 AI 应用模板，普遍都支持自定义模型服务地址。你只需要在框架配置里把模型服务地址改成 litellm 网关地址，模型名改成你配置的逻辑名，这个框架就能在整个项目生命周期里通过网关调用不同的模型，而不需要改框架本身。
这相当于给框架套了一层“万能插座”。以后想试验新的模型，你不需要升级框架版本，不需要改 Agent 的代码，只需要在网关配置里加一条映射。开发调试时也可以把某个逻辑名临时指向本地模型，方便离线测试和节省成本。这个玩法用在联调环境里特别省心：同一套配置，测试环境走本地模型，生产环境走正式模型，靠环境变量切换即可。
5. 踩坑记录：文档里没写清楚的细节
5.1 模型名映射错位
我在配置阶段遇到最多的报错就是“模型没有映射”。这个错基本都是 model_name 写错或漏配导致。网关只会识别 model_list 里出现的逻辑名，你在请求里传了一个没定义过的名字，它当然不知道怎么路由。
排查思路非常简单：先确认请求 body 里的 model 值，再对照 config.yaml 里 model_name 的拼写，注意大小写和下划线。还有一个隐蔽情况是，你改完配置文件却忘了重启网关，导致新加的映射根本没加载。这类问题看到没有？日志里通常会有模型列表加载的记录，重启后看一眼日志很关键。
5.2 密钥配置混乱导致的 401
有两种典型现象。第一种是业务侧直接拿着真实服务商密钥请求网关，但网关开启虚拟密钥校验后，并不认识这把钥匙。正确的做法是先去管理后台生成一把虚拟密钥，用那把钥匙访问网关。
第二种是网关注入的 api_key 本身写错了，或者环境变量名与配置里的 os.environ/ 前缀不匹配。可以这样自查：先不起网关，单独用配置里的那把密钥直连原服务商，确认密钥本身有效；再检查环境变量是否真的存在，很多部署在容器里的场景就是环境变量没传进去导致的。把“真实密钥是否有效”和“网关是否拿到密钥”分开排查，能省很多时间。
5.3 超时与流式断连
网关多了一层网络跳转，超时问题会比直连略微复杂。首先是各服务商默认响应时间不一样，代码生成类任务动辄几十秒，如果网关默认超时太短，业务方就会看到一些莫名其妙的半截响应。
我的建议是先在配置里把整体超时调到一个相对宽裕的值，比如 600 秒，同时结合 4.2 里的重试策略来控制异常情况。流式输出也是重点：开启流式之后，如果某一个服务商的错误发生在流中间，错误不是以 HTTP 状态码的形式返回，而是以流中一个错误事件的形式出现。调用方如果没做流式异常处理，就会误以为返回正常，只是内容中断了。所以流式场景下，客户端要把“完整读完”当成成功标准，而不是“能读几块算几块”。
5.4 成本数据对不上账
成本统计和真实账单对不上，是团队接入网关后最常见的运营问题。原因无外乎几个方向：单价没配或配错；降级触发时同一个请求实际上调用了两个模型，但业务侧只看到一次成功，导致报表里出现两条记录；还有缓存命中等其他计费规则没有被准确建模。
我自己的习惯是定期做一次“单品对账”：从网关导出一个模型最近七天的成本，再到服务商控制台里拉同样时间段的账单，两者对比偏差应该控制在小范围内。如果偏差大，优先检查单价和 model_info 的计费模式。永远不要把成本报表当成绝对正确，它只是辅助你发现异常的仪表盘。
5.5 网关自身安全
加了网关之后，会有新的攻击面，这一点容易被忽略。网关对外暴露的接口其实是一个统一的“钥匙孔”，一旦主密钥或高权限虚拟密钥泄露，坏处比单个业务服务泄露更大。所以生产环境至少要保证三件事：第一，主密钥绝对不要出现在客户端代码或前端页面里；第二，能给某个虚拟密钥限制的模型和预算就尽量限制，权限越小越好；第三，如果网关前面还有一层负载均衡或 Web 防火墙，记得把管理后台相关的路由限制在内网访问。
另外，网关的数据库里会存访问记录和密钥散列，数据库的访问权限也要收敛，别把连接串写进会被提交到代码仓库的配置里，用环境变量来注入。
6. 实践心得与后续扩展
用了几个月之后，我的真实感受是：litellm 最有价值的不是“统一接口”这个点，而是它把模型接入这件事从“反复改代码”变成了“改配置重启”。以前切换一个大模型可能要排一个完整迭代，现在就是改一段 YAML 的事情。团队里其他同事也开始习惯只看逻辑模型名，不再关心背后到底挂了什么模型。
如果你后续想继续扩展，我建议往这几个方向深入。一是把网关后方的模型按场景分组，不同业务线用不同逻辑名前缀，这样成本统计和权限隔离会更清晰。二是结合已有的监控体系，把网关日志里的请求成功率、平均延迟这些指标接进去，报警机制会比网关内置的简单日志更好用。三是引入更精细的预算管理，给每个团队设定月度上限，快超了自动降级到便宜模型，这件事对控制 AI 成本非常有用。
最后分享一个我在实际使用中的小技巧：每次新增一个模型，不要急着写进正式配置，先用一条独立配置在网关里跑通 curl，连同单价、超时、返回结构一起确认无误，再统一迁移。这个习惯帮我躲过了很多配置写错引起的线上问题。模型接入做到像改菜单一样简单的时候，你才会真正体会到多模型带来的自由度有多香。
