LiteLLM Proxy 使用指南：Docker 部署、vLLM 代理

背景与目标

LiteLLM Proxy 是一个 OpenAI API 兼容的模型网关，支持将来自 OpenAI、Azure OpenAI、Bedrock、Vertex AI 以及本地/自建的 OpenAI 兼容推理服务（如 vLLM）统一到一套接口之下，并提供虚拟 API Key、用量与预算、速率限制、缓存、日志/指标、路由、负载均衡与回退等能力。本文将演示：

• 如何用 Docker 快速部署 LiteLLM Proxy（含最小可用与带数据库的完整模式）
• 如何把 vLLM 暴露的 OpenAI 兼容接口接入到 LiteLLM Proxy 进行统一代理
• 如何生成虚拟 Key、设置每分钟请求数（RPM）限速
• 如何查询模型列表等常用“免费”功能

参考与更多细节请见官方文档：

• LiteLLM Proxy Docker 快速上手
• vLLM Provider 文档

你将学到什么

• 用 Docker 启动 LiteLLM Proxy，并验证 /chat/completions
• 将本地 vLLM（OpenAI 兼容接口）纳入代理，统一用 OpenAI 协议调用
• 配置同名模型多后端负载均衡，实现流量分发与高可用
• 在不接数据库的前提下，如何给”不同团队”分发可控的 Key（网关方案）
• 接入数据库后，如何生成”虚拟 Key”、设置限速并进行用量治理
• 查询模型列表、排错以及生产级监控与高可用实践

核心功能速览

• OpenAI 兼容：统一 /chat/completions、/embeddings 等接口
• 多模型路由：一个代理前面挂多家模型与自建 vLLM
• 负载均衡：同名模型多后端分发，支持 simple-shuffle、usage-based-routing、latency-based-routing 等策略
• 密钥治理：
  • 无数据库：用网关做静态 Key 白名单 + 限速 + 审计
  • 带数据库：原生虚拟 Key、预算/配额、团队/用户可视化管理
• 可观测性：日志、指标、追踪，支持缓存与回退策略

如何阅读这篇文章

• 想快速跑通：直接看”快速开始”和”对接 vLLM”。
• 需要负载均衡：看”负载均衡：同名模型多后端分发”。
• 无数据库就要分发团队 Key：看”无数据库的密钥治理（最简部署）”。
• 需要 RPM/预算/面板：看”使用 Docker Compose（Proxy + Postgres）”与”生成虚拟 Key 并设置限速（RPM）”。
• 线上实践：看”生产部署实践（监控与高可用）”。

快速开始（最小可用）

你可以直接拉取官方镜像并用一份 config.yaml 启动 Proxy。下面示例展示最小可用部署（未接数据库、仅用于功能验证）。

# Pull image
docker pull ghcr.io/berriai/litellm:main-latest

# Start proxy with your config (created in next section)
docker run \
  -v $(pwd)/litellm_config.yaml:/app/config.yaml \
  -e AZURE_API_KEY=demo \
  -e AZURE_API_BASE=https://example.openai.azure.com/ \
  -p 4000:4000 \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml --detailed_debug
# Proxy up at http://0.0.0.0:4000

最简单的 litellm_config.yaml（示例使用 Azure OpenAI，仅用于快速跑通 Proxy）：

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: azure/my_azure_deployment
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: "2025-01-01-preview" # optional

提示：启动后可用 POST /chat/completions 进行测试，详见下文调用示例。

使用 Docker Compose（Proxy + Postgres）

如果需要启用虚拟 Key、用户/团队管理、预算与用量统计等高级功能，建议配合 Postgres 使用。官方提供了现成的 docker-compose.yml 与 .env 用法：

# Get the compose file
curl -O https://raw.githubusercontent.com/BerriAI/litellm/main/docker-compose.yml

# Set master key (admin) and salt key (for encrypting provider keys)
echo 'LITELLM_MASTER_KEY="sk-1234"' > .env
echo 'LITELLM_SALT_KEY="sk-1234"' >> .env
source .env

# Start services
docker-compose up

