3980 字
20 分钟
AI 工具应用:LiteLLM 把模型包装成统一 API
2026-11-15

先说问题:模型一多,接口先乱#

刚开始用 AI 接口时,事情很简单:一个供应商、一个 API Key、一段代码。乱象是从第二个模型开始的。OpenAI 一套请求格式,Anthropic 一套,本地 Ollama 又一套;每接一家,代码里就多一个分支、多一处密钥、多一种报错格式。等到想统计「这个月到底在模型上花了多少钱」、想给某个脚本单独限额、想在主供应商挂掉时自动切备用时,直连模式就彻底管不住了——这些能力散落在每个客户端里,谁也拼不出一张全图。

这一篇的主线,就是在所有客户端和所有模型之间加一层网关:LiteLLM Proxy。它把云端各家的 API 和本地 Ollama 模型全部包装成同一个 OpenAI 兼容接口,对外只暴露一个地址、一套密钥体系、一份日志。客户端从此只认网关,换供应商、加模型、调限额都变成改网关配置,而不是改一圈代码。

项目地址:https://github.com/BerriAI/litellm

LiteLLM 的两种形态:SDK 与 Proxy#

LiteLLM 有两种用法,先分清再选:

形态是什么适合谁
Python SDK一个 Python 库,在代码里 from litellm import completion,用统一参数调用各家模型单个 Python 项目内部想抹平供应商差异,不需要独立服务
Proxy Server独立运行的网关服务,对外提供 OpenAI 兼容的 HTTP 接口,自带密钥、限额、日志多个工具、多个设备、多个人共用一套模型资源,本篇主讲这种

两者的关系是:Proxy 内部用的就是 SDK 的转换能力,只是外面多套了一层服务化的壳——鉴权、虚拟密钥、消费统计、Admin 管理界面都在这一层。本篇默认你已经有至少两个模型来源(比如一家云端 API 加一个本地 Ollama,Ollama 的部署见 Ollama 部署本地大模型),目标是把它们收成一个入口。

Docker 部署 Proxy#

官方提供现成镜像,一条命令就能起。先准备一个目录放配置和环境变量:

Terminal window
mkdir -p ~/litellm && cd ~/litellm
cat > .env << 'EOF'
LITELLM_MASTER_KEY=sk-master-换成你自己的随机长串
OPENAI_API_KEY=sk-你的OpenAI密钥
ANTHROPIC_API_KEY=sk-ant-你的Anthropic密钥
EOF

用 Docker Compose 把它固化下来,后面改配置、看日志都方便:

services:
litellm:
image: ghcr.io/berriai/litellm:main-latest
container_name: litellm
restart: unless-stopped
ports:
- "4000:4000"
env_file:
- .env
volumes:
- ./config.yaml:/app/config.yaml
command:
- "--config"
- "/app/config.yaml"
- "--port"
- "4000"
extra_hosts:
- "host.docker.internal:host-gateway"

这里有三个细节值得注意:

  • LITELLM_MASTER_KEY 是网关的主密钥,相当于管理员密码,后面生成虚拟密钥、调管理接口都靠它,它一旦泄露,等于所有上游供应商的密钥一起泄露,务必用随机长串并保管好。
  • 上游各家的真实密钥只写在 .env 里,配置文件通过环境变量引用(下一节会看到),这样 config.yaml 可以放心进 Git 仓库、发给别人看,密钥不跟着走。
  • extra_hosts 那行是给容器访问宿主机上的 Ollama 用的,本地模型走 host.docker.internal 这个地址,Linux 上没有这行会连不上。

config.yaml 先写个最小版(下一节逐段拆),然后启动:

Terminal window
docker compose up -d
docker compose logs -f litellm # 看到 Uvicorn running on http://0.0.0.0:4000 即起来了
curl http://localhost:4000/health/liveliness

返回 I'm alive! 说明服务活着。浏览器打开 http://localhost:4000/ui,用主密钥登录,就是 Admin 管理界面,模型列表、密钥、消费记录都能在这里看。

WARNING

4000 端口只建议监听在本机或内网。LiteLLM 的接口虽然有密钥鉴权,但 绝对不要把没套 HTTPS、没加访问控制的网关端口直接暴露到公网——它背后连着的全是你付费的密钥,被人扫到就是替别人买单。

