LiteLLM 部署实战：Docker 环境

1. 引言

LiteLLM 是一个开源的 LLM 网关，它提供统一的 API 接口，让开发者可以用一套代码接入 OpenAI、Anthropic、Azure OpenAI、Google Gemini 等多家大模型服务。通过 LiteLLM，你可以实现模型路由、负载均衡、成本追踪、限流和密钥管理等功能，从而简化多模型接入的复杂度。

本文将从零开始，介绍 LiteLLM 的部署方式，包括本地快速启动、Docker 部署、生产环境配置以及常见问题排查，帮助你快速搭建一个稳定可用的 LLM 网关服务。

2. LiteLLM 简介

LiteLLM 的核心价值在于统一了不同厂商的 API 差异。无论是请求格式、鉴权方式还是响应结构，LiteLLM 都会帮你转换为 OpenAI 兼容的格式，这样你的业务代码只需要对接一个标准接口即可。

它的主要特性包括：

统一接口：所有模型都通过 OpenAI 兼容的 /chat/completions 接口调用。
多模型路由：支持按模型名、供应商、优先级进行路由分发。
负载均衡：同一模型配置多个 Key 时自动轮询，提升可用性。
成本与用量追踪：内置 Token 计数和费用统计，方便预算管理。
密钥管理：支持 Virtual Key，避免在业务侧暴露真实供应商密钥。

3. 环境准备

在开始部署之前，需要准备以下环境：

一个可用的模型供应商 API Key（如 OpenAI、Anthropic 等）
Docker 环境（用于容器化部署）
Postgres DB

4. Docker 部署

对于生产环境，推荐使用 Docker 部署，这样可以实现环境一致性、快速扩容和便捷的版本管理。

4.1 使用官方镜像

LiteLLM 官方提供了 Docker 镜像，可以直接拉取运行：

bash 复制代码

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

4.2 创建PG DB、account (role)

Create a role: litellm

Create a Database: litellm, using the litellm for owner.

4.3 设置密钥

export DATABASE_URL='postgresql://litellm:***@litellm:5432/litellm'

export LITELLM_MASTER_KEY="***"

export STORE_MODEL_IN_DB="True"

4.4 启动 LiteLLM

复制代码

docker run -d \
  --name litellm \
  -p 4000:4000 \
  -e DATABASE_URL \
  -e LITELLM_MASTER_KEY \
  -e STORE_MODEL_IN_DB \
  ghcr.io/berriai/litellm:main-stable

## 查看日志：
# docker logs -f litellm

## 停止和删除容器：
# docker stop litellm
# docker rm litellm

启动后，可以通过 http://localhost:4000 访问 LiteLLM 服务。UI 地址：http://localhost:4000/ui

4.5 Add model on UI

Open LiteLLM UI, enter user-name: admin and password: {LITELLM_MASTER_KEY} to login.

Add a model: 配置模型供应商的 API Key

4.6 测试请求

复制代码

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

5. Create start.sh

复制代码

# 停止和删除容器：
docker stop litellm
docker rm litellm

export DATABASE_URL='postgresql://litellm:***@litellm:5432/litellm'
export LITELLM_MASTER_KEY="***"
export STORE_MODEL_IN_DB="True"

docker run -d \
  --name litellm \
  -p 4000:4000 \
  -e DATABASE_URL \
  -e LITELLM_MASTER_KEY \
  -e STORE_MODEL_IN_DB \
  ghcr.io/berriai/litellm:main-stable

6. 生产环境配置

6.1 启用 Virtual Key

通过 Virtual Key 机制，可以为不同业务方分配独立的访问密钥，并设置独立的预算和速率限制，避免直接暴露供应商密钥。

6.2 日志与监控

建议将 LiteLLM 的日志接入集中式日志系统，并配置 Prometheus 指标采集，以便实时监控请求量、延迟和错误率。

7. 常见问题排查

在部署和使用过程中，可能会遇到一些常见问题，这里列出几个典型场景及解决方法。

7.1 请求超时

如果上游模型响应较慢，可以在配置中调整超时时间：

yaml 复制代码

litellm_settings:
  request_timeout: 600

7.2 模型 404 错误

通常是因为模型名称未在 model_list 中正确配置，请检查配置文件中的模型名是否与请求中的 model 参数一致。

7.3 数据库连接失败

检查 DATABASE_URL 配置是否正确，并确认数据库服务已启动且网络可达。

8. 总结

LiteLLM 作为一款优秀的 LLM 网关，能够显著降低多模型接入的开发和维护成本。通过本文介绍的Docker 部署和生产配置方法，你可以快速搭建一套稳定可靠的模型代理服务。

在实际落地时，建议根据业务规模合理规划数据库、监控和密钥管理策略，并持续关注 LiteLLM 官方文档和版本更新，以获得最新的功能和性能优化。