1. LiteLLM 多模型 API 网关部署实战
在当前的 AI 应用开发领域,开发者经常需要同时接入多个大语言模型(LLM)服务。以我最近负责的一个智能客服系统为例,我们需要同时调用通义千问、Kimi 和 Claude 等多个模型,每个模型都有不同的 API 接入方式、密钥管理和计费体系。这种碎片化的接入方式不仅增加了开发复杂度,也给运维带来了巨大挑战。
LiteLLM 作为开源的 LLM 代理网关,完美解决了这个问题。它提供了统一的 OpenAI 兼容接口,让我们可以用相同的方式调用 100+ 种大模型。经过两周的实战部署和调优,我将分享从环境准备到生产部署的全过程经验,特别是那些官方文档没有提及的实战技巧和避坑指南。
2. 环境准备与安装
2.1 系统要求与前置检查
在开始部署前,建议先进行系统环境检查。以下是我在阿里云 ECS 上使用的配置清单:
- 操作系统:Ubuntu 22.04 LTS(内核版本 5.15+)
- Docker 版本:Docker Engine 24.0.5(注意:20.10+版本即可)
- Docker Compose:v2.23.0
- 硬件配置:
- CPU:4核(建议 x86_64 架构)
- 内存:8GB(最低4GB,生产环境建议16GB+)
- 存储:50GB SSD(用于数据库和缓存持久化)
重要提示:如果使用 ARM 架构服务器(如 AWS Graviton),需要确认 LiteLLM 镜像是否支持多架构。我在测试中发现部分 ARM 环境会出现兼容性问题,建议优先选择 x86 架构。
2.2 项目结构与文件准备
创建以下目录结构(这是我经过多次部署优化后的最佳实践):
bash复制litellm-gateway/
├── docker-compose.yml # Docker 服务定义
├── config.yaml # LiteLLM 模型配置
├── .env # 环境变量(务必加入.gitignore)
├── scripts/ # 辅助脚本目录
│ ├── init_db.sh # 数据库初始化脚本
│ └── healthcheck.sh # 服务健康检查
└── logs/ # 日志目录(建议挂载到主机)
2.3 关键配置文件详解
2.3.1 Docker Compose 配置优化版
yaml复制version: "3.8"
services:
litellm-proxy:
image: ghcr.io/berriai/litellm:main-v1.81.12-stable.1
ports:
- "4000:4000"
volumes:
- ./config.yaml:/app/config.yaml:ro
- ./logs:/app/logs
environment:
- DATABASE_URL=postgresql://litellm:${DB_PASSWORD}@db:5432/litellm
- LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
- DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY}
- DASHSCOPE_API_BASE=${DASHSCOPE_API_BASE}
- REDIS_HOST=redis
- REDIS_PORT=6379
- REDIS_PASSWORD=${REDIS_PASSWORD}
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
restart: unless-stopped
command: --config /app/config.yaml --port 4000 --detailed_debug --num_workers 4
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:4000/health"]
interval: 30s
timeout: 10s
retries: 3
db:
image: postgres:14-alpine
environment:
- POSTGRES_DB=litellm
- POSTGRES_USER=litellm
- POSTGRES_PASSWORD=${DB_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
- ./scripts/init_db.sh:/docker-entrypoint-initdb.d/init_db.sh
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U litellm"]
interval: 10s
timeout: 5s
retries: 5
redis:
image: redis:7-alpine
command: redis-server --requirepass ${REDIS_PASSWORD} --appendonly yes
volumes:
- redis_data:/data
restart: unless-stopped
healthcheck:
test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
interval: 10s
timeout: 5s
retries: 5
volumes:
postgres_data:
redis_data:
关键优化点:
- 增加了健康检查端点(healthcheck)
- 添加了日志目录挂载
- 包含数据库初始化脚本挂载点
- 调整了健康检查间隔和重试次数
2.3.2 环境变量文件(.env)安全实践
ini复制# 主密钥配置
LITELLM_MASTER_KEY=sk-master-你的主密钥(至少32位随机字符)
# 数据库配置
DB_PASSWORD=你的数据库密码(建议使用密码生成器生成)
# Redis配置
REDIS_PASSWORD=你的Redis密码(建议与数据库密码不同)
# 阿里云百炼API配置
DASHSCOPE_API_KEY=sk-your-dashscope-key
DASHSCOPE_API_BASE=https://coding.dashscope.aliyuncs.com/v1
# 管理界面凭证(可选)
UI_USERNAME=admin
UI_PASSWORD=你的管理密码
安全建议:
- 所有密码应使用密码管理器生成(至少16位,包含大小写字母、数字和特殊字符)
- 文件权限设置为600:
chmod 600 .env - 永远不要将此文件提交到版本控制系统
3. 核心配置与模型管理
3.1 多模型配置实战
以下是支持阿里云百炼多个模型的完整配置示例(config.yaml):
yaml复制model_list:
- model_name: qwen3.5-plus(aliCP)
litellm_params:
model: qwen3.5-plus
api_base: os.environ/DASHSCOPE_API_BASE
api_key: os.environ/DASHSCOPE_API_KEY
custom_llm_provider: openai
rpm: 1000
tpm: 1000000
timeout: 30
metadata:
deployment: "aliyun-coding-plan"
region: "cn-hangzhou"
- model_name: kimi-k2.5(aliCP)
litellm_params:
model: kimi-k2.5
api_base: os.environ/DASHSCOPE_API_BASE
api_key: os.environ/DASHSCOPE_API_KEY
custom_llm_provider: openai
rpm: 500
tpm: 500000
timeout: 25
metadata:
deployment: "aliyun-coding-plan"
region: "cn-shanghai"
router_settings:
routing_strategy: simple-shuffle
model_group_alias:
default: qwen3.5-plus(aliCP)
vision: qwen3.5-plus(aliCP)
num_retries: 2
timeout: 30
retry_delay: 5
litellm_settings:
drop_params: true
cache: true
cache_params:
type: redis
host: os.environ/REDIS_HOST
port: os.environ/REDIS_PORT
password: os.environ/REDIS_PASSWORD
ttl: 3600 # 缓存1小时
num_retries: 3
request_timeout: 30
success_callback: ["posthog"] # 可添加监控回调
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
database_url: os.environ/DATABASE_URL
database_connection_pool_limit: 20
proxy_batch_write_at: 60
enable_ui: true # 启用管理界面
配置亮点:
- 每个模型都设置了合理的速率限制(rpm/tpm)
- 添加了metadata字段记录部署信息
- 配置了Redis缓存(TTL 1小时)
- 启用了管理界面
3.2 负载均衡高级配置
当需要处理高流量时,可以通过权重分配实现负载均衡:
yaml复制model_list:
# 主API端点 - 70%流量
- model_name: qwen3.5-plus
litellm_params:
model: qwen3.5-plus
api_base: https://primary.dashscope.aliyuncs.com/v1
api_key: os.environ/DASHSCOPE_API_KEY_1
custom_llm_provider: openai
rpm: 1500
weight: 7
timeout: 30
# 备用API端点 - 30%流量
- model_name: qwen3.5-plus
litellm_params:
model: qwen3.5-plus
api_base: https://secondary.dashscope.aliyuncs.com/v1
api_key: os.environ/DASHSCOPE_API_KEY_2
custom_llm_provider: openai
rpm: 1500
weight: 3
timeout: 30
流量分配策略对比:
| 策略类型 | 配置值 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|---|
| 随机加权 | simple-shuffle | 常规生产环境 | 实现简单,分布均匀 | 不考虑节点状态 |
| 延迟优先 | latency-based-routing | 对延迟敏感场景 | 自动选择最快节点 | 需要持续监控延迟 |
| 最少负载 | least-busy | 高并发场景 | 避免单点过载 | 实现复杂度高 |
| 成本优化 | cost-based-routing | 预算有限场景 | 节省API成本 | 可能牺牲性能 |
4. 密钥管理与安全实践
4.1 密钥生命周期管理
通过API管理密钥的完整流程:
bash复制# 生成新密钥(有效期30天,限用指定模型)
curl -X POST 'http://localhost:4000/key/generate' \
-H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
-H "Content-Type: application/json" \
-d '{
"models": ["qwen3.5-plus(aliCP)", "kimi-k2.5(aliCP)"],
"metadata": {"team": "chatbot-dev"},
"expires": "2024-08-01T00:00:00Z",
"budget": 100.00 # 设置预算上限(美元)
}'
# 列出所有密钥
curl 'http://localhost:4000/key/info' \
-H "Authorization: Bearer ${LITELLM_MASTER_KEY}"
# 禁用泄露的密钥
curl -X POST 'http://localhost:4000/key/block' \
-H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
-H "Content-Type: application/json" \
-d '{"key": "sk-泄露的密钥"}'
# 查询密钥使用情况
curl 'http://localhost:4000/key/usage?key=sk-要查询的密钥' \
-H "Authorization: Bearer ${LITELLM_MASTER_KEY}"
4.2 安全最佳实践
-
密钥轮换策略:
- 主密钥每3个月更换一次
- 应用密钥设置合理有效期(通常1-3个月)
- 使用预算限制防止超额消费
-
访问控制:
yaml复制general_settings: allowed_functions: ["completion", "embedding"] # 限制可用功能 blocked_user_agents: ["curl/7.68.0"] # 屏蔽可疑UA -
审计日志:
bash复制# 查看最近100条审计日志 docker-compose exec db psql -U litellm -c \ "SELECT * FROM audit_logs ORDER BY created_at DESC LIMIT 100;"
5. 监控与运维
5.1 健康检查与监控
建议的Prometheus监控指标:
yaml复制# config.yaml 补充配置
litellm_settings:
monitoring:
prometheus: true
prometheus_port: 4001 # 指标暴露端口
metrics:
- latency
- usage
- errors
- cost
关键监控项:
- API响应延迟(P99 < 500ms)
- 错误率(5xx < 1%)
- 额度使用情况(接近限额时告警)
- 并发连接数(避免过载)
5.2 日志分析技巧
使用ELK栈分析日志的示例查询:
json复制// 查找高频错误
{
"query": {
"bool": {
"must": [
{ "match": { "level": "ERROR" } },
{ "range": { "@timestamp": { "gte": "now-1h" } } }
]
}
},
"aggs": {
"error_types": {
"terms": { "field": "error_type.keyword", "size": 5 }
}
}
}
常见日志模式与解决方案:
| 错误模式 | 可能原因 | 解决方案 |
|---|---|---|
| 429 Too Many Requests | 超出API速率限制 | 调整rpm/tpm或添加更多API key |
| 401 Unauthorized | 密钥失效或错误 | 检查密钥有效期和权限 |
| 503 Service Unavailable | 后端服务不可用 | 启用自动重试或切换到备用模型 |
| 400 Invalid Request | 参数不合法 | 检查输入数据格式 |
6. 故障排查实战记录
6.1 镜像拉取问题深度解决
当遇到ghcr.io访问问题时,除了重试脚本,还可以:
-
使用镜像加速器:
bash复制# 在/etc/docker/daemon.json中添加 { "registry-mirrors": [ "https://mirror.ccs.tencentyun.com", "https://docker.mirrors.ustc.edu.cn" ] }然后重启Docker:
sudo systemctl restart docker -
手动导入镜像:
bash复制# 在有网络的环境下拉取并保存 docker pull ghcr.io/berriai/litellm:main-v1.81.12-stable.1 docker save -o litellm.tar ghcr.io/berriai/litellm:main-v1.81.12-stable.1 # 在目标服务器加载 docker load -i litellm.tar
6.2 复杂环境变量问题
当环境变量未生效时,按此流程排查:
-
检查Compose文件变量引用:
bash复制grep -r "\${[A-Z_]*}" docker-compose.yml -
验证容器内环境变量:
bash复制docker-compose exec litellm-proxy env | grep DASHSCOPE -
检查变量名拼写(注意大小写敏感)
-
确认.env文件位置(必须与docker-compose.yml同级)
6.3 数据库连接池问题
典型错误日志:
code复制Connection pool limit exceeded, consider increasing pool_size
解决方案:
- 调整连接池大小:
yaml复制general_settings: database_connection_pool_limit: 50 - 优化查询:
sql复制-- 在PostgreSQL中创建索引 CREATE INDEX idx_requests_model ON litellm_api_audit (model_name); - 定期维护:
bash复制# 每周执行一次VACUUM docker-compose exec db psql -U litellm -c "VACUUM ANALYZE;"
7. 性能调优与扩展
7.1 横向扩展方案
当单节点性能不足时,可以:
-
增加Worker数量:
yaml复制# docker-compose.yml command: --config /app/config.yaml --port 4000 --num_workers 8建议Worker数 = CPU核心数 × 2
-
多节点部署架构:
code复制[负载均衡器] ├── [LiteLLM节点1] → [Redis/PostgreSQL集群] ├── [LiteLLM节点2] └── [LiteLLM节点3] -
数据库读写分离:
yaml复制environment: - DATABASE_URL=postgresql://litellm:${DB_PASSWORD}@db-primary:5432,db-replica:5432/litellm?target_session_attrs=read-write
7.2 缓存优化策略
-
分级缓存配置:
yaml复制cache_params: type: redis host: os.environ/REDIS_HOST port: os.environ/REDIS_PORT password: os.environ/REDIS_PASSWORD ttl: 3600 # 长期缓存 local_ttl: 60 # 短期本地缓存 max_size: 10000 # 最大缓存条目 -
缓存键优化:
python复制# 自定义缓存键生成逻辑(避免无效参数影响命中率) def custom_cache_key(params): return f"{params['model']}:{params['messages'][-1]['content']}" -
缓存预热脚本:
bash复制# 预先加载常见查询 curl -X POST "http://localhost:4000/cache/warmup" \ -H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \ -d @frequent_queries.json
8. 生产环境部署检查清单
在将网关部署到生产环境前,请完成以下检查:
-
[ ] 安全审计
- 主密钥已更换为随机生成值
- 所有密码强度符合要求(16+字符,含特殊字符)
- 管理界面已设置强密码
- 防火墙限制4000端口只对可信IP开放
-
[ ] 性能测试
- 使用locust进行负载测试(模拟峰值流量)
- 确认各模型rpm/tpm限制设置合理
- 监控P99延迟 < 1s
-
[ ] 灾备方案
- 配置了至少一个备用API端点
- 定期数据库备份(crontab每天全量备份)
- Redis持久化配置确认(AOF开启)
-
[ ] 监控告警
- Prometheus监控指标收集正常
- 配置了关键指标告警(错误率、延迟、额度)
- 日志收集系统(ELK或Loki)接入完成
-
[ ] 文档记录
- 维护runbook记录常见问题解决方案
- API文档已更新(Swagger或Redoc)
- 团队完成运维培训
经过三周的部署和调优,我们的LiteLLM网关目前稳定处理日均50万+请求,平均延迟控制在300ms以内。最大的收获是:一定要提前做好容量规划,并为每个模型设置合理的速率限制。曾经因为一个脚本失控导致API额度在10分钟内耗尽,这个教训让我们完善了监控和熔断机制。