config.yaml 逐段详解:统一命名与别名映射#

这是整篇的核心。LiteLLM 的配置哲学只有一句话:客户端看到的模型名,和上游真实的模型名,彻底解耦。客户端只认你在 model_name 里起的别名,至于这个别名背后是 OpenAI 还是本地 Ollama、以后要换成谁,都在网关这一层悄悄改。

一份把云端与本地模型统一收编的完整配置:

model_list:
# —— 云端 API ——
- model_name: fast-chat
litellm_params:
model: openai/gpt-4o-mini
api_key: os.environ/OPENAI_API_KEY
- model_name: strong-chat
litellm_params:
model: anthropic/claude-sonnet-4-5
api_key: os.environ/ANTHROPIC_API_KEY
# —— 本地 Ollama(选模型的思路见系列前篇)——
- model_name: local-chat
litellm_params:
model: ollama_chat/qwen2.5:14b
api_base: http://host.docker.internal:11434
# —— 同名多后端:两个条目共用一个别名,组成负载均衡池 ——
- model_name: smart
litellm_params:
model: openai/gpt-4o
api_key: os.environ/OPENAI_API_KEY
- model_name: smart
litellm_params:
model: anthropic/claude-sonnet-4-5
api_key: os.environ/ANTHROPIC_API_KEY
router_settings:
routing_strategy: simple-shuffle # 池内随机分发;也可 least-busy、latency-based
num_retries: 2 # 单个后端失败时自动重试
timeout: 120 # 单次请求超时(秒)
litellm_settings:
drop_params: true # 自动丢弃目标模型不支持的参数,减少 400 报错
fallbacks:
- smart: ["local-chat"] # smart 池整体不可用时,自动落到本地模型
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY

逐段看关键点:

  • model_name:对外别名,客户端请求里填的就是它。起名建议按用途而不是按供应商,比如 fast-chat、strong-chat、local-chat——哪天把 strong-chat 背后的供应商换掉,客户端一行都不用动。
  • litellm_params.model:上游真实模型,格式是 供应商/模型名。云端写 openai/...、anthropic/...;本地 Ollama 写 ollama_chat/模型名 并配 api_base 指向 Ollama 地址(用 ollama_chat 而不是 ollama,是因为前者走 Ollama 的对话接口、工具调用等行为更贴近 OpenAI 格式)。
  • api_key: os.environ/XXX:这个前缀是固定写法,表示从环境变量读,避免把密钥明文写进配置文件。
  • 同名条目:model_name 相同的多个条目自动组成一个池,请求按 routing_strategy 分发,某个后端报错还会按 num_retries 换一个重试——这是下一节负载均衡与故障转移的基础,这里先把池建好。
  • fallbacks:池级别的兜底。上面这条的意思是:smart 池里的后端全军覆没时,请求自动改走 local-chat。本地模型能力弱一截,但胜在不会欠费、不会被限流,做降级兜底正合适。本地模型怎么选才够用,见 开源模型怎么选。

改完配置执行 docker compose restart litellm 生效,再调一下模型列表接口确认别名都注册上了:

Terminal window
curl http://localhost:4000/v1/models \
-H "Authorization: Bearer sk-master-换成你自己的随机长串"

返回里能看到 fast-chat、strong-chat、local-chat、smart 四个别名,就可以进入下一步了。

客户端接入:只改两个地方#

网关建好之后,任何支持 OpenAI 格式的客户端都只需要改两个参数:base_url 指向网关,api_key 换成网关的密钥。先用 curl 验一发:

Terminal window
curl http://localhost:4000/v1/chat/completions \
-H "Authorization: Bearer sk-master-换成你自己的随机长串" \
-H "Content-Type: application/json" \
-d '{
"model": "local-chat",
"messages": [{"role": "user", "content": "用一句话介绍你自己"}]
}'

注意这里请求的是本地模型,但走的是标准 OpenAI 格式——把 model 换成 strong-chat 再发一次,同一段请求代码就调到了 Anthropic 的模型,这就是统一接口的实际体感。Python 里用官方 SDK 也一样,只是把客户端初始化改两行:

