# New-API 项目 API 代理转换层详细分析报告

## 一、项目概述

`new-api` 是一个用 Go 语言编写的 AI API 网关/代理项目，基于 Gin Web 框架和 GORM ORM 构建。其核心功能是将 30+ 种上游 AI 服务提供商（OpenAI、Claude/Anthropic、Google Gemini、AWS Bedrock、阿里通义千问、百度文心等）的 API 统一管理，并以标准化格式对外提供统一入口。

### 与同类项目的核心差异

New-API 是 One-API 的增强分支，在 One-API 的 OpenAI-only 输入基础上增加了**多协议输入**能力（同时接受 OpenAI、Claude、Gemini 三种格式的客户端请求）和 **Hub-and-Spoke 转换架构**（以 OpenAI 格式为内部枢纽）。同时引入了 **Chat Completions via Responses API** 内部路由、**Thinking-to-Content** 转换、异步任务适配器等高级特性。

---

## 二、技术架构

### 2.1 分层架构

项目采用经典的分层架构：**Router → Controller → Relay Handler → Adaptor → Upstream API**

```
┌──────────────────────────────────────────────────────────────┐
│                        客户端请求                              │
│  (OpenAI / Claude / Gemini / Embedding / Audio / Image ...)  │
└───────────────────────────┬──────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                   router/relay-router.go                      │
│            路由层：URL路径 → RelayFormat 映射                   │
│  /v1/chat/completions → RelayFormatOpenAI                     │
│  /v1/messages         → RelayFormatClaude                     │
│  /v1beta/models/*     → RelayFormatGemini                     │
│  /v1/responses        → RelayFormatOpenAIResponses            │
│  /v1/embeddings       → RelayFormatEmbedding ...              │
└───────────────────────────┬──────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                   controller/relay.go                         │
│            控制器层：请求验证、计费预扣、重试循环                   │
│                                                              │
│  Relay() 函数：                                               │
│   1. 解析验证请求 (GetAndValidateRequest)                      │
│   2. 生成 RelayInfo (GenRelayInfo)                           │
│   3. Token估算 + 敏感词检测                                    │
│   4. 价格计算 + 预扣费                                        │
│   5. 渠道选择 + 重试循环                                      │
│   6. 按 RelayFormat 分发到 Handler                           │
└───────────────────────────┬──────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────┐
│              relay/ 目录 - Handler + Adaptor 层               │
│                                                              │
│  ┌──────────────────┐  ┌──────────────────┐                  │
│  │compatible_handler│  │claude_handler.go │                  │
│  │   (OpenAI格式)    │  │  (Claude格式)     │                  │
│  └────────┬─────────┘  └────────┬─────────┘                  │
│           │                      │                            │
│  ┌────────┴─────────┐  ┌────────┴─────────┐                  │
│  │gemini_handler.go │  │responses_handler │                  │
│  │  (Gemini格式)     │  │  (Responses API)  │                  │
│  └────────┬─────────┘  └────────┬─────────┘                  │
│           └──────────┬───────────┘                            │
│                      ▼                                       │
│  ┌──────────────────────────────────────────────────┐        │
│  │       relay/relay_adaptor.go                      │        │
│  │  GetAdaptor(apiType) → channel.Adaptor            │        │
│  └──────────────────────┬───────────────────────────┘        │
│                         ▼                                    │
│  ┌──────────────────────────────────────────────────┐        │
│  │     relay/channel/adapter.go (Adaptor接口)         │        │
│  │  ConvertOpenAIRequest()  - OpenAI格式请求转换      │        │
│  │  ConvertClaudeRequest()  - Claude格式请求转换      │        │
│  │  ConvertGeminiRequest()  - Gemini格式请求转换      │        │
│  │  ConvertEmbeddingRequest() / Audio / Image / Rerank│       │
│  │  ConvertOpenAIResponsesRequest() - Responses转换   │        │
│  │  DoRequest() + DoResponse()                        │        │
│  └──────────────────────┬───────────────────────────┘        │
└─────────────────────────┼────────────────────────────────────┘
                          ▼
┌──────────────────────────────────────────────────────────────┐
│               上游 AI 服务提供商                                │
│  OpenAI / Claude / Gemini / AWS Bedrock / 阿里 / 百度 / ...  │
└──────────────────────────────────────────────────────────────┘
```

