Litellm 网关层详解：统一 OpenAI、Claude、Gemini 等模型接口-北京尧图网络

Litellm 这个名字我建议所有做 AI 应用的后端开发都先记下来。它不是一个AI 神器或者花哨的提示词工具而是一个被很多团队实打实用了很久的 LLM 网关层。一句话概括它把 OpenAI、Anthropic、Google、Azure以及各类基于 OpenAI 协议的开源模型服务全部统一成一套 OpenAI 兼容接口让你用一份代码、一个地址去调用所有模型。我最初接触 litellm是因为一个内部工具要同时接入 GPT 系列、Claude 和本地部署的开源模型做效果对比。原本每个人对接方式都不一样参数命名也不统一有的叫 max_tokens有的叫 max_output_tokens有人在代码里对着各家文档疯狂做 if else 适配看着就头疼。后来项目里有人提议用 litellm 把这一层收敛掉结果证明这几乎是当时最正确的决定。它适合谁后端开发、AI 应用工程师或者带一个小团队做 AI 产品的人。如果你手上同时有多个模型提供方的 key想统一管理调用、路由、限流和成本又不想自己写一个完整的适配层和网关litellm 是同类方案里最省事的一个。下面我把它的核心原理、部署模式、进阶配置以及我在实际使用中踩过的坑完整讲一遍希望你能少走点弯路。1. litellm 到底在做什么统一接口背后的三种能力1.1 接口差异是真实痛点不是矫情很多人觉得各家 API 不就是换个 URL 和鉴权头嘛真去接的时候才知道不是这么回事。OpenAI 的 Chat Completions 返回结构是 choices 数组里套 messageAnthropic 的 Messages API 返回结构是 content 数组Google 那边又是另一种 JSON 结构流式输出的格式更是五花八门。更烦人的是参数名。OpenAI 用 max_tokensGoogle Gemini 用 max_output_tokensOpenAI 的 system prompt 是 messages 里的 system roleAnthropic 是单独一个 system 字段Claude 还有 temperature、top_p 支持范围也不一样。工具调用function calling在各家的定义更是各玩各的。这些差异单看哪一个都不难适配难点在于你要维护的模型数量一多组合数就爆炸了。今天业务方说把默认模型从 4o 换成 Sonnet你不仅要改配置还得确认代码里有没有用到不受支持的参数有没有读取响应里某个字段。模型换成 Gemini又要重新看一遍文档。这种适配工作极其消耗精力而且没有任何业务价值纯属给生态分裂买单。1.2 请求改写、响应还原、流式兼容litellm 做的事本质上就是把你和各家 SDK 之间做一个翻译层。你只管用 OpenAI 风格发请求它内部把请求改写成目标模型服务商认识的格式再把响应还原成 OpenAI 风格给你。具体拆开是三件事第一是请求改写。你在 litellm 里传 model 参数的时候带上供应商前缀比如 claude-3-5-sonnet、gemini/gemini-1.5-pro、ollama/llama3.1:8b它根据前缀找到对应的供应商把 messages、temperature、max_tokens、tools 这些参数映射成目标 API 的字段。比如传过去的 max_tokens 会被翻译成 Gemini 的 maxOutputTokenstools 会被改写成对方认识的 tool 定义格式。第二是响应还原。各家返回的 token 用量、角色字段、内容位置都不一样litellm 统一转成和 OpenAI SDK 一致的 response 结构。你在代码里response.choices[0].message.content拿内容不管背后是哪个模型写法完全一样。这一点对业务代码的稳定性影响很大换模型的时候大部分代码根本不用动。第三是流式兼容。各家流式接口的 SSE 事件格式不同Anthropic 是 event 流OpenAI 是 choices 增量litellm 把后端的流翻译成 OpenAI 的 chunk 格式。你客户端只要按 OpenAI 的方式解析 stream 就行。这就是为什么我说它更像翻译层而不是SDK 封装。SDK 只是替你说了一门语言翻译层是你说一种语言它能把你的话转给所有语种的人。1.3 为什么不建议自己写适配层当然自己写也不是不行能跑但你会很快遇到几个问题。首先是知识成本。你要维护各家 API 的变更今天这个供应商把某个字段 deprecated明天那个改了限流策略光跟踪文档就够喝一壶的。litellm 背后有一套持续跟进的维护机制这些信息它帮你消化掉了。其次是功能扩展。你要做故障转移、负载均衡、预算控制、虚拟 key全部自己写的话工作量不比业务系统小。litellm 这些基本都内置了你只需要填配置。最后是团队协作。你自己写的适配层注释水平取决于当时写代码的人状态人一走就是灾难。litellm 是开源项目有社区、有文档、有 issue 沉淀后来的人接手成本低得多。所以自己写更可控这个想法我建议只停留在我试过之后真的后悔了这个阶段就够了。2. 核心组件与部署形态SDK、Router、Proxy 三件套2.1 三种使用方式定位完全不同litellm 不是一个单一形态的库它有三种典型用法对应不同需求。第一种是当作 Python SDK 直接在代码里用。litellm.completion(modelgpt-4o, messagesmessages)这种方式适合快速验证、写脚本、在单机应用里直接用。不需要起服务装个 pip 包就行。第二种是 Router 模式。它在 SDK 之上加了一层路由能力你可以同时配置多个模型、多个 key、多个供应商Router 负责负载均衡、健康检查、失败重试和故障转移。适合需要高可用的业务服务在代码里初始化一个 Router 实例然后到处调用。第三种是 Proxy 模式这是团队使用最推荐的方式。litellm 启动一个独立的服务暴露 OpenAI 兼容的 HTTP 接口你现有的 OpenAI SDK、LangChain、或者其他任何支持自定义 base_url 的工具直接把地址指向 litellm 就行。业务方根本不需要知道自己背后接的是什么模型也不需要安装 litellm。所有 key 管理、限流、日志都在网关这一层完成。这三种模式可以叠加。有了 Proxy 之后Router 的故障转移能力依然可以配置在网关层SDK 则退化成业务方手里的通用客户端。2.2 Proxy 模式的定位团队里的唯一出口Proxy 模式我最看重的一点是它把模型供应商的 key 从业务代码里剥离了。没有网关之前每个项目都要配置 OPENAI_API_KEY有人还直接把 key 硬编码在代码里或写进前端请求。有了 litellm 做网关业务方只需要知道一个网关地址和一个虚拟 key真正的供应商 key 全部锁在网关配置里权限收敛了很多。另一个价值是对所有模型调用做统一观测。所有请求都经过 Proxy 这个唯一出口自然就能记录每次调用的模型、耗时、token 用量和费用哪个团队在烧钱一目了然。如果你准备让公司里多个项目组共用一套模型资源这个价值比省那点适配代码重要得多。2.3 模型别名与路由的玩法litellm 配置里有个关键概念叫 model_name 和 litellm_params 分离。你可以给一个模型起个业务别名比如 model_name: company-main 实际指向 litellm_params 里的 gpt-4o还可以让同一个 model_name 指向多个真实模型由 Router 做分配。这样业务方永远只认你的逻辑名称底层换模型、加并发副本业务方完全无感。这个设计很实用。比如你担心gpt-4o这个 API 模型名在未来被上游废弃业务侧代码又写死了字符串那就在 litellm 里定义一个别名即可底层换成新版本模型一行配置的事业务代码都不用动。3. 实操入门从安装到把请求打通的完整过程3.1 安装与第一个 completion 请求安装很简单pip 直接装pip install litellm装完之后先确认环境变量里有对应的供应商 key。比如要调 OpenAI就设置export OPENAI_API_KEY你的key然后写个最简单的调用import litellm response litellm.completion( modelgpt-4o, messages[ {role: system, content: 你是一个简洁的助手}, {role: user, content: 用一句话解释什么是路由器} ], temperature0.3 ) print(response.choices[0].message.content)跑通这一小段说明安装、鉴权、请求翻译全部正常。如果要同时调 Anthropic不用改代码只需要把 model 参数换成claude-3-5-sonnet并且在环境变量里加上 ANTHROPIC_API_KEY。这就是统一接口最大的直观感受代码不动换模型只换字符串。再复杂一点你可以请求流式输出response litellm.completion( modelgpt-4o, messages[{role: user, content: 写一段 200 字的产品简介}], streamTrue ) for chunk in response: delta chunk.choices[0].delta.content if delta: print(delta, end)流式输出的 chunk 已经被 litellm 标准化成 OpenAI 风格直接按 OpenAI 的解析方式处理就行了。3.2 用配置文件把 proxy 跑起来SDK 模式适合单人用。如果要多团队共用或者想统一收口 key 和策略得用 Proxy 模式。先创建一个配置文件比如 proxy_config.yamlmodel_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: sonnet litellm_params: model: claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY - model_name: gemini-pro litellm_params: model: gemini/gemini-1.5-pro api_key: os.environ/GEMINI_API_KEY general_settings: master_key: sk-gateway-master-001注意 model_name 不带供应商前缀它是暴露给业务方的逻辑名称litellm_params.model 才是带前缀的真实模型标识。api_key 可以写成 os.environ/环境变量名litellm 会自动从环境变量读取避免把密钥明文写进配置文件。然后启动litellm --config proxy_config.yaml --port 4000启动后litellm 会监听 4000 端口。你可以直接 curl 验证curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-gateway-master-001 \ -d { model: gpt-4o, messages: [{role: user, content: 你好}] }如果配置没问题这里返回的 JSON 结构和 OpenAI 官方接口基本一致。这就是整个网关的核心入口。3.3 用 OpenAI SDK 接入 litellm Proxy网关起来之后业务方接入非常傻瓜。任何一个支持自定义 base_url 的 OpenAI SDK 都可以直接用不需要安装 litellm。from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-gateway-master-001 ) response client.chat.completions.create( modelsonnet, # 这是配置里的逻辑名称 messages[{role: user, content: 介绍一下你自己}] ) print(response.choices[0].message.content)这里最关键的一点是model 参数传的是配置文件里的 model_name而不是真实的供应商模型名。业务方只需要知道我调用 sonnet 这个逻辑名至于 sonnet 背后是 Claude 哪个版本、key 是哪个、会不会被路由到别的模型都是网关侧的事。LangChain 也一样设置 OpenAIChat 时把 base_url 指向 litellm 网关即可。对已有项目来说改动量很小。3.4 接入本地模型和 OpenAI 兼容服务生产环境经常要接私有化部署的模型比如用 vLLM、SGLang 起了个 OpenAI 兼容服务。litellm 对这类服务支持很直接配置里用openai/前缀再指定 api_base 就行model_list: - model_name: qwen-local litellm_params: model: openai/qwen2.5-72b-instruct api_base: http://127.0.0.1:8000/v1 api_key: fake-key这样本地模型也进入了统一路由业务方调 qwen-local 就能同时用上远程和本地模型故障转移也能把流量从远程模型切到本地模型。还有一类常见的本地服务是 Ollama前缀换成ollama/- model_name: llama-local litellm_params: model: ollama/llama3.1:8b api_base: http://localhost:11434接入门槛同样很低Ollama 服务跑起来litellm 配好业务方就是一个新的模型名。4. 进阶配置成本、限流、故障转移与可观测性4.1 成本统计与预算设置模型调用成本是很多团队忽略的隐性炸弹尤其是做批量任务时一个循环调几万次接口月底账单能让人当场社死。litellm 对成本追踪做得很细。代码里直接拿响应算钱import litellm from litellm import completion_cost response litellm.completion(modelgpt-4o, messages[...]) cost completion_cost(completion_responseresponse) print(f本次调用花费: ${cost:.6f})它内部自带一份常见模型的价格表会根据 prompt tokens 和 completion tokens 分别计算。对自定义模型你可以在配置里补充 model_infomodel_list: - model_name: my-custom-model litellm_params: model: openai/qwen2.5-72b-instruct api_base: http://127.0.0.1:8000/v1 api_key: fake-key model_info: input_cost_per_token: 0.000002 output_cost_per_token: 0.000006在 Proxy 模式下还可以给每个虚拟 key 设置预算上限一个团队一个 key预算一超直接拒绝请求防止有人写个 bug 导致整个账号半夜刷爆。4.2 限流和并发控制很多供应商对 API 有 RPM、TPM 限制尤其是共享账号时一不小心就触发 429。litellm 的路由层可以做两层控制。第一层是全局并发控制。在配置里限制整个网关的最大并发请求数防止业务高峰把后端供应商打爆general_settings: max_parallel_requests: 100第二层是 per-key 限制。生成虚拟 key 时可以指定这个 key 允许的模型范围、预算上限、每分钟请求数。这个虚拟 key 的速率限制是在网关侧执行的不会被供应商的限流策略突然打断。实际操作中我倾向于把限流值设置得比供应商限制激进一些比如供应商允许 60 RPM我就在网关侧设 50 RPM留出余量给重试和并发波动避免一堆请求同时撞墙。4.3 故障转移与重试这是 Router 和 Proxy 模式下最有价值的功能。一个模型挂了、被限流了、或者响应超时litellm 可以自动把请求转到备用模型。在 Proxy 配置里加 router_settingsrouter_settings: fallbacks: [ {gpt-4o: [sonnet, gemini-pro]}, {sonnet: [gpt-4o]} ] num_retries: 2 retry_after: 2意思是当 gpt-4o 失败时尝试转到 sonnet再不行转到 gemini-pro每个模型节点最多重试 2 次重试间隔 2 秒。这样业务方调用时完全感知不到故障只看到最终成功了。配合 Retry 机制一起看它是先重试同节点再转移节点。设置重试次数和转移策略时要注意一个现实问题如果请求内容很长重试成本会翻倍。所以对长上下文的请求我的建议是重试次数不要超过 1转移顺序把成本更低的模型放前面。4.4 日志、Trace 与回调没有观测的网关等于没有网关。litellm Proxy 本身就带请求日志你可以把成功和失败回调接到自己的可观测系统里。代码模式下用回调就够litellm.success_callback [langfuse] response litellm.completion( modelgpt-4o, messages[{role: user, content: 记录一次调用}] )回调会自动把 token 数、模型、耗时、成本等元数据送出去不需要在业务代码里埋点。Proxy 模式下还有两个比较实用的端点一个是 /health用来做网关的健康检查另一个是 /models用来列出当前网关所有可用的逻辑模型名。接入负载均衡或者给前端展示模型列表时这两个端点很省事。5. 踩坑实录最常遇到的五个问题与排查思路5.1 model_name 对不上导致的 404第一次用 Proxy 的人十有八九会遇到这个。你在代码里明明用的是 claude-3-5-sonnet但配置里 model_name 定义的是 sonnet结果请求返回 404 或者模型不存在。原因很简单Proxy 只认配置里的 model_name不认供应商的真实模型名。你的逻辑名字和配置不一致网关层根本不知道这个模型是什么。排查思路分两步先 curl /models 看看网关实际暴露了哪些模型名再检查请求体里的 model 字段是否和配置的 model_name 完全一致。这个完全一致包括大小写、连字符一个字符都不能差。我们当时就在配置里写了两个 gpt-4o 的定义一个带版本后缀一个不带结果请求方用错名字找了大半天。5.2 超时问题长输出和高延迟模型litellm 默认超时时间比较短遇到长输出任务比如让模型生成 2000 行代码或者用 Claude 处理超大上下文请求很容易在网关层被掐掉。当时我们内部跑一批长文本生成任务8 个请求里能有 3 个超时第一反应是模型太慢后来发现是网关把请求给截了。解决方式是在 litellm_params 里加超时配置- model_name: sonnet litellm_params: model: claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY timeout: 600或者全局设置litellm_settings: request_timeout: 600我的习惯是短交互模型设 60 秒处理长文档的模型设 600 秒起步。另外要注意超时设置是透传到供应商的设太短真正吃亏的是你自己该给长任务留的余量一定要留够。5.3 key 管理不当带来的鉴权问题用 Proxy 模式就要明确 master_key 和业务方 key 的区别。master_key 是高权限的管理 key可以调用配置管理接口、生成虚拟 key。业务方用的是虚拟 key权限范围受创建时设定的模型和预算约束。我们早期图省事让业务方直接用 master_key 调接口后来发现日志里分不清是谁在调没法做预算拆分还担心 key 泄露影响整个网关。后来统一改成虚拟 key 方案每个团队一个 key出了问题一键撤销再也不用全局换 key 了。如果你发现某个请求 401先确认这个 key 有没有被授权调用对应模型。虚拟 key 的权限是创建时就锁定的不是所有模型都能调。5.4 参数不兼容与 drop_params不同模型对参数的支持程度不同。比如某个模型不支持 top_p 或者 frequency_penalty你按 OpenAI 的习惯传了供应商可能直接报错拒绝。litellm 会在翻译层尽量映射已知参数但总有覆盖不到的角落。最简单的兜底方案是打开 drop_paramslitellm_settings: drop_params: true打开之后litellm 会把目标供应商不支持的参数悄悄丢弃而不是把请求硬传过去收到 400 错误。这个开关在对接开源本地模型时尤其好用因为本地模型的参数支持往往比云端 API 少很多。5.5 流式请求的坑Proxy 模式下流式请求经常遇到的问题不是不通而是看起来不通。业务方用 requests 库直接调网关传了 stream: true然后收到一整块 JSON 而不是分块的 SSE 流就以为出了问题。其实这是正常的。litellm 会把后端供应商的流转换成 OpenAI 风格的 SSE 分块但你必须用支持 SSE 的客户端去解析比如 OpenAI SDK 的 streamTrue 模式或者自己按 SSE 协议解析 data 行。我建议团队统一约定流式请求一律走 OpenAI SDK不要自己拼 HTTP 请求省掉的麻烦比想象中多。还有个细节如果网关后端的模型本身不支持流式litellm 会把整个响应缓冲完之后一次性吐给你这时候即使响应成功客户端看到的也不是增量输出。做实时打字机效果前记得确认后端模型真的支持流式。6. 什么场景适合上 litellm什么场景要慎重6.1 适合上 litellm 的情况如果你的项目符合这几条里的任意两条litellm 基本是值得引入的一是多供应商接入。手上有两个以上模型的 key并且经常要做对比、切换、容灾。二是多团队共享资源。多个项目组要用同一个模型账号需要统一发 key、限制预算、按团队拆分成本。三是对稳定性有要求。单个模型提供方不可用的时候希望业务能自动切换备用模型。四是希望沉淀统一观测。想让所有模型调用都有日志、trace、成本记录而不是每个项目各记各的。我自己的经验是litellm 最适合作为团队基础设施来建设而不是某个项目的临时依赖。一旦它成为全组统一的模型接入层后续新增模型就是改配置、刷新列表的事效率提升是肉眼可见的。6.2 要慎重的情况反过来有几种情况我不建议上来就上 litellm。第一个是只有一个模型、一个人用、调量也不大的小脚本项目。为这种场景起一个网关服务引入配置和运维成本是自找麻烦。你直接用 litellm SDK 或者干脆用官方 SDK 就好。第二个是对响应格式有高度定制需求的场景。虽然 litellm 能做很多自定义但如果你和模型供应商签了私有协议、有大量定制字段可能有部分特性在统一接口下覆盖不到这时候原生的供应商接口反而更直接。第三个是团队没有运维能力却硬上 Proxy 模式。网关是会挂的高可用、升级、日志存储都需要人把网关做成单点反而比不做好。小团队建议先用 SDK 模式等规模上来再演进。7. 写在最后几点使用体会最后分享几个我自己的体会。配置文件的版本管理很重要。litellm 的配置本身就是代码我们把它放进 Git 仓库改模型路由、加新模型都走代码评审流程。这样任何一次变更都有记录出了问题能回溯。这个习惯帮我们避免过一次误把生产流量切到未验证模型的意外。第二个体会是关于过度路由的。不要把路由规则设计得太花哨什么按用户 tag 走不同模型、按消息长度动态选模型听着很聪明实际排障的时候会让你疯掉。我们后来收敛到最简单的策略默认模型故障转移顺序复杂路由只留给特定业务线。简单才是可持续的。最后litellm 迭代很快文档是跟着版本变的。看到新功能不要急着上生产先在测试环境用几天观察日志和成本表现再切流量。我在实际使用中一直保持先读 changelog 再升级的习惯这个习惯让我避开了好几次不兼容更新的雷。你如果正在规划团队的模型接入方案litellm 值得花一个下午跑通全流程这笔时间投入会很值。

Litellm 网关层详解：统一 OpenAI、Claude、Gemini 等模型接口

相关推荐

COMSOL中弯月型结构BIC仿真与斜入射线偏振设置

MFC窗口分割实战：CSplitterWnd静态与动态分割及嵌套布局详解

微信小程序字符串处理全攻略：split/substring/concat/charAt实战

更多资讯

栈与表达式求值：双栈法及中缀转后缀的机试实战

小白做题日记（3）洛谷P5440 洛谷P1378

Scala递归类型：原理、实现与应用场景解析

MDO3024 示波器 + LabVIEW 能测什么？

高校职称评审管理系统设计与实现

云计算课件开发实战：从抽象概念到可运行实验环境

今日更新

小波包能量谱原理与MATLAB实现：从频带分解到故障特征提取

基于LSTM的网易云音乐评论情感分析：数据清洗与模型调优实战

Alpha-Beta剪枝与极大极小值算法：博弈树搜索原理与实战优化

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

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

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

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

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