LiteLLM 介绍与部署

[一、LiteLLM 相关概念](#一、LiteLLM 相关概念)

[1.1 LiteLLM 是什么](#1.1 LiteLLM 是什么)

[1.2 两个组成部分](#1.2 两个组成部分)

[1.3 它解决什么问题](#1.3 它解决什么问题)

[1.4 核心概念速查](#1.4 核心概念速查)

[1.5 工作原理示意](#1.5 工作原理示意)

[二、方式一：pip 安装（快速体验）](#二、方式一：pip 安装（快速体验）)

三、创建数据库

四、编写配置文件（可选）

[五、Docker 部署（推荐）](#五、Docker 部署（推荐）)

[步骤 1：创建工作目录](#步骤 1：创建工作目录)

[步骤 2：下载官方 QuickStart 编排文件](#步骤 2：下载官方 QuickStart 编排文件)

[步骤 3：生成环境变量文件 .env](#步骤 3：生成环境变量文件 .env)

[步骤 4：启动服务](#步骤 4：启动服务)

六、登录管理界面

[七、添加模型（以 DeepSeek 为例）](#七、添加模型（以 DeepSeek 为例）)

[步骤 1：进入添加模型页面](#步骤 1：进入添加模型页面)

[步骤 2：填写 API Key](#步骤 2：填写 API Key)

[步骤 3：测试连通性](#步骤 3：测试连通性)

[步骤 4：保存模型](#步骤 4：保存模型)

[步骤 5：（可选）在 LLM Credentials 中托管凭据](#步骤 5：（可选）在 LLM Credentials 中托管凭据)

八、创建虚拟密钥并调用测试

[步骤 1：生成 Virtual Key](#步骤 1：生成 Virtual Key)

[步骤 2：用 curl 调用测试](#步骤 2：用 curl 调用测试)

[步骤 3：在代码中调用（OpenAI SDK 兼容）](#步骤 3：在代码中调用（OpenAI SDK 兼容）)

九、常见问题排查

学习目标

理解 LiteLLM 是什么、能解决什么问题；
掌握 Master Key / Salt Key / Virtual Key 等核心概念；
学会用 pip 与 Docker 两种方式安装 LiteLLM；
能在 Web 管理界面中添加模型、测试连通性、创建虚拟密钥，并用代码调用。

实验环境

项目	要求
服务器	一台 Linux 服务器（示例 Ubuntu / CentOS），本机体验也可用 Windows + WSL
容器环境	Docker 20.10+ 与 Docker Compose v2
数据库	PostgreSQL（QuickStart 的 compose 文件已自带，无需单独安装）
网络	放行 4000 端口（LiteLLM 默认端口）
模型凭据	至少一个上游模型的 API Key（本教程以 DeepSeek 为例）

一、LiteLLM 相关概念

1.1 LiteLLM 是什么

LiteLLM 是由 BerriAI 开源的 LLM 网关（AI Gateway） ，核心理念是"用一套统一的 OpenAI 格式接口，调用所有大模型"。它把 OpenAI、Azure、Anthropic、Google Gemini、DeepSeek、通义千问、Ollama、vLLM 等 100+ 模型提供商统一到同一个调用规范下，应用代码不需要为每家厂商写不同的适配逻辑。

1.2 两个组成部分

组件	形态	用途
LiteLLM Python SDK	Python 库	在代码中直接调用，`litellm.completion()` 一个函数切换所有模型
LiteLLM Proxy Server（LLM AI Gateway）	独立服务	部署为网关，提供 OpenAI 兼容的 HTTP 接口和管理 UI，供多人/多项目共用，本教程的重点

1.3 它解决什么问题

统一入口：应用只记住一个网关地址、一套密钥，底层换模型不改代码；
密钥分管 ：管理员持有真实 API Key，给每个学生/项目发放独立的 Virtual Key，真实 Key 永不下发；
预算与限流：可按密钥/团队设置花费上限、速率限制，超额自动停用；
用量与审计：每次调用的模型、token 数、花费、归属用户都有记录；
高可用路由：同一模型可配多个上游 Key 做负载均衡，故障自动重试/切换（fallback）。

1.4 核心概念速查

概念	说明
Master Key （`LITELLM_MASTER_KEY`）	管理员密钥，`sk-` 开头，权限最高；既是管理 API 的凭据，也是 Web UI 的登录密码，务必保密
Salt Key （`LITELLM_SALT_KEY`）	加盐加密密钥，用于加密保存在数据库中的上游凭据；一旦更换，已存凭据将无法解密
Virtual Key	网关对外发放的 `sk-` 虚拟密钥，可绑定预算、有效期、可用模型范围；调用计费与追踪都挂在它名下
Model Management	模型管理：添加模型并起一个对外名称（`model_name`），调用方只看得到这个名称
LLM Credentials	上游提供商凭据（真实 API Key），在 UI 中统一托管、加密存储、可复用
Team / User / Budget	多租户体系：把密钥归属到团队与用户，按团队控预算
PostgreSQL 数据库	持久化上述所有数据（密钥、模型、用量日志）；不用数据库则密钥等配置重启即失

1.5 工作原理示意

复制代码

学生应用/项目                LiteLLM 网关                      上游模型
─────────────        ─────────────────────────       ─────────────────
  调用请求  ──Bearer──▶  校验 Virtual Key        ──▶   DeepSeek
  (OpenAI格式)          检查预算/限流/权限              OpenAI
                        记录用量与花费    ──真实Key──▶  Claude / Gemini
                        返回统一格式结果                 Ollama / vLLM ...

管理入口：部署后浏览器访问 http://服务器IP:4000/ui 进入管理界面。

二、方式一：pip 安装（快速体验）

适合本机体验 SDK 或临时起一个单用户代理；多人共用、需要密钥管理时请用第三节的 Docker 部署。

复制代码

pip install "litellm[proxy]" -i https://pypi.tuna.tsinghua.edu.cn/simple/

说明：

litellm[proxy] 表示安装 litellm 及其代理服务所需的额外依赖（FastAPI、UVicorn 等）；
-i 指定清华镜像源，国内下载更快。

验证安装：

复制代码

litellm --version

三、创建数据库

LiteLLM 代理需要 PostgreSQL 数据库来保存虚拟密钥、模型配置和用量记录，数据库名使用 litellm。

方式 A：QuickStart 自带数据库（推荐） 。第四节的 docker-compose.quickstart.yml 已经内置 PostgreSQL 服务，会自动创建名为 litellm 的数据库，无需手动操作。

方式 B：使用已有的外部 PostgreSQL，手动创建数据库：

复制代码

sudo -u postgres psql

复制代码

CREATE DATABASE litellm;
\l        -- 查看数据库列表，确认 litellm 已创建
\q        -- 退出

也可以使用 pgAdmin、Navicat 等图形工具：右键 Databases → Create → Database，名称填 litellm。

四、编写配置文件（可选）

通过 Web UI 添加的模型会自动保存到数据库中，不写配置文件也能用 。如果希望用文件方式统一管理（便于版本化、批量部署），可编写 litellm_config.yaml：

复制代码

model_list:
  - model_name: deepseek-v4-pro            # 对外模型名（调用时 model= 的值）
    litellm_params:
      model: deepseek/deepseek-v4-pro      # 实际路由：提供商/模型名
      api_key: os.environ/DEEPSEEK_API_KEY
  - model_name: deepseek-v4-flash
    litellm_params:
      model: deepseek/deepseek-v4-flash
      api_key: os.environ/DEEPSEEK_API_KEY

litellm_settings:
  drop_params: true                        # 自动忽略上游不支持的参数

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

文件方式需把配置挂载进容器并在启动参数中指定 --config /app/config.yaml。本教程后续采用 UI 方式添加模型，此文件仅作了解。

五、Docker 部署（推荐）

步骤 1：创建工作目录

复制代码

sudo mkdir -p /opt/lite
cd /opt/lite

步骤 2：下载官方 QuickStart 编排文件

复制代码

curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml
ls

该文件包含两个服务：litellm（网关本体）和 db（PostgreSQL 16，自动建库 litellm）。

国内服务器下载 GitHub 文件较慢时，可在链接前加代理前缀（如 https://ghproxy.com/），或本地下载后上传服务器。

步骤 3：生成环境变量文件 .env

复制代码

printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
cat .env

命令解读：

openssl rand -hex 32：随机生成 64 位十六进制字符串；
LITELLM_MASTER_KEY：管理员密钥（UI 登录密码），请立即复制保存到安全的地方；
LITELLM_SALT_KEY：凭据加密盐。重新生成会使数据库中已保存的上游 API Key 全部无法解密，务必妥善保管。

步骤 4：启动服务

复制代码

docker compose -f docker-compose.quickstart.yml up -d

验证运行状态：

复制代码

docker compose -f docker-compose.quickstart.yml ps     # 两个服务应为 running / healthy
docker compose -f docker-compose.quickstart.yml logs -f litellm   # 看到启动完成日志后 Ctrl+C 退出
curl http://127.0.0.1:4000/health/liveliness            # 返回 I'm alive! 即服务正常

六、登录管理界面

浏览器访问（IP 换成你的服务器地址）：

复制代码

http://211.90.XXX.XX:4000/ui

登录方式：用户名 admin ，密码为 .env 中的 LITELLM_MASTER_KEY （cat /opt/lite/.env 查看）。

登录后默认进入 Virtual Keys（虚拟密钥） 页面。此时顶部若出现红色横幅，提示内容为：当前使用的是"引导共享账号"（任何拿到 Master Key 的人都能以此身份登录），建议先创建一个带个人密码的正式管理员账号，再关闭该登录通道。实验室环境下可先忽略，生产环境务必按提示处理。

左侧菜单常用项：

菜单	用途
Virtual Keys	创建、管理虚拟密钥，查看每个密钥的花费
Models + Endpoints	模型管理与连通性测试（本教程第八节）
Logs	调用日志：模型、token 数、花费
Budgets / Teams	预算与团队管理

七、添加模型（以 DeepSeek 为例）

前提：已准备好 DeepSeek 的 API Key（platform.deepseek.com 申请）。

步骤 1：进入添加模型页面

左侧菜单点击 Models + Endpoints ，再点击顶部的 Add Model 标签页。

按图中标注依次操作：

左侧菜单选择 Models + Endpoints；
顶部点击 Add Model 标签页；
Provider 下拉框选择 Deepseek；
LiteLLM Model Name 填写对外模型名，如 deepseek-v4-pro（也可点 Select model 从列表选择，同法可再添加一个 deepseek-v4-flash）。

下方的 Model Mappings 会自动显示映射关系：左侧为对外名称，右侧为 LiteLLM 实际发送给上游 API 的模型名，保持默认即可。Mode 选择 chat（对话模型）。

步骤 2：填写 API Key

在 API Key 输入框中粘贴 DeepSeek 的 API Key。

也可以不直接填 Key，而是先到 LLM Credentials 页签集中创建凭据（见步骤 5），再在此处的 Existing Credentials 中选择。

步骤 3：测试连通性

点击右下角 Test Call 按钮（上图红圈处），等待测试结果。

弹出 Connection Test Results 对话框，显示 Connection to deepseek-v4-flash, deepseek-v4-pro successful 即为成功；若失败，请检查 API Key 是否正确、服务器是否能访问外网。

步骤 4：保存模型

点击 Add Model 按钮保存。保存后可在 All Models 页签看到已添加的模型：

列表中可以看到 deepseek-v4-flash 与 deepseek-v4-pro 两个模型，及其提供商、健康状态和费用信息。

步骤 5：（可选）在 LLM Credentials 中托管凭据

切换到 LLM Credentials 页签，可集中管理各提供商的 API Key，供添加模型时复用。点击右上角 Add Credential 可新增凭据（选择 Provider、命名、粘贴 Key）。

八、创建虚拟密钥并调用测试

步骤 1：生成 Virtual Key

回到 Virtual Keys 页面，点击 Create New Key ，按需设置名称、可用模型、预算上限、有效期后创建，得到一个 sk- 开头的虚拟密钥。复制保存，只显示一次。

步骤 2：用 curl 调用测试

复制代码

curl -X POST http://211.90.XXX.XX:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的虚拟密钥" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好，请用一句话介绍你自己"}]
  }'

返回 JSON 中出现 choices[0].message.content 的回答内容即部署成功。Virtual Keys 页面中该密钥的 Spend 列也会同步记录花费。

步骤 3：在代码中调用（OpenAI SDK 兼容）

复制代码

from openai import OpenAI

client = OpenAI(
    base_url="http://211.90.XXX.XX:4000/v1",   # 指向 LiteLLM 网关
    api_key="sk-你的虚拟密钥"                    # 网关发放的 Virtual Key
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",                  # 添加模型时起的对外名称
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

九、常见问题排查

现象	排查方向
浏览器无法访问 UI	服务器防火墙/云安全组是否放行 4000 端口；`docker compose ps` 确认容器在运行
登录被拒	用户名固定为 `admin`，密码是 `LITELLM_MASTER_KEY`（`cat /opt/lite/.env`），注意不要多余空格
Test Call 失败	上游 API Key 是否有效、账户是否有余额；服务器能否访问上游 API（`curl` 上游地址测试）
调用返回 401	用的是不是 Virtual Key / Master Key；`Authorization: Bearer` 是否完整
调用返回模型不存在	`model` 参数与添加模型时的 LiteLLM Model Name 不一致
更换 `.env` 后已有模型凭据报错	更换了 `LITELLM_SALT_KEY` 导致数据库中旧凭据无法解密，需删除凭据重新录入；Salt Key 不可随意更换
数据库连不上	`docker compose logs db` 查看 PostgreSQL 状态，等待其 healthy 后重启 litellm

动手练习

再添加一个其他提供商的模型（如通义千问或本地 Ollama 模型），并用 Test Call 验证；
创建一个预算上限为 1 美元的 Virtual Key，反复调用观察 Budgets 中的花费统计；
用两台"服务器"（或本机不同端口）模拟：一台当 LiteLLM 网关，一台当应用方，只允许应用方持有 Virtual Key。