一、项目概述

LiteLLM 是由 BerriAI 开发的开源项目（MIT 协议，GitHub 已超过 28,000 星），核心使命是通过统一的 OpenAI 格式接口，接入 100+ 家 LLM 提供商，让开发者无需面对各厂商 API 的差异性，同时提供完整的企业级管控能力。

用一句话概括：LiteLLM = 统一 LLM 入口 + 智能路由 + 成本治理 + 可观测性。

生产用例包括 Netflix、Lemonade、Rocket Money 等企业。

---

二、核心架构：两大使用形态

2.1 Python SDK（嵌入式）

直接在应用代码中 pip install litellm，作为一个 Python 库运行在应用进程内。适合单体应用或快速原型。

from litellm import completion
import os

# 调用 OpenAI
response = completion(model="openai/gpt-4o",
    messages=[{"role": "user", "content": "你好"}])

# 调用 Anthropic Claude
response = completion(model="anthropic/claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "你好"}])

# 调用 Ollama 本地模型
response = completion(model="ollama/llama2",
    messages=[{"role": "user", "content": "你好"}],
    api_base="http://localhost:11434")

2.2 Proxy Server / LLM Gateway（独立网关）

以独立进程（HTTP 服务）方式运行，监听在 http://0.0.0.0:4000，所有客户端应用统一指向这个地址，LiteLLM Proxy 负责鉴权、路由、计费、日志。

应用层 (OpenAI SDK / 任意 HTTP 客户端)
       ↓ POST /v1/chat/completions
  LiteLLM Proxy (port 4000)
       ↓ 路由 / 负载均衡 / 计费
  [OpenAI] [Azure] [Qwen] [Ollama] [vLLM] ...

这是企业级部署的标准方式。LiteLLM Proxy 通常以容器（Docker、Kubernetes、AWS ECS/EKS 等）形式部署，使用 PostgreSQL 持久化配置（模型列表、密钥、预算、团队），可选用 Redis 实现分布式限速，前端可以加 Load Balancer 实现高可用。

---

三、SDK 与 Gateway 的核心区别

维度	Python SDK	LLM Gateway (Proxy)
运行位置	应用进程内	独立微服务
共享性	单应用使用	多应用共享同一入口
鉴权管理	各应用各自持有密钥	集中统一管理密钥，应用只拿 Virtual Key
计费追踪	单应用内	跨项目/团队/用户多维度追踪
适用场景	个人开发者、快速 POC	平台团队、多部门企业
运维负担	无额外服务	需维护 Proxy 服务本身
支持语言	Python	任何语言（HTTP REST）

选择 Gateway 可以得到：集中鉴权与授权、多租户成本追踪与预算管理、Virtual Key 访问控制、管理后台 UI；选择 SDK 适合直接嵌入 Python 代码库，含 Router 重试/fallback 逻辑、应用级负载均衡。

简单判断标准：团队里有多个业务方需要使用 LLM → 用 Gateway；个人项目或单一服务 → 用 SDK。

---

四、快速上手

4.1 安装与启动

# 安装
pip install 'litellm[proxy]'

# 最简启动（单模型）
litellm --model gpt-4o

# 或通过配置文件启动（推荐）
litellm --config litellm_config.yaml

4.2 配置文件结构（litellm_config.yaml）

model_list:
  - model_name: gpt-4o            # 对外暴露的模型名（客户端使用）
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

  - model_name: claude-3-5-sonnet
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: qwen-plus         # 通义千问（下面详细讲）
    litellm_params:
      model: openai/qwen-plus
      api_base: https://dashscope.aliyuncs.com/compatible-mode/v1
      api_key: os.environ/DASHSCOPE_API_KEY

router_settings:
  routing_strategy: latency-based-routing   # 路由策略

general_settings:
  master_key: sk-1234  # Admin 主密钥

4.3 Docker 部署（生产推荐）

# 拉取配置文件
curl -O https://raw.githubusercontent.com/BerriAI/litellm/main/docker-compose.yml

# 设置环境变量
echo 'LITELLM_MASTER_KEY="sk-your-master-key"' > .env
echo 'LITELLM_SALT_KEY="sk-random-hash"' >> .env
echo 'DATABASE_URL="postgresql://user:pass@host:5432/litellm"' >> .env

# 启动
docker compose up -d

也可以直接用 Docker run：

docker run \
  -v $(pwd)/litellm_config.yaml:/app/config.yaml \
  -e OPENAI_API_KEY="sk-xxx" \
  -e DATABASE_URL="postgresql://..." \
  -p 4000:4000 \
  docker.litellm.ai/berriai/litellm:main-latest \
  --config /app/config.yaml

4.4 客户端接入（任意语言）

启动后，客户端只需把 base_url 指向 Proxy：

import openai

client = openai.OpenAI(
    api_key="sk-your-virtual-key",   # LiteLLM Virtual Key
    base_url="http://localhost:4000"
)

response = client.chat.completions.create(
    model="gpt-4o",     # 对应 model_list 中的 model_name
    messages=[{"role": "user", "content": "你好"}]
)

JavaScript/TypeScript、curl、LangChain 等完全一样，换个 base_url 即可。

---

五、私有化部署的模型接入

这是 LiteLLM 的核心优势之一，支持所有本地/私有化模型。

5.1 Ollama（本地运行）

model_list:
  - model_name: llama3
    litellm_params:
      model: ollama/llama3
      api_base: http://localhost:11434

5.2 vLLM（高性能推理）

model_list:
  - model_name: my-llama
    litellm_params:
      model: openai/meta-llama/Meta-Llama-3-8B-Instruct
      api_base: http://vllm-server:8000/v1
      api_key: "none"  # vLLM 不需要 key

5.3 任意 OpenAI 兼容端点（最通用）

所有兼容 OpenAI 格式的私有部署（如本地部署的 Qwen、DeepSeek、百川等）都可以用 openai/ 前缀：

model_list:
  - model_name: private-deepseek
    litellm_params:
      model: openai/deepseek-chat
      api_base: http://your-private-server:8080/v1
      api_key: your-internal-key

5.4 Hugging Face TGI / SGLang / LMDeploy

model_list:
  - model_name: tgi-llama
    litellm_params:
      model: huggingface/meta-llama/Llama-3-8b-chat-hf
      api_base: http://tgi-server:8080

---

六、阿里云通义千问（Qwen）和通义万相配置

6.1 通义千问（Qwen Chat/文本）

阿里云百炼平台（DashScope）提供了 OpenAI 兼容接口，这是最简单的接入方式：

model_list:
  # 通义千问 Plus
  - model_name: qwen-plus
    litellm_params:
      model: openai/qwen-plus
      api_base: https://dashscope.aliyuncs.com/compatible-mode/v1
      api_key: os.environ/DASHSCOPE_API_KEY

  # 通义千问 Max（最强）
  - model_name: qwen-max
    litellm_params:
      model: openai/qwen-max
      api_base: https://dashscope.aliyuncs.com/compatible-mode/v1
      api_key: os.environ/DASHSCOPE_API_KEY

  # 通义千问 Turbo（快速低成本）
  - model_name: qwen-turbo
    litellm_params:
      model: openai/qwen-turbo
      api_base: https://dashscope.aliyuncs.com/compatible-mode/v1
      api_key: os.environ/DASHSCOPE_API_KEY

  # 本地私有化部署的 Qwen（vLLM 启动）
  - model_name: qwen-private
    litellm_params:
      model: openai/Qwen2.5-72B-Instruct
      api_base: http://your-vllm-server:8000/v1
      api_key: "none"

Python SDK 直接调用：

from litellm import completion
import os

os.environ["DASHSCOPE_API_KEY"] = "your-key"

response = completion(
    model="openai/qwen-plus",
    api_base="https://dashscope.aliyuncs.com/compatible-mode/v1",
    messages=[{"role": "user", "content": "你是谁？"}]
)

6.2 通义万相（图像生成）

通义万相目前的接入方式需要走 DashScope 原生 API（非 OpenAI 兼容），在 LiteLLM 里可以通过 custom_llm_provider 或直接用 OpenAI 格式的图像生成端点接入。

实际上最近 LiteLLM 社区已有 PR 合并了 DashScope 作为独立 provider（参考 PR #12361），因此你也可以用 dashscope/ 前缀：

model_list:
  # 文本模型走 dashscope provider
  - model_name: qwen-plus-native
    litellm_params:
      model: dashscope/qwen-plus
      api_key: os.environ/DASHSCOPE_API_KEY

  # 图像生成（通义万相）—— 走 OpenAI image generation 格式
  - model_name: wanx-image
    litellm_params:
      model: openai/wanx-v1
      api_base: https://dashscope.aliyuncs.com/compatible-mode/v1
      api_key: os.environ/DASHSCOPE_API_KEY

注意：通义万相的完整多模态能力（视频生成等）目前需要使用 DashScope 原生 SDK，LiteLLM 对其覆盖还在完善中。对于图文多模态，可用 qwen-vl-plus 等视觉模型通过标准接口接入。

---

七、企业前端集成方案

7.1 整体架构

前端应用 (React/Vue/Next.js)
    │
    ▼
企业 API 网关 (Nginx/Kong/APIG)
    │ Bearer Token 验证
    ▼
LiteLLM Proxy (Docker/K8s, port 4000)
    │ Virtual Key 路由
    ▼
各模型后端 (OpenAI / Qwen / 私有模型...)

旁路：
PostgreSQL (配置/计费) + Redis (限速) + Langfuse/Grafana (可观测)

7.2 Virtual Key 体系

LiteLLM 的 Virtual Key 是企业多租户管理的核心。管理员通过 API 为不同团队/项目创建独立密钥，设置各自的预算和权限：

# 创建一个给"前端团队"的 Virtual Key，月预算 $100
curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "max_budget": 100,
    "budget_duration": "monthly",
    "models": ["gpt-4o", "qwen-plus"],
    "metadata": {"team": "frontend", "project": "customer-chat"}
  }'