### 2.2 核心设计模式

项目采用 **适配器模式 + Hub-and-Spoke 架构**：

1. **统一接口 (`channel.Adaptor`)**：定义所有提供商必须实现的转换方法
2. **工厂函数 (`GetAdaptor`)**：根据 `apiType` 创建对应提供商的适配器实例
3. **Hub-and-Spoke 转换架构**：以 OpenAI 格式作为内部规范格式（Canonical Format），所有其他格式先转换为 OpenAI 格式，再由 OpenAI 格式转换为目标格式

### 2.3 关键接口定义

**同步请求适配器接口** (`relay/channel/adapter.go`, 83 行)：

```go
type Adaptor interface {
    Init(info *relaycommon.RelayInfo)
    GetRequestURL(info *relaycommon.RelayInfo) (string, error)
    SetupRequestHeader(c *gin.Context, req *http.Header, info *relaycommon.RelayInfo) error
    ConvertOpenAIRequest(c, info, request *dto.GeneralOpenAIRequest) (any, error)
    ConvertClaudeRequest(c, info, request *dto.ClaudeRequest) (any, error)
    ConvertGeminiRequest(c, info, request *dto.GeminiChatRequest) (any, error)
    ConvertRerankRequest(c, relayMode int, request dto.RerankRequest) (any, error)
    ConvertEmbeddingRequest(c, info, request dto.EmbeddingRequest) (any, error)
    ConvertAudioRequest(c, info, request dto.AudioRequest) (io.Reader, error)
    ConvertImageRequest(c, info, request dto.ImageRequest) (any, error)
    ConvertOpenAIResponsesRequest(c, info, request dto.OpenAIResponsesRequest) (any, error)
    DoRequest(c, info, requestBody io.Reader) (any, error)
    DoResponse(c, resp, info) (usage any, err *types.NewAPIError)
    GetModelList() []string
    GetChannelName() string
}
```

**异步任务适配器接口** (`TaskAdaptor`)：16 个方法，覆盖任务提交、轮询、计费估算等全生命周期。

---

## 三、支持的协议/格式类型

### 3.1 输入格式（RelayFormat）

**文件**: `types/relay_format.go` (19 行)

| RelayFormat 常量 | 值 | 对应路由 |
|---|---|---|
| `RelayFormatOpenAI` | `"openai"` | `/v1/chat/completions`, `/v1/completions`, `/v1/moderations` |
| `RelayFormatClaude` | `"claude"` | `/v1/messages` |
| `RelayFormatGemini` | `"gemini"` | `/v1beta/models/*`, `/v1/engines/:model/embeddings` |
| `RelayFormatOpenAIResponses` | `"openai_responses"` | `/v1/responses` |
| `RelayFormatOpenAIResponsesCompaction` | `"openai_responses_compaction"` | `/v1/responses/compact` |
| `RelayFormatOpenAIAudio` | `"openai_audio"` | `/v1/audio/*` |
| `RelayFormatOpenAIImage` | `"openai_image"` | `/v1/images/*` |
| `RelayFormatOpenAIRealtime` | `"openai_realtime"` | `/v1/realtime` (WebSocket) |
| `RelayFormatRerank` | `"rerank"` | `/v1/rerank` |
| `RelayFormatEmbedding` | `"embedding"` | `/v1/embeddings` |
| `RelayFormatTask` | `"task"` | 异步任务 (Suno/Video等) |
| `RelayFormatMjProxy` | `"mj_proxy"` | `/mj/*` |

### 3.2 上游提供商 API 类型

**文件**: `constant/api_type.go` (40 行)

定义 35 种 API 类型（iota 0-34, 加 APITypeDummy=35），工厂函数 `GetAdaptor()` 映射了其中 29 种（其余复用 OpenAI 适配器或未使用）：