将数据库接入到 config.yaml：

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: azure/my_azure_deployment
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: "2025-01-01-preview"

general_settings:
  master_key: sk-1234
  database_url: "postgresql://<user>:<password>@<host>:<port>/<dbname>"

使用数据库后，默认提供 /ui 管理界面，可在浏览器访问。

对接 vLLM：把自建模型纳入统一代理

vLLM 可以以 OpenAI 兼容方式暴露推理服务（/v1 路径）。我们先启动 vLLM，再在 LiteLLM 里将其注册为一个“模型”。

1) 启动 vLLM（OpenAI 兼容 API）

# Example: start vLLM OpenAI-compatible server
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000
# vLLM OpenAI API at http://<host>:8000/v1

如果使用容器化 vLLM，请确保 LiteLLM Proxy 容器能够访问到 vLLM 的 http://<host>:8000/v1（可用 host.docker.internal 或桥接网络）。

2) 在 LiteLLM 中注册 vLLM 模型

LiteLLM 对“OpenAI 兼容端点”的使用建议前缀为 hosted_vllm/。将 litellm_params.model 设为 hosted_vllm/<model-identifier>，并把 api_base 指向你 vLLM 的 /v1 即可。

# file: litellm_config.yaml
model_list:
  - model_name: llama-3.1-8b-instruct
    litellm_params:
      model: hosted_vllm/llama-3.1-8b-instruct  # route to OpenAI-compatible vLLM
      api_base: os.environ/HOSTED_VLLM_API_BASE # e.g. http://host.docker.internal:8000/v1
      api_key: os.environ/HOSTED_VLLM_API_KEY   # optional if your vLLM server doesn't require it

general_settings:
  master_key: sk-1234                           # required if you want admin/virtual keys

然后启动 LiteLLM Proxy：

docker run \
  -v $(pwd)/litellm_config.yaml:/app/config.yaml \
  -e HOSTED_VLLM_API_BASE=http://host.docker.internal:8000/v1 \
  -e HOSTED_VLLM_API_KEY=EMPTY \
  -p 4000:4000 \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml --detailed_debug

现在，Proxy 会以 model: "llama-3.1-8b-instruct" 的名义，将请求转发到你本地/私有的 vLLM 服务上。

常见坑速查（vLLM 对接）

• 404/connection error：api_base 必须指向 vLLM 的 /v1 根，如 http://host:8000/v1。
• 容器网络：Proxy 与 vLLM 不在同一网络时，使用 host.docker.internal 或配置自定义 bridge 网络。
• 鉴权：若 vLLM 无鉴权，api_key 可留空；若自定义鉴权，请按 vLLM 的要求设置。
• 模型名不一致：model_name（对外名）可以自定义，但 litellm_params.model 需符合前缀与路由规则（hosted_vllm/<name>）。

负载均衡：同名模型多后端分发

在 model_list 中设置同名的 model_name，可实现流量负载到不同的后端。这种情况下 master_key 是必须的。同时路由策略默认为：simple-shuffle，其它策略可在 LiteLLM 负载均衡文档 中查看。

负载均衡配置示例

# file: litellm_config.yaml
model_list:
  # 第一个后端实例
  - model_name: llama-3.1-8b-instruct
    litellm_params:
      model: hosted_vllm/llama-3.1-8b-instruct
      api_base: http://vllm-backend-1:8000/v1
      api_key: ""
  
  # 第二个后端实例（同名模型）
  - model_name: llama-3.1-8b-instruct
    litellm_params:
      model: hosted_vllm/llama-3.1-8b-instruct
      api_base: http://vllm-backend-2:8000/v1
      api_key: ""
  
  # 第三个后端实例（同名模型）
  - model_name: llama-3.1-8b-instruct
    litellm_params:
      model: hosted_vllm/llama-3.1-8b-instruct
      api_base: http://vllm-backend-3:8000/v1
      api_key: ""

general_settings:
  master_key: sk-1234  # 负载均衡功能需要 master_key
router_settings:
  routing_strategy: simple-shuffle  # 默认策略，可选：usage-based-routing, latency-based-routing