返回的 key（如 sk-frontend-xxxxx）就是前端调用时使用的密钥。

7.3 前端 JavaScript/TypeScript 集成示例

// utils/llm-client.ts
import OpenAI from "openai";

const llmClient = new OpenAI({
  apiKey: process.env.NEXT_PUBLIC_LITELLM_KEY,  // Virtual Key
  baseURL: process.env.NEXT_PUBLIC_LITELLM_URL, // LiteLLM Proxy URL
  dangerouslyAllowBrowser: true,  // 前端直调时需要
});

// 普通聊天
export async function chat(messages: any[]) {
  return llmClient.chat.completions.create({
    model: "gpt-4o",
    messages,
  });
}

// 流式输出（SSE）
export async function streamChat(messages: any[], onChunk: (text: string) => void) {
  const stream = await llmClient.chat.completions.create({
    model: "gpt-4o",
    messages,
    stream: true,
  });

  for await (const chunk of stream) {
    const text = chunk.choices[0]?.delta?.content || "";
    if (text) onChunk(text);
  }
}

7.4 企业安全最佳实践

不要把 Virtual Key 直接暴露给浏览器（即使是 Virtual Key 也应保护）。推荐架构：

浏览器 → 企业自有后端 (Next.js API Route / BFF) → LiteLLM Proxy

