欢迎光临
我们一直在努力
        找回密码
当前位置：171主机测评 > 服务器技术 > 正文

LiteLLM 多模型 API 网关部署教程：负载均衡、密钥管理与故障排查

2026-06-12 分类：服务器技术 阅读(59) 评论(0)

摘要：本文详细记录 LiteLLM Proxy 的完整部署过程，以阿里云百炼（Coding Plan）为例，涵盖 Docker 安装、多模型配置、负载均衡、密钥管理，以及部署过程中遇到的 5 个典型问题及解决方案。适合需要搭建私有化 LLM API 网关的开发者阅读。

关键词：LiteLLM Docker 部署、LiteLLM 阿里云配置、LiteLLM 负载均衡、LiteLLM 故障排查、LLM API 网关

一、前言

在 AI 应用开发中，我们经常面临这样的场景：需要同时调用多个大模型（如通义千问、Kimi、Claude 等），每个模型都有不同的 API 接入方式、密钥管理和计费体系。如何统一管理和调度这些模型资源？

LiteLLM 是一个开源的 LLM 代理网关，它提供了统一的 OpenAI 兼容接口，让我们可以用相同的方式调用 100+ 种大模型。本文以实际部署经验为基础，详细介绍如何使用 Docker 搭建 LiteLLM Proxy，并接入阿里云百炼（Coding Plan）API。

本文适合读者：

  • 需要统一管理和调度多个 LLM API 的开发者

  • 希望搭建私有化 API 网关的运维工程师

  • 正在使用 LiteLLM 并遇到配置问题的使用者

二、环境准备与安装

2.1 系统要求

  • Docker Engine 20.10+

  • Docker Compose 2.0+

  • 至少 4GB 可用内存

  • 开放 4000 端口（可自定义）

2.2 项目结构

litellm-team/
├── docker-compose.yml   # Docker 服务定义
├── config.yaml           # LiteLLM 模型配置
└── .env                 # 环境变量（不提交到 Git）

2.3 核心配置文件

docker-compose.yml：

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
  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
​
db:
  image: postgres:14-alpine
  environment:
    – POSTGRES_DB=litellm
    – POSTGRES_USER=litellm
    – POSTGRES_PASSWORD=${DB_PASSWORD}
  volumes:
    – postgres_data:/var/lib/postgresql/data
  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:

.env 环境变量（隐藏真实密钥）：

LITELLM_MASTER_KEY=sk-master-your-key-here
DB_PASSWORD=your-db-password
REDIS_PASSWORD=your-redis-password
DASHSCOPE_API_KEY=sk-your-dashscope-key
DASHSCOPE_API_BASE=https://coding.dashscope.aliyuncs.com/v1 # 根据要配置的模型进行进行变化
UI_USERNAME=admin
UI_PASSWORD=your-ui-password

三、核心配置详解

LiteLLM 的核心配置在 config.yaml 文件中。以下是以阿里云百炼（Coding Plan）为例的完整配置：

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
​
– 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
​
– model_name: glm-5(aliCP)
  litellm_params:
    model: glm-5
    api_base: os.environ/DASHSCOPE_API_BASE
    api_key: os.environ/DASHSCOPE_API_KEY
    custom_llm_provider: openai
    rpm: 500
    tpm: 500000
​
– model_name: MiniMax-M2.5(aliCP)
  litellm_params:
    model: MiniMax-M2.5
    api_base: os.environ/DASHSCOPE_API_BASE
    api_key: os.environ/DASHSCOPE_API_KEY
    custom_llm_provider: openai
    rpm: 500
    tpm: 500000
​
router_settings:
routing_strategy: simple-shuffle
model_group_alias:
  default: qwen3.5-plus
  vision: qwen3.5-plus
num_retries: 2
timeout: 30
​
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
num_retries: 3
request_timeout: 30
​
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

3.1 配置项详解

model_list：定义可用的模型列表

  • model_name：用户调用的模型别名，可自定义

  • litellm_params.model：实际的模型名称

  • api_base：API 基础地址，使用 os.environ/ 从环境变量读取

  • custom_llm_provider：必须是预定义值（如 openai、azure），不能自定义

  • rpm/tpm：每分钟请求数/令牌数限制，用于负载均衡