负载均衡测试

启动多个 vLLM 后端实例：

# 启动第一个 vLLM 实例
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8001

# 启动第二个 vLLM 实例
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8002

# 启动第三个 vLLM 实例
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8003

启动 LiteLLM Proxy：

docker run \
  -v $(pwd)/litellm_config.yaml:/app/config.yaml \
  -p 4000:4000 \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml --detailed_debug

验证负载均衡效果

发送多个请求，观察流量分发：

# 发送 10 个请求，观察负载分发
for i in {1..10}; do
  echo "Request $i:"
  curl -X POST 'http://0.0.0.0:4000/chat/completions' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer sk-1234' \
    -d '{
      "model": "llama-3.1-8b-instruct",
      "messages": [
        {"role": "user", "content": "Hello, which backend am I talking to?"}
      ],
      "max_tokens": 50
    }' | jq '.choices[0].message.content'
  echo "---"
done

其他路由策略

除了默认的 simple-shuffle，还可以使用以下策略：

general_settings:
  master_key: sk-1234
  routing_strategy: usage-based-routing  # 基于使用量的路由
  # 或者
  routing_strategy: latency-based-routing  # 基于延迟的路由

注意：负载均衡功能需要 master_key 支持，确保在 general_settings 中正确配置。

通过 Proxy 发起聊天请求

LiteLLM Proxy 兼容 OpenAI SDK/接口。以下用 curl 演示：

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-1234' \
  -d '{
    "model": "llama-3.1-8b-instruct",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is LiteLLM Proxy?"}
    ]
  }'

如果未使用数据库，你也可以把 Authorization 设置为你在 general_settings.master_key 中配置的主密钥；若启用了虚拟 Key（见下一节），则推荐使用虚拟 Key 访问。

生成虚拟 Key 并设置限速（RPM）

启用了数据库后，可使用主密钥（master_key）来创建受控的虚拟 Key。例如限制每分钟 1 次请求：

curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json' \
  -d '{"rpm_limit": 1}'

成功将返回：

{ "key": "sk-12..." }

使用该虚拟 Key 调用模型：

# 1st call - should succeed
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-12...' \
  -d '{
    "model": "llama-3.1-8b-instruct",
    "messages": [
      {"role": "system", "content": "You are a helpful math tutor."},
      {"role": "user", "content": "How to solve 8x + 7 = -23?"}
    ]
  }'

# 2nd call (within one minute) - should fail with 429
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-12...' \
  -d '{
    "model": "llama-3.1-8b-instruct",
    "messages": [
      {"role": "system", "content": "You are a helpful math tutor."},
      {"role": "user", "content": "How to solve 8x + 7 = -23?"}
    ]
  }'

查询模型列表（/models）

LiteLLM Proxy 暴露 OpenAI 兼容的模型列表接口：

curl -s 'http://0.0.0.0:4000/models' \
  -H 'Authorization: Bearer sk-1234'

返回的列表中将包含你在 model_list 中注册的模型（例如 llama-3.1-8b-instruct）。

常见问题与故障排除

• SSL 校验失败 / 连接错误：可在 config.yaml 中关闭 SSL 校验（仅在受信环境调试时使用）。

  litellm_settings:
    ssl_verify: false

• 数据库连接失败 / 权限不足：确认数据库用户有建库/建表权限。必要时在数据库中执行授权（云厂商如 CloudSQL 语法略有差异）。

• 非 root 场景：官方提供了非 root 镜像使用说明，按需选择。

• vLLM 访问不到：检查容器网络连通性，api_base 是否指向了可达的 http://<host>:8000/v1，以及是否通过 host.docker.internal 或自定义 bridge 网络打通。

安全与最佳实践

• 生产环境务必使用强随机的 LITELLM_SALT_KEY 与 master_key，切勿在版本库中明文提交。
• 对外暴露的 Proxy 建议置于零信任/网关之后，搭配 WAF/速率限制/鉴权策略。
• 针对不同团队与应用使用不同的虚拟 Key，并配置预算、RPM/TPM、可访问模型白名单。
• 定期审计访问日志与开销，启用缓存与模型路由策略以优化成本与稳定性。