| API 类型 | 提供商 | 适配器目录 |
|---|---|---|
| `APITypeOpenAI` (0) | OpenAI / Azure / OpenRouter / Xinference | `relay/channel/openai/` |
| `APITypeAnthropic` (1) | Anthropic Claude | `relay/channel/claude/` |
| `APITypeGemini` (9) | Google Gemini | `relay/channel/gemini/` |
| `APITypeAws` (13) | AWS Bedrock | `relay/channel/aws/` |
| `APITypeAli` (5) | 阿里云通义千问 | `relay/channel/ali/` |
| `APITypeBaidu` (3) / `APITypeBaiduV2` (24) | 百度文心 | `relay/channel/baidu/`, `baidu_v2/` |
| `APITypeZhipu` (4) / `APITypeZhipuV4` (10) | 智谱AI (GLM) | `relay/channel/zhipu/`, `zhipu_4v/` |
| `APITypeXunfei` (6) | 科大讯飞 | `relay/channel/xunfei/` |
| `APITypeTencent` (8) | 腾讯混元 | `relay/channel/tencent/` |
| `APITypeOllama` (11) | Ollama | `relay/channel/ollama/` |
| `APITypeDeepSeek` (21) | DeepSeek | `relay/channel/deepseek/` |
| `APITypeVolcEngine` (23) | 火山引擎 | `relay/channel/volcengine/` |
| `APITypeVertexAi` (19) | Google Vertex AI | `relay/channel/vertex/` |
| `APITypeMistral` (20) | Mistral AI | `relay/channel/mistral/` |
| `APITypeCohere` (14) | Cohere | `relay/channel/cohere/` |
| `APITypeOpenRouter` (25) | OpenRouter | 复用 `openai/` |
| `APITypeXai` (27) | xAI (Grok) | `relay/channel/xai/` |
| `APITypeCoze` (28) | 扣子 | `relay/channel/coze/` |
| `APITypeMoonshot` (30) | Moonshot (月之暗面) | `relay/channel/moonshot/` |
| `APITypeMiniMax` (32) | MiniMax | `relay/channel/minimax/` |
| `APITypeCodex` (34) | Codex | `relay/channel/codex/` |
| ... 其他 | SiliconFlow, Cloudflare, Perplexity, Dify, Jina, Jimeng, MokaAI, Replicate, Submodel | 各自目录 |

---

## 四、转换层核心业务逻辑

### 4.1 格式转换核心 — Hub-and-Spoke 模式

项目以 **OpenAI 格式作为内部规范格式（Canonical Format）**，采用 Hub-and-Spoke 转换架构：

```
                  客户端输入格式
                 ┌──────┬──────┬───────┐
                 │OpenAI│Claude│Gemini │ ...
                 └──┬───┴──┬───┴──┬────┘
                    │      │      │
                    ▼      ▼      ▼
              ┌─────────────────────────┐
              │   OpenAI 规范格式 (Hub)    │
              │  dto.GeneralOpenAIRequest  │
              └────────────┬──────────────┘
                           │
                    ┌──────┼──────┐
                    ▼      ▼      ▼
              ┌──────┐┌──────┐┌──────┐
              │OpenAI││Claude││Gemini│ ... (上游格式)
              └──┬───┘└──┬───┘└──┬───┘
                 │       │       │
                 ▼       ▼       ▼
              上游API   上游API  上游API
```

**请求转换方向**：
- `Claude → OpenAI → 上游原生格式`（如上游是 Gemini: `Claude → OpenAI → Gemini`，链式转换）
- `Gemini → OpenAI → 上游原生格式`
- `OpenAI → 上游原生格式`（直接转换）

**响应转换方向**：
- `上游原生格式 → OpenAI → 客户端格式`
- 如客户端请求 Claude 格式且上游是 Gemini: `Gemini → OpenAI → Claude`

### 4.2 转换链跟踪 (RequestConversionChain)

`RelayInfo` 中维护 `RequestConversionChain []types.RelayFormat` 字段，记录请求格式变化轨迹。例如：

- 用户发送 OpenAI 格式，上游是 Claude：`["openai", "claude"]`
- 用户发送 Claude 格式，上游是 OpenAI 兼容：`["claude", "openai"]`
- 用户发送 Claude 格式，上游是 Gemini：`["claude", "openai", "gemini"]`（链式转换）

`FinalRequestRelayFormat` 记录最终发送到上游的格式。

---

## 五、核心转换实现

### 5.1 核心转换服务层 — `service/convert.go` (~1007 行)

这是整个项目的**中心格式转换库**，包含 OpenAI ↔ Claude、OpenAI ↔ Gemini 的双向转换函数：

