LiteLLM 实战：用统一网关接入多家大模型与成本管控

当业务同时调用 OpenAI、DeepSeek、通义千问和本地 Ollama 时，每家 SDK 的鉴权、参数和错误格式都不一样，换模型就要改一茬代码。LiteLLM 统一网关用一套 OpenAI 兼容接口把这些大模型收敛成同一个端点，并自带负载均衡、失败降级和按密钥的成本管控。本文手把手带你从零部署一个可用的大模型网关，覆盖接入、路由、成本与上线四个环节。

一、为什么需要大模型统一网关

直接在每个服务里硬编码各家厂商 SDK 会带来三个痛点：第一，密钥散落在多个仓库，轮换和审计都很麻烦；第二，某家模型限流或涨价时，要改代码才能切换，无法热更新；第三，没有统一的用量与花费视图，月底对账才发现预算超了。

大模型统一网关把”调用模型”这件事标准化成一道中间层：上层业务永远只面向 OpenAI 格式，底层具体走哪家、怎么分摊流量、花了多少钱，全部交给网关配置。这也是云原生架构里”关注点分离”思想在 AI 应用上的落地。

二、LiteLLM 是什么

LiteLLM 是一个开源的 Python 库和代理服务（proxy server），它把 100+ 家模型提供商的接口翻译成统一的 OpenAI 格式。你既可以在代码里当 SDK 用，也可以起一个常驻的 proxy，作为团队共享的大模型网关。核心能力包括：

• 统一接口：用 openai SDK 直接调用任意模型，只需改 model 名。
• 路由策略：负载均衡、失败降级（fallback）、超时与重试。
• 成本管控：虚拟密钥（virtual key）、预算上限、按用户/团队统计花费。
• 可观测性：内置 LangFuse、OpenTelemetry 回调，记录每次请求的输入输出与 token 消耗。

三、5 分钟快速开始

最简单的方式是本地起一个代理，把请求转发到指定模型。先安装并直接跑通：

pip install litellm
# 用环境变量注入某家厂商密钥，然后起一个本地代理
export OPENAI_API_KEY="sk-xxxx"

litellm --model openai/gpt-4o --drop_params
# 默认监听 http://0.0.0.0:4000

此时你的业务只要把 base_url 指向 http://localhost:4000，就能用标准 openai 客户端调用。想接本地模型，可参考我们之前写的 Dify + Ollama 本地部署教程，把 Ollama 作为一个 model 加进网关即可。

四、用配置文件接入多家模型

生产环境用 config.yaml 声明所有模型，启动 proxy 时通过 –config 加载。一个最小可用配置如下：

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY

  - model_name: qwen-local
    litellm_params:
      model: ollama/qwen2.5:14b
      api_base: http://127.0.0.1:11434

litellm_settings:
  drop_params: true
  request_timeout: 60

注意 model_name 是你在业务里用的”逻辑名”，litellm_params.model 才是真实厂商路径。把密钥放在环境变量或密钥管理里，不要写死在配置文件。

五、路由策略：负载均衡、降级与超时

5.1 负载均衡

同一个 model_name 下挂多个实例，LiteLLM 会自动做轮询，提升吞吐并分散限流风险。

5.2 失败降级

当主模型 429 或超时时，自动切到备用模型，避免业务直接报错。这和我们在 Text2SQL 实战 里强调的”可靠兜底”思路一致。

router_settings:
  routing_strategy: least-busy        # 也可选 round-robin / fallback-only
  model_group_alias:
    default: gpt-4o

model_group:
  default:
    models: [gpt-4o, deepseek-chat]
    fallbacks: [deepseek-chat]
    timeout: 30

策略	适用场景	效果
round-robin	多实例平摊流量	均匀分摊，提高并发
least-busy	实例负载不均	优先选最空闲的实例
fallback-only	主模型不稳	主模型失败才切备用

六、用 OpenAI 兼容 SDK 调用

业务侧零改造——只要改 base_url 和 api_key，就能调用网关背后的任意模型：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="sk-1234",          # 网关分配的 virtual key
)

resp = client.chat.completions.create(
    model="gpt-4o",             # 也可以用 deepseek-chat / qwen-local
    messages=[{"role": "user", "content": "用一句话解释什么是负载均衡"}],
)
print(resp.choices[0].message.content)

七、成本管控：虚拟密钥与预算

7.1 创建 virtual key

不要让业务直接持有厂商密钥，而是由网关签发虚拟密钥，按团队或按服务隔离，并可以设上限。

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

# 用 master key 签发虚拟密钥（CLI 或 API）
curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"models": ["gpt-4o","deepseek-chat"], "max_budget": 20.0}'