生产部署实践（监控与高可用）

架构与高可用

• 多副本部署：将 LiteLLM Proxy 以无状态方式水平扩展，多副本 + 负载均衡（Nginx/Ingress/Gateway）。
• 数据库高可用：Postgres 采用主从/托管服务（如 RDS/CloudSQL/Aurora），开启自动备份与只读副本；连接池建议使用 PgBouncer。
• 缓存层：开启 Proxy 的缓存能力，或引入 Redis 作为响应缓存（对热门提示/嵌入有效）。
• 故障回退：在 model_list 中配置路由回退与多提供商冗余，优先同类开源模型或公有云模型作为备份。
• 弹性伸缩：以 QPS/RPM、CPU、延迟 P95/P99 为指标触发 HPA（K8s 水平自动扩缩容）。

监控与日志

• 核心指标（Proxy）：
  • 请求量：requests_total（按模型、调用方、状态码分维度）
  • 成功率：success_rate（2xx 比例）
  • 延迟：latency_ms_p50/p95/p99
  • 速率限制触发：rate_limit_hits
  • Token/成本：input_tokens_total、output_tokens_total、cost_total
• 核心指标（vLLM）：
  • 并发/排队：requests_in_flight、queue_depth
  • 显存与负载：gpu_memory_used、gpu_utilization、cpu_utilization
  • 拒绝/超时：backend_errors、timeout_errors
• 日志与追踪：
  • 结构化访问日志（含 request_id、调用方、模型、用量、耗时、状态码）
  • 结合 OpenTelemetry / Jaeger 进行链路追踪，串联网关→Proxy→vLLM→存储
• 可观测性栈：Prometheus + Grafana（Dashboard：Proxy 指标 + vLLM/GPU 指标），Loki/ELK 做日志聚合。

告警阈值示例

• 成功率低于 98%（5 分钟窗口）
• P95 延迟高于 2s（连续 10 分钟）
• 429 速率限制命中率 > 5%（提示需要扩容或调参）
• vLLM queue_depth > 100 且持续 5 分钟（推理拥塞）
• GPU 显存利用率 > 95% 且持续 10 分钟（需要缩短 max tokens/增加副本）

安全与密钥治理

• 密钥管理：LITELLM_SALT_KEY 与 master_key 存放于 KMS/Secret Manager；定期轮换，最小权限访问。
• 虚拟 Key 策略：为每个应用/团队单独发放虚拟 Key，设置 RPM/TPM/并发、预算与模型白名单，超限自动告警。
• 网络与访问控制：将 Proxy 置于私有网络内，通过 API 网关暴露；开启 WAF 与 IP 访问控制；对外只暴露必要端口。
• 数据与合规：记录审计日志，敏感数据脱敏；对模型消息体避免长期持久化，仅保留元数据。

灰度与流量治理

• 版本灰度：新模型/新参数走 1%-5% 灰度；监控指标稳定后逐步扩大权重。
• 路由策略：按租户/区域/延迟/成本做智能路由与回退；对低优先级任务使用更低成本模型。
• 缓存与重放：对可缓存请求开启缓存；对失败请求采用指数退避与幂等重试（结合 request_id）。

无数据库的密钥治理（最简部署）

前提说明：官方 E2E 教程中，虚拟 Key（/key/generate）功能需要接入 Postgres 数据库方可启用与持久化管理（参考：LiteLLM Proxy Docker 快速上手 的“Generate a virtual key”章节）。在“最简部署（无数据库）”下，内建的虚拟 Key、预算、配额面板不可用。以下提供两种在无数据库前提下的可操作密钥治理方案。

方案 A：API 网关静态 Key 白名单（推荐）

思路：

• 为每个团队生成一个“外发 Key”（例如 sk-teamA-...、sk-teamB-...），仅对团队公开。
• 在 API 网关（Nginx/Kong/Traefik 等）校验来访 Key；校验通过后，将请求头 Authorization 改写为 LiteLLM 的 master_key，并注入 X-Team 头标识团队，LiteLLM Proxy 端只需维护 master_key 即可。
• 限速与访问控制在网关实现（按团队维度），日志也在网关聚合，LiteLLM 只做推理转发。