from openai import OpenAI
client = OpenAI(
base_url="http://localhost:4000/v1", # 原来是各家供应商的地址
api_key="sk-给这个项目单独生成的虚拟密钥", # 原来是供应商的真实密钥
)
resp = client.chat.completions.create(
model="smart", # 填网关别名,不填供应商模型名
messages=[{"role": "user", "content": "写一个快速排序"}],
)
print(resp.choices[0].message.content)

其余代码——消息结构、流式处理、错误处理——全部不用动。这意味着存量项目迁移到网关的成本约等于改一次配置;也意味着以后再换供应商、加模型,改的都是网关配置,而不是散落在各个项目里的代码。

进阶能力:密钥、限额、均衡、日志、缓存#

虚拟密钥与预算限额#

主密钥只该握在自己手里。给每个项目、每个人发的应该是虚拟密钥(Virtual Key):能限定可用模型、能设预算上限、能单独吊销。用主密钥调管理接口生成:

Terminal window
curl -X POST http://localhost:4000/key/generate \
-H "Authorization: Bearer sk-master-换成你自己的随机长串" \
-H "Content-Type: application/json" \
-d '{
"key_alias": "my-script",
"models": ["fast-chat", "local-chat"],
"max_budget": 5,
"duration": "30d"
}'

返回的 key 就是给那个脚本用的密钥:它只能调 fast-chat 和 local-chat,30 天内最多花 5 美元,超了自动拒绝,想停用随时在 Admin 界面或用 /key/delete 吊销,而上游的真实密钥它从头到尾没见过。把主密钥直接写进脚本或客户端分发出去,是使用网关最常见的翻车姿势——主密钥能生成任意新密钥、能看全部消费记录,只能留在网关管理员手里。

负载均衡与故障转移#

上一节配置里已经埋了两层:同名别名组成池做负载均衡,fallbacks 做跨池故障转移。实际效果是:同一家供应商有多个账号 Key 时,写成多个同名条目即可把请求摊开,撞限流的概率大幅下降;某个后端连续失败,路由会自动避开并重试其他后端,客户端只会感觉「偶尔慢一点」,不会直接吃报错。再进一步,还可以给池内条目加 weight 按比例分发,或把 routing_strategy 换成 latency-based-routing 让请求优先走响应最快的后端。

请求日志与成本统计#

网关的另一大价值是账算得清。每次请求经过网关,都会记录调用方密钥、模型、Token 数和折算成本。想让这些记录在重启后不丢失,需要给网关接一个 PostgreSQL 存消费数据,在 Compose 里加两行环境变量即可:

environment:
- DATABASE_URL=postgresql://user:password@db:5432/litellm
- STORE_MODEL_IN_DB=True

(数据库服务本身的部署不是本篇重点,任意一个现成的 PostgreSQL 实例都可以。)接好之后,Admin 界面的 Usage 页能按密钥、按模型看消费曲线,也可以用接口直接查某个虚拟密钥的花费:

Terminal window
curl "http://localhost:4000/key/info?key=sk-某个虚拟密钥" \
-H "Authorization: Bearer sk-master-换成你自己的随机长串"

返回里的 spend 就是这个密钥累计花掉的钱。对个人玩家来说,这解决了一个很实际的问题:脚本在后台默默跑偏时,不用等供应商账单出来才发现。

缓存#

对重复提问较多的场景(比如同一批文档反复问答),可以开启响应缓存,命中时直接返回旧结果,不再向上游付费:

litellm_settings:
cache: true
cache_params:
type: local # 个人使用够了;多实例部署可换成 redis

缓存适合问答结果稳定的场景;需要每次答案都有随机性的创作类调用,记得在请求里带上参数单独关掉,别让缓存把多样性吃掉。

顺带一提:和 CLIProxyAPI 分工不同#

本系列另一篇讲的 CLIProxyAPI 解决的是另一头的问题:它把命令行订阅账号包装成 API。两者不冲突,反而能串联——CLIProxyAPI 对外同样是 OpenAI 兼容接口,把它作为一个上游条目写进 LiteLLM 的 model_list(api_base 指向它的地址),就能让订阅账号来的模型也进入统一的密钥、限额和日志体系。