7.2 预算与用量追踪

网关会按 virtual key 累计花费，超预算自动拒绝请求。你可以通过接口或数据库查每天的支出：

# 查看某个密钥的花费
curl "http://localhost:4000/key/info?key=sk-1234" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

# CLI 汇总近 7 天按模型的 token 与花费
litellm --spend logs --duration 7d

方案	多模型	成本视图	维护成本
直接调厂商 SDK	需改代码	分散、难对账	低
LiteLLM 网关	统一接口	按密钥聚合	中
完全自研网关	统一接口	可定制	高

八、用 Docker 部署网关

生产环境建议用容器常驻。下面这份 docker-compose 把配置挂载进去，并依赖一个 Postgres 存用量（可选）：

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    command: ["--config", "/app/config.yaml", "--port", "4000", "--detailed_debug"]
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml
    environment:
      - DATABASE_URL=postgresql://litellm:pass@db:5432/litellm
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=litellm
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=litellm
    volumes:
      - litellm_pg:/var/lib/postgresql/data

volumes:
  litellm_pg:

关于 Compose 编排的更多细节，可参考 Docker Compose 一键编排 一文。

九、用 Nginx 反代暴露到公网

网关只监听内网 4000 端口，对外建议套一层 Nginx 做 HTTPS 与限流。关键配置片段：

location / {
    proxy_pass http://127.0.0.1:4000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 120s;
    # 限制单 IP 调用频率，防止密钥被盗刷
    limit_req zone=apilimit burst=20 nodelay;
}

完整的负载均衡、HTTPS 与缓存写法见 Nginx 反向代理完整配置。

十、用 CI 校验配置

把 config.yaml 纳入仓库，在合并前用 CI 做一次语法和连通性校验，避免错误配置上生产：

# .github/workflows/litellm-check.yml
name: litellm-config-check
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install litellm pyyaml
      - run: python -c "import yaml,litellm; yaml.safe_load(open('config.yaml'))"

这条流水线的搭建套路与 GitHub Actions CI/CD 实战 一致，可复用同一套缓存与校验模板。

十一、常见问题与排错

现象	原因	处理
401 Unauthorized	master/virtual key 不对	检查 Authorization 头与密钥作用域
429 频繁	厂商限流	加 fallback + 限流窗口，错峰重试
参数报错	厂商不支持该参数	开启 drop_params 丢弃未知参数
花费突增	无预算上限	给 virtual key 设 max_budget

十二、落地清单

1. 用 config.yaml 收敛所有模型，密钥走环境变量。
2. 配置 fallback 与超时，保证单点故障可降级。
3. 签发 virtual key 并按团队设预算，禁止业务直连厂商。
4. 用 Docker 常驻，Nginx 做 HTTPS 与限流，CI 校验配置。
5. 接入 LangFuse/OTel 回调，建立用量与花费看板。

十三、流式响应与工具调用如何透传

很多 AI 应用依赖流式输出（打字机效果）和 Function Calling 工具调用，这两者都不会因为走了网关而失效——LiteLLM 对 OpenAI 的 chat/completions 端点做了逐字透传，stream 参数和 tools 参数原样转发给底层模型，再把结果还原成标准格式回传。也就是说，上层业务几乎不用感知网关的存在。

import openai

client = openai.OpenAI(base_url="http://localhost:4000", api_key="sk-1234")

# 流式输出：加 stream=True 即可，网关逐 token 转发
stream = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "用三句话介绍负载均衡"}],
    stream=True,
)
for chunk in stream:
    if delta := chunk.choices[0].delta.content:
        print(delta, end="", flush=True)

# 工具调用：tools 参数同样透传
tools = [{"type": "function", "function": {
    "name": "get_weather",
    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
}}]
resp = client.chat.completions.create(model="gpt-4o", messages=[...], tools=tools)

唯一需要留意的是超时设置：流式请求体量大、耗时长，网关和 Nginx 的 read_timeout 都要调大（上文已设 120s），否则长回答会被中间层截断。若业务还涉及把模型输出写回数据库，可结合 PostgreSQL 慢查询优化 的思路给写入加上批量提交，避免高并发下把网关的回调压垮。

十四、小结

大模型统一网关并不是银弹，但它把”多模型接入、故障降级、成本可视”这三件每家 AI 团队迟早要做的事，沉淀成了一个可复用、可审计的标准组件。当你只有一家模型时可以先不引入；一旦模型数量或调用方超过两个，早一天上 LiteLLM，就少一天在散装 SDK 里救火。

照此落地，你就能得到一个可观测、可控成本、可随时切换模型的大模型网关，把”调模型”从一堆散装 SDK 收拢成一条稳定管线。