| 函数 | 转换方向 | 位置 |
|---|---|---|
| `ClaudeToOpenAIRequest()` | Claude 请求 → OpenAI 请求 | line 17 |
| `GeminiToOpenAIRequest()` | Gemini 请求 → OpenAI 请求 | line 658 |
| `ResponseOpenAI2Claude()` | OpenAI 响应 → Claude 响应 | line 607 |
| `StreamResponseOpenAI2Claude()` | OpenAI 流式 → Claude 流式 | line 255 |
| `ResponseOpenAI2Gemini()` | OpenAI 响应 → Gemini 响应 | line 828 |
| `StreamResponseOpenAI2Gemini()` | OpenAI 流式 → Gemini 流式 | line 907 |

### 5.2 Claude 适配器 — `relay/channel/claude/`

| 文件 | 行数 | 功能 |
|---|---|---|
| `relay-claude.go` | ~1009 | Claude 原生请求/响应转换 + 流式处理 |
| `adaptor.go` | ~134 | 适配器实现 |
| `dto.go` | — | Claude DTO 定义 |
| `constants.go` | — | Claude 模型列表 |

**关键转换函数**:
- `RequestOpenAI2ClaudeMessage()` — OpenAI→Claude 请求转换 (line 47): 工具转换 (function→input_schema)、Web Search 工具、tool_choice 映射 (required→any, named→tool)、parallel_tool_calls→disable_parallel_tool_use、Thinking adapter (Opus 4.6/4.7 adaptive/enabled 模式、ReasoningEffort→BudgetTokens 映射)、OpenRouter reasoning 参数覆盖、消息角色映射、媒体内容 (image/PDF→base64 source)
- `StreamResponseClaude2OpenAI()` / `ResponseClaude2OpenAI()` — Claude→OpenAI 响应转换
- `mapToolChoice()` — OpenAI tool_choice → Claude tool_choice

### 5.3 Gemini 适配器 — `relay/channel/gemini/`

| 文件 | 行数 | 功能 |
|---|---|---|
| `relay-gemini.go` | ~1900 | Gemini 原生请求/响应转换 + Thinking adapter + 原生直通处理 |
| `adaptor.go` | ~287 | 适配器实现，支持多级链式转换 |
| `relay-gemini-native.go` | 97 | Gemini 原生格式直通处理 |

**关键转换函数**:
- `CovertOpenAI2Gemini()` — OpenAI→Gemini 请求转换 (line 201): GenerationConfig 映射、ThinkingAdaptor (thinking 后缀/budget clamp/effort level)、安全设置、工具转换 (tools→functionDeclarations + googleSearch/codeExecution/urlContext)、tool_choice→Gemini ToolConfig、ResponseFormat→responseMimeType+responseSchema、角色映射 (assistant→model, system→SystemInstructions)、Markdown 图片检测、ThoughtSignature bypass、Schema 清理
- `ThinkingAdaptor()` — Thinking 配置适配 (line 134): 支持 `-thinking`、`-thinking-<budget>`、`-nothinking` 后缀，model-specific budget clamp
- `responseGeminiChat2OpenAI()` / `streamResponseGeminiChat2OpenAI()` — Gemini→OpenAI 响应转换

**Gemini 适配器的链式转换支持**:
- `ConvertClaudeRequest()`: 先通过 OpenAI 适配器 Claude→OpenAI，再 ConvertOpenAIRequest() 转 Gemini
- `DoResponse()`: 先 Gemini→OpenAI，再根据客户端格式转 Claude/Gemini 输出

### 5.4 OpenAI 适配器 — `relay/channel/openai/`

| 文件 | 行数 | 功能 |
|---|---|---|
| `adaptor.go` | ~683 | OpenAI 适配器实现，含 Claude/Gemini→OpenAI 入口 |
| `relay-openai.go` | ~718 | OpenAI 响应处理，含多格式输出分发 |
| `helper.go` | ~261 | 流式格式分发器 `HandleStreamFormat()` |
| `chat_via_responses.go` | ~550 | Chat Completions via Responses API 模式 |
| `relay_responses.go` | ~150 | Responses API 原生处理 |
| `relay_responses_compact.go` | ~44 | Responses Compact API 处理 |

