上半年我一直在折腾一件事：把公司内部几个 AI 功能模块接入的大模型 API 统一收口。最开始业务代码里直接散落着各家厂商的官方 SDK，看起来都挺省事，但等模型多了、调用方多了之后，光维护这些 SDK 的版本差异和异常分支就让人头大。后来我们花了两天时间，在业务代码前面架了一层 LiteLLM 网关，问题才算真正解决。

LiteLLM 是一个轻量级的大模型网关，也可以理解成一个 LLM Proxy。它最核心的能力，是把不同厂商的大模型 API 统一成一套格式：业务方只需要按同一套接口发请求，鉴权、路由、重试、成本统计这些脏活累活都交给网关处理。这篇文章不打算写成官方文档的翻译，而是从我实际落地的角度出发，把 LiteLLM 解决了什么问题、怎么配置、生产环境要注意什么、踩过哪些坑，一次讲清楚。适合正在做 AI 应用开发、需要接入多个模型服务、或者想在团队内部统一模型调用入口的人参考。

1. 先说清楚：LiteLLM 到底解决什么问题

1.1 大模型接入的碎片化困境

如果你们团队只有一个 AI 功能，只接一家模型厂商，用官方 SDK 是最舒服的。但业务一旦跑起来，你会发现下面这些情况特别常见：

• 第二个功能要接另一家厂商的模型，请求参数风格完全不一样，代码没法复用。
• 某家厂商调整了计费规则，你们想换模型，但业务代码里到处是裸 API 调用，改起来牵一发动全身。
• 某个模型偶尔限流，你希望失败时自动切到备用模型，而不是让用户直接看到报错。
• 团队里每个人本地都保存着不同的密钥，key 的轮换靠手工，一旦泄露要在所有项目里全局改。

我之前接手的一个内部系统，里面同时有三条模型调用代码路径，每条路径的请求格式、超时处理、错误码都不一样。改一个模型，得把所有路径全部同步修改，测试范围也极大。后来我们把所有调用集中到 LiteLLM 网关，代码路径从三条变成一条，之后再做模型切换，只是改动网关配置文件的事情，业务侧完全不用动。

用生活化的比喻来说，不同大模型 API 就像不同品牌的充电协议，如果每种设备都要求专属充电器，你的桌面早就插满线了。LiteLLM 做的事情就是“统一充电口”，把各家 API 的差异在网关层消化掉，业务方只要认准一个接口就行。

1.2 LiteLLM 的定位：一层“统一接口”的网关

具体来说，LiteLLM 做了几件事。

第一，统一请求格式。它对外暴露一套兼容主流 Chat Completions 风格的 HTTP 接口。你在业务侧用这套接口发请求，网关内部再转换成目标厂商要求的格式。这意味着业务代码不需要感知背后是哪家模型服务，换模型只是改一个字段的事。

第二，统一模型路由。同一个逻辑模型名可以映射到多个实际供应商的模型实例，支持按权重分发、故障转移、限流冷却。比如配置一个主模型和一个备用模型，主模型连续失败时自动切到备用模型，用户无感知。

第三，统一基础设施能力。密钥管理、使用额度、成本统计、日志审计、多租户权限，这些都在网关层实现。给每个团队分配一个虚拟密钥，独立统计用量，比散落各处的原始密钥安全得多。

第四，它的接入范围很宽。既支持各家主流云厂商的托管模型 API，也支持本地或自建的模型服务。这意味着同一套网关，既能管线上模型，也能管内部推理服务，不用搞两套系统。

1.3 什么场景适合引入，什么场景别急着上

我也坦白说说边界。不是所有项目都需要 LiteLLM。

适合上网关的情况：

• 团队中多个业务模块都要用大模型，希望把接入方式统一。
• 想在不同模型服务之间动态切换，或者做故障回退。
• 需要对多团队或多成员做密钥隔离和用量统计。
• 对成本敏感，希望能在每个请求维度看到消耗数据。

不适合的情况：

• 只有一个服务、只调一家模型 API，也没有密钥管理和成本统计诉求。这时候多加一层服务就是额外复杂度。
• 对延迟极度敏感，不能接受多一次网络转发的开销。虽然这个开销通常只有几毫秒，但极端场景还是要评估。
• 团队没有基本运维能力，宁可把逻辑放在官方 SDK 里，也不愿意维护一个常驻服务。