操作步骤：

1. 配置 LiteLLM 最简 config.yaml（仅 master_key）：

   model_list:
     - model_name: llama-3.1-8b-instruct
       litellm_params:
         model: hosted_vllm/llama-3.1-8b-instruct
         api_base: http://vllm:8000/v1
         api_key: ""
   general_settings:
     master_key: sk-master-very-strong

2. 启动 LiteLLM Proxy（略，见前文）。

3. 在 Nginx 上实现静态 Key 白名单 + 改写：

   # 假设放在 stream 或 http 反向代理前置，以下为 http 片段示例
   map $http_authorization $team_name {
     default "";
     "Bearer sk-teamA-123" teamA;
     "Bearer sk-teamB-456" teamB;
   }
   
   map $http_authorization $is_valid_key {
     default 0;
     "Bearer sk-teamA-123" 1;
     "Bearer sk-teamB-456" 1;
   }
   
   # 可选：每团队限速桶，1 分钟 60 次
   limit_req_zone $team_name zone=per_team:10m rate=60r/m;
   
   server {
     listen 80;
     server_name litellm.example.com;
   
     location / {
       if ($is_valid_key = 0) { return 401; }
   
       # 限速（命中返回 429）
       limit_req zone=per_team burst=30 nodelay;
   
       # 注入团队头，改写为 master_key 转发到 LiteLLM Proxy
       proxy_set_header Authorization "Bearer sk-master-very-strong";
       proxy_set_header X-Team $team_name;
       proxy_pass http://litellm-proxy:4000;
     }
   }

4. 团队使用各自外发 Key 调用：

   # Team A
   curl -X POST 'https://litellm.example.com/chat/completions' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer sk-teamA-123' \
     -d '{
       "model": "llama-3.1-8b-instruct",
       "messages": [
         {"role": "user", "content": "hi"}
       ]
     }'

优点：

• 无需数据库即可做到“多团队 Key、限速、隔离与审计”。
• Key 轮换在网关层进行，LiteLLM 无感。

注意：

• 外发 Key 白名单应存放于 Secret 管理，启用审计与告警；网关日志中保留 X-Team 以便统计。
• 若需更精细的模型白名单、预算、用量统计面板，请切换到“带数据库”模式，使用虚拟 Key 原生能力。

方案 B：多实例多主密钥（隔离更强）

思路：

• 为每个团队部署一个 LiteLLM Proxy 实例，分别设置不同的 master_key 与域名（如 teamA-llm.example.com）。
• 通过上游 LB/Ingress 做域名或路径路由，实例间资源独立，便于限速与版本隔离。

优点：

• 实例层面的强隔离，团队级资源/风控策略互不影响。

成本：

• 需要多实例运维与配置同步（可用 IaC/Helm 统一下发）。

无数据库下的常见诉求替代

• 限速：用网关 limit_req（Nginx）或 API 网关内置策略按团队维度限速。
• 预算/用量：解析网关日志与 LiteLLM 访问日志，按 X-Team 汇总请求数与 token 用量（可在边车或日志管道中解析响应 usage 字段）。
• 模型白名单：按路由规则控制允许访问的路径和模型名（例如基于 model 字段的 WAF/自定义网关插件）。

若后续需要虚拟 Key、预算、速率限制、团队/用户/密钥可视化管理，建议切换带数据库的部署方式；参考前文与官方教程：LiteLLM Proxy Docker 快速上手。

参考资料

• 官方教程：LiteLLM Proxy E2E 与 Docker 快速启动（包含虚拟 Key、速率限制、数据库接入等）
  • https://docs.litellm.ai/docs/proxy/docker_quick_start
• vLLM Provider 集成说明（如何让 LiteLLM 代理 vLLM 暴露的 OpenAI 兼容服务）
  • https://docs.litellm.ai/docs/providers/vllm

本文由 AI 辅助生成，如有错误或建议，欢迎指出。