Next.js API Route 示例：

// pages/api/chat.ts
import { OpenAI } from "openai";
import { NextApiRequest, NextApiResponse } from "next";

const litellm = new OpenAI({
  apiKey: process.env.LITELLM_VIRTUAL_KEY,  // 服务端环境变量，不暴露
  baseURL: process.env.LITELLM_BASE_URL,
});

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // 这里可以加企业自己的用户鉴权
  const userId = req.headers["x-user-id"];

  const response = await litellm.chat.completions.create({
    model: "qwen-plus",
    messages: req.body.messages,
    // 传递 user 便于追踪
    user: userId as string,
  });

  res.json(response);
}

---

八、高级功能

8.1 负载均衡 & Fallback

model_list:
  - model_name: smart-gpt4
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_KEY_1

  - model_name: smart-gpt4
    litellm_params:
      model: azure/gpt-4o-deployment
      api_key: os.environ/AZURE_KEY
      api_base: https://your-azure.openai.azure.com/

router_settings:
  routing_strategy: latency-based-routing
  fallbacks:
    - {"smart-gpt4": ["qwen-plus"]}   # 主模型失败时切换到通义千问
  num_retries: 3
  retry_after: 5

8.2 预算与限速

general_settings:
  master_key: sk-master
  alerting:
    - slack
  alerting_thresholds:
    spend: 80  # 达到 80% 预算时告警

8.3 可观测性集成（Langfuse）

litellm_settings:
  success_callback:
    - langfuse
  failure_callback:
    - langfuse

