核心定位

LiteLLM 的核心价值在于抽象化底层差异。不同模型提供商（OpenAI、Azure、Hugging Face、Anthropic 等）在 API 规范、认证方式、响应格式等方面存在显著差异。LiteLLM 通过统一的接口层，让开发者可以使用完全相同的代码逻辑调用任意支持的模型。

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 包含多个功能模块，覆盖从简单调用到企业级代理的完整场景：

资料来源：README.md:1-10

代理服务器架构

LiteLLM Proxy 是企业级部署的核心组件，提供完整的 API 网关功能：

graph TD
    A[客户端请求] --> B[LiteLLM Proxy<br/>:4000]
    B --> C[数据平面<br/>/v1/chat/completions<br/>/v1/embeddings]
    B --> D[管理平面<br/>/key/*<br/>/user/*<br/>/team/*]
    C --> E[LLM 提供商]
    D --> F[Prisma 数据库]
    B --> G[LiteLLM UI<br/>:3000]

资料来源：terraform/litellm/README.md:1-15

部署架构

LiteLLM 支持多种部署模式：

资料来源：terraform/litellm/README.md:5-10

企业级功能

LiteLLM 提供丰富的企业特性，覆盖关键管理和安全需求：

提示词管理

LiteLLM 支持外部提示词管理系统，允许将提示词模板存储在版本控制系统中：

• GitLab 集成：支持从 GitLab 仓库获取 .prompt 文件
• BitBucket 集成：支持从 BitBucket 仓库获取提示词
• dotprompt 格式：使用 YAML 前置元数据和 Handlebars 模板语法

安装

基本安装

pip install litellm

完整安装（含代理依赖）

pip install litellm[proxy] prisma

Docker 部署

LiteLLM 提供官方 Docker 镜像，支持容器化部署：

# 标准镜像
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

环境配置

环境变量配置

创建 .env 文件，配置您的 API 密钥：

# 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

代理配置（config.yaml）

LiteLLM 支持通过 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 - 文本补全

import litellm

# OpenAI 格式调用
response = litellm.completion(
    model="gpt-4",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手"},
        {"role": "user", "content": "你好，请介绍一下自己"}
    ]
)

print(response.choices[0].message.content)

支持的模型提供商

LiteLLM 支持多种模型提供商的统一调用：

多模态支持

# 图片理解
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"}
                }
            ]
        }
    ]
)

流式输出

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 - 文本嵌入

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 格式：

response = litellm.audio.transcriptions(
    model="whisper-1",
    file=open("audio.mp3", "rb")
)

print(response.text)

社区建议：FunASR 作为自托管语音转文字提供商的功能请求正在进行中（Issue #29367）。

提示词管理

LiteLLM 支持从外部仓库管理提示词模板，支持 GitLab、BitBucket 等平台。

.prompt 文件格式

概述

LiteLLM 是一个统一的大语言模型（LLM）网关和代理服务，为开发者提供对 100+ 大语言模型的统一调用接口。LiteLLM 的系统架构设计遵循模块化原则，将核心路由、智能体编排、提示词管理、可观测性和企业级功能解耦为独立组件，实现了高度的可扩展性和可维护性。

LiteLLM 架构的核心价值在于：

• 统一接口：通过标准化 API 调用不同提供商的 LLM
• 负载均衡：智能路由和故障转移
• 成本控制：多模型调用优化和预算管理
• 安全审计：完整的请求日志和访问控制
• 企业级功能：SSO、团队管理、API 密钥管理等

资料来源：litellm/proxy/proxy_server.py:1-100

整体架构图

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 请求。

#### 主要职责

#### 企业级端点组织

企业级功能按照功能域进行模块化组织：

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 的核心引擎，负责实现智能路由逻辑，包括负载均衡、故障转移、重试机制和预算控制。

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[降级处理]

#### 路由策略

资料来源：litellm/router.py:1-200

3. 模型适配层（LLM Adapters）

LiteLLM 通过统一的适配器接口支持 100+ LLM 提供商，每个适配器负责将标准化请求转换为特定提供商的 API 格式。

#### 支持的模型类型

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 机制在请求和响应层面进行内容过滤：

# 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 文件格式

概述

LiteLLM 是一个统一的 LLM 调用接口库，支持超过 100 种大语言模型提供商。通过提供标准化的抽象层，开发者可以使用统一的 API 调用方式访问 OpenAI、Anthropic、Google Gemini、AWS Bedrock、Azure 等多种 LLM 服务。

LLM 提供商集成系统的核心职责包括：

• 统一接口抽象：将不同提供商的 API 差异封装为一致的调用格式
• 请求转换：将用户请求转换为各提供商特定的请求格式
• 响应标准化：将提供商响应统一转换为标准化的返回格式
• 错误处理：提供一致的错误处理和重试机制
• Provider 路由：根据模型名称自动识别并路由到正确的提供商

架构设计

整体架构

LiteLLM 的提供商集成采用分层架构设计，核心组件包括：

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 路由机制

模型名称解析

LiteLLM 使用特定的模型命名约定来识别提供商。模型名称格式为：{provider}/{model_name}

# 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 识别流程

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 核心方法

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 需要处理的通用参数包括：

主要 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 (文本补全)

请求转换示例：

# 用户输入格式
{
    "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

关键转换逻辑：

资料来源：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

支持的模型：

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

请求与响应转换

转换流程

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 转换：

# 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 配置

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 的认证信息通常通过环境变量提供：

使用示例

基础调用

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!"}]
)

使用配置文件

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!"}]
)

流式输出

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="")

工具调用

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 选择建议

2. 错误处理

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

问题 4：Windows Prisma 查询崩溃

在 Windows 环境下使用 Prisma 查询引擎时可能出现崩溃，建议使用 v1.84.3 或更新版本。

资料来源：GitHub Issue #25260

扩展新的 Provider

如需添加新的 LLM Provider，需要实现以下组件：

1. 创建 Handler 类

# 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. 实现请求转换

# 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 官方文档
• 支持的模型列表
• GitHub Issues
• 安全公告

概述

LiteLLM代理服务器是一个高性能的统一网关服务，为大型语言模型（LLM）提供标准化API接口。通过该代理，用户可以：

• 统一接入：通过单一端点访问多个LLM提供商
• 密钥管理：安全存储和管理API密钥
• 访问控制：基于API密钥的细粒度权限控制
• 成本追踪：记录和监控每个密钥的使用情况
• 限流保护：防止API滥用和服务过载

资料来源：litellm/proxy/proxy_server.py:1-100

架构设计

系统架构图

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

核心处理流程

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.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密钥作为主要认证方式。认证流程如下：

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 <key>头部提取密钥
2. 格式验证：检查密钥格式是否符合规范
3. 数据库查询：在Prisma数据库中查询密钥信息
4. 状态检查：验证密钥是否启用、未过期
5. 权限校验：检查密钥是否有权访问请求的模型
6. 限流检查：验证请求是否超过速率限制

资料来源：litellm/proxy/auth/user_api_key_auth.py:1-150

权限模型

密钥管理

密钥生命周期

stateDiagram-v2
    [*] --> 创建: /v1/key/generate
    创建 --> 激活: 密钥生成成功
    激活 --> 使用中: 首次API调用
    使用中 --> 暂停: 管理员禁用
    暂停 --> 激活: 管理员启用
    使用中 --> 过期: 达到有效期
    暂停 --> 过期: 达到有效期
    过期 --> [*]: 清理
    使用中 --> [*]: 删除

密钥生成端点

POST /v1/key/generate 用于创建新的API密钥：

请求参数：

响应：

{
  "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消耗）
• 团队和用户关联信息

请求处理流程

通用请求处理

通用请求处理模块负责所有传入请求的标准化处理：

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兼容格式：

{
    "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 实现了灵活的路由机制：

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中配置模型列表：

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

路由参数

资料来源：litellm/proxy/route_llm_request.py:1-150

CLI认证流程

LiteLLM CLI支持通过OAuth SSO进行身份验证，采用轮询机制实现无浏览器直接认证：

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端点

资料来源：litellm/proxy/client/README.md:1-100

配置参考

完整配置示例

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天

环境变量

安全最佳实践

密钥安全

社区安全事件警示：2024年发生的PyPI供应链攻击事件表明，依赖外部包时需格外谨慎。相关安全事件详见 Issue #24512。

推荐的安全措施：

1. 定期轮换密钥：设置合理的密钥过期时间
2. 最小权限原则：为每个密钥分配最小必要权限
3. 密钥存储：使用环境变量而非硬编码
4. 监控审计：启用详细日志记录并定期审查

Dockerfile签名验证

所有LiteLLM Docker镜像均使用cosign签名，建议验证：

cosign verify \
  --certificate-identity-repository ghcr.io/berriai/litellm \
  --certificate-oidc-issuer https://github.com \
  ghcr.io/berriai/litellm:main

常见问题与故障排除

问题诊断流程

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

常见错误码

性能优化

1. 启用连接池：减少连接建立开销
2. 合理设置限流：平衡可用性与安全性
3. 使用缓存：减少重复请求
4. 批量处理：合并小请求减少网络往返

相关资源

• 官方文档
• GitHub Issues
• 安全公告
• 贡献指南

概述

LiteLLM管理控制台（LiteLLM Dashboard）是基于Web的用户界面，为管理员和运维人员提供对LiteLLM代理实例的集中管理和监控能力。管理控制台通过RESTful API与后端LiteLLM代理进行通信，支持团队管理、API密钥管理、视图配置、使用量监控等核心功能。

管理控制台采用React技术栈构建，前端代码位于ui/litellm-dashboard/目录下，通过代理API端点实现与后端的数据交互。控制台设计遵循组件化开发原则，将UI组件、数据Hooks和业务逻辑分离，确保代码的可维护性和可扩展性。

架构设计

整体架构

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密钥、使用限额和权限配置。

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、密钥别名等条件筛选密钥列表。

# 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,
)

密钥管理界面提供以下信息展示：

UI发现与配置

LiteLLM代理通过ui_discovery_endpoints.py暴露UI相关的配置和发现端点，供前端控制台获取必要的初始化信息和配置数据。这些端点返回的信息包括：

• 当前代理实例的配置状态
• 可用的UI功能和模块
• 用户权限和访问范围
• 系统级配置参数

认证与授权

CLI认证流程

LiteLLM CLI支持基于OAuth的SSO认证流程，通过轮询机制与浏览器端配合完成身份验证。

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

概述

LiteLLM 的路由策略是实现智能负载均衡和请求分发的核心组件。在 LiteLLM 架构中，路由器（Router）负责在多个模型部署或 LLM 提供商之间分配请求，而路由策略则决定了这种分配的具体逻辑。

路由策略的主要作用包括：

• 负载均衡：将请求均匀分配到多个模型实例或提供商
• 成本优化：优先使用成本更低的模型
• 延迟优化：选择响应最快的模型
• 容错处理：在某个模型不可用时自动切换到其他模型
• 自适应路由：根据实时性能指标动态选择最佳模型

架构设计

核心组件关系

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

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)

最少繁忙策略基于模型的并发负载选择当前请求压力最小的模型。

工作原理：

1. 获取所有健康部署的当前并发数
2. 选择并发数最低的部署
3. 如果存在多个并发数相同的部署，随机选择其中之一

资料来源：litellm/router_strategy/least_busy.py

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)

最低延迟策略基于历史响应时间选择延迟最低的模型。

工作原理：

1. 从部署配置中读取历史延迟数据
2. 计算各部署的平均响应时间
3. 选择延迟最低的部署
4. 支持基于请求类型的动态延迟估算

资料来源：litellm/router_strategy/lowest_latency.py

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)

最低成本策略优先选择成本最低的模型，适合成本敏感型应用。

工作原理：

1. 获取所有健康部署的定价信息
2. 根据请求的 token 数量估算成本
3. 优先选择成本最低的部署
4. 支持预算限制模式，防止超出预算

资料来源：litellm/router_strategy/lowest_cost.py

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)

自适应路由策略结合多个指标动态选择最佳模型，能够根据实时性能自动调整路由决策。

架构设计：

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

核心特性：

• 动态权重调整：根据历史表现自动调整各指标的权重
• 异常检测：识别表现异常的模型并降低其权重
• 多指标融合：综合考虑延迟、成本、负载等多个因素
• 实时反馈：根据实际响应时间更新路由决策

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]

路由器配置

基础配置参数

资料来源：litellm/router.py

模型列表配置

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,
    }
]

路由策略配置

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"]
    }
)

使用示例

基础用法

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!"}]
)

自定义路由策略

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)
)

多策略组合

# 按优先级组合多个策略
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}
        ]
    }
)

最佳实践

策略选择指南

性能优化建议

1. 合理设置健康检查间隔：避免过于频繁的健康检查影响性能
2. 配置适当的重试次数：过多重试会增加延迟，过少可能丢失请求
3. 监控路由指标：关注各策略的表现并适时调整
4. 使用缓存：对于不常变化的配置，使用路由器级别的缓存

常见问题

Q: 如何处理所有模型都不可用的情况？

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: 如何实现跨区域的智能路由？

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 官方文档
• GitHub 源码仓库
• 路由策略示例

概述

LiteLLM 缓存系统是一个统一的多层缓存解决方案，旨在减少 LLM API 调用成本并提升响应速度。该系统支持多种缓存后端，包括内存缓存、Redis 缓存以及语义缓存（基于向量相似度），能够智能识别重复请求并返回缓存结果。

缓存系统的核心职责包括：

• 缓存请求参数和响应结果
• 支持语义相似度匹配（semantic caching）
• 提供灵活的配置选项
• 处理缓存键生成和序列化
• 管理缓存过期策略

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 的高级缓存功能，能够识别语义上相似的请求。当请求内容语义相似（向量余弦相似度超过阈值）时，即使精确键不同，也能返回缓存结果。

语义缓存工作流程：

graph LR
    A[新请求] --> B[生成嵌入向量]
    B --> C[查询向量数据库]
    C --> D{相似度 > 阈值?}
    D -->|是| E[返回缓存响应]
    D -->|否| F[调用 LLM]
    F --> G[存储新结果]

核心组件

CacheConfig

缓存配置类定义了缓存行为的关键参数：

LLMRequestCacheHandler

LLMRequestCacheHandler 是核心缓存处理器，负责拦截请求、检查缓存、执行缓存读写操作。

核心方法：

配置与使用

环境变量配置

通过环境变量配置 Redis 缓存：

export REDIS_HOST="localhost"
export REDIS_PORT="6379"
export REDIS_PASSWORD="your_password"
export REDIS_DB="0"
export LITELLM_CACHE="redis"

代理配置（config.yaml）

在 LiteLLM 代理配置文件中启用缓存：

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

语义缓存配置

启用语义缓存需要配置嵌入模型和相似度阈值：

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 使用

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 采用多维度哈希策略生成缓存键，确保语义相同但格式不同的请求能够匹配到同一缓存条目。

键生成算法

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[缓存键]

缓存键生成考虑以下因素：

代理缓存路由

缓存管理端点

LiteLLM 代理提供以下缓存管理 API：

批量缓存操作

# 删除多个缓存条目
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/

影响：使用缓存控制且需要函数调用选择的请求可能产生意外行为。

临时解决方案：

# 方案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. 语义缓存阈值调整：根据准确率需求调整相似度阈值

性能优化

扩展开发

自定义缓存后端

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()

钩子函数

缓存系统支持钩子扩展，可在缓存命中/未命中时执行自定义逻辑：

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")

概述

LiteLLM 的安全护栏（Guardrails）是一个模块化的安全框架，用于在 LLM 请求和响应的处理过程中实施内容审核、PII（个人身份信息）保护、内容过滤等安全策略。安全护栏可以在请求到达模型之前对输入进行预处理，也可以在模型响应返回之前对输出进行后处理，从而实现对企业级 AI 应用的安全管控。

安全护栏系统支持多种内置护栏类型，包括内容审核、PII 脱敏、提示词注入检测等。同时，框架提供了扩展机制，允许开发者自定义护栏以满足特定的业务安全需求。

核心架构

系统组件

LiteLLM 安全护栏系统由以下几个核心组件构成：

架构流程图

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[记录审计日志]

护栏类型与处理逻辑

输入处理

安全护栏系统对用户输入进行多层处理，确保输入内容符合安全策略。

处理字段：

处理流程：

1. 解析输入消息结构
2. 依次执行已注册的护栏链
3. 根据护栏结果决定放行或拒绝
4. 返回修改后的输入或安全错误响应

资料来源：litellm/proxy/policy_engine/pipeline_executor.py

输出处理

模型响应返回时，系统会对输出内容进行安全审核。

处理范围：

• LLM 生成的文本内容
• 工具调用（Function Calling）参数
• 重排结果的相关性评分

处理策略：

资料来源：litellm/llms/openai/completion/guardrail_translation/README.md

内置护栏类型

内容审核（Content Moderation）

内容审核护栏用于检测和过滤不当内容，包括：

• 仇恨言论
• 暴力内容
• 性暗示内容
• 垃圾信息

使用方式：

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 脱敏功能，支持自动检测和掩码敏感信息：

资料来源：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

支持的调用类型

安全护栏系统支持多种 LLM 调用类型：

注意：重排请求的输出仅包含相关性评分，不涉及文本内容，因此不需要输出处理。

资料来源：litellm/llms/cohere/rerank/guardrail_translation/README.md

配置与管理

护栏注册

护栏通过 GuardrailRegistry 进行统一管理：

from litellm.proxy.guardrails import guardrail_registry

# 注册自定义护栏
guardrail_registry.register(
    name="my_guardrail",
    handler=MyGuardrailHandler()
)

全局配置

在 LiteLLM Proxy 配置文件中启用护栏：

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

自定义护栏开发

实现自定义护栏处理器

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

扩展方法

常见应用场景

PII 保护

在处理包含用户个人信息的请求时，自动检测并脱敏敏感数据：

curl -X POST 'http://localhost:4000/v1/chat/completions' \
-H 'Content-Type: application/json' \
-d '{
    "model": "gpt-4",
    "messages": [
        {"role": "user", "content": "我的邮箱是 [email protected]，请帮我处理"}
    ],
    "guardrails": ["secret_detection"]
}'

内容过滤

阻止包含不当内容的请求到达模型层：

{
    "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

故障排查

常见问题

调试模式

启用详细日志查看护栏执行过程：

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
• 企业版功能介绍
• 安全漏洞报告指引

概述

MCP（Model Context Protocol）集成是 LiteLLM 框架为支持大语言模型（LLM）与外部工具和服务进行标准化交互而设计的功能模块。通过 MCP 协议，LiteLLM 能够将任意 MCP 服务器提供的工具（Tools）无缝转换为 LLM 可调用的函数接口，实现模型与现实世界数据的连接。

LiteLLM 的 MCP 集成包含两个核心组件：MCP Client（客户端）和 MCP Server Manager（服务器管理器）。客户端负责与远程 MCP 服务器建立连接并调用其提供的工具，服务器管理器则负责在 LiteLLM Proxy 环境中注册和管理这些 MCP 工具，使其可通过 RESTful API 暴露给外部调用者。

架构设计

系统组件关系

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 服务器的通信协议处理；服务器管理层提供服务器注册、配置和生命周期管理功能。

客户端与服务器交互流程

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 类的初始化参数包括服务器 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 可识别的函数调用格式。

转换流程：

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 端点列表：

配置与使用

基本配置

在 config.yaml 中配置 MCP 服务器的基本方式如下：

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

配置项说明：

运行时注册

除了配置文件方式，还可以通过管理 API 动态注册 MCP 服务器：

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 工具调用相同：

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 协议规范的服务器。

示例服务器结构：

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 集成支持多种认证方式以满足不同场景需求：

安全建议

1. 敏感信息保护：在生产环境中，应使用环境变量或密钥管理服务存储认证令牌，避免明文写在配置文件中
2. 连接加密：确保 MCP 服务器启用 HTTPS，LiteLLM 支持通过 ssl_verify 参数配置 SSL 验证
3. 访问控制：利用 LiteLLM Proxy 的密钥和团队管理功能控制对 MCP 工具的访问
4. 超时设置：合理设置请求超时时间，防止因 MCP 服务器无响应导致请求挂起

错误处理

常见错误及解决方案

调试模式

启用详细日志有助于排查 MCP 集成问题：

import litellm
litellm.set_verbose = True

# 执行 MCP 工具调用，日志将输出详细信息
response = litellm.completion(...)

性能优化

连接池管理

MCP Server Manager 内部维护连接池以提高性能。关键配置参数：

缓存策略

工具定义会缓存在本地以减少网络请求。缓存可通过以下方式刷新：

1. 重启 LiteLLM Proxy
2. 调用 DELETE 端点注销后重新注册服务器
3. 使用管理 API 的刷新接口

限制与注意事项

根据社区反馈和源码分析，使用 MCP 集成时需注意以下限制：

1. 实验性功能：experimental_mcp_client 目录表明该功能仍处于实验阶段，生产环境使用需评估风险
2. 同步/异步支持：当前实现主要支持异步调用，同步调用场景可能需要额外适配
3. 批量调用：单个 MCP 请求仅支持一次工具调用，如需批量操作需在应用层循环
4. 错误传播：MCP 服务器返回的错误会被转换但可能丢失部分上下文信息

扩展开发

自定义 MCP 服务器

开发自定义 MCP 服务器需要实现以下核心接口：

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 方法实现：

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
• LiteLLM 官方文档：LiteLLM Docs
• 示例实现： litellm/experimental_mcp_client/servers/

Pitfall Log / 踩坑日志

项目：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