litellm这个项目我第一次接触到的时候第一反应是“这不就是一个API网关嘛”。但真正用起来之后才发现它解决的问题比“网关”两个字要深得多。你想想看一个团队里有人用OpenAI、有人用Anthropic、还有人接了各种国产模型或者自研模型每个人的代码都是按各家SDK的写法来的到时候统一对接下游系统那叫一个酸爽。而litellm就像在你所有的模型供应商前面立了一个哨塔所有请求先进来由它统一分发、统一计费、统一做权限控制你的后端代码只需要认准一套OpenAI格式的接口就完事了。这篇文章我会从它解决的真实痛点讲起拆解它的核心设计思路然后给你一套能直接上手的部署方案最后把我自己踩过的几个坑整理成排查手册。我不打算讲太多虚的架构图尽量用实操场景说话让你看完之后能自己搭起来并且知道每个配置项为什么存在。1. 项目定位它不是模型聚合工具是LLM基础设施的“统一入口”1.1 先搞明白它解决的是哪一类问题很多人第一次看到litellm容易把它理解成“一个集成了很多模型的第三方客户端”。其实这个理解偏差挺大的。它确实兼容了上百家模型服务商包括OpenAI、Anthropic、Google、Azure、AWS Bedrock还有一些开源模型的自托管方案。但litellm本身不训练模型、不托管权重也没有自己的对话界面虽然管理后台带了简单的测试页但那是辅助调试用的。它的核心角色是帮你把“应用代码”和“底层模型供应商”之间的耦合关系切开。在没有这样一个中间层的时候你只要把代码里的openai.ChatCompletion.create换成anthropic.Completion这种写法就要重写一遍业务逻辑。而且每家的请求格式都不一样流式输出的数据帧格式也不同错误码体系更是千奇百怪。一旦某个模型服务商涨价或者出故障你想临时切换到另一家改动范围往往会波及到整个项目。我在某个模拟项目X里就遇到过这种情况业务方要求“所有对话必须走A供应商但B供应商作为容灾备份”还要对内部不同部门的调用量做预算隔离。如果直接去改业务代码每个调用点都得加判断逻辑后期维护就是一场噩梦。后来我们给每个模型调用点前面加了一个中转业务代码永远只调一个固定地址切换模型供应商的活全部交给中间层去做。litellm其实就是把这一层能力做成了开箱即用的产品。1.2 一张核心功能清单快速对上号我整理了一下实际使用中真正高频的功能点你按这个清单来验证litellm适不适合你的场景功能模块作用说明日常使用频率统一API格式只暴露OpenAI风格的/chat/completions与/embeddings接口每次调用模型路由与映射在配置文件里声明“对外模型名”和“真实供应商模型名”的映射关系每次调用多Key负载均衡同一个供应商配置多个API Key自动分散流量、故障切换高并发必用预算与限流控制按API Key、用户、团队维度设定调用上限与花费上限团队协作时很关键Redis缓存相同请求直接命中缓存减少重复计费重复型业务场景好用日志与审计自动记录每次请求的输入、输出、耗时、花费明细排查问题时刚需内置管理后台可视化查看模型列表、调用日志、预算使用情况日常运维效率高这几种能力不是互相独立的。比如你在同一个配置里可以同时做模型映射、加预算上限、开缓存、挂回调日志几件事一次性在启动参数里配好。这一点比你自己拿FastAPI包一层要省事得多。1.3 适合谁来用不适合谁来用litellm最适合的场景是“你们团队的代码要同时对接多个模型供应商”或者“你们需要对内部不同业务线的LLM调用做统一管控”。尤其适合已经有AI功能上线、但觉得维护成本开始上升的团队。它不太适合的场景是那种“我就一个模型一个Key直接写在代码里不想加任何中间层”的轻量使用。这种场景确实没必要多维护一个服务。还有一个不适合的场景是如果你需要非常细粒度地定制协议内容比如特殊的流式格式、自定义鉴权头、私有加密体系那直接用代码写中转可能更灵活。litellm提供的是标准化的能力太偏门的需求得通过插件和回调来补能补但没必要硬塞。提示litellm底层本身就是一套Python库你不想跑独立服务的话也可以直接当SDK来用在代码里调用litellm.completion()这样的方法。后者适合快速脚本场景前者适合稳定服务场景。我下面的实操都基于独立Proxy模式因为多数人落地的形态是“独立中转服务”。2. 核心技术拆解一个统一入口背后的设计思路2.1 协议适配层为什么选择OpenAI格式作为“通用语言”如果你接触过不同的模型供应商你会发现各家API的设计哲学差异很大。OpenAI的接口走的是messages数组每条消息带role和contentAnthropic的接口也带消息概念但system是独立参数请求体结构完全不同Google的Gemini则有自己的contents和parts结构。如果你直接写代码对接每换一家就要改一遍参数拼装逻辑。litellm的做法是把OpenAI格式视为“通用语言”。你的业务代码只需要按OpenAI格式发送请求由litellm在内部把OpenAI格式转换成对应供应商的原生格式。比如你传一个max_tokens参数它会被翻译成Anthropic的max_tokens_to_sample你传一个system消息它在某些供应商那边会被合并进消息数组的第一条。这种“翻译层”的价值在于团队里新成员上手时只需要学一套API规范。我做嵌入式开发的朋友说这有点像HDMI转VGA的转接头。显示器只认VGA信号游戏机只输出HDMI信号中间有个转换器两边都不用改。当然这个比喻不完全准确因为各家模型的“参数能力”本身有差异比如有些模型根本不支持JSON模式、有些模型不支持logprobs翻译层只能传过去如果底层不支持只能报错。所以协议适配层真正解决的是“格式一致”问题并不包办“能力对齐”问题。2.2 路由策略与重试机制当两个Key都被你塞进配置后会发生什么litellm最让我觉得实用的不是它能把一个请求转发到OpenAI而是它允许你对同一个“对外模型名”配置多个真实目标。这意味着你可以把同一个模型配两条记录一个走供应商A的Key一个走供应商B的Key然后由litellm来决定这次请求到底发到哪一家。它的路由核心逻辑很简单先根据配置把model_name匹配到一组候选配置项。再根据策略选择一个目标。默认策略大致是按权重分配你也可以配置优先级列表。如果目标返回错误比如限流、超时、5xx按照配置好的重试次数去尝试下一个候选。这个机制解决了我之前的容灾需求。业务代码根本不需要知道自己这次调用的是哪家供应商只要返回内容正常即可。如果某家供应商故障了litellm会自动转移到另一个可用的Key上业务方最多观察到响应时间变长不会直接报错中断。有一件事必须搞清楚路由切换和模型切换是两个概念。如果A供应商的gpt-4和B供应商的gpt-4都叫同一个对外名那路由只是在“同一模型名的不同渠道”之间切换。如果你想让一个请求从gpt-4切到Claude 3.5 Sonnet那得在业务代码里显式改模型名litellm不会按语义智能替换模型。2.3 预算管控与请求审计透明化LLM成本的关键一步很多团队不敢把大模型能力开放给内部成员担心的不是技术而是成本失控。litellm的预算体系是我比较认可的设计它分几个层级全局预算整个网关的总消费上限。Key级预算为每个API Key限定最大花费或者最大请求次数。用户/团队级预算通过请求头里的用户标识关联到对应账户做配额限制。实际落地的时候你可以为每个外部客户生成一个专属API Key并挂一个限额。客户调用到上限之后litellm会直接拒绝请求返回预算超限的错误。这一点比自己在业务代码里做计数器要精确得多因为litellm统计的是模型供应商那边真实返回的usage字段还按供应商的单价算出了美元金额。日志方面litellm默认会把每次请求的model、messages摘要、response、latency、cost、total_tokens这些信息记录下来。你可以在管理后台一页页翻也可以接回调把日志推到自己的ES或者其他日志平台。对于我们习惯了“出了问题要能回溯”的工程师来说这个能力省了太多事。2.4 缓存层什么时候能省大钱什么时候千万别开litellm支持在内存里做缓存也支持接Redis做分布式缓存。说直白点它是把请求体的hash值作为key如果用户发送了一个完全相同的请求就直接把上次的响应返回不再去上游调用。这个功能在两类场景下特别有用客服问答用户问的问题高度重复比如“怎么退款”“忘记密码怎么办”命中缓存能省掉大量重复计费。测试联调开发阶段同一个请求会反复触发开了缓存能缓解上游限流压力。但缓存不是什么地方都能开。如果你的业务内容强依赖时效性比如实时分析、股票行情、新闻摘要那开缓存会产生明显的“内容滞后”问题。另外如果模型本身有随机性而你希望每次响应都不同比如创意写作缓存会直接毁掉产品的体验。所以litellm里默认缓存并不是全局强制打开的而是需要你在配置里显式声明。3. 实操落地从零到一部署一套可用网关3.1 环境准备与基础安装litellm的部署非常轻量只要机器有Python 3.8以上环境就行。我是在一台2核4G的云主机上跑过日常几十个人的调用团队完全够用了。安装方式很简单用pip装带Proxy功能的版本pip install litellm[proxy]如果你不想污染系统Python环境建议用一个独立的虚拟环境来装python3 -m venv llm-gateway source llm-gateway/bin/activate pip install litellm[proxy]装完之后命令行工具里会多出一个litellm命令你可以先看一眼版本号确认装好了litellm --version我踩过的一个坑是如果机器上Python版本比较老依赖解析的时候可能会报pydantic版本冲突。建议装的时候顺手升级一下pydanticpip install -U pydantic3.2 最小配置一键跑通单模型转发先别急着把配置画得花里胡哨的。第一步我建议你先用一个模型配置把整个链路跑通之后再慢慢加花活。在项目目录下创建一个配置文件config.yamlmodel_list: - model_name: gpt-3.5-turbo litellm_params: model: openai/gpt-3.5-turbo api_key: sk-你的OpenAIKey然后启动服务litellm --config config.yaml --port 4000默认情况下litellm会要求设置一个master key用于网关自身的身份鉴权。如果你只是本地测一下可以加环境变量先临时放一个export LITELLM_MASTER_KEYsk-liteLLM-local-test litellm --config config.yaml --port 4000这时候你的网关地址就是http://localhost:4000。接下来用OpenAI的Python SDK来测一下是否能通from openai import OpenAI client OpenAI( api_keysk-liteLLM-local-test, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelgpt-3.5-turbo, messages[ {role: user, content: 你好用一句话介绍一下自己} ] ) print(response.choices[0].message.content)如果这个脚本跑通了恭喜你你已经拥有了一个“兼容OpenAI格式的LLM网关”。这一步看起来简单但它是后面所有高级功能的基础。3.3 多模型映射用同一个接口名访问不同供应商现在进入真正有价值的配置环节。假设你要在业务里同时使用OpenAI的GPT、Anthropic的Claude和Google的Gemini但你不想在业务代码里区分它们。那么你可以在config.yaml里这样配置model_list: - model_name: gpt-3.5-turbo litellm_params: model: openai/gpt-3.5-turbo api_key: sk-你的OpenAIKey - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: sk-ant-你的AnthropicKey - model_name: gemini-pro litellm_params: model: gemini/gemini-1.5-pro api_key: AIza你的GoogleKey这里的model_name是对外暴露的名字业务代码里传的就是这个litellm_params.model是真实供应商那边的模型标识前缀openai/、anthropic/、gemini/分别代表要走哪一家协议。配置好之后你的业务代码不需要做任何区分# 这是调用Claude的代码 response client.chat.completions.create( modelclaude-3-5-sonnet, messages[{role: user, content: 给我讲个笑话}] )它实际上会跑到Anthropic那边去。如果哪一天你不想用Claude了直接在配置里把claude-3-5-sonnet对应的litellm_params改成别的供应商即可业务代码一行都不用动。注意不同供应商对模型能力支持不同。比如有些模型不能接收max_tokens之外的额外参数如果你在litellm_params里加了上游不支持的字段请求会失败。遇到这种“多传参数导致报错”的情况优先检查是不是转发层传了不该传的东西。3.4 多Key负载均衡与故障转移配置这一步是我推荐所有流量稍大的团队都要做的。同一家供应商的同一个模型你可以配置两条记录各走一个不同的API Key。这样当某个Key因为并发超限被限流时网关会自动重试到另一个Key上。model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: sk-key-001 - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: sk-key-002当业务方调用gpt-4o时litellm会在两个Key之间做负载均衡。默认逻辑简单又实用两个Key权重相同轮询或者根据压力分布来挑。你也可以在litellm_params里显式加rpm每分钟请求数限制来控制单个Key的压力。如果一个Key返回了429限流或者500类错误litellm会自动去尝试另一个Key。如果你希望重试的行为更可控可以在配置里加上router_settingsrouter_settings: retry_policy: TimeoutError: 3 RateLimitError: 2 InternalServerError: 2这里的数字代表最大重试次数。比如RateLimitError: 2意味着遇到限流错误时最多再尝试2次。这里我建议不要太贪心重试次数过多会让单次请求的总延迟拉长用户那边的体感会很差。3.5 预算限制与用户维度隔离配置给外部客户或者内部部门分配独立的Key是成本管控的必要动作。比如我为“客户A”创建一个只属于它的Key并在配置中限定它的月度最大消费general_settings: master_key: sk-网关管理员Key # 创建虚拟Key litellm_key_management: enable_key_management: true启动服务后调用接口来生成一个虚拟Keycurl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-网关管理员Key \ -H Content-Type: application/json \ -d { duration: 30d, max_budget: 10.0, user_id: customer-A }生成后返回里会有一个api_key字段把它返回给对应客户。客户用这个Key调用你的网关时所有消费都会被统计到customer-A这个用户上。当累计消费超过10美元时该Key的后续请求会被拒绝。除此之外你还可以通过max_parallel_requests限制并发数避免一个客户把整台网关的实例资源都打满。3.6 对接管理后台与生产环境部署建议启动服务之后直接访问http://localhost:4000/ui就能看到管理后台页面。上面能看到模型列表、历史请求、报错信息、Key管理。我个人强烈建议在生产环境至少做以下几件事用systemd或者Docker方式托管网关进程不要裸跑在nohup下面。设置LITELLM_MASTER_KEY环境变量别写在命令行参数里。把config.yaml放到独立的配置目录并且加入版本管理。如果有多实例部署需求缓存务必切换成Redis模式。一个简单的Docker启动示例docker run -d \ --name litellm-proxy \ -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ -e LITELLM_MASTER_KEYsk-网关管理员Key \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml生产环境我建议加一层反向代理在前面做TLS终止不要裸奔HTTP。4. 常见问题与排查技巧实录4.1 每次请求都返回401认证失败这个问题的根源九成是master key没配对。litellm网关有两层Key概念一个是管理用的master key一个是下游业务方调用时用的“虚拟Key”。请求头里如果只带了业务方的虚拟Key而该Key在key management里还没创建就会返回401。建议按这个顺序排查先用master key去访问/health/readiness确认服务本身是活的。检查业务端请求头是不是用了Authorization: Bearer master_key要知道master key也能调用普通接口但生产环境不建议这么用。检查是否在调用生成Key接口时命令里的master key用错了。4.2 请求转发出去了但响应时间格外慢在litellm管理后台的日志里你可以看到每一个请求的latency。如果发现上游耗时很长大概率不是网关的锅而是你选的路由目标本身就慢或者被限流了。我遇到过一种情况A供应商的Key被限流后litellm自动重试到B供应商但B供应商那边本身响应就偏慢平均要多等3秒钟。这种情况下需要调整策略把响应快的供应商权重调高或者换用低延迟的模型版本。另外如果你开了流式响应用户侧看到的首字延迟会明显改善这也是很多产品接入litellm之后优先开流式的原因。4.3 模型名总是匹配不上路由litellm匹配模型名时是按model_list里的model_name精确匹配的。如果你在业务代码里传了gpt-4o但配置里写的是gpt-4那就会报model not found。还有一个容易忽略的点如果你在配置里写了model_name: gpt-4o而litellm的litellm_params.model写的是openai/gpt-4o那么请求日志里显示的模型名可能是openai/gpt-4o但业务代码里仍然用gpt-4o来调用二者不要混为一谈。4.4 流式输出断裂或者不完整流式输出依赖供应商和网关之间的SSE通道。如果你前面套了一层反向代理尽量确认反向代理的缓冲机制不会截断流。litellm在转发流式响应时会把上游的数据帧实时转发给客户端。如果客户端SDK那边设置了较低的超时时间或者代理层开启了缓冲缓冲就可能出现“收到一半就断掉”的情况。排查的时候先用curl直接打网关的流式接口看返回数据是否完整如果curl没问题再查客户端和中间代理的连接设置。4.5 工具调用function calling透传异常这个坑比较隐蔽。不同供应商的function calling格式不同litellm虽然做了大量转换但如果你用的模型不支持工具调用或者你传的参数格式稍微复杂一点比如嵌套对象就可能在转换时报错。我给的建议是在代码里尽量精简工具参数结构不要带太复杂的自定义字段。如果业务真的需要复杂工具参数先在litellm的调试接口里单测一次确认能正常返回tool_calls再接入业务代码。千万不要在没验证的情况下直接全量上线。4.6 成本统计与供应商账单对不上litellm的成本统计是基于模型供应商返回的usage字段乘单价计算出来的。问题在于有些供应商的价格模式很复杂比如按小时计费的batch任务、缓存命中折扣、夜间折扣等等这些情况litellm不可能完全先知。我个人的用法是把litellm的统计当成“相对准确的相对成本参考”用于团队内的消耗对比和预算控制。最终的成本结算还是以供应商账单为准。如果你发现cost数据明显虚高检查一下配置里是否设置了错误的模型单价。5. 我对litellm的真实使用感受与一点建议用了一段时间之后我最大的感受是这个项目解决的不是“技术问题”而是“协作问题”。技术上游供应商虽然各不相同但真正磨人的是团队里每一个人都要记住“这个模型要走这个Key、那家模型要用那种鉴权”这种零散信息。litellm把这类信息全部收敛进一份配置文件中不论业务代码写得多么混乱网关这一侧始终清清楚楚。如果你打算在团队里推动落地我给三个实操建议第一批接入的模型不要贪多就接你最常用的两三家先跑一个月看看。管理后台的日志功能利用率要拉满每周抽几分钟看一眼各业务线的调用量和花费分布你会对自己系统的成本结构有全新的认知。不要把生产网关和开发网关共用同一个实例用两个配置文件、两个端口或者两套部署分开跑不然开发联调时产生的日志会污染生产侧的统计数据。最后分享一个小技巧litellm的配置是动态重载的。你改了config.yaml里新增一个模型不需要重启服务用管理后台刷新一下配置就能生效。这一点我看很多人不知道还傻乎乎地重启生产服务结果每次配置变更都要断几秒完全没有必要。你在/config/update接口发一次新的配置内容或者直接调用SDK的update_config方法就行。如果你正在为多模型接入的维护成本头疼litellm确实值得放进你的工具箱认真试一次。