我个人的判断标准是：当第二个业务方准备接入模型，而你发现自己又要复制一遍鉴权和请求构造代码时，就该考虑上网关了。越早引入，业务代码里残留的“厂商特色写法”就越少，后面切换模型时流的泪也就越少。

2. 快速上手：安装与最小可用配置

2.1 准备环境与安装

LiteLLM 本质上是一个 Python 项目，最直接的安装方式是用 pip 装带代理功能的完整包：

python -m venv .venv source .venv/bin/activate pip install "litellm[proxy]"

有两点需要注意：建议使用 Python 3.9 以上版本，我一般在 3.10 和 3.11 上跑，比较稳；如果版本太老，新版本依赖可能装不上。另外一定要在虚拟环境里装，这个包依赖比较多，全局安装很容易把系统 Python 环境搞乱。

安装完成后，用litellm --help验证是否成功。如果能正常输出帮助信息，说明环境没问题。我在这一步见过不少人不建虚拟环境，结果后面升级系统依赖时把网关搞崩，这个坑能避就避。生产环境建议直接用官方 Docker 镜像部署，后面会讲。

2.2 写第一份配置文件

LiteLLM 网关的运行核心是配置文件，通常命名为config.yaml。里面写清楚有哪些模型、每个模型对应的真实请求参数、密钥存哪、要不要启用数据库等。

一个最小配置长这样：

model_list: - model_name: "chat-main" litellm_params: model: "openai/gpt-4o" api_key: "${OPENAI_API_KEY}" model_info: mode: chat

解释几个关键字段：

• model_name：你给业务方使用的逻辑模型名，可以随意命名，比如chat-main、recommend-model。业务代码请求时填的就是这个名字。
• litellm_params.model：实际转发到目标厂商时使用的模型标识。格式通常是“厂商前缀/模型名”，前缀决定了走哪家的协议。这里的openai/前缀并不表示密钥归属，它说明网关要用哪套请求格式去适配。
• litellm_params.api_key：目标厂商的密钥。这里用${OPENAI_API_KEY}表示从环境变量读取，不要在配置文件里硬编码密钥。
• model_info.mode：声明这个模型是对话模型、补全模型还是向量模型。某些自动路由和功能开关依赖这个字段。

如果你的模型密钥不止一个，想实现多个 key 轮询，可以写成api_key: ["${KEY_A}", "${KEY_B}"]。网关会按策略选择密钥发送请求，这个在调用量大、厂商频繁限流的场景特别好用。

另外，强烈建议在配置里加统一超时：

litellm_settings: timeout: 30

默认超时时间在某些网络环境下偏短，模型推理一慢就会被误判为失败。设成 30 秒是我在多数场景下测试出来的安全值，如果你们用的是超长上下文模型，可以再放宽到 60 秒。

2.3 启动网关并完成第一次调用

配置文件写好后，启动网关很简单：

export OPENAI_API_KEY="你的密钥" litellm --config config.yaml --port 4000 --num_workers 4

启动后，网关注册在 4000 端口。用 curl 发一个对话请求测试：

curl http://localhost:4000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-any-string" \ -d '{ "model": "chat-main", "messages": [{"role": "user", "content": "你好，请用一句话介绍自己"}] }'

这里的sk-any-string是网关的虚拟密钥。默认情况下，LiteLLM 会生成一个用于内部识别的密钥，你可以在配置里关闭认证或改成自己派发的 key。这个设计很关键：业务方拿到的永远是虚拟 key，原始厂商密钥只在网关内部出现，不会暴露给调用方。

如果一切正常，命令行会输出类似POST /v1/chat/completions 200的日志，并返回业务方需要的结果。到这一步，最小可用链路就通了。

3. 核心能力拆解与配置实战

3.1 统一接口格式与格式转换逻辑

LiteLLM 对外接口模仿了主流 chat completions 接口，这也是它上手快的原因。你几乎不需要给团队额外培训，原来怎么写请求，现在就怎么写，只需要把base_url指向网关地址，把model换成逻辑模型名。

接口格式转换的本质，是网关内部做了一层协议翻译。它对进来的统一格式请求做解析，根据目标模型服务的特点重组成对方需要的请求结构。有的厂商要求消息里带特定角色类型，有的厂商要求参数名不同，有的厂商不支持某些字段，这些差异全部由网关的适配层处理。

