lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
master
nex/docs/analysis_reference/analysis_litellm.md

29 KiB
Raw Permalink Blame History

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

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 统一接口：

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、请求体重构等）
View Git Blame Copy Permalink