576 lines
29 KiB
Markdown
576 lines
29 KiB
Markdown
# LiteLLM 大模型 API 代理转换层深度分析报告
|
||
|
||
## 1. 项目概述
|
||
|
||
LiteLLM 是一个统一的 LLM API 网关和 SDK 项目，核心能力是将 100+ 种不同来源的大模型 API 统一管理，并以 **OpenAI 格式** 作为统一接口标准提供给用户。
|
||
|
||
### 整体请求流向
|
||
|
||
```
|
||
OpenAI SDK (客户端) ──▶ LiteLLM AI Gateway (proxy/) ──▶ LiteLLM SDK (litellm/) ──▶ LLM API
|
||
Anthropic SDK (客户端) ──▶ LiteLLM AI Gateway (proxy/) ──▶ LiteLLM SDK (litellm/) ──▶ LLM API
|
||
任意 HTTP 客户端 ──▶ LiteLLM AI Gateway (proxy/) ──▶ LiteLLM SDK (litellm/) ──▶ LLM API
|
||
```
|
||
|
||
- **AI Gateway（代理层）**：在 SDK 之上提供认证、速率限制、预算管理和路由功能
|
||
- **SDK（核心层）**：处理实际的 LLM 提供商调用、请求/响应转换和流式传输
|
||
|
||
### 与同类项目的核心差异
|
||
|
||
LiteLLM 是**覆盖最广**的 LLM 网关，以 **OpenAI 格式为唯一内部规范格式**（Canonical Format），所有转换都围绕 OpenAI ↔ 提供商格式展开。同时支持 **Anthropic Messages API 直通模式**（`/v1/messages` 端点），使其也能充当 Anthropic 协议的代理网关。SDK 可独立使用（Python 包），也可配合 Gateway 作为服务部署。
|
||
|
||
---
|
||
|
||
## 2. 转换层技术架构
|
||
|
||
### 2.1 架构设计模式
|
||
|
||
采用 **策略模式 + 工厂模式 + 模板方法** 组合设计：
|
||
|
||
- **策略模式**：每个 LLM 提供商都有一个独立的 `Config` 类，继承自统一的 `BaseConfig` 抽象基类，实现各自的转换方法
|
||
- **工厂模式**：`ProviderConfigManager` 作为中心工厂，根据模型名称和提供商类型动态解析出正确的 Config 实例
|
||
- **模板方法**：`BaseConfig` 定义统一的转换接口（抽象方法），子类实现具体的提供商差异
|
||
|
||
### 2.2 核心抽象基类
|
||
|
||
**文件**: `litellm/llms/base_llm/chat/transformation.py` (466 行)
|
||
|
||
```python
|
||
class BaseConfig(ABC):
|
||
@abstractmethod
|
||
def get_supported_openai_params(self, model: str) -> list:
|
||
"""返回该提供商支持的 OpenAI 格式参数列表"""
|
||
|
||
@abstractmethod
|
||
def map_openai_params(self, non_default_params, optional_params, model, drop_params) -> dict:
|
||
"""将 OpenAI 格式参数映射为提供商特定参数"""
|
||
|
||
@abstractmethod
|
||
def validate_environment(self, headers, model, messages, optional_params, ...) -> dict:
|
||
"""验证并构建请求头"""
|
||
|
||
@abstractmethod
|
||
def transform_request(self, model, messages, optional_params, litellm_params, headers) -> dict:
|
||
"""将 OpenAI 格式请求转换为提供商格式"""
|
||
|
||
@abstractmethod
|
||
def transform_response(self, model, raw_response, model_response, ...) -> ModelResponse:
|
||
"""将提供商响应转换为统一的 OpenAI ModelResponse 格式"""
|
||
|
||
@abstractmethod
|
||
def get_error_class(self, error_message, status_code, headers) -> BaseLLMException:
|
||
"""返回提供商特定的错误类"""
|
||
|
||
# 以下为有默认实现的重要方法：
|
||
def get_complete_url(self, api_base, api_key, model, ...) -> str: ... # URL 构建
|
||
def sign_request(self, headers, optional_params, request_data, ...) -> ...: ... # 请求签名
|
||
def get_model_response_iterator(self, ...) -> BaseModelResponseIterator: ... # 流式迭代器
|
||
def should_fake_stream(self, ...) -> bool: ... # 是否需要模拟流式
|
||
def is_thinking_enabled(self, ...) -> bool: ... # 思考模式检测
|
||
def calculate_additional_costs(self, ...) -> float: ... # 自定义成本计算
|
||
def post_stream_processing(self, ...) -> ...: ... # 流式后处理钩子
|
||
```
|
||
|
||
**6 个抽象方法**必须实现，其余方法提供默认实现。
|
||
|
||
### 2.3 中央 HTTP 编排器
|
||
|
||
**文件**: `litellm/llms/custom_httpx/llm_http_handler.py` (12,161 行)
|
||
|
||
`BaseLLMHTTPHandler` 是所有提供商共用的 HTTP 编排器，支持**多种模态**（不仅限于 chat）：
|
||
|
||
```
|
||
completion() 编排流程：
|
||
1. provider_config.validate_environment() → 验证环境、构建请求头
|
||
2. provider_config.get_complete_url() → 构建 API URL
|
||
3. provider_config.transform_request() → 转换请求体
|
||
4. provider_config.sign_request() → 签名请求（如 AWS Bedrock）
|
||
5. 发送 HTTP 请求到提供商 API
|
||
6. provider_config.transform_response() → 转换响应为 ModelResponse
|
||
```
|
||
|
||
**额外支持的模态**: embedding、rerank、audio_transcription、OCR、vector_store、files、batches、image_generation、video_generation、responses API 等。
|
||
|
||
**关键设计**: 编排器本身不需要修改，所有提供商的差异都封装在各自的 Config 类中。此外编排器还支持 **HTTP 错误重试**模式 — 通过 `should_retry_llm_api_inside_llm_translation_on_http_error()` 在特定错误时自动修复并重试。
|
||
|
||
### 2.4 请求入口与提供商解析
|
||
|
||
**入口文件**: `litellm/main.py` 的 `completion()` 函数（约 7,807 行，`completion()` 起始于 line 1052）
|
||
|
||
**提供商解析文件**: `litellm/litellm_core_utils/get_llm_provider_logic.py` 的 `get_llm_provider()` 函数 (958 行)
|
||
|
||
解析优先级：
|
||
|
||
1. **LiteLLM Proxy 默认**: 检查是否应使用 litellm_proxy
|
||
2. **litellm_params**: 从 router 参数获取
|
||
3. **Azure 特殊处理**: Azure 非 OpenAI 模型
|
||
4. **Cohere/Anthropic 文本模型重定向**
|
||
5. **OpenRouter 前缀剥离**
|
||
6. **JSON 配置提供商**: `JSONProviderRegistry` 动态注册的 OpenAI 兼容提供商
|
||
7. **前缀提供商**: `model.split("/")[0]` 在提供商列表中匹配
|
||
8. **API Base 匹配**: ~40 个已知 API 端点域名匹配
|
||
9. **已知模型名查找**: `"gpt-4"` → `"openai"`，`"claude-3"` → `"anthropic"`
|
||
10. **字符串前缀回退**: `model.startswith("bytez/")` → `"bytez"`
|
||
11. **错误**: 无法解析则抛出 `BadRequestError`
|
||
|
||
**Config 解析**: `litellm/utils.py` 的 `ProviderConfigManager`（line 8013），通过 `_PROVIDER_CONFIG_MAP` 懒加载字典进行 O(1) 查找，约 90 个提供商映射。
|
||
|
||
**派发模式**: `main.py` 中仍保留一个较大的 `if/elif` 链用于提供商分派。Azure 和 OpenAI 仍使用专用处理路径，约 30 个提供商通过 `base_llm_http_handler.completion()` 处理。
|
||
|
||
### 2.5 多模态工厂
|
||
|
||
`ProviderConfigManager` 提供多个工厂方法：
|
||
|
||
| 工厂方法 | 用途 | 提供商数量 |
|
||
|---------|------|-----------|
|
||
| `get_provider_chat_config()` | Chat Completions | ~90 |
|
||
| `get_provider_embedding_config()` | Embedding 向量 | ~25 |
|
||
| `get_provider_rerank_config()` | Rerank 重排序 | ~13 |
|
||
| `get_provider_anthropic_messages_config()` | Anthropic Messages 直通 | 4 |
|
||
|
||
---
|
||
|
||
## 3. 支持的协议/提供商总览
|
||
|
||
### 3.1 支持规模
|
||
|
||
| 维度 | 数量 |
|
||
|------|------|
|
||
| LLM 提供商枚举值 (`LlmProviders`) | 133 |
|
||
| 搜索提供商枚举值 (`SearchProviders`) | 12 |
|
||
| 实现目录数 (`litellm/llms/` 下) | ~118 |
|
||
| `base_llm/` 子模态目录 | 29 (chat, embedding, rerank, responses, audio, OCR, image, video, etc.) |
|
||
|
||
### 3.2 主要提供商分类
|
||
|
||
| 分类 | 提供商 | 转换方式 |
|
||
|------|--------|----------|
|
||
| **OpenAI 及兼容** | OpenAI, Azure OpenAI, DeepSeek, Groq, Together AI, Fireworks, Perplexity, OpenRouter 等 | 几乎直通，参数过滤 |
|
||
| **Anthropic 系列** | Anthropic 原生, Bedrock Claude, Vertex AI Claude | 深度转换（消息格式、工具调用、思考模式） |
|
||
| **Google 系列** | Gemini (AI Studio), Vertex AI Gemini | 深度转换（contents/parts 格式、角色映射） |
|
||
| **AWS 系列** | Bedrock Converse, Bedrock Invoke | Converse 统一格式 或 按提供商分派转换 |
|
||
| **开源/本地** | Ollama, vLLM, LM Studio, llamafile | 参数重映射 + 消息格式适配 |
|
||
| **其他云厂商** | Cohere, Mistral, Databricks, WatsonX, OCI, Snowflake 等 | 各自独立转换 |
|
||
| **直通模式** | 所有提供商 | 请求体不变，仅转换 URL 和认证头 |
|
||
|
||
---
|
||
|
||
## 4. 核心转换文件详解
|
||
|
||
### 4.1 转换文件总览表
|
||
|
||
| 入站 API 协议 | 目标提供商 | 转换文件 |
|
||
|---------------|-----------|----------|
|
||
| `/v1/chat/completions` (OpenAI) | Anthropic | `litellm/llms/anthropic/chat/transformation.py` |
|
||
| `/v1/chat/completions` (OpenAI) | Bedrock Converse | `litellm/llms/bedrock/chat/converse_transformation.py` |
|
||
| `/v1/chat/completions` (OpenAI) | Bedrock Invoke | `litellm/llms/bedrock/chat/invoke_transformations/*.py` |
|
||
| `/v1/chat/completions` (OpenAI) | Gemini | `litellm/llms/gemini/chat/transformation.py` (薄层) → `litellm/llms/vertex_ai/gemini/transformation.py` (核心) |
|
||
| `/v1/chat/completions` (OpenAI) | Vertex AI | `litellm/llms/vertex_ai/vertex_ai_partner_models/main.py` |
|
||
| `/v1/chat/completions` (OpenAI) | OpenAI | `litellm/llms/openai/chat/gpt_transformation.py` |
|
||
| `/v1/chat/completions` (OpenAI) | Ollama | `litellm/llms/ollama/chat/transformation.py` |
|
||
| `/v1/chat/completions` (OpenAI) | Cohere | `litellm/llms/cohere/chat/transformation.py` |
|
||
| `/v1/chat/completions` (OpenAI) | Mistral | `litellm/llms/mistral/chat/transformation.py` |
|
||
| `/v1/messages` (Anthropic) | Anthropic/Bedrock/Vertex | `litellm/llms/base_llm/anthropic_messages/transformation.py` |
|
||
| 直通端点 | 所有 | `litellm/proxy/pass_through_endpoints/` |
|
||
|
||
---
|
||
|
||
### 4.2 Anthropic 转换层
|
||
|
||
**文件**: `litellm/llms/anthropic/chat/transformation.py` (2,096 行)
|
||
**类**: `AnthropicConfig(AnthropicModelInfo, BaseConfig)`
|
||
|
||
#### 请求转换（OpenAI → Anthropic）
|
||
|
||
`transform_request()` 方法核心转换逻辑：
|
||
|
||
1. **系统消息提取**: 将 `role: "system"` 消息从 messages 列表中提取出来，放入 Anthropic 顶层 `system` 字段（Anthropic API 不使用 system-role 消息）
|
||
2. **消息格式转换**: 调用 `anthropic_messages_pt()` 将 OpenAI 消息转为 Anthropic Messages 格式
|
||
3. **工具调用转换**: OpenAI 的 `function.parameters` → Anthropic 的 `input_schema`；工具选择 `"required"` → `"any"`，`parallel_tool_calls: false` → `disable_parallel_tool_use: true`
|
||
4. **Beta Header 管理**: 根据使用的功能（web search、memory、structured output、computer use、code execution、MCP server 等）自动添加 `anthropic-beta` 请求头
|
||
5. **Thinking 参数处理**: 管理 Anthropic Extended Thinking 参数
|
||
6. **JSON 模式**: 旧模型通过创建合成工具实现 JSON 模式；新模型（Sonnet 4.5+）原生支持结构化输出
|
||
|
||
**关键参数映射**:
|
||
|
||
| OpenAI 参数 | Anthropic 参数 | 说明 |
|
||
|-------------|---------------|------|
|
||
| `max_tokens` / `max_completion_tokens` | `max_tokens` | 直接映射，默认值可通过环境变量配置 |
|
||
| `tools[].function.parameters` | `tools[].input_schema` | JSON Schema 格式转换 |
|
||
| `tool_choice: "required"` | `tool_choice: {"type": "any"}` | 语义映射 |
|
||
| `parallel_tool_calls: false` | `disable_parallel_tool_use: true` | 反转布尔值 |
|
||
| `stop` | `stop_sequences` | 字符串 → 列表 |
|
||
| `response_format` (JSON) | 合成工具方式 / `output_format` | 按模型能力选择 |
|
||
| `reasoning_effort` | `thinking` + `output_config` | 努力级别映射为思考预算 |
|
||
| `web_search_options` | `tools` (web_search hosted tool) | 转换为 Anthropic 原生搜索工具 |
|
||
| `user` | `metadata.user_id` | 嵌套到 metadata |
|
||
|
||
#### 响应转换（Anthropic → OpenAI）
|
||
|
||
1. **内容块解析**: text → 文本, tool_use → ToolCall, thinking/redacted_thinking → `reasoning_content` + `thinking_blocks`
|
||
2. **JSON 模式逆向转换**: 如果启用了 JSON 模式，将工具调用的参数提取为文本内容
|
||
3. **停止原因映射**: `end_turn`/`stop_sequence` → `stop`, `max_tokens` → `length`, `tool_use` → `tool_calls`
|
||
4. **Usage 计算**: 输入/输出 token、缓存 token、推理 token 等
|
||
|
||
---
|
||
|
||
### 4.3 OpenAI 转换层（基准实现）
|
||
|
||
**文件**: `litellm/llms/openai/chat/gpt_transformation.py` (820 行)
|
||
**类**: `OpenAIGPTConfig(BaseLLMModelInfo, BaseConfig)` — 标记 `_is_base_class = True`
|
||
|
||
OpenAI 是"原生"格式提供者，其转换层最简单：
|
||
|
||
- **`transform_request()`**: 仅做少量规范化（image_url 格式化、移除 `cache_control`、PDF URL 转 base64）
|
||
- **`transform_response()`**: JSON 解析后直接构建 `ModelResponse`
|
||
- **`map_openai_params()`**: 简单的参数过滤（只保留支持的参数列表）
|
||
|
||
**作为基类被复用**:
|
||
- `OpenAIOSeriesConfig` — O1/O3 推理模型（`system` 角色转 `user`，限制 temperature）
|
||
- `OpenAIGPTAudioConfig` — GPT-4o 音频模型
|
||
- `OpenAIGPT5Config` — GPT-5 系列（推理努力级别标准化）
|
||
- 许多 OpenAI 兼容提供商（DeepSeek、Groq、Together AI 等）也复用此类
|
||
- **Mistral** 也继承自 `OpenAIGPTConfig`（API 大部分兼容，额外处理 schema 清理和 thinking）
|
||
|
||
---
|
||
|
||
### 4.4 Google Gemini 转换层
|
||
|
||
**文件**:
|
||
- `litellm/llms/gemini/chat/transformation.py` (154 行) — 薄层，继承 Vertex Gemini
|
||
- `litellm/llms/vertex_ai/gemini/transformation.py` (941 行) — 核心转换逻辑
|
||
|
||
**类继承链**:
|
||
```
|
||
BaseConfig → VertexAIBaseConfig → VertexGeminiConfig → GoogleAIStudioGeminiConfig
|
||
```
|
||
|
||
#### 请求转换（OpenAI → Gemini）
|
||
|
||
这是最复杂的转换之一：
|
||
|
||
| 方面 | OpenAI 格式 | Gemini 格式 |
|
||
|------|-----------|------------|
|
||
| 消息容器 | `messages: [{role, content}]` | `contents: [{role, parts}]` |
|
||
| 角色类型 | `system`, `user`, `assistant`, `tool` | 仅 `user` 和 `model` |
|
||
| 内容格式 | 字符串或内容对象列表 | `PartType` 对象列表 |
|
||
| 工具结果 | 独立的 `role: "tool"` 消息 | 合并到 `role: "user"` 的 parts |
|
||
| 连续消息 | 允许任意顺序 | 必须严格交替 user/model |
|
||
|
||
转换算法核心步骤：
|
||
1. **系统消息提取**: 放入 `system_instruction` 字段
|
||
2. **角色映射**: `user`/`system` → `user`, `assistant` → `model`, `tool`/`function` → `user`
|
||
3. **角色交替强制**: 合并连续相同角色的消息
|
||
4. **媒体处理**: image_url → `inline_data` (base64) 或 `file_data` (GCS URI)
|
||
5. **工具调用转换**: OpenAI `tool_calls` → Gemini `functionCall` parts
|
||
6. **搜索工具冲突处理**: 搜索工具与函数声明互斥时优先保留函数声明
|
||
|
||
**关键参数映射**:
|
||
|
||
| OpenAI 参数 | Gemini 参数 | 说明 |
|
||
|-------------|-----------|------|
|
||
| `max_tokens` | `max_output_tokens` | 名称变更 |
|
||
| `stop` | `stop_sequences` | 字符串 → 列表 |
|
||
| `n` | `candidate_count` | 名称变更 |
|
||
| `response_format` | `response_mime_type` + `response_schema` | 复杂 Schema 转换 |
|
||
| `reasoning_effort` | `thinkingConfig` | 努力级别 → 思考预算 |
|
||
| `tool_choice: "none"` | `NONE` | 大写枚举 |
|
||
| `tool_choice: "required"` | `ANY` | 语义映射 |
|
||
| `modalities: ["image"]` | `responseModalities: ["IMAGE"]` | 大写枚举 |
|
||
| `web_search_options` | `tools` (googleSearch) | 转换为 Gemini 搜索工具 |
|
||
|
||
---
|
||
|
||
### 4.5 AWS Bedrock 转换层
|
||
|
||
Bedrock 是架构最复杂的转换层，支持 **四条独立转换路径**：
|
||
|
||
#### 路径 1：Converse API（推荐）
|
||
|
||
**文件**: `litellm/llms/bedrock/chat/converse_transformation.py` (2,129 行)
|
||
**类**: `AmazonConverseConfig(BaseConfig)`
|
||
|
||
使用 Bedrock 的统一 Converse API，所有提供商共享同一套请求/响应结构：
|
||
|
||
```
|
||
请求格式：{
|
||
"messages": [...], # Bedrock MessageBlock 格式
|
||
"system": [...], # SystemContentBlock 格式
|
||
"inferenceConfig": {...}, # maxTokens, temperature, topP, topK 等
|
||
"additionalModelRequestFields": {...}, # 提供商特定字段
|
||
"toolConfig": {...}, # 工具配置
|
||
"guardrailConfig": {...}, # 护栏配置
|
||
}
|
||
```
|
||
|
||
支持最丰富的功能集：工具调用、思考模式、结构化输出、护栏、Web 搜索、Computer Use 等。
|
||
|
||
#### 路径 2：Invoke API（传统/遗留）
|
||
|
||
**文件**: `litellm/llms/bedrock/chat/invoke_transformations/` — 15 个提供商特定文件
|
||
**基类**: `AmazonInvokeConfig(BaseConfig, BaseAWSLLM)`
|
||
|
||
采用 **分派模式 (Dispatcher Pattern)**：`get_bedrock_chat_config()` 从模型名解析提供商，然后委托给对应的转换类：
|
||
|
||
```
|
||
AmazonInvokeConfig.transform_request()
|
||
→ get_bedrock_invoke_provider(model) # 从模型名解析提供商
|
||
→ 按提供商委托：
|
||
- "anthropic" → AmazonAnthropicClaudeConfig（复用 AnthropicConfig）
|
||
- "cohere" → 构建 Cohere 格式请求
|
||
- "meta" → {"prompt": ...} 文本格式
|
||
- "nova" → AmazonInvokeNovaConfig
|
||
- "deepseek_r1", "qwen3", "qwen2", "moonshot", "openai" 等 → 各自的转换器
|
||
```
|
||
|
||
**Anthropic Claude Invoke 特殊设计**: `AmazonAnthropicClaudeConfig` 通过多重继承 `AmazonInvokeConfig + AnthropicConfig`，复用 Anthropic 原生转换逻辑，但去除 Bedrock 不兼容的字段并设置 `anthropic_version = "bedrock-2023-05-31"`。
|
||
|
||
#### 路径 3：Converse-like — Converse 的轻量包装器
|
||
|
||
#### 路径 4：Invoke Agent — Bedrock Agent 编排调用的专用路径
|
||
|
||
**路由决策** (`get_bedrock_chat_config()`): 先按 `bedrock_route`（converse/openai/agent/agentcore）选择路径，再按 `bedrock_invoke_provider` 选择子提供商。
|
||
|
||
---
|
||
|
||
### 4.6 Vertex AI 转换层
|
||
|
||
**文件**: `litellm/llms/vertex_ai/` — 多提供商门面 (Multi-Provider Facade)
|
||
|
||
Vertex AI 在 Google Cloud 上托管了多种第三方模型：
|
||
|
||
| 模型类型 | Config 类 / 处理方式 | 转换方式 |
|
||
|----------|----------|----------|
|
||
| Gemini | `VertexGeminiConfig` | 深度转换（同 Gemini 格式） |
|
||
| Anthropic Claude | `VertexAIAnthropicConfig` | 复用 AnthropicConfig + Vertex 认证 + `anthropic_version: "vertex-2023-10-16"` |
|
||
| Meta Llama | `OpenAILikeChatHandler` / `base_llm_http_handler` | OpenAI 兼容端点 |
|
||
| AI21 Jamba | `VertexAIAi21Config` | 继承 OpenAIGPTConfig |
|
||
| DeepSeek / Qwen / Minimax / Moonshot | `base_llm_http_handler` | OpenAI 兼容端点 |
|
||
| Mistral/Codestral | `MistralConfig` / `CodestralTextCompletionConfig` | OpenAI 兼容 |
|
||
|
||
**调度器**: `VertexAIPartnerModels` 类通过 `PartnerModelPrefixes` 枚举（META, DEEPSEEK, MISTRAL, CODERESTAL, JAMBA, CLAUDE, QWEN, GPT_OSS 等）路由到正确的处理器。
|
||
|
||
---
|
||
|
||
### 4.7 其他重要提供商转换
|
||
|
||
#### Ollama（本地模型）
|
||
|
||
**文件**: `litellm/llms/ollama/chat/transformation.py` (580 行)
|
||
|
||
| OpenAI 参数 | Ollama 参数 | 说明 |
|
||
|-------------|-----------|------|
|
||
| `max_tokens` | `num_predict` | 名称变更 |
|
||
| `frequency_penalty` | `repeat_penalty` | 语义差异 |
|
||
| `response_format(json_object)` | `format: "json"` | 简化映射 |
|
||
| `response_format(json_schema)` | `format: <schema>` | 直接传入 schema |
|
||
| `reasoning_effort` | `think` | 布尔/字符串 |
|
||
|
||
支持 Ollama 特有参数（Mirostat 采样、num_ctx、num_gpu、num_thread 等），支持从 `<think/>` 标签中提取推理内容。
|
||
|
||
#### Cohere
|
||
|
||
- **v1 API**: `CohereChatConfig(BaseConfig)` — 完全独立的转换（`chat_history` + 最新消息分离）
|
||
- **v2 API**: `CohereV2ChatConfig` — v2 是 OpenAI 兼容的，复用 OpenAI 转换
|
||
- 通过 `_get_cohere_config(model)` 根据模型选择版本
|
||
|
||
#### Mistral
|
||
|
||
**类**: `MistralConfig(OpenAIGPTConfig)` — **继承自 OpenAI Config**（非直接继承 BaseConfig）
|
||
|
||
特殊处理：工具 Schema 清理（移除 `$id`、`$schema`、`additionalProperties` 等 Mistral 不支持的字段），Magistral 模型的推理通过注入专用系统提示实现。
|
||
|
||
---
|
||
|
||
### 4.8 Anthropic Messages API 直通层
|
||
|
||
**文件**: `litellm/llms/base_llm/anthropic_messages/transformation.py` (165 行)
|
||
**基类**: `BaseAnthropicMessagesConfig(ABC)` — **独立的**抽象基类，与 `BaseConfig` 并行
|
||
|
||
这是一条与标准 OpenAI 格式 `BaseConfig` 并行的转换路径，用于直接接受 Anthropic Messages API 格式（`/v1/messages`）的请求并转发到多个云提供商：
|
||
|
||
| 提供商 | 实现类 | 认证方式 |
|
||
|--------|--------|----------|
|
||
| Anthropic 原生 | `AnthropicMessagesConfig` | API Key |
|
||
| AWS Bedrock | `BedrockModelInfo.get_bedrock_provider_config_for_messages_api()` | AWS SigV4 |
|
||
| Vertex AI Claude | `VertexAIPartnerModelsAnthropicMessagesConfig` | Google OAuth |
|
||
| Azure AI Claude | `AzureAnthropicMessagesConfig` | Azure Token |
|
||
|
||
**关键抽象方法** (5 个):
|
||
1. `validate_anthropic_messages_environment()` — 返回 (headers, api_base)
|
||
2. `get_complete_url()` — URL 构建
|
||
3. `get_supported_anthropic_messages_params()` — 支持的参数列表
|
||
4. `transform_anthropic_messages_request()` — 请求转换
|
||
5. `transform_anthropic_messages_response()` — 响应转换
|
||
|
||
**自修复能力**: 支持在 thinking signature 无效时自动重试（`should_retry_anthropic_messages_on_http_error()`，最多 2 次）。
|
||
|
||
### 4.9 Proxy 直通模式
|
||
|
||
**目录**: `litellm/proxy/pass_through_endpoints/`
|
||
|
||
直通模式允许用户直接调用提供商的原生 API，**请求体不做任何转换**，仅转换：
|
||
- **URL**: 将代理路由映射到提供商的实际 API 端点
|
||
- **认证**: 将 LiteLLM 虚拟密钥替换为提供商的 API 密钥（`PassthroughEndpointRouter` 管理凭证）
|
||
- **元数据**: 注入日志和计费信息
|
||
|
||
主要文件: `llm_passthrough_endpoints.py` (2,371 行)、`pass_through_endpoints.py`、`passthrough_guardrails.py` 等。
|
||
|
||
---
|
||
|
||
## 5. 流式传输处理
|
||
|
||
### 5.1 统一流式包装器
|
||
|
||
**文件**: `litellm/litellm_core_utils/streaming_handler.py` (2,418 行)
|
||
**类**: `CustomStreamWrapper`
|
||
|
||
所有提供商共用的流式响应统一化层，实现 `__iter__`/`__next__`（同步）和 `__aiter__`/`__anext__`（异步）。
|
||
|
||
**核心设计**: 引入 `GenericStreamingChunk` 统一接口：
|
||
```python
|
||
GenericStreamingChunk = {
|
||
"text": str,
|
||
"is_finished": bool,
|
||
"finish_reason": str,
|
||
"usage": Usage,
|
||
"tool_use": [...],
|
||
}
|
||
```
|
||
|
||
所有实现了 `BaseConfig.get_model_response_iterator()` 的提供商都返回符合此格式的块，`CustomStreamWrapper` 可以统一处理。
|
||
|
||
**关键功能**:
|
||
- 特殊 token 处理（`<|im_start|>`, `<|im_end|>` 等）
|
||
- Stream options 支持（`include_usage`）
|
||
- 最大流式持续时间强制
|
||
- `merge_reasoning_content_in_choices` 支持
|
||
- `aclose()` 通过 `anyio.CancelScope` 正确清理
|
||
|
||
### 5.2 提供商特定的流式解析器
|
||
|
||
每个提供商都有独立的 `ModelResponseIterator` 实现：
|
||
|
||
| 提供商 | 解析器位置 | 特殊处理 |
|
||
|--------|-----------|---------|
|
||
| Anthropic | `llms/anthropic/chat/handler.py` | SSE 事件类型分派（message_start/content_block_delta/message_delta） |
|
||
| OpenAI | `llms/openai/chat/gpt_transformation.py` | 几乎直通 |
|
||
| Gemini | Vertex AI 流式处理 | `contents[0].parts[0].text` 格式 |
|
||
| Bedrock Converse | `llms/bedrock/chat/converse_handler.py` | AWS 事件流格式 |
|
||
| Ollama | 内置于 transformation.py | JSON 行格式，`<think/>` 标签解析 |
|
||
|
||
### 5.3 Fake Stream 机制
|
||
|
||
部分提供商（如某些 Bedrock Invoke 模型）不支持真正的流式传输。LiteLLM 通过 `should_fake_stream()` 检测这种情况，先发送非流式请求获取完整响应，然后通过 `MockResponseIterator` 逐块模拟流式输出。
|
||
|
||
---
|
||
|
||
## 6. 转换层设计模式总结
|
||
|
||
### 6.1 三层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ Proxy Layer (proxy/) │ 认证、限流、路由、计费
|
||
├─────────────────────────────────────────┤
|
||
│ SDK Layer (litellm/) │ 统一入口、参数映射
|
||
│ ┌─────────────────────────────────┐ │
|
||
│ │ BaseLLMHTTPHandler │ │ HTTP 编排器（不变）
|
||
│ │ ┌───────────────────────────┐ │ │
|
||
│ │ │ ProviderConfig (BaseConfig)│ │ │ 转换策略（可变）
|
||
│ │ │ • transform_request() │ │ │
|
||
│ │ │ • transform_response() │ │ │
|
||
│ │ │ • map_openai_params() │ │ │
|
||
│ │ └───────────────────────────┘ │ │
|
||
│ └─────────────────────────────────┘ │
|
||
├─────────────────────────────────────────┤
|
||
│ HTTP Client (httpx) │ 底层 HTTP 通信
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 6.2 关键设计模式
|
||
|
||
| 模式 | 应用位置 | 说明 |
|
||
|------|---------|------|
|
||
| **策略模式** | `BaseConfig` + 各提供商 Config | 每个提供商的转换逻辑独立封装 |
|
||
| **工厂模式** | `ProviderConfigManager` | 根据模型/提供商动态创建 Config 实例（含子工厂） |
|
||
| **分派模式** | `AmazonInvokeConfig`, `VertexAIPartnerModels` | 根据模型名检测子提供商并委托转换 |
|
||
| **模板方法** | `BaseConfig` 抽象方法 | 定义统一的转换接口，子类实现细节 |
|
||
| **门面模式** | `VertexAIPartnerModels` | 统一入口管理多种 Vertex AI 合作模型 |
|
||
| **适配器模式** | `AmazonAnthropicClaudeConfig` | 通过多重继承适配不同 API（Bedrock + Anthropic） |
|
||
| **装饰器模式** | `CustomStreamWrapper` | 统一包装各提供商的流式响应 |
|
||
|
||
### 6.3 转换类型分类
|
||
|
||
| 转换类型 | 复杂度 | 典型提供商 | 说明 |
|
||
|----------|--------|-----------|------|
|
||
| **直通型** | 低 | OpenAI, Azure, DeepSeek, Groq | 格式基本兼容，仅过滤/重命名少量参数 |
|
||
| **参数重映射型** | 中 | Ollama, Cohere v1 | 参数名称变更，消息格式基本兼容 |
|
||
| **深度转换型** | 高 | Anthropic, Gemini, Bedrock Converse | 消息结构完全不同，角色系统不同，工具调用格式不同 |
|
||
| **分派委托型** | 高 | Bedrock Invoke, Vertex AI | 根据子提供商委托到不同的转换器 |
|
||
| **直通代理型** | 极低 | Proxy 直通模式 | 仅转换 URL 和认证，请求体不变 |
|
||
|
||
### 6.4 添加新提供商的标准流程
|
||
|
||
1. 在 `litellm/llms/{provider}/chat/transformation.py` 创建 Config 类
|
||
2. 实现 `BaseConfig` 的 6 个抽象方法
|
||
3. 在 `ProviderConfigManager._build_provider_config_map()` 中注册
|
||
4. 在 `get_llm_provider()` 中添加提供商解析规则
|
||
5. 在 `tests/llm_translation/test_{provider}.py` 添加单元测试
|
||
|
||
---
|
||
|
||
## 7. 关键目录结构图
|
||
|
||
```
|
||
litellm/
|
||
├── main.py # 统一入口：completion(), acompletion() (7,807行)
|
||
├── utils.py # ProviderConfigManager, 工厂方法 (9,568行)
|
||
├── types/
|
||
│ ├── llms/openai.py # OpenAI 格式类型定义
|
||
│ └── utils.py # LlmProviders 枚举 (133个), SearchProviders 枚举 (12个)
|
||
├── llms/
|
||
│ ├── base_llm/ # 抽象基类目录 (29子目录, 覆盖多种模态)
|
||
│ │ ├── chat/transformation.py # ★ BaseConfig 抽象基类 (466行)
|
||
│ │ ├── anthropic_messages/ # Anthropic Messages 直通基类
|
||
│ │ ├── embedding/ # Embedding 基类
|
||
│ │ ├── rerank/ # Rerank 基类
|
||
│ │ └── ... (其他模态)
|
||
│ ├── custom_httpx/
|
||
│ │ ├── llm_http_handler.py # ★ BaseLLMHTTPHandler 编排器 (12,161行)
|
||
│ │ └── http_handler.py # HTTP 客户端封装
|
||
│ ├── anthropic/chat/transformation.py # Anthropic 转换 (2,096行)
|
||
│ ├── openai/chat/gpt_transformation.py # OpenAI 转换 (820行)
|
||
│ ├── gemini/chat/transformation.py # Gemini 转换 (薄层, 154行)
|
||
│ ├── vertex_ai/gemini/transformation.py # Gemini 核心转换 (941行)
|
||
│ ├── vertex_ai/vertex_ai_partner_models/ # Vertex AI 合作模型门面
|
||
│ ├── bedrock/chat/
|
||
│ │ ├── converse_transformation.py # Bedrock Converse 转换 (2,129行)
|
||
│ │ └── invoke_transformations/ # Bedrock Invoke (15个子提供商)
|
||
│ ├── ollama/chat/transformation.py # Ollama 转换 (580行)
|
||
│ ├── cohere/chat/transformation.py # Cohere 转换 (373行)
|
||
│ ├── mistral/chat/transformation.py # Mistral 转换 (686行, 继承OpenAI)
|
||
│ └── ... (~118 个提供商目录)
|
||
├── litellm_core_utils/
|
||
│ ├── streaming_handler.py # CustomStreamWrapper 统一流式处理 (2,418行)
|
||
│ └── get_llm_provider_logic.py # 提供商解析逻辑 (958行)
|
||
├── proxy/
|
||
│ └── pass_through_endpoints/ # 直通代理模式 (含凭证管理)
|
||
└── router.py # 负载均衡、故障转移
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 总结
|
||
|
||
LiteLLM 的转换层是一个设计精良的**统一 API 网关转换引擎**，其核心优势在于：
|
||
|
||
1. **高度模块化**: 每个提供商的转换逻辑完全独立，修改一个提供商不影响其他提供商
|
||
2. **统一抽象**: 所有提供商通过 `BaseConfig` 接口统一管理，编排器不需要感知提供商差异
|
||
3. **广泛覆盖**: 支持 133 个 LLM 提供商、12 个搜索提供商，涵盖所有主流云厂商、开源模型和本地部署
|
||
4. **多协议支持**: 同时支持 OpenAI Chat Completions、Anthropic Messages (直通)、Gemini GenerateContent 等多种协议
|
||
5. **多模态支持**: 29 个 base_llm 子目录覆盖 Chat、Embedding、Rerank、Audio、OCR、Image、Video、Responses API 等模态
|
||
6. **可扩展性**: 添加新提供商只需实现一个 Config 类并注册
|
||
7. **流式兼容**: 通过 `GenericStreamingChunk` + `CustomStreamWrapper` (2,418行) 统一处理所有提供商的流式响应
|
||
8. **自修复能力**: 支持 HTTP 错误时自动重试和修复（thinking signature、请求体重构等）
|