Litellm：用一套接口统一调用所有大模型，简化AI应用开发

1. 项目概述Litellm 到底是什么做 AI 应用开发的朋友尤其是接过大模型接口的应该都有过这种体会今天用 A 厂商的接口调通了一个功能明天老板说要换成 B 厂商的模型对比效果结果发现不仅 API 地址不一样、鉴权方式不一样连请求参数的字段名都对不上。明明都是干同一件事不同厂商的 SDK 却各自为政改一次需求就要重新写一遍对接代码相当折腾。Litellm 就是来解决这个问题的。它是一个开源的 Python 库也附带代理服务器能力核心目标只有一个——用一套统一的接口格式去调用市面上几乎所有主流的大模型服务。OpenAI、Anthropic、Google Gemini、Azure OpenAI、各类开源模型托管的推理服务以及国内常见厂商的模型服务它都能帮你转成统一的请求格式。你只需要按照它定义的格式写一份请求litellm 会在底层帮你完成协议转换、鉴权适配、参数映射这些脏活累活。这个项目解决的最核心痛点就是“多模型适配成本”。在实际业务里我们的需求往往不只是“能调用一个模型”而是要能够在多个模型之间做对比测试选出效果最好的那个在某个模型服务出现故障或限流时自动切换备用模型不同业务线用不同模型但统一走同一套代码入口汇总所有模型调用的成本消耗做统一核算如果没有一个中间适配层这些事情做起来会非常痛苦基本上每个模型就要维护一套独立代码。Litellm 的价值就在于——它把“模型调用”这件事抽象成了一个标准动作无论底层用的是什么模型对业务代码来说都是同一个入口。如果你属于下面这几类人群litellm 会很适合你应用开发者需要在产品里集成大模型能力但又不想被某一个特定厂商绑定AI 平台/中间件开发者需要为团队或公司搭建统一的模型接入层测试/算法工程师需要频繁对比不同模型的效果不想为每个模型都写一套测试脚本独立开发者想快速做出一个支持多模型切换的 Demo 或 MVP简单总结就是如果你觉得“对接模型服务”这件事很烦人值得花点时间看看 litellm它能把这部分工作大幅简化。2. 核心思路拆解它凭什么能做到“一套代码调所有模型”litellm 的设计思路其实不复杂概括起来就是“标准化 适配器”两层结构。理解了这个设计你就能明白它的能力和边界在哪里。2.1 核心设计逻辑统一标准 各类适配器litellm 为所有支持的模型服务定义了一套标准请求格式基于 OpenAI 的 API 风格上层业务代码只需要按照这套标准格式发请求。在底层litellm 针对每个不同的模型服务都实现了对应的“适配器”组件负责把标准格式的请求转换为目标服务要求的格式。打个比方这就像我们日常使用的充电接口标准。手机厂商都在 Type-C 接口上做统一但针对老式设备你还是需要一个转接头。litellm 就是那个万能转接头集线器你只带一根线就能给各种设备充电。这样做的好处非常明显业务代码与具体模型解耦换模型时业务代码完全不用改新增模型服务时只需要增加适配器实现不影响已有功能可以在适配层统一实现重试、限流、成本统计、日志记录等横切功能那为什么标准格式要“基于 OpenAI 风格”呢这里有一个现实原因——OpenAI 的接口格式实际上是当前大模型 API 领域的事实标准。早期很多模型服务厂商在设计自己的 API 时都参考了 OpenAI 的格式有的甚至直接兼容。litellm 采用了这套风格意味着学习成本很低大部分开发者对接过 OpenAI SDK 后就能直接上手。2.2 支持的模型范围不只是“多家”而是“非常多”很多类似的库可能只支持三五家主流服务但 litellm 覆盖的范围要广得多。它能同时支持OpenAI 系列包括 GPT 系列全模型Anthropic 系列Claude 系列Google 系列Gemini 系列等Azure OpenAI企业级部署形态AWS Bedrock 上的各类模型各类开源模型的托管推理服务通过兼容接口接入国内多家厂商的大模型服务通过兼容适配接入本地部署的推理服务比如通过 Ollama 等工具启动的本地模型这意味着无论你是在做一个聚合类 AI 产品还是在企业内部做多模型调度平台基本都能在 litellm 中找到对应的适配实现。2.3 不只是 API 转换代理模式是真正的杀手锏如果你以为 litellm 只是一个“调用 SDK 封装库”那就忽略了这个项目最重要的价值。除了在 Python 代码里作为库使用litellm 还提供了一个代理服务器模式Proxy Server这一点在企业应用场景中价值很大。代理模式是什么意思呢你不需要在业务代码里引入 litellm SDK只需要部署一个 litellm 代理服务它对外暴露一个统一的 API 入口兼容 OpenAI 接口格式你仍然用你熟悉的 OpenAI SDK 去访问这个代理但代理会把请求转发到你配置好的任意一个真实模型服务上。这个设计在企业环境中很实用团队内不同项目不需要都学习 litellm 的 SDK 用法直接用 OpenAI SDK 就能访问API 密钥可以统一在代理层管理不散落在各个业务代码里可以在代理层统一配置重试策略、熔断机制、速率限制、成本告警上层业务完全无感知地切换底层模型服务用一句话概括litellm 既能当作库来用也能当作服务来部署。前者适合单体应用快速接入后者适合团队级统一管控。两者结合不管是个人项目还是企业级应用都能找到合适的落点。3. 实操过程全解从安装到跑通第一个多模型调用这块我直接分享非常具体的实操过程按照我实际跑通的步骤来写包含坑和注意事项。3.1 安装与基础环境准备首先litellm 是基于 Python 的所以你需要一个 Python 环境3.8 以上版本就行新版本建议 3.10有些新模型特性会依赖更新的 Python 特性。安装方式非常简单pip install litellm或者你打算使用代理服务器模式一并安装 proxy 相关依赖pip install litellm[proxy]安装完成后在 Python 环境中验证一下能不能正常导入import litellm print(litellm.__version__)正常打印版本号就说明安装成功了。这里有一个很多人第一次用时会犯的错litellm 安装后不会自动包含所有模型服务商的 SDK 依赖它会在实际调用某个服务时按需加载。所以如果你只安装了最基础的 litellm 包调用 OpenAI 没问题但调用 Anthropic 时可能会提示缺少某些依赖。遇到这种情况不用慌根据错误提示补装对应依赖包或者直接用pip install litellm[all]把常用项都装齐。3.2 快速上手用代码直接调用多个模型litellm 的库模式使用体验很顺核心的方法就是litellm.completion()我们直接看一个多模型调用的例子。假设我们想在三个不同的模型之间做一次效果对比分别是 OpenAI 的 GPT 4.0 系列模型、Anthropic 的 Claude 系列模型以及一个通过 Ollama 拉起的本地模型。你只需要这样写import litellm # 调用 OpenAI 系列模型 response_openai litellm.completion( modelgpt-4o, messages[{role: user, content: 讲一个程序员加班的笑话}], api_key你的OpenAI_API_Key ) # 调用 Anthropic 系列模型 response_claude litellm.completion( modelclaude-3-5-sonnet-20241022, messages[{role: user, content: 讲一个程序员加班的笑话}], api_key你的Anthropic_API_Key ) # 调用本地 Ollama 模型 response_local litellm.completion( modelollama/llama3, messages[{role: user, content: 讲一个程序员加班的笑话}] ) print(response_openai.choices[0].message.content) print(response_claude.choices[0].message.content) print(response_local.choices[0].message.content)注意看model参数litellm 对不同模型服务有约定的格式通常是“服务前缀/模型名”的格式。比如 OpenAI 模型直接写模型名Anthropic 也是直接写模型名但本地 Ollama 模型就是ollama/模型名。这种约定在 litellm 文档中都有清晰说明。这样一段代码就完成了三个不同服务商的模型调用。如果将来要换模型或者换服务商你只需要改model字段和对应的api_key其他业务逻辑完全不用动。在上面的例子里我把api_key直接写在代码里了但真实项目中千万别这么做——密钥管理很关键建议通过环境变量设置。litellm 也支持通过环境变量读取密钥export OPENAI_API_KEY你的OpenAI密钥 export ANTHROPIC_API_KEY你的Anthropic密钥设置好环境变量之后代码里就不需要传api_key参数了litellm 会自动去环境变量中匹配对应的密钥。3.3 服务商返回格式统一这件事比表面看起来重要有时候我们在 Python 里打印 litellm 的返回值会看到它返回的对象结构和 OpenAI SDK 的返回结构几乎一样都包含choices、usage这些字段这就是它做的“返回结果标准化”。为什么说这件事重要因为我们做业务对接时需要处理各种逻辑——比如从返回结果中抽取文本内容、统计 token 消耗、获取对应的结束原因等。如果每家模型返回的字段结构都不一样那你的业务代码就要写大量的if provider openai这种类型判断。litellm 帮你把这些差异都抹平了拿到手的就是一个统一的响应对象写代码时心智负担小很多。我来展示一个更贴近真实业务的使用方式一个封装好的函数内部用它来调用任意模型并提取文本内容def ask_llm(model: str, user_query: str) - str: try: response litellm.completion( modelmodel, messages[ {role: system, content: 你是一个乐于助人的中文助手。}, {role: user, content: user_query} ], temperature0.7 ) return response.choices[0].message.content except Exception as e: # 统一异常处理记录日志 print(f模型 {model} 调用失败{e}) return 然后当你需要对比多个模型时只需要一个循环models [gpt-4o, claude-3-5-sonnet-20241022, ollama/llama3] question 用一句话解释什么是HTTP协议 for m in models: answer ask_llm(m, question) print(f模型 {m} 的回答\n{answer}\n —*40)实测下来这种方式写对比测试脚本效率很高。以前要做类似的事情我需要打开三个不同的 SDK 文档分别处理不同的鉴权逻辑现在全部统一在几行代码里搞定。3.4 代理服务器模式部署一个“模型网关”如果你是一个团队的技术负责人想给团队提供一个统一的模型访问入口那就需要部署 proxy 模式了。安装好litellm[proxy]后可以用命令行启动一个服务。先准备一个配置文件config.yaml内容大致是这样model_list: - model_name: gpt-openai litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-anthropic litellm_params: model: claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llama litellm_params: model: ollama/llama3然后启动代理服务litellm --config config.yaml --port 4000启动后本地会监听 4000 端口外部通过 OpenAI SDK 兼容的方式访问http://localhost:4000就行。比如用 Python 的 openai SDK 访问from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_key任意值代理层可能会校验但默认情况下可以配置跳过或统一校验 ) response client.chat.completions.create( modelgpt-openai, # 这里用的是配置里设置的 model_name messages[{role: user, content: 你好介绍一下自己}] ) print(response.choices[0].message.content)这个模式的关键点在于业务团队完全不用修改代码只要把base_url指到代理服务把model换成配置里自定义的model_name就能访问代理背后配置的任何模型。哪天你想把某个业务从 OpenAI 模型切换到 Claude 模型只需要修改代理的配置文件重启服务即可业务代码一行都不用动。我在实际部署中体会最深的点是代理模式是模型切换的“开关”业务代码是“灯泡”。你不需要去改灯泡的接线只需要在开关处控制电流走向就行。3.5 成本与 Token 统计做 AI 应用的人迟早都要面对的事不管是大模型 API 的账单还是内部多个业务线的成本核算Token 用量统计都绕不开。litellm 在返回结果中会带上usage信息包含prompt_tokens输入 Token 数、completion_tokens输出 Token 数和total_tokens总 Token 数。更实用的是litellm 还提供了成本估算能力。当你配置了模型对应的价格信息后部分默认支持需要你确认定价周期你可以通过litellm.completion_cost()直接算出一调用的费用import litellm response litellm.completion( modelgpt-4o, messages[{role: user, content: 写一段100字的产品介绍}] ) cost litellm.completion_cost(completion_responseresponse) print(f本次调用花费${cost})在企业里这个功能可以直接用于按业务线汇总模型消耗分摊成本设置成本阈值告警避免某个业务线费用失控在多个模型之间做性价比对比效果差不多但价格低 30% 的模型优先选做一个粗略的估算公式如果单次请求处理 2000 个输入 token 并生成 1000 个输出 token用某个 0.03 美元/千输入 token、0.06 美元/千输出 token 的模型计算一次调用大约是 0.03 × 2 0.06 × 1 0.12 美元。如果每天调用一万次那就是 1200 美元。通过成本估算提前做预算规划对公司决策很有帮助。4. 进阶玩法与实战细节litellm 不止能“调用模型”它还有很多实用的高级能力。这一部分分享几个我实际使用过并且觉得价值很高的功能。4.1 模型重试、超时和兜底降级策略在生产环境里模型服务商可能会不稳定也偶尔会遇到限流429 状态码或者服务不可用5xx。如果我们只在代码里写一次调用出错了就抛异常会让用户体验很不好。litellm 提供了一些内建的机制你可以通过参数来控制重试行为import litellm # 设置全局重试次数 litellm.num_retries 3 # 设置超时时间单位秒 litellm.request_timeout 30 # 自定义重试退避策略默认是1秒起步支持设置 litellm.max_retries 5除此之外比较进阶的操作是“模型兜底降级”。举个例子你的应用默认使用 GPT-4o但它出现了限流或故障你希望在这种情况下自动用一个备用的模型比如本地 Ollama 的 Llama继续服务而不是直接报错。litellm 的代理服务器配置里可以定义 fallbackmodel_list: - model_name: main-model litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: fallback-model litellm_params: model: ollama/llama3 litellm_settings: fallbacks: [{main-model: [fallback-model]}]这样配置之后当主模型调用失败时请求会自动尝试备用模型。对于实时在线业务来说这种降级策略能显著提升可用性。4.2 多模型路由与负载均衡当你的业务请求量很大或者想让不同请求尽量均匀地分配到多个模型实例上时代理模式中的路由能力就派上用场了。你可以在配置里把一个逻辑模型名对应到多个目标模型上model_list: - model_name: my-chat-model litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: my-chat-model litellm_params: model: claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY然后业务请求时指定model: my-chat-model代理会根据配置的策略支持轮询、随机、最少请求优先等分发到一个实际模型上。对于内部平台来说这种方式非常实用你可以用同一个 API 入口把不同用户的请求分发到不同模型上再配合权重设置实现按流量分配。比如 80% 流量走性价比模型20% 流量走最强模型做对比或验证。4.3 流式输出很多大模型应用都需要打字机效果也就是流式输出。litellm 对流的支持也比较到位。在代码模式下只需要传入streamTrueimport litellm response litellm.completion( modelgpt-4o, messages[{role: user, content: 写一个800字的旅游攻略}], streamTrue ) for chunk in response: if chunk.choices[0].get(delta, {}).get(content): print(chunk.choices[0].delta.content, end, flushTrue)我在本地测试过流式输出整体延迟表现不错各个模型在 litellm 层被统一成了相同结构的流式对象。如果你用 OpenAI SDK 兼容模式访问代理流式输出也能正常工作因为代理把底层的流式返回格式转为了 OpenAI 风格的流式格式上层代码拿到的是标准 SSE 流。需要注意的是流式输出对代理服务的并发连接数有一定要求。如果业务里流式请求特别多建议在代理服务前面加负载均衡避免单实例连接数过高导致新请求排队。4.4 嵌入模型支持litellm 不止做文本生成它还支持调用各种嵌入模型这在做语义搜索、向量数据库、知识库召回的场景中很有用。用法同样很简洁import litellm response litellm.embedding( modeltext-embedding-3-large, input[什么是大语言模型, 自然语言处理的常见任务], api_key你的OpenAI_API_Key ) embeddings response.data print(len(embeddings[0].embedding)) # 输出向量维度如果业务里需要同时使用文本生成和向量化两类能力统一用 litellm 也意味着你只需要维护一套工具链不用给不同的服务商分别准备 SDK。4.5 本地大模型的一碗水端平为什么我在多个示例里都提到 Ollama 和本地模型因为在做模型效果对比、隐私敏感数据处理、离线环境开发时本地模型往往是很好的补充方案。litellm 对 Ollama 的支持很好你在本地用 Ollama 启动模型后litellm 可以直接通过ollama/模型名来调用不需要额外的 API Key。此外litellm 还支持通过 OpenAI 兼容接口接入本地推理服务比如某些开源项目通过 vLLM 等框架启动的本地推理服务。这就让本地模型和云端模型在代码层面完全对等你可以放心地在不同环境本地开发、测试、生产中切换而不需要重写调用逻辑。5. 常见问题与排查经验实录说实话用 litellm 对接这么多家服务踩坑是难免的。这里我整理了一些高频问题的实测经验方便你遇到类似情况时快速定位。5.1 报错提示找不到对应的模型服务典型报错litellm.exceptions.BadRequestError或者Model not found之类。常见原因model参数里的服务前缀写错或者模型名称和实际服务商提供的名称不一致。litellm 识别模型服务是通过provider/模型名的规则如果你不写前缀它会默认当成 OpenAI 去解析自然找不到其他服务上的模型。排查与解决先在 litellm 文档的模型列表中确认“服务前缀”和“模型全名”的写法再对照一次代码中的参数。也可以直接在 Python 中打印出实际请求发送的目标地址方便确认是否按预期路由import litellm # 查看一个模型实际会请求的地址 url litellm.get_llm_provider(claude-3-5-sonnet-20241022) print(url)5.2 鉴权失败返回 401典型报错AuthenticationError: api_key not found或者Invalid API key provided。常见原因环境变量没有设置对应的密钥或者设置的环境变量名不是 litellm 约定的那个比如 OpenAI 密钥必须是OPENAI_API_KEYAnthropic 密钥必须是ANTHROPIC_API_KEY。排查与解决优先检查环境变量是否在当前进程可见。可以用echo $OPENAI_API_KEY这种方式确认。如果业务代码是在某个容器或服务器上跑的还要检查环境变量是否在部署配置中正确注入。5.3 返回内容被截断或者输出不完整常见原因max_tokens设置太小。有些模型服务在 litellm 中的参数会被转换成目标服务对应设置如果底层模型服务默认限制了最大输出长度而你传入的最大长度不匹配就会出现输出中断。排查与解决看一下返回结果中的finish_reason字段如果是length说明是因为达到长度限制而停止而非正常结束。可以调大max_tokens参数response litellm.completion( modelgpt-4o, messages[{role: user, content: 写一篇长文章}], max_tokens4096 )另外要注意不同模型单次请求的最大输出限制不一样有的 4K有的 8K还有的更少。最好了解目标模型的具体限制再设置合理的max_tokens。5.4 传参格式错误有时候你写代码传了temperature、top_p、presence_penalty等参数但目标模型服务不支持其中某些参数。litellm 会有两种处理方式一是忽略不支持的参数并继续调用二是直接抛出异常。这取决于目标服务商实现的具体行为。实测心得对于不支持某些参数的服务建议在调用前通过 litellm 提供的能力查一下该模型支持的参数列表。如果业务代码里有比较“激进”的参数组合可以对不同模型做参数差异化处理。比如在函数中把参数按模型类型分组避免强求一套参数走天下。5.5 代理模式下访问延迟偏高现象在代理模式下流式响应或者非流式请求整体比直连模型服务晚几百毫秒到数秒。原因请求多了一层代理转发网络耗时增加且 litellm 代理在处理某些复杂逻辑比如重试、路由时如果配置不够精简会增大开销。经验将代理服务器部署在与模型服务网络距离较近的地方避免在代理层配置过多无关联的 fallback 链只在必要时启用如果业务并发不高可以减少不必要的日志和统计插件实测中发现把代理和业务服务部署在同一地域或同一内网后额外延迟能控制在 50-100 毫秒左右基本可以接受5.6 安装依赖冲突现象安装litellm[all]后与项目其他包发生依赖版本冲突尤其是openai、pydantic等较常用的包。经验实测建议不要一上来就安装[all]。先装基础包按需补充缺的依赖。出现冲突时优先看错误信息中提示的具体库和版本要求通过虚拟环境隔离可以降低这类问题的影响。用pip install litellm[proxy]是折中方案既能用代理模式又尽可能少引入额外依赖。6. 个人使用体验和一些拓展想法最后说点我自己的感受。用过一段时间 litellm 后我最大的体会是它解决的不是“能不能调通”的问题而是“长期维护成本”的问题。AI 模型迭代速度很快今天好用的模型可能半年后就被更好的替代了。如果没有一个统一适配层每次模型切换都是一次伤筋动骨的改动。有了 litellm切换模型变成了一件很轻的事——改配置跑测试上生产。如果你在公司做技术基建我建议可以以小范围试点的方式推进 litellm。先让一两个项目通过代理模式接入跑通后把成本统计、模型切换、限流重试这些能力都沉淀下来再逐步推广到更多业务线。跟引入任何基础组件一样最好配上文档和内部示例让团队里的人快速上手。另外litellm 的社区版本使用上没什么门槛但是如果你想把它用到大规模生产环境建议仔细理解它的路由策略、并发模型、配置管理和监控告警能力。必要时可以对代理服务做压测确保在峰值流量下稳定运行。最后分享一个小技巧如果你在用 litellm 的代理模式别忘了利用它的health check能力定时检查配置的模型服务是否健康。配合 prometheus 等监控体系你可以把每个模型服务的成功率、延迟、耗时都量化出来后续做模型选型和容量规划时这些数据会很有说服力。总之litellm 不是一个能让你“一键解决所有模型调用问题”的神器但它所提供的统一接入思路和完善的工具链确实能大幅降低多模型场景下的维护成本。如果你正在被多模型对接、切换、成本核算这些琐事困扰花半天时间试试它大概率会有所收获。