environment_variables:
  LANGFUSE_PUBLIC_KEY: "pk-..."
  LANGFUSE_SECRET_KEY: "sk-..."
  LANGFUSE_HOST: "https://cloud.langfuse.com"

---

九、LiteLLM vs 竞品横向对比

	LiteLLM	OpenRouter	Helicone	Portkey	OneAPI
开源/自托管	✅ 完全开源	❌ SaaS only	✅ 开源可托管	✅ 部分开源	✅ 开源
模型数量	100+	500+	100+	100+	支持自定义
性能开销	~8ms P95	~25-40ms	~50ms	中等	低
企业功能	✅ 完整	有限	中等	✅ 完整	中等
数据驻留	✅ 完全自控	❌ 数据出境	可选	可选	✅ 自控
国内模型支持	较好	一般	一般	一般	✅ 专长
运维成本	中（需维护）	零	低	低	中
成本	免费/企业版付费	5% markup	免费基础	$49/月起	免费

---

十、LiteLLM 的优势与不足

优势

1. 真正的数据主权：完全自托管，数据不离开企业内网，满足金融、医疗、政府等合规要求。

2. 统一抽象层：LiteLLM 让平台团队轻松给开发者分配 LLM 访问权限，精准追踪团队用量，自动追踪 OpenAI/Azure/Bedrock/GCP 等各厂商的费用支出。

3. 强大的路由与容灾：支持基于延迟、成本、随机、轮询、加权等多种路由规则分发请求到多个后端，某个 provider 超速或失败时自动重试其他模型，支持超时、冷却期和请求排队。

4. 性能表现：LiteLLM P95 延迟在 1k RPS 下仅 8ms。

5. 生态完整：与 LangChain、LlamaIndex、Langfuse、OpenAI JS SDK、Anthropic SDK 等主流框架无缝集成。

不足与局限

1. 运维负担：LiteLLM 的自托管特性意味着团队需要负责扩容、监控和维护，这是它与 OpenRouter 等托管服务的核心差距。

2. 大规模下的性能问题：生产团队在高规模场景下越来越多地遭遇性能降级、内存泄漏和延迟增大等问题。（Go 语言写的竞品如 Bifrost、Helicone 在极高 RPS 下表现更好。）

3. 国内模型支持还在追赶：DashScope/通义万相的完整原生支持是近期才逐步完善的，部分多模态能力还需借道 OpenAI 兼容接口。

4. 配置复杂度：LiteLLM 需要 15-30 分钟的技术配置（包括 YAML 配置文件），复杂高级功能如自定义路由算法或分布式部署门槛更高。

5. 企业版功能收费：SSO、SCIM、OIDC/JWT、高级审计日志等功能需要购买 Enterprise License，核心开源功能免费但企业级治理能力需付费。

6. Python 语言绑定（SDK 层面）：Python SDK 只适合 Python 应用，其他语言只能走 Proxy HTTP，无法享受 SDK 的便捷性。

---

十一、未来展望

根据社区动态和行业趋势，LiteLLM 的发展方向包括：

A2A Protocol 支持：已在最新版本中添加了 A2A（Agent-to-Agent）协议客户端，为多 Agent 协作场景铺路，这与 Anthropic MCP 的生态走向高度一致。

更多国内 Provider 原生支持：DashScope（通义千问）、智谱 GLM、百度文心、字节豆包等国内模型的原生 provider 正在持续添加，而不仅依赖 OpenAI 兼容模式。

多模态全覆盖：语音、视频、图像生成等多模态路由的标准化，通义万相等图像/视频生成模型的完整支持是路线图方向。

性能优化：面对 Bifrost（Go 实现）等竞品的压力，LiteLLM 的高并发性能优化是重要课题。

Guardrails 与安全：内置 prompt injection 检测、PII 脱敏、内容安全过滤等企业安全特性。

---

总结：适合谁用 LiteLLM？

LiteLLM 是目前企业自托管 LLM 网关的最优选择之一，尤其适合：

• 数据合规要求严格（金融/医疗/政府）的企业
• 需要同时接入国内外多个模型提供商
• 平台团队需要为多个业务团队统一分发和管控 LLM 访问权
• 已有 OpenAI 格式的应用，想以最小改动切换或扩展到其他模型

不适合：团队没有运维能力、只需要快速接入 1-2 个模型的小型项目（用 OpenRouter 或直连 SDK 更简单）。