# https://github.com/BerriAI/litellm 项目说明书
生成时间：2026-05-31 04:18:10 UTC
## 目录
- [LiteLLM 概述](#overview)
- [快速入门指南](#quickstart)
- [系统架构](#system_architecture)
- [LLM 提供商集成](#llm_providers)
- [代理服务器详解](#proxy_server)
- [管理控制台](#admin_ui)
- [路由策略](#router_strategies)
- [缓存系统](#caching_system)
- [安全护栏](#guardrails)
- [MCP 集成](#mcp_integration)
## LiteLLM 概述
### 相关页面
相关主题：[快速入门指南](#quickstart), [系统架构](#system_architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/BerriAI/litellm/blob/main/README.md)
- [litellm/proxy/enterprise/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/enterprise/README.md)
- [litellm/integrations/dotprompt/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/integrations/dotprompt/README.md)
- [litellm/proxy/client/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/client/README.md)
- [scripts/health_check/health_check_client_README.md](https://github.com/BerriAI/litellm/blob/main/scripts/health_check/health_check_client_README.md)
- [terraform/litellm/README.md](https://github.com/BerriAI/litellm/blob/main/terraform/litellm/README.md)
# LiteLLM 概述
LiteLLM 是一个统一的 LLM（大型语言模型）调用库，通过标准化的 OpenAI API 格式，提供对 100+ 大语言模型的无缝接入能力。该项目旨在简化多模型切换、成本追踪、负载均衡等复杂场景下的 LLM 集成工作。
## 核心定位
LiteLLM 的核心价值在于**抽象化底层差异**。不同模型提供商（OpenAI、Azure、Hugging Face、Anthropic 等）在 API 规范、认证方式、响应格式等方面存在显著差异。LiteLLM 通过统一的接口层，让开发者可以使用完全相同的代码逻辑调用任意支持的模型。
```mermaid
graph LR
A[应用代码] --> B[LiteLLM 统一接口]
B --> C[OpenAI]
B --> D[Azure OpenAI]
B --> E[Anthropic]
B --> F[Google Gemini]
B --> G[100+ 更多模型]
```
资料来源：[litellm/proxy/enterprise/README.md:1-4]()
## 核心功能模块
LiteLLM 包含多个功能模块，覆盖从简单调用到企业级代理的完整场景：
| 模块 | 说明 | 主要用途 |
|------|------|----------|
| `litellm.completion()` | 统一聊天补全接口 | 对话生成、文本完成 |
| `litellm.embedding()` | 统一嵌入接口 | 向量检索、语义搜索 |
| `litellm. acompletion()` | 异步聊天补全 | 高并发场景 |
| `litellm.image_generation()` | 图像生成 | DALL-E 等模型 |
| `litellm.transcription()` | 语音转文本 | 音频处理 |
资料来源：[README.md:1-10]()
## 代理服务器架构
LiteLLM Proxy 是企业级部署的核心组件，提供完整的 API 网关功能：
```mermaid
graph TD
A[客户端请求] --> B[LiteLLM Proxy
:4000]
B --> C[数据平面
/v1/chat/completions
/v1/embeddings]
B --> D[管理平面
/key/*
/user/*
/team/*]
C --> E[LLM 提供商]
D --> F[Prisma 数据库]
B --> G[LiteLLM UI
:3000]
```
资料来源：[terraform/litellm/README.md:1-15]()
### 部署架构
LiteLLM 支持多种部署模式：
| 部署方式 | 端口 | 说明 |
|----------|------|------|
| `litellm/main` | 4000 | LLM 数据平面 |
| `litellm-backend` | 4001 | 管理 API |
| `litellm-ui` | 3000 | Next.js 管理界面 |
资料来源：[terraform/litellm/README.md:5-10]()
## 企业级功能
LiteLLM 提供丰富的企业特性，覆盖关键管理和安全需求：
### 提示词管理
LiteLLM 支持外部提示词管理系统，允许将提示词模板存储在版本控制系统中：
- **GitLab 集成**：支持从 GitLab 仓库获取 `.prompt` 文件
- **BitBucket 集成**：支持从 BitBucket 仓库获取提示词
- **dotprompt 格式**：使用 YAML 前置元数据和 Handlebars 模板语法
```yaml
---
model: gpt-4
temperature: 0.7
max_tokens: 500
input:
schema:
user_message: string
system_context?: string
---
System: You are a helpful {{role}} assistant.
User: {{user_message}}
```
资料来源：[litellm/integrations/dotprompt/README.md:1-30]()
### Guardrails 安全防护
LiteLLM 提供完整的内容安全审核能力：
| 组件 | 功能 |
|------|------|
| Azure Text Moderation | 文本内容分类审核 |
| PII 脱敏 | 自动识别和遮蔽敏感信息 |
| 输出过滤 | 对 LLM 生成内容进行审查 |
资料来源：[ui/litellm-dashboard/src/components/guardrails/README.md:1-20]()
### 密钥与用户管理
LiteLLM Proxy 提供完整的 API 密钥管理和用户控制系统：
- API 密钥生成与轮换
- 基于团队的资源隔离
- 支出限额与使用追踪
- 细粒度的访问控制
资料来源：[litellm/proxy/enterprise/README.md:1-8]()
## Python 客户端
LiteLLM 提供类型安全的 Python 客户端库，简化与代理服务器的交互：
```python
from litellm.proxy.client import Client
client = Client(
base_url="http://localhost:4000",
api_key="sk-api-key"
)
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[
{"role": "user", "content": "Hello, how are you?"}
]
)
```
客户端支持的功能模块包括：
| 资源 | 功能 |
|------|------|
| `client.chat` | 聊天补全 |
| `client.models` | 模型管理 |
| `client.model_groups` | 模型组管理 |
| `client.keys` | API 密钥管理 |
| `client.credentials` | 凭证管理 |
| `client.users` | 用户管理 |
资料来源：[litellm/proxy/client/README.md:1-40]()
## 健康检查与监控
LiteLLM 提供独立的健康检查客户端，用于验证部署状态：
```bash
export LITELLM_BASE_URL="https://litellm.example.com"
export LITELLM_API_KEY="your-api-key"
python scripts/health_check/health_check_client.py
```
功能特性：
- 自动从 YAML 配置或代理 API 获取模型列表
- 智能模式检测（嵌入模型 vs 聊天模型）
- 并发测试所有配置的模型
- Docker 容器化部署支持
资料来源：[scripts/health_check/health_check_client_README.md:1-25]()
## 快速开始
### 基础调用
```python
import litellm
# OpenAI 模型
response = litellm.completion(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "Hello!"}]
)
# 切换到其他模型
response = litellm.completion(
model="claude-3-opus-20240229",
messages=[{"role": "user", "content": "Hello!"}]
)
```
### 代理部署配置
```yaml
model_list:
- model_name: gpt-3.5-turbo
litellm_params:
model: openai/gpt-3.5-turbo
api_key: os.environ/OPENAI_API_KEY
litellm_settings:
drop_params: true
set_verbose: true
```
启动代理：
```bash
litellm --config config.yaml
```
## 社区关注的问题
### 安全事件回顾
**PyPI 包安全问题（2024年）**
2024 年发生的 PyPI 包供应链攻击事件（影响 v1.82.7 和 v1.82.8）提醒用户：
- 始终验证 Docker 镜像签名
- 使用 `cosign` 验证镜像完整性
- 推荐使用固定提交哈希方式验证
资料来源：[社区安全公告](https://github.com/BerriAI/litellm/issues/24518)
### 功能请求热点
社区讨论较多的功能改进方向：
| 功能 | 状态 | 说明 |
|------|------|------|
| 深色模式 UI | 待实现 | Issue #10177，51 个评论 |
| 导入速度优化 | 待优化 | Issue #7605，导入耗时约 1 秒 |
| FunASR 音频转录 | 功能请求 | Issue #29367 |
### 已知问题
| 问题 | 影响版本 | 说明 |
|------|----------|------|
| Gemini 缓存请求丢失 tool_choice | 多个版本 | Issue #29088 |
| Windows Prisma 查询引擎崩溃 | 1.82.x / 1.83.0 | Issue #25260 |
| UI 邮箱设置无法保存 | 多个版本 | Issue #19221 |
## 版本发布
LiteLLM 采用语义化版本号，持续迭代发布：
| 版本类型 | 说明 |
|----------|------|
| `v1.x.y` | 稳定版本 |
| `v1.x.y-rc.n` | 发布候选版本 |
| `v1.x.y-dev.n` | 开发预览版本 |
所有 Docker 镜像使用 `cosign` 签名，推荐使用固定提交哈希验证：
```bash
cosign verify --certificate-identity-repository ghcr.io/berriai/litellm \
ghcr.io/berriai/litellm:v1.x.x
```
## 技术架构要点
### 模块化设计
LiteLLM 采用高度模块化的架构：
```
litellm/
├── llms/ # 各模型提供者实现
│ ├── openai/ # OpenAI 系列
│ ├── anthropic/ # Anthropic 系列
│ ├── cohere/ # Cohere 系列
│ └── ...
├── proxy/ # 代理服务器
│ ├── _new/ # 新版 API
│ ├── auth/ # 认证模块
│ ├── management_endpoints/ # 管理接口
│ └── enterprise/ # 企业功能
├── integrations/ # 第三方集成
│ ├── gitlab/ # GitLab 提示词管理
│ ├── bitbucket/ # BitBucket 提示词管理
│ ├── dotprompt/ # dotprompt 格式支持
│ └── arize/ # Arize Phoenix 集成
└── ui/ # Web 管理界面
```
### 扩展机制
LiteLLM 支持通过提示词管理 API 扩展：
开发者可以实现自己的提示词管理服务器，只需实现以下端点：
| 端点 | 方法 | 说明 |
|------|------|------|
| `/beta/litellm_prompt_management` | GET | 获取提示词 |
| `/prompts` | GET | 列出所有提示词 |
| `/prompts/{id}/variables` | GET | 获取变量列表 |
资料来源：[cookbook/mock_prompt_management_server/README.md:1-20]()
## 总结
LiteLLM 是一个功能全面的 LLM 集成解决方案，其核心优势包括：
- **统一接口**：通过标准化 OpenAI API 格式调用 100+ 模型
- **灵活部署**：支持从简单脚本到企业级代理的多种部署模式
- **安全合规**：内置 Guardrails 内容审核和密钥管理
- **扩展性强**：支持自定义提示词管理和第三方集成
- **社区活跃**：持续迭代，积极响应安全和功能需求
---
## 快速入门指南
### 相关页面
相关主题：[LiteLLM 概述](#overview), [代理服务器详解](#proxy_server)
相关源码文件
以下源码文件用于生成本页说明：
- [litellm/main.py](https://github.com/BerriAI/litellm/blob/main/litellm/main.py)
- [litellm/proxy/proxy_cli.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/proxy_cli.py)
- [.env.example](https://github.com/BerriAI/litellm/blob/main/.env.example)
- [litellm/integrations/gitlab/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/integrations/gitlab/README.md)
- [litellm/integrations/bitbucket/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/integrations/bitbucket/README.md)
- [litellm/integrations/dotprompt/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/integrations/dotprompt/README.md)
# 快速入门指南
LiteLLM 是一个统一接口库，用于调用 100+ 大语言模型（LLM），包括 OpenAI、Anthropic、Google Vertex AI、Azure、Hugging Face 等提供商。本指南将帮助您快速上手 LiteLLM 的核心功能。
## 安装
### 基本安装
```bash
pip install litellm
```
### 完整安装（含代理依赖）
```bash
pip install litellm[proxy] prisma
```
### Docker 部署
LiteLLM 提供官方 Docker 镜像，支持容器化部署：
```bash
# 标准镜像
docker pull ghcr.io/berriai/litellm:main
# 非 root 用户镜像
docker pull ghcr.io/berriai/litellm-non_root:v1.86.0
```
所有 Docker 镜像均使用 cosign 进行签名验证，签名密钥基于 commit `0112e53`。资料来源：[v1.86.0 Release Notes](https://github.com/BerriAI/litellm/releases/tag/v1.86.0)
## 环境配置
### 环境变量配置
创建 `.env` 文件，配置您的 API 密钥：
```bash
# OpenAI
OPENAI_API_KEY=sk-xxxx
# Anthropic
ANTHROPIC_API_KEY=sk-ant-xxxx
# Azure OpenAI
AZURE_API_KEY=xxxx
AZURE_API_BASE=https://xxx.openai.azure.com
AZURE_API_VERSION=2023-05-15
# Google Vertex AI
VERTEX_PROJECT=your-project
VERTEX_LOCATION=us-central1
```
资料来源：[.env.example](https://github.com/BerriAI/litellm/blob/main/.env.example)
### 代理配置（config.yaml）
LiteLLM 支持通过 YAML 文件配置代理服务器：
```yaml
model_list:
- model_name: gpt-4
litellm_params:
model: gpt-4
api_key: os.environ/AZURE_API_KEY
api_base: os.environ/AZURE_API_BASE
- model_name: claude-3
litellm_params:
model: anthropic/claude-3-5-sonnet-20241022
api_key: os.environ/ANTHROPIC_API_KEY
litellm_settings:
drop_params: true
set_verbose: true
```
## 基础 API 调用
### completion - 文本补全
```python
import litellm
# OpenAI 格式调用
response = litellm.completion(
model="gpt-4",
messages=[
{"role": "system", "content": "你是一个有帮助的助手"},
{"role": "user", "content": "你好，请介绍一下自己"}
]
)
print(response.choices[0].message.content)
```
### 支持的模型提供商
LiteLLM 支持多种模型提供商的统一调用：
| 提供商 | 模型格式 | 认证方式 |
|--------|----------|----------|
| OpenAI | `gpt-4`, `gpt-3.5-turbo` | API Key |
| Anthropic | `anthropic/claude-3-5-sonnet-20241022` | API Key |
| Azure | `azure/gpt-4` | API Key + Endpoint |
| Google Vertex | `vertex_ai/gemini-pro` | Service Account |
| Hugging Face | `huggingface/mistral-7b-instruct` | API Key |
| AWS Bedrock | `bedrock/anthropic.claude-3-v1` | AWS Credentials |
### 多模态支持
```python
# 图片理解
response = litellm.completion(
model="gpt-4-vision-preview",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么？"},
{
"type": "image_url",
"image_url": {"url": "https://example.com/image.jpg"}
}
]
}
]
)
```
### 流式输出
```python
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "讲一个关于AI的笑话"}],
stream=True
)
for chunk in response:
print(chunk.choices[0].delta.content or "", end="")
```
### embedding - 文本嵌入
```python
response = litellm.embedding(
model="text-embedding-ada-002",
input=["Hello world", "How are you?"]
)
print(response.data[0].embedding)
```
### audio/transcriptions - 语音转文字
LiteLLM 支持 `/audio/transcriptions` 端点，兼容 OpenAI 格式：
```python
response = litellm.audio.transcriptions(
model="whisper-1",
file=open("audio.mp3", "rb")
)
print(response.text)
```
社区建议：FunASR 作为自托管语音转文字提供商的功能请求正在进行中（Issue #29367）。
## 提示词管理
LiteLLM 支持从外部仓库管理提示词模板，支持 GitLab、BitBucket 等平台。
### .prompt 文件格式
```yaml
---
model: gpt-4
temperature: 0.7
max_tokens: 500
input:
schema:
user_message: string
system_context?: string
---
{% if system_context %}System: {{system_context}}
{% endif %}User: {{user_message}}
```
### GitLab 集成
```python
import litellm
# 配置 GitLab 访问
gitlab_config = {
"workspace": "your-workspace",
"repository": "your-repo",
"access_token": "your-access-token",
"branch": "main",
"base_url": "https://gitlab.com/api/v4"
}
litellm.set_global_gitlab_config(gitlab_config)
# 使用提示词
response = litellm.completion(
model="gitlab/gpt-4",
prompt_id="chat_assistant",
prompt_variables={"user_message": "你好"}
)
```
### BitBucket 集成
```python
import litellm
bitbucket_config = {
"workspace": "your-workspace",
"repository": "your-repo",
"access_token": "your-access-token",
"branch": "main"
}
litellm.set_global_bitbucket_config(bitbucket_config)
response = litellm.completion(
model="bitbucket/gpt-4",
prompt_id="chat_assistant",
prompt_variables={"user_message": "你好"}
)
```
### dotprompt 本地管理
```python
from litellm.integrations.dotprompt import get_dotprompt_manager
manager = get_dotprompt_manager()
# 列出所有提示词
print(manager.prompt_manager.list_prompts())
# 渲染提示词
rendered = manager.prompt_manager.render(
"my_prompt",
{"domain": "machine learning", "task": "分类任务"}
)
```
资料来源：[litellm/integrations/dotprompt/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/integrations/dotprompt/README.md)
## LiteLLM 代理服务器
LiteLLM 代理服务器提供统一的 API 网关，支持密钥管理、负载均衡、计费等企业功能。
### 启动代理
```bash
litellm --config config.yaml --port 4000
```
### Docker 启动代理
```bash
docker run \
-v $(pwd)/config.yaml:/app/config.yaml \
-e DATABASE_URL="postgresql://user:pass@host:5432/db" \
-p 4000:4000 \
ghcr.io/berriai/litellm:main
```
### CLI 认证
LiteLLM 支持 SSO 认证流程：
```mermaid
sequenceDiagram
participant CLI as CLI
participant Browser as Browser
participant Proxy as LiteLLM Proxy
participant SSO as SSO Provider
CLI->>Proxy: POST /sso/cli/start
Proxy->>CLI: Return login_id, poll_secret
CLI->>Browser: Open auth URL
Browser->>Proxy: User authenticates via SSO
Proxy->>CLI: Generate session token
```
### 代理 API 端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/chat/completions` | POST | 聊天补全 |
| `/completions` | POST | 文本补全 |
| `/embeddings` | POST | 文本嵌入 |
| `/audio/transcriptions` | POST | 语音转文字 |
| `/rerank` | POST | 文档重排序 |
| `/v1/model/info` | GET | 模型信息 |
## Guardrails（内容安全）
LiteLLM 支持在请求和响应中应用内容安全检查。
### 支持的调用类型
- `CallTypes.completion` - 同步补全
- `CallTypes.acompletion` - 异步补全
- `CallTypes.rerank` - 文档重排序
- `CallTypes.arerank` - 异步重排序
### Guardrail 配置示例
```python
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "用户消息"}],
guardrails=["content_moderation"]
)
```
### Cohere Rerank Guardrail
```python
response = litellm.rerank(
model="cohere/rerank-english-v2.0",
query="搜索查询",
documents=[
{"text": "文档1", "metadata": {"source": "wiki"}},
{"text": "文档2", "metadata": {"source": "docs"}}
],
guardrails=["content_moderation"]
)
```
资料来源：[litellm/llms/cohere/rerank/guardrail_translation/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/llms/cohere/rerank/guardrail_translation/README.md)
## 技能系统（Skills）
LiteLLM 支持通过 ZIP 包发布和安装技能。
### 技能 ZIP 格式
```
my-skill.zip
└── my-skill/
└── SKILL.md
```
### SKILL.md 格式
```markdown
---
name: my-skill
description: 技能描述
---
# My Skill
技能使用说明...
## 使用场景
- 示例 1
- 示例 2
```
### 技能操作
```python
from litellm.llms.litellm_proxy.skills import LiteLLMSkillsHandler
handler = LiteLLMSkillsHandler()
# 创建技能
skill = await handler.create_skill(
data=NewSkillRequest(
display_title="My Skill",
description="技能描述",
instructions="使用说明...",
file_content=zip_bytes,
file_name="my-skill.zip",
file_type="application/zip"
),
user_id="user_123"
)
# 列出技能
skills = await handler.list_skills(limit=10, offset=0)
# 获取技能
skill = await handler.get_skill(skill_id="skill_abc123")
# 删除技能
await handler.delete_skill(skill_id="skill_abc123")
```
资料来源：[litellm/llms/litellm_proxy/skills/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/llms/litellm_proxy/skills/README.md)
## 常见问题与已知问题
### 导入性能
LiteLLM 完整导入可能需要约 1 秒，这是社区关注的性能问题（Issue #7605）。如需优化导入速度，建议使用按需导入：
```python
# 仅导入需要的模块
from litellm import completion
```
### Gemini 缓存与 tool_choice
使用 Gemini 缓存（`cache_control: {"type": "ephemeral"}`）时，`tool_choice` 参数会被静默丢弃。这影响 `gemini/` 和 `vertex_ai/` 提供商（Issue #29088）。
### Prisma 查询引擎（Windows）
在 Windows 上使用 pip 安装 LiteLLM 代理时，Prisma 查询引擎在首次查询时会立即崩溃，影响版本 1.82.x 和 1.83.0（Issue #25260）。
### UI 邮件设置
代理 UI 中的邮件服务器设置保存后可能无法持久化（Issue #19221）。建议通过配置文件设置邮件参数。
### 安全提醒
2024 年发现 v1.82.7 和 v1.82.8 版本存在供应链安全风险（Issue #24512、#24518）。请确保使用最新稳定版本 v1.88.0-dev.1 或更高版本。
## 最佳实践
### 1. 使用环境变量管理密钥
```python
import os
import litellm
# 通过环境变量传递密钥
os.environ["OPENAI_API_KEY"] = "sk-xxxx"
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "Hello"}]
)
```
### 2. 配置重试机制
```python
import litellm
from litellm import RetryConfig
litellm.set_retry=True
litellm.retry_config=RetryConfig(
max_retries=3,
retry_delay=1
)
```
### 3. 日志调试
```python
import litellm
litellm.set_verbose=True
litellm._turn_on_debug()
```
### 4. 错误处理
```python
import litellm
try:
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "Hello"}]
)
except litellm.RateLimitError:
print("请求频率超限，请稍后重试")
except litellm.AuthenticationError:
print("认证失败，请检查 API 密钥")
except Exception as e:
print(f"请求失败: {e}")
```
### 5. 生产环境检查清单
- [ ] 使用最新稳定版本
- [ ] 配置适当的超时时间
- [ ] 实现重试和回退机制
- [ ] 启用请求日志和监控
- [ ] 定期轮换 API 密钥
- [ ] 验证 Docker 镜像签名
## 下一步
- 阅读 [完整文档](https://docs.litellm.ai/)
- 加入 [社区 Slack](https://join.slack.com/t/litellm/shared_invite/xxx)
- 查看 [示例代码](../examples/)
- 贡献代码，请查阅 [贡献指南](../CONTRIBUTING.md)
---
## 系统架构
### 相关页面
相关主题：[LLM 提供商集成](#llm_providers), [代理服务器详解](#proxy_server), [路由策略](#router_strategies)
相关源码文件
以下源码文件用于生成本页说明：
- [litellm/proxy/proxy_server.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/proxy_server.py)
- [litellm/router.py](https://github.com/BerriAI/litellm/blob/main/litellm/router.py)
- [litellm/litellm_core_utils/litellm_logging.py](https://github.com/BerriAI/litellm/blob/main/litellm/litellm_core_utils/litellm_logging.py)
- [litellm/proxy/_types.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/_types.py)
- [litellm/integrations/dotprompt/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/integrations/dotprompt/README.md)
- [litellm/llms/litellm_proxy/skills/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/llms/litellm_proxy/skills/README.md)
- [litellm/integrations/otel/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/integrations/otel/README.md)
- [litellm/proxy/enterprise/litellm_enterprise/proxy/readme.md](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/enterprise/litellm_enterprise/proxy/readme.md)
# 系统架构
## 概述
LiteLLM 是一个统一的大语言模型（LLM）网关和代理服务，为开发者提供对 100+ 大语言模型的统一调用接口。LiteLLM 的系统架构设计遵循模块化原则，将核心路由、智能体编排、提示词管理、可观测性和企业级功能解耦为独立组件，实现了高度的可扩展性和可维护性。
LiteLLM 架构的核心价值在于：
- **统一接口**：通过标准化 API 调用不同提供商的 LLM
- **负载均衡**：智能路由和故障转移
- **成本控制**：多模型调用优化和预算管理
- **安全审计**：完整的请求日志和访问控制
- **企业级功能**：SSO、团队管理、API 密钥管理等
资料来源：[litellm/proxy/proxy_server.py:1-100]()
## 整体架构图
```mermaid
graph TB
subgraph "客户端层"
Client[用户应用/SDK]
CLI[CLI 工具]
Dashboard[Web 管理界面]
end
subgraph "代理服务层 Proxy Server"
API[FastAPI 服务]
Auth[认证/鉴权]
RateLimit[限流控制]
Guardrails[安全防护]
end
subgraph "核心路由层 Router"
LB[负载均衡器]
Fallback[故障转移]
Retry[重试机制]
Budget[预算控制]
end
subgraph "模型适配层 LLM Adapters"
OpenAI[OpenAI]
Anthropic[Anthropic]
Gemini[Gemini]
Azure[Azure]
Vertex[Vertex AI]
Custom[自定义 Provider]
end
subgraph "外部服务"
PromptMgmt[提示词管理]
Skills[技能系统]
OTel[可观测性]
DB[(数据库)]
end
Client --> API
CLI --> API
Dashboard --> API
API --> Auth
Auth --> RateLimit
RateLimit --> Guardrails
Guardrails --> Router
Router --> LB
LB --> OpenAI
LB --> Anthropic
LB --> Gemini
LB --> Azure
LB --> Vertex
LB --> Custom
Router --> PromptMgmt
Router --> Skills
Router --> OTel
Router --> DB
```
## 核心组件架构
### 1. 代理服务层（Proxy Server）
代理服务层是 LiteLLM 的入口层，基于 FastAPI 框架构建，负责处理所有传入的 HTTP 请求。
#### 主要职责
| 职责 | 描述 | 相关文件 |
|------|------|----------|
| 请求路由 | 将 API 请求分发到相应的处理器 | proxy_server.py |
| 认证鉴权 | API Key 验证、SSO 认证、团队权限控制 | proxy_server.py, _types.py |
| 限流控制 | 基于用户/团队/API Key 的请求频率限制 | proxy_server.py |
| 成本追踪 | 记录和汇总 API 调用费用 | proxy_server.py |
| 日志记录 | 完整的请求/响应日志 | litellm_logging.py |
#### 企业级端点组织
企业级功能按照功能域进行模块化组织：
```
enterprise/litellm_enterprise/proxy/
├── key_management_endpoints.py # 密钥管理
├── user_management_endpoints.py # 用户管理
├── auth_endpoints.py # 认证端点
├── management_endpoints/ # 管理类端点
│ ├── team_management.py
│ ├── organization_management.py
│ └── budget_management.py
└── auth_endpoints/ # 认证相关
```
资料来源：[litellm/proxy/enterprise/litellm_enterprise/proxy/readme.md:1-20]()
### 2. 核心路由层（Router）
Router 是 LiteLLM 的核心引擎，负责实现智能路由逻辑，包括负载均衡、故障转移、重试机制和预算控制。
```mermaid
graph LR
Request[请求] --> Validation{参数验证}
Validation -->|通过| Budget{预算检查}
Validation -->|失败| Error[错误响应]
Budget -->|有预算| Deployments[可用部署]
Budget -->|超预算| Blocked[阻止请求]
Deployments --> Health{健康检查}
Health -->|健康| Selected[选中实例]
Health -->|不健康| Next{下一个实例}
Selected --> Call[调用 LLM]
Call -->|成功| Response[返回响应]
Call -->|失败| Retry{重试}
Retry -->|可重试| Selected
Retry -->|不可重试| Fallback[降级处理]
```
#### 路由策略
| 策略 | 说明 | 配置参数 |
|------|------|----------|
| 轮询（Round Robin） | 依次选择可用部署 | `router_strategy: "simple-shuffle"` |
| 最短响应时间 | 选择延迟最低的部署 | `router_strategy: "latency-based-routing"` |
| 成本优先 | 优先使用低价模型 | `router_strategy: "cost-based-routing"` |
| 优先级 | 按权重分配流量 | `routing_strategy_args` |
资料来源：[litellm/router.py:1-200]()
### 3. 模型适配层（LLM Adapters）
LiteLLM 通过统一的适配器接口支持 100+ LLM 提供商，每个适配器负责将标准化请求转换为特定提供商的 API 格式。
#### 支持的模型类型
```mermaid
graph TD
subgraph "对话模型"
ChatOpenAI[OpenAI Chat]
ChatAnthropic[Anthropic Claude]
ChatGemini[Google Gemini]
ChatAzure[Azure OpenAI]
end
subgraph "文本补全模型"
CompOpenAI[OpenAI Completion]
CompAnthropic[Anthropic Text]
end
subgraph "嵌入模型"
EmbedOpenAI[OpenAI Embeddings]
EmbedAzure[Azure Embeddings]
end
subgraph "其他能力"
Rerank[重排序]
Audio[语音转写]
Image[图像生成]
end
```
#### 适配器结构
每个 LLM 适配器遵循统一的结构：
```
llms/
├── openai/
│ ├── completion/
│ │ ├── handler.py # 主处理器
│ │ └── guardrail_translation/ # 安全防护
│ ├── chat/
│ └── embeddings/
├── anthropic/
├── gemini/
├── vertex_ai/
├── azure/
└── custom/ # 自定义 Provider
```
#### Guardrails 安全防护
Guardrails 机制在请求和响应层面进行内容过滤：
```python
# Guardrail 处理流程
class GuardrailHandler:
def process_input_messages(self, messages, guardrails):
# 对输入进行 PII 过滤、内容审核
return processed_messages
def process_output_response(self, response, guardrails):
# 对输出进行内容审核
return processed_response
```
支持的 Guardrail 类型：
- **PII 保护**：自动检测和掩码个人身份信息
- **内容审核**：过滤不当内容
- **自定义规则**：基于正则表达式的文本过滤
资料来源：[litellm/llms/cohere/rerank/guardrail_translation/README.md:1-60]()
### 4. 提示词管理系统
LiteLLM 支持多种提示词管理方案，便于团队协作和版本控制。
#### 支持的存储后端
| 后端 | 说明 | 特点 |
|------|------|------|
| Dotprompt | 本地 `.prompt` 文件 | 轻量、快速 |
| GitLab | GitLab 仓库 | 团队协作、版本控制 |
| BitBucket | BitBucket 仓库 | 团队协作、分支管理 |
| Arize Phoenix | Arize 平台 | 实验跟踪、评估 |
#### Dotprompt 文件格式
```yaml
---
model: gpt-4
temperature: 0.7
max_tokens: 500
input:
schema:
user_message: string
system_context?: string
---
{% raw %}
System: You are a helpful {{role}} assistant.
User: {{user_message}}
{% endraw %}
```
#### PromptManager 核心方法
```python
class PromptManager:
def __init__(self, prompt_directory: str):
"""初始化提示词管理器"""
def render(self, prompt_id: str, variables: dict) -> str:
"""渲染带变量的提示词模板"""
def list_prompts(self) -> List[str]:
"""列出所有可用的提示词 ID"""
def get_prompt(self, prompt_id: str) -> PromptTemplate:
"""获取提示词模板对象"""
def get_prompt_metadata(self, prompt_id: str) -> dict:
"""获取提示词元数据（模型、参数等）"""
def reload_prompts(self) -> None:
"""重新加载所有提示词"""
```
资料来源：[litellm/integrations/dotprompt/README.md:1-150]()
### 5. 技能系统（Skills）
技能系统允许开发者创建和分发可复用的 LLM 功能模块，以 ZIP 包的形式上传和管理。
#### 技能 ZIP 结构
```
my-skill.zip
└── my-skill/
└── SKILL.md # 必需：技能定义文件
```
#### SKILL.md 格式
```markdown
---
name: my-skill
description: 技能功能描述
---
# 技能名称
详细的使用说明...
## 使用场景
- 场景 1
- 场景 2
```
#### 技能数据库模型
```prisma
model LiteLLM_SkillsTable {
skill_id String @id @default(uuid())
display_title String?
description String?
instructions String?
source String @default("custom")
latest_version String?
metadata Json? @default("{}")
file_content Bytes? // ZIP 文件内容
file_name String?
file_type String?
created_at DateTime @default(now())
created_by String?
updated_at DateTime @updatedAt
}
```
资料来源：[litellm/llms/litellm_proxy/skills/README.md:1-150]()
### 6. 可观测性层（OpenTelemetry）
LiteLLM 集成 OpenTelemetry 标准，提供完整的分布式追踪能力。
#### 追踪词汇表（Attribute Mappers）
| Mapper | 用途 | 属性命名空间 |
|--------|------|-------------|
| `genai` | OpenTelemetry GenAI 标准 | `genai.*` |
| `legacy` | 旧版 Traceloop 命名 | `ai.*` |
| `openinference` | Arize Phoenix | 特定格式 |
| `langfuse` | Langfuse 集成 | 特定格式 |
| `weave` | Weights & Biases | 特定格式 |
| `langtrace` | Langtrace | 特定格式 |
#### 追踪器架构
```mermaid
graph TB
subgraph "配置层 Config"
Config[用户配置]
Specs[Exporter Specs]
end
subgraph "路由层 Routing"
Cache[TenantTracerCache]
Route[路由决策]
end
subgraph "管道层 Plumbing"
Providers[TracerProviders]
Exporters[Exporters]
Processor[Span Processor]
end
Config --> Cache
Specs --> Providers
Cache --> Route
Route --> Providers
Providers --> Exporters
Exporters --> Processor
```
#### 多租户追踪
当请求携带团队或密钥级别的供应商凭证时，追踪器通过 `TenantTracerCache` 将请求路由到凭证密钥化的 `TracerProvider`，确保多租户环境下的追踪隔离。
资料来源：[litellm/integrations/otel/README.md:1-100]()
## 数据流架构
### 完整请求生命周期
```mermaid
sequenceDiagram
participant Client as 客户端
participant Proxy as Proxy Server
participant Router as Router
participant Adapter as LLM Adapter
participant Provider as LLM Provider
Client->>Proxy: HTTP 请求 (OpenAI 兼容格式)
Proxy->>Proxy: 认证/鉴权
Proxy->>Proxy: 限流检查
Proxy->>Proxy: Guardrails 输入处理
Proxy->>Router: 标准化请求
Router->>Router: 负载均衡选择
Router->>Router: 预算检查
Router->>Router: 健康检查
Router->>Adapter: 调用请求
Adapter->>Provider: 转换为 Provider 格式
Provider-->>Adapter: Provider 响应
Adapter-->>Router: 标准化响应
alt 失败重试
Router->>Router: 重试逻辑
Router->>Adapter: 重试请求
end
Router-->>Proxy: 响应
Proxy->>Proxy: Guardrails 输出处理
Proxy->>Proxy: 日志记录
Proxy-->>Client: OpenAI 兼容响应
```
### CLI 认证流程
LiteLLM CLI 支持 OAuth SSO 认证：
```mermaid
sequenceDiagram
participant CLI as CLI
participant Browser as 浏览器
participant Proxy as LiteLLM Proxy
participant SSO as SSO Provider
CLI->>Proxy: POST /sso/cli/start
Proxy->>CLI: login_id, poll_secret, user_code
CLI->>Browser: 打开认证页面
Browser->>Proxy: GET /sso/key/generate
Proxy->>Proxy: 设置 cli_state
Proxy->>SSO: 重定向
SSO->>Browser: 显示登录页
Browser->>SSO: 用户认证
SSO->>Proxy: 回调
Proxy->>Browser: 请求 user_code 确认
Browser->>Proxy: POST /sso 完成认证
```
资料来源：[litellm/proxy/client/README.md:1-100]()
## 类型系统
LiteLLM 使用集中化的类型定义来确保整个系统的类型安全。
```python
# litellm/proxy/_types.py 核心类型
class UserRole(Enum):
"""用户角色"""
ADMIN = "admin"
INTERNAL_USER = "internal_user"
TEAM = "team"
class KeyTier(Enum):
"""密钥层级"""
BASIC = "basic"
STANDARD = "standard"
ENTERPRISE = "enterprise"
class CallTypes(Enum):
"""支持的调用类型"""
completion = "completion"
acompletion = "acompletion"
embedding = "embedding"
aembedding = "aembedding"
image_generation = "image_generation"
rerank = "rerank"
arerank = "arerank"
```
资料来源：[litellm/proxy/_types.py:1-200]()
## 关键设计模式
### 1. 适配器模式
所有 LLM Provider 通过统一的适配器接口实现，便于添加新提供商：
```python
class BaseHandler:
def __init__(self):
self.supports_function_calling = False
self.supports_vision = False
async def acompletion(self, *args, **kwargs):
raise NotImplementedError
def completion(self, *args, **kwargs):
raise NotImplementedError
```
### 2. 中间件模式
请求经过多层中间件处理：
- 认证中间件
- 限流中间件
- Guardrails 中间件
- 日志中间件
### 3. 工厂模式
提示词管理器通过工厂模式支持多种后端：
```python
def get_dotprompt_manager():
"""获取 Dotprompt 管理器实例"""
return PromptManager(...)
def get_gitlab_manager(config):
"""获取 GitLab 管理器实例"""
return GitLabPromptManager(...)
```
## 安全性考虑
### 认证机制
| 方式 | 说明 | 适用场景 |
|------|------|----------|
| API Key | 静态密钥认证 | 生产环境 |
| SSO | OAuth/OIDC 单点登录 | 企业用户 |
| Team Key | 团队级密钥 | 多租户应用 |
| Organization Key | 组织级密钥 | 大型企业 |
### 安全事件回顾
2025 年初，LiteLLM v1.82.7 和 v1.82.8 版本遭受供应链攻击（[Issue #24512](https://github.com/BerriAI/litellm/issues/24512)），恶意代码通过 PyPI 包分发。LiteLLM 团队已确认所有受影响版本已从 PyPI 删除，并加强了包签名验证。
**建议**：使用 Docker 镜像部署时，验证镜像签名：
```bash
cosign verify \
--certificate-identity "https://github.com/BerriAI/litellm/actions" \
ghcr.io/berriai/litellm:main
```
## 性能优化
### 导入速度
LiteLLM 的完整导入时间较长（约 1 秒），社区已提出优化请求（[Issue #7605](https://github.com/BerriAI/litellm/issues/7605)）。建议按需导入：
```python
# 只导入需要的模块
from litellm import completion
# 而非完整导入
# import litellm # 较慢
```
### 路由缓存
Router 层维护部署健康状态和延迟缓存，减少不必要的健康检查开销。
## 总结
LiteLLM 的系统架构采用分层设计，从入口代理到模型适配层各司其职，通过统一的 Router 编排实现智能路由和故障转移。提示词管理、技能系统和可观测性层的模块化设计使其成为企业级 LLM 网关的优选方案。架构的可扩展性体现在：
1. **Provider 扩展**：通过适配器模式轻松添加新模型提供商
2. **存储扩展**：支持多种提示词存储后端
3. **追踪扩展**：兼容多种 OTel 供应商
4. **企业功能**：模块化的企业级端点组织
---
## LLM 提供商集成
### 相关页面
相关主题：[系统架构](#system_architecture), [路由策略](#router_strategies)
相关源码文件
以下源码文件用于生成本页说明：
- [litellm/llms/__init__.py](https://github.com/BerriAI/litellm/blob/main/litellm/llms/__init__.py)
- [litellm/llms/base.py](https://github.com/BerriAI/litellm/blob/main/litellm/llms/base.py)
- [litellm/llms/openai/openai.py](https://github.com/BerriAI/litellm/blob/main/litellm/llms/openai/openai.py)
- [litellm/llms/anthropic/chat/handler.py](https://github.com/BerriAI/litellm/blob/main/litellm/llms/anthropic/chat/handler.py)
- [litellm/llms/gemini/chat/transformation.py](https://github.com/BerriAI/litellm/blob/main/litellm/llms/gemini/chat/transformation.py)
- [litellm/llms/bedrock/chat/converse_handler.py](https://github.com/BerriAI/litellm/blob/main/litellm/llms/bedrock/chat/converse_handler.py)
- [litellm/litellm_core_utils/get_llm_provider_logic.py](https://github.com/BerriAI/litellm/blob/main/litellm/litellm_core_utils/get_llm_provider_logic.py)
# LLM 提供商集成
## 概述
LiteLLM 是一个统一的 LLM 调用接口库，支持超过 100 种大语言模型提供商。通过提供标准化的抽象层，开发者可以使用统一的 API 调用方式访问 OpenAI、Anthropic、Google Gemini、AWS Bedrock、Azure 等多种 LLM 服务。
LLM 提供商集成系统的核心职责包括：
- **统一接口抽象**：将不同提供商的 API 差异封装为一致的调用格式
- **请求转换**：将用户请求转换为各提供商特定的请求格式
- **响应标准化**：将提供商响应统一转换为标准化的返回格式
- **错误处理**：提供一致的错误处理和重试机制
- **Provider 路由**：根据模型名称自动识别并路由到正确的提供商
## 架构设计
### 整体架构
LiteLLM 的提供商集成采用分层架构设计，核心组件包括：
```mermaid
graph TD
A[用户请求] --> B[LiteLLM 主入口]
B --> C[Provider 路由层]
C --> D[get_llm_provider_logic]
D --> E[提供商识别]
E --> F{Provider 类型}
F -->|OpenAI| G[OpenAI Handler]
F -->|Anthropic| H[Anthropic Handler]
F -->|Gemini| I[Gemini Handler]
F -->|Bedrock| J[Bedrock Handler]
F -->|Azure| K[Azure Handler]
G --> L[API 请求发送]
H --> L
I --> L
J --> L
K --> L
L --> M[响应转换层]
M --> N[统一响应格式]
```
### 核心组件职责
| 组件 | 位置 | 职责 |
|------|------|------|
| Provider 路由 | `get_llm_provider_logic.py` | 根据模型名称解析提供商类型 |
| Base Handler | `llms/base.py` | 定义所有 Provider Handler 的接口规范 |
| Provider Handlers | `llms/{provider}/` | 实现各提供商的特定逻辑 |
| 请求转换 | 各 Provider 的 `transformation.py` | 转换请求格式 |
| 响应转换 | 各 Provider 的 `transformation.py` | 转换响应格式 |
## Provider 路由机制
### 模型名称解析
LiteLLM 使用特定的模型命名约定来识别提供商。模型名称格式为：`{provider}/{model_name}`
```python
# OpenAI: gpt-4, gpt-3.5-turbo
# Anthropic: claude-3-opus-20240229, claude-3-sonnet-20240229
# Google Gemini: gemini-pro, gemini-1.5-flash
# AWS Bedrock: amazon.titan-text-express-v1, anthropic.claude-3-sonnet
# Azure: azure/gpt-4
```
### Provider 识别流程
```mermaid
graph LR
A[模型名称] --> B{前缀检查}
B -->|"openai/"| C[OpenAI Provider]
B -->|"anthropic/"| D[Anthropic Provider]
B -->|"gemini/"| E[Gemini Provider]
B -->|"bedrock/"| F[Bedrock Provider]
B -->|"azure/"| G[Azure Provider]
B -->|"vertex_ai/"| H[Vertex AI Provider]
C --> I[Handler 实例化]
D --> I
E --> I
F --> I
G --> I
H --> I
```
Provider 路由逻辑的核心代码位于 `get_llm_provider_logic.py`，该模块负责：
1. 解析模型字符串，提取 provider 和 model
2. 验证 provider 是否支持该模型
3. 返回对应的 Handler 类引用
资料来源：[litellm/litellm_core_utils/get_llm_provider_logic.py:1-50]()
## Base Handler 抽象
所有 Provider Handler 必须继承自 `BaseHandler` 基类，该基类定义了统一的接口规范。
### Handler 核心方法
```python
class BaseHandler:
def __init__(self, **kwargs):
"""初始化 Handler，配置 API 密钥等认证信息"""
async def async_completion(self, model, messages, **kwargs):
"""处理异步补全请求"""
raise NotImplementedError
def completion(self, model, messages, **kwargs):
"""处理同步补全请求"""
raise NotImplementedError
def embedding(self, model, input, **kwargs):
"""处理嵌入请求"""
raise NotImplementedError
def async_embedding(self, model, input, **kwargs):
"""处理异步嵌入请求"""
raise NotImplementedError
```
资料来源：[litellm/llms/base.py:1-100]()
### 通用参数处理
Handler 需要处理的通用参数包括：
| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 模型名称 |
| `messages` | list | 消息列表 |
| `temperature` | float | 采样温度 (0-2) |
| `max_tokens` | int | 最大生成 token 数 |
| `top_p` | float | Top-p 采样参数 |
| `stream` | bool | 是否使用流式输出 |
| `tools` | list | 工具/函数定义 |
| `tool_choice` | string/object | 工具选择策略 |
| `user` | string | 用户标识 |
## 主要 Provider 实现
### OpenAI Provider
OpenAI 是 LiteLLM 最完整的 Provider 实现，支持完整的 Chat Completions 和 Completions API。
**核心文件**：`litellm/llms/openai/openai.py`
**支持的模型**：
- GPT-4 系列 (gpt-4, gpt-4-turbo, gpt-4o)
- GPT-3.5 Turbo 系列
- GPT-3.5 Instruct (文本补全)
**请求转换示例**：
```python
# 用户输入格式
{
"model": "gpt-4",
"messages": [
{"role": "system", "content": "You are helpful."},
{"role": "user", "content": "Hello!"}
],
"temperature": 0.7
}
# 转换为 OpenAI API 格式
{
"model": "gpt-4",
"messages": [...],
"temperature": 0.7
}
```
OpenAI Provider 的请求转换相对直接，因为 LiteLLM 的内部格式与 OpenAI API 格式高度兼容。
资料来源：[litellm/llms/openai/openai.py:1-200]()
### Anthropic Provider
Anthropic Provider 处理 Claude 系列模型的调用，需要将 OpenAI 格式的消息转换为 Anthropic 的格式。
**核心文件**：`litellm/llms/anthropic/chat/handler.py`
**支持的模型**：
- Claude 3 Opus
- Claude 3 Sonnet
- Claude 3 Haiku
- Claude 2.x
**关键转换逻辑**：
| OpenAI 格式 | Anthropic 格式 |
|-------------|----------------|
| `system` 消息 | `system` 参数 |
| `user` 消息 | `user` 内容块 |
| `assistant` 消息 | `assistant` 内容块 |
| `max_tokens` | `max_tokens` |
| `stream` | `stream` |
资料来源：[litellm/llms/anthropic/chat/handler.py:1-150]()
### Google Gemini Provider
Gemini Provider 支持 Google 的 Gemini 系列模型。注意：根据社区反馈，使用缓存时 `tool_choice` 可能会被静默丢弃。
**核心文件**：`litellm/llms/gemini/chat/transformation.py`
**支持的模型**：
- Gemini Pro (gemini-pro)
- Gemini Flash (gemini-1.5-flash)
- Gemini Pro Vision (gemini-pro-vision)
**已知问题**：
> ⚠️ 当 Gemini 请求同时包含 `cache_control: {"type": "ephemeral"}` 标记和 `tool_choice` 参数时，`tool_choice` 会被静默丢弃。此问题影响 `gemini/` 和 `vertex_ai/` 两个 Provider。
资料来源：[litellm/llms/gemini/chat/transformation.py:1-100]()
### AWS Bedrock Provider
Bedrock Provider 通过 AWS Bedrock 服务调用各种基础模型，包括 Amazon Titan、Claude (通过 Anthropic)、Llama 等。
**核心文件**：`litellm/llms/bedrock/chat/converse_handler.py`
**支持的模型**：
| 模型系列 | 具体模型 |
|----------|----------|
| Amazon Titan | amazon.titan-text-express-v1 |
| Anthropic Claude | anthropic.claude-3-sonnet |
| Meta Llama | meta.llama2-13b-chat |
| AI21 Jurassic | ai21.j2-mid-v1 |
**AWS 认证配置**：
Bedrock Provider 支持多种 AWS 认证方式：
1. **环境变量**：`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
2. **AWS Profile**：使用 `aws_profile` 参数
3. **IAM Role**：在 AWS 环境中自动使用 EC2/ECS 角色
资料来源：[litellm/llms/bedrock/chat/converse_handler.py:1-150]()
## 请求与响应转换
### 转换流程
```mermaid
graph TD
A[用户请求] --> B[LiteLLM 标准化]
B --> C[Provider 转换层]
C --> D{Provider 类型}
D -->|OpenAI| E[直接传递]
D -->|Anthropic| F[消息格式转换]
D -->|Gemini| G[结构重组]
D -->|Bedrock| H[Converse API 格式]
E --> I[Provider API]
F --> I
G --> I
H --> I
I --> J[响应转换层]
J --> K[LiteLLM 标准格式]
```
### 消息格式转换示例
**OpenAI 到 Anthropic 转换**：
```python
# OpenAI 格式
messages = [
{"role": "system", "content": "You are helpful."},
{"role": "user", "content": "What is 2+2?"},
{"role": "assistant", "content": "4"},
{"role": "user", "content": "Multiply by 3"}
]
# Anthropic 转换后
{
"system": "You are helpful.",
"messages": [
{"role": "user", "content": "What is 2+2?"},
{"role": "assistant", "content": "4"},
{"role": "user", "content": "Multiply by 3"}
]
}
```
## 配置与管理
### config.yaml 配置
```yaml
model_list:
- model_name: gpt-4-turbo
litellm_params:
model: gpt-4-turbo-preview
api_key: os.environ/OPENAI_API_KEY
temperature: 0.7
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-3-sonnet-20240229
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: gemini-pro
litellm_params:
model: gemini/gemini-pro
api_key: os.environ/GOOGLE_API_KEY
- model_name: bedrock-claude
litellm_params:
model: bedrock/anthropic.claude-3-sonnet-20240229-v1:0
aws_region_name: us-east-1
```
### 环境变量配置
各 Provider 的认证信息通常通过环境变量提供：
| Provider | 环境变量 |
|----------|----------|
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Google | `GOOGLE_API_KEY`, `GOOGLE_VERTEX_AI_PROJECT` |
| Azure | `AZURE_API_KEY`, `AZURE_API_BASE` |
| AWS Bedrock | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION_NAME` |
## 使用示例
### 基础调用
```python
import litellm
# OpenAI
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "Hello!"}]
)
# Anthropic
response = litellm.completion(
model="anthropic/claude-3-sonnet-20240229",
messages=[{"role": "user", "content": "Hello!"}]
)
# Gemini
response = litellm.completion(
model="gemini/gemini-pro",
messages=[{"role": "user", "content": "Hello!"}]
)
```
### 使用配置文件
```python
import litellm
# 加载配置文件
litellm.set_config_path(config_file_path="config.yaml")
# 使用配置的模型别名
response = litellm.completion(
model="gpt-4-turbo", # 使用 config.yaml 中的别名
messages=[{"role": "user", "content": "Hello!"}]
)
```
### 流式输出
```python
import litellm
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "Write a story"}],
stream=True
)
for chunk in response:
print(chunk.choices[0].delta.content, end="")
```
### 工具调用
```python
import litellm
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"}
}
}
}
}
]
response = litellm.completion(
model="gpt-4-turbo",
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
tools=tools,
tool_choice="auto"
)
```
## 最佳实践
### 1. Provider 选择建议
| 场景 | 推荐 Provider |
|------|---------------|
| 通用对话 | OpenAI GPT-4 |
| 长上下文 | Anthropic Claude 3 |
| 多模态 | Google Gemini |
| AWS 生态 | AWS Bedrock |
| 成本敏感 | OpenAI GPT-3.5 / 开源模型 |
### 2. 错误处理
```python
import litellm
from litellm.exceptions import (
AuthenticationError,
RateLimitError,
BadRequestError
)
try:
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "Hello!"}]
)
except AuthenticationError as e:
print(f"API 认证失败: {e}")
except RateLimitError as e:
print(f"请求频率超限: {e}")
# 实现退避重试逻辑
except BadRequestError as e:
print(f"请求格式错误: {e}")
```
### 3. 性能优化
- **使用流式输出**：减少感知延迟
- **批量请求**：使用 `batches` 参数处理多个请求
- **缓存响应**：使用 `caching` 参数启用响应缓存
- **选择合适的模型**：根据任务复杂度选择模型
## 故障排查
### 常见问题
**问题 1：Provider 识别失败**
```
错误：LitellmRoutingPromptError: Model name not mapped. Provide a valid model name.
```
**解决方案**：检查模型名称格式是否正确，确保包含 Provider 前缀（如 `openai/gpt-4`）。
**问题 2：认证失败**
```
错误：AuthenticationError: Incorrect API key provided
```
**解决方案**：验证环境变量中的 API 密钥是否正确，检查是否包含正确的密钥前缀。
**问题 3：Gemini tool_choice 失效**
当使用 Gemini 缓存功能时，`tool_choice` 参数可能被丢弃。这是已知问题，建议在启用缓存时避免使用强制工具调用。
资料来源：[GitHub Issue #29088](https://github.com/BerriAI/litellm/issues/29088)
**问题 4：Windows Prisma 查询崩溃**
在 Windows 环境下使用 Prisma 查询引擎时可能出现崩溃，建议使用 v1.84.3 或更新版本。
资料来源：[GitHub Issue #25260](https://github.com/BerriAI/litellm/issues/25260)
## 扩展新的 Provider
如需添加新的 LLM Provider，需要实现以下组件：
### 1. 创建 Handler 类
```python
# litellm/llms/{provider}/chat/handler.py
from litellm.llms.base import BaseHandler
class {Provider}Handler(BaseHandler):
def __init__(self, **kwargs):
super().__init__(**kwargs)
# 初始化提供商特定的配置
def completion(self, model, messages, **kwargs):
# 实现补全逻辑
pass
async def async_completion(self, model, messages, **kwargs):
# 实现异步补全逻辑
pass
```
### 2. 实现请求转换
```python
# litellm/llms/{provider}/chat/transformation.py
class {Provider}Transformation:
def transform_request(self, model, messages, kwargs):
# 将 LiteLLM 标准格式转换为 Provider 格式
pass
def transform_response(self, response):
# 将 Provider 响应转换为 LiteLLM 标准格式
pass
```
### 3. 注册 Provider
在 `litellm/litellm_core_utils/get_llm_provider_logic.py` 中注册新的 Provider，确保路由层能正确识别。
## 相关资源
- [LiteLLM 官方文档](https://docs.litellm.ai/)
- [支持的模型列表](https://docs.litellm.ai/docs/providers)
- [GitHub Issues](https://github.com/BerriAI/litellm/issues)
- [安全公告](https://docs.litellm.ai/blog/security-townhall-updates)
---
## 代理服务器详解
### 相关页面
相关主题：[管理控制台](#admin_ui), [安全护栏](#guardrails)
相关源码文件
以下源码文件用于生成本页说明：
- [litellm/proxy/proxy_server.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/proxy_server.py)
- [litellm/proxy/auth/user_api_key_auth.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/auth/user_api_key_auth.py)
- [litellm/proxy/management_endpoints/key_management_endpoints.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/management_endpoints/key_management_endpoints.py)
- [litellm/proxy/common_request_processing.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/common_request_processing.py)
- [litellm/proxy/route_llm_request.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/route_llm_request.py)
# 代理服务器详解
## 概述
LiteLLM代理服务器是一个高性能的统一网关服务，为大型语言模型（LLM）提供标准化API接口。通过该代理，用户可以：
- **统一接入**：通过单一端点访问多个LLM提供商
- **密钥管理**：安全存储和管理API密钥
- **访问控制**：基于API密钥的细粒度权限控制
- **成本追踪**：记录和监控每个密钥的使用情况
- **限流保护**：防止API滥用和服务过载
资料来源：[litellm/proxy/proxy_server.py:1-100]()
## 架构设计
### 系统架构图
```mermaid
graph TD
Client[客户端请求] --> Gateway[代理网关]
Gateway --> Auth[认证层]
Auth --> Router[请求路由器]
Router --> LLM1[OpenAI]
Router --> LLM2[Anthropic]
Router --> LLM3[Azure]
Router --> LLM4[其他提供商]
LLM1 --> Response1[响应]
LLM2 --> Response2[响应]
LLM3 --> Response3[响应]
LLM4 --> Response4[响应]
Response1 --> Logging[日志记录]
Response2 --> Logging
Response3 --> Logging
Response4 --> Logging
Logging --> Client
```
### 核心处理流程
```mermaid
sequenceDiagram
participant C as 客户端
participant G as 代理网关
participant A as 认证模块
participant P as 请求处理
participant R as LLM路由
participant LLM as 模型提供商
C->>G: HTTP请求
G->>A: 验证API密钥
A->>A: 检查权限/限流
A-->>G: 认证通过/拒绝
G->>P: 处理请求
P->>R: 路由到提供商
R->>LLM: 转发请求
LLM-->>R: 模型响应
R-->>P: 标准化响应
P-->>G: 返回结果
G-->>C: HTTP响应
```
## 核心组件
### 组件概览
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| proxy_server | `litellm/proxy/proxy_server.py` | 主服务器入口，处理FastAPI路由 |
| user_api_key_auth | `litellm/proxy/auth/user_api_key_auth.py` | API密钥认证与授权 |
| key_management_endpoints | `litellm/proxy/management_endpoints/key_management_endpoints.py` | 密钥生命周期管理 |
| common_request_processing | `litellm/proxy/common_request_processing.py` | 通用请求预处理 |
| route_llm_request | `litellm/proxy/route_llm_request.py` | LLM请求路由与转发 |
### proxy_server.py
代理服务器的主入口文件，负责：
- 初始化FastAPI应用实例
- 注册所有API路由端点
- 配置中间件（认证、日志、CORS等）
- 管理服务器生命周期
核心端点包括：
- `/chat/completions` - 聊天补全
- `/completions` - 文本补全
- `/embeddings` - 向量嵌入
- `/v1/key/generate` - 生成API密钥
- `/v1/key/info` - 查询密钥信息
- `/v1/models` - 可用模型列表
资料来源：[litellm/proxy/proxy_server.py:1-200]()
## 认证与授权
### 认证机制
LiteLLM采用API密钥作为主要认证方式。认证流程如下：
```mermaid
graph LR
A[请求头] --> B{提取密钥}
B --> C{格式检查}
C -->|Bearer token| D[查询数据库]
C -->|无效格式| E[返回401]
D --> F{密钥存在?}
F -->|是| G[验证权限]
F -->|否| H[返回401]
G --> I{未过期?}
I -->|是| J[检查限流]
I -->|否| K[返回401]
J --> L[请求通过]
```
### 密钥验证流程
用户API密钥认证模块实现以下验证步骤：
1. **密钥提取**：从`Authorization: Bearer `头部提取密钥
2. **格式验证**：检查密钥格式是否符合规范
3. **数据库查询**：在Prisma数据库中查询密钥信息
4. **状态检查**：验证密钥是否启用、未过期
5. **权限校验**：检查密钥是否有权访问请求的模型
6. **限流检查**：验证请求是否超过速率限制
资料来源：[litellm/proxy/auth/user_api_key_auth.py:1-150]()
### 权限模型
| 权限字段 | 描述 | 可选值 |
|----------|------|--------|
| `models` | 允许访问的模型列表 | `["gpt-4", "claude-3"]` 或 `["*"]` |
| `duration` | 密钥有效期 | `"30d"`, `"1h"`, `"never"` |
| `budget_id` | 关联的预算ID | 字符串 |
| `team_id` | 所属团队ID | 字符串 |
| `max_budget` | 最大消费额度 | 浮点数 |
## 密钥管理
### 密钥生命周期
```mermaid
stateDiagram-v2
[*] --> 创建: /v1/key/generate
创建 --> 激活: 密钥生成成功
激活 --> 使用中: 首次API调用
使用中 --> 暂停: 管理员禁用
暂停 --> 激活: 管理员启用
使用中 --> 过期: 达到有效期
暂停 --> 过期: 达到有效期
过期 --> [*]: 清理
使用中 --> [*]: 删除
```
### 密钥生成端点
`POST /v1/key/generate` 用于创建新的API密钥：
**请求参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `key_alias` | string | 否 | 密钥别名 |
| `user_id` | string | 否 | 关联用户ID |
| `team_id` | string | 否 | 关联团队ID |
| `models` | list | 否 | 允许的模型列表 |
| `duration` | string | 否 | 有效期 |
| `max_budget` | float | 否 | 最大预算 |
| `metadata` | dict | 否 | 自定义元数据 |
**响应：**
```json
{
"key": "sk-...",
"key_name": "sdk-key-...",
"expires_at": "2024-12-31T23:59:59Z",
"user_id": "user_123",
"team_id": "team_456",
"models": ["gpt-4", "gpt-3.5-turbo"]
}
```
资料来源：[litellm/proxy/management_endpoints/key_management_endpoints.py:1-200]()
### 密钥信息查询
`GET /v1/key/info` 返回当前密钥的详细信息，包括：
- 密钥ID和名称
- 创建时间和过期时间
- 关联的模型列表
- 使用统计（请求数、token消耗）
- 团队和用户关联信息
## 请求处理流程
### 通用请求处理
通用请求处理模块负责所有传入请求的标准化处理：
```mermaid
graph TD
Input[原始请求] --> Parse[解析请求体]
Parse --> Validate[验证必填字段]
Validate -->|失败| Error[返回错误]
Validate -->|成功| Transform[转换格式]
Transform --> Enrich[添加元数据]
Enrich --> Route[路由决策]
Route --> LLM[转发至LLM]
LLM --> Normalize[标准化响应]
Normalize --> Output[返回结果]
```
### 请求预处理
`common_request_processing.py` 实现了以下预处理逻辑：
1. **参数标准化**：将不同提供商的请求格式统一为LiteLLM标准格式
2. **默认值设置**：为缺失参数填充默认值
3. **模型名称解析**：解析模型别名和提供商前缀
4. **成本估算**：在请求前估算token消耗
5. **缓存检查**：检查请求是否可复用缓存结果
资料来源：[litellm/proxy/common_request_processing.py:1-100]()
### 响应标准化
所有LLM响应都会被标准化为OpenAI兼容格式：
```python
{
"id": "chatcmpl-xxx",
"object": "chat.completion",
"created": 1234567890,
"model": "gpt-4",
"choices": [...],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30
}
}
```
## LLM请求路由
### 路由策略
`route_llm_request.py` 实现了灵活的路由机制：
```mermaid
graph TD
Req[请求] --> Model{解析模型名}
Model -->|openai/gpt-4| P1[OpenAI Provider]
Model -->|anthropic/claude-3| P2[Anthropic Provider]
Model -->|azure/gpt-4| P3[Azure Provider]
Model -->|gemini/pro| P4[Google Provider]
P1 --> Check1{健康检查}
P2 --> Check2{健康检查}
P3 --> Check3{健康检查}
P4 --> Check4{健康检查}
Check1 -->|正常| Call1[调用API]
Check1 -->|失败| Fallback1[备用节点]
Call1 --> Resp[响应]
Fallback1 --> Resp
```
### 模型配置
在`config.yaml`中配置模型列表：
```yaml
model_list:
- model_name: gpt-4-turbo
litellm_params:
model: gpt-4-turbo-preview
api_key: os.environ/OPENAI_API_KEY
rpm: 100 # 每分钟请求数限制
- model_name: claude-3-sonnet
litellm_params:
model: anthropic/claude-3-sonnet-20240229
api_key: os.environ/ANTHROPIC_API_KEY
```
### 路由参数
| 参数 | 描述 | 示例 |
|------|------|------|
| `model` | 模型标识符 | `openai/gpt-4`, `anthropic/claude-3` |
| `rpm` | 每分钟请求数限制 | `100` |
| `tpm` | 每分钟token数限制 | `100000` |
| `max_parallel_requests` | 最大并发请求数 | `50` |
| `retry_policy` | 重试策略 | `{"max_retries": 3}` |
资料来源：[litellm/proxy/route_llm_request.py:1-150]()
## CLI认证流程
LiteLLM CLI支持通过OAuth SSO进行身份验证，采用轮询机制实现无浏览器直接认证：
```mermaid
sequenceDiagram
participant CLI as CLI工具
participant Browser as 浏览器
participant Proxy as LiteLLM代理
participant SSO as SSO提供商
CLI->>Proxy: POST /sso/cli/start
Proxy->>CLI: login_id, poll_secret, user_code
CLI->>Browser: 打开认证URL
Browser->>Proxy: GET /sso/key/generate
Proxy->>SSO: 重定向到SSO登录页
SSO->>Browser: 显示登录界面
Browser->>SSO: 用户输入凭据
SSO->>Proxy: 回调完成认证
loop 轮询检查
CLI->>Proxy: POST /sso/callback 轮询
Proxy-->>CLI: 认证状态
end
Proxy->>CLI: 返回API密钥
CLI->>Proxy: 使用密钥调用API
```
### SSO端点
| 端点 | 方法 | 描述 |
|------|------|------|
| `/sso/cli/start` | POST | 启动CLI认证流程 |
| `/sso/key/generate` | GET | 生成认证URL |
| `/sso/callback` | POST | 处理SSO回调 |
| `/key/generate` | POST | 生成最终API密钥 |
资料来源：[litellm/proxy/client/README.md:1-100]()
## 配置参考
### 完整配置示例
```yaml
model_list:
- model_name: gpt-4
litellm_params:
model: openai/gpt-4
api_key: os.environ/OPENAI_API_KEY
litellm_settings:
drop_params: true
set_verbose: true
json_logs: false
environment_variables:
DATABASE_URL: "postgresql://..."
general_settings:
master_key: sk-1234
database_url: "prisma+postgres://..."
proxy_batch_write_at: 60
auth_settings:
max_budget_per_key: 100.0
default_key_ttl: 2592000 # 30天
```
### 环境变量
| 变量名 | 描述 | 必需 |
|--------|------|------|
| `DATABASE_URL` | Prisma数据库连接字符串 | 是 |
| `MASTER_KEY` | 主密钥（管理员密钥） | 是 |
| `LITELLM_KEY` | 默认API密钥 | 否 |
## 安全最佳实践
### 密钥安全
社区安全事件警示：2024年发生的PyPI供应链攻击事件表明，依赖外部包时需格外谨慎。相关安全事件详见 [Issue #24512](https://github.com/BerriAI/litellm/issues/24512)。
**推荐的安全措施：**
1. **定期轮换密钥**：设置合理的密钥过期时间
2. **最小权限原则**：为每个密钥分配最小必要权限
3. **密钥存储**：使用环境变量而非硬编码
4. **监控审计**：启用详细日志记录并定期审查
### Dockerfile签名验证
所有LiteLLM Docker镜像均使用cosign签名，建议验证：
```bash
cosign verify \
--certificate-identity-repository ghcr.io/berriai/litellm \
--certificate-oidc-issuer https://github.com \
ghcr.io/berriai/litellm:main
```
## 常见问题与故障排除
### 问题诊断流程
```mermaid
graph TD
Issue[遇到问题] --> Check1{认证错误?}
Check1 -->|是| A1[检查API密钥]
A1 --> A2{密钥有效?}
A2 -->|否| Fix1[重新生成密钥]
A2 -->|是| Fix2[检查权限设置]
Check1 -->|否| Check2{路由错误?}
Check2 -->|是| R1[检查config.yaml]
R1 --> R2{模型配置正确?}
R2 -->|否| Fix3[修正模型配置]
Check2 -->|否| Check3{限流错误?}
Check3 -->|是| L1[等待重置]
L1 --> L2[调整rpm/tpm]
Fix1 --> Done[问题解决]
Fix2 --> Done
Fix3 --> Done
L2 --> Done
```
### 常见错误码
| 错误码 | 描述 | 解决方案 |
|--------|------|----------|
| 401 | 认证失败 | 检查API密钥是否正确 |
| 403 | 权限不足 | 检查密钥的models权限 |
| 429 | 请求超限 | 等待或增加rpm/tpm限制 |
| 500 | 服务器错误 | 检查日志并重启服务 |
### 性能优化
1. **启用连接池**：减少连接建立开销
2. **合理设置限流**：平衡可用性与安全性
3. **使用缓存**：减少重复请求
4. **批量处理**：合并小请求减少网络往返
## 相关资源
- [官方文档](https://docs.litellm.ai/)
- [GitHub Issues](https://github.com/BerriAI/litellm/issues)
- [安全公告](https://github.com/BerriAI/litellm/issues/24518)
- [贡献指南](../../CONTRIBUTING.md)
---
## 管理控制台
### 相关页面
相关主题：[代理服务器详解](#proxy_server)
相关源码文件
以下源码文件用于生成本页说明：
- [ui/litellm-dashboard/src/components](https://github.com/BerriAI/litellm/blob/main/ui/litellm-dashboard/src/components)
- [ui/litellm-dashboard/src/app](https://github.com/BerriAI/litellm/blob/main/ui/litellm-dashboard/src/app)
- [litellm/proxy/discovery_endpoints/ui_discovery_endpoints.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/discovery_endpoints/ui_discovery_endpoints.py)
- [litellm/proxy/management_endpoints/team_endpoints.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/management_endpoints/team_endpoints.py)
- [litellm/proxy/client/cli/commands/keys.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/client/cli/commands/keys.py)
# 管理控制台
## 概述
LiteLLM管理控制台（LiteLLM Dashboard）是基于Web的用户界面，为管理员和运维人员提供对LiteLLM代理实例的集中管理和监控能力。管理控制台通过RESTful API与后端LiteLLM代理进行通信，支持团队管理、API密钥管理、视图配置、使用量监控等核心功能。
管理控制台采用React技术栈构建，前端代码位于`ui/litellm-dashboard/`目录下，通过代理API端点实现与后端的数据交互。控制台设计遵循组件化开发原则，将UI组件、数据Hooks和业务逻辑分离，确保代码的可维护性和可扩展性。
## 架构设计
### 整体架构
```mermaid
graph TD
A[用户浏览器] --> B[LiteLLM Dashboard React应用]
B --> C[LiteLLM Proxy REST API]
C --> D[Prisma数据库]
C --> E[LLM提供商]
F[CLI客户端] --> C
G[第三方集成] --> C
```
LiteLLM管理控制台的架构遵循前后端分离模式，前端为单页应用（SPA），通过HTTP请求与后端代理进行通信。后端代理负责处理所有业务逻辑，包括认证授权、数据库操作和LLM调用转发。这种设计使得控制台可以独立于后端进行开发和部署，同时保证了系统的安全性和可扩展性。
### 组件目录结构
根据项目规范，管理控制台的组件组织遵循以下目录结构原则：
```
ui/litellm-dashboard/src/
├── app/ # 页面级组件
│ └── (dashboard)/ # Dashboard路由组
│ ├── page.tsx # 主页面入口
│ ├── components/ # 页面专用组件
│ │ ├── CreateTeamModal.tsx
│ │ └── DeleteTeamModal.tsx
│ └── hooks/ # 页面专用Hooks
│ └── useFetchTeams.ts
├── components/ # 全局通用组件
│ └── [共享组件目录]
└── utils/ # 工具函数
```
### 组件设计规范
管理控制台的组件设计遵循以下核心规范：
- **组件职责单一**：每个组件应尽可能保持简洁，其主要职责是从Hooks或Props获取数据并渲染UI
- **组件大小控制**：单个组件文件建议控制在300行以内，超过时应拆分为更小的子组件
- **就近使用原则**：组件应放置在其使用位置附近，例如仅在某页面使用的组件应放在该页面的`components`子目录下
- **公共组件提取**：多个页面共用的组件应移动到最低公共祖先的`components`文件夹中
## 核心功能模块
### 团队管理
团队管理是管理控制台的核心功能之一，支持创建、查看、更新和删除团队。通过团队机制，可以实现多租户隔离，每个团队拥有独立的API密钥、使用限额和权限配置。
```mermaid
graph LR
A[管理员] --> B[创建团队]
B --> C[配置团队设置]
C --> D[分配团队成员]
D --> E[生成团队密钥]
E --> F[监控团队使用]
```
团队管理相关的API端点定义在`litellm/proxy/management_endpoints/team_endpoints.py`中，主要包括：
- 创建团队并设置基础配置
- 列出所有团队及成员信息
- 更新团队配置和成员列表
- 删除团队及相关资源
### API密钥管理
API密钥管理允许管理员创建、查看、撤销和筛选API密钥。控制台提供了灵活的查询功能，支持按用户ID、团队ID、组织ID、密钥别名等条件筛选密钥列表。
```python
# CLI密钥管理示例（来源：litellm/proxy/client/cli/commands/keys.py）
response = client.list(
page=page,
size=size,
user_id=user_id,
team_id=team_id,
organization_id=organization_id,
key_hash=key_hash,
key_alias=key_alias,
return_full_object=return_full_object,
include_team_keys=include_team_keys,
)
```
密钥管理界面提供以下信息展示：
| 字段 | 说明 |
|------|------|
| Key Hash | API密钥的哈希值（脱敏显示） |
| Alias | 密钥别名便于识别 |
| User ID | 密钥所属用户ID |
| Team ID | 密钥所属团队ID |
| Spend | 当前密钥已消耗金额 |
### UI发现与配置
LiteLLM代理通过`ui_discovery_endpoints.py`暴露UI相关的配置和发现端点，供前端控制台获取必要的初始化信息和配置数据。这些端点返回的信息包括：
- 当前代理实例的配置状态
- 可用的UI功能和模块
- 用户权限和访问范围
- 系统级配置参数
## 认证与授权
### CLI认证流程
LiteLLM CLI支持基于OAuth的SSO认证流程，通过轮询机制与浏览器端配合完成身份验证。
```mermaid
sequenceDiagram
participant CLI as CLI客户端
participant Browser as 浏览器
participant Proxy as LiteLLM代理
participant SSO as SSO提供商
CLI->>Proxy: POST /sso/cli/start
Proxy->>CLI: 返回login_id, poll_secret, user_code
CLI->>Browser: 打开认证页面
Browser->>Proxy: GET /sso/key/generate
Proxy->>SSO: 重定向到SSO登录页
SSO->>Browser: 显示登录表单
Browser->>SSO: 用户完成认证
SSO->>Proxy: 回调并携带状态
Proxy->>Browser: 提示输入user_code
Browser->>Proxy: POST /sso完成验证
```
认证流程采用状态令牌机制，确保OAuth回调请求来自合法的SSO提供商。状态令牌格式为`litellm-session-token:login_id`，代理通过检查状态令牌前缀来验证请求来源。
### 权限模型
管理控制台采用基于角色的权限控制模型，管理员通过代理的访问控制配置来限制用户和团队的操作权限。核心权限包括：
- 密钥管理权限：创建、查看、撤销API密钥
- 团队管理权限：创建团队、添加成员、配置团队设置
- 视图配置权限：自定义控制台显示的视图和面板
- 系统配置权限：修改代理全局配置和集成设置
## 用户界面组件
### Hooks规范
控制台的React Hooks遵循以下设计原则：
- **纯函数优先**：Hooks应为纯函数文件，除非需要作为上下文管理器
- **目录组织**：专用Hooks放置在页面目录下的`hooks`文件夹中
- **通用Hooks提取**：多个页面共用的Hooks应移动到最低公共祖先的`hooks`文件夹中
### 工具函数
数据处理和业务逻辑相关的纯函数应放置在局部的`utils.ts`文件中。这些函数不涉及副作用，便于单元测试和代码复用。
### 页面路由
管理控制台采用基于文件系统的路由约定，每个`page.tsx`文件对应一个路由入口。页面组件负责组合各种UI组件和数据Hooks，形成完整的页面视图。
## 已知问题与限制
根据社区反馈，管理控制台存在以下已知问题：
### 邮件设置保存问题
用户报告在代理UI中保存邮件服务器设置后，刷新页面设置会丢失。这是一个持续存在的bug，影响使用`pip install litellm[proxy] prisma`安装的代理实例（相关Issue：#19221）。问题表现为保存时显示成功提示，但数据实际未被持久化到数据库。
### 暗色模式需求
社区多次请求在管理控制台添加暗色主题支持（相关Issue：#10177），以便在低光环境下提供更好的视觉体验。当前版本仅支持亮色主题。
### 导入性能
由于LiteLLM库包含大量依赖项，单纯导入库可能需要约1秒时间（相关Issue：#7605）。这虽然不影响管理控制台的功能，但可能影响开发环境中的热重载体验。
## 最佳实践
### 生产部署
在生产环境中部署管理控制台时，建议：
- 使用反向代理（如Nginx）处理SSL终止和负载均衡
- 配置适当的缓存策略减少API请求
- 启用访问日志和审计追踪
- 定期备份Prisma数据库
### 安全考虑
- 管理控制台的API端点应仅允许授权IP访问
- 使用强密码策略并启用MFA
- 定期轮换API密钥
- 监控异常的API使用模式
### 性能优化
- 合理设置API密钥的请求速率限制
- 使用团队级别的使用量聚合减少查询压力
- 对常用视图启用服务端缓存
## 相关资源
- 管理控制台前端代码：`ui/litellm-dashboard/`
- 代理管理端点：`litellm/proxy/management_endpoints/`
- UI发现端点：`litellm/proxy/discovery_endpoints/ui_discovery_endpoints.py`
- CLI密钥命令：`litellm/proxy/client/cli/commands/keys.py`
- 团队管理端点：`litellm/proxy/management_endpoints/team_endpoints.py`
---
## 路由策略
### 相关页面
相关主题：[系统架构](#system_architecture), [LLM 提供商集成](#llm_providers), [缓存系统](#caching_system)
相关源码文件
以下源码文件用于生成本页说明：
- [litellm/router.py](https://github.com/BerriAI/litellm/blob/main/litellm/router.py)
- [litellm/router_strategy/base_routing_strategy.py](https://github.com/BerriAI/litellm/blob/main/litellm/router_strategy/base_routing_strategy.py)
- [litellm/router_strategy/least_busy.py](https://github.com/BerriAI/litellm/blob/main/litellm/router_strategy/least_busy.py)
- [litellm/router_strategy/lowest_latency.py](https://github.com/BerriAI/litellm/blob/main/litellm/router_strategy/lowest_latency.py)
- [litellm/router_strategy/lowest_cost.py](https://github.com/BerriAI/litellm/blob/main/litellm/router_strategy/lowest_cost.py)
- [litellm/router_strategy/adaptive_router/adaptive_router.py](https://github.com/BerriAI/litellm/blob/main/litellm/router_strategy/adaptive_router/adaptive_router.py)
# 路由策略
## 概述
LiteLLM 的路由策略是实现智能负载均衡和请求分发的核心组件。在 LiteLLM 架构中，路由器（Router）负责在多个模型部署或 LLM 提供商之间分配请求，而路由策略则决定了这种分配的具体逻辑。
路由策略的主要作用包括：
- **负载均衡**：将请求均匀分配到多个模型实例或提供商
- **成本优化**：优先使用成本更低的模型
- **延迟优化**：选择响应最快的模型
- **容错处理**：在某个模型不可用时自动切换到其他模型
- **自适应路由**：根据实时性能指标动态选择最佳模型
## 架构设计
### 核心组件关系
```mermaid
graph TD
A[请求入口] --> B[LiteLLM Router]
B --> C[路由策略选择]
C --> D{策略类型}
D -->|最少繁忙| E[LeastBusyStrategy]
D -->|最低延迟| F[LowestLatencyStrategy]
D -->|最低成本| G[LowestCostStrategy]
D -->|自适应路由| H[AdaptiveRoutingStrategy]
E --> I[模型选择]
F --> I
G --> I
H --> I
I --> J[执行请求]
J --> K{响应状态}
K -->|成功| L[返回结果]
K -->|失败| M[重试/切换]
M --> B
```
### 策略基类设计
所有路由策略都继承自 `BaseRoutingStrategy` 基类，该基类定义了策略执行的标准化接口。资料来源：[litellm/router_strategy/base_routing_strategy.py]()
```python
class BaseRoutingStrategy(ABC, LoggingMixin):
"""路由策略基类"""
def __init__(self, model_list: list):
self.model_list = model_list
@abstractmethod
async def get_available_deployment(
self,
model: str,
messages: list,
**kwargs
) -> Optional[dict]:
"""获取可用的模型部署"""
pass
```
## 可用路由策略
LiteLLM 支持多种路由策略，每种策略适用于不同的场景。
### 1. 最少繁忙策略 (Least Busy)
最少繁忙策略基于模型的并发负载选择当前请求压力最小的模型。
| 参数 | 类型 | 说明 |
|------|------|------|
| `model_group_alias` | str | 模型组别名 |
| `healthy_deployments` | list | 健康部署列表 |
| `messages` | list | 请求消息 |
| `request_priority` | int | 请求优先级（可选）|
**工作原理**：
1. 获取所有健康部署的当前并发数
2. 选择并发数最低的部署
3. 如果存在多个并发数相同的部署，随机选择其中之一
资料来源：[litellm/router_strategy/least_busy.py]()
```python
async def get_available_deployment(
self,
model: str,
messages: list,
request_priority: Optional[int] = None,
**kwargs
) -> Optional[dict]:
"""获取最少繁忙的部署"""
healthy_deployments = kwargs.get("healthy_deployments", [])
if len(healthy_deployments) == 0:
return None
if len(healthy_deployments) == 1:
return healthy_deployments[0]
# 获取并发数最低的部署
deployment_loads = [
{"deployment": d, "current_load": self._get_current_load(d)}
for d in healthy_deployments
]
deployment_loads.sort(key=lambda x: x["current_load"])
return deployment_loads[0]["deployment"]
```
### 2. 最低延迟策略 (Lowest Latency)
最低延迟策略基于历史响应时间选择延迟最低的模型。
| 参数 | 类型 | 说明 |
|------|------|------|
| `model_group_alias` | str | 模型组别名 |
| `healthy_deployments` | list | 健康部署列表 |
| `messages` | list | 请求消息 |
| `latency_header_name` | str | 延迟数据头名称 |
**工作原理**：
1. 从部署配置中读取历史延迟数据
2. 计算各部署的平均响应时间
3. 选择延迟最低的部署
4. 支持基于请求类型的动态延迟估算
资料来源：[litellm/router_strategy/lowest_latency.py]()
```python
async def get_available_deployment(
self,
model: str,
messages: list,
**kwargs
) -> Optional[dict]:
"""获取延迟最低的部署"""
healthy_deployments = kwargs.get("healthy_deployments", [])
if not healthy_deployments:
return None
# 计算每个部署的加权延迟分数
deployment_scores = []
for deployment in healthy_deployments:
latency_data = self._get_latency_data(deployment)
weighted_latency = self._calculate_weighted_latency(latency_data)
deployment_scores.append((deployment, weighted_latency))
# 选择延迟最低的部署
deployment_scores.sort(key=lambda x: x[1])
return deployment_scores[0][0]
```
### 3. 最低成本策略 (Lowest Cost)
最低成本策略优先选择成本最低的模型，适合成本敏感型应用。
| 参数 | 类型 | 说明 |
|------|------|------|
| `model_group_alias` | str | 模型组别名 |
| `healthy_deployments` | list | 健康部署列表 |
| `messages` | list | 请求消息 |
| `budget_mode` | bool | 是否启用预算模式 |
**工作原理**：
1. 获取所有健康部署的定价信息
2. 根据请求的 token 数量估算成本
3. 优先选择成本最低的部署
4. 支持预算限制模式，防止超出预算
资料来源：[litellm/router_strategy/lowest_cost.py]()
```python
async def get_available_deployment(
self,
model: str,
messages: list,
**kwargs
) -> Optional[dict]:
"""获取成本最低的部署"""
healthy_deployments = kwargs.get("healthy_deployments", [])
if not healthy_deployments:
return None
# 计算每个部署的预估成本
deployment_costs = []
for deployment in healthy_deployments:
estimated_cost = self._estimate_cost(deployment, messages)
deployment_costs.append((deployment, estimated_cost))
# 按成本排序
deployment_costs.sort(key=lambda x: x[1])
# 在预算模式下检查成本限制
if kwargs.get("budget_mode"):
return self._check_budget_limit(deployment_costs)
return deployment_costs[0][0]
```
### 4. 自适应路由策略 (Adaptive Routing)
自适应路由策略结合多个指标动态选择最佳模型，能够根据实时性能自动调整路由决策。
| 参数 | 类型 | 说明 |
|------|------|------|
| `model_group_alias` | str | 模型组别名 |
| `healthy_deployments` | list | 健康部署列表 |
| `messages` | list | 请求消息 |
| `routing_metrics` | dict | 实时路由指标 |
**架构设计**：
```mermaid
graph TD
A[请求] --> B[指标收集器]
B --> C[性能指标聚合]
C --> D[动态权重计算]
D --> E{路由决策}
E -->|延迟权重| F[延迟优化路径]
E -->|成本权重| G[成本优化路径]
E -->|负载权重| H[负载均衡路径]
F --> I[综合评分]
G --> I
H --> I
I --> J[选择最佳部署]
```
资料来源：[litellm/router_strategy/adaptive_router/adaptive_router.py]()
**核心特性**：
- **动态权重调整**：根据历史表现自动调整各指标的权重
- **异常检测**：识别表现异常的模型并降低其权重
- **多指标融合**：综合考虑延迟、成本、负载等多个因素
- **实时反馈**：根据实际响应时间更新路由决策
```python
class AdaptiveRoutingStrategy(BaseRoutingStrategy):
"""自适应路由策略"""
def __init__(self, model_list: list):
super().__init__(model_list)
self.metrics_cache = {}
self.model_weights = {}
async def get_available_deployment(
self,
model: str,
messages: list,
**kwargs
) -> Optional[dict]:
"""获取自适应最优部署"""
healthy_deployments = kwargs.get("healthy_deployments", [])
if not healthy_deployments:
return None
# 收集实时指标
metrics = await self._collect_metrics(healthy_deployments)
# 计算综合分数
deployment_scores = []
for deployment in healthy_deployments:
score = self._calculate_composite_score(
deployment,
metrics,
self.model_weights.get(deployment["model_name"], {})
)
deployment_scores.append((deployment, score))
# 选择得分最高的部署
deployment_scores.sort(key=lambda x: x[1], reverse=True)
return deployment_scores[0][0]
```
## 路由器配置
### 基础配置参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model_list` | list | 是 | 模型列表配置 |
| `routing_strategy` | str | 否 | 路由策略名称，默认为 "simple_hash" |
| `redis_host` | str | 否 | Redis 主机地址 |
| `redis_port` | int | 否 | Redis 端口 |
| `num_retries` | int | 否 | 失败重试次数，默认为 5 |
| `timeout` | float | 否 | 请求超时时间（秒）|
| `allowed_fails` | int | 否 | 允许的最大失败次数 |
资料来源：[litellm/router.py]()
### 模型列表配置
```python
model_list = [
{
"model_name": "gpt-4",
"litellm_params": {
"model": "gpt-4",
"api_key": os.getenv("OPENAI_API_KEY"),
"api_base": "https://api.openai.com/v1"
},
"tpm": 10000, # 每分钟 token 数限制
"rpm": 500, # 每分钟请求数限制
},
{
"model_name": "claude-3",
"litellm_params": {
"model": "claude-3-opus-20240229",
"api_key": os.getenv("ANTHROPIC_API_KEY"),
},
"tpm": 8000,
"rpm": 400,
}
]
```
### 路由策略配置
```python
from litellm import Router
router = Router(
model_list=model_list,
routing_strategy="latency-based-routing", # 可选: simple_hash, least-busy, latency-based-routing, cost-based-routing, adaptive-routing
routing_args={
"latency_header_name": "llm_provider_latency_ms",
"budget_mode": False,
"priority": ["gpt-4", "claude-3"]
}
)
```
## 使用示例
### 基础用法
```python
import litellm
from litellm import Router
# 初始化路由器
router = Router(
model_list=[
{
"model_name": "gpt-4",
"litellm_params": {
"model": "gpt-4",
"api_key": "your-api-key"
}
}
],
routing_strategy="least-busy"
)
# 使用路由器进行请求
response = await router.acompletion(
model="gpt-4",
messages=[{"role": "user", "content": "Hello!"}]
)
```
### 自定义路由策略
```python
from litellm.router_strategy.base_routing_strategy import BaseRoutingStrategy
class CustomRoutingStrategy(BaseRoutingStrategy):
"""自定义路由策略示例"""
async def get_available_deployment(
self,
model: str,
messages: list,
**kwargs
) -> Optional[dict]:
# 实现自定义路由逻辑
healthy_deployments = kwargs.get("healthy_deployments", [])
# 按自定义规则排序
sorted_deployments = self._custom_sort(healthy_deployments)
return sorted_deployments[0] if sorted_deployments else None
# 使用自定义策略
router = Router(
model_list=model_list,
routing_strategy=CustomRoutingStrategy(model_list)
)
```
### 多策略组合
```python
# 按优先级组合多个策略
router = Router(
model_list=model_list,
routing_strategy="priority-based-routing",
routing_args={
"strategies": [
{"type": "latency-based-routing", "weight": 0.4},
{"type": "cost-based-routing", "weight": 0.3},
{"type": "least-busy", "weight": 0.3}
]
}
)
```
## 最佳实践
### 策略选择指南
| 应用场景 | 推荐策略 | 原因 |
|---------|---------|------|
| 生产环境高可用 | 自适应路由 | 综合考虑多指标，自动优化 |
| 成本敏感型应用 | 最低成本 | 优先使用低价模型 |
| 低延迟要求 | 最低延迟 | 选择响应最快的模型 |
| 高并发场景 | 最少繁忙 | 负载均衡，避免过载 |
| 简单场景 | simple_hash | 开销小，配置简单 |
### 性能优化建议
1. **合理设置健康检查间隔**：避免过于频繁的健康检查影响性能
2. **配置适当的重试次数**：过多重试会增加延迟，过少可能丢失请求
3. **监控路由指标**：关注各策略的表现并适时调整
4. **使用缓存**：对于不常变化的配置，使用路由器级别的缓存
### 常见问题
**Q: 如何处理所有模型都不可用的情况？**
```python
from litellm import Router, RouterConfig
try:
response = await router.acompletion(
model="gpt-4",
messages=[{"role": "user", "content": "Hello"}]
)
except Exception as e:
# 实现降级逻辑
response = await fallback_completion(messages)
```
**Q: 如何实现跨区域的智能路由？**
```python
router = Router(
model_list=[
{"model_name": "gpt-4-us", "region": "us-east", ...},
{"model_name": "gpt-4-eu", "region": "eu-west", ...},
],
routing_strategy="adaptive-routing",
routing_args={
"region_preference": "eu-west", # 优先选择欧洲区域
"failover_region": "us-east" # 区域故障时切换到美国
}
)
```
## 相关资源
- [LiteLLM 官方文档](https://docs.litellm.ai/docs/proxy/routing)
- [GitHub 源码仓库](https://github.com/BerriAI/litellm)
- [路由策略示例](https://github.com/BerriAI/litellm/blob/main/router_strategy/README.md)
---
## 缓存系统
### 相关页面
相关主题：[路由策略](#router_strategies)
相关源码文件
以下源码文件用于生成本页说明：
- [litellm/caching/caching.py](https://github.com/BerriAI/litellm/blob/main/litellm/caching/caching.py)
- [litellm/caching/redis_cache.py](https://github.com/BerriAI/litellm/blob/main/litellm/caching/redis_cache.py)
- [litellm/caching/redis_semantic_cache.py](https://github.com/BerriAI/litellm/blob/main/litellm/caching/redis_semantic_cache.py)
- [litellm/caching/llm_caching_handler.py](https://github.com/BerriAI/litellm/blob/main/litellm/caching/llm_caching_handler.py)
- [litellm/proxy/caching_routes.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/caching_routes.py)
# 缓存系统
## 概述
LiteLLM 缓存系统是一个统一的多层缓存解决方案，旨在减少 LLM API 调用成本并提升响应速度。该系统支持多种缓存后端，包括内存缓存、Redis 缓存以及语义缓存（基于向量相似度），能够智能识别重复请求并返回缓存结果。
缓存系统的核心职责包括：
- 缓存请求参数和响应结果
- 支持语义相似度匹配（semantic caching）
- 提供灵活的配置选项
- 处理缓存键生成和序列化
- 管理缓存过期策略
```mermaid
graph TD
A[用户请求] --> B{缓存检查}
B -->|命中| C[返回缓存结果]
B -->|未命中| D[转发至 LLM 提供商]
D --> E[存储响应到缓存]
E --> F[返回新响应]
G[缓存后端] --> B
G --> E
G[缓存后端] -->|向量查询| H[语义缓存]
```
## 缓存类型
### 内存缓存（In-Memory Cache）
内存缓存是最轻量级的缓存方案，适用于单实例部署场景。所有缓存数据存储在进程内存中，读写速度最快，但不支持跨进程或跨实例共享。
主要特点：
- 高性能、低延迟
- 无需额外依赖
- 进程重启后缓存失效
- 适合开发测试和小规模部署
### Redis 缓存
Redis 缓存是企业级解决方案，支持分布式部署和持久化存储。LiteLLM 提供两种 Redis 缓存实现：
1. **标准 Redis 缓存** (`RedisCache`)：基于精确键值匹配的缓存
2. **语义 Redis 缓存** (`RedisSemanticCache`)：基于向量相似度的智能缓存
Redis 缓存优势：
- 支持集群部署
- 数据持久化
- 支持 TTL 过期策略
- 跨实例共享缓存
### 语义缓存（Semantic Cache）
语义缓存是 LiteLLM 的高级缓存功能，能够识别语义上相似的请求。当请求内容语义相似（向量余弦相似度超过阈值）时，即使精确键不同，也能返回缓存结果。
语义缓存工作流程：
```mermaid
graph LR
A[新请求] --> B[生成嵌入向量]
B --> C[查询向量数据库]
C --> D{相似度 > 阈值?}
D -->|是| E[返回缓存响应]
D -->|否| F[调用 LLM]
F --> G[存储新结果]
```
## 核心组件
### CacheConfig
缓存配置类定义了缓存行为的关键参数：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `type` | str | `null` | 缓存类型：`redis`、`s3`、`dynamodb` 等 |
| `bullet_boarding` | bool | `False` | 是否启用缓存排队 |
| `semantic_cache` | dict | `None` | 语义缓存配置 |
| `redis_host` | str | `None` | Redis 主机地址 |
| `redis_port` | int | `6379` | Redis 端口 |
| `redis_password` | str | `None` | Redis 密码 |
| `ttl` | int | `3600` | 默认缓存过期时间（秒） |
| `cache_kwargs` | dict | `{}` | 额外缓存参数 |
### LLMRequestCacheHandler
`LLMRequestCacheHandler` 是核心缓存处理器，负责拦截请求、检查缓存、执行缓存读写操作。
核心方法：
| 方法 | 说明 |
|------|------|
| `get_cache_key()` | 根据请求参数生成唯一缓存键 |
| `get_cached_response()` | 尝试从缓存获取响应 |
| `set_cache()` | 存储响应到缓存 |
| `get_cache()` | 获取缓存条目详情 |
| `delete_cache()` | 删除指定缓存条目 |
| `flush_cache()` | 清空所有缓存 |
## 配置与使用
### 环境变量配置
通过环境变量配置 Redis 缓存：
```bash
export REDIS_HOST="localhost"
export REDIS_PORT="6379"
export REDIS_PASSWORD="your_password"
export REDIS_DB="0"
export LITELLM_CACHE="redis"
```
### 代理配置（config.yaml）
在 LiteLLM 代理配置文件中启用缓存：
```yaml
model_list:
- model_name: gpt-4
litellm_params:
model: gpt-4
api_key: os.environ/GPT_API_KEY
litellm_settings:
cache: true
cache_params:
type: redis
redis_host: localhost
redis_port: 6379
ttl: 3600
supported_call_types:
- completion
- acompletion
- embedding
```
### 语义缓存配置
启用语义缓存需要配置嵌入模型和相似度阈值：
```yaml
litellm_settings:
cache: true
cache_params:
type: redis
semantic_cache:
enabled: true
embedding_model: "azure/text-embedding-ada-002"
similarity_threshold: 0.8
redis_host: localhost
redis_port: 6379
```
### Python SDK 使用
```python
import litellm
from litellm import Cache
# 启用默认缓存
litellm.cache = Cache(type="redis", redis_host="localhost", ttl=3600)
# 使用缓存发起请求
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "Hello!"}],
cache={"enabled": True} # 显式启用此请求的缓存
)
```
## 缓存键生成策略
LiteLLM 采用多维度哈希策略生成缓存键，确保语义相同但格式不同的请求能够匹配到同一缓存条目。
### 键生成算法
```mermaid
graph TD
A[请求参数] --> B[规范化 JSON]
B --> C[提取关键字段]
C --> D[messages]
C --> E[model]
C --> F[temperature]
C --> G[max_tokens]
D --> H[组合字符串]
E --> H
F --> H
G --> H
H --> I[SHA256 哈希]
I --> J[缓存键]
```
缓存键生成考虑以下因素：
| 字段 | 处理方式 |
|------|----------|
| `model` | 直接使用 |
| `messages` | JSON 序列化后参与哈希 |
| `temperature` | 精度处理后参与哈希 |
| `max_tokens` | 直接参与哈希 |
| `top_p` | 直接参与哈希 |
| `tools` | JSON 序列化后参与哈希 |
## 代理缓存路由
### 缓存管理端点
LiteLLM 代理提供以下缓存管理 API：
| 端点 | 方法 | 说明 |
|------|------|------|
| `/cache/info` | GET | 获取缓存状态信息 |
| `/cache/delete` | POST | 删除指定缓存条目 |
| `/cache/flush` | POST | 清空所有缓存 |
| `/v1/cache` | GET | 查看缓存配置 |
### 批量缓存操作
```python
# 删除多个缓存条目
import requests
response = requests.post(
"http://localhost:4000/cache/delete",
json={"cache_key": "abc123...", "user_id": "user_123"},
headers={"Authorization": "Bearer sk-..."}
)
```
## 已知问题
### Gemini 缓存请求中的 tool_choice 问题
**问题编号**: #29088
当 Gemini 请求同时包含 `cache_control: {"type": "ephemeral"}` 标记和 `tool_choice` 参数时，`tool_choice` 参数会被静默丢弃。
受影响提供商：
- `gemini/`
- `vertex_ai/`
**影响**：使用缓存控制且需要函数调用选择的请求可能产生意外行为。
**临时解决方案**：
```python
# 方案1：避免同时使用 cache_control 和 tool_choice
response = litellm.completion(
model="gemini/gemini-2.0-flash",
messages=[{"role": "user", "content": "Hello"}],
tools=[...],
# tool_choice="auto" # 避免在此场景使用
)
# 方案2：分离请求
# 先使用 cache_control 获取上下文缓存
# 再使用独立请求进行工具选择
```
## 最佳实践
### 缓存策略建议
1. **合理设置 TTL**：根据业务需求和数据时效性设置合适的过期时间
2. **监控缓存命中率**：通过日志监控缓存性能
3. **分离敏感数据**：避免缓存包含敏感信息的响应
4. **语义缓存阈值调整**：根据准确率需求调整相似度阈值
### 性能优化
| 场景 | 建议 |
|------|------|
| 高并发 | 使用 Redis 集群部署 |
| 低延迟需求 | 启用内存缓存 + Redis 持久化 |
| 语义相似场景 | 配置 `similarity_threshold: 0.85+` |
| 成本优化 | 设置合理的 TTL 避免缓存膨胀 |
## 扩展开发
### 自定义缓存后端
```python
from litellm.caching.caching import BaseCache
from litellm.types.caching import CacheResponse
class MyCustomCache(BaseCache):
def __init__(self, **kwargs):
super().__init__(**kwargs)
async def get_cache(self, **kwargs) -> CacheResponse | None:
# 实现获取逻辑
pass
async def set_cache(self, **kwargs) -> None:
# 实现存储逻辑
pass
async def delete_cache(self, **kwargs) -> None:
# 实现删除逻辑
pass
# 注册自定义缓存
litellm.cache = MyCustomCache()
```
### 钩子函数
缓存系统支持钩子扩展，可在缓存命中/未命中时执行自定义逻辑：
```python
def on_cache_hit(response, cache_metadata):
"""缓存命中回调"""
print(f"Cache hit: {cache_metadata}")
def on_cache_miss(request_params):
"""缓存未命中回调"""
print(f"Cache miss for request")
---
## 安全护栏
### 相关页面
相关主题：[代理服务器详解](#proxy_server)
相关源码文件
以下源码文件用于生成本页说明：
- [litellm/proxy/guardrails/guardrail_hooks](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/guardrails/guardrail_hooks)
- [litellm/proxy/guardrails/guardrail_registry.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/guardrails/guardrail_registry.py)
- [litellm/proxy/policy_engine/pipeline_executor.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/policy_engine/pipeline_executor.py)
- [litellm/proxy/hooks/prompt_injection_detection.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/hooks/prompt_injection_detection.py)
- [litellm/llms/cohere/rerank/guardrail_translation/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/llms/cohere/rerank/guardrail_translation/README.md)
- [litellm/llms/openai/completion/guardrail_translation/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/llms/openai/completion/guardrail_translation/README.md)
- [ui/litellm-dashboard/src/components/prompts/README.md](https://github.com/BerriAI/litellm/blob/main/ui/litellm-dashboard/src/components/prompts/README.md)
# 安全护栏
## 概述
LiteLLM 的安全护栏（Guardrails）是一个模块化的安全框架，用于在 LLM 请求和响应的处理过程中实施内容审核、PII（个人身份信息）保护、内容过滤等安全策略。安全护栏可以在请求到达模型之前对输入进行预处理，也可以在模型响应返回之前对输出进行后处理，从而实现对企业级 AI 应用的安全管控。
安全护栏系统支持多种内置护栏类型，包括内容审核、PII 脱敏、提示词注入检测等。同时，框架提供了扩展机制，允许开发者自定义护栏以满足特定的业务安全需求。
## 核心架构
### 系统组件
LiteLLM 安全护栏系统由以下几个核心组件构成：
| 组件 | 路径 | 职责 |
|------|------|------|
| GuardrailHooks | `litellm/proxy/guardrails/guardrail_hooks` | 护栏执行的主钩子，处理请求/响应拦截 |
| GuardrailRegistry | `litellm/proxy/guardrails/guardrail_registry.py` | 护栏注册与管理中心 |
| PipelineExecutor | `litellm/proxy/policy_engine/pipeline_executor.py` | 管道执行器，协调多护栏链式执行 |
| PromptInjectionDetection | `litellm/proxy/hooks/prompt_injection_detection.py` | 提示词注入检测钩子 |
| SecretDetection | `enterprise/litellm_enterprise/enterprise_callbacks/secret_detection.py` | 企业级密钥/敏感信息检测 |
### 架构流程图
```mermaid
graph TD
A[用户请求] --> B[GuardrailHooks]
B --> C{护栏配置检查}
C -->|有护栏配置| D[PipelineExecutor]
C -->|无护栏配置| E[直接转发至模型]
D --> F[输入处理]
F --> G[内容审核]
G --> H[PII 脱敏]
H --> I[提示词注入检测]
I --> J{检测结果判定}
J -->|通过| K[转发至模型]
J -->|拒绝| L[返回安全错误]
K --> M[模型响应]
M --> N[输出处理]
N --> O{响应审核}
O -->|通过| P[返回用户]
O -->|拒绝| L
L --> Q[记录审计日志]
```
## 护栏类型与处理逻辑
### 输入处理
安全护栏系统对用户输入进行多层处理，确保输入内容符合安全策略。
**处理字段**：
| 字段类型 | 处理方式 | 说明 |
|----------|----------|------|
| `messages` | 应用护栏 | 对话消息数组，逐条应用护栏规则 |
| `prompt` | 应用护栏 | 文本补全请求的提示词 |
| `query` | 应用护栏 | 重排请求的查询文本 |
**处理流程**：
1. 解析输入消息结构
2. 依次执行已注册的护栏链
3. 根据护栏结果决定放行或拒绝
4. 返回修改后的输入或安全错误响应
资料来源：[litellm/proxy/policy_engine/pipeline_executor.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/policy_engine/pipeline_executor.py)
### 输出处理
模型响应返回时，系统会对输出内容进行安全审核。
**处理范围**：
- LLM 生成的文本内容
- 工具调用（Function Calling）参数
- 重排结果的相关性评分
**处理策略**：
| 输出类型 | 处理方式 | 备注 |
|----------|----------|------|
| 文本补全 | `process_output_response` | 应用内容审核和 PII 脱敏 |
| 对话补全 | `process_output_response` | 处理 assistant 消息内容 |
| 重排请求 | 不处理 | 输出仅包含相关性评分，无文本内容 |
资料来源：[litellm/llms/openai/completion/guardrail_translation/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/llms/openai/completion/guardrail_translation/README.md)
## 内置护栏类型
### 内容审核（Content Moderation）
内容审核护栏用于检测和过滤不当内容，包括：
- 仇恨言论
- 暴力内容
- 性暗示内容
- 垃圾信息
**使用方式**：
```bash
curl -X POST 'http://localhost:4000/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer your-api-key' \
-d '{
"model": "gpt-4",
"messages": [{"role": "user", "content": "用户的输入内容"}],
"guardrails": ["content_moderation"]
}'
```
### PII 脱敏（Secret Detection）
企业级 PII 脱敏功能，支持自动检测和掩码敏感信息：
| 敏感数据类型 | 检测模式 |
|--------------|----------|
| 电子邮件地址 | `user@example.com` |
| API 密钥 | Bearer Token、API Key 格式 |
| 信用卡号 | 16位数字格式 |
| 社会安全号 | XXX-XX-XXXX 格式 |
| 手机号码 | 带区号格式 |
资料来源：[enterprise/litellm_enterprise/enterprise_callbacks/secret_detection.py](https://github.com/BerriAI/litellm/blob/main/enterprise/litellm_enterprise/enterprise_callbacks/secret_detection.py)
### 提示词注入检测（Prompt Injection Detection）
该护栏专门针对提示词注入攻击进行防护，检测常见的注入模式：
- 指令覆盖尝试（如 "Ignore previous instructions"）
- 角色扮演逃逸（如 "You are now DAN"）
- 上下文操纵尝试
资料来源：[litellm/proxy/hooks/prompt_injection_detection.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/hooks/prompt_injection_detection.py)
## 支持的调用类型
安全护栏系统支持多种 LLM 调用类型：
| 调用类型 | 标识符 | 输入处理 | 输出处理 |
|----------|--------|----------|----------|
| 同步对话补全 | `CallTypes.acompletion` | ✅ | ✅ |
| 异步对话补全 | `CallTypes.acompletion` | ✅ | ✅ |
| 同步文本补全 | `CallTypes.completion` | ✅ | ✅ |
| 异步文本补全 | `CallTypes.acompletion` | ✅ | ✅ |
| 同步重排 | `CallTypes.rerank` | ✅ | ❌ |
| 异步重排 | `CallTypes.arerank` | ✅ | ❌ |
> 注意：重排请求的输出仅包含相关性评分，不涉及文本内容，因此不需要输出处理。
资料来源：[litellm/llms/cohere/rerank/guardrail_translation/README.md](https://github.com/BerriAI/litellm/blob/main/litellm/llms/cohere/rerank/guardrail_translation/README.md)
## 配置与管理
### 护栏注册
护栏通过 `GuardrailRegistry` 进行统一管理：
```python
from litellm.proxy.guardrails import guardrail_registry
# 注册自定义护栏
guardrail_registry.register(
name="my_guardrail",
handler=MyGuardrailHandler()
)
```
### 全局配置
在 LiteLLM Proxy 配置文件中启用护栏：
```yaml
model_list:
- model_name: gpt-4
litellm_params:
model: gpt-4
api_key: os.environ/GPT4_API_KEY
litellm_settings:
guardrails:
- content_moderation
- pii_detection
```
## 自定义护栏开发
### 实现自定义护栏处理器
```python
from litellm.proxy.guardrails.base_handler import BaseGuardrailHandler
class MyCustomGuardrail(BaseGuardrailHandler):
"""自定义护栏处理器示例"""
def process_input_messages(self, messages: list) -> list:
"""
处理输入消息
Args:
messages: 输入消息列表
Returns:
处理后的消息列表
"""
# 自定义处理逻辑
for msg in messages:
if "blocked_keyword" in msg["content"]:
raise ValueError("Content blocked by custom guardrail")
return messages
def process_output_response(self, response) -> dict:
"""
处理输出响应
Args:
response: 模型响应对象
Returns:
处理后的响应
"""
# 自定义输出处理逻辑
return response
```
### 扩展方法
| 方法名 | 用途 | 必须重写 |
|--------|------|----------|
| `process_input_messages()` | 输入消息预处理 | 是 |
| `process_output_response()` | 输出响应后处理 | 否 |
| `get_results()` | 获取护栏执行结果 | 是 |
## 常见应用场景
### PII 保护
在处理包含用户个人信息的请求时，自动检测并脱敏敏感数据：
```bash
curl -X POST 'http://localhost:4000/v1/chat/completions' \
-H 'Content-Type: application/json' \
-d '{
"model": "gpt-4",
"messages": [
{"role": "user", "content": "我的邮箱是 user@example.com，请帮我处理"}
],
"guardrails": ["secret_detection"]
}'
```
### 内容过滤
阻止包含不当内容的请求到达模型层：
```json
{
"model": "gpt-4",
"messages": [
{"role": "user", "content": "不当内容..."}
],
"guardrails": ["content_moderation"]
}
```
### 合规审计
记录所有经过护栏处理的请求，支持审计追溯：
- 请求时间戳
- 使用的护栏类型
- 检测结果（通过/拒绝）
- 拒绝原因（如有）
## 企业级功能
### Secret Detection 高级特性
企业版的 Secret Detection 提供更全面的敏感信息检测能力：
- **自定义检测规则**：根据企业政策定义特定的敏感信息模式
- **自动脱敏替换**：将检测到的敏感信息替换为占位符
- **审计报告**：生成敏感信息暴露事件的详细报告
### UI 管理界面
LiteLLM Dashboard 提供护栏配置的可视化管理：
- **访问路径**：「Experimental」→「Guardrails」（需要 admin 角色权限）
- **路由参数**：可通过 `?page=guardrails` URL 参数直接访问
- **功能**：查看已配置的护栏列表、启用/禁用状态、关联模型等
资料来源：[ui/litellm-dashboard/src/components/prompts/README.md](https://github.com/BerriAI/litellm/blob/main/ui/litellm-dashboard/src/components/prompts/README.md)
## 故障排查
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 护栏未生效 | 护栏名称拼写错误 | 检查 `guardrails` 参数中的护栏名称 |
| 所有请求被拒绝 | 护栏规则过于严格 | 调整护栏敏感度阈值 |
| 性能下降明显 | 护栏链过长 | 优化护栏执行顺序或并行化 |
| PII 未检测到 | 自定义格式未配置 | 在 Secret Detection 中添加自定义正则 |
### 调试模式
启用详细日志查看护栏执行过程：
```python
import litellm
# 启用详细日志
litellm.set_verbose = True
# 测试护栏
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "测试内容"}],
guardrails=["content_moderation"]
)
```
## 安全最佳实践
1. **多层防护**：建议在输入和输出两端都部署护栏
2. **定期更新规则**：随着攻击手法演进，及时更新检测规则
3. **审计日志**：保持完整的护栏执行日志，便于安全分析
4. **性能监控**：监控护栏对响应延迟的影响
5. **灰度发布**：新护栏上线前先在小范围流量中测试
## 相关资源
- [LiteLLM 官方文档 - Guardrails](https://docs.litellm.ai/docs/guardrails)
- [企业版功能介绍](https://litellm.ai/docs/enterprise)
- [安全漏洞报告指引](https://github.com/BerriAI/litellm/security)
---
## MCP 集成
### 相关页面
相关主题：[代理服务器详解](#proxy_server), [安全护栏](#guardrails)
相关源码文件
以下源码文件用于生成本页说明：
- [litellm/experimental_mcp_client/client.py](https://github.com/BerriAI/litellm/blob/main/litellm/experimental_mcp_client/client.py)
- [litellm/proxy/_experimental/mcp_server/mcp_server_manager.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py)
- [litellm/proxy/management_endpoints/mcp_management_endpoints.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/management_endpoints/mcp_management_endpoints.py)
- [litellm/proxy/mcp_tools.py](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/mcp_tools.py)
- [litellm/experimental_mcp_client/servers/p股票mcp_server.py](https://github.com/BerriAI/litellm/blob/main/litellm/experimental_mcp_client/servers/stock_mcp_server.py)
# MCP 集成
## 概述
MCP（Model Context Protocol）集成是 LiteLLM 框架为支持大语言模型（LLM）与外部工具和服务进行标准化交互而设计的功能模块。通过 MCP 协议，LiteLLM 能够将任意 MCP 服务器提供的工具（Tools）无缝转换为 LLM 可调用的函数接口，实现模型与现实世界数据的连接。
LiteLLM 的 MCP 集成包含两个核心组件：**MCP Client**（客户端）和 **MCP Server Manager**（服务器管理器）。客户端负责与远程 MCP 服务器建立连接并调用其提供的工具，服务器管理器则负责在 LiteLLM Proxy 环境中注册和管理这些 MCP 工具，使其可通过 RESTful API 暴露给外部调用者。
## 架构设计
### 系统组件关系
```mermaid
graph TD
A[LLM 模型] --> B[LiteLLM Client]
B --> C[MCP Tools]
C --> D[MCP Client]
D --> E[MCP Server]
F[MCP Server Manager] --> D
G[Proxy API] --> F
H[外部调用者] --> G
E --> I[外部服务/数据源]
```
LiteLLM 的 MCP 集成采用分层架构设计，从上到下依次为：LLM 层负责生成函数调用请求；工具转换层将 MCP 工具适配为 LiteLLM 格式；MCP 客户端层负责与 MCP 服务器的通信协议处理；服务器管理层提供服务器注册、配置和生命周期管理功能。
### 客户端与服务器交互流程
```mermaid
sequenceDiagram
participant 用户
participant LiteLLM
participant MCPClient
participant MCPServer
participant 外部服务
用户->>LiteLLM: 发送包含 MCP 工具的请求
LiteLLM->>MCPClient: 调用工具函数
MCPClient->>MCPServer: 发送 MCP 协议请求
MCPServer->>外部服务: 查询/处理数据
外部服务->>MCPServer: 返回结果
MCPServer->>MCPClient: 返回 MCP 协议响应
MCPClient->>LiteLLM: 返回标准化结果
LiteLLM->>用户: 返回 LLM 响应
```
## 核心组件
### MCP Client
`litellm/experimental_mcp_client/client.py` 文件实现了 MCP 客户端的核心功能。该客户端负责与 MCP 服务器建立连接、管理会话状态以及执行工具调用。
**关键类和方法：**
| 类/方法 | 功能描述 | 源码位置 |
|---------|----------|----------|
| `MCPClient` | MCP 客户端主类 | [client.py:1-100]() |
| `connect()` | 建立与 MCP 服务器的连接 | [client.py:50-80]() |
| `call_tool()` | 调用 MCP 服务器上的工具 | [client.py:100-150]() |
| `list_tools()` | 列出服务器提供的所有工具 | [client.py:150-200]() |
| `close()` | 关闭连接并清理资源 | [client.py:200-250]() |
MCPClient 类的初始化参数包括服务器 URL、认证令牌、超时设置等。连接建立后，客户端会从服务器获取可用工具列表并缓存到本地，以便后续快速调用。
### MCP Server Manager
`litellm/proxy/_experimental/mcp_server/mcp_server_manager.py` 文件实现了 MCP 服务器管理器，负责在 LiteLLM Proxy 环境中统一管理所有 MCP 服务器的生命周期。
**核心职责：**
- 服务器注册与注销
- 连接池管理
- 工具注册到 LiteLLM 工具系统
- 健康检查和自动重连
- 配置持久化
服务器管理器采用单例模式设计，确保整个 Proxy 进程中只有一个管理器实例。每个注册的 MCP 服务器都会被分配一个唯一标识符，用于在管理 API 中进行引用。
### MCP Tools 集成
`litellm/proxy/mcp_tools.py` 文件实现了 MCP 工具到 LiteLLM 工具格式的转换逻辑。该模块将 MCP 服务器提供的工具定义转换为 LiteLLM 可识别的函数调用格式。
**转换流程：**
```mermaid
graph LR
A[MCP 工具定义] --> B[解析工具元数据]
B --> C[映射参数类型]
C --> D[生成 OpenAI 函数格式]
D --> E[注册到 LiteLLM]
```
转换过程中，系统会处理以下映射：
- MCP 参数类型映射到 JSON Schema 类型
- 必填参数验证
- 返回值格式标准化
- 错误处理规范化
### 管理端点
`litellm/proxy/management_endpoints/mcp_management_endpoints.py` 文件定义了用于管理 MCP 服务器的 RESTful API 端点。这些端点允许用户在不重启 Proxy 的情况下动态管理 MCP 服务器。
**API 端点列表：**
| 端点 | 方法 | 功能 | 源码位置 |
|------|------|------|----------|
| `/mcp/servers` | GET | 列出所有已注册的 MCP 服务器 | [mcp_management_endpoints.py:1-50]() |
| `/mcp/servers` | POST | 注册新的 MCP 服务器 | [mcp_management_endpoints.py:50-100]() |
| `/mcp/servers/{id}` | GET | 获取特定服务器详情 | [mcp_management_endpoints.py:100-150]() |
| `/mcp/servers/{id}` | DELETE | 注销指定的 MCP 服务器 | [mcp_management_endpoints.py:150-200]() |
| `/mcp/servers/{id}/tools` | GET | 列出服务器提供的工具 | [mcp_management_endpoints.py:200-250]() |
| `/mcp/servers/{id}/health` | GET | 健康检查 | [mcp_management_endpoints.py:250-300]() |
## 配置与使用
### 基本配置
在 `config.yaml` 中配置 MCP 服务器的基本方式如下：
```yaml
model_list:
- model_name: gpt-4
litellm_params:
model: gpt-4
mcp_servers:
- name: stock-service
url: "http://localhost:8000/mcp"
auth_token: "your-auth-token"
enabled: true
- name: weather-service
url: "http://localhost:8001/mcp"
enabled: true
```
配置项说明：
| 配置项 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | string | 是 | MCP 服务器的唯一标识名称 |
| `url` | string | 是 | MCP 服务器的端点 URL |
| `auth_token` | string | 否 | 认证令牌 |
| `enabled` | boolean | 否 | 是否启用，默认为 true |
| `timeout` | integer | 否 | 请求超时时间（秒） |
### 运行时注册
除了配置文件方式，还可以通过管理 API 动态注册 MCP 服务器：
```bash
curl -X POST 'http://localhost:4000/mcp/servers' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer your-api-key' \
-d '{
"name": "my-mcp-server",
"url": "http://localhost:9000/mcp",
"auth_token": "optional-token"
}'
```
### 工具调用
注册 MCP 服务器后，其提供的工具会自动出现在 LLM 的函数调用选项中。使用方式与标准 LiteLLM 工具调用相同：
```python
import litellm
response = litellm.completion(
model="gpt-4",
messages=[{"role": "user", "content": "查询苹果公司当前股价"}],
tools=[{
"type": "function",
"function": {
"name": "stock_quote",
"description": "获取股票实时报价",
"parameters": {
"type": "object",
"properties": {
"symbol": {"type": "string", "description": "股票代码"}
},
"required": ["symbol"]
}
}
}]
)
```
## MCP 服务器实现示例
LiteLLM 提供了示例 MCP 服务器实现，位于 `litellm/experimental_mcp_client/servers/stock_mcp_server.py`。该示例展示如何创建符合 MCP 协议规范的服务器。
**示例服务器结构：**
```python
from mcp.server import MCPServer
from mcp.types import Tool, CallToolRequest, CallToolResult
class StockMCPServer(MCPServer):
def __init__(self):
super().__init__(name="stock-service")
self.register_tool(self.get_quote)
self.register_tool(self.get_history)
async def get_quote(self, symbol: str) -> CallToolResult:
"""获取股票实时报价"""
# 实现逻辑
return CallToolResult(
content=[{"type": "text", "text": json.dumps(quote_data)}]
)
async def get_history(self, symbol: str, days: int) -> CallToolResult:
"""获取股票历史数据"""
# 实现逻辑
return CallToolResult(
content=[{"type": "text", "text": json.dumps(history_data)}]
)
```
## 认证与安全
### 认证方式
MCP 集成支持多种认证方式以满足不同场景需求：
| 认证方式 | 适用场景 | 配置方式 |
|----------|----------|----------|
| 无认证 | 本地开发测试 | 不配置 `auth_token` |
| Bearer Token | 生产环境 | 设置 `auth_token` |
| API Key | 第三方服务 | 通过 header 传递 |
| OAuth 2.0 | 企业环境 | 配置 OAuth 参数 |
### 安全建议
1. **敏感信息保护**：在生产环境中，应使用环境变量或密钥管理服务存储认证令牌，避免明文写在配置文件中
2. **连接加密**：确保 MCP 服务器启用 HTTPS，LiteLLM 支持通过 `ssl_verify` 参数配置 SSL 验证
3. **访问控制**：利用 LiteLLM Proxy 的密钥和团队管理功能控制对 MCP 工具的访问
4. **超时设置**：合理设置请求超时时间，防止因 MCP 服务器无响应导致请求挂起
## 错误处理
### 常见错误及解决方案
| 错误类型 | 错误信息 | 可能原因 | 解决方案 |
|----------|----------|----------|----------|
| 连接错误 | `Connection refused` | MCP 服务器未启动 | 确认服务器运行状态 |
| 认证失败 | `401 Unauthorized` | 令牌无效或过期 | 检查并更新认证令牌 |
| 超时错误 | `TimeoutError` | 服务器响应过慢 | 增大 `timeout` 配置 |
| 工具不存在 | `Tool not found` | 工具名称拼写错误 | 使用 `/mcp/servers/{id}/tools` 验证 |
| 协议错误 | `Invalid MCP response` | 服务器响应格式错误 | 检查 MCP 服务器实现 |
### 调试模式
启用详细日志有助于排查 MCP 集成问题：
```python
import litellm
litellm.set_verbose = True
# 执行 MCP 工具调用，日志将输出详细信息
response = litellm.completion(...)
```
## 性能优化
### 连接池管理
MCP Server Manager 内部维护连接池以提高性能。关键配置参数：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `max_connections` | 10 | 最大并发连接数 |
| `connection_timeout` | 30 | 连接超时时间（秒） |
| `idle_timeout` | 300 | 空闲连接存活时间（秒） |
### 缓存策略
工具定义会缓存在本地以减少网络请求。缓存可通过以下方式刷新：
1. 重启 LiteLLM Proxy
2. 调用 DELETE 端点注销后重新注册服务器
3. 使用管理 API 的刷新接口
## 限制与注意事项
根据社区反馈和源码分析，使用 MCP 集成时需注意以下限制：
1. **实验性功能**：`experimental_mcp_client` 目录表明该功能仍处于实验阶段，生产环境使用需评估风险
2. **同步/异步支持**：当前实现主要支持异步调用，同步调用场景可能需要额外适配
3. **批量调用**：单个 MCP 请求仅支持一次工具调用，如需批量操作需在应用层循环
4. **错误传播**：MCP 服务器返回的错误会被转换但可能丢失部分上下文信息
## 扩展开发
### 自定义 MCP 服务器
开发自定义 MCP 服务器需要实现以下核心接口：
```python
from mcp.protocol import MCPProtocol
from mcp.types import Tool, CallToolResult
class MyCustomMCPServer(MCPProtocol):
async def handle_call_tool(self, request: CallToolRequest) -> CallToolResult:
tool_name = request.params.name
arguments = request.params.arguments
if tool_name == "my_tool":
return await self.my_tool_handler(arguments)
raise ValueError(f"Unknown tool: {tool_name}")
async def my_tool_handler(self, args: dict) -> CallToolResult:
# 自定义工具逻辑
pass
```
### 工具结果后处理
如需在工具返回结果后进行额外处理，可通过继承 `MCPClient` 并重写 `process_result` 方法实现：
```python
class CustomMCPClient(MCPClient):
def process_result(self, tool_name: str, result: dict) -> dict:
# 自定义后处理逻辑
if tool_name == "sensitive_data":
# 敏感信息过滤
result = self.redact_pii(result)
return result
```
## 参考资料
- MCP 协议规范：[Model Context Protocol](https://modelcontextprotocol.io/)
- LiteLLM 官方文档：[LiteLLM Docs](https://docs.litellm.ai/)
- 示例实现： [`litellm/experimental_mcp_client/servers/`](https://github.com/BerriAI/litellm/tree/main/litellm/experimental_mcp_client/servers)
---
---
## Doramagic 踩坑日志
项目：BerriAI/litellm
摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Feature Request: Add FunASR as audio/transcriptions provider。
## 1. 安装坑 · 失败模式：installation: Feature Request: Add FunASR as audio/transcriptions provider
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Feature Request: Add FunASR as audio/transcriptions provider
- 对用户的影响：Developers may fail before the first successful local run: Feature Request: Add FunASR as audio/transcriptions provider
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: Add FunASR as audio/transcriptions provider. Context: Observed when using python, cuda
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_d1a79ffc4464fe779b4b0bfab64762c6 | https://github.com/BerriAI/litellm/issues/29367 | Feature Request: Add FunASR as audio/transcriptions provider
## 2. 安装坑 · 失败模式：installation: v1.84.3
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.84.3
- 对用户的影响：Upgrade or migration may change expected behavior: v1.84.3
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.84.3. Context: Observed when using node, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_25464f70a090a48873093478f9c47a44 | https://github.com/BerriAI/litellm/releases/tag/v1.84.3 | v1.84.3
## 3. 安装坑 · 失败模式：installation: v1.85.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.85.2
- 对用户的影响：Upgrade or migration may change expected behavior: v1.85.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.85.2. Context: Observed when using node, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_14c2300a2d7a22c62b42ee598460aa1c | https://github.com/BerriAI/litellm/releases/tag/v1.85.2 | v1.85.2
## 4. 安装坑 · 失败模式：installation: v1.86.1
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.86.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.86.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.86.1. Context: Observed when using node, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_dd10890701f492cd3ae462ba46a60648 | https://github.com/BerriAI/litellm/releases/tag/v1.86.1 | v1.86.1
## 5. 配置坑 · 失败模式：configuration: v1.87.0-rc.1
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.87.0-rc.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.87.0-rc.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.87.0-rc.1. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_e83fcb4313aa1f975cd02db71b6c8f36 | https://github.com/BerriAI/litellm/releases/tag/v1.87.0-rc.1 | v1.87.0-rc.1
## 6. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:671269505 | https://github.com/BerriAI/litellm | README/documentation is current enough for a first validation pass.
## 7. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:671269505 | https://github.com/BerriAI/litellm | last_activity_observed missing
## 8. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:671269505 | https://github.com/BerriAI/litellm | no_demo; severity=medium
## 9. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:671269505 | https://github.com/BerriAI/litellm | no_demo; severity=medium
## 10. 安全/权限坑 · 来源证据：Feature Request: Add FunASR as audio/transcriptions provider
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Add FunASR as audio/transcriptions provider
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7b1a78fc07144bc688c7f665fc1503f1 | https://github.com/BerriAI/litellm/issues/29367 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 11. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:671269505 | https://github.com/BerriAI/litellm | issue_or_pr_quality=unknown
## 12. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:671269505 | https://github.com/BerriAI/litellm | release_recency=unknown
## 13. 维护坑 · 失败模式：maintenance: v1.84.1
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.84.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.84.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.84.1. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_e37da84b06f8756f9d6ada5202dd65e8 | https://github.com/BerriAI/litellm/releases/tag/v1.84.1 | v1.84.1
## 14. 维护坑 · 失败模式：maintenance: v1.85.1
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.85.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.85.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.85.1. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_d8cbc3f0c1410960fe083eb8883abccb | https://github.com/BerriAI/litellm/releases/tag/v1.85.1 | v1.85.1
## 15. 维护坑 · 失败模式：maintenance: v1.86.2
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.86.2
- 对用户的影响：Upgrade or migration may change expected behavior: v1.86.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.86.2. Context: Observed when using python, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_e3fe7e15330ae72c532ac5cddd5bc94c | https://github.com/BerriAI/litellm/releases/tag/v1.86.2 | v1.86.2
## 16. 维护坑 · 失败模式：maintenance: v1.87.0-dev.1
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.87.0-dev.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.87.0-dev.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.87.0-dev.1. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_3b6e1b82db9da67cfc32b910fa694c8c | https://github.com/BerriAI/litellm/releases/tag/v1.87.0-dev.1 | v1.87.0-dev.1
## 17. 维护坑 · 失败模式：maintenance: v1.87.0-rc.2
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.87.0-rc.2
- 对用户的影响：Upgrade or migration may change expected behavior: v1.87.0-rc.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.87.0-rc.2. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_97024b746f786019f75ce1249f8548cc | https://github.com/BerriAI/litellm/releases/tag/v1.87.0-rc.2 | v1.87.0-rc.2
## 18. 维护坑 · 失败模式：maintenance: v1.88.0-dev.1
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.88.0-dev.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.88.0-dev.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.88.0-dev.1. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_1beb03ff87763a9d5c04116bac1cfeba | https://github.com/BerriAI/litellm/releases/tag/v1.88.0-dev.1 | v1.88.0-dev.1