第10章 LiteLLM Proxy Server

为什么需要一个网关

想象公司里 12 个业务部门都在用 LLM:

每个组自己管 API Key——年底 10 个 Key 过期、泄露的有 3 个。
A 组用 OpenAI、B 组用 Claude、C 组用 Gemini——三套 SDK、三份价格表、三个报错格式。
财务问"上个月 AI 花了多少钱",3 张 invoice 拼不清楚。
法务要求"所有 prompt 留存 90 天可审计",12 个组各写各的日志。
一个组的死循环脚本把整公司 Azure 配额吃光。

把 LiteLLM 作为中间 Proxy部署成公司级服务:

各业务 → OpenAI SDK 请求 → LiteLLM Proxy → 真实 provider(OpenAI/Azure/Claude/…)
                ↑                    ↓
           用 Virtual Key          ● 统一限额/预算
                                   ● 统一日志/审计
                                   ● 统一路由/缓存
                                   ● 统一模型名

业务代码感知不到变化。他们继续 from openai import OpenAI; client = OpenAI(base_url="http://llm.company.internal", api_key="sk-virtual-xxx")——接口完全兼容,换的只是 base_url 和 key。这是 LiteLLM Proxy 最大价值。

3 分钟跑起来

# 1. 安装 (带 proxy extra)
pip install "litellm[proxy]"

# 2. 最小 config.yaml
cat > config.yaml <<'EOF'
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY
EOF

# 3. 启动
litellm --config config.yaml --port 4000

现在你有了一个 OpenAI 兼容的 API:

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-1234" \
  -d '{
    "model": "claude-sonnet",
    "messages": [{"role":"user","content":"你好"}]
  }'

任何 OpenAI SDK 都能连:

from openai import OpenAI
client = OpenAI(base_url="http://localhost:4000/v1", api_key="sk-1234")
client.chat.completions.create(model="claude-sonnet", messages=[{"role":"user","content":"hi"}])

到这里:业务零依赖、零改动,背后 Anthropic、OpenAI、Gemini、DeepSeek 随便换。这是"LLM 运维解耦"的关键一步。

config.yaml 的 4 大板块

# ============ 1. model_list: 所有可用模型/部署 ============
model_list:
  - model_name: gpt-4o              # 客户端看到的名字
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
      rpm: 500
      tpm: 1000000
    model_info:
      description: "GA GPT-4o for production chat"

# ============ 2. router_settings: 路由策略 ============
router_settings:
  routing_strategy: usage-based-routing-v2
  num_retries: 3
  timeout: 30
  fallbacks:
    - gpt-4o: [claude-sonnet, gemini-2.5-flash]
  cooldown_time: 60
  redis_host: os.environ/REDIS_HOST
  redis_password: os.environ/REDIS_PASSWORD

# ============ 3. litellm_settings: 全局行为 ============
litellm_settings:
  drop_params: true
  set_verbose: false
  cache: true
  cache_params:
    type: redis
    host: os.environ/REDIS_HOST
    ttl: 1800
  success_callback: ["langfuse"]    # 日志/观测
  failure_callback: ["langfuse"]

# ============ 4. general_settings: 网关本身 ============
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY   # sk-1234 就是这里
  database_url: os.environ/DATABASE_URL         # Postgres, 存 Virtual Keys/spend
  ui_access_mode: admin_only
  allow_user_auth: true
  alerting: ["slack"]
  alerting_threshold: 300                    # 慢于 5 分钟告警

四块的分工说一次就好记:第 1 块"能调什么模型",第 2 块"怎么路由",第 3 块"LiteLLM 内部行为",第 4 块"Proxy 这个服务本身的运维配置"。

Virtual Keys:业务的第一入口

Master Key(LITELLM_MASTER_KEY)只给管理员和 Admin UI,绝不能给业务。业务拿到的是Virtual Key,通过 Proxy 自身的 API 生成:

# 管理员: 给 support-team 生成一把 key
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-MASTER-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["gpt-4o", "claude-sonnet"],
    "max_budget": 500,
    "budget_duration": "30d",
    "rpm_limit": 100,
    "tpm_limit": 200000,
    "duration": "180d",
    "metadata": {"team": "support", "env": "prod"}
  }'

# 返回:
# {"key": "sk-LxYtd0Mpp...", "expires": "2026-11-07", ...}

这把 key 的能力被全方位约束:

字段	作用	超额行为
`models`	白名单模型,别的不给调	返回 401 / model not allowed
`max_budget`	上限美元	返回 429
`budget_duration`	预算周期:1d / 7d / 30d	周期结束自动重置
`rpm_limit / tpm_limit`	每分钟请求/token	返回 429
`duration`	key 本身的 TTL	过期整体失效
`metadata`	business tag	进日志/报表

