源码部署 LiteLLM

源码部署 LiteLLM Proxy

LiteLLM 是一个统一的 LLM 网关，支持 100+ 模型提供商，提供负载均衡、认证、缓存、限流等企业级功能。本文介绍如何从源码部署 LiteLLM Proxy。

适用场景：需要自定义修改 LiteLLM 源码、或在内网环境部署的场景。

部署时间：约 15-20 分钟

一、外部依赖

| 依赖 | 用途 | 配置示例 |

|------|------|

| PostgreSQL | 存储 API Key、用户、团队、预算等数据 |

| Redis | 多节点共享缓存、限流计数、冷却状态 |

二、环境要求

项目	要求
操作系统	Ubuntu 22.04 / 24.04
Python	3.10 - 3.13
CPU	4 vCPU+
内存	8 GB+
磁盘	20 GB+（日志会增长）

三、获取最新版本

1. 查看 Latest Tag

访问 GitHub Tags 获取最新稳定版本。

国内可通过 GitCode 镜像下载，无需翻墙：
复制代码
https://gitcode.com/GitHub_Trending/li/litellm

2. 克隆代码

bash 复制代码

mkdir -p /data
cd /data

# 方式一：GitCode 镜像（国内推荐）
git clone https://gitcode.com/GitHub_Trending/li/litellm.git
cd litellm

# 方式二：GitHub 原始仓库
git clone https://github.com/BerriAI/litellm.git
cd litellm

# 切换到最新 tag（示例：v1.88.0-rc.1）
git checkout v1.88.0-rc.1

四、安装依赖

1. 安装系统依赖

bash 复制代码

apt-get update
apt-get install -y curl wget git git-lfs ca-certificates \
    build-essential redis-tools postgresql-client

2. 安装 Miniconda

bash 复制代码

cd /tmp
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
bash miniconda.sh -b -p /root/miniconda3
rm -f miniconda.sh

# 初始化 conda
/root/miniconda3/bin/conda init
source ~/.bashrc

3. 创建 Python 环境

bash 复制代码

conda create -n litellm python=3.13 -y
conda activate litellm

# 自动激活
echo 'conda activate litellm' >> ~/.bashrc

4. 安装 Python 依赖

bash 复制代码

cd /data/litellm

# 国内使用清华源
pip install -e ".[proxy,extra_proxy]" \
    --prefer-binary \
    -i https://pypi.tuna.tsinghua.edu.cn/simple

五、配置文件

1. 环境变量 `.env`

创建 /data/litellm/.env：

ini 复制代码

# ===== 数据库 =====
# 注意：原密码123456%abc 中的 % 在 URL 里必须编码为 %25
DATABASE_URL=postgresql://litellm:<password>@**:5432/litellm

# ===== Redis =====
REDIS_HOST=**
REDIS_PORT=6379
REDIS_PASSWORD=<redis-password>

# ===== Proxy 配置 =====
LITELLM_MASTER_KEY=sk-your-master-key
LITELLM_LOG=INFO
STORE_MODEL_IN_DB=True

# ===== Admin UI =====
UI_USERNAME=admin
UI_PASSWORD=<ui-password>

# ===== 上游模型 API Key =====
OPENAI_API_KEY=sk-xxx
DEEPSEEK_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-xxx

收紧权限：

bash 复制代码

chmod 600 /data/litellm/.env

2. 配置文件 `config.yaml`

创建 /data/litellm/config.yaml：

yaml 复制代码