这意味着业务侧可以放心地使用统一字段，不用再为每家厂商写 if-else 分支。举个例子：你想在请求里传temperature、max_tokens这类参数，业务侧写一次，网关会根据目标厂商支持的字段透传或转换。如果目标厂商不支持的参数，网关会按配置决定是忽略还是报错。

流式响应也一样。业务侧发一个流式请求，网关同样以流式方式把内容逐步转发回来，中间做了 buffer 和格式处理，对客户端来说体验和直连官方接口几乎没有差别。

3.2 虚拟密钥：把密钥管理收口到网关

密钥管理是我认为 LiteLLM 价值最大的功能之一，团队协作时尤其明显。

没有网关的时候，密钥怎么管？最常见的是写在项目环境变量里，每个开发者本地一份。一旦某个人不小心把.env提交到仓库，或者密钥泄露，你就要去厂商后台重新生成，然后挨个通知所有人更新。这个流程既慢又容易遗漏。

用 LiteLLM 之后，业务方不再接触原始厂商密钥，只使用网关生成的虚拟 key。每个虚拟 key 可以绑定指定模型、设置额度上限、设置过期时间、甚至绑定团队。比如给算法组一个 key，只允许调用chat-main，每月限额 50 美元；给测试环境一个 key，没有额度限制但只能访问测试模型。

后端生成虚拟 key 的调用大致是这样的：

curl -X POST http://localhost:4000/key/generate \ -H "Authorization: Bearer sk-admin-key" \ -H "Content-Type: application/json" \ -d '{ "models": ["chat-main"], "max_budget": 50, "expires": "2025-12-31T23:59:59Z" }'

返回结果里会包含一个新的sk-...密钥，把这个密钥发给对应业务方即可。后续撤销权限、查看用量，都能通过管理接口完成，不用再动厂商后台。

需要注意，管理接口的 Authorization 里用的也是网关自身的管理 key，这个管理 key 要单独保存，别和业务 key 混用。我就见过有人拿管理 key 当业务 key 直接发给前端，结果谁都能生成新 key 的尴尬情况。

3.3 成本统计与用量追踪

接入多个模型之后，另一个绕不开的问题是钱。不同模型的价格单位不统一，有的按 token 计费，有的按字符，有的按调用次数。业务侧手动算成本通常不准确，尤其是流式请求，你很难精确知道每个请求实际消耗了多少 token。

LiteLLM 会在响应里读取或估算 token 用量，并把成本计算放在网关层。你可以按模型、按虚拟 key、按团队维度看消耗。如果配合数据库，历史数据会持久化，能做日、周、月维度的报表。

纯内存模式也能跑，但有一个遗憾：网关重启后历史统计会丢。所以只要你想做成本统计，就尽早把数据库接上。配置方式是在主配置里增加database_url，比如指向 PostgreSQL：

general_settings: database_url: "postgresql://user:password@localhost:5432/litellm"

接入数据库之后，密钥管理、用量记录、审计日志都会持久化。这个能力在生产环境几乎是必须的，否则你无法回答“上周大家的 token 消耗在哪”这种最基本的问题。

还有一个容易忽略的点：详细的 token 用量依赖上游返回 usage 信息。如果某个自建模型服务不返回 usage，LiteLLM 的成本估算就不准确。遇到这种情况，可以在model_info里手动补价格，我会在第 5 部分展开讲。

3.4 负载均衡、重试与熔断：让调用更稳

AI 应用的可用性，很大程度上取决于模型服务是否稳定。但模型服务本身会限流、会超时、会故障。LiteLLM 提供了一组机制来缓解这些问题。

首先是多实例负载均衡。同一个逻辑模型名可以对应多个上游实例，每个实例配不同密钥，配置里重复写同一个model_name即可：

model_list: - model_name: "chat-main" litellm_params: model: "openai/gpt-4o" api_key: "${KEY_A}" model_info: mode: chat - model_name: "chat-main" litellm_params: model: "openai/gpt-4o" api_key: "${KEY_B}" model_info: mode: chat

网关会在多个 key 之间做轮询或按权重分发。某个 key 触发限流时，请求可以转到另一个 key 上，降低被限流拒掉的概率。