业务拿到 key 后,前面提过的"OpenAI SDK + base_url"就跑起来了。跑失控也超不过 $500——硬限,不是代码自觉。

三级权限:Team → User → Key

更大规模的公司,要做部门/子团队管理。LiteLLM 提供三层:

Organization(公司)
  └─ Team (部门, 如 "support-team")          ← 预算聚合 / 模型白名单
      └─ User (员工, alice@company.com)      ← 每人限额
          └─ Virtual Key (alice 的 3 个项目用的) ← 真正调用

# 建 Team
curl -X POST http://localhost:4000/team/new \
  -H "Authorization: Bearer sk-MASTER-KEY" \
  -d '{
    "team_alias": "support-team",
    "max_budget": 2000,
    "models": ["gpt-4o", "claude-sonnet"]
  }'

# 把 User 加进 Team
curl -X POST http://localhost:4000/team/member_add \
  -H "Authorization: Bearer sk-MASTER-KEY" \
  -d '{
    "team_id": "t-abc123",
    "member": {"user_id": "alice@company.com", "role": "user"}
  }'

# 给 User 在这个 team 里生成 Key
curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-MASTER-KEY" \
  -d '{
    "team_id": "t-abc123",
    "user_id": "alice@company.com",
    "max_budget": 200,
    "duration": "90d"
  }'

预算关系:key 限额 ≤ user 限额 ≤ team 限额 ≤ org 限额,任何一层超了都拒绝。计算写在 Postgres 里,多实例共享一致。

Admin UI:可视化管理

启动 Proxy 后访问 http://localhost:4000/ui(需要 Postgres + master key),默认给你:

Models 页:可视化加/删/改模型,改完立刻生效,不用重启。
Keys 页:生成、revoke、查谁花了多少。
Teams / Users 页:组织架构管理。
Usage 页:曲线图——花费、调用量、error rate,按 key/model/team 筛选。
Logs 页:每次调用的 prompt/response 可审计(敏感数据脱敏)。

小公司就可以把 Admin UI 直接当做 AI 网关的控制面。改模型、改限额、拉报表,都不需要写代码。配合 SSO 接 Okta/Google 就完成了权限治理。

Docker / Compose 部署

# docker-compose.yml
version: "3.9"
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    ports: ["4000:4000"]
    volumes:
      - ./config.yaml:/app/config.yaml
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      DATABASE_URL: postgresql://litellm:pw@postgres:5432/litellm
      REDIS_HOST: redis
      LITELLM_MASTER_KEY: ${MASTER_KEY}
    depends_on: [postgres, redis]

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: pw
      POSTGRES_DB: litellm
    volumes: [pgdata:/var/lib/postgresql/data]

  redis:
    image: redis:7-alpine

volumes:
  pgdata:

docker compose up -d

四件套齐活:Proxy + Postgres(存 Keys/spend) + Redis(缓存/限流状态) + Admin UI。生产最小配置就这样。

Kubernetes / Helm 部署

有集群的话用官方 Helm:

# 加 repo
helm repo add litellm https://berriai.github.io/litellm/
helm repo update

# values.yaml 核心配置
cat > values.yaml <<'EOF'
image:
  repository: ghcr.io/berriai/litellm
  tag: main-stable
replicaCount: 3
config: |
  model_list: [...]
  general_settings:
    master_key: os.environ/LITELLM_MASTER_KEY
    database_url: os.environ/DATABASE_URL
env:
  OPENAI_API_KEY:
    valueFrom: {secretKeyRef: {name: llm-keys, key: openai}}
  ANTHROPIC_API_KEY:
    valueFrom: {secretKeyRef: {name: llm-keys, key: anthropic}}
  LITELLM_MASTER_KEY:
    valueFrom: {secretKeyRef: {name: llm-keys, key: master}}
  DATABASE_URL:
    valueFrom: {secretKeyRef: {name: llm-keys, key: database-url}}
  REDIS_HOST:
    value: redis-master.default.svc
postgres:
  enabled: true
redis:
  enabled: true
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  targetCPUUtilizationPercentage: 70
EOF

helm install llm-gateway litellm/litellm -f values.yaml

要点:

replicaCount ≥ 3,避免单 pod 挂了整个公司的 LLM 断线。
HPA 基于 CPU + RPS。单 pod 上千 RPS 没问题,慢请求多就要横向扩。
Postgres 用托管服务(RDS / Cloud SQL),不要跟 Proxy 混部,断电故障域分开。
Redis 必须高可用(Redis Sentinel / Cluster),限流/缓存/Router 状态都靠它。

日志与可审计

Proxy 默认把每次请求的核心字段写 Postgres:

