668 lines
31 KiB
Markdown
668 lines
31 KiB
Markdown
# One-API 项目转换层深度分析报告
|
||
|
||
## 一、项目概览
|
||
|
||
One-API 是一个基于 Go 语言（Gin 框架）开发的大模型 API 网关代理项目。其核心功能是：**将用户发来的统一 OpenAI 格式请求，转换为各家大模型厂商的原生 API 格式，转发请求后，再将厂商的响应统一转换回 OpenAI 格式返回给用户**。
|
||
|
||
对外暴露的接口完全兼容 OpenAI API 规范，用户只需更改 `base_url` 和 `api_key` 即可使用。
|
||
|
||
### 与同类项目的核心差异
|
||
|
||
One-API 是此类项目的**鼻祖和基线**，采用最简单的架构模式——仅支持 OpenAI 格式作为唯一输入/输出协议，所有转换都是 **OpenAI ↔ 厂商原生格式** 的双向转换。New-API 在其基础上增加了 Claude/Gemini 输入支持和 Hub-and-Spoke 架构。One-API 的设计追求简洁实用：56 种渠道类型通过三层映射归并为 19 种 API 类型，其中 18 种 OpenAI 兼容渠道直接复用同一适配器，实现零开销透传。
|
||
|
||
---
|
||
|
||
## 二、项目目录结构
|
||
|
||
```
|
||
one-api/
|
||
├── main.go # 程序入口
|
||
├── router/
|
||
│ └── relay.go # 路由定义（/v1/chat/completions 等）
|
||
├── middleware/
|
||
│ ├── auth.go # Token 认证
|
||
│ ├── distributor.go # 渠道分发（负载均衡）
|
||
│ └── rate-limit.go # 限流
|
||
├── controller/
|
||
│ └── relay.go # 入口控制器（含重试逻辑）
|
||
├── relay/ # ★ 转换层核心目录
|
||
│ ├── adaptor.go # Adaptor 工厂函数 (69行)
|
||
│ ├── adaptor/ # 各厂商 Adaptor 实现
|
||
│ │ ├── interface.go # Adaptor 接口定义 (9方法)
|
||
│ │ ├── common.go # 公共辅助函数
|
||
│ │ ├── openai/ # OpenAI 适配器（基座）
|
||
│ │ ├── anthropic/ # Anthropic Claude 适配器
|
||
│ │ ├── gemini/ # Google Gemini 适配器
|
||
│ │ ├── geminiv2/ # Gemini V2 模型适配器
|
||
│ │ ├── ali/ # 阿里通义千问适配器
|
||
│ │ ├── baidu/ # 百度文心适配器
|
||
│ │ ├── zhipu/ # 智谱 ChatGLM 适配器
|
||
│ │ ├── tencent/ # 腾讯混元适配器
|
||
│ │ ├── xunfei/ # 讯飞星火适配器
|
||
│ │ ├── aws/ # AWS Bedrock Claude 适配器 (含子适配器)
|
||
│ │ │ ├── claude/ # Claude on Bedrock
|
||
│ │ │ └── llama3/ # Llama3 on Bedrock
|
||
│ │ ├── vertexai/ # Google Vertex AI (含子适配器)
|
||
│ │ │ ├── claude/ # Claude on Vertex AI
|
||
│ │ │ └── gemini/ # Gemini on Vertex AI
|
||
│ │ ├── ollama/ # Ollama 适配器
|
||
│ │ ├── coze/ # Coze 适配器
|
||
│ │ ├── cohere/ # Cohere 适配器
|
||
│ │ ├── cloudflare/ # Cloudflare Workers AI 适配器
|
||
│ │ ├── deepl/ # DeepL 翻译适配器
|
||
│ │ ├── replicate/ # Replicate 适配器
|
||
│ │ ├── palm/ # Google PaLM 适配器
|
||
│ │ ├── proxy/ # 通用代理适配器
|
||
│ │ ├── aiproxy/ # AIProxy 适配器
|
||
│ │ └── ... (38个子目录)
|
||
│ ├── controller/ # 中转控制器（按功能分类）
|
||
│ │ ├── text.go # 文本类请求处理 (115行)
|
||
│ │ ├── image.go # 图片生成请求处理 (238行)
|
||
│ │ ├── audio.go # 音频请求处理 (281行)
|
||
│ │ ├── proxy.go # 通用代理请求处理
|
||
│ │ ├── helper.go # 辅助函数（配额、计费等）
|
||
│ │ └── error.go # 统一错误处理
|
||
│ ├── meta/
|
||
│ │ └── relay_meta.go # 请求元数据结构 (66行)
|
||
│ ├── model/ # 内部数据模型
|
||
│ │ ├── general.go # 统一 OpenAI 请求结构 (88行)
|
||
│ │ ├── message.go # 消息结构（支持多模态） (91行)
|
||
│ │ ├── misc.go # Usage、Error 等通用结构 (27行)
|
||
│ │ ├── tool.go # Tool/Function Calling 结构
|
||
│ │ └── image.go # 图片请求结构
|
||
│ ├── apitype/
|
||
│ │ └── define.go # API 类型枚举 (19种)
|
||
│ ├── channeltype/
|
||
│ │ ├── define.go # 渠道类型枚举 (56种)
|
||
│ │ ├── helper.go # ChannelType → APIType 映射
|
||
│ │ └── url.go # 各渠道默认 BaseURL (52条)
|
||
│ ├── relaymode/
|
||
│ │ ├── define.go # 中转模式枚举 (11种)
|
||
│ │ └── helper.go # URL 路径 → 中转模式映射
|
||
│ └── billing/ # 计费相关
|
||
└── model/ # 数据库模型
|
||
├── channel.go # 渠道配置
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 三、转换层技术架构
|
||
|
||
### 3.1 整体架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 用户请求 (OpenAI 格式) │
|
||
│ POST /v1/chat/completions │
|
||
└──────────────────┬──────────────────────┘
|
||
│
|
||
┌──────────────────▼──────────────────────┐
|
||
│ router/relay.go │
|
||
│ 路由: /v1/* → controller.Relay │
|
||
└──────────────────┬──────────────────────┘
|
||
│
|
||
┌──────────────────▼──────────────────────┐
|
||
│ middleware (中间件链) │
|
||
│ CORS → GzipDecode → PanicRecover │
|
||
│ → TokenAuth → Distribute │
|
||
│ 1. 解析 Token, 验证身份 │
|
||
│ 2. 根据模型名选择渠道(随机负载均衡) │
|
||
│ 3. 将渠道信息注入 gin.Context │
|
||
└──────────────────┬──────────────────────┘
|
||
│
|
||
┌──────────────────▼──────────────────────┐
|
||
│ controller/relay.go │
|
||
│ 1. 根据 URL 判断 relayMode │
|
||
│ 2. 调用 relayHelper 分发 │
|
||
│ 3. 失败时自动重试(切换渠道) │
|
||
└──────────────────┬──────────────────────┘
|
||
│
|
||
┌────────────────────────┼────────────────────────┐
|
||
│ │ │
|
||
┌─────────▼──────────┐ ┌─────────▼──────────┐ ┌─────────▼──────────┐
|
||
│ RelayTextHelper │ │ RelayImageHelper │ │ RelayAudioHelper │
|
||
│ text.go (115行) │ │ image.go (238行) │ │ audio.go (281行) │
|
||
└─────────┬──────────┘ └─────────┬──────────┘ └─────────┬──────────┘
|
||
│ │ │
|
||
└────────────────────────┼────────────────────────┘
|
||
│
|
||
┌──────────────────▼──────────────────────┐
|
||
│ relay/adaptor.go │
|
||
│ GetAdaptor(apiType) → 具体Adaptor实例 │
|
||
└──────────────────┬──────────────────────┘
|
||
│
|
||
┌────────────────────────┼────────────────────────┐
|
||
│ │ │
|
||
┌─────────▼──────────┐ ┌─────────▼──────────┐ ┌─────────▼──────────┐
|
||
│ openai.Adaptor │ │ anthropic.Adaptor │ │ gemini.Adaptor │
|
||
│ ConvertRequest() │ │ ConvertRequest() │ │ ConvertRequest() │
|
||
│ DoRequest() │ │ DoRequest() │ │ DoRequest() │
|
||
│ DoResponse() │ │ DoResponse() │ │ DoResponse() │
|
||
└─────────┬──────────┘ └─────────┬──────────┘ └─────────┬──────────┘
|
||
│ │ │
|
||
└────────────────────────┼────────────────────────┘
|
||
│
|
||
┌──────────────────▼──────────────────────┐
|
||
│ 上游大模型厂商 API │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 核心设计模式：适配器模式
|
||
|
||
**Adaptor 接口** (`relay/adaptor/interface.go`, 21 行):
|
||
|
||
```go
|
||
type Adaptor interface {
|
||
Init(meta *meta.Meta) // 初始化元数据
|
||
GetRequestURL(meta *meta.Meta) (string, error) // 构建请求 URL
|
||
SetupRequestHeader(c, req, meta) error // 设置认证请求头
|
||
ConvertRequest(c, mode, request) (any, error) // 请求体转换 (OpenAI → 厂商)
|
||
ConvertImageRequest(request) (any, error) // 图片请求转换
|
||
DoRequest(c, meta, requestBody) (*http.Response, error) // 发送 HTTP 请求
|
||
DoResponse(c, resp, meta) (usage, err) // 响应体转换 (厂商 → OpenAI)
|
||
GetModelList() []string // 返回支持的模型列表
|
||
GetChannelName() string // 返回渠道名称
|
||
}
|
||
```
|
||
|
||
**9 个方法**构成最精简的适配器接口，相比 New-API 的 15+ 方法接口更聚焦。
|
||
|
||
### 3.3 三层映射关系
|
||
|
||
项目通过三层映射将"渠道"与"转换逻辑"关联：
|
||
|
||
```
|
||
ChannelType (渠道类型) → APIType (API 类型) → Adaptor (适配器实例)
|
||
(56 种) (19 种) (18 个实现)
|
||
```
|
||
|
||
- **ChannelType**: 具体的厂商/服务商标识（56 种）
|
||
- **APIType**: 共享同一套转换逻辑的分组（19 种，定义在 `relay/apitype/define.go`）
|
||
- **Adaptor**: 负责具体转换逻辑的实例
|
||
|
||
**映射代码**: `relay/channeltype/helper.go` 的 `ToAPIType()` 函数。
|
||
|
||
**关键设计**: 18 种 OpenAI 兼容渠道的 APIType 被映射为 `apitype.OpenAI`，直接复用 `openai.Adaptor`，无需编写独立转换逻辑。兼容渠道列表 (`relay/adaptor/openai/compatible.go`):
|
||
|
||
```go
|
||
var CompatibleChannels = []int{
|
||
Azure, AI360, Moonshot, Baichuan, Minimax, Doubao,
|
||
Mistral, Groq, LingYiWanWu, StepFun, DeepSeek, TogetherAI,
|
||
Novita, SiliconFlow, XAI, BaiduV2, XunfeiV2,
|
||
}
|
||
```
|
||
|
||
另有 OpenRouter、AliBailian、GeminiOpenAICompatible 也有特殊映射处理。
|
||
|
||
### 3.4 Adaptor 工厂
|
||
|
||
**文件**: `relay/adaptor.go` (69 行)
|
||
|
||
`GetAdaptor(apiType int)` 映射 18 种 API 类型到具体适配器实例（Proxy 类型额外处理）。
|
||
|
||
---
|
||
|
||
## 四、请求处理完整流程
|
||
|
||
### 4.1 路由阶段
|
||
|
||
**文件**: `router/relay.go` (74 行)
|
||
|
||
所有 `/v1/` 下的请求都经过中间件链：`CORS() → GzipDecodeMiddleware() → RelayPanicRecover → TokenAuth → Distribute`
|
||
|
||
### 4.2 中间件阶段
|
||
|
||
#### Token 认证 (middleware/auth.go, 167 行)
|
||
- 从 `Authorization` 头提取 `Bearer <token>`
|
||
- 管理员可通过 `sk-<token>-<channelId>` 指定特定渠道
|
||
- 验证 Token 有效性，提取 userId、tokenId
|
||
- 从请求体解析 `model` 字段，验证模型可用性
|
||
- 支持 IP 子网限制
|
||
|
||
#### 渠道分发 (middleware/distributor.go, 102 行)
|
||
- 获取用户分组 (group)
|
||
- 根据 group + model 随机选择一个可用渠道
|
||
- 将渠道信息注入 `gin.Context`：渠道类型、API Key、BaseURL、ModelMapping 等
|
||
- 渠道类型转换为 APIType，存入 meta
|
||
|
||
### 4.3 控制器阶段
|
||
|
||
**文件**: `controller/relay.go` (156 行)
|
||
|
||
```go
|
||
func Relay(c *gin.Context) {
|
||
relayMode := relaymode.GetByPath(c.Request.URL.Path)
|
||
bizErr := relayHelper(c, relayMode)
|
||
// 失败时自动重试：切换到其他渠道
|
||
for i := retryTimes; i > 0; i-- {
|
||
channel := CacheGetRandomSatisfiedChannel(group, model)
|
||
SetupContextForSelectedChannel(c, channel, model)
|
||
bizErr = relayHelper(c, relayMode)
|
||
}
|
||
}
|
||
```
|
||
|
||
`relayHelper` 根据 `relayMode` 分发：
|
||
- `ChatCompletions / Completions / Embeddings / Moderations` → `RelayTextHelper`
|
||
- `ImagesGenerations` → `RelayImageHelper`
|
||
- `AudioSpeech / AudioTranscription / AudioTranslation` → `RelayAudioHelper`
|
||
- `Proxy` → `RelayProxyHelper`
|
||
|
||
**重试策略**: 429 和 5xx 触发重试，400 和 2xx 不重试。管理员指定渠道时不重试。
|
||
|
||
### 4.4 转换处理阶段 — RelayTextHelper
|
||
|
||
**文件**: `relay/controller/text.go` (115 行)
|
||
|
||
```go
|
||
func RelayTextHelper(c *gin.Context) *model.ErrorWithStatusCode {
|
||
// 1. 解析请求（统一按 OpenAI 格式解析）
|
||
meta := meta.GetByContext(c)
|
||
textRequest := getAndValidateTextRequest(c, meta.Mode)
|
||
|
||
// 2. 模型名称映射
|
||
textRequest.Model = getMappedModelName(textRequest.Model, meta.ModelMapping)
|
||
|
||
// 3. 强制系统提示词注入
|
||
setSystemPrompt(textRequest, meta)
|
||
|
||
// 4. 计算配额、预扣费
|
||
promptTokens := getPromptTokens(textRequest, meta.Mode)
|
||
preConsumedQuota := preConsumeQuota(...) // 用户配额 > 100x预扣时跳过
|
||
|
||
// 5. 获取对应 Adaptor
|
||
adaptor := relay.GetAdaptor(meta.APIType)
|
||
adaptor.Init(meta)
|
||
|
||
// 6. 请求转换（OpenAI 格式 → 厂商格式）
|
||
requestBody := getRequestBody(c, meta, textRequest, adaptor)
|
||
|
||
// 7. 发送请求到上游
|
||
resp := adaptor.DoRequest(c, meta, requestBody)
|
||
|
||
// 8. 响应转换（厂商格式 → OpenAI 格式）
|
||
usage := adaptor.DoResponse(c, resp, meta)
|
||
|
||
// 9. 后扣费
|
||
postConsumeQuota(usage, ...)
|
||
}
|
||
```
|
||
|
||
#### 请求体透传优化
|
||
|
||
**文件**: `relay/controller/text.go` 的 `getRequestBody()` 函数
|
||
|
||
当满足以下所有条件时，**跳过请求转换**，直接透传原始请求体：
|
||
- API 类型为 OpenAI
|
||
- 模型名未被映射
|
||
- 渠道不是百川（百川有特殊处理）
|
||
- 无强制系统提示词
|
||
- 未启用 include_usage 强制选项
|
||
|
||
```go
|
||
if meta.APIType == apitype.OpenAI &&
|
||
meta.OriginModelName == meta.ActualModelName &&
|
||
meta.ChannelType != channeltype.Baichuan &&
|
||
meta.ForcedSystemPrompt == "" {
|
||
return c.Request.Body, nil // 直接透传，零开销
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、各厂商转换逻辑详解
|
||
|
||
### 5.1 OpenAI 适配器（基座）
|
||
|
||
**文件**: `relay/adaptor/openai/` (9 文件)
|
||
|
||
作为项目的"基座适配器"，不仅处理 OpenAI 自身，还被 18 种 OpenAI 兼容渠道复用。
|
||
|
||
**请求转换**: 基本不需要格式转换，直接透传 `GeneralOpenAIRequest`。唯一处理：流式模式下自动注入 `stream_options.include_usage = true`。
|
||
|
||
**URL 构建**: 根据渠道类型有不同逻辑：
|
||
- 标准 OpenAI 兼容: `BaseURL + RequestURLPath`
|
||
- Azure: `/openai/deployments/{model}/{task}?api-version=xxx`
|
||
- Minimax/Doubao/Novita/BaiduV2/AliBailian/GeminiOpenAICompatible: 各有独立 URL 逻辑
|
||
|
||
**认证方式**:
|
||
- 标准渠道: `Authorization: Bearer <api_key>`
|
||
- Azure: `api-key: <api_key>`
|
||
- OpenRouter: 额外 `HTTP-Referer` 和 `X-Title` 头
|
||
|
||
**流式处理**: 逐行解析 SSE (`data: {...}`)，提取 usage 信息，支持 Cloudflare AI Gateway URL。
|
||
|
||
### 5.2 Anthropic Claude 适配器
|
||
|
||
**文件**: `relay/adaptor/anthropic/` (4 文件, main.go 379 行)
|
||
|
||
Claude 使用完全不同的 API 格式，需要大量转换工作。
|
||
|
||
**请求转换** (main.go `ConvertRequest()`):
|
||
|
||
| OpenAI 字段 | Claude 字段 | 转换说明 |
|
||
|---|---|---|
|
||
| `messages[].role = "system"` | `system` (顶层字段) | 系统提示词提取到顶层 |
|
||
| `messages[].content` (string) | `messages[].content` (Content 数组) | 包装为 `[{type:"text", text:"..."}]` |
|
||
| `messages[].role = "tool"` | `messages[].role = "user"` + `type = "tool_result"` | 工具结果转为用户消息 |
|
||
| `messages[].tool_calls` | `content.type = "tool_use"` | 工具调用转为 content 块 |
|
||
| `tools[].function.parameters` | `tools[].input_schema` | 字段名转换 |
|
||
| `tool_choice` | `tool_choice.type + name` | auto/tool/any 格式映射 |
|
||
| `max_tokens` | `max_tokens` | 直接映射，默认 4096 |
|
||
|
||
**认证**: `x-api-key: <api_key>` + `anthropic-version: 2023-06-01`。Claude 3.5 Sonnet 额外添加 `anthropic-beta: max-tokens-3-5-sonnet-2024-07-15`。
|
||
|
||
**URL**: `{base_url}/v1/messages`
|
||
|
||
**响应转换**:
|
||
|
||
| Claude 字段 | OpenAI 字段 |
|
||
|---|---|
|
||
| `content[].text` | `choices[].message.content` |
|
||
| `content[].type = "tool_use"` | `choices[].message.tool_calls[]` |
|
||
| `stop_reason: "end_turn"/"stop_sequence"` | `finish_reason: "stop"` |
|
||
| `stop_reason: "max_tokens"` | `finish_reason: "length"` |
|
||
| `stop_reason: "tool_use"` | `finish_reason: "tool_calls"` |
|
||
| `usage.input_tokens/output_tokens` | `usage.prompt_tokens/completion_tokens` |
|
||
|
||
**流式处理**: Claude 的 SSE 事件类型（`message_start`、`content_block_start`、`content_block_delta`、`message_delta`）逐事件转换为 OpenAI 的 `chat.completion.chunk` 格式。
|
||
|
||
### 5.3 Google Gemini 适配器
|
||
|
||
**文件**: `relay/adaptor/gemini/` (4 文件, main.go 437 行)
|
||
|
||
**请求转换**:
|
||
|
||
| OpenAI 字段 | Gemini 字段 | 转换说明 |
|
||
|---|---|---|
|
||
| `messages[]` | `contents[]` | 数组结构转换 |
|
||
| `role = "assistant"` | `role = "model"` | 角色名映射 |
|
||
| `role = "system"` | `systemInstruction` 或 `role = "user"` | 新模型用 systemInstruction，旧模型转 user |
|
||
| `tools[].function` | `tools[].functionDeclarations[]` | 字段名转换 |
|
||
| `temperature/top_p/max_tokens` | `generationConfig.{temperature, topP, maxOutputTokens}` | 包装到 generationConfig |
|
||
| `response_format.type = "json_object"` | `responseMimeType = "application/json"` | MIME 类型映射 |
|
||
|
||
**特殊处理**:
|
||
- system 消息后自动插入 `model: "Okay"` 虚拟消息（Gemini API 要求角色交替）
|
||
- 安全设置设为最低 (`GeminiSafetySetting`，5 个类别)
|
||
- 图片数量限制最多 16 张，转为 base64 inlineData
|
||
- 支持 system instruction 的模型列表硬编码: `gemini-2.0-flash`, `gemini-2.0-flash-exp`, `gemini-2.0-flash-thinking-exp-01-21`
|
||
|
||
**URL**: `{base_url}/{version}/models/{model}:{action}`
|
||
- 版本选择: `gemini-2.0` 和 `gemini-1.5` 用 `v1beta`；其他用 `config.GeminiVersion`
|
||
- 非流式: `generateContent`
|
||
- 流式: `streamGenerateContent?alt=sse`
|
||
- Embedding: `batchEmbedContents`
|
||
|
||
**认证**: `x-goog-api-key: <api_key>`
|
||
|
||
### 5.4 阿里通义千问适配器
|
||
|
||
**文件**: `relay/adaptor/ali/` (5 文件, main.go 267 行)
|
||
|
||
使用阿里 DashScope API 格式。
|
||
|
||
**请求转换**:
|
||
- Messages 包装到 `Input.Messages`，参数包装到 `Parameters`（含 `ResultFormat: "message"`, `IncrementalOutput`, `EnableSearch`）
|
||
- 模型名后缀 `-internet` 启用联网搜索 (`EnableSearch: true`)
|
||
- `top_p` 上限为 0.9999
|
||
- 图片生成使用异步模式 (`X-DashScope-Async: enable`)，轮询等待（最多 20 步，2 秒间隔）
|
||
|
||
**URL**:
|
||
- 文本: `/api/v1/services/aigc/text-generation/generation`
|
||
- Embedding: `/api/v1/services/embeddings/text-embedding/text-embedding`
|
||
- 图片: `/api/v1/services/aigc/text2image/image-synthesis`
|
||
|
||
**特殊头**: `X-DashScope-SSE: enable` (流式), `X-DashScope-Async: enable` (异步)
|
||
|
||
### 5.5 百度文心一言适配器
|
||
|
||
**文件**: `relay/adaptor/baidu/` (4 文件, main.go 312 行)
|
||
|
||
**认证方式**: 百度不使用 API Key 直接认证，而是先通过 `client_id|client_secret` 获取 `access_token`，然后在 URL 中传递。
|
||
|
||
**access_token 缓存机制**:
|
||
- `baiduTokenStore` 使用 `sync.Map` 存储
|
||
- 缓存的 token 在过期前 1 小时触发异步刷新
|
||
- API Key 格式: `client_id|client_secret`，通过 OAuth2 端点获取 token
|
||
|
||
**请求转换**: 系统消息提取到 `System` 字段，`FrequencyPenalty` → `PenaltyScore`
|
||
|
||
**URL**: `{base_url}/rpc/2.0/ai_custom/v1/wenxinworkshop/{suffix}?access_token={token}`
|
||
- URL 中包含模型端点名称（如 `chat/completions_pro`），通过大量 switch-case 映射模型名到端点
|
||
|
||
### 5.6 智谱 ChatGLM 适配器
|
||
|
||
**文件**: `relay/adaptor/zhipu/` (4 文件)
|
||
|
||
**双版本支持**:
|
||
- **v4** (`glm-*` 模型): `/api/paas/v4/chat/completions` — **OpenAI 兼容**，直接复用 OpenAI 的 StreamHandler/Handler
|
||
- **v3**: `/api/paas/v3/model-api/{model}/{method}` — 自有格式
|
||
|
||
**认证**: JWT token（API Key 格式 `id.secret`，HMAC-SHA256 签名）
|
||
|
||
### 5.7 腾讯混元适配器
|
||
|
||
**文件**: `relay/adaptor/tencent/` (4 文件, main.go 307 行)
|
||
|
||
- URL: `{baseURL}/` (单一端点)
|
||
- 认证: **TC3-HMAC-SHA256** 签名算法（完整实现在 main.go 中）
|
||
- API Key 格式: `appId|secretId|secretKey`
|
||
|
||
### 5.8 讯飞星火适配器
|
||
|
||
**文件**: `relay/adaptor/xunfei/` (5 文件, main.go 273 行)
|
||
|
||
- **协议**: WebSocket（唯一非 HTTP 适配器）
|
||
- `GetRequestURL()` 返回空字符串，`DoRequest()` 返回 dummy 200
|
||
- `DoResponse()` 处理实际 WebSocket 通信
|
||
- 认证: HMAC-SHA256 签名的 WebSocket URL
|
||
- API Key 格式: `appId|apiSecret|apiKey` (pipe 分隔三部分)
|
||
- 流式: 使用 `c.Stream()` + SSE 格式
|
||
- 非流式: 累积所有 WebSocket chunk 后返回单次响应
|
||
|
||
### 5.9 AWS Bedrock Claude 适配器
|
||
|
||
**文件**: `relay/adaptor/aws/` (5 文件)
|
||
|
||
- 使用 **AWS SDK v2** `bedrockruntime.Client`，不走 HTTP
|
||
- **子适配器模式**: `registry.go` 根据模型名分派到 `aws/claude/` 或 `aws/llama3/`
|
||
- `aws/claude/`: 复用 `anthropic.ConvertRequest()` 转换请求，使用 Bedrock `InvokeModel`/`InvokeModelWithResponseStream` 通信
|
||
- `aws/llama3/`: Llama3 专用转换
|
||
|
||
### 5.10 Google Vertex AI 适配器
|
||
|
||
**文件**: `relay/adaptor/vertexai/` (5 文件)
|
||
|
||
- URL: `{baseURL}/v1/projects/{project}/locations/{region}/publishers/google/models/{model}:{action}`
|
||
- Claude: `rawPredict`/`streamRawPredict?alt=sse`
|
||
- Gemini: `generateContent`/`streamGenerateContent?alt=sse`
|
||
- **子适配器模式**: `registry.go` 分派到 `vertexai/claude/` 或 `vertexai/gemini/`
|
||
- `vertexai/claude/`: 复用 `anthropic.ConvertRequest()`，设置 `anthropic_version: "vertex-2023-10-16"`
|
||
- `vertexai/gemini/`: 复用 `gemini.ConvertRequest()`
|
||
- 认证: Google Cloud IAM `GenerateAccessToken` (ADC)，Token 缓存 50 分钟 TTL
|
||
|
||
### 5.11 其他适配器简述
|
||
|
||
| 适配器 | 文件 | 关键特征 |
|
||
|-------|------|---------|
|
||
| **Ollama** | `adaptor/ollama/` | 类 OpenAI 格式，`/api/chat` 或 `/api/generate` |
|
||
| **Coze** | `adaptor/coze/` | 字节跳动 Coze 平台 |
|
||
| **Cohere** | `adaptor/cohere/` | Cohere 自有 API 格式 |
|
||
| **Cloudflare** | `adaptor/cloudflare/` | Workers AI，URL 支持 Cloudflare AI Gateway |
|
||
| **DeepL** | `adaptor/deepl/` | 翻译 API，非 LLM |
|
||
| **Replicate** | `adaptor/replicate/` | 异步任务模式 |
|
||
| **PaLM** | `adaptor/palm/` | Google PaLM (旧版) |
|
||
| **Proxy** | `adaptor/proxy/` | 通用透传代理，无转换 |
|
||
|
||
---
|
||
|
||
## 六、统一数据模型
|
||
|
||
### 6.1 统一请求模型 (`relay/model/general.go`, 88 行)
|
||
|
||
```go
|
||
type GeneralOpenAIRequest struct {
|
||
Messages []Message // 聊天消息
|
||
Model string // 模型名
|
||
MaxTokens int // 最大生成 token
|
||
MaxCompletionTokens int // 最大完成 token (o-series)
|
||
Temperature *float64 // 温度
|
||
TopP *float64 // Top-P
|
||
TopK int // Top-K
|
||
Stream bool // 流式
|
||
StreamOptions *StreamOptions // 流式选项
|
||
Tools []Tool // 工具调用
|
||
ToolChoice any // 工具选择
|
||
Stop any // 停止词
|
||
ResponseFormat *ResponseFormat // 响应格式
|
||
ReasoningEffort string // 推理强度
|
||
Store *bool // 存储标记
|
||
// ... 更多字段
|
||
}
|
||
```
|
||
|
||
这是整个项目的"通用语言"——所有厂商的请求都先解析为此格式，再由各 Adaptor 转换为厂商格式。
|
||
|
||
### 6.2 统一消息模型 (`relay/model/message.go`, 91 行)
|
||
|
||
```go
|
||
type Message struct {
|
||
Role string // system / user / assistant / tool / developer
|
||
Content any // 字符串 或 多模态内容数组
|
||
ReasoningContent any // 推理内容 (o1 等模型)
|
||
Name *string // 消息发送者名称
|
||
ToolCalls []Tool // 工具调用结果
|
||
ToolCallId string // 工具调用 ID
|
||
}
|
||
```
|
||
|
||
`Content` 支持字符串（纯文本）和数组（多模态：text + image_url），通过 `ParseContent()` 解析。
|
||
|
||
### 6.3 统一 Usage 模型
|
||
|
||
```go
|
||
type Usage struct {
|
||
PromptTokens int
|
||
CompletionTokens int
|
||
TotalTokens int
|
||
}
|
||
```
|
||
|
||
### 6.4 统一错误模型
|
||
|
||
所有上游错误统一转换为 OpenAI 错误格式：
|
||
```json
|
||
{"error": {"message": "...", "type": "...", "param": "...", "code": "..."}}
|
||
```
|
||
|
||
`GeneralErrorResponse` 兼容多种厂商的错误格式（OpenAI 的 `error.message`、通用的 `message`、百度的 `error_msg` 等）。
|
||
|
||
---
|
||
|
||
## 七、中转模式 (RelayMode)
|
||
|
||
**文件**: `relay/relaymode/` (2 文件)
|
||
|
||
11 种中转模式，根据 URL 路径自动判断：
|
||
|
||
| 模式 | URL 路径 | 说明 |
|
||
|------|---------|------|
|
||
| ChatCompletions | `/v1/chat/completions` | Chat 聊天补全 |
|
||
| Completions | `/v1/completions` | 文本补全 |
|
||
| Embeddings | `/v1/embeddings`, `/v1/engines/:model/embeddings` | 文本嵌入 |
|
||
| Moderations | `/v1/moderations` | 内容审核 |
|
||
| ImagesGenerations | `/v1/images/generations` | 图片生成 |
|
||
| Edits | `/v1/edits` | 文本编辑 |
|
||
| AudioSpeech | `/v1/audio/speech` | 语音合成 |
|
||
| AudioTranscription | `/v1/audio/transcriptions` | 语音识别 |
|
||
| AudioTranslation | `/v1/audio/translations` | 语音翻译 |
|
||
| Proxy | `/v1/oneapi/proxy/:channelid/*target` | 通用代理 |
|
||
|
||
判断逻辑通过 `strings.HasPrefix` 匹配。
|
||
|
||
---
|
||
|
||
## 八、关键业务逻辑
|
||
|
||
### 8.1 配额管理
|
||
|
||
"预扣费 + 后结算"机制：
|
||
1. **预扣费**: 根据 prompt tokens 和模型倍率预先扣除估算配额
|
||
2. **后结算**: 根据 usage 的实际 token 数计算费用并调整
|
||
3. 信任优化: 用户配额超过预扣费 100 倍时跳过预扣
|
||
|
||
### 8.2 自动重试
|
||
|
||
请求失败时 (429/5xx)：
|
||
1. 选择另一个不同的渠道（随机负载均衡）
|
||
2. 重新设置上下文
|
||
3. 从缓存的原始 body 重放请求
|
||
4. 最多重试 `RetryTimes` 次
|
||
5. 429 返回特殊消息"当前分组上游负载已饱和，请稍后再试"
|
||
|
||
### 8.3 错误监控
|
||
|
||
`processChannelRelayError()` 异步记录错误，并通过 `monitor.ShouldDisableChannel()` 自动禁用频繁出错的渠道。
|
||
|
||
---
|
||
|
||
## 九、流式 (SSE) 处理架构
|
||
|
||
### 9.1 统一处理流程
|
||
|
||
```
|
||
上游 SSE 流 → Scanner 逐行扫描 → 解析厂商 JSON → 转换为 OpenAI 格式 → SSE 写回客户端
|
||
```
|
||
|
||
### 9.2 各厂商 SSE 格式对比
|
||
|
||
| 厂商 | SSE 前缀 | 数据格式 | 结束标记 |
|
||
|------|---------|---------|---------|
|
||
| OpenAI | `data: ` | `ChatCompletionsStreamResponse` | `data: [DONE]` |
|
||
| Anthropic | `data:` | `StreamResponse` (type 字段区分事件) | 无显式标记 |
|
||
| Gemini | `data: ` | `ChatResponse` | 无显式标记 |
|
||
| 阿里 | `data:` | `ChatResponse` (`\n` 分隔) | 无显式标记 |
|
||
| 百度 | `data: ` | `ChatStreamResponse` | `is_end = true` |
|
||
|
||
### 9.3 OpenAI 兼容渠道的 SSE 优化
|
||
|
||
OpenAI 兼容渠道的流式数据直接透传给客户端，仅需解析统计 usage 信息，不需要格式转换。
|
||
|
||
---
|
||
|
||
## 十、架构总结
|
||
|
||
### 10.1 核心设计原则
|
||
|
||
1. **统一入口，适配器分发**: 所有请求通过同一入口，由工厂模式创建对应适配器
|
||
2. **OpenAI 格式为"通用语言"**: 内部所有流转使用 OpenAI 格式，仅在"进出"时转换
|
||
3. **接口抽象**: 通过 `Adaptor` 接口 (9 方法) 隔离各厂商差异，新增厂商只需实现接口
|
||
4. **零拷贝优化**: OpenAI 兼容渠道无特殊处理时直接透传请求体
|
||
5. **关注点分离**: 认证、分发、转换、计费、重试各自独立
|
||
|
||
### 10.2 新增厂商适配步骤
|
||
|
||
1. 在 `relay/channeltype/define.go` 添加 `ChannelType` 常量
|
||
2. 在 `relay/apitype/define.go` 添加 `APIType`（或复用已有）
|
||
3. 在 `relay/channeltype/helper.go` 添加 `ToAPIType()` 映射
|
||
4. 在 `relay/channeltype/url.go` 添加默认 BaseURL
|
||
5. 创建 `relay/adaptor/<vendor>/` 目录实现 `Adaptor` 接口
|
||
6. 如果复用 OpenAI 格式，只需在 `compatible.go` 的 `CompatibleChannels` 列表中添加
|
||
|
||
### 10.3 架构特点
|
||
|
||
**优点**:
|
||
- 接口精简（9 方法），扩展性强
|
||
- 18 种 OpenAI 兼容渠道零开销透传
|
||
- 自动重试 + 渠道切换 + 错误监控自动禁用
|
||
- 统一的计费和错误处理
|
||
- 子适配器模式支持 Bedrock/Vertex AI 的多云厂商模型
|
||
|
||
**局限**:
|
||
- 仅支持 OpenAI 格式输入/输出（New-API 已在此基础上扩展了 Claude/Gemini 输入）
|
||
- 音频处理未完全走 Adaptor 接口
|
||
- 部分适配器 SSE 解析逻辑有重复模式，可抽取公共基类
|
||
- 缺少请求/响应中间件钩子的统一注入点
|