其次是对不同模型做故障转移。你想让chat-main背后的模型不可用时，自动降级到备用模型：

litellm_settings: fallbacks: [ {"chat-main": ["chat-backup"]} ]

只要chat-main连续失败，网关会自动把请求路由到chat-backup。用户无感知，业务代码无感知，只有网关日志在记录发生了什么。

第三是熔断和冷却。网关会记录上游连续失败的情况，失败次数超过阈值后，会在一个时间窗口内不再把请求发到那个上游，避免请求继续打向已经出问题的服务。冷却时间结束后再尝试恢复。

需要注意，这些高可用配置不是开了就万事大吉。fallback 可能带来成本变化，备用模型和主模型价格可能差很多；不同模型的返回值格式也可能有细微差异，业务方能否接受降级结果，要提前确认。自动降级是兜底，不是常态通道。

4. 生产环境落地的关键细节

4.1 两种部署方式：网关模式与嵌入式模式

LiteLLM 有两种典型用法。

第一种是网关模式，启动一个独立服务，业务通过 HTTP 调用。这是团队协作的标准形态，所有模型路由逻辑、密钥、统计都集中在服务端。业务代码里只需要一个 base_url 配置项，改网关地址或者做多副本扩展都很方便。

第二种是嵌入式模式，在 Python 代码里直接引入litellm模块，把统一接口当库调用。适合单机脚本、内部数据处理任务，不需要单独部署服务：

import litellm response = litellm.completion( model="openai/gpt-4o", messages=[{"role": "user", "content": "你好"}], api_key="..." )

我的建议是：如果只有一个脚本在用，嵌入式模式完全够用；只要涉及多团队、多服务，就用网关模式。网关模式还有一个隐藏好处：模型可用性和调用日志都沉淀在一个地方，后面做监控、告警、成本分析都非常方便。

4.2 高可用部署与缓存策略

生产环境不建议直接litellm --config ...跑裸进程，而是用 Docker 容器配合进程守护或编排平台部署。

一个基本的 Docker 启动方式示例：

docker run -d --name litellm-proxy \ -p 4000:4000 \ -v /opt/litellm/config.yaml:/app/config.yaml \ -e DATABASE_URL="postgresql://..." \ ghcr.io/litellm/litellm:main \ --config /app/config.yaml

有几个生产细节值得注意：

• 镜像版本要固定，不要用 latest 漂移。上游发布节奏不慢，固定版本才能让变更可控。
• 配置目录用 volume 挂载，这样改配置不用重建容器。
• 数据库地址通过环境变量注入，不要写死在配置里。
• 建议至少启动两个副本，由上层负载均衡器分发流量，避免单点。
• 网关自身要暴露健康检查接口，配置好探针，方便编排平台自动拉起异常实例。

缓存方面，LiteLLM 内置了可选的缓存能力。可以在litellm_settings里开启：

litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379 ttl: 600

缓存适合重复性极高的请求，比如一模一样的历史消息反复查询分析结果。它能显著降低上游压力和账单金额。但开缓存前要想清楚：涉及实时数据或用户个性化内容的场景不适合缓存，不同用户的请求结果不能混用。我通常只在一些固定的分析类请求上开，效果很明显，其他场景宁可让它每次都走真实调用。

4.3 权限、审计与团队协作

生产环境里，谁有权限用哪些模型、谁改过配置、谁生成了新密钥，这些都应该被记录。LiteLLM 在开启数据库之后，能记录下不少关键操作的审计信息。

团队协同时，我建议做几件事：

• 为每个业务模块创建独立的虚拟 key，不要所有人共用一个 key。
• 给每个 key 设置模型白名单和额度上限，宁可后面调整，也不要一开始放开所有权限。
• 管理接口的 Authorization 密钥单独保存，不要把管理 key 混在业务 key 里。
• 定期审视密钥列表，把长期不用的撤销掉。
• 模型配置变更后，先在一个测试模型名上验证，再逐步切换流量。

这些听起来像常规安全建议，但实际团队里能做到的真心不多。尤其在公司快速发展期，大家图方便共用 key，等到月度账单异常或者密钥泄露时才后悔。提前花半小时把权限分配好，后面省下的是整个运维月的精力。

5. 常见问题排查与避坑实录