SELECT model, user_id, spend, total_tokens, startTime, api_key
FROM   "LiteLLM_SpendLogs"
WHERE  startTime >= NOW() - INTERVAL '1 day'
ORDER BY spend DESC
LIMIT  20;

想要 prompt / completion 全文留存(很多公司合规要求),在 config 里加:

litellm_settings:
  success_callback: ["s3", "langfuse"]
  s3_callback_params:
    s3_bucket_name: my-company-llm-audit
    s3_region_name: us-east-1
    s3_aws_access_key_id: os.environ/AWS_KEY
    s3_aws_secret_access_key: os.environ/AWS_SECRET

效果:每次请求自动写一份 JSON 到 S3(含 prompt/response/user/key/cost),对业务透明。法务拿 bucket 读权限就能完成审计。

客户端迁移

公司上 Proxy 前,各组用法杂七杂八。上 Proxy 后只需改两行:

# 改前 (各组不同)
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
genai.configure(api_key=os.getenv("GOOGLE_API_KEY"))

# 改后 (全员统一)
client = OpenAI(
    base_url="http://llm.company.internal/v1",
    api_key=os.getenv("LLM_VIRTUAL_KEY"),    # sk-Lx...
)

# 模型名统一走别名
client.chat.completions.create(model="gpt-4o", messages=msgs)         # 可能实际跑的是 Azure
client.chat.completions.create(model="claude-sonnet", messages=msgs) # 实际 Anthropic

"任何用 OpenAI SDK 的老代码,改 base_url + key 就能跑"——这是 LiteLLM Proxy 最大魅力,迁移成本近似零。

网关 vs SDK 该怎么选

维度	SDK 模式 (Router)	Proxy 模式 (Server)
部署	import 到业务代码	独立服务
语言	只 Python	任何语言(走 HTTP)
配额硬限	应用自觉	网关强制
Virtual Keys	无	有(Postgres)
Admin UI	无	有
配置改动	要发版	热更/UI 改
SSO/RBAC	无	有
网络延迟	0(本进程)	+5–15ms
运维复杂度	低	中(Postgres+Redis)
合适规模	1–3 个 Python 服务	≥ 5 人/多语言/多部门

组合用才最有力。公司级:Proxy 统一管理;某个 Python 服务内部嵌 Router,Router 的"upstream"配成 Proxy。这样:业务代码享受 Router 的本进程性能,同时整个公司的账、日志、key 治理都在 Proxy 一头。

常见坑位

Master Key 泄露:它有最高权限,能建任意 key/team。永远不要交给业务,只在管理员和 CI 里用,定期轮换。
没上 Postgres:没有 DB,Virtual Keys/spend/logs 全丢,生产必配。
忘了配 Redis:多实例之间限额各算各的,实际限额 = 配置值 × replica 数。
health check 只打 /health:这只看进程活不活。真正的探测要用 /health/liveliness(连 DB/Redis)和 /health/readiness(能不能路由)。
把 Proxy 暴露到公网:必须前面挂 API Gateway / Ingress + WAF + rate limit。直接暴露等于把账单按钮放外网。
callback 里同步写 S3:S3 偶发 500ms,把你所有请求 p99 拖垮。用 async callback + buffer。
升级直接 latest tag:LiteLLM 迭代极快,一个 PR 可能改动 schema。生产一定锁版本,改完在 staging 跑 24h 再推。
用 in-memory cache:多 replica 下命中率直接除以 replica 数,同时 stats 乱。Proxy 场景强制用 Redis 缓存。

本章小结

    Proxy 把 LiteLLM 做成公司级 AI 网关,业务走 OpenAI SDK 改 base_url 就能接入
config.yaml 四块:model_list / router_settings / litellm_settings / general_settings
Master Key 管理员用;业务只拿 Virtual Key,受 budget/rpm/tpm/models 四重约束
三层治理:Team → User → Key,预算/白名单逐层约束,Postgres 做权威存储
Admin UI 做可视化运维,/ui 路由自带 Keys/Teams/Logs/Usage 页
Docker Compose 四件套:Proxy + Postgres + Redis + 业务;Helm 适合集群规模
合规:success_callback 双写 S3 + Langfuse,做到 prompt/response 可审计
SDK Router vs Proxy Server:小团队 SDK,公司规模 Proxy,组合拳最强

  

Proxy Server:公司级的 AI 网关

为什么需要一个网关

3 分钟跑起来

config.yaml 的 4 大板块

Virtual Keys:业务的第一入口

三级权限:Team → User → Key

Admin UI:可视化管理

Docker / Compose 部署

Kubernetes / Helm 部署

日志与可审计

客户端迁移

网关 vs SDK 该怎么选

常见坑位

本章小结