# 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、请求体重构等）