**`HandleStreamFormat()`** — 流式响应核心分发器 (helper.go line 22):
```go
switch info.RelayFormat {
case types.RelayFormatClaude:
    handleClaudeFormat(c, data, info)   // → service.StreamResponseOpenAI2Claude
case types.RelayFormatGemini:
    handleGeminiFormat(c, data, info)   // → service.StreamResponseOpenAI2Gemini
default:
    sendStreamData(c, data)             // 直接透传 OpenAI 格式 (含 forceFormat/thinkToContent)
}
```

### 5.5 Chat Completions ↔ Responses API 转换 — `service/openaicompat/`

| 文件 | 行数 | 功能 |
|---|---|---|
| `chat_to_responses.go` | ~402 | Chat Completions → Responses API |
| `responses_to_chat.go` | ~133 | Responses API → Chat Completions |
| `policy.go` | 19 | 基于正则的策略路由：判断是否将 Chat 请求路由到 Responses API |

**Chat-via-Responses 优化**: 当配置开启时（通过正则策略匹配模型名），系统将 Chat Completions 请求内部转换为 Responses API 格式发送，再将响应转回 Chat 格式。这允许在不改变客户端 API 的前提下利用 Responses API 的独有特性（reasoning summaries、built-in tools）。

### 5.6 其他提供商适配器

| 提供商 | 转换逻辑 |
|---|---|
| **阿里 (ali/)** | OpenAI→DashScope 格式；Claude 先→OpenAI→阿里；支持 qwen 模型 Claude 兼容；异步图片生成 (X-DashScope-Async) |
| **AWS Bedrock (aws/)** | OpenAI→Claude 格式（通过 claude 包转换）；支持 Nova 模型特殊处理；API Key + AKSK 双认证模式 |
| **Ollama (ollama/)** | OpenAI→Ollama `/api/chat` 或 `/api/generate`；Claude 先→OpenAI→Ollama |
| **百度 (baidu/, baidu_v2/)** | OpenAI→百度文心格式 |
| **智谱 (zhipu/, zhipu_4v/)** | OpenAI→智谱 GLM 格式 |
| **讯飞 (xunfei/)** | OpenAI→讯飞星火格式 |
| **腾讯 (tencent/)** | OpenAI→腾讯混元格式 |
| **火山引擎 (volcengine/)** | OpenAI→火山引擎格式 |
| **Vertex AI (vertex/)** | 继承 Gemini 适配器，添加 Google Cloud 认证 |
| **DeepSeek / Mistral** | OpenAI 兼容（基础直通） |

---

## 六、详细转换流程分析

### 6.1 场景一：用户发送 OpenAI 格式，上游是 Claude

**请求路径**: `POST /v1/chat/completions` → Claude 上游

```
1. 路由层: RelayFormatOpenAI → controller.Relay()
2. 控制器: relayHandler() → relay.TextHelper()
3. TextHelper():
   a. 解析请求 → dto.GeneralOpenAIRequest
   b. GetAdaptor(APITypeAnthropic) → claude.Adaptor
   c. adaptor.ConvertOpenAIRequest() → RequestOpenAI2ClaudeMessage()
      - 角色映射、工具转换、thinking adapter、参数映射
   d. 发送到 Claude /v1/messages 端点
4. DoResponse():
   - 流式: ClaudeStreamHandler() → StreamResponseClaude2OpenAI()
   - 非流式: ClaudeHandler() → ResponseClaude2OpenAI()
   转换链: ["openai", "claude"]
```

### 6.2 场景二：用户发送 Claude 格式，上游是 Gemini

**请求路径**: `POST /v1/messages` → Gemini 上游

```
1. 路由层: RelayFormatClaude → controller.Relay()
2. 控制器: ClaudeHelper()
3. ClaudeHelper():
   a. 解析请求 → dto.ClaudeRequest
   b. Thinking adapter (Opus 模型)
   c. 可选: Chat-via-Responses 桥接
   d. GetAdaptor(APITypeGemini) → gemini.Adaptor
   e. adaptor.ConvertClaudeRequest():
      - 第一步: openai.Adaptor.ConvertClaudeRequest() → ClaudeToOpenAIRequest()
      - 第二步: CovertOpenAI2Gemini() → Gemini 格式
      - 转换链: ["claude", "openai", "gemini"]
   f. 发送到 Gemini generateContent 端点
4. DoResponse():
   - 流式: GeminiChatStreamHandler() → streamResponseGeminiChat2OpenAI()
     再根据客户端格式: service.StreamResponseOpenAI2Claude()
   - 非流式: GeminiChatHandler() → responseGeminiChat2OpenAI()
     再根据客户端格式: service.ResponseOpenAI2Claude()
```

