LiteLLM：一个统一多模型API调用的开源网关方案-北京尧图网络

1. LiteLLM 到底解决什么问题一个 API 网关的诞生逻辑做 AI 应用做到某个阶段你一定会遇到这样一个问题代码里的模型调用五花八门某家用 OpenAI 的格式某家用 Anthropic 的格式本地跑的去连 Ollama私有化部署又要走 vLLM光是记住各家 API 差异就够写一篇技术文档了。我最后找到的最省事解法就是 LiteLLM——一个把几十家模型接口统一成同一套格式的开源网关。说起来很有意思LiteLLM 这个名字容易让人误以为它是个“轻量级大模型”但实际它和模型本身无关。它就是一个纯 Python 写的中间层你依然用 OpenAI 那套 SDK 的写法去调模型LiteLLM 在背后替你翻译请求、转发请求、管理密钥、控制预算甚至帮你做负载均衡和失败重试。换句话说你只需要学会一种接口格式就能调用市面上几乎所有主流的大模型。我以前带过一个项目最开始只用一家的模型代码写得很顺手。后来业务需要同时对比三家模型的效果为了切模型我在代码里写了三层 if-else每层对应不同的 SDK光是统一超时配置就折腾了两天。接入 LiteLLM 之后整个调用层缩成了不到二十行代码切换模型只需要改一个字符串。这种体验上的落差才是 LiteLLM 真正打动我的地方。那它具体适合谁如果你是个人开发者想在本地快速体验不同模型LiteLLM 的 SDK 模式足够轻量如果你在公司负责 AI 平台需要给团队统一模型入口、控制成本、审计调用记录LiteLLM 的 Proxy 模式几乎就是为你准备的。无论哪种场景它的核心价值都一样把“接模型”这件事从一个月的工作量压缩到一天。我在实际使用中反复确认过LiteLLM 并不仅仅是个“转换器”它在转换之外还做了三层很关键的事第一层是协议归一把各家的请求体、返回体、错误码都翻译成 OpenAI 风格第二层是路由调度可以在多个模型、多个密钥、多个供应商之间做分发第三层是治理能力密钥管理、预算限额、审计日志这些都是企业级网关该有的东西。这三点合起来才构成一个完整的“LLM Gateway”。1.1 为什么会聊到“统一 API 格式”这件事要理解 LiteLLM 的价值得先承认一个现状模型厂商之间从来没有为开发者考虑过接口兼容。OpenAI 的 Chat Completions 有 messages 数组和 role 字段Anthropic 的 Messages API 却用 system 独立字段加 content 数组Google 的 Gemini 又是另一套 generationConfig 结构本地 Ollama 的 /api/chat 走的是精简版 OpenAI 风格但不完全一致。每个 SDK 的安装方式不同、错误类型不同、流式返回的数据片结构不同。这个问题的本质是“模型接口碎片化”。对一个业务团队来说每多接一家模型就要多维护一套调用代码、一套错误处理逻辑、一套鉴权方式而且这些代码往往只为了某一个供应商存在没法复用。更麻烦的是当你想在几个模型间做 A/B 对比时代码改动的范围会超出预期因为各家的超时时间、最大 token 限制、重试策略都是独立的。LiteLLM 的统一思路很简单既然 OpenAI 的 API 格式已经被广泛接受成了事实上的行业标准那就让其他所有模型都“说”OpenAI 的话。你在代码里写一个client.chat.completions.create把相同结构的参数传进去LiteLLM 会判断目标模型属于哪一家然后自动转换成对方需要的请求格式。等于你做应用开发永远只面对一套接口契约。1.2 LiteLLM 的双层架构SDK 模式与 Proxy 模式LiteLLM 提供两种使用形态初学者容易混淆我分开讲清楚。第一种是 SDK 模式你在自己的 Python 代码里直接import litellm调用litellm.completion()或者litellm.embedding()LiteLLM 作为库被嵌入你的进程里。这种方式适合个人项目、小服务、脚本工具不需要额外部署任何东西venv 里装个包就能跑。第二种是 Proxy 模式你启动一个独立的 LiteLLM 服务进程它对外暴露一个标准的 OpenAI 兼容接口也就是一个 HTTP 服务器。你的应用代码不再直接碰 LiteLLM 库而是像调用远程 OpenAI 服务一样去请求这个代理。Proxy 模式承载了更多企业级能力比如虚拟密钥、预算控制、调用审计、多模型负载均衡这些都是 SDK 模式没有的。两者的选择并不冲突。我个人的习惯是本地验证想法用 SDK 模式一旦要上生产环境或者要交付给团队统一使用立刻切换到 Proxy 模式。因为 Proxy 模式把模型接入的复杂度收拢到一个独立服务里业务代码完全感知不到底层有多个模型供应商这在多人协作、多服务部署的场景下优势极其明显。1.3 用生活化的方式理解 LiteLLM 的工作位置我经常给团队同事打一个比方LiteLLM 就像你出差时随身带的多口转换插头。插座标准五花八门你不可能每去一个地方就买一套专用的电线你只需要一个转换头把任何插座都变成你能用的形式。LiteLLM 就是这个转换头只不过它转换的不是电流而是各家模型的 API 协议。但它又比转换头多做了几件事。它像一个有“脑子”的转换头知道哪个插座容量不够时换另一个插座供电知道这栋楼的电费是多少并帮你记账知道某个插座临时故障时自动切换到备用口。对应到技术上就是模型选择、成本控制、故障转移。这也是我对 LiteLLM 定位的理解它不只是一个格式翻译器更是一个 AI 应用的流量入口与策略引擎。2. SDK 层实操从安装到统一调用那些模型先聊 SDK 模式因为它是理解 LiteLLM 内部逻辑最快的路径。日常开发里我用 LiteLLM 的 SDK 模式最多的地方就是写脚本做模型效果评测、跑实验对比、或者在小型服务里快速接一个模型。它最大的特点就是省事不需要维护多套 SDK也不用启动任何额外服务。2.1 环境准备与安装LiteLLM 是一个纯 Python 库安装方式没什么特别直接用 pip 就行。有一点需要注意它会顺带装不少依赖比如 pydantic、openai 等如果在已有项目里安装建议单独建虚拟环境避免和项目里其他依赖打架。我一般在做模型接入相关的项目时会直接开一个新的 venv 或者 conda 环境。pip install litellm[proxy]这里我用了[proxy]的 extra 安装因为我知道后面一定会用到代理服务。如果你只想要 SDK 模式装pip install litellm就够。安装完成之后可以跑一下自带的版本命令确认环境正常然后顺手看一眼支持的模型列表。python -c import litellm; print(litellm.__version__) python -c import litellm; print(litellm.model_list)2.2 首次调通写一段最简单的模型调用装好之后最快验证通路的方式就是调一次litellm.completion()。大多数模型服务都需要 API 密钥推荐的做法是用环境变量配置不要硬编码在代码里。LiteLLM 默认会读取一些常见的环境变量名比如OPENAI_API_KEY、ANTHROPIC_API_KEY等这样你在代码里就不用写api_key参数了。import os import litellm os.environ[OPENAI_API_KEY] your-openai-key os.environ[ANTHROPIC_API_KEY] your-anthropic-key # 调用 OpenAI 系模型 response_openai litellm.completion( modelgpt-4o-mini, messages[{role: user, content: 你好请简单介绍一下自己}], ) # 调用 Anthropic 系模型 response_anthropic litellm.completion( modelanthropic/claude-3-5-sonnet, messages[{role: user, content: 你好请简单介绍一下自己}], ) print(response_openai.choices[0].message.content) print(response_anthropic.choices[0].message.content)注意看第二段代码模型名前面多了anthropic/前缀这是 LiteLLM 识别模型所属供应商的方式。如果你要调 Google 的 Gemini就写gemini/gemini-1.5-pro调本地 Ollama 就写ollama/llama3调 Azure OpenAI 就写azure/gpt-4o。这个前缀机制很重要后面我们讲配置文件和排查问题时还会反复提到它。我第一次用的时候犯过一个错直接把模型名写成了claude-3-5-sonnet没加anthropic/前缀结果 LiteLLM 把它当成 OpenAI 系的模型去请求然后报了一个模型不存在。这件事给我的教训就是LiteLLM 的模型名规则是“供应商前缀模型名”前缀不能省。想知道一个模型到底应该怎么写去 LiteLLM 文档的模型列表里查一次比在代码里猜要快得多。2.3 进阶用法流式、异步、函数调用模型调用进入真实业务场景之后光会completion()不够。最常遇到的是流式输出需求也就是像 ChatGPT 那样一个字一个字地往外蹦。LiteLLM 对这个场景的支持很直接加一个streamTrue参数就能拿到生成器。response litellm.completion( modelgpt-4o-mini, messages[{role: user, content: 写一段关于秋天的短文}], streamTrue, ) for chunk in response: delta chunk.choices[0].delta.content if delta: print(delta, end, flushTrue)流式返回的每个 chunk 结构基本上和 OpenAI 的流式格式一致所以如果你之前写过 OpenAI 流式代码几乎可以无缝迁移。还有一点不同供应商的流式行为不一致有些是逐 token 返回有些是分块返回但 LiteLLM 已经在内部帮你抹平了差异你在上层拿到的永远是 OpenAI 风格的 chunk。再就是异步调用。在高并发场景下用异步能显著提升吞吐量。LiteLLM 提供了litellm.acompletion()接口用起来和同步版本几乎一样只是需要配合await使用。import asyncio import litellm async def main(): response await litellm.acompletion( modelgpt-4o-mini, messages[{role: user, content: 写一首五言绝句}], ) print(response.choices[0].message.content) asyncio.run(main())异步版的内部实现实际上是把请求丢进了线程池去处理所以在某些严格限制线程数的环境里要注意别把线程池撑爆。另外函数调用Function Calling在 LiteLLM 里同样做了统一各家模型只要支持都能识别 OpenAI 格式的tools参数这点我在多模型适配的业务里用过多次确实省心。2.4 SDK 层容易踩的几个坑SDK 模式看着简单实际用起来有几个坑值得单独提醒。第一个是环境变量大小写问题。比如 Azure OpenAI 配置里有一堆像是AZURE_API_VERSION、AZURE_API_BASE之类的变量拼写和大小写必须和 LiteLLM 预期的一致否则认证就会失败。排查这类问题最好的办法是打开日志设置litellm.set_verbose True就能看到完整的请求日志。第二个坑是超时设置。LiteLLM 默认的请求超时时间有时会比较长而且不同供应商的默认值可能不一样。如果你的业务对响应时间敏感一定要显式设置request_timeout建议给一个你认为合理的值比如 30 秒而不是依赖默认值。第三点关于模型重试。LiteLLM 内部自带简单的失败重试机制但默认的重试次数、重试间隔不一定适合你的场景。遇到上游服务限流的问题重试反而会加剧限流所以要认真配置num_retries和retry_interval不要盲目提高重试次数。我现在习惯把 num_retries 控制在 2 次以内让错误快速暴露出来。3. Proxy 模式把模型接入做成一件事如果说 SDK 模式是给个人开发者准备的便利工具那 Proxy 模式就是给团队、给生产环境准备的基础设施。我一开始只用 SDK 模式后来同事多了人人都来问“你的 API Key 是什么”“我要接的模型怎么配”我才意识到统一网关是必然选择。LiteLLM 的 Proxy 模式本质上就是一个专为 LLM 场景设计的 API 网关。3.1 为什么团队协作迟早要走到 Proxy让大家各自拿着 SDK 接模型短期看着灵活时间一长就是灾难。每个人的代码里都有自己的模型配置、自己的密钥管理方式有人把 API Key 写死在代码里有人根本没设超时。一旦你要给团队换一个底层模型就得通知所有人改代码。这个场景下Proxy 模式的核心价值就出来了模型相关的所有配置全部收敛到一个服务里业务代码只需要知道一个网关地址。除了配置收敛Proxy 模式还把一个很关键的能力带出来了——密钥隔离。你完全可以用一个网关主密钥按团队、按项目、按个人生成不同的虚拟密钥每个虚拟密钥可以绑定不同的模型白名单、不同的预算上限。这样团队成员各用各的密钥互不干扰出问题比如某个密钥被滥用时可以直接吊销不影响其他人。还有审计日志。LiteLLM Proxy 会把每次调用的模型、Token 数、耗时、密钥标识记录下来配合数据库存储就能做成本分析、用量追踪。这个能力在“模型费用分摊”“服务容量规划”这些场景下特别有用。一个网关把模型接入这件事从“每个人的技术活”变成了“平台的一项能力”。3.2 config.yamlProxy 的中枢神经Proxy 模式的一切配置都围绕一个 YAML 文件展开叫config.yaml。启动代理时通过--config参数指定这个文件。这是整个 LiteLLM Proxy 最核心的部分我把一个生产环境用得比较多的配置写出来逐字段解释。model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llama litellm_params: model: ollama/llama3 api_base: http://localhost:11434 litellm_settings: drop_params: true set_verbose: false num_retries: 2 request_timeout: 30 cache: true cache_params: type: redis host: localhost port: 6379 general_settings: master_key: sk-your-master-key-here database_url: postgresql://user:passwordlocalhost:5432/litellm先看model_list它是路由的入口表。每个条目有一个model_name这是你对外暴露给调用方的名字业务代码请求的时候只认这个名字。底下的litellm_params.model才是真正的供应链路由openai/、anthropic/、ollama/这些前缀决定请求会被翻译成哪家格式、发到哪个地址。这里一个比较巧妙的设计是多个条目可以共用同一个model_name。比如我把同一个model_name配置到两个不同的供应商上LiteLLM 就会在它们之间做负载均衡。这个能力在“多云容灾”场景里很好用OpenAI 挂了流量自动转到本地或者其他家。litellm_settings段是全局行为配置。drop_params: true值得专门讲一下各家的请求参数并不完全一样比如top_p、frequency_penalty这些参数有些供应商根本不支持如果传过去就会报错。打开drop_params后LiteLLM 会自动丢弃目标供应商不支持的参数这个开关我强烈建议在生产环境打开。general_settings段管的是网关自身的运维配置。master_key是代理服务的主密钥所有管理接口的访问都要用到它。另外建议开启database_url把调用日志、密钥信息持久化到数据库里。没有数据库很多统计功能会退化为内存模式重启就丢数据。3.3 启动代理与验证通路配置文件写好后启动代理服务非常简单。默认监听在 8000 端口你可以通过参数调整。litellm --config ./config.yaml --port 8000启动成功后可以先用一个简单的 curl 请求验证通路。因为 LiteLLM Proxy 对外提供的是 OpenAI 兼容接口所以你可以用任何 OpenAI SDK 的客户端去连它只需要把 base_url 指到代理地址即可。curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-master-key-here \ -d { model: claude-sonnet, messages: [{role: user, content: 你好}] }这里传给model的参数是config.yaml里定义的model_name也就是claude-sonnet而不是真正的供应商模型名。这个隔离设计让上层业务完全不用关心底层到底是哪个模型将来你把claude-sonnet背后的实现从 Anthropic 换成本地 vLLM业务代码一行都不用改。3.4 虚拟密钥、预算控制与负载均衡Proxy 模式有一个非常实用的管理接口体系都是通过 HTTP 调用的。我用得最多的是/key/generate这个端点用来创建虚拟密钥。你可以限制这个密钥能访问哪些模型、能花多少钱甚至绑定到某个用户或团队。curl -X POST http://localhost:8000/key/generate \ -H Authorization: Bearer sk-your-master-key-here \ -H Content-Type: application/json \ -d { models: [gpt-4o-mini], budget: { budget_limit: 100, time_period: 30d } }返回结果里有一串以sk-开头的 key把它发给对应的团队成员他们就能用这个 key 请求代理。虚拟密钥的价值在于第一真正的上游密钥不会暴露给任何团队成员第二每个密钥的预算独立谁超额了系统会自动拦截不需要人工干预。负载均衡的配置在前面说过原理在model_list里model_name相同、litellm_params不同的条目之间LiteLLM 默认会做轮询分发。如果你需要不同权重可以用路由策略参数控制。这个能力我通常用在“主备切换”场景一个容量较大的主力供应商、一个成本较低的备用供应商主供应商限流时自动降级到备用。3.5 Proxy 生产化部署的关键经验Proxy 模式一旦跑在生产环境有几个经验值得分享。第一个是 Docker 部署。LiteLLM 官方提供了现成的镜像用 Docker Compose 可以很轻量地把代理服务和配套的 Redis、PostgreSQL 都编排起来隔离性比直接裸跑进程好很多。我一般会把config.yaml和.env文件挂载进容器不把密钥写进镜像。第二个经验是端口与网络。如果你的业务服务分布在不同的网络区域要确保它们都能访问到代理服务的端口同时做好访问控制不要让代理端口暴露到公网。建议在代理前面放一层网关比如自带鉴权的 API 网关负责更细粒度的流量控制。还有个容易忽略的点代理服务的日志。日志里会包含完整的请求参数和响应内容这些数据里可能有用户输入或生成结果要注意脱敏和访问权限控制。尤其是在多租户使用场景下日志数据的安全边界要提前划清楚别等出问题了再去亡羊补牢。4. 常见问题排查与避坑实录技术文章写到最后我一般都会把自己踩过的坑整理出来。LiteLLM 用久了问题是会集中出现在几个地方系统性排查效率很高。下面这张表是我在多个项目里沉淀下来的高频问题速查配合后面的详细解释一起看。现象常见原因解决方案模型不存在错误模型名前忘了加供应商前缀检查model参数确认前缀格式请求超时默认超时时间过长或模型响应慢显式设置request_timeout参数报错某些供应商不支持部分采样参数打开drop_params: true流式输出卡住上游接口不稳定或超时配置太短检查流式请求的超时适当调大密钥鉴权失败master_key 或虚拟密钥配置不对检查Authorization头确认密钥有效并发一高就失败连接池或线程池太小调大并发数或考虑多实例部署缓存命中但结果奇怪缓存语义错误地命中了不同请求关闭缓存或细化缓存 key4.1 模型名前缀与格式问题这个是我见到开发者问得最多的。LiteLLM 的模型名规则可以理解为“目标供应商前缀/模型标识符”。比如 OpenAI 系的可以直接写gpt-4o-mini也可以写openai/gpt-4o-mini但 Anthropic 的必须写anthropic/claude-3-5-sonnetGoogle 的写gemini/gemini-1.5-pro本地的写ollama/llama3。很多人刚上手时不习惯这个规则写错了就会得到模型不存在的报错。判断方法很简单去 LiteLLM 官网的模型列表页查一下你要用的模型名它写了什么你就用什么。如果用了自定义模型名要确认litellm_params里面映射的model字段前缀正确。我排查这类问题上最快的动作就是打开 verbose 日志看实际发出的请求地址是什么。4.2 超时与重试策略怎么配才合理超时问题在接 Anthropic 和 Gemini 时特别容易遇到因为它们的推理速度可能比 OpenAI 更慢如果沿用 OpenAI 时代的超时设置就会频繁超时。反过来如果你把所有超时都调成很大的值一旦上游真的挂了你的应用会长时间卡住。我的做法是分层设置第一层LiteLLM 的request_timeout设为业务可接受的上限比如 30 到 60 秒第二层依赖上游 SDK 自带的超时比如有些供应商 SDK 默认连接超时是 10 秒读取超时是 60 秒。两层配合既能兜底又能快速暴露问题。重试策略上num_retries设 2 次我认为比较平衡间隔时间建议逐步扩大避免同时间打爆上游。4.3 缓存与日志的两个深坑缓存是我用 LiteLLM Proxy 时最小心的地方。它的缓存机制可以缓存 LLM 的完整响应降低重复请求的开销和费用。但大模型输出天然带有随机性如果业务要求每次生成结果不同打开缓存反而会出问题。我建议只在确定性比较强的场景比如知识问答、关键词提取里开缓存而且最好把缓存的 key 配置得细一点把 temperature、top_p 这些采样参数都纳入 key避免不同参数的请求互相污染。日志这块前面已经提醒过脱敏问题再补一个点LiteLLM 的日志是可配置的可以根据需求调整日志级别。生产环境建议把set_verbose关掉避免记录过于详尽的请求体既能减少存储压力也降低敏感信息泄露的风险。出了问题需要排查时临时打开 verbose完事再关掉。5. 一个很实用的小技巧在网关层面做模型 A/B 测试最后分享一个我把 LiteLLM 用出额外价值的场景模型选型对比。很多团队想在 OpenAI、Anthropic、本地开源模型之间做效果评估往往需要写一套并行调用代码然后手工整理结果。有了 LiteLLM Proxy 之后这个事变得非常简单。思路是在config.yaml里把不同供应商的真实模型映射到同一个model_name下面然后轮流切换litellm_params.model指向的目标或者直接配置两个不同名的模型入口。然后用一个脚本同时请求这两个入口把返回结果、Token 消耗、响应耗时都记录下来做对比。我实际用下来这套方案比在业务代码里写多供应商适配要省事得多。而且因为通过网关统计成本数据也是现成的直接就能算出每个模型回答一次的平均成本。我当时就是通过这种方式说服团队把一部分高频低复杂度的问题从商用模型迁移到本地模型成本降了将近一半效果差距却很细微。LiteLLM 这个东西初看以为是工具用久了会发现它更像一种接入模型的“方法论”把复杂的、易变的模型生态屏蔽在业务视角之外。我个人到现在仍保持着一个小习惯——每次新项目起步接模型先把 LiteLLM 搭起来再去谈业务逻辑这省下来的时间远比想象中要多。如果你正在被多模型接入折磨不妨花一个下午把 Proxy 跑起来我相信你也会得出类似结论。

LiteLLM：一个统一多模型API调用的开源网关方案

相关推荐

从“ArtCraft”看手作创作：艺术灵感与工艺实现的缝合点

Java团队用LangChain4j打造医疗智能客服：多轮对话与RAG实战

多模态大模型训练避坑指南：归一化、激活函数与架构一致性

更多资讯

嵌入式C与标准C的差异：内存、运行时与编译器行为解析

UWB定位锚点三合一实测：中继、定位、信标如何兼顾部署效率

PLC工程师实战错题本：90条现场踩坑经验与避坑指南

从零理解电机旋转电压矢量：Clarke/Park变换与SVPWM仿真实践

从零搭建步兵机器人：硬件选型、供电与通信全解析

读懂HCU控制模块说明书：状态机、标定与故障码排查

今日更新

微信云开发旅游小程序实战：LBS打卡+UGC社交全栈方案

金融AI代理平台核心拆解：从多代理协作到财报分析实战

基于大数据的智慧旅游推荐与可视化平台架构实践

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？