"litellm"这个名字，第一次看到的时候我愣了一下，念了两遍才反应过来——就是“Lite LLM”的意思。当时我正在同时对接三家大模型供应商的API，代码里if-else套得跟千层饼一样，换个模型要改半天，加个新模型又要改半天。后来我意识到，问题不在代码写得不够好，而在于我缺少一个统一的接入层。LiteLLM解决的就是这个事：它帮你把各家大模型的API差异抹平，让你用一套代码、一套格式去调用所有主流模型服务。对于做AI应用开发、做模型选型测试、或者需要给团队搭建统一模型入口的朋友来说，这几乎是绕不开的基础设施。
这篇内容不是我抄官方文档的复读，而是我实际把LiteLLM接进业务、跑过压测、踩过计费和超时坑之后的经验整理。我会从它为什么存在讲起，到核心功能拆解，再到完整实操步骤和常见问题排查，尽量让还不熟悉网关类工具的朋友看完就能上手。
1. 为什么需要一个“LLM网关”：统一接入层的诞生逻辑
1.1 多模型接入带来的真实痛点
先说个具体场景。假设你正在做一个AI客服产品，底层要接大模型。今天用某家的模型，效果还行但贵；明天换另一家的，便宜但偶尔抽风；后天又出现一个新的模型，效果更好，你想快速试。问题来了：这三家的API风格完全不一样。
参数名不同算轻的，有的叫max_tokens，有的叫max_new_tokens，有的叫max_output_tokens。流式返回格式不同，一个给你SSE，一个给你WebSocket，还有一个给的是不兼容的JSON结构。错误码更乱，限流了有的返回429，有的返回400，有的干脆返回200但告诉你“稍后再试”。你以为换个模型只是改个API Key，实际上要改协议解析、超时策略、重试逻辑、格式转换，一轮改下来少说三四天。
如果只是自己写demo，忍忍也就过去了。但如果是团队协作呢？前端同事要调模型，后端同事也要调，测试同事也要调，每个人都要各自对接一遍官方SDK，js写一套、Python写一套、Java再写一套。各写各的，出了问题各自排查，完全失控。
这就是典型的“多点接入、重复造轮子”问题。在数据库时代，我们用ORM解决多数据库方言差异；在微服务时代，我们用API网关统一服务入口。到了大模型时代，自然也需要一个类似的统一层——LiteLLM做的就是这件事。
1.2 LiteLLM的核心定位：把复杂留给工具，把简单留给你
LiteLLM在官网上有一句话说得挺直接：“Call all LLM APIs using the OpenAI format”。意思是它把各家模型的调用全部转成OpenAI兼容格式，你的业务代码只需要维护一套调用逻辑。
但如果你以为它只是个格式转换器，就太小看它了。实际上，LiteLLM更像一个“LLM网关”，主要有两种使用形态：
第一种，SDK模式。你在自己的Python代码里import litellm，然后直接调用，它帮你做格式适配和转发。
第二种，代理服务模式。你启动一个LiteLLM代理服务，它暴露一个统一接口出来，你的业务系统、团队同事、自动化测试统统走这个接口，由代理来负责路由、鉴权、计费、限流、重试、缓存这些杂活。
两种模式我都在生产环境用过。SDK模式适合自己快速接入、写脚本测试模型效果；代理模式适合团队协作和上生产，因为你可以在这层集中做治理，不用逼着每个调用方去理解各家API差异。
我自己最喜欢的点在于，LiteLLM把“接模型”变成了“配表”。以后要新增模型，不需要改业务代码，改配置文件、重启一下代理，完事。这对业务的侵入性几乎为零，谁用谁知道。
2. 核心功能拆解：LiteLLM到底替你做了什么
2.1 统一的API格式：一套代码对接所有模型
LiteLLM最核心的卖点，就是把所有模型都包装成同一个调用格式。无论你调的是OpenAI系的、Anthropic系的、Azure的、Google系的，还是本地的开源模型，你在业务代码里看到的接口都是一样的：
import litellm response = litellm.completion( model="gpt-4o", messages=[ {"role": "user", "content": "你好"} ] )想换个模型？把model参数改成claude-3-5-sonnet或者gemini-1.5-pro，其他代码不动。
这背后的原理其实不复杂：LiteLLM内部维护了一组适配器，针对每个模型提供商的API特点，在请求阶段把OpenAI格式的参数转换成目标API需要的格式，在响应阶段再把各家返回的数据统一成OpenAI格式的结构返回给你。流式、非流式、工具调用、多模态输入，它都做了适配。
关键点在于“兼容”的准确度。早期这类工具最怕的就是兼容不完整——某些模型支持的功能在转换时被丢掉了。LiteLLM做得比较细，比如不同模型对temperature这类参数的支持范围不同，它会自动做裁剪；有些模型不支持frequency_penalty，它会忽略这个参数而不是报错。这些都是细节，但生产环境往往就是被这些细节坑的。
2.2 代理服务：把网关变成团队共享设施
SDK模式很好用，但一个人用可以，团队用就太“各自为政”了。LiteLLM提供代理模式，启动后就是一个标准的HTTP服务，对外暴露一个/chat/completions接口，完全兼容OpenAI的接口格式。你甚至可以直接把OpenAI的官方SDK的base_url改成你本地的代理地址，无缝切换。
这个模式带来的好处是结构性的：
- 集中管理API Key：各家模型的真实Key只存在服务端，团队成员拿到的都是代理颁发的虚拟Key。别说前端页面不会泄露Key了，就算有人离职把配置带走了，你随时在代理侧吊销，不需要去各家平台逐个重置。
- 统一的路由策略：你在代理这边配置好哪个模型走哪家供应商，可以给同一个模型配置多个供应商作为备援，一个挂了自动转另一个。
- 团队内的调用规范：所有人面对的都是同一个API地址、同一套认证方式，写出来的代码也高度统一，交接成本大幅降低。
部署也没有想象中复杂。以Docker方式为例，拉取镜像、挂载配置文件、暴露端口，一条龙下来基本不会超过十分钟。对于中小团队，这就是把模型能力变成内部“公用事业”的最短路径。
2.3 成本与预算治理：给调用加上“阀门”
做AI应用的人都知道，大模型调用的费用是真实的“燃烧速度”。没有治理之前，测试环境一天烧掉的钱可能比生产环境还多——因为大家反复测试、反复调参、模型越用越大。
LiteLLM在成本治理上做得相当实在，主要有几块：
- 预算限制：可以设置项目级别的总预算，也可以按API Key、按用户来分别设限。超过预算以后代理直接拒绝请求，返回详细错误信息。
- 速率限制：可以设置每分钟、每小时、每天不同粒度的请求数上限。实测下来，它的限流是滑动窗口的，比固定窗口要平滑很多，不会出现“窗口边缘大量误杀”的情况。
- 细粒度计费：LiteLLM内置了主流模型的价格表，可以统计每一次调用消耗了多少钱，精确到美元的分。虽然各平台价格会有调整，但用于日常监控和成本归因已经足够。
我自己最深的一个体会是：预算功能不只是为了防止恶意刷接口，更重要的是让团队培养起“成本敏感”的意识。当开发人员能看到每一次调试烧掉多少钱之后，写测试脚本的时候自然会用更小的模型、更少的token。
2.4 缓存与重试：省成本、稳服务的关键机制
还有两个容易被忽略但非常影响生产体验的功能：缓存和重试。
缓存的逻辑很朴素——同样的用户提问，如果之前已经有完全一样的回答，没必要每次花钱重新调模型。LiteLLM支持将响应缓存到内存、Redis或S3。实际测试中，像“这个按钮怎么点”这种高频重复的问题，命中缓存后响应速度从几秒降到几十毫秒，成本也直接降下来。
重试机制则是“接稳定性”的兜底。大模型服务不是每时每刻都稳，偶尔抽风返回5xx，动不动限流。LiteLLM支持配置重试次数、重试间隔、指数退避策略。它还区分了“可重试的错误”和“不可重试的错误”——比如超时、限流、服务不可用，重试是合理的；但如果是参数错误、鉴权失败，那就直接抛出错误，不该浪费一次重试机会。
这里有个小经验：重试不是越多越好。有些供应商的限流是按token的bucket来算的，你疯狂重试反而容易把自己彻底锁死。我一般设为3次，指数退避，第一次等1秒、第二次等2秒、第三次等4秒，基本够用了。
3. 实操：从安装到部署一个可用的LLM网关
3.1 环境准备与安装
LiteLLM是用Python写的，安装最简单的方式就是通过pip：
pip install litellm它同时要求Python 3.8以上。如果你要跑代理服务，我建议用Docker，省去环境依赖的麻烦：
docker pull ghcr.io/berriai/litellm:main-latest如果你只是想在本地试试SDK模式，pip装完直接用就行。代理模式通常需要Redis做缓存和限流的数据存储，本机没有Redis的话，可以用Docker起一个：
docker run -d -p 6379:6379 redis装完之后先验证一下：
import litellm print(litellm.__version__)能正常打印版本号，就可以继续往下走了。
3.2 SDK方式快速上手
安装完成后，如果是SDK模式，只需要设置环境变量，然后调用completion即可：
# 设置各家API Key export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..."然后写代码：
import litellm # OpenAI风格调用 response = litellm.completion( model="gpt-4o", messages=[ {"role": "system", "content": "你是运维助手"}, {"role": "user", "content": "帮我总结一下这行日志"} ], temperature=0.3 ) print(response.choices[0].message.content)如果此时model换成其他家的模型名，代码如下：
response = litellm.completion( model="anthropic/claude-3-5-sonnet", messages=[{"role": "user", "content": "讲个冷笑话"}] )注意模型名的前缀规则。LiteLLM用provider/model-name的形式来指定模型，比如anthropic/、azure/、bedrock/、ollama/等。如果不带前缀且没在配置里映射，它默认会按OpenAI来处理。这一块我刚接触时也容易搞混，后来习惯成自然。
流式调用也差不多：
response = litellm.completion( model="gpt-4o", messages=[{"role": "user", "content": "写一首短诗"}], stream=True ) for chunk in response: print(chunk.choices[0].delta.content, end="")SDK模式的好处是轻量，适合脚本和快速验证。它还能帮你处理重试、超时，甚至自动切换到备用模型。
3.3 以代理模式部署服务
代理模式是生产环境的推荐方案。首先需要准备一个配置文件，控制哪些模型可用、各模型路由到哪里、预算和限流怎么设。下面是一个精简但可用的配置示例：
model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY - model_name: llama3 litellm_params: model: ollama/llama3 api_base: http://localhost:11434 litellm_settings: drop_params: true set_verbose: false retry: true num_retries: 3 request_timeout: 30 fallbacks: [{ "gpt-4o": ["claude-3-5-sonnet"] }] general_settings: master_key: sk-master-key-here database_url: postgresql://user:pass@localhost/litellm redis_url: redis://localhost:6379几个关键配置说一下：
model_list：声明哪些模型可以通过代理访问，这里还支持按不同分组做负载。比如你可以配置两个gpt-4o条目，一个走主账号、一个走备账号，代理自动分摊流量。drop_params：设为true后，如果某个模型不支持你传的参数，代理会悄悄丢弃而不是报错。这在不同模型切换时非常救命。general_settings：master_key是代理的管理员密钥，所有的请求必须带上这个Key才能访问。database_url用于持久化预算和日志数据，不配的话重启后数据会丢。
配置文件准备好之后，启动代理：
litellm --config config.yaml --port 8000或者用Docker：
docker run -d \ -p 8000:8000 \ -v $(pwd)/config.yaml:/app/config.yaml \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml启动之后，你的业务代码只需要把base_url指过来即可。用Python的OpenAI SDK示例：
from openai import OpenAI client = OpenAI( api_key="sk-master-key-here", base_url="http://localhost:8000/v1" ) resp = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "你好"}] ) print(resp.choices[0].message.content)到这里，你的团队就拥有了一个统一的模型接入入口。新增模型、修改路由、调整限流，都只需要改配置、重载服务，业务代码一行都不用动。
3.4 从开发到上线的常见配置清单
如果要把代理真正用进生产，我建议按照下面这个清单做一遍检视：
- 确认设置了
master_key，并且没有把它放到前端代码里。 - 确认
database_url配置的是持久化数据库，而不是默认的SQLite临时文件。 - 确认
redis_url可用，缓存和限流都依赖它。 - 确认预算限制配置到每个Key或每个项目的粒度，而不是只有总预算。
- 确认设置了
num_retries和request_timeout，至少覆盖掉常见的供应商抖动。 - 确认模型路由里有
fallbacks，至少给核心模型配置一个备用方案。 - 确认日志打到独立文件或日志服务里，方便做调用量分析和问题回溯。
别嫌啰嗦，这些配置项我几乎每一项都在生产环境里出现过意义。尤其是预算和fallback，一个是保钱袋子，一个是保服务质量，缺一不可。
4. 常见问题与排查技巧实录
4.1 各家模型返回格式不一致怎么办
就算LiteLLM尽量统一了格式，不同模型在返回内容的“风格”上仍然有差异。比如有的模型喜欢用Markdown标题，有的喜欢用纯文本，还有的会在答案里加上“根据我的理解”这种前缀。
这不算技术故障，但会影响下游解析。我的建议是：不要指望LiteLLM帮你抹平模型表达风格的差异，这一层差异应该在业务侧通过系统提示词来约束，甚至在代码里做后处理过滤。你可以把LiteLLM理解成“水管”，它保证水能流通，但不能保证每个水源的水质一样。
另一个常见问题是工具调用（function calling）的格式。有的模型返回的JSON结构里，参数是字符串，需要自行解析；有的已经是对象。如果遇到这种情况，优先检查你用的是不是该模型最新的接口版本，其次再考虑在后处理层做兼容。
4.2 请求超时与限流如何应对
代理上线之后第一个容易碰到的就是超时。大模型本身响应就慢，如果你把request_timeout设成10秒，生产环境里很可能会频繁超时。我实测下来，设置30-60秒比较稳妥，流式场景还要更长。
限流则有两个层面。第一层是上游供应商的限流，这时代理的重试逻辑会尝试兜底；第二层是你自己在代理里设置的限流，触发后会返回429和明确提示。排查的时候，先看错误码：如果是代理返回的429，去查自己限流配置；如果是供应商返回的429或5xx，那就是上游的锅，代理的重试和fallback应该要发挥作用了。
另外提一句：限流触发时记得看返回头里的Retry-After字段，供应商通常会告诉你多久后可以再试。LiteLLM的重试也会参考这个字段，比自己拍脑袋等几秒要准得多。
4.3 预算管理不生效的排查
这是团队里最容易踩的坑。配置了预算但感觉没生效，通常原因有三个：
第一种，你用的是默认内存存储，重启之后预算数据被清零了。解决方法是配置持久化数据库。
第二种，预算粒度没对。LiteLLM支持全局、Key、用户、团队等多层预算，你得确认自己设置的是哪一层。如果只是设置了用户预算，但调用时没有传用户ID，那这条预算自然管不到。
第三种，没有在模型配置里启用max_budget。有人以为配了general_settings就万事大吉了，实际上每个模型的预算管理还要在对应模型的litellm_params里单独声明max_budget。
排错的时候有个技巧：用同一个API Key连续调用几次，然后在管理后台看日志。LiteLLM会记录每次调用的“预算扣减”和“当前余额”，一目了然。
4.4 日志和监控：没有可视化面板的替代方案
LiteLLM本身带一个简易的管理后台，但功能不算丰富。如果你要深入分析调用量、token消耗和延迟，可以把代理的日志打到数据库里，然后用现有的BI工具或日志系统去分析。常见做法是接Prometheus监控，或者干脆用SQL查数据库。
这里顺带一个实用小技巧：配置set_verbose: true以后，代理会打印出非常详细的调试信息，包括请求头、响应体、重试过程。排错阶段开着，上线前关掉，不然日志量会很大。
还有如果遇到代理响应速度快但感觉模型一直在转圈的情况，多半是流式输出的网络问题。检查代理所在服务器的出网带宽，以及客户端到代理的连接是否稳定。流式调试时可以用curl直接观察SSE流，排除客户端代码的干扰。
我自己在实际使用中的体会是，LiteLLM的确不是一个“炫技型”的工具，它解决的都是很实在的工程问题。第一次把它部署进生产时，最让我安心的不是它有多fancy的功能，而是团队有人突然问“能不能接一个某个新出的模型”的时候，我只需要在配置文件里加一行，而不是又花一个下午去改代码、调参数、踩格式的坑。最后再分享一个小技巧：如果你是刚接触这个工具，别一上来就搭代理、配数据库，先用SDK模式把一两个模型跑通，感受一下它的调用方式和错误信息，再一步步往代理模式过渡。磨刀不误砍柴工，这个工具值得你在项目里试上一试。