# =============================================================================
# litellm_settings - LiteLLM 核心设置
# =============================================================================
# 这些设置控制 LiteLLM 的核心行为，包括参数处理、日志、缓存、回调等
litellm_settings:

  # ---------------------------------------------------------------------------
  # drop_params: 是否自动丢弃模型不支持的参数
  # ---------------------------------------------------------------------------
  # 作用: 当请求包含目标模型不支持的参数时，自动移除而非报错
  # 场景: 不同模型支持的参数不同（如 response_format），开启后可兼容调用
  # 默认: false
  drop_params: true

  # ---------------------------------------------------------------------------
  # set_verbose: 是否启用详细日志
  # ---------------------------------------------------------------------------
  # 作用: 控制日志输出详细程度
  # 值: true (详细) / false (简洁)
  # 生产建议: false，避免日志过多
  set_verbose: false

  # ---------------------------------------------------------------------------
  # enable_redis_auth_cache: 是否将用户认证缓存共享到 Redis
  # ---------------------------------------------------------------------------
  # 作用: 多 worker/多节点部署时，共享 API Key 验证缓存
  # 场景: 不开启时，每个 worker 维护独立缓存，导致：
  #       - 缓存命中率低
  #       - 数据库查询量 = workers × hosts 倍
  # 依赖: Redis
  enable_redis_auth_cache: true

  # ---------------------------------------------------------------------------
  # callbacks: 自定义回调钩子列表
  # ---------------------------------------------------------------------------
  # 作用: 在请求生命周期的特定节点执行自定义逻辑
  # 场景:
  #   - consistent_hash_affinity_check: 基于 API Key 的一致性哈希路由
  #     同一 API Key 总是路由到同一 deployment，提高 backend prefill cache 命中率
  callbacks:
    - "litellm.proxy.hooks.consistent_hash_affinity_check.consistent_hash_affinity_check"

  # ---------------------------------------------------------------------------
  # cache: 是否启用缓存
  # ---------------------------------------------------------------------------
  # 作用: 缓存 LLM 响应，减少重复调用成本
  # 场景:
  #   - 相同请求直接返回缓存结果
  #   - 注意: chat completion 缓存可能导致空响应问题，建议仅缓存 embedding
  # 默认: false
  cache: true

  # ---------------------------------------------------------------------------
  # cache_params: 缓存详细配置
  # ---------------------------------------------------------------------------
  cache_params:
    type: redis                          # 缓存类型: redis / local / s3 / qdrant
    host: os.environ/REDIS_HOST          # Redis 主机
    port: os.environ/REDIS_PORT          # Redis 端口
    password: os.environ/REDIS_PASSWORD  # Redis 密码
    db: 0                                # Redis 数据库编号
    ttl: 86400                           # 缓存过期时间（秒），86400 = 1天
    supported_call_types: ["embedding", "aembedding"]  # 仅缓存 embedding，不缓存 chat

# =============================================================================
# router_settings - 路由设置
# =============================================================================
# 这些设置控制 LiteLLM Router 的行为，包括负载均衡、重试、冷却等
router_settings:

  # ---------------------------------------------------------------------------
  # redis_host / redis_port / redis_password: Redis 连接配置
  # ---------------------------------------------------------------------------
  # 作用: 多节点部署时共享 cooldown 状态、限流计数
  # 场景:
  #   - 单节点: 可不配置，状态存内存
  #   - 多节点: 必须配置，否则各节点状态独立
  redis_host: os.environ/REDIS_HOST
  redis_port: os.environ/REDIS_PORT
  redis_password: os.environ/REDIS_PASSWORD

  # ---------------------------------------------------------------------------
  # routing_strategy: 负载均衡策略
  # ---------------------------------------------------------------------------
  # 可选值:
  #   - simple-shuffle: 加权随机选择（默认）
  #   - usage-based-routing: TPM 使用量最低优先
  #   - usage-based-routing-v2: 速率限制感知 v2，推荐
  #   - latency-based-routing: 延迟最低优先
  #   - least-busy: 最空闲优先
  #   - cost-based-routing: 成本最低优先
  routing_strategy: usage-based-routing-v2

  # ---------------------------------------------------------------------------
  # enable_pre_call_checks: 是否启用调用前检查
  # ---------------------------------------------------------------------------
  # 作用: 请求前检查部署是否满足条件，不满足则过滤
  # 检查项:
  #   - 上下文窗口: input_tokens > max_input_tokens 时过滤该部署
  #   - 区域限制: region_name 不匹配时过滤
  # 场景: 避免请求发送到容量不足的部署
  enable_pre_call_checks: true

# =============================================================================
# general_settings - 通用设置
# =============================================================================
# 这些设置控制 Proxy Server 的基础行为
general_settings:

  # ---------------------------------------------------------------------------
  # master_key: 主密钥
  # ---------------------------------------------------------------------------
  # 作用: 管理员密钥，用于生成/管理 API Key
  # 格式: 必须以 "sk-" 开头
  # 权限: 拥有所有权限，可调用所有管理端点
  master_key: os.environ/LITELLM_MASTER_KEY

  # ---------------------------------------------------------------------------
  # database_url: 数据库连接 URL
  # ---------------------------------------------------------------------------
  # 作用: PostgreSQL 数据库连接，存储 API Key、用户、团队、预算等
  # 格式: postgresql://<user>:<password>@<host>:<port>/<database>
  # 注意: 密码中的特殊字符需 URL encode:
  #   - % → %25
  #   - # → %23
  database_url: os.environ/DATABASE_URL

  # ---------------------------------------------------------------------------
  # database_connection_pool_limit: 数据库连接池大小
  # ---------------------------------------------------------------------------
  # 作用: 每个 worker 进程的数据库连接池上限
  # 默认: 10
  # 建议: 根据 worker 数量和数据库连接上限调整
  database_connection_pool_limit: 10

  # ---------------------------------------------------------------------------
  # proxy_batch_write_at: 批量写入间隔
  # ---------------------------------------------------------------------------
  # 作用: 支出日志等数据批量写入数据库的间隔（秒）
  # 场景: 减少数据库写入频率，提高性能
  # 单位: 秒
  proxy_batch_write_at: 60

  # ---------------------------------------------------------------------------
  # allow_requests_on_db_unavailable: 数据库不可用时是否允许请求
  # ---------------------------------------------------------------------------
  # 作用: 数据库连接失败时，是否仍允许 LLM 请求通过
  # 场景:
  #   - true: 数据库抖动不影响线上服务（推荐生产环境）
  #   - false: 数据库不可用时拒绝所有请求
  allow_requests_on_db_unavailable: true