router_settings：路由配置

  • routing_strategy：负载均衡策略，simple-shuffle 为推荐策略

  • num_retries：失败重试次数

  • timeout：请求超时时间

litellm_settings：全局设置

  • cache：启用 Redis 缓存

  • drop_params：自动丢弃不支持的参数

四、高级配置：负载均衡与多 API Key

4.1 负载均衡配置

LiteLLM 支持通过相同的 model_name 实现负载均衡：

model_list:
 # 第一个部署：60% 流量
– model_name: qwen3.5-plus
  litellm_params:
    model: qwen3.5-plus
    api_base: os.environ/DASHSCOPE_API_BASE
    api_key: os.environ/DASHSCOPE_API_KEY_1
    custom_llm_provider: openai
    rpm: 1000
    weight: 6
​
 # 第二个部署：40% 流量
– model_name: qwen3.5-plus
  litellm_params:
    model: qwen3.5-plus
    api_base: os.environ/DASHSCOPE_API_BASE
    api_key: os.environ/DASHSCOPE_API_KEY_2
    custom_llm_provider: openai
    rpm: 1000
    weight: 4

4.2 路由策略选择

策略说明适用场景
simple-shuffle 基于权重随机选择（推荐） 生产环境
latency-based-routing 选择延迟最低的部署 低延迟需求
least-busy 选择当前负载最低的 高并发场景
cost-based-routing 选择成本最低的 成本优化

4.3 密钥管理

LiteLLM 支持动态生成和管理 API 密钥：

生成密钥：

curl 'http://localhost:4000/key/generate' \\
 -H 'Authorization: Bearer sk-master-your-key-here' \\
 -H 'Content-Type: application/json' \\
 -d '{
   "models": ["qwen3.5-plus(aliCP)", "kimi-k2.5(aliCP)"],
   "metadata": {"user": "developer@company.com"}
}'

禁用密钥：

curl -X POST 'http://localhost:4000/key/block' \\
 -H 'Authorization: Bearer sk-master-your-key-here' \\
 -H 'Content-Type: application/json' \\
 -d '{"key": "sk-key-to-block"}'

启用密钥：

curl -X POST 'http://localhost:4000/key/unblock' \\
 -H 'Authorization: Bearer sk-master-your-key-here' \\
 -H 'Content-Type: application/json' \\
 -d '{"key": "sk-key-to-unblock"}'

也可在LiteLLM UI 中进行管理设置。

五、测试与验证

5.1 启动服务

docker-compose up -d

5.2 验证模型配置

curl http://localhost:4000/model/info \\
-H "Authorization: Bearer sk-master-your-key-here"

5.3 测试 API 调用

curl http://localhost:4000/v1/chat/completions \\
-H "Authorization: Bearer sk-master-your-key-here" \\
-H "Content-Type: application/json" \\
-d '{
"model": "qwen3.5-plus(aliCP)",
"messages": [{"role": "user", "content": "你好"}],
"max_tokens": 100
}'

5.4 查看日志

# 实时查看 LiteLLM 日志
docker-compose logs -f litellm-proxy

# 查看最后 100 行
docker-compose logs –tail=100 litellm-proxy

六、踩坑实录：常见问题与解决方案

问题 1：LiteLLM Docker 镜像下载失败

现象：

error pulling image configuration: download failed after attempts=6: EOF

原因：国内网络访问 ghcr.io 受限。

解决：创建镜像拉取重试脚本：

# pull-litellm.ps1
$MAX_RETRIES = 50
$imageName = "ghcr.io/berriai/litellm:main-latest"

for ($i = 1; $i -le $MAX_RETRIES; $i++) {
Write-Host "Attempt $i of $MAX_RETRIES"
docker pull $imageName
if ($LASTEXITCODE -eq 0) { break }
}

或使用 Docker 镜像加速器配置。

注： 各种加速器都试了，效果都一般，除非科学手法，或者私信博主，可以把下载下来的给你。

问题 2：api_base URL 配置错误导致 404

现象：

{
"error": {
"message": "OpenAIException – 404 NOT_FOUND \\"No static resource v1/chat/completions/chat/completions.\\"",
"type": "invalid_request_error",
"code": "404"
}
}

