搞大模型应用的开发者，不管你是做Agent、做RAG还是做企业内部AI工具，最近应该都被同一个问题折磨过：各家模型服务的接口风格不一样，参数千奇百怪，换个模型就得改一版代码，还要自己处理超时、重试、成本统计。我之前在好几个项目里都栽过这个跟头，直到把 litellm 引入到工作流里，才算是把这块彻底理顺了。这个工具说白了就干一件事：把市面上主流的模型接口统一成一套标准格式，你代码里只认这一套规范，底层想接哪个平台、想换哪个模型，只在配置层改，业务代码基本不动。对于做AI应用落地的人来说，它解决的恰恰是最烦人、最磨人的那一堆“脏活”。
这篇文章我会从设计思路、快速上手、核心功能拆解、生产环境经验、常见排错这几个角度，讲清楚 litellm 到底怎么用，以及在实际项目里哪些地方最值得注意。内容更适合已经在接模型接口、但被多平台适配折磨过的开发者，哪怕你目前只用一家服务，也建议看完，因为你迟早要面对“多模型”这个问题。
1. LiteLLM到底解决什么问题
1.1 多模型API接入的“烦躁期”
先说一个很真实的场景。假设你正在开发一个智能客服系统，最开始只接了一家模型服务商，代码写得很顺手，消息格式、返回结构都摸清了。过了一阵子领导说要引入另一家模型做对比测试，你打开对方的文档一看，心就凉了一半：接口路径不一样，报文格式有差异，鉴权方式也不同，连流式返回的字段名都对不上。
这意味着什么？意味着你不得不写一层适配逻辑，把A平台的请求转换成B平台的请求，再把B平台的响应转换回统一结构。如果后面再接第三家、第四家呢？每一家都要重复这套工作。我见过一个项目里，光是适配不同模型平台的代码就攒了两千多行，维护起来愁死人。而且这类代码对业务毫无价值，本质上就是重复劳动。litellm 正是冲着这个痛点来的，它把接口适配层下沉为通用基础设施，你对外只暴露一套统一的SDK或API，背后连接各家平台。
1.2 从SDK到网关的两种打开方式
litellm 提供了两种主要的使用形态，理解这两点对后面怎么选型很关键。
第一种是直接调用它的 Python SDK。你在项目里import litellm，然后调用litellm.completion()或litellm.acompletion()，传入模型名、消息列表、参数，它就会自动识别该用哪家平台去请求。这种方式适合在Python项目里直接改代码，侵入小，动一行就能换模型。
第二种是把 litellm 作为独立服务跑起来，它的官方叫法是“代理服务器”。启动后，本机会暴露一个本地HTTP服务，兼容业界主流的接口规范。你的业务代码只对着这个本地服务发请求，就好像在用一个统一的模型API；至于实际流量转发到哪家平台，由代理服务根据配置决定。这种形态适合中大型项目，因为它能集中管理密钥、做负载均衡、统一记录日志和成本，多个服务还可以共用同一个模型入口。
我在实际项目里一般推荐第二种。原因很简单：SDK方式适合单机脚本和个人项目，但只要你的系统里不止一个服务在调用模型，或者你希望把密钥集中在某处而不是散落在各环境变量里，独立网关的优势就非常明显。
1.3 为什么值得选它而不是自己封装
有人会想，我自己写一个封装层不是也行吗？确实行，但前提是你的项目足够简单，而且未来不打算增加新模型平台。一旦规模上来，自己封装会面临三个绕不开的问题。
第一是兼容范围。litellm 已经对接了众多主流平台，这里面涉及很多细节：不同平台的鉴权头、请求体结构、返回格式、错误码、限流策略、流式协议，甚至是某些平台对参数名称的特殊处理。这些经验是长期积累出来的，你自己从零开始踩坑，时间成本极高。
第二是生态能力。litellm 不只是做转发，它还有成本计算、模型别名管理、负载均衡、故障回退、预算预警这些开箱即用的能力。这些都是生产环境需要的功能，自己写的话工程量不小。
第三是维护升级。模型平台的一些接口规则是变动频繁的，litellm 社区一直在跟进这些变化。自研封装层最大的风险在于：某个平台的接口悄悄变了，你的线上服务毫无征兆地出问题，而你发现这个问题可能需要等到用户报障。
2. 从零开始：安装与首次接入
2.1 前置条件与安装细节
litellm 是基于 Python 的工具，所以环境里需要 Python 3.8 或更高版本。我建议在虚拟环境里安装，避免和系统 Python 或其他项目产生依赖冲突。安装命令非常简单：
pip install litellm装完之后可以验证一下版本：
python -c "import litellm; print(litellm.__version__)"这里有一个小提示：litellm 的依赖中包含uvicorn和fastapi，用于跑代理服务。如果你只是在代码里调用 SDK，这些依赖也会一并装上，稍微有点膨胀，但不用太在意。
安装完成之后，如果你要调用各家模型平台，就需要配置对应的 API 密钥。litellm 支持通过环境变量传入密钥，例如：
export MY_API_KEY="sk-xxxxxxx"密钥的具体名称取决于你对接的模型平台的规范，一般对应平台的官方变量名。这样配置的好处是密钥不会写进代码仓库，部署的时候集中管理比较安全。另外一个细节是，如果你的代理服务需要配置自己的访问密钥（也就是别人调用你的网关时要带上的钥匙），可以用LITELLM_MASTER_KEY这个环境变量来设置。
2.2 用Python SDK完成首次请求
最简单的用法是直接在脚本里调用completion接口，传入模型名和上下文消息：
from litellm import completion messages = [ {"role": "system", "content": "你是一个简洁的助手。"}, {"role": "user", "content": "用一句话解释什么是负载均衡。"} ] response = completion( model="my-platform/my-model-name", messages=messages, temperature=0.7 ) print(response.choices[0].message.content)是的，就这么几行。你不需要关心目标平台的鉴权细节、请求体长什么样、返回要怎么解析，litellm 全帮你处理好了。返回对象的结构是统一规范的，choices、message、content这些字段直接可取。
第一次跑通之后，你可能想试试流式输出。只需要把stream=True传进去，然后迭代返回的数据块：
response = completion( model="my-platform/my-model-name", messages=messages, stream=True ) for chunk in response: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="")流式场景下，迭代出来的每个 chunk 也有统一的格式，不用针对不同平台分别处理。这一步跑通了，后面做聊天机器人、做流式输出的 Agent 工具都会非常顺手。
2.3 把LiteLLM跑成独立服务
SDK 的用法虽然简单，但要在生产环境里规模化使用，我建议把它作为独立服务部署。启动代理服务只需要一行命令：
litellm --model my-platform/my-model-name --port 4000启动之后，它会在本地 4000 端口监听 HTTP 请求。默认的接口风格是兼容行业标准格式的，所以那些原本面向标准接口开发的项目，只需要把 base_url 指向本地地址，不需要修改太多代码。举个例子，原本项目里请求模型的地址可能是https://api.example.com/v1，现在换成http://localhost:4000，模型名传你配置文件里定义的别名，其他照旧。
这时候可以先用 curl 验证一下：
curl http://localhost:4000/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-master-key" \ -d '{ "model": "my-model-name", "messages": [{"role": "user", "content": "你好"}], "stream": false }'返回内容里的choices[0].message.content就是模型回复的内容。你会注意到，这个请求的报文结构、返回结构，完全不关心后端实际接的是哪家平台。这就是网关存在的意义：业务端和模型端彻底解耦。
2.4 用配置文件管理模型目录
如果只用--model参数指定单个模型，那它和直连就没多大区别了。litellm 真正好用的地方在于，可以通过 YAML 配置维护一个“模型目录”，把多个平台、多个模型、多组密钥都集中管理起来。
下面这个是我常用的最小配置样例：
model_list: - model_name: chat-model litellm_params: model: my-platform/my-model-name api_key: os.environ/MY_API_KEY model_info: supports_function_calling: true cost_per_token: 0.000002我用model_name定义了一个对外暴露的别名，业务代码不用关心底层具体调用了哪个模型。litellm_params里的model字段是实际模型名，api_key引用了环境变量里的密钥。model_info里可以写一些模型能力描述，比如是否支持函数调用、单token成本是多少，这些信息后面会用于路由和成本统计。
写好配置文件后，启动服务的方式变成：
litellm --config ./config.yaml之后你在业务代码里请求model字段传chat-model，网关会根据配置找到实际模型来调用。以后想换模型，只改配置文件，不动业务代码。
如果你有多个模型，就往model_list里追加节点，甚至可以配置同一个别名对应多个模型实例——这就为后面的负载均衡和故障转移打下了基础。
3. 核心功能的拆解与实战
3.1 统一格式转换是怎么做到的
聊一个很多用户好奇的问题：litellm 是怎么做到统一格式的？原理其实不复杂。每一家模型平台，本质上都是暴露了一组 HTTP 接口。litellm 内部为每个平台实现了一套“入站转换”和“出站转换”，入站转换把标准格式的请求转换成目标平台的请求结构，出站转换则把目标平台的响应转换成标准结构。
举个例子，你调用completion时，litellm 先拿到标准消息列表，然后根据model前缀识别出要对接的目标平台，把消息、参数、鉴权信息拼装成该平台要求的报文，发出请求；收到响应后，再把返回的文本、结束原因、Token用量等信息统一成标准对象，才返回给调用方。
这里面最容易被忽略的是异常处理。不同平台的错误码各不相同：有的用 4xx 表示限流，有的用 5xx 表示服务内部错误，还有的返回结构里藏了错误详情。litellm 会把它们统一包装成标准异常对象，并且保留原始错误信息，方便排查。这意味着你在业务代码里只需要捕获一种异常类型，就能覆盖所有平台的报错场景。
模型名里一般会带平台标识前缀，格式是平台名/模型名。但是我们也经常需要在配置里通过litellm_params把某个模型显式映射到指定平台，这样在别名体系下更灵活，不会把底层路由信息暴露给业务方。
3.2 模型路由与故障转移的配置实例
生产系统最怕单点。如果只绑定一家模型服务，它一限流，你的业务就跟着瘫痪。litellm 提供了一种非常实用的能力：同一个对外模型名，可以关联多个实际模型，并把它们做成主备关系或负载均衡关系。
我习惯的做法是：在配置里给同一个model_name配置两个或更多的litellm_params，每个指向不同的平台或不同的模型。然后配置路由策略：
router_settings: routing_strategy: "simple-shuffle" num_retries: 2 timeout: 30 cooldown_time: 60routing_strategy代表负载均衡策略，默认有随机轮换之类的选项；num_retries表示单个请求失败后最多重试的次数；timeout是每次请求的超时时间；cooldown_time表示某个模型连续失败后，进入“冷却期”的时间，冷却期内会自动把这个模型从候选列表剔除。
这套配置的实际效果是：当业务方请求chat-model时，网关自动挑选一个可用模型执行；如果这个模型超时或报错，网关会自动重试另一个模型，用户基本感知不到故障。这个机制在关键业务里尤其好用。
一般建议把不同的模型分配给不同优先级的场景：比如快速模型处理高频低复杂度请求，高精度模型处理复杂指令。你可以针对不同model_name配置不同的路由策略和成本设置，灵活度很高。
3.3 成本追踪与用量统计
你有没有遇到过这种情况：月底看账单，发现模型调用费用比预期高出一大截，但翻遍日志也搞不清是哪个业务线花掉的。litellm 内置了成本追踪能力，它的模型信息表里记录了众多常见模型的 token 单价，每次请求返回后会通过 Token 用量乘以单价得出费用，这个过程对调用方是透明的。
使用 SDK 时，你可以在每次请求后直接查看响应里的usage信息，包括输入 token 数、输出 token 数，并且可以通过litellm.completion_cost()函数来计算花费：
from litellm import completion, completion_cost response = completion( model="my-platform/my-model-name", messages=messages ) cost = completion_cost(completion_response=response) print(f"本次请求花费: {cost} 美元")如果你用的是代理服务器，litellm 还可以结合数据库做更细粒度的成本统计，按用户、按标签、按天聚合消耗。我在项目里通常给每个业务请求附加一个metadata，里面写业务线名称，后续查看成本报表时就能精确到具体业务模块。这个能力对做内部成本分摊、做预算管控极其重要。
有一点要提醒：成本数据的准确性依赖配置里cost_per_token或内置单价表的版本，不同时期的单价可能变化。因此关键模型上线前，最好核对一眼 litellm 内置的价格信息是否最新，或者在配置里手动覆盖价格参数。
3.4 和Agent、工具调用等场景的配合
最近做 Agent 应用的人越来越多，而 Agent 的核心能力之一是工具调用（或者叫函数调用）。litellm 对这类场景的支持需要注意两点。
第一，消息格式上要支持工具定义的传入。标准格式里，开发者会把可用工具以 JSON 结构传给模型，模型返回“是否调用某个工具、参数是什么”的意图，litellm 会把这个意图原样透传回来。你只要在调用时把工具列表传给tools参数即可。
第二，不是所有模型都原生支持工具调用。如果你配置的模型不支持，通常会出现返回格式异常的情况。解决办法有两个：要么换一个支持工具调用的模型；要么在业务侧做“提示词式的工具调用”兜底，也就是把工具描述塞进系统提示词，让模型用特定 JSON 格式返回。前者体验好，后者兼容性强，两者结合使用效果最好。
我还有一个经验：在 Agent 场景里，建议在配置文件中准确声明每个模型的supports_function_calling能力。litellm 的路由器在做模型选择时，会把这类元信息纳入考量，避免把带工具调用的请求路由到不支持工具的模型上。
4. 上生产之前：性能、安全与运维细节
4.1 并发与性能调优
网关本身是一个反向代理，如果处理不好并发，就会成为新的瓶颈。litellm 代理服务底层是基于异步框架的，在普通配置下处理几百个并发请求没什么压力，但仍有一些值得调优的细节。
第一个是超时时间。模型请求往往很慢，尤其是长文本输出，几分钟都有可能。你要确保反向代理层和应用层配置的超时时间足够大，否则请求会被中途掐断。我一般把网关层的 timeout 设置为 30 到 60 秒，具体看业务场景。
第二个是连接池。高并发时，如果网关到模型平台之间的连接复用不够，握手开销会拖慢整体响应。litellm 内部使用了连接池机制，但你可以通过调整环境变量来扩大连接池规模。具体参数名称建议查一下官方配置说明。
第三个是异步调用。在 SDK 模式下，如果你的业务代码已经是异步的，建议使用litellm.acompletion()而不是completion()，避免阻塞事件循环。异步模式在高吞吐场景下提升明显，但注意链路里的所有环节都要保持异步，否则会出现“假异步”。
4.2 密钥管理与配置隔离
既然 litellm 作为网关集中了所有平台的密钥，那密钥安全就变成了重中之重。我有几条原则：
不要把真实密钥写进仓库。环境变量、密钥管理服务、容器平台的密文配置都可以。配置文件里引用环境变量是一个稳妥的做法，比如api_key: os.environ/XXX。
区分网关调用密钥和业务访问密钥。业务端访问网关时需要一个访问凭证，叫 “master key”；网关访问各模型平台时用的是真实的平台密钥。两种密钥分开管理，即使业务端的 key 泄露，也拿不到平台密钥。
不同环境使用不同配置。开发环境、测试环境、生产环境，模型目录和密钥应当完全隔离。我通常会把配置拆成三份，部署时按环境注入。这样改测试配置不会影响到生产，误操作的概率会小很多。
4.3 可观测性与日志
网关这种中间层最容易出问题，因为它承接了大量转发逻辑。litellm 提供了比较详细的操作日志，包含请求时间、模型名、耗时、Token 用量、成本、状态码等信息。建议在应用侧把日志采集起来，接入类似 ELK 或云日志服务，方便做集中检索和告警。
日志里最值得关注的三类信息是：高延迟请求、失败重试记录、成本异常增长。我一般都会设置告警规则，例如“近5分钟失败率超过 10%”或者“单次请求耗时超过 60 秒”。这类告警往往比业务层的报错更能提前暴露问题。
另外，litellm 的/health健康检查端点可以用来做网关存活探测，负载均衡器或容器编排平台可以基于这个端点做自动重启。
4.4 部署落地的几处细节
部署 litellm 本身没有太高门槛，但有几个小细节容易忽略。
第一，如果服务跑在容器里，记得把日志目录和持久化数据目录挂载到宿主机或持久卷，否则容器重启后数据丢失。
第二，如果要接入数据库做历史记录，建议选一个事务能力稳定的关系型数据库，初始化表结构时留意使用官方推荐的迁移方式，别手动乱改。
第三，模型配置的变更应该走发布流程，而不是直接在线上手改配置文件。因为配置错误可能导致网关启动失败，影响所有依赖它的业务。稳妥的做法是先在测试环境加载新配置，跑一遍冒烟测试再上线。
5. 常见问题速查与排错心得
5.1 高频报错和排查对照表
我把实际使用中碰到比较多的报错整理成了下面这张表，方便你遇到问题的时候快速定位。
| 现象 | 可能原因 | 排查与解决 |
|---|---|---|
| 请求返回 401 | 平台密钥不正确或未正确配置 | 检查环境变量是否注入，检查配置文件里的 api_key 引用方式 |
| 请求返回 404 | 模型名不存在或平台接口路径变化 | 先确认模型名是否拼写正确，再用 curl 直连平台接口确认路径是否正常 |
| 返回超时 | 模型响应太慢或网关超时设得太短 | 调大 timeout 参数，检查网络链路是否正常，最好能抓包定位 |
| 流式输出不完整 | 客户端与网关之间的代理缓冲 | 关闭代理缓冲，或者把 X-Accel-Buffering 设为 no |
| 成本统计数据为 0 | 配置缺少单价信息 | 在 model_info 里显式补充 cost_per_token，或用 litellm 的重算工具刷新单价表 |
| 错误信息显示某平台不支持某参数 | 模型能力有限 | 换模型，或将参数在配置层做降级处理 |
| 网关启动报配置解析错误 | YAML 格式问题 | 检查缩进和特殊字符，特别是os.environ/这类映射是否正确 |
这张表里的问题，一大半都是配置问题，而不是工具缺陷。所以遇到问题时，先检查配置，再检查密钥，最后怀疑代码，能省很多时间。
5.2 换模型却发现行为不一致的排查思路
很多人会遇到一种情况：把后端模型从 A 换成 B 后，同样的业务代码，输出风格变了个样，甚至返回结构都不太对劲。这个不一定是 bug，而是不同模型本身的输出习惯、参数支持程度不同。
我的排查思路是：先通过网关用同样一组消息分别请求两个模型，对比原始输出。如果差异仅仅体现在文本风格上，那属于模型特性；如果差异体现在返回字段、格式上，那多半是能力差异，比如一个模型原生支持工具调用，另一个不支持。
还有一种常见情况是，用了新模型之后，某些参数被静默忽略。比如有的平台支持max_tokens，有的平台把对应字段叫max_output_tokens，如果你的配置没有映射好，模型就会用默认行为。这种问题最隐蔽，建议换新平台时，先做一次参数兼容性验证，把常用参数都试一遍，记录哪些生效、哪些无效。
5.3 最后的几条实操提醒
最后分享几个我在项目里沉淀下来的小习惯。
一是模型命名规范要提前定好。建议用“场景-用途”的方式定义别名，比如chat-support、agent-router、embedding-search，而不是直接用底层模型名当别名。这样后面调整模型、做灰度替换的时候，代码里不用改任何东西。
二是每次升级 litellm 版本之前，先在测试环境把全量用例跑一遍。虽然它整体迭代质量不错，但接口细节偶尔会有调整。我踩过一次版本升级后流式返回格式有细微变化的坑，从那以后严格执行先测后升。
三是把“成本异常”看作一种线上告警来看待。我会定时跑一个任务，拉取前一天的分业务成本报表，超出阈值的部分自动通知到钉钉群。这个机制看起来简单，但实际救了团队好几次，避免了大额预算超支。
四是在团队内部维护一份“模型能力清单”。哪个平台支持上传文件、哪个模型支持图像输入、哪个接口支持 embedding，都整理成表格。对接新业务时，先在清单里查能力，再去写代码，能少踩很多坑。
litellm 不是一个花哨的工具，它更像一个低调的底座。真正用起来之后，你会发现多模型接入这件事变得不再让人头痛，省下来的时间可以拿去做更核心的业务逻辑。希望这篇文章能帮到正在为模型 API 适配发愁的你。
