很多人第一次看到“litellm”这个词，都会下意识念成“little lm”——一个小模型。其实它跟“模型大小”没关系，它是一个大模型API网关，中文圈子里常叫它“统一代理层”。我大概半年前开始重度使用它之后，最大的感受是：如果你手里同时要对接两个以上的大模型API，没有litellm这类东西，你的代码库会膨胀得非常痛苦。
简单说，litellm做的事情就是“一个接口管所有模型”。它把不同厂商的模型API全部重新封装成一套你熟悉的调用格式，让你只需要写一套代码、维护一套配置，就能在十几个甚至几十个模型之间自由切换。对于个人开发者、中小团队甚至一些已经在跑生产环境的业务方来说，这玩意儿解决的是非常具体的工程痛点。
这篇文章我会从“它到底解决了什么问题”开始，然后逐步拆解它的核心功能，手把手演示本地部署和两种接入方式，最后分享一些我们在实际运行中踩过的坑和排查思路。如果你正在为“怎么把模型的API统一起来”发愁，或者你只是想少写点重复代码，这篇内容应该对你有用。
1. 为什么你需要一个模型接入层
1.1 接口不统一是真正的工程灾难
先说一个最朴素的事实：各大模型的API调用方式不统一。有的用chat/completions，有的用messages.generate，有的返回结构是choices[0].message.content，有的则是candidates[0].content。参数名也不同，有的叫temperature，有的叫top_p，还有的设置max_tokens的方式完全不一样。
我那个阶段手上同时维护了三个业务：一个是用某头部模型的接口做客服问答，一个是用另一家模型做文本分类，还有一个是给内部工具做的摘要服务。三个业务各自封装了一套HTTP请求逻辑，各自的超时时间、重试策略、错误处理全是各写各的。这还只是三个模型，等后面你想试验第四家、第五家的时候，最可怕的不是新增代码，而是任何一次模型迭代或更换都要同时改多个地方。
litellm的核心价值就是把这一堆乱七八糟的“方言”统一成一套“普通话”。你说普通话，它来翻译给各个模型听。这听起来简单，但是做得好非常难，因为各家模型的鉴权方式、请求超时、限流语义、返回格式差异是真的不少。
1.2 “网关”模式比“SDK”更值得重视
litellm提供两种使用方式：一种是在你的代码里直接import它的Python SDK，另一种是起一个API Server作为代理网关。很多人用SDK只是因为不想写重复代码，但我个人更推荐你花半小时把它的网关模式搭起来。
SDK模式适合快速试验、脚本编排、本地小工具。你把它当做一个统一调用的函数库，在Python代码里直接from litellm import completion，然后传不同的model名就行，确实方便。
网关模式就完全不同了。它起一个本地HTTP服务，让你公司的所有业务系统都去对接这个服务，然后由这个服务统一转发到真实的模型厂商。相当于你在公司内部搭了一个“AI网关”，所有业务代码里写的都是同一个base_url，请求统一走一个入口。这样带来的好处是：账号密钥不用散落在每个服务里，统一在网关管理；限流和熔断可以做在网关层；模型切换根本不改业务代码，改一下网关配置就行。
对于中小团队，SDK模式是“一个人方便”，网关模式是“一群人方便”。我自己是从SDK用起，但真正体验到生产力提升，是切换到网关模式之后。
1.3 选型时的几个关键判断点
在选择是否引入这样一个接入层之前，我的建议是你先想清楚三个问题。
第一，你的模型调用量是否多元化。如果你们只固定用同一家模型，一年到头没有换的可能，那确实没必要引入额外的层。引入任何中间层都是有成本的，哪怕它是开源的。
第二，你是否需要“可替换性”。换模型不是简简单单改个名字的事，不同模型在能力、延迟、定价上都有差异，你需要做AB对比测试。实际上很多团队引入网关的初始动机就是“不想在试新模型的时候重写一轮代码”。
第三，你的团队有没有人愿意维护这个基础设施。litellm虽然开源，但它毕竟是一个需要鉴权配置、需要监控、需要升级的服务，不是一个扔在那不管的静态库。如果有人维护，它会非常省心；如果没人维护，它可能会成为新的“技术债”。
2. 核心功能拆解与原理分析
2.1 统一模型路由：从provider到model的映射机制
litellm最基础的模型路由逻辑可以用一句话概括：你指定一个模型名，它来找到对应的provider并按规则转换格式。
举例来说，你在代理配置里写：
model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY这里的逻辑是：对外暴露的模型名叫gpt-4o，但真正要调用的后端是openai/gpt-4o。litellm_params里还可以写很多额外参数，比如api_base、max_tokens、timeout等等。
什么是provider前缀？openai/、anthropic/、bedrock/、vertex_ai/这些前缀就是拼音里的声母，后面跟的是韵母。litellm通过前缀来判断使用哪一套适配逻辑。它支持的服务商数量非常庞大，这里没必要全列，你只需要知道一件事——绝大多数你能想到的大模型，它基本都覆盖了。
2.2 自动重试与模型fallback的价值
“请求失败自动换一个模型重试”这是litellm特别实用、也是许多人用它做生产环境的首要理由。
模型服务是可能出各种问题的：限流报错、超时、服务端5xx、负载过高返回不稳定。你不可能因为一次请求失败就直接向用户展示“我挂了”。litellm允许你在配置里指定retry_policy和fallbacks，从而实现：第一次请求某模型失败，自动换另一个模型再试。
这里有个容易混淆的概念——自动重试和fallback是两码事。重试是同一个模型再试一次，fallback是换成另一个模型。实际生产里，你可以先开启重试，等重试都失败了再触发fallback。我曾经在一次线上事故里靠这个机制稳定扛过三天的模型服务降级，用户体验基本无感。这个机制绝对值得每一个用模型的团队都拥有。
2.3 限流、负载均衡与预算控制
网关模式还内置了限流控制。你可以给不同的API key设置不同的访问速率，比如rate_limit_per_minute: 100。内部会有一个线程安全的计数器来配合滑动窗口逻辑实现限流。
负载均衡则是针对同一个模型配置了多个deployment的情况。你可以在model_list里写入同一个model_name对应多条litellm_params，然后通过routing_strategy参数来选择simple-shuffle（随机）、least-busy（最少请求数）或usage-based-routing（基于消耗量的路由）。
预算控制这块，很多老板关心的其实是成本。litellm可以配合它是一个测量真实token消耗的情况来统计。配置了max_budget之后，网关会在预算耗尽时拒绝新请求或者降级。这一块需要模型服务商返回usage信息，litellm才能正确统计，所以建议在配置时不要随意关掉usage读取。
2.4 日志与可观测性实现
可观测性是网关存在的又一个理由。litellm默认会把每次请求的模型、输入token、输出token、延迟、状态码、花费这些信息记录到本地数据库。它支持SQLite这个轻量级方案，也支持更正规的PostgreSQL。
说个实际的场景：之前我们在排查某个模型响应质量问题时，正好用到它记录的日志来对比同样prompt在不同模型上的返回、耗时、token消耗。如果没有这些结构化日志，排查这类问题基本靠猜。
2.5 一个特别的细节：缓存机制
litellm支持缓存，包括内存缓存和Redis缓存。缓存模式有sdk_ttl_cache、redis、redis_semantic_cache等。简单理解就是：相同的prompt，在一段时间内直接返回结果，不重新调用模型。
这听着很美好，但我必须提醒一句：LLM请求的“相同”概念没那么可靠，尤其当你使用语义缓存时，缓存命中的判断不是精确匹配，而是基于向量相似度。这个在特定场景下可能带来奇怪的副作用。如果只是想降低重复计算成本，我更建议先用TTL缓存，在绝对能接受prompt近似匹配时才考虑语义缓存。我自己对这个功能一直比较谨慎。
3. 从零部署：安装、配置与API接入实操
3.1 快速起步：安装litellm并理解进程结构
安装litellm本身很简单。它是Python包，所以你只需要一个Python环境（官方建议Python 3.8以上），然后执行：
pip install 'litellm[proxy]'注意这个[proxy]很重要，它会额外装好运行代理服务所需的依赖，比如Flask、数据库驱动等。如果你只是用SDK模式，pip install litellm就够了。但既然要跑网关，直接用带proxy的组合包省事很多。
安装完成后，你会在环境里多出一个叫litellm的命令行工具。整个进程结构就是“一个HTTP服务 + 一堆后端转发逻辑 + 数据库存储”，没有其他复杂的组件，部署起来直觉上就很轻。
3.2 最小可用配置：YAML就是这样写的
我们需要创建一个配置文件。先看一下最小能跑的例子：
model_list: - model_name: my-gpt litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: my-claude litellm_params: model: anthropic/claude-3-5-sonnet-latest api_key: os.environ/ANTHROPIC_API_KEY litellm_settings: drop_params: true set_verbose: true general_settings: database_url: sqlite:///litellm_config.db这个配置里干了四件事：注册了两个模型、允许litellm在调用时丢弃它不认识的参数、开启详细日志、挂上一个SQLite数据库。
os.environ/OPENAI_API_KEY这种写法表示从环境变量里读密钥，密钥不要直接写死在配置里，这是常识。你启动服务前在shell里export好相应的环境变量就行。
然后启动网关：
litellm --config config.yaml --port 4000跑起来之后，你的网关默认为http://localhost:4000。这个端口是默认的，你可以按需改。
3.3 和OpenAI SDK风格一致的接入方式
我用代码来说明如何接入这个网关。因为litellm本身就是为了兼容这套生态，接入方式和用OpenAI官方库几乎一样：
from openai import OpenAI client = OpenAI( api_key="sk-anything", base_url="http://localhost:4000" ) resp = client.chat.completions.create( model="my-gpt", messages=[ {"role": "user", "content": "你好，请介绍一下你自己"} ] ) print(resp.choices[0].message.content)注意这里的api_key是你自己在网关配置的虚拟key，不是真实模型的密钥。真实密钥收在网关里，网关负责与真实模型交互。业务侧不知道真实密钥的存在，安全性大大提升。
另外这里的model参数填的是你在配置文件里对外暴露的my-gpt，而不是真实的gpt-4o。换模型的时候，只需要改网关配置里my-gpt对应的litellm_params.model名，或者干脆再发一个my-gpt-2做AB，业务代码完全不用动。这就是统一接入层的实际收益。
这一段你如果跑通了，相当于已经完成了最核心的“统一调用”。你再也不需要记住某一家模型特殊请求头怎么设置，因为litellm把这些都处理了。
3.4 用Python SDK模式快速调用
如果你不想起网关，只想在脚本里快速用，可以直接用Python SDK模式：
import litellm response = litellm.completion( model="openai/gpt-4o", messages=[ {"role": "user", "content": "你好"} ], api_key="sk-xxx" ) print(response.choices[0].message.content)SDK模式里，model参数必须写完整的provider/model_name格式，比如openai/gpt-4o或anthropic/claude-3-5-sonnet-latest。它直接从环境变量读取密钥，或者你显式传api_key。
还有一点值得提的是异步调用。我的经验里，生产环境异步是必须的，litellm也支持：
import asyncio import litellm async def main(): resp = await litellm.acompletion( model="openai/gpt-4o", messages=[{"role": "user", "content": "异步测试"}] ) print(resp.choices[0].message.content) asyncio.run(main())另外还有一个litellm.batch_completion，用于并发批量请求。在跑大规模评测或者批量离线任务时，这个函数能有效提高吞吐。
3.5 实际运行效果的现场观察
我按上面的配置跑过一次最小实验。起了网关后用OpenAI SDK发请求，几乎没有任何额外感知，延迟相比直连只多了几个毫秒。但如果你看网关的日志，就能看到它已经记录了这个请求经过的路由、真实模型名、token消耗和费用估算。这种“代码没多写一行，但所有治理都收口到一个位置”的感觉，就是使用接入层的底气。
顺手再提一下日志查看方式，方便你验证：
litellm --config config.yaml --port 4000 --detailed_debug这会输出非常详细的请求链路日志，比如真实请求的URL、请求头、返回内容片段、耗时等。正式环境不建议全程开着这种详细日志，它太吵了，但调试阶段非常有用。
4. 高级玩法：fallback路由、参数计算与成本策略
4.1 一个标准的failover配置长什么样
模型服务不可能永远稳定，能被可靠替代的模型链条才算稳健。我目前在生产环境用的fallback配置框架是这样的：
model_list: - model_name: main-model litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: mode: completion supports_function_calling: true - model_name: fallback-model litellm_params: model: anthropic/claude-3-5-sonnet-latest api_key: os.environ/ANTHROPIC_API_KEY router_settings: model_group_alias: primary: main-model fallbacks: [ { "primary": "main-model", "fallbacks": ["fallback-model"] } ]注意我用了model_group_alias，定义了对外统一叫primary，这比硬编码main-model更灵活。业务侧只知道“我在调用主模型”，不知道主模型到底是哪个。某一天你想把主模型从gpt-4o换成另一个模型的更新版本，业务代码还是传primary，配置改一下就行。
fallback触发的条件比你想的更丰富。它不仅是在5xx错误时触发，还可以在限流、超时、上下文长度超限等场景下触发。这一点很关键，因为有些模型在特别长的对话里会返回“上下文长度超限”错误，这种时候fallback到一个上下文容量更大的模型，往往是更优雅的处理方案。
4.2 参数计算：重试次数、超时与上限的选择
这种配置不能拍脑袋，我来分享一个简单的计算思路。
先看超时。模型接口响应时间的分布很宽，但大多数正常请求会在10至20秒内返回。如果你把timeout设成60秒，意味着你要等满60秒才知道这次请求失败。用户体验上，迟迟不响应比快速失败更难受。我通常把timeout设为30秒左右，兼顾长输出的场景，又不至于无限等。
再看max_retries。如果网关你对同一模型重试3次，每次都要消耗完整超时时间，那最坏情况是90秒过去用户还在等。所以我的做法是：单次请求max_retries保持2次以内，此时搭配fallback到不同模型往往更划算。因为如果第一个模型真的有问题（连续失败），说明它短时间状态不好，再重试同模型意义不大，不如换一个后端。
还有一个容易被忽略的参数是allowed_fails。在负载均衡场景里，它表示一个deployment在连续失败多少次后会被标记为不健康，之后一段时间内流量会优先避开它。这个值我建议开到2或3，太高则无法快速摘掉故障节点，太低则会因为偶发抖动就把节点摘了。
4.3 成本控制：用量数字如何算清楚
成本是老板一定会问的事。litellm在日志里能记录token与费用，但这个费用是怎么来的？它主要依赖模型返回的usage字段里包含的token数，再乘以litellm内置的单位价格表。如果你用的是自定义的私有化模型，这个费用估算就不一定准确，需要你自定义价格。
这里给一个具体的计算示例。假设你一次请求消耗了1000个输入token和2000个输出token，模型定价是输入$5/百万token，输出$15/百万token，那这次请求的成本是：
(5 \times 1000 / 1000000 + 15 \times 2000 / 1000000 = 0.005 + 0.03 = 0.035)美元。
如果你用litellm的费用统计面板看月度总结，它其实就是在逐条累加类似的估算值。这个估算值虽然不是账单级别的精确，但用来做预算评估和模型选型对比，精度完全足够。
4.4 生产环境的安全加固与外部暴露
如果你要把网关暴露在公网或内网供多个团队共用，一些安全设置不能省。
第一，至少开启虚拟key验证。在litellm里，可以通过管理API生成一个sk-开头的虚拟key。业务侧用这个key调用网关，而真实模型密钥保存在网关环境变量中。这样就算虚拟key泄漏，损失的也只是网关这一层的访问权限，真实模型账号不受直接影响。
第二，配合Auth配置。如果有条件，建议把网关放在内网或通过访问控制中间层来保护。它不是必须的，但多一层防护总没错。生产环境暴露在公网且没有任何鉴权保护的服务，一旦被发现扫描端口，后果会很麻烦。
第三，定期升级版本。litellm维护非常活跃，几乎每周都有更新。它修复问题的速度很快，但前提是你愿意花五分钟跑一下pip install --upgrade litellm[proxy]。我自己习惯每月做一次升级并跑一遍基础链路测试，成本很低，收益却很实在。
5. 实战中的典型问题与排查记录
5.1 模型反复报错“model not found”
这台排查记录很常见。配置看起来没问题，但请求时总是提示找不到模型。原因八成是理解错了model_name与model的区别。
你在业务侧请求里传的model参数，必须等于配置中model_list里的model_name字段，不是litellm_params里的model值。前者是对外暴露的别名，后者是真实模型映射。比如配置里model_name: my-gpt，业务侧就传my-gpt，不要传成gpt-4o。
排查方式也很简单，查看网关日志中实际打印的路由名称，确认请求落在了哪个model_name上。
5.2 虚拟key鉴权失败的排查
我一开始自己跑通网关后，用OpenAI SDK直接调用，没设置任何虚拟key，结果每次请求返回401。原因很简单：litellm网关默认会校验请求头的Authorization字段。如果你的配置没有开放无鉴权访问，那么必须提供一个有效的虚拟key。
这时候有两条路：一是在业务侧请求头里带上生成的虚拟key；二是修改general_settings里的master_key，或者开放disable_auth参数（仅测试可用）。生产环境不要开disable_auth，这等于裸奔。
5.3 中文token统计不准与输出截断
这个问题比较隐蔽。同一段中文prompt，不同模型的tokenizer统计差异很大。litellm日志里的token数是按模型自身返回的usage算的，这个数据是模型侧给的，对接层很难修正。所以当你看到两个模型处理同一请求的token消耗差异大时，先不要怀疑litellm算错了，更多是模型自身编码方式不同导致的了。
另外，如果你发现输出总是到某个长度就断了，大概率是配置了max_tokens但数值太小，或者模型默认最大输出被限制。检查一下你的litellm_params里有没有传入max_tokens，如果没有，试试显式设置成模型允许的上限。
5.4 请求延迟高，何处下手
延迟高是很多人运行网关后的第一个疑问。我的排查顺序是这样的：
先看是不是模型侧延迟。直连该模型API测一下，如果直连也慢，那问题不在litellm，是模型或网络问题。
再看请求排队。大规模并发下，网关自身和模型端都可能排队。你可以查日志中的start_time和end_time差值，但更有用的指标是看网络连接复用情况。litellm对每个模型后端会维护连接池，频繁创建和断开连接会显著增加延迟。如果你的业务QPS不低，建议在配置里优化连接池的超时参数，或者调整并发策略。
最后，检查是否错误使用了同步阻塞方式。有些框架里异步请求被无意中串行化了，那延迟自然成倍上涨。这一步属于接入方自身逻辑问题，litellm帮不了你，需要检查业务代码。
5.5 一份快速排查速查表
| 现象 | 优先排查方向 | 常见解决办法 |
|---|---|---|
| model not found | 请求的名字是否等于配置别名 | 改为model_name值 |
| 401鉴权失败 | 请求头中的key是否为有效虚拟key | 生成key或调整鉴权配置 |
| 请求全部超时 | 模型侧是否故障 | 检查直连延迟、fallback配置 |
| 日志有请求但业务没响应 | 超时参数设太小 | 调大timeout |
| 费用统计为0 | 模型未返回usage字段 | 确认模型类型与价格配置 |
| 网关经常502 | 后端模型不可达或key失效 | 查看真实后端错误日志 |
6. 个人搬家心得与一些补充建议包袱
现在litellm已经稳稳地躺在我自己的服务器上跑了大半年，累计转发了十几万次模型调用。它的定位在我心里也越来越清晰：它不是“替代厂商SDK”，而是“厂商SDK之上的调度中枢”。如果你有多个模型、多业务线、需要管控成本和灰度切换，它的价值会非常明显。如果你只是单模型单业务随便玩一玩，那确实可以先不碰它。
最后再分享一个我在实战中体会到的小技巧：网关的配置，建议纳入版本管理。把config.yaml放到仓库里，每次改动都走一次代码评审。因为网关一开，谁改了配置都影响全局，一不小心就把主模型切到了测试模型上去。有版本控制，随时能追溯和回滚，哪怕出问题也不会满头大汗。
还有一点是，为了更省心，把environment variables的管理也纳入统一流程。密钥这种东西，别写文件里，也别在命令行里直接暴露。用密钥管理工具去管理环境变量，或者至少在部署时用加密的选项导入。这不算litellm的功能，但它是整个链路里最不该松手的一环。
如果你打算开始用litellm，我的建议是从SDK模式试起，跑通两三个模型之后，再考虑搭网关、做fallback、加限流这些深水区操作。直接上网关也不是不行，但一步到位容易在多层级排查时找不到方向。踩过几次坑之后你会发现，这个工具最大的价值不是省几个调的API，而是让你从“我要迁就模型的脾气”变成“模型要迁就我的标准”。这中间的效率差距，只有实际用过才体会得到。