### 6.3 场景三：用户发送 Gemini 格式，上游是 OpenAI

**请求路径**: `POST /v1beta/models/gemini-pro:generateContent` → OpenAI 上游

```
1. 路由层: RelayFormatGemini → GeminiHelper()
2. GeminiHelper():
   a. 解析请求 → dto.GeminiChatRequest
   b. Thinking adapter
   c. adaptor.ConvertGeminiRequest(): Gemini→OpenAI (GeminiToOpenAIRequest)
   d. 发送到 OpenAI /v1/chat/completions
3. DoResponse():
   - OpenAI 响应 → Gemini 格式 (ResponseOpenAI2Gemini / StreamResponseOpenAI2Gemini)
   转换链: ["gemini", "openai"]
```

### 6.4 场景四：Chat Completions 经由 Responses API

```
1. POST /v1/chat/completions
2. TextHelper() 检测到 ShouldChatCompletionsUseResponsesGlobal() 为 true
3. chatCompletionsViaResponses():
   a. ChatCompletionsRequestToResponsesRequest() — Chat → Responses API
   b. adaptor.ConvertOpenAIResponsesRequest() — 转换为上游格式
   c. 发送请求到上游 /v1/responses
   d. OaiResponsesToChatHandler() / OaiResponsesToChatStreamHandler() — Responses → Chat
   e. 如果客户端格式是 Claude/Gemini，继续转换为对应格式
   转换链: ["openai", "openai_responses"]
```

---

## 七、特殊功能与高级特性

### 7.1 Pass-Through 模式

当全局 `PassThroughRequestEnabled` 或渠道 `PassThroughBodyEnabled` 启用时，请求体直接透传到上游，跳过所有格式转换。

### 7.2 字段过滤 (RemoveDisabledFields)

根据渠道安全设置过滤敏感字段: `service_tier`、`inference_geo`、`speed`、`store`、`safety_identifier`、`stream_options.include_obfuscation`。

### 7.3 参数覆写 (ParamOverride)

通过 `relay/common/override.go` 支持请求参数覆写（如强制 temperature、max_tokens）。

### 7.4 模型名称映射

支持将用户请求的模型名称映射为上游实际模型名称（渠道级配置）。

### 7.5 Thinking/Reasoning 适配

- **Claude**: `-thinking` 后缀 → 启用 extended thinking + BudgetTokens；Opus 4.6/4.7 adaptive 模式
- **Gemini**: `ThinkingAdaptor()` 支持 `-thinking`、`-thinking-<budget>`、`-nothinking` 后缀；model-specific budget clamp
- **OpenAI**: o-series 模型 → `-high/-medium/-low` 推理力度后缀

### 7.6 Thinking-to-Content 转换

渠道设置 `ThinkingToContent` 启用时，将 reasoning content 转换为带有 `<think\>...</think\>` 标签的普通文本内容，供不支持 reasoning 字段的客户端使用。

### 7.7 StreamOptions 适配

对支持 `stream_options` 的渠道自动添加 `include_usage: true` 以获取流式用量信息。

### 7.8 SSE Ping Keep-Alive

内置 ping 机制保持长时间流式连接活跃。

### 7.9 Header 覆写/透传

复杂的 Header 管理系统：支持占位符替换 (`{api_key}`, `{client_header:name}`)、正则规则透传、渠道级覆写。

### 7.10 异步任务适配器 (TaskAdaptor)

对视频/音乐等异步生成任务使用独立的 `TaskAdaptor` 接口，支持：任务提交、轮询、计费估算。覆盖平台：Suno、Kling、Jimeng、Vidu、Doubao、Sora、Gemini、Vertex AI、Hailuo 等。

---

## 八、转换矩阵总结

### 请求转换矩阵

| 客户端 \ 上游 | OpenAI | Claude | Gemini | Ali | AWS | Ollama |
|---|---|---|---|---|---|---|
| **OpenAI** | 直通 | OpenAI→Claude | OpenAI→Gemini | OpenAI→Ali | OpenAI→Claude(Bedrock) | OpenAI→Ollama |
| **Claude** | Claude→OpenAI | 直通 | Claude→OpenAI→Gemini | Claude→OpenAI→Ali | 直通 | Claude→OpenAI→Ollama |
| **Gemini** | Gemini→OpenAI | Gemini→OpenAI→Claude | 直通 | × | × | × |