# =============================================================================
# 其他常用配置项
# =============================================================================

# ---------------------------------------------------------------------------
# model_list: 模型列表
# ---------------------------------------------------------------------------
# 作用: 定义 Proxy 支持的模型及其配置
# model_list:
#   - model_name: gpt-4o                    # 用户调用时使用的模型名
#     litellm_params:
#       model: openai/gpt-4o                # 实际模型
#       api_key: os.environ/OPENAI_API_KEY  # API Key
#       rpm: 1000                           # RPM 限制
#       tpm: 100000                         # TPM 限制
#       order: 1                            # 优先级（越小越高）
#       weight: 9                           # 权重
#     model_info:
#       max_input_tokens: 128000            # 上下文窗口
#       base_model: openai/gpt-4o           # 用于成本跟踪

# ---------------------------------------------------------------------------
# fallbacks: 通用回退配置
# ---------------------------------------------------------------------------
# litellm_settings:
#   fallbacks:
#     - gpt-4o: ["gpt-3.5-turbo", "claude-3-haiku"]  # gpt-4o 失败时回退

# ---------------------------------------------------------------------------
# context_window_fallbacks: 上下文超限回退
# ---------------------------------------------------------------------------
# litellm_settings:
#   context_window_fallbacks:
#     - gpt-4o: ["gpt-4o-32k"]  # 上下文超限时回退

# ---------------------------------------------------------------------------
# num_retries: 重试次数
# ---------------------------------------------------------------------------
# router_settings:
#   num_retries: 3          # 重试次数
#   retry_after: 5          # 重试间隔（秒）
#   allowed_fails: 3        # 允许失败次数
#   cooldown_time: 30       # 冷却时间（秒）

# ---------------------------------------------------------------------------
# environment_variables: 环境变量定义
# ---------------------------------------------------------------------------
# environment_variables:
#   REDIS_HOST: localhost
#   REDIS_PORT: 6379

六、初始化数据库

bash 复制代码

cd /data/litellm

# 加载环境变量
set -a; source .env; set +a

# 生成 Prisma Client
prisma generate --schema=./schema.prisma

# 执行数据库迁移
prisma migrate deploy --schema=./schema.prisma

七、启动服务

1. 创建启动脚本

创建 /data/litellm/start.sh：

bash 复制代码

#!/bin/bash
set -e

cd /data/litellm

# 加载环境变量
conda activate litellm

# 启动服务 num_workers <= cpu数量 
nohup litellm \
    --config config.yaml \
    --port 18001 \
    --num_workers 3 \
    > litellm.log 2>&1 &

echo $! > litellm.pid
echo "LiteLLM started. PID: $(cat litellm.pid)"

2. 启动

bash 复制代码

chmod +x /data/litellm/start.sh
bash /data/litellm/start.sh

参考链接

官方文档：https://docs.litellm.ai/
中文文档：https://docs.litellm.com.cn/
GitHub：https://github.com/BerriAI/litellm
GitCode 镜像：https://gitcode.com/GitHub_Trending/li/litellm

源码部署 LiteLLM

源码部署 LiteLLM Proxy

一、外部依赖

二、环境要求

三、获取最新版本

1. 查看 Latest Tag

2. 克隆代码

四、安装依赖

1. 安装系统依赖

2. 安装 Miniconda

3. 创建 Python 环境

4. 安装 Python 依赖

五、配置文件

1. 环境变量 .env

2. 配置文件 config.yaml

六、初始化数据库

七、启动服务

1. 创建启动脚本

2. 启动

参考链接

1. 环境变量 `.env`

2. 配置文件 `config.yaml`