与直连的取舍:什么时候值得多这一层#

维度直连供应商经过 LiteLLM 网关
接入成本每家一套 SDK 参数与密钥管理客户端只认一个地址、一套格式
换供应商改代码、改配置、重新发版改 config.yaml 里一行
密钥安全真实密钥散落在每个客户端真实密钥只存网关,客户端用虚拟密钥
限额与账单各家后台分别看,口径不一一处设预算、一处看总账
故障转移自己写重试与切换逻辑配置即得
代价——多一跳网络延迟(通常毫秒级)、网关本身成为单点

判断标准很朴素:只有一个项目、一家供应商,网关纯属多余,直连最省事;一旦出现「两家以上供应商」「本地模型加云端混用」「多个工具共用密钥」「想给某个脚本封顶预算」中的任何一条,网关省下的管理成本就远超它多出的那一跳。单点问题对个人部署不算大事——网关挂了客户端会立刻报错,重启容器即可恢复;真到了在意可用性的规模,再考虑多实例加负载均衡,那已经是另一个话题了。

常见问题与排障#

请求返回 401 Authentication Error。 先分清用的是哪把钥匙:调业务接口可以用虚拟密钥,调 /key/generate 这类管理接口必须用主密钥。还要检查主密钥的配置方式——用 general_settings.master_key 引用环境变量时,写法必须是 os.environ/LITELLM_MASTER_KEY,漏了前缀会被当成字面字符串。

返回 400,提示模型不存在或 model not found。 客户端请求里的 model 必须填 config.yaml 里的别名(model_name),不是上游的真实模型名。先调 /v1/models 对一眼网关实际注册了哪些别名;如果列表里根本没有,多半是配置文件没挂载对或改完没重启,docker compose logs 里会有 YAML 解析报错。

本地模型条目连不上 Ollama。 容器里访问宿主机不能用 localhost——那指的是容器自己。确认 Compose 里有 extra_hosts: ["host.docker.internal:host-gateway"],且 api_base 写的是 http://host.docker.internal:11434;再在宿主机上 curl http://localhost:11434/api/tags 确认 Ollama 本身在跑。如果 Ollama 是装在另一台机器上,直接把 api_base 换成那台机器的内网地址即可。

某些参数被上游拒绝,报 400 Unsupported parameter。 不同供应商支持的参数不一样,比如把 OpenAI 的参数原样发给别的模型就会中招。在 litellm_settings 里打开 drop_params: true,网关会自动丢弃目标模型不支持的参数,绝大多数这类报错会消失。

重启容器后,虚拟密钥和消费记录全没了。 这是没接数据库的必然结果:默认状态只存内存。按上一节给网关配上 DATABASE_URL 指向 PostgreSQL,密钥与消费记录才会持久化;已经在裸跑的,先把现有虚拟密钥清单导出备份再迁移。

流式输出中途断开。 多半是超时:本地大模型首字慢、云端长回答久,都会撞上默认超时。把 router_settings.timeout 调大(比如 300),同时检查客户端自己的读取超时设置,两边都要放宽,只改一边没用。

Admin 界面打不开或登录失败。 /ui 登录用的就是主密钥本身(用户名任意或留空视版本而定)。如果改过主密钥但没重启容器,界面仍认旧值;另外注意别把 LITELLM_MASTER_KEY 和给数据库用的其他密码搞混,它们互不相干。

小结#

LiteLLM Proxy 的定位,是给所有模型调用立一个总闸口:上游无论是云端 API 还是本地 Ollama,在 config.yaml 里统一命名、统一收编;下游无论是什么工具,只认一个地址、一把虚拟密钥。密钥不再散落、预算有了封顶、账单有了一处总账、供应商故障有了自动转移——这些都不是某一家供应商接口能给你的。

落地顺序建议照着本篇走:先 Docker 起网关、把在用的两三个模型写进 model_list 跑通,再给每个项目换发虚拟密钥,最后按需要打开日志持久化和缓存。跑顺之后你会发现,之后每次想试新模型,动作都只剩下「在配置里加四行」。

AI 工具应用:LiteLLM 把模型包装成统一 API
https://www.anexns.cloudns.org/posts/ai-litellm-gateway/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0