### 响应转换矩阵

| 上游 \ 客户端 | OpenAI | Claude | Gemini |
|---|---|---|---|
| **OpenAI** | 直通 | OpenAI→Claude | OpenAI→Gemini |
| **Claude** | Claude→OpenAI | 直通 | Claude→OpenAI→Gemini |
| **Gemini** | Gemini→OpenAI | Gemini→OpenAI→Claude | 直通 |
| **Ali/Ollama/其他** | →OpenAI | →OpenAI→Claude | × |

---

## 九、关键文件索引

| 文件路径 | 行数 | 功能 |
|---|---|---|
| `relay/channel/adapter.go` | 83 | Adaptor/TaskAdaptor 接口定义 |
| `relay/relay_adaptor.go` | 165 | 适配器工厂函数 GetAdaptor/GetTaskAdaptor |
| `types/relay_format.go` | 19 | RelayFormat 类型定义 |
| `constant/api_type.go` | 40 | API 类型常量 (35种) |
| `service/convert.go` | ~1007 | **核心转换库** (OpenAI↔Claude↔Gemini) |
| `relay/channel/claude/relay-claude.go` | ~1009 | Claude 原生格式转换 |
| `relay/channel/gemini/relay-gemini.go` | ~1900 | Gemini 原生格式转换 + Thinking adapter |
| `relay/channel/gemini/relay-gemini-native.go` | 97 | Gemini 原生直通处理 |
| `relay/channel/openai/adaptor.go` | ~683 | OpenAI 适配器 (含 Claude/Gemini 入口) |
| `relay/channel/openai/helper.go` | ~261 | 流式格式分发器 HandleStreamFormat |
| `relay/channel/openai/relay-openai.go` | ~718 | OpenAI 响应处理 (含 WebSocket 代理) |
| `relay/channel/openai/chat_via_responses.go` | ~550 | Chat→Responses 内部路由 |
| `service/openaicompat/chat_to_responses.go` | ~402 | Chat→Responses 转换 |
| `service/openaicompat/responses_to_chat.go` | ~133 | Responses→Chat 转换 |
| `relay/common/relay_info.go` | ~890 | RelayInfo 上下文对象 |
| `relay/common/request_conversion.go` | 40 | 转换链跟踪 |
| `controller/relay.go` | ~647 | 主控制器 (含重试循环) |
| `router/relay-router.go` | 224 | 路由定义 |
| `relay/compatible_handler.go` | 217 | OpenAI 格式文本请求处理 (TextHelper) |
| `relay/claude_handler.go` | 214 | Claude 格式请求处理 (ClaudeHelper) |
| `relay/gemini_handler.go` | 293 | Gemini 格式请求处理 (GeminiHelper) |
| `relay/responses_handler.go` | 161 | Responses API 处理 |
| `relay/chat_completions_via_responses.go` | 161 | Chat-via-Responses 桥接处理 |

---

## 十、总结

`new-api` 的转换层是一个**多协议 Hub-and-Spoke API 网关转换系统**，核心特点：

1. **Hub-and-Spoke 架构**: 以 OpenAI 格式为枢纽，避免 O(n²) 的转换矩阵，通过链式转换支持任意输入/输出格式组合
2. **多格式输入**: 同一上游提供商可接受 OpenAI、Claude、Gemini 三种主流格式，通过 `RequestConversionChain` 跟踪转换路径
3. **统一适配器接口**: `channel.Adaptor` 接口抽象所有提供商差异，新提供商只需实现该接口
4. **Chat-via-Responses 优化**: 在不改变客户端 API 的前提下内部路由到 Responses API，利用其独有特性
5. **Thinking 深度适配**: Claude/Gemini/OpenAI 三种 thinking/reasoning 模式均有完善的参数适配
6. **流式实时转换**: SSE 流式响应逐块格式转换，包括复杂的状态机管理
7. **异步任务支持**: 独立 `TaskAdaptor` 接口覆盖视频/音乐生成等异步场景
8. **计费深度集成**: 转换层与预扣费、结算、退款等完整计费生命周期集成