这一块我整理了自己和身边团队实际遇到过的几个典型问题，按问题现象、排查思路、解决方案来写。

5.1 请求返回 404、模型不存在

最常见的报错之一是网关返回model not found，但配置文件里明明写了这个模型。这类问题通常有三个原因。

一是请求 body 里的 model 名称和配置里的model_name不匹配。注意逻辑模型名的大小写、空格、前后缀，差一个字符都匹配不上。

二是配置修改后没有输出。LiteLLM 部分配置修改不用重启，但模型列表的变更在很多版本里还是要求重启或触发 reload。遇到这种情况先重启验证一次。

三是没有启用对应的模型类别。比如你配置了 chat 类模型，但请求的是 embeddings 或 completions 接口，同样会找不到模型。

排查时先看网关日志，日志里一般会明确写出当前模型列表和匹配失败的请求模型名，对照一眼就能确认。

5.2 上游请求超时或限流

如果发现请求偶尔失败，错误信息里有 timeout 或 rate limit 字样，先别怀疑 LiteLLM，而是要区分是哪一层引起的。

先看网关日志里的上游耗时统计。如果上游耗时本身就很长，说明是模型服务响应慢。此时调大统一超时，或者对长输入场景单独设置更大的超时值。如果日志显示上游返回 429，说明触发了限流，这时考虑加 key 轮询、开启 fallback、或降低单 key 的并发。

我踩过的一个坑：初期把超时设成 10 秒，结果某些需要长上下文处理的请求持续超时，用户端看到的是“服务不可用”，真实原因却是网关把它误杀了。后来把超时调到 30 秒，配合重试机制之后，这类误报立刻消失。

5.3 数据库配置后一直报连接错误

有一次，团队加了数据库配置后，网关启动时一直报连接失败。排查发现配置文件里database_url写的是内网地址，但网关容器运行的网络环境访问不了那个内网段。这不是 LiteLLM 的问题，而是部署网络规划的问题。

建议在生产中：

• 数据库地址用环境变量注入，不要写进配置。
• 确认网络策略放通了网关到数据库的访问。
• 第一次接入数据库时，先在本机用同一个连接串测试连通性，再交给容器使用。

这些报错大多卡在连通性这一环。先确认网络，再怀疑代码，能省很多时间。

5.4 成本数据不准或丢失

成本统计不准确，通常有两个原因：模型没有在配置里登记价格字段，或者模型响应里没有返回 usage 信息。LiteLLM 对常见模型有内置价格表，但对自定义模型、自建服务往往估算不准。

对策是在配置里给自定义模型补上价格：

model_list: - model_name: "internal-llm" litellm_params: model: "custom_model_id" model_info: mode: chat input_cost_per_token: 0.000001 output_cost_per_token: 0.000002

这样网关计算成本时会使用你定义的价格，报表才会接近真实。另外，如果用的是网关模式但没有启用数据库，历史统计自然也不会持久化，这不是 bug，是设计如此。

5.5 快速定位速查表

为了方便排障，我把上面几个常用场景整理成一张表，遇到问题可以先对号入座：

6. 写在最后：我的一点实际体会

真的把 LiteLLM 用顺之后，我有一个很深的感受：网关这类基础设施，真正降低的不是第一次接入的编码量，而是长期维护时的“心智负担”。如果团队里每个人都各自维护一套模型调用代码，每次模型升级、厂商限流、密钥轮换，你都要在多个地方同时操作。收口到网关之后，这些操作都集中到一个地方，变更的影响面也被限制住了。

我也建议大家不要一上来就把所有功能全部打开。第一次接入，先只用统一接口转发，跑通一条链路；第二周再加虚拟密钥和额度管理；等稳定之后，再做 fallback、负载均衡和缓存。功能加得越慢，你越能明确知道每一个开关到底解决了什么问题，出了问题也更容易定位。

最后分享一个小技巧：给网关注册一个专门的测试模型，每次发布配置后都跑一遍验证命令，确认模型列表、密钥连通性、数据库连接都正常。几分钟的验证，能避免很多“配置改了但没生效”“密钥过期导致线上报错”的低级事故。LiteLLM 的灵活性很强，但灵活性也意味着配置容易失控，保持简单，保持可验证，它就能成为团队里那个最省心的角色。