原因：LiteLLM 在调用 OpenAI 兼容 API 时会自动追加 /chat/completions 路径。

错误配置：

DASHSCOPE_API_BASE=https://coding.dashscope.aliyuncs.com/v1/chat/completions

正确配置：

DASHSCOPE_API_BASE=https://coding.dashscope.aliyuncs.com/v1/chat/completions

关键词：LiteLLM 404 错误、LiteLLM api_base 配置、LiteLLM URL 配置错误

问题 3：custom_llm_provider 不支持自定义名称

现象：模型列表为空，日志显示：

Exception: Unsupported provider – aliCodingPlan
Error creating deployment: Unsupported provider – aliCodingPlan

原因：custom_llm_provider 必须是 LiteLLM 预定义的值，如 openai、azure、anthropic 等。

解决：将自定义名称改回 openai：

custom_llm_provider: openai # 不能改成其他值

关键词：LiteLLM 模型不显示、LiteLLM custom_llm_provider 错误、LiteLLM 模型列表为空

问题 4：配置修改后不生效（数据库缓存）

现象：修改了 config.yaml 或 .env 中的配置，但 LiteLLM 仍然使用旧的配置。

原因：LiteLLM 会将模型配置持久化到 PostgreSQL 数据库中，修改文件不会自动更新数据库。

解决：

# 停止服务并删除数据库卷（会清空所有数据）
docker-compose down -v

# 重新启动服务
docker-compose up -d

关键词：LiteLLM 配置不生效、LiteLLM 数据库缓存、LiteLLM 配置更新

问题 5：环境变量未正确传递

现象：日志中显示的 api_base 不是配置的地址。

原因：Docker Compose 的环境变量未正确传递，或使用了默认值。

排查：

# 查看容器内环境变量
docker-compose exec litellm-proxy env | grep DASHSCOPE

# 验证 docker-compose.yml 中的环境变量映射

解决：确保 docker-compose.yml 中正确引用了环境变量：

environment:
– DASHSCOPE_API_BASE=${DASHSCOPE_API_BASE:-https://default-url}

关键词：LiteLLM 环境变量、LiteLLM Docker Compose 配置、LiteLLM 变量传递

七、总结

通过本文的详细配置步骤，我们成功搭建了一个支持多模型的 LiteLLM API 网关，实现了：

✅ 统一接口：所有模型都通过 OpenAI 兼容的 /v1/chat/completions 接口访问

✅ 负载均衡：支持多 API Key 配置和流量权重分配

✅ 密钥管理：动态生成和管理访问密钥

✅ 监控日志：详细的调用日志和支出跟踪

相关资源：

  • LiteLLM 官方文档：https://docs.litellm.ai

  • 阿里云百炼：https://bailian.aliyun.com

  • GitHub 仓库：https://github.com/BerriAI/litellm

本文关键词：LiteLLM Docker 部署、LiteLLM 阿里云配置、LiteLLM 负载均衡、LiteLLM 故障排查、LiteLLM API 网关、LLM 代理服务器、阿里云百炼 API、LiteLLM 多模型管理

长尾关键词：LiteLLM 404 错误解决、LiteLLM 模型不显示、LiteLLM 数据库缓存清除、LiteLLM 环境变量配置、LiteLLM 国内部署

本文基于 LiteLLM v1.81.12 和阿里云百炼（Coding Plan）实测整理，如有问题欢迎在评论区交流。

赞(0)
未经允许不得转载：171主机测评 » LiteLLM 多模型 API 网关部署教程：负载均衡、密钥管理与故障排查
分享到： 更多 (0)
标签：

相关推荐

评论 抢沙发

取消

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

热门标签

#人工智能(60607)#python(20449)#开发语言(17114)#java(15696)#运维(15563)#linux(15120)#大数据(14763)#服务器(13222)#算法(11889)#前端(11103)#网络(9516)#ai(9206)#数据库(9039)#c++(8260)#学习(6895)#课程设计(6877)#机器学习(6789)#区块链(5960)#OpenClaw(5398)#后端(5233)#spring boot(5066)#深度学习(5010)#c语言(4411)#毕业设计(4322)#数据结构(4229)#安全(4209)#docker(3967)#架构(3950)#javascript(3855)#大模型(3721)

热门文章

最新文章

归档

分类