先说问题:模型一多,接口先乱
刚开始用 AI 接口时,事情很简单:一个供应商、一个 API Key、一段代码。乱象是从第二个模型开始的。OpenAI 一套请求格式,Anthropic 一套,本地 Ollama 又一套;每接一家,代码里就多一个分支、多一处密钥、多一种报错格式。等到想统计「这个月到底在模型上花了多少钱」、想给某个脚本单独限额、想在主供应商挂掉时自动切备用时,直连模式就彻底管不住了——这些能力散落在每个客户端里,谁也拼不出一张全图。
这一篇的主线,就是在所有客户端和所有模型之间加一层网关:LiteLLM Proxy。它把云端各家的 API 和本地 Ollama 模型全部包装成同一个 OpenAI 兼容接口,对外只暴露一个地址、一套密钥体系、一份日志。客户端从此只认网关,换供应商、加模型、调限额都变成改网关配置,而不是改一圈代码。
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
官方提供现成镜像,一条命令就能起。先准备一个目录放配置和环境变量:
mkdir -p ~/litellm && cd ~/litellmcat > .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 先写个最小版(下一节逐段拆),然后启动:
docker compose up -ddocker 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 管理界面,模型列表、密钥、消费记录都能在这里看。
WARNING4000 端口只建议监听在本机或内网。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 生效,再调一下模型列表接口确认别名都注册上了:
curl http://localhost:4000/v1/models \ -H "Authorization: Bearer sk-master-换成你自己的随机长串"返回里能看到 fast-chat、strong-chat、local-chat、smart 四个别名,就可以进入下一步了。
客户端接入:只改两个地方
网关建好之后,任何支持 OpenAI 格式的客户端都只需要改两个参数:base_url 指向网关,api_key 换成网关的密钥。先用 curl 验一发:
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):能限定可用模型、能设预算上限、能单独吊销。用主密钥调管理接口生成:
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 页能按密钥、按模型看消费曲线,也可以用接口直接查某个虚拟密钥的花费:
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 跑通,再给每个项目换发虚拟密钥,最后按需要打开日志持久化和缓存。跑顺之后你会发现,之后每次想试新模型,动作都只剩下「在配置里加四行」。