1708 lines
71 KiB
Markdown
1708 lines
71 KiB
Markdown
# LLM API Protocol Conversion Layer — Architecture Design
|
||
|
||
> 语言无关的 HTTP 层 SDK。以 Hub-and-Spoke 架构实现 OpenAI / Anthropic 协议间的双向转换，覆盖完整 HTTP 接口体系，同协议自动透传，为新协议和多模态预留扩展点。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [设计目标与约束](#1-设计目标与约束)
|
||
2. [架构总览](#2-架构总览)
|
||
3. [接口体系分层](#3-接口体系分层)
|
||
4. [Canonical Model（规范模型）](#4-canonical-model规范模型)
|
||
5. [Protocol Adapter 接口](#5-protocol-adapter-接口)
|
||
6. [Conversion Engine（转换引擎）](#6-conversion-engine转换引擎)
|
||
7. [流式转换架构](#7-流式转换架构)
|
||
8. [OpenAI 协议适配器](#8-openai-协议适配器)
|
||
9. [Anthropic 协议适配器](#9-anthropic-协议适配器)
|
||
10. [字段映射参考](#10-字段映射参考)
|
||
11. [扩展点设计](#11-扩展点设计)
|
||
12. [错误处理](#12-错误处理)
|
||
13. [参考实现对比](#13-参考实现对比)
|
||
|
||
---
|
||
|
||
## 1. 设计目标与约束
|
||
|
||
### 1.1 核心目标
|
||
|
||
| 目标 | 说明 |
|
||
|------|------|
|
||
| **完整 HTTP 接口体系转换** | 覆盖 /models、/embeddings、/files、/rerank 等全部接口的 URL 路由映射、请求头转换、请求体/响应体格式转换 |
|
||
| **输入输出解耦** | 客户端协议和上游协议独立指定，任意组合 |
|
||
| **同协议透传** | source == target 时跳过转换，零语义损失、零序列化开销 |
|
||
| **尽力转换** | 能对接的参数尽可能对接，不能对接的各自忽略，保障最大覆盖面 |
|
||
| **协议可扩展** | 添加新协议只需实现 Adapter，不修改核心引擎 |
|
||
| **流式优先** | SSE 流式转换作为核心能力，与非流式同等地位 |
|
||
| **Tool Calling 核心** | 工具调用是编程场景的一等公民 |
|
||
| **语言无关** | 不绑定编程语言，用伪类型描述接口 |
|
||
|
||
### 1.2 约束
|
||
|
||
| 约束 | 说明 |
|
||
|------|------|
|
||
| 部署形态 | HTTP 层 SDK，处理 HTTP 请求/响应转换（URL + Headers + Body），不包含 HTTP 服务器启动/监听 |
|
||
| 当前协议 | OpenAI API、Anthropic API |
|
||
| 当前模态 | 仅文本（含 Tool Calling），接口体系覆盖 /models、/count_tokens、/embeddings、/files、/rerank |
|
||
| Provider 必传 | 每次转换调用需传入 TargetProvider，提供目标上游的地址、认证、模型名等信息 |
|
||
| 适配器注册 | 所有 ProtocolAdapter 通过代码注册，不支持动态增减 |
|
||
| 有状态特性 | 初始不实现，架构预留扩展点 |
|
||
|
||
### 1.3 设计决策溯源
|
||
|
||
| 决策 | 依据 |
|
||
|------|------|
|
||
| HTTP 层 SDK | 编程工具启动时调用 /models、/count_tokens 等接口，缺失会报错或功能降级 |
|
||
| Hub-and-Spoke | new-api 验证了以规范格式为枢纽的可行性，O(n²) 降为 O(n) |
|
||
| 自定义 Canonical Model | 不选用厂商格式，避免语义损失和厂商锁定 |
|
||
| 协议前缀路由 | CC-Switch 的 `/claude/`、`/codex/`、`/gemini/` 前缀验证了 URL 前缀区分协议的可行性 |
|
||
| 接口分层 + 尽力转换 | 不同接口差异程度不同，分层处理最大化覆盖面 |
|
||
| 同协议透传 | CC-Switch 的 Anthropic→Anthropic 直通验证了零转换性能优势 |
|
||
|
||
---
|
||
|
||
## 2. 架构总览
|
||
|
||
### 2.1 分层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ 上层 HTTP 框架（用户自选） │
|
||
│ Express / FastAPI / Axum / Gin / 任意框架 │
|
||
└───────────────────────────────┬─────────────────────────────────────────┘
|
||
│ HTTP 请求/响应
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ Conversion Engine (SDK) │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Protocol Prefix Router │ │
|
||
│ │ │ │
|
||
│ │ 入站: /{protocol}/{native_path} │ │
|
||
│ │ │ │
|
||
│ │ /openai/v1/chat/completions → source=openai, CHAT │ │
|
||
│ │ /anthropic/v1/messages → source=anthropic, CHAT │ │
|
||
│ │ /openai/v1/models → source=openai, MODELS │ │
|
||
│ │ /anthropic/v1/models → source=anthropic, MODELS │ │
|
||
│ │ /openai/v1/* → source=openai, UNKNOWN │ │
|
||
│ │ /anthropic/v1/* → source=anthropic, UNKNOWN │ │
|
||
│ │ │ │
|
||
│ │ Step 1: URL 前缀 → source protocol（唯一依据，无歧义） │ │
|
||
│ │ Step 2: 剥离前缀 → 识别 InterfaceType │ │
|
||
│ │ Step 3: target protocol 由配置决定 │ │
|
||
│ └─────────────────────────────┬───────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────┼────────────┐ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌──────────────┐ ┌─────────┐ ┌──────────┐ │
|
||
│ │ Passthrough │ │核心接口层│ │扩展接口层 │ │
|
||
│ │ 同协议直通 │ │ Chat │ │ Models │ │
|
||
│ │ 或未知接口 │ │ 流式 │ │ Embed │ │
|
||
│ │ 直接转发 │ │ Tool │ │ Files │ │
|
||
│ └──────────────┘ │ Thinking│ │ Rerank │ │
|
||
│ └────┬────┘ └────┬─────┘ │
|
||
│ ┌──────────▼──────────▼───────┐ │
|
||
│ │ ProtocolAdapter 层 │ │
|
||
│ │ ┌────────┐ ┌───────────┐ │ │
|
||
│ │ │OpenAI │ │Anthropic │ │ │
|
||
│ │ │Adapter │ │Adapter │ │ │
|
||
│ │ └────────┘ └───────────┘ │ │
|
||
│ └──────────────┬───────────────┘ │
|
||
│ ┌──────────────▼───────────────┐ │
|
||
│ │ Canonical Model │ │
|
||
│ └──────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 URL 路由规则
|
||
|
||
入站 URL 采用协议前缀：`/{protocol}/{native_path}`。前缀是协议识别的**唯一依据**。
|
||
|
||
```
|
||
入站 URL 剥离前缀后 出站（target=anthropic）
|
||
──────────────────────────────────────────────────────────────────────────────────
|
||
/openai/v1/chat/completions → /v1/chat/completions → /v1/messages
|
||
/anthropic/v1/messages → /v1/messages → /v1/chat/completions
|
||
/openai/v1/models → /v1/models → /v1/models
|
||
/anthropic/v1/models → /v1/models → /v1/models
|
||
/openai/v1/embeddings → /v1/embeddings → 不支持，透传或返回错误
|
||
/anthropic/v1/messages/count_tokens→ /v1/messages/count_tokens→ OpenAI 无此接口
|
||
```
|
||
|
||
协议前缀仅用于入站侧。出站到上游 API 时使用目标协议原生路径（无前缀）。
|
||
|
||
### 2.3 请求处理流程
|
||
|
||
每个 HTTP 请求的转换流程：
|
||
|
||
```
|
||
客户端入站 SDK 内部处理 上游出站
|
||
┌──────────────────┐ ┌──────────────────┐
|
||
│ URL: │ 1. 前缀提取: /anthropic/ → source=anthropic │ URL: │
|
||
│ /anthropic/ │ 2. 前缀剥离: /v1/messages │ /v1/chat/ │
|
||
│ v1/messages │ 3. 接口识别: CHAT │ completions │
|
||
│ Headers: │ 4. 同协议? ──yes──▶ 剥离前缀后直接转发 │ Headers: │
|
||
│ x-api-key │ └──no──▶ 继续转换 │ Authorization │
|
||
│ Body: │ 5. URL 映射: /v1/messages → /v1/chat/completions │ Body: │
|
||
│ {model,system, │ 6. Header 转换: x-api-key → Authorization: Bearer │ {model,messages,│
|
||
│ messages,...} │ 7. Body 转换: Anthropic → Canonical → OpenAI │ tools,...} │
|
||
└──────────────────┘ └──────────────────┘
|
||
```
|
||
|
||
响应方向同理（含流式）。
|
||
|
||
**同协议透传**：source == target 时，仅剥离前缀后原样转发到上游。
|
||
**未知接口透传**：无法识别的路径，URL+Header 适配后 Body 原样转发。
|
||
|
||
---
|
||
|
||
## 3. 接口体系分层
|
||
|
||
### 3.1 分层策略
|
||
|
||
| 层级 | 接口 | 转换方式 |
|
||
|------|------|---------|
|
||
| **核心层** | Chat Completions, Messages | Canonical Model 深度转换 |
|
||
| **扩展层** | /models, /embeddings, /files, /rerank, /count_tokens | 轻量级字段映射 |
|
||
| **透传层** | /batches, /fine-tuning, /audio/*, /images/*, /video/*, /moderations 等未知路径 | URL+Header 适配后 Body 原样转发 |
|
||
|
||
**接口纳入原则**：只有 ≥2 个协议提供相同功能的接口才纳入转换层（核心层或扩展层），其余走透传。
|
||
|
||
**尽力转换策略**：
|
||
- 双方都支持且可映射 → 完整转换（如 /models）
|
||
- 目标协议不支持该接口 → 透传到上游或返回空响应/错误（可配置）
|
||
- 未知接口 → 始终透传
|
||
|
||
### 3.2 OpenAI 接口体系
|
||
|
||
```
|
||
OpenAI API
|
||
├── /v1/chat/completions [核心层]
|
||
├── /v1/models [扩展层]
|
||
├── /v1/models/{model} [扩展层]
|
||
├── /v1/embeddings [扩展层]
|
||
├── /v1/files [扩展层]
|
||
├── /v1/files/{id}/content [扩展层]
|
||
├── /v1/rerank [扩展层]
|
||
├── /v1/batches [透传层]
|
||
├── /v1/fine_tuning/jobs [透传层]
|
||
├── /v1/audio/* [透传层]
|
||
├── /v1/images/* [透传层]
|
||
├── /v1/moderations [透传层]
|
||
├── /v1/realtime [透传层]
|
||
└── /v1/* [透传层]
|
||
```
|
||
|
||
### 3.3 Anthropic 接口体系
|
||
|
||
```
|
||
Anthropic API
|
||
├── /v1/messages [核心层]
|
||
├── /v1/messages/count_tokens [扩展层]
|
||
├── /v1/models [扩展层]
|
||
├── /v1/batches [扩展层]
|
||
└── /v1/* [透传层]
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Canonical Model（规范模型）
|
||
|
||
协议无关的统一内部表示，Hub-and-Spoke 架构的枢纽。**核心层**使用完整 Canonical Model 深度转换；**扩展层**使用轻量 Canonical Models 做字段映射；**透传层**不使用。
|
||
|
||
设计原则：超集设计、类型化 discriminated union、前向兼容。Canonical Model 面向当前已适配协议（OpenAI、Anthropic）的公共语义进行抽象，字段随协议扩展演进（详见附录 D：字段晋升规范）。
|
||
|
||
### 4.1 CanonicalRequest
|
||
|
||
```
|
||
CanonicalRequest {
|
||
model: String
|
||
system: Union<None, String, Array<SystemBlock>>
|
||
|
||
SystemBlock {
|
||
text: String
|
||
}
|
||
|
||
messages: Array<CanonicalMessage>
|
||
tools: Option<Array<CanonicalTool>>
|
||
tool_choice: Option<ToolChoice>
|
||
parameters: RequestParameters
|
||
thinking: Option<ThinkingConfig>
|
||
stream: Boolean
|
||
user_id: Option<String>
|
||
output_format: Option<OutputFormat>
|
||
parallel_tool_use: Option<Boolean> // true = 允许并行, false = 禁止并行
|
||
}
|
||
```
|
||
|
||
### 4.2 RequestParameters
|
||
|
||
```
|
||
RequestParameters {
|
||
max_tokens: Option<Integer>
|
||
temperature: Option<Float>
|
||
top_p: Option<Float>
|
||
stop_sequences: Option<Array<String>>
|
||
}
|
||
```
|
||
|
||
### 4.3 CanonicalMessage / ContentBlock
|
||
|
||
```
|
||
CanonicalMessage {
|
||
role: Enum<system, user, assistant, tool>
|
||
content: Array<ContentBlock>
|
||
}
|
||
|
||
ContentBlock = Union<
|
||
TextBlock, { type: "text", text: String }
|
||
ToolUseBlock, { type: "tool_use", id: String, name: String, input: Object }
|
||
ToolResultBlock, { type: "tool_result", tool_use_id: String,
|
||
content: Union<String, Array<ContentBlock>>,
|
||
is_error: Option<Boolean> }
|
||
ThinkingBlock, { type: "thinking", thinking: String }
|
||
ImageBlock, { type: "image", source: ... } // 多模态预留
|
||
AudioBlock, { type: "audio", source: ... } // 多模态预留
|
||
VideoBlock, { type: "video", source: ... } // 多模态预留
|
||
FileBlock { type: "file", source: ... } // 多模态预留
|
||
>
|
||
```
|
||
|
||
### 4.4 CanonicalTool / ToolChoice
|
||
|
||
```
|
||
CanonicalTool {
|
||
name: String
|
||
description: Option<String>
|
||
input_schema: Object
|
||
}
|
||
|
||
ToolChoice = Union<
|
||
{type: "auto"},
|
||
{type: "none"},
|
||
{type: "any"},
|
||
{type: "tool", name: String}
|
||
>
|
||
```
|
||
|
||
### 4.5 ThinkingConfig
|
||
|
||
```
|
||
ThinkingConfig {
|
||
type: Enum<enabled, disabled> // Anthropic 启用时 budget_tokens 必填
|
||
budget_tokens: Option<Integer> // Anthropic: thinking tokens 不计入 max_tokens
|
||
effort: Option<Enum<low, medium, high, xhigh>> // OpenAI
|
||
}
|
||
```
|
||
|
||
### 4.6 OutputFormat
|
||
|
||
```
|
||
OutputFormat = Union<
|
||
{ type: "json_object" },
|
||
{ type: "json_schema", json_schema: { name: String, schema: Object, strict: Option<Boolean> } },
|
||
{ type: "text" }
|
||
>
|
||
```
|
||
|
||
### 4.7 CanonicalResponse
|
||
|
||
```
|
||
CanonicalResponse {
|
||
id: String
|
||
model: String
|
||
content: Array<ContentBlock>
|
||
stop_reason: Option<StopReason> // end_turn | max_tokens | tool_use | stop_sequence | content_filter
|
||
usage: CanonicalUsage
|
||
}
|
||
|
||
CanonicalUsage {
|
||
input_tokens: Integer
|
||
output_tokens: Integer
|
||
cache_read_tokens: Option<Integer>
|
||
cache_creation_tokens: Option<Integer>
|
||
reasoning_tokens: Option<Integer>
|
||
}
|
||
```
|
||
|
||
### 4.7 CanonicalStreamEvent
|
||
|
||
采用 Anthropic 风格的类型化事件模型（比 OpenAI delta 模型语义更明确，双向转换更容易）：
|
||
|
||
```
|
||
CanonicalStreamEvent = Union<
|
||
MessageStartEvent, { type: "message_start", message: {id, model, usage} }
|
||
ContentBlockStartEvent, { type: "content_block_start", index, content_block }
|
||
ContentBlockDeltaEvent, { type: "content_block_delta", index, delta }
|
||
ContentBlockStopEvent, { type: "content_block_stop", index }
|
||
MessageDeltaEvent, { type: "message_delta", delta: {stop_reason}, usage }
|
||
MessageStopEvent, { type: "message_stop" }
|
||
ErrorEvent, { type: "error", error: {type, message} }
|
||
PingEvent { type: "ping" }
|
||
>
|
||
|
||
content_block: Union<
|
||
{type: "text", text: ""},
|
||
{type: "tool_use", id, name, input: {}},
|
||
{type: "thinking", thinking: ""},
|
||
{type: "image"} | {type: "audio"} | {type: "video"} // 预留
|
||
>
|
||
|
||
delta: Union<
|
||
{type: "text_delta", text},
|
||
{type: "input_json_delta", partial_json},
|
||
{type: "thinking_delta", thinking},
|
||
{type: "image_delta", data} | {type: "audio_delta", data} // 预留
|
||
>
|
||
```
|
||
|
||
### 4.8 扩展层 Canonical Models
|
||
|
||
```
|
||
// /models
|
||
CanonicalModelList { models: Array<CanonicalModel> }
|
||
CanonicalModel { id, name, created, owned_by }
|
||
|
||
// /embeddings
|
||
CanonicalEmbeddingRequest { model, input, encoding_format?, dimensions? }
|
||
CanonicalEmbeddingResponse { data: [{index, embedding}], model, usage }
|
||
|
||
// /count_tokens
|
||
CanonicalTokenCountRequest { model, messages, system?, tools? }
|
||
CanonicalTokenCountResponse { input_tokens }
|
||
|
||
// /files
|
||
CanonicalFileObject { id, object, filename?, bytes?, created_at?, purpose?, status? }
|
||
|
||
// /rerank
|
||
CanonicalRerankRequest { model, query, documents, top_n?, return_documents? }
|
||
CanonicalRerankResponse { results: [{index, relevance_score, document?}], model }
|
||
```
|
||
|
||
### 4.9 设计说明
|
||
|
||
**`system` 为什么独立于 `messages`？**
|
||
Anthropic 用顶层 `system` 字段，OpenAI 用 `messages[role="system"]`。独立 `system` 语义更清晰，Decoder 提取、Encoder 注入。
|
||
|
||
**流式事件为什么用 Anthropic 风格？**
|
||
类型化事件有显式的 start/stop 生命周期，语义明确；OpenAI delta 模型需要状态机推断语义，双向转换更复杂。
|
||
|
||
**`user_id` 为什么从 `metadata` 中提升？**
|
||
OpenAI 用顶层 `user`，Anthropic 用 `metadata.user_id`。两者语义相同，提升为独立字段更清晰。
|
||
|
||
**`output_format` 为什么替代 `response_format`？**
|
||
OpenAI 的 `response_format` 和 Anthropic 新模型的 `output_format` 表达相同意图（控制输出格式），统一为 `output_format` 避免命名偏向。
|
||
|
||
**`parallel_tool_use` 为什么独立为顶层字段？**
|
||
OpenAI 用 `parallel_tool_calls`（允许），Anthropic 用 `disable_parallel_tool_use`（禁止），语义反转但表达相同控制。统一为正向语义。
|
||
|
||
---
|
||
|
||
## 5. Protocol Adapter 接口
|
||
|
||
### 5.1 TargetProvider
|
||
|
||
每次转换调用传入的目标上游信息。Adapter 通过 Provider 获取认证和配置，**不需要理解其他协议的 Header 格式**。
|
||
|
||
```
|
||
TargetProvider {
|
||
base_url: String // 上游 API 地址
|
||
api_key: String // 上游认证密钥
|
||
model_name: String // 目标模型名（调用方完成映射后传入）
|
||
adapter_config: Map<String, Any> // 协议专属配置（如 anthropic-version）
|
||
}
|
||
```
|
||
|
||
`adapter_config` 由各 Adapter 自行定义所需的 key，引擎不感知含义，原样透传。示例：
|
||
- Anthropic: `{ "anthropic_version": "2023-06-01", "anthropic_beta": ["..."] }`
|
||
- OpenAI: `{ "organization": "org-xxx" }` 或空
|
||
|
||
### 5.2 ProtocolAdapter
|
||
|
||
每种协议的完整适配器，融入所有接口类型的处理能力。所有 Adapter 通过代码注册，不支持动态增减。
|
||
|
||
```
|
||
interface ProtocolAdapter {
|
||
protocolName(): String
|
||
protocolVersion(): String
|
||
supportsPassthrough(): Boolean // 同协议透传开关，默认 true
|
||
|
||
// HTTP 级别
|
||
mapUrl(nativePath: String, interfaceType: InterfaceType): Option<String>
|
||
buildHeaders(provider: TargetProvider): Map<String, String>
|
||
supportsInterface(interfaceType: InterfaceType): Boolean
|
||
|
||
// 核心层：Chat
|
||
decodeRequest(raw): CanonicalRequest
|
||
encodeRequest(canonical, provider): RawRequest
|
||
decodeResponse(raw): CanonicalResponse
|
||
encodeResponse(canonical): RawResponse
|
||
|
||
// 核心层：流式
|
||
createStreamDecoder(): StreamDecoder
|
||
createStreamEncoder(): StreamEncoder
|
||
|
||
// 错误编码
|
||
encodeError(error: ConversionError): RawResponse
|
||
|
||
// 扩展层
|
||
decodeModelsResponse(raw): CanonicalModelList
|
||
encodeModelsResponse(canonical): RawResponse
|
||
decodeEmbeddingRequest(raw): CanonicalEmbeddingRequest
|
||
encodeEmbeddingRequest(canonical, provider): RawRequest
|
||
decodeEmbeddingResponse(raw): CanonicalEmbeddingResponse
|
||
encodeEmbeddingResponse(canonical): RawResponse
|
||
decodeTokenCountRequest(raw): CanonicalTokenCountRequest
|
||
encodeTokenCountRequest(canonical, provider): RawRequest
|
||
decodeTokenCountResponse(raw): CanonicalTokenCountResponse
|
||
encodeTokenCountResponse(canonical): RawResponse
|
||
encodeFileListResponse(canonical): RawResponse
|
||
decodeRerankRequest(raw): CanonicalRerankRequest
|
||
encodeRerankRequest(canonical, provider): RawRequest
|
||
decodeRerankResponse(raw): CanonicalRerankResponse
|
||
encodeRerankResponse(canonical): RawResponse
|
||
}
|
||
```
|
||
|
||
**`buildHeaders` vs 原 `mapHeaders`**：Adapter 只需从 `provider` 中提取自己协议需要的认证和配置信息，构建自己的 Header 格式。不再需要理解其他协议的 Header。
|
||
|
||
### 5.3 InterfaceType
|
||
|
||
```
|
||
InterfaceType = Enum<
|
||
CHAT, MODELS, MODEL_INFO, EMBEDDINGS, FILES, RERANK,
|
||
COUNT_TOKENS, BATCHES, FINE_TUNING,
|
||
AUDIO, IMAGES, REALTIME, UNKNOWN
|
||
>
|
||
```
|
||
|
||
注：`MODERATIONS` 移除，仅 OpenAI 单协议支持，走透传层。
|
||
|
||
### 5.4 StreamDecoder / StreamEncoder
|
||
|
||
```
|
||
interface StreamDecoder {
|
||
processChunk(rawChunk): Array<CanonicalStreamEvent>
|
||
flush(): Array<CanonicalStreamEvent>
|
||
}
|
||
|
||
interface StreamEncoder {
|
||
encodeEvent(event): Array<RawSSEChunk>
|
||
flush(): Array<RawSSEChunk>
|
||
}
|
||
```
|
||
|
||
### 5.5 AdapterRegistry
|
||
|
||
```
|
||
interface AdapterRegistry {
|
||
register(adapter: ProtocolAdapter): void
|
||
get(protocolName: String): ProtocolAdapter
|
||
listProtocols(): Array<String>
|
||
}
|
||
```
|
||
|
||
协议识别规则：URL 第一个路径段即协议标识。
|
||
|
||
```
|
||
/openai/v1/... → "openai"
|
||
/anthropic/v1/... → "anthropic"
|
||
/gemini/v1beta/... → "gemini" (未来)
|
||
未知前缀 → null, 上层框架自行处理
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Conversion Engine（转换引擎）
|
||
|
||
### 6.1 ConversionEngine
|
||
|
||
```
|
||
class ConversionEngine {
|
||
registry: AdapterRegistry
|
||
middlewareChain: MiddlewareChain
|
||
|
||
registerAdapter(adapter): void
|
||
use(middleware): void
|
||
|
||
isPassthrough(source, target): Boolean {
|
||
return source == target && registry.get(source).supportsPassthrough()
|
||
}
|
||
|
||
// 非流式请求转换
|
||
convertHttpRequest(request, sourceProtocol, targetProtocol, provider): HttpRequest {
|
||
nativePath = stripProtocolPrefix(request.url)
|
||
interfaceType = detectInterfaceType(nativePath)
|
||
|
||
if isPassthrough(sourceProtocol, targetProtocol):
|
||
targetAdapter = registry.get(targetProtocol)
|
||
return {url: provider.base_url + nativePath, method: request.method,
|
||
headers: targetAdapter.buildHeaders(provider), body: request.body}
|
||
|
||
sourceAdapter = registry.get(sourceProtocol)
|
||
targetAdapter = registry.get(targetProtocol)
|
||
|
||
targetUrl = targetAdapter.mapUrl(nativePath, interfaceType) ?? nativePath
|
||
targetHeaders = targetAdapter.buildHeaders(provider)
|
||
targetBody = convertBody(interfaceType, sourceAdapter, targetAdapter, provider, request.body)
|
||
|
||
return {url: provider.base_url + targetUrl, method: request.method,
|
||
headers: targetHeaders, body: targetBody}
|
||
}
|
||
|
||
// 非流式响应转换
|
||
convertHttpResponse(response, sourceProtocol, targetProtocol, interfaceType): HttpResponse {
|
||
if isPassthrough(sourceProtocol, targetProtocol): return response
|
||
|
||
sourceAdapter = registry.get(sourceProtocol)
|
||
targetAdapter = registry.get(targetProtocol)
|
||
targetBody = convertResponseBody(interfaceType, sourceAdapter, targetAdapter, response.body)
|
||
|
||
return {status: response.status, headers: response.headers, body: targetBody}
|
||
}
|
||
|
||
// 流式转换
|
||
createStreamConverter(sourceProtocol, targetProtocol, provider): StreamConverter {
|
||
if isPassthrough(sourceProtocol, targetProtocol):
|
||
targetAdapter = registry.get(targetProtocol)
|
||
return new PassthroughStreamConverter(targetAdapter.buildHeaders(provider))
|
||
|
||
source = registry.get(sourceProtocol)
|
||
target = registry.get(targetProtocol)
|
||
return new CanonicalStreamConverter(
|
||
source.createStreamDecoder(), target.createStreamEncoder(), middlewareChain)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 Body 转换分发
|
||
|
||
```
|
||
function convertBody(interfaceType, sourceAdapter, targetAdapter, provider, body):
|
||
switch interfaceType:
|
||
case CHAT:
|
||
canonical = sourceAdapter.decodeRequest(body)
|
||
canonical = middlewareChain.apply(canonical)
|
||
return targetAdapter.encodeRequest(canonical, provider)
|
||
case MODELS:
|
||
return body // GET 请求，无 body
|
||
case EMBEDDINGS:
|
||
if !sourceAdapter.supportsInterface(EMBEDDINGS)
|
||
|| !targetAdapter.supportsInterface(EMBEDDINGS):
|
||
return body // 尽力转换：不支持则透传
|
||
return targetAdapter.encodeEmbeddingRequest(
|
||
sourceAdapter.decodeEmbeddingRequest(body), provider)
|
||
case RERANK:
|
||
// 同 EMBEDDINGS 模式
|
||
case COUNT_TOKENS:
|
||
// 同 EMBEDDINGS 模式
|
||
default:
|
||
return body // 透传层：原样转发
|
||
|
||
function convertResponseBody(interfaceType, sourceAdapter, targetAdapter, body):
|
||
// 结构与 convertBody 对称，CHAT 走 Canonical 深度转换，扩展层走轻量映射，默认透传
|
||
```
|
||
|
||
### 6.3 StreamConverter
|
||
|
||
```
|
||
interface StreamConverter {
|
||
processChunk(rawChunk): Array<RawSSEChunk>
|
||
flush(): Array<RawSSEChunk>
|
||
}
|
||
|
||
class PassthroughStreamConverter implements StreamConverter {
|
||
headers: Map<String, String>
|
||
constructor(headers) { this.headers = headers }
|
||
processChunk(rawChunk): Array<RawSSEChunk> { return [rawChunk] }
|
||
flush(): Array<RawSSEChunk> { return [] }
|
||
}
|
||
|
||
class CanonicalStreamConverter implements StreamConverter {
|
||
decoder: StreamDecoder
|
||
encoder: StreamEncoder
|
||
middleware: MiddlewareChain
|
||
|
||
processChunk(rawChunk):
|
||
events = decoder.processChunk(rawChunk).map(e => middleware.applyStreamEvent(e))
|
||
return events.flatMap(e => encoder.encodeEvent(e))
|
||
|
||
flush():
|
||
return decoder.flush().flatMap(e => encoder.encodeEvent(e)) + encoder.flush()
|
||
}
|
||
```
|
||
|
||
### 6.4 Middleware
|
||
|
||
引擎内部的拦截钩子，在 decode → encode 之间对 Canonical 进行变换。
|
||
|
||
```
|
||
interface ConversionMiddleware {
|
||
intercept(canonical, sourceProtocol, targetProtocol, context): canonical | error
|
||
interceptStreamEvent?(event, sourceProtocol, targetProtocol, context): event | error
|
||
}
|
||
|
||
ConversionContext { conversionId, interfaceType, timestamp, metadata }
|
||
```
|
||
|
||
- `intercept` 返回修改后的 canonical，或返回 ConversionError 以**中断转换**
|
||
- `interceptStreamEvent` 同理，返回错误可中断流式转换
|
||
- 多个 Middleware 按注册顺序链式执行，任一中断则后续不再执行
|
||
|
||
### 6.5 使用示例
|
||
|
||
```
|
||
engine = new ConversionEngine()
|
||
engine.registerAdapter(new OpenAIAdapter())
|
||
engine.registerAdapter(new AnthropicAdapter())
|
||
|
||
// 场景1: OpenAI→Anthropic Chat
|
||
// 入站: /openai/v1/chat/completions
|
||
provider = TargetProvider {
|
||
base_url: "https://api.anthropic.com",
|
||
api_key: "sk-ant-xxx",
|
||
model_name: "claude-sonnet-4-20250514",
|
||
adapter_config: { "anthropic_version": "2023-06-01" }
|
||
}
|
||
out = engine.convertHttpRequest(inRequest, "openai", "anthropic", provider)
|
||
// 出站 /v1/messages, headers: x-api-key + anthropic-version
|
||
|
||
// 场景2: /models 跨协议
|
||
// 入站: /anthropic/v1/models
|
||
provider = TargetProvider {
|
||
base_url: "https://api.openai.com",
|
||
api_key: "sk-xxx", model_name: "", adapter_config: {}
|
||
}
|
||
out = engine.convertHttpRequest(inRequest, "anthropic", "openai", provider)
|
||
// source=anthropic, 出站 /v1/models + Authorization: Bearer
|
||
|
||
// 场景3: 同协议透传
|
||
// 入站: /openai/v1/chat/completions
|
||
provider = TargetProvider {
|
||
base_url: "https://api.openai.com",
|
||
api_key: "sk-xxx", model_name: "", adapter_config: {}
|
||
}
|
||
out = engine.convertHttpRequest(inRequest, "openai", "openai", provider)
|
||
// source=openai == target=openai → 剥离前缀, 用 provider 重建 headers 后原样转发
|
||
|
||
// 场景4: 流式转换
|
||
converter = engine.createStreamConverter("anthropic", "openai", provider)
|
||
for chunk in upstreamSSE {
|
||
for out in converter.processChunk(chunk) { sendToClient(out) }
|
||
}
|
||
converter.flush()
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 流式转换架构
|
||
|
||
### 7.1 转换管道
|
||
|
||
```
|
||
上游 SSE 流
|
||
│
|
||
├── 同协议: PassthroughStreamConverter（用 provider 重建 Headers 后逐块转发）
|
||
│
|
||
└── 跨协议: CanonicalStreamConverter
|
||
StreamDecoder StreamEncoder
|
||
┌───────────┐ ┌───────────┐
|
||
│ SSE Parser│ │SSE Writer │
|
||
└─────┬─────┘ └─────▲─────┘
|
||
│ │
|
||
┌─────▼─────┐ CanonicalEvent[] ┌─────┴─────┐
|
||
│ Event │──────────────────────▶│ Event │
|
||
│ Translator │ ┌──────────┐ │ Translator │
|
||
│ (状态机) │ │Middleware│ │ │
|
||
└───────────┘ └──────────┘ └───────────┘
|
||
```
|
||
|
||
### 7.2 StreamDecoder 状态
|
||
|
||
```
|
||
StreamDecoderState {
|
||
messageStarted: Boolean
|
||
openBlocks: Set<Integer>
|
||
currentBlockType: Map<Integer, String>
|
||
currentBlockId: Map<Integer, String>
|
||
toolCallIdMap: Map<Integer, String> // OpenAI 特有
|
||
toolCallNameMap: Map<Integer, String> // OpenAI 特有
|
||
toolCallArguments: Map<Integer, StringBuffer> // OpenAI 特有
|
||
utf8Remainder: Option<ByteArray> // UTF-8 跨 chunk 安全
|
||
accumulatedUsage: Option<CanonicalUsage>
|
||
}
|
||
```
|
||
|
||
### 7.3 事件映射
|
||
|
||
**Anthropic SSE ↔ Canonical**：几乎 1:1 映射，事件类型完全对应。
|
||
|
||
**OpenAI SSE → Canonical**（需要状态机）：
|
||
|
||
| OpenAI chunk | Canonical 事件 |
|
||
|---|---|
|
||
| 首个 chunk (id/model) | MessageStartEvent |
|
||
| delta.content 首次 | ContentBlockStart(text) + ContentBlockDelta(text_delta) |
|
||
| delta.content 后续 | ContentBlockDelta(text_delta) |
|
||
| delta.tool_calls[i] 首次 | ContentBlockStart(tool_use) |
|
||
| delta.tool_calls[i].arguments | ContentBlockDelta(input_json_delta) |
|
||
| delta.reasoning_content | ContentBlockStart(thinking) + ContentBlockDelta(thinking_delta) |
|
||
| finish_reason | ContentBlockStop × N + MessageDeltaEvent + MessageStopEvent |
|
||
| [DONE] | flush() |
|
||
|
||
**Canonical → OpenAI SSE**（Encoder 端）：
|
||
|
||
| Canonical 事件 | OpenAI chunk |
|
||
|---|---|
|
||
| MessageStartEvent | 首个 chunk (id, model, delta:{}) |
|
||
| ContentBlockStart(text) | 缓冲，不输出 |
|
||
| ContentBlockDelta(text) | {choices:[{delta:{content:"..."}}]}（首次合并 block_start） |
|
||
| ContentBlockStart(tool) | 缓冲 |
|
||
| ContentBlockDelta(input_json) | {choices:[{delta:{tool_calls:[...]}}]}（首次含 id/name） |
|
||
| ContentBlockStop | 不输出 |
|
||
| MessageDeltaEvent | {choices:[{finish_reason:"..."}]} |
|
||
| MessageStopEvent | [DONE] |
|
||
| PingEvent | 丢弃 |
|
||
|
||
---
|
||
|
||
## 8. OpenAI 协议适配器
|
||
|
||
### 8.1 URL 路径映射
|
||
|
||
```
|
||
OpenAI.mapUrl(nativePath, interfaceType):
|
||
switch interfaceType:
|
||
case CHAT: return "/v1/chat/completions"
|
||
case MODELS: return "/v1/models"
|
||
case MODEL_INFO: return "/v1/models/{modelId}"
|
||
case EMBEDDINGS: return "/v1/embeddings"
|
||
case FILES: return nativePath
|
||
case RERANK: return "/v1/rerank"
|
||
default: return nativePath
|
||
```
|
||
|
||
### 8.2 请求头构建
|
||
|
||
```
|
||
OpenAI.buildHeaders(provider):
|
||
result = {}
|
||
result["Authorization"] = "Bearer " + provider.api_key
|
||
if provider.adapter_config["organization"]:
|
||
result["OpenAI-Organization"] = provider.adapter_config["organization"]
|
||
result["Content-Type"] = "application/json"
|
||
return result
|
||
```
|
||
|
||
### 8.3 接口能力声明
|
||
|
||
```
|
||
OpenAI.supportsInterface(type):
|
||
CHAT...IMAGES: return true // 全部支持
|
||
COUNT_TOKENS: return false // OpenAI 无此接口
|
||
default: return false
|
||
```
|
||
|
||
### 8.4 Chat 请求 Decoder/Encoder
|
||
|
||
#### Decoder: decodeRequest → CanonicalRequest
|
||
|
||
```
|
||
decodeSystemPrompt(messages):
|
||
systemMsgs = messages.filter(m => m.role == "system")
|
||
remaining = messages.filter(m => m.role != "system")
|
||
if systemMsgs.length == 0: return {system: None, messages: remaining}
|
||
return {system: systemMsgs.map(m => extractText(m.content)).join("\n\n"), messages: remaining}
|
||
```
|
||
|
||
```
|
||
decodeMessage(msg):
|
||
switch msg.role:
|
||
case "user":
|
||
return {role: "user", content: decodeUserContent(msg.content)}
|
||
case "assistant":
|
||
blocks = []
|
||
if msg.content: blocks.append({type: "text", text: extractText(msg.content)})
|
||
if msg.refusal: blocks.append({type: "text", text: msg.refusal})
|
||
if msg.tool_calls:
|
||
for tc in msg.tool_calls:
|
||
blocks.append({type: "tool_use", id: tc.id, name: tc.function.name,
|
||
input: JSON.parse(tc.function.arguments)})
|
||
return {role: "assistant", content: blocks}
|
||
case "tool":
|
||
return {role: "tool", content: [{
|
||
type: "tool_result", tool_use_id: msg.tool_call_id,
|
||
content: msg.content, is_error: false}]}
|
||
```
|
||
|
||
#### Encoder: encodeRequest ← CanonicalRequest
|
||
|
||
```
|
||
encodeRequest(canonical, provider):
|
||
result = {
|
||
model: provider.model_name,
|
||
messages: encodeSystemPrompt(canonical) + canonical.messages.flatMap(encodeMessage),
|
||
max_tokens: canonical.parameters.max_tokens,
|
||
temperature: canonical.parameters.temperature,
|
||
top_p: canonical.parameters.top_p,
|
||
stream: canonical.stream
|
||
}
|
||
if canonical.parameters.stop_sequences:
|
||
result.stop = canonical.parameters.stop_sequences
|
||
if canonical.user_id:
|
||
result.user = canonical.user_id
|
||
if canonical.output_format:
|
||
result.response_format = encodeOutputFormat(canonical.output_format)
|
||
if canonical.parallel_tool_use != null:
|
||
result.parallel_tool_calls = canonical.parallel_tool_use
|
||
if canonical.tools:
|
||
result.tools = canonical.tools.map(t => ({
|
||
type: "function", function: {name: t.name, description: t.description, parameters: t.input_schema}}))
|
||
if canonical.tool_choice:
|
||
result.tool_choice = encodeToolChoice(canonical.tool_choice)
|
||
if canonical.thinking && canonical.thinking.type == "enabled":
|
||
result.reasoning_effort = canonical.thinking.effort ?? "medium"
|
||
return result
|
||
|
||
encodeOutputFormat(format):
|
||
switch format.type:
|
||
"json_object" → {type: "json_object"}
|
||
"json_schema" → {type: "json_schema", json_schema: format.json_schema}
|
||
"text" → null
|
||
|
||
encodeToolChoice(choice):
|
||
switch choice.type:
|
||
"auto" → "auto"
|
||
"none" → "none"
|
||
"any" → "required"
|
||
"tool" → {type: "function", function: {name: choice.name}}
|
||
|
||
```
|
||
|
||
### 8.5 Chat 响应 Decoder/Encoder
|
||
|
||
```
|
||
// Decoder
|
||
mapStopReason(reason):
|
||
"stop" → "end_turn" | "length" → "max_tokens" | "tool_calls" → "tool_use" | "content_filter" → "content_filter" | _ → "end_turn"
|
||
|
||
decodeResponse(openaiResp):
|
||
choice = openaiResp.choices[0]
|
||
blocks = []
|
||
if choice.message.content: blocks.append({type: "text", text: choice.message.content})
|
||
if choice.message.refusal: blocks.append({type: "text", text: choice.message.refusal})
|
||
if choice.message.reasoning_content:
|
||
blocks.append({type: "thinking", thinking: choice.message.reasoning_content})
|
||
if choice.message.tool_calls:
|
||
for tc: blocks.append({type: "tool_use", id: tc.id, name: tc.function.name,
|
||
input: JSON.parse(tc.function.arguments)})
|
||
return CanonicalResponse {id, model, content: blocks, stop_reason: mapStopReason(choice.finish_reason), usage: decodeUsage(openaiResp.usage)}
|
||
|
||
// Encoder
|
||
mapCanonicalToFinishReason(reason):
|
||
"end_turn" → "stop" | "max_tokens" → "length" | "tool_use" → "tool_calls" | "content_filter" → "content_filter" | _ → "stop"
|
||
|
||
encodeResponse(canonical):
|
||
textParts = canonical.content.filter(b => b.type == "text")
|
||
toolUses = canonical.content.filter(b => b.type == "tool_use")
|
||
message = {}
|
||
if textParts.length > 0: message.content = textParts.map(b => b.text).join("")
|
||
elif toolUses.length > 0: message.content = null
|
||
else: message.content = ""
|
||
if toolUses.length > 0:
|
||
message.tool_calls = toolUses.map(tu => ({
|
||
id: tu.id, type: "function",
|
||
function: {name: tu.name, arguments: JSON.stringify(tu.input)}}))
|
||
return {id: canonical.id, object: "chat.completion", model: canonical.model,
|
||
choices: [{index: 0, message, finish_reason: mapCanonicalToFinishReason(canonical.stop_reason)}],
|
||
usage: encodeUsage(canonical.usage)}
|
||
```
|
||
|
||
### 8.6 /models 响应编解码
|
||
|
||
```
|
||
// Decoder: OpenAI → Canonical
|
||
decodeModelsResponse(openaiResp):
|
||
return CanonicalModelList {
|
||
models: openaiResp.data.map(m => CanonicalModel {
|
||
id: m.id, name: m.id, created: m.created, owned_by: m.owned_by })}
|
||
|
||
// Encoder: Canonical → OpenAI
|
||
encodeModelsResponse(canonical):
|
||
return {object: "list",
|
||
data: canonical.models.map(m => ({id: m.id, object: "model",
|
||
created: m.created ?? 0, owned_by: m.owned_by ?? "unknown"}))}
|
||
```
|
||
|
||
**跨协议示例（入站 `/openai/v1/models`，目标 Anthropic）**：
|
||
|
||
```
|
||
入站: GET /openai/v1/models, Authorization: Bearer sk-xxx
|
||
→ source=openai, target=anthropic
|
||
→ URL: /v1/models, Headers: x-api-key: sk-xxx, anthropic-version: ...
|
||
|
||
Anthropic 上游响应: {data: [{id: "claude-sonnet-4", display_name: "Claude Sonnet 4", ...}], has_more: false}
|
||
→ Anthropic.decodeModelsResponse → CanonicalModelList
|
||
→ OpenAI.encodeModelsResponse
|
||
|
||
返回客户端: {object: "list", data: [{id: "claude-sonnet-4", object: "model", created: 0, owned_by: "anthropic"}]}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Anthropic 协议适配器
|
||
|
||
### 9.1 URL 路径映射
|
||
|
||
```
|
||
Anthropic.mapUrl(nativePath, interfaceType):
|
||
switch interfaceType:
|
||
case CHAT: return "/v1/messages"
|
||
case MODELS: return "/v1/models"
|
||
case MODEL_INFO: return "/v1/models/{modelId}"
|
||
case COUNT_TOKENS: return "/v1/messages/count_tokens"
|
||
case EMBEDDINGS: return null // 不支持
|
||
case RERANK: return null
|
||
case FILES: return null
|
||
default: return nativePath
|
||
```
|
||
|
||
### 9.2 请求头构建
|
||
|
||
```
|
||
Anthropic.buildHeaders(provider):
|
||
result = {}
|
||
result["x-api-key"] = provider.api_key
|
||
result["anthropic-version"] = provider.adapter_config["anthropic_version"] ?? "2023-06-01"
|
||
if provider.adapter_config["anthropic_beta"]:
|
||
result["anthropic-beta"] = provider.adapter_config["anthropic_beta"].join(",")
|
||
result["Content-Type"] = "application/json"
|
||
return result
|
||
```
|
||
|
||
### 9.3 接口能力声明
|
||
|
||
```
|
||
Anthropic.supportsInterface(type):
|
||
CHAT: return true
|
||
MODELS: return true
|
||
COUNT_TOKENS: return true
|
||
BATCHES: return true
|
||
default: return false
|
||
```
|
||
|
||
### 9.4 Chat 请求 Decoder/Encoder
|
||
|
||
#### Decoder
|
||
|
||
```
|
||
decodeSystem(system):
|
||
if system is None: return None
|
||
if system is String: return system
|
||
return system.map(s => SystemBlock {text: s.text})
|
||
|
||
decodeMessage(msg):
|
||
switch msg.role:
|
||
case "user":
|
||
blocks = decodeContentBlocks(msg.content)
|
||
toolResults = blocks.filter(b => b.type == "tool_result")
|
||
others = blocks.filter(b => b.type != "tool_result")
|
||
if toolResults.length > 0:
|
||
return [
|
||
...(others.length > 0 ? [{role: "user", content: others}] : []),
|
||
{role: "tool", content: toolResults}]
|
||
return [{role: "user", content: blocks}]
|
||
case "assistant":
|
||
return [{role: "assistant", content: decodeContentBlocks(msg.content)}]
|
||
|
||
decodeContentBlocks(content):
|
||
if content is String: return [{type: "text", text: content}]
|
||
return content.map(block => {
|
||
switch block.type:
|
||
"text" → TextBlock{text: block.text}
|
||
"tool_use" → ToolUseBlock{id: block.id, name: block.name, input: block.input}
|
||
"tool_result" → ToolResultBlock{tool_use_id: block.tool_use_id, ...}
|
||
"thinking" → ThinkingBlock{thinking: block.thinking}
|
||
"redacted_thinking" → 丢弃 }) // 仅 Anthropic 使用，不在中间层保留
|
||
|
||
// 额外字段提取
|
||
decodeExtras(raw):
|
||
user_id = raw.metadata?.user_id
|
||
output_format = null // Anthropic 旧模型无 output_format，新模型通过 output_config 提取
|
||
parallel_tool_use = raw.disable_parallel_tool_use == true ? false : null
|
||
thinking = raw.thinking ? ThinkingConfig {
|
||
type: raw.thinking.type, // "enabled" | "disabled"
|
||
budget_tokens: raw.thinking.budget_tokens,
|
||
effort: null } : null
|
||
```
|
||
|
||
#### Encoder
|
||
|
||
```
|
||
encodeRequest(canonical, provider):
|
||
result = {
|
||
model: provider.model_name,
|
||
messages: encodeMessages(canonical),
|
||
max_tokens: canonical.parameters.max_tokens,
|
||
temperature: canonical.parameters.temperature,
|
||
top_p: canonical.parameters.top_p,
|
||
stream: canonical.stream
|
||
}
|
||
if canonical.system:
|
||
result.system = encodeSystem(canonical.system)
|
||
if canonical.parameters.stop_sequences:
|
||
result.stop_sequences = canonical.parameters.stop_sequences
|
||
if canonical.user_id:
|
||
result.metadata = {user_id: canonical.user_id}
|
||
if canonical.output_format:
|
||
result.output_format = encodeOutputFormat(canonical.output_format)
|
||
if canonical.parallel_tool_use == false:
|
||
result.disable_parallel_tool_use = true
|
||
if canonical.tools:
|
||
result.tools = canonical.tools.map(t => ({
|
||
name: t.name, description: t.description, input_schema: t.input_schema}))
|
||
if canonical.tool_choice:
|
||
result.tool_choice = encodeToolChoice(canonical.tool_choice)
|
||
if canonical.thinking:
|
||
result.thinking = {type: canonical.thinking.type}
|
||
if canonical.thinking.budget_tokens:
|
||
result.thinking.budget_tokens = canonical.thinking.budget_tokens
|
||
return result
|
||
|
||
encodeSystem(system):
|
||
if system is String: return system
|
||
return system.map(s => ({text: s.text}))
|
||
|
||
encodeToolChoice(choice):
|
||
switch choice.type:
|
||
"auto" → {type: "auto"}
|
||
"none" → {type: "none"}
|
||
"any" → {type: "any"}
|
||
"tool" → {type: "tool", name: choice.name}
|
||
```
|
||
|
||
### 9.5 Chat 响应 Decoder/Encoder
|
||
|
||
```
|
||
// Decoder
|
||
decodeResponse(anthropicResp):
|
||
blocks = []
|
||
for block in anthropicResp.content:
|
||
switch block.type:
|
||
"text" → blocks.append({type: "text", text: block.text})
|
||
"tool_use" → blocks.append({type: "tool_use", id: block.id, name: block.name, input: block.input})
|
||
"thinking" → blocks.append({type: "thinking", thinking: block.thinking})
|
||
"redacted_thinking" → 丢弃 // 仅 Anthropic 使用，不在中间层保留
|
||
return CanonicalResponse {id, model, content: blocks, stop_reason: anthropicResp.stop_reason,
|
||
usage: CanonicalUsage {input_tokens, output_tokens,
|
||
cache_read_tokens: anthropicResp.usage.cache_read_input_tokens,
|
||
cache_creation_tokens: anthropicResp.usage.cache_creation_input_tokens}}
|
||
|
||
// Encoder
|
||
encodeResponse(canonical):
|
||
blocks = canonical.content.map(block => {
|
||
switch block.type:
|
||
"text" → {type: "text", text: block.text}
|
||
"tool_use" → {type: "tool_use", id: block.id, name: block.name, input: block.input}
|
||
"thinking" → {type: "thinking", thinking: block.thinking}})
|
||
return {id: canonical.id, type: "message", role: "assistant", model: canonical.model,
|
||
content: blocks,
|
||
stop_reason: canonical.stop_reason == "content_filter" ? "end_turn" : canonical.stop_reason,
|
||
stop_sequence: None,
|
||
usage: {input_tokens: canonical.usage.input_tokens, output_tokens: canonical.usage.output_tokens,
|
||
cache_read_input_tokens: canonical.usage.cache_read_tokens,
|
||
cache_creation_input_tokens: canonical.usage.cache_creation_tokens}}
|
||
|
||
// 错误编码
|
||
encodeError(error):
|
||
return {type: "error", error: {type: error.code, message: error.message}}
|
||
```
|
||
|
||
### 9.6 /models 响应编解码
|
||
|
||
```
|
||
// Decoder: Anthropic → Canonical
|
||
decodeModelsResponse(anthropicResp):
|
||
return CanonicalModelList {
|
||
models: anthropicResp.data.map(m => CanonicalModel {
|
||
id: m.id, name: m.display_name ?? m.id, created: m.created_at,
|
||
owned_by: "anthropic"})}
|
||
|
||
// Encoder: Canonical → Anthropic
|
||
encodeModelsResponse(canonical):
|
||
return {data: canonical.models.map(m => ({
|
||
id: m.id,
|
||
display_name: m.name ?? m.id,
|
||
created_at: m.created ?? 0, type: "model"})),
|
||
has_more: false,
|
||
first_id: canonical.models[0]?.id, last_id: canonical.models.last?.id}
|
||
```
|
||
|
||
### 9.7 /count_tokens 编解码
|
||
|
||
```
|
||
// Decoder
|
||
decodeTokenCountRequest(raw):
|
||
return CanonicalTokenCountRequest {
|
||
model: raw.model, messages: decodeMessages(raw.messages),
|
||
system: decodeSystem(raw.system), tools: decodeTools(raw.tools)}
|
||
|
||
// Encoder
|
||
encodeTokenCountRequest(canonical):
|
||
return {model: canonical.model, messages: encodeMessages(canonical),
|
||
system: encodeSystem(canonical), tools: encodeTools(canonical.tools)}
|
||
|
||
decodeTokenCountResponse(raw):
|
||
return CanonicalTokenCountResponse {input_tokens: raw.input_tokens}
|
||
|
||
encodeTokenCountResponse(canonical):
|
||
return {input_tokens: canonical.input_tokens}
|
||
```
|
||
|
||
**跨协议对接策略（入站 `/anthropic/v1/messages/count_tokens`，目标 OpenAI）**：
|
||
|
||
OpenAI 不提供 `/count_tokens` 接口。Anthropic Claude Code 启动时会调用此接口。
|
||
|
||
| 策略 | 实现 |
|
||
|------|------|
|
||
| **透传** | URL+Header 适配后发送到 OpenAI，由上游返回 404 |
|
||
| **模拟（推荐）** | 解码请求，用估算器返回近似 token 数 |
|
||
| **精确估算** | 解码 messages，调用 OpenAI Chat Completions (max_tokens=1)，从 usage.prompt_tokens 获取 |
|
||
|
||
策略选择通过配置或 Middleware 决定。
|
||
|
||
---
|
||
|
||
## 10. 字段映射参考
|
||
|
||
### 10.1 Chat 请求字段映射
|
||
|
||
| Canonical | OpenAI | Anthropic | 说明 |
|
||
|---|---|---|---|
|
||
| `system` | `messages[0].role="system"` | `system` (顶层) | 位置差异 |
|
||
| `user_id` | `user` (顶层) | `metadata.user_id` | 嵌套差异 |
|
||
| `output_format` | `response_format` | `output_format` (新模型) | 字段名差异；旧 Anthropic 模型需降级 |
|
||
| `parallel_tool_use` | `parallel_tool_calls` (bool) | `disable_parallel_tool_use` (bool, 反转) | 语义反转 |
|
||
| `ToolUseBlock` | `tool_calls[{id,function}]` | `content[{type:"tool_use"}]` | OpenAI 在 message 顶层 |
|
||
| `ToolResultBlock` | `{role:"tool",tool_call_id}` | `content[{type:"tool_result"}]` in user | 结构性差异 |
|
||
| `tools[].input_schema` | `tools[].function.parameters` | `tools[].input_schema` | 字段名不同 |
|
||
| `tool_choice: "any"` | `"required"` | `{type:"any"}` | 语义映射 |
|
||
| `max_tokens` | `max_tokens` / `max_completion_tokens` | `max_tokens` | o-series 差异 |
|
||
| `stop_sequences` | `stop` (String or Array) | `stop_sequences` (Array) | OpenAI Decoder 规范化为 Array |
|
||
| `thinking.type` | — | `thinking.type` | Anthropic 特有 |
|
||
| `thinking.effort` | `reasoning_effort` | — | OpenAI 参数级 |
|
||
| `thinking.budget_tokens` | — | `thinking.budget_tokens` | Anthropic token 级 |
|
||
|
||
### 10.2 Chat 响应字段映射
|
||
|
||
| Canonical | OpenAI | Anthropic |
|
||
|---|---|---|
|
||
| `stop_reason: "end_turn"` | `finish_reason: "stop"` | `stop_reason: "end_turn"` |
|
||
| `stop_reason: "max_tokens"` | `finish_reason: "length"` | `stop_reason: "max_tokens"` |
|
||
| `stop_reason: "tool_use"` | `finish_reason: "tool_calls"` | `stop_reason: "tool_use"` |
|
||
| `ThinkingBlock` | `reasoning_content` (非流式) | `content[{type:"thinking"}]` |
|
||
| `usage.input_tokens` | `usage.prompt_tokens` | `usage.input_tokens` |
|
||
| `usage.output_tokens` | `usage.completion_tokens` | `usage.output_tokens` |
|
||
| `usage.cache_read_tokens` | `usage.prompt_tokens_details.cached_tokens` | `usage.cache_read_input_tokens` |
|
||
|
||
### 10.3 HTTP 头映射
|
||
|
||
Headers 由各 Adapter 的 `buildHeaders(provider)` 方法构建，从 `provider.api_key` 和 `provider.adapter_config` 获取信息，无需理解其他协议。
|
||
|
||
| 场景 | OpenAI | Anthropic |
|
||
|------|--------|-----------|
|
||
| 认证 | `Authorization: Bearer <key>` | `x-api-key: <key>` |
|
||
| 版本 | — | `anthropic-version`（从 adapter_config 读取） |
|
||
| Beta | — | `anthropic-beta`（从 adapter_config 读取） |
|
||
|
||
### 10.4 扩展层接口映射
|
||
|
||
#### /models
|
||
|
||
| 维度 | OpenAI | Anthropic |
|
||
|------|--------|-----------|
|
||
| 响应格式 | `{object:"list", data:[{id, object:"model", created, owned_by}]}` | `{data:[{id, display_name, created_at, type}], has_more, first_id, last_id}` |
|
||
| 映射 | `id↔id`, `created↔created_at`, `owned_by→"anthropic"`, `display_name→id` |
|
||
|
||
#### /count_tokens
|
||
|
||
| 维度 | OpenAI | Anthropic |
|
||
|------|--------|-----------|
|
||
| 存在性 | 不存在 | `POST /v1/messages/count_tokens` |
|
||
| 策略 | Anthropic→OpenAI: 模拟/估算 | 原生支持 |
|
||
|
||
#### /embeddings
|
||
|
||
| 维度 | OpenAI | Anthropic |
|
||
|------|--------|-----------|
|
||
| 存在性 | `POST /v1/embeddings` | 不存在 |
|
||
| 策略 | 原生支持 | OpenAI→Anthropic: 返回不支持错误 |
|
||
|
||
---
|
||
|
||
## 11. 扩展点设计
|
||
|
||
### 11.1 新协议接入
|
||
|
||
1. 实现 ProtocolAdapter（URL 映射 + Header 映射 + 各接口编解码）
|
||
2. 注册到 AdapterRegistry
|
||
3. 完成
|
||
|
||
### 11.2 多模态扩展
|
||
|
||
Canonical Model 已预留 ImageBlock / AudioBlock / VideoBlock / FileBlock。实现路径：
|
||
1. 在各 ProtocolAdapter 中实现多模态块的编解码
|
||
2. 在 StreamDecoder/StreamEncoder 中处理多模态增量数据
|
||
|
||
### 11.3 有状态特性扩展
|
||
|
||
```
|
||
interface StatefulMiddleware extends ConversionMiddleware {
|
||
stateStore: SessionStateStore
|
||
}
|
||
```
|
||
|
||
适用场景：Gemini thoughtSignature 跨轮次保留。
|
||
|
||
### 11.4 特性降级策略
|
||
|
||
| 源特性 | 目标协议 | 降级方式 |
|
||
|--------|---------|---------|
|
||
| `output_format` | Anthropic（旧模型） | 注入合成工具实现 JSON 模式 |
|
||
| `thinking.effort` | Anthropic | 转为 `thinking.budget_tokens` |
|
||
| `thinking.budget_tokens` | OpenAI | 转为 `reasoning_effort` |
|
||
| `count_tokens` | OpenAI | 模拟/估算 |
|
||
| `/embeddings` | Anthropic | 返回不支持的错误 |
|
||
|
||
### 11.5 自定义接口支持
|
||
|
||
```
|
||
interface CustomInterfaceHandler {
|
||
interfaceType(): InterfaceType
|
||
matchUrl(url): Boolean
|
||
convertRequest(source, target, raw): raw
|
||
convertResponse(source, target, raw): raw
|
||
}
|
||
engine.registerCustomHandler(handler)
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 错误处理
|
||
|
||
### 12.1 错误分类
|
||
|
||
```
|
||
ConversionError { code: ErrorCode, message, sourceProtocol?, targetProtocol?,
|
||
interfaceType?, details?, cause? }
|
||
|
||
ErrorCode = Enum<
|
||
INVALID_INPUT, // 请求格式不符合协议规范
|
||
MISSING_REQUIRED_FIELD, // 缺少必填字段
|
||
INCOMPATIBLE_FEATURE, // 特性在目标协议不可用
|
||
FIELD_MAPPING_FAILURE, // 字段映射逻辑错误
|
||
TOOL_CALL_PARSE_ERROR, // 工具调用参数解析失败
|
||
JSON_PARSE_ERROR, // JSON 解析失败
|
||
STREAM_STATE_ERROR, // 流式状态机异常
|
||
UTF8_DECODE_ERROR, // UTF-8 解码错误
|
||
PROTOCOL_CONSTRAINT_VIOLATION, // 违反协议约束
|
||
ENCODING_FAILURE, // 编码失败
|
||
INTERFACE_NOT_SUPPORTED // 目标协议不支持此接口
|
||
>
|
||
```
|
||
|
||
### 12.2 错误处理策略
|
||
|
||
```
|
||
ErrorHandler { mode: "strict" | "lenient" }
|
||
|
||
strict: 任何错误抛出异常
|
||
lenient: 尽力继续
|
||
INCOMPATIBLE_FEATURE → 降级继续
|
||
INTERFACE_NOT_SUPPORTED → 透传或返回空响应
|
||
TOOL_CALL_PARSE_ERROR → 保留原始内容继续
|
||
PROTOCOL_CONSTRAINT_VIOLATION → 自动修复
|
||
```
|
||
|
||
**不支持接口的处理**（`INTERFACE_NOT_SUPPORTED`）：
|
||
|
||
| 策略 | 适用场景 | 实现 |
|
||
|------|---------|------|
|
||
| 透传 | 上游可能有自己的实现 | URL+Header 适配后 Body 原样转发 |
|
||
| 返回空响应 | 不影响核心功能 | 返回空列表 `{data: []}` |
|
||
| 返回错误 | 客户端明确需要此功能 | 返回 501 或协议格式错误 |
|
||
|
||
具体策略通过配置或 Middleware 决定。
|
||
|
||
### 12.3 错误响应格式
|
||
|
||
转换失败时，错误响应用**客户端协议（source protocol）**的格式编码。由 `sourceAdapter.encodeError(error)` 完成：
|
||
|
||
- OpenAI 格式：`{error: {message, type, code, param}}`
|
||
- Anthropic 格式：`{type: "error", error: {type, message}}`
|
||
|
||
Middleware 中断转换时同理，引擎调用 sourceAdapter.encodeError 将 ConversionError 编码为客户端可理解的格式。
|
||
|
||
---
|
||
|
||
## 13. 参考实现对比
|
||
|
||
### 13.1 关键差异
|
||
|
||
| 维度 | CC-Switch | LiteLLM | new-api | one-api | 本设计 |
|
||
|------|-----------|---------|---------|---------|--------|
|
||
| 定位 | 桌面代理 | 完整网关+SDK | 完整网关 | 完整网关 | HTTP 层 SDK |
|
||
| 架构 | 直接转换 | 策略+工厂 | Hub-and-Spoke (OpenAI) | Hub-and-Spoke (OpenAI) | Hub-and-Spoke (自定义) |
|
||
| 转换方向 | 双向(有限) | 单向→厂商 | 单向→OpenAI | 单向→OpenAI | 双向(任意协议对) |
|
||
| Canonical 模型 | 无 | 无 | OpenAI 格式 | OpenAI 格式 | 自定义超集，字段随协议扩展演进 |
|
||
| 厂商覆盖 | 2 | 100+ | 50+ | 56 渠道/19 API 类型 | 协议级(当前 2, 可扩展) |
|
||
| 管理接口 | /health, /status | 全接口 | 全接口 | 全接口 | /models, /embeddings, /count_tokens, /files, /rerank + 透传层 |
|
||
| 同协议透传 | Anthropic 直通 | 无 | 开关控制 | OpenAI 兼容渠道零拷贝 | 自动检测 |
|
||
| 协议前缀 | /claude/, /codex/, /gemini/ | 无 | 无 | 无 | /openai/, /anthropic/ |
|
||
| 流式处理 | 简单转发 | 简单解析 | Scanner+SSE | Scanner+SSE | StreamDecoder/Encoder 状态机 |
|
||
| 错误处理 | 基础 | 基础 | 统一格式归一化 | 多格式归一化 | strict/lenient 模式 + ErrorCode 枚举 |
|
||
| 扩展机制 | 硬编码 | 策略模式 | 实现 Adaptor 接口 | 实现 Adaptor 接口 | ProtocolAdapter + Middleware + 自定义接口 |
|
||
|
||
### 13.2 设计取舍
|
||
|
||
| 取舍 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| HTTP 层 SDK vs 纯 chat 库 | HTTP 层 SDK | 编程工具需要管理接口 |
|
||
| 自定义 Canonical vs OpenAI | 自定义 | 避免厂商锁定 |
|
||
| 接口分层 vs 全部深度转换 | 分层 | 核心深度转换，扩展轻量映射，透传零转换 |
|
||
| 尽力转换 vs 严格转换 | 尽力转换 | 最大化覆盖面 |
|
||
| 透传 vs 总是 Canonical | 自动透传 + 可选禁用 | 同协议和未知接口的性能优化 |
|
||
|
||
### 13.3 关键经验
|
||
|
||
- **CC-Switch**: UTF-8 跨 chunk 截断处理必要；工具调用参数可能乱序到达；同协议直通是最高频路径
|
||
- **LiteLLM**: BaseConfig 抽象 + 编排器不变模式扩展性好；全接口覆盖对用户体验至关重要
|
||
- **new-api**: 多格式输入的 Hub-and-Spoke 已生产验证；/models 的协议感知转换价值最高
|
||
- **one-api**: 以 OpenAI 格式为 Canonical 的 Hub-and-Spoke 架构在 19 种 API 类型、56 个渠道的生产环境验证了可行性；大量厂商(DepSeek/Groq/Mistral/Moonshot 等)采用 OpenAI 兼容格式使得同协议透传成为最高频路径；适配器模式的 ChannelType→APIType→Adaptor 三层映射提供了厂商级精细控制但增加了维护复杂度
|
||
|
||
---
|
||
|
||
## 附录 A：完整转换流程示例
|
||
|
||
```
|
||
客户端发送:
|
||
POST /openai/v1/chat/completions HTTP/1.1 ← /openai/ 前缀标识源协议
|
||
Authorization: Bearer sk-xxx
|
||
Content-Type: application/json
|
||
|
||
{ "model": "gpt-4",
|
||
"messages": [
|
||
{"role": "system", "content": "You are a coding assistant"},
|
||
{"role": "user", "content": "Read the file main.py"},
|
||
{"role": "assistant", "content": null, "tool_calls": [{
|
||
"id": "call_abc123", "type": "function",
|
||
"function": {"name": "read_file", "arguments": "{\"path\": \"main.py\"}"}}]},
|
||
{"role": "tool", "tool_call_id": "call_abc123", "content": "print('hello')"},
|
||
{"role": "user", "content": "What does this code do?"}],
|
||
"tools": [{"type": "function", "function": {"name": "read_file", "parameters": {...}}}],
|
||
"max_tokens": 1024, "stream": true }
|
||
|
||
│
|
||
▼
|
||
|
||
engine.convertHttpRequest(request, "openai", "anthropic", provider)
|
||
|
||
provider = TargetProvider {
|
||
base_url: "https://api.anthropic.com",
|
||
api_key: "sk-ant-xxx",
|
||
model_name: "claude-sonnet-4-20250514",
|
||
adapter_config: { "anthropic_version": "2023-06-01" }
|
||
}
|
||
|
||
Step 0: 前缀 /openai/ → source=openai, 剥离后 /v1/chat/completions
|
||
Step 1: 接口识别 → CHAT
|
||
Step 2: URL 映射 → /v1/messages
|
||
Step 3: Header 构建 → x-api-key: sk-ant-xxx, anthropic-version: 2023-06-01
|
||
Step 4: Body 转换:
|
||
|
||
OpenAI.decodeRequest → CanonicalRequest {
|
||
model: "gpt-4",
|
||
system: "You are a coding assistant",
|
||
messages: [
|
||
{user, [{text, "Read the file main.py"}]},
|
||
{assistant, [{tool_use, id:"call_abc123", name:"read_file", input:{path:"main.py"}}]},
|
||
{tool, [{tool_result, tool_use_id:"call_abc123", content:"print('hello')"}]},
|
||
{user, [{text, "What does this code do?"}]}],
|
||
parameters: {max_tokens: 1024},
|
||
stream: true }
|
||
|
||
Anthropic.encodeRequest(canonical, provider) → {
|
||
"model": "claude-sonnet-4-20250514", ← 使用 provider.model_name
|
||
"system": "You are a coding assistant",
|
||
"messages": [
|
||
{"role": "user", "content": [{"type": "text", "text": "Read the file main.py"}]},
|
||
{"role": "assistant", "content": [{"type": "tool_use", "id": "call_abc123", ...}]},
|
||
{"role": "user", "content": [{"type": "tool_result", "tool_use_id": "call_abc123", ...}]},
|
||
{"role": "user", "content": [{"type": "text", "text": "What does this code do?"}]}],
|
||
"max_tokens": 1024, "stream": true }
|
||
|
||
发往 Anthropic 上游:
|
||
POST https://api.anthropic.com/v1/messages HTTP/1.1 ← provider.base_url + 目标路径
|
||
x-api-key: sk-ant-xxx
|
||
anthropic-version: 2023-06-01
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 B：模块依赖
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────┐
|
||
│ ConversionEngine │
|
||
│ 门面：HTTP 转换 / 协议路由 / 透传判断 / 流式转换 │
|
||
│ ┌────────────────────────────────────────────┐ │
|
||
│ │ Protocol Prefix Router │ │
|
||
│ │ URL 前缀 → source protocol │ │
|
||
│ └────────────────────────────────────────────┘ │
|
||
├──────────────────────────────────────────────────┤
|
||
│ TargetProvider │
|
||
│ base_url / api_key / model_name / adapter_config │
|
||
├──────────────────┬───────────────────────────────┤
|
||
│ AdapterRegistry │ MiddlewareChain │
|
||
├──────────────────┴───────────────────────────────┤
|
||
│ StreamConverter: Passthrough | Canonical │
|
||
├──────────────────────────────────────────────────┤
|
||
│ ProtocolAdapter: OpenAI | Anthropic | Future... │
|
||
│ · buildHeaders(provider) · URL 映射 │
|
||
│ · Chat/Models/Embeddings/Rerank/... 编解码 │
|
||
│ · encodeError · StreamDecoder / StreamEncoder │
|
||
├──────────────────────────────────────────────────┤
|
||
│ Canonical Model (Core + Extended) │
|
||
├──────────────────────────────────────────────────┤
|
||
│ Error Handling │
|
||
├──────────────────────────────────────────────────┤
|
||
│ Utility: UTF-8 Buffer / SSE Parser / Detector │
|
||
└──────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 C：接口速查
|
||
|
||
```
|
||
// ─── 核心入口 ───
|
||
ConversionEngine
|
||
.registerAdapter(adapter)
|
||
.use(middleware)
|
||
.isPassthrough(source, target): Boolean
|
||
.convertHttpRequest(request, sourceProtocol, targetProtocol, provider): HttpRequest
|
||
.convertHttpResponse(response, sourceProtocol, targetProtocol, interfaceType): HttpResponse
|
||
.createStreamConverter(sourceProtocol, targetProtocol, provider): StreamConverter
|
||
|
||
// ─── 目标上游信息 ───
|
||
TargetProvider
|
||
.base_url: String
|
||
.api_key: String
|
||
.model_name: String
|
||
.adapter_config: Map<String, Any>
|
||
|
||
// ─── URL 路由 ───
|
||
// 入站: /{protocol}/{native_path}
|
||
// /openai/v1/chat/completions → source=openai
|
||
// /anthropic/v1/messages → source=anthropic
|
||
// 出站: provider.base_url + 目标协议原生路径（无前缀）
|
||
|
||
// ─── 协议适配器 ───
|
||
ProtocolAdapter
|
||
.protocolName() / .protocolVersion() / .supportsPassthrough()
|
||
.mapUrl(nativePath, type) / .buildHeaders(provider) / .supportsInterface(type)
|
||
.decodeRequest(raw) / .encodeRequest(canonical, provider)
|
||
.decodeResponse(raw) / .encodeResponse(canonical)
|
||
.createStreamDecoder() / .createStreamEncoder()
|
||
.encodeError(error): RawResponse
|
||
.decodeModelsResponse / .encodeModelsResponse
|
||
.decodeEmbeddingRequest / .encodeEmbeddingRequest(canonical, provider) / ...Response
|
||
.decodeTokenCountRequest / .encodeTokenCountRequest(canonical, provider) / ...Response
|
||
.decodeRerankRequest / .encodeRerankRequest(canonical, provider) / ...Response
|
||
|
||
// ─── 流式处理 ───
|
||
StreamConverter: .processChunk(raw) / .flush()
|
||
├─ PassthroughStreamConverter [raw] → [raw]（用 provider 重建 Headers）
|
||
└─ CanonicalStreamConverter decode → middleware → encode
|
||
|
||
// ─── 接口类型 ───
|
||
InterfaceType = CHAT | MODELS | MODEL_INFO | EMBEDDINGS | FILES |
|
||
RERANK | COUNT_TOKENS | BATCHES |
|
||
FINE_TUNING | AUDIO | IMAGES | REALTIME | UNKNOWN
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 D：字段晋升规范
|
||
|
||
### 原则
|
||
|
||
Canonical Model 是**活的公共契约**，不是固定不变的。其字段集反映的是**当前已适配协议的公共语义**，随协议扩展而演进。
|
||
|
||
### 字段分类
|
||
|
||
| 分类 | 判定条件 | 处理方式 |
|
||
|------|---------|---------|
|
||
| **公共字段** | ≥2 个协议表达相同含义 | 升级为 Canonical Model 的正式字段 |
|
||
| **协议特有字段** | 仅 1 个协议使用 | 不在中间层传播；同协议透传时自然保留；跨协议时丢弃 |
|
||
| **未知字段** | 新协议带来的新概念 | 先按特有字段处理；当第二个协议也出现时晋升 |
|
||
|
||
### 晋升流程
|
||
|
||
```
|
||
1. 发现：适配新协议时，识别出无法映射到现有 Canonical 字段的语义
|
||
2. 判定：该语义是否已被 ≥1 个现有协议所表达？
|
||
- 是 → 晋升为 Canonical 公共字段
|
||
- 否 → 暂不纳入，记录在适配清单中
|
||
3. 设计：确定字段名（协议中立）、类型、在 Canonical 中的位置
|
||
4. 更新：修改 Canonical Model 定义，所有现有 Adapter 的 Decoder/Encoder 同步更新
|
||
5. 文档：更新 §10 字段映射参考表
|
||
```
|
||
|
||
### 晋升示例
|
||
|
||
| 字段 | 原始位置 | 晋升原因 |
|
||
|------|---------|---------|
|
||
| `user_id` | OpenAI `user` / Anthropic `metadata.user_id` | 两协议均支持用户标识 |
|
||
| `output_format` | OpenAI `response_format` / Anthropic `output_format` | 两协议均支持控制输出格式 |
|
||
| `parallel_tool_use` | OpenAI `parallel_tool_calls` / Anthropic `disable_parallel_tool_use` | 两协议均支持并行工具调用控制 |
|
||
| `cache_control` | 仅 Anthropic | 不晋升，仅 Anthropic 使用 |
|
||
| `reasoning_content` | 仅 OpenAI | 不晋升（但 ThinkingBlock 已覆盖 thinking 语义） |
|
||
|
||
### 降级规则
|
||
|
||
当公共字段的目标协议不支持时：
|
||
- 有语义等价物 → 自动映射（如 `parallel_tool_use` → `disable_parallel_tool_use`）
|
||
- 无等价物 → 丢弃，日志 warn（如 `output_format` → Anthropic 旧模型丢弃）
|
||
- 有替代方案 → 降级策略处理（如 `output_format` → 注入合成工具）
|
||
|
||
---
|
||
|
||
## 附录 E：协议适配清单模板
|
||
|
||
适配新协议时，按以下清单逐项确认。所有项目确认后即可与引擎对接。
|
||
|
||
### E.1 协议基本信息
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 协议名称 | 用于 URL 前缀和 Adapter 注册的唯一标识（如 `"openai"`, `"anthropic"`） |
|
||
| 协议版本 | 当前适配的 API 版本（如 `"2023-06-01"`） |
|
||
| Base URL | API 服务地址 |
|
||
| 认证方式 | Header 名称和格式（如 `Authorization: Bearer` / `x-api-key`） |
|
||
|
||
### E.2 接口识别
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| URL 路径模式 | 列出所有接口的 URL 路径和对应的 InterfaceType |
|
||
| 接口能力矩阵 | 每种 InterfaceType 的支持状态（`supportsInterface`） |
|
||
| URL 映射表 | 每种 InterfaceType 的目标 URL 路径（`mapUrl`） |
|
||
|
||
### E.3 请求头构建
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 认证头 | 如何从 `provider.api_key` 构建认证 Header |
|
||
| 必需 Header | 协议要求的固定 Header（如 Content-Type） |
|
||
| 可选 Header | 根据功能动态添加的 Header（如 anthropic-beta） |
|
||
| adapter_config 契约 | 定义本 Adapter 从 `provider.adapter_config` 读取的 key 列表和默认值 |
|
||
|
||
### E.4 核心层 — Chat 请求编解码
|
||
|
||
#### Decoder（协议 → Canonical）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 系统消息 | 如何提取为 `canonical.system`（顶层字段 / messages 中 / 不支持） |
|
||
| 消息角色 | 协议角色与 Canonical 角色（system/user/assistant/tool）的映射 |
|
||
| 内容块 | 每种内容类型（text/tool_use/tool_result/thinking）的解码规则 |
|
||
| 工具定义 | 如何映射为 `canonical.tools`（字段名差异：input_schema vs parameters） |
|
||
| 工具选择 | tool_choice 各变体的映射规则 |
|
||
| 参数映射 | max_tokens/temperature/top_p/stop_sequences 等参数的映射 |
|
||
| 新增公共字段 | user_id/output_format/parallel_tool_use/thinking 的提取规则 |
|
||
| 协议特有字段 | 仅本协议使用的字段列表，以及处理方式（忽略/记录） |
|
||
| 协议约束 | 消息顺序要求、角色交替要求、必填字段等 |
|
||
|
||
#### Encoder（Canonical → 协议）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 模型名称 | 使用 `provider.model_name` 覆盖 `canonical.model` |
|
||
| 系统消息注入 | 如何将 `canonical.system` 编码为协议格式 |
|
||
| 消息编码 | 各角色的编码规则（特别注意 role 映射、content 结构差异） |
|
||
| 角色约束处理 | 是否需要 enforceAlternation？具体策略？ |
|
||
| 工具编码 | tools/tool_choice 的编码规则 |
|
||
| 参数编码 | Canonical 参数到协议参数的映射 |
|
||
| 公共字段编码 | user_id/output_format/parallel_tool_use/thinking 的注入规则 |
|
||
| 降级处理 | 目标协议不支持的 Canonical 字段的降级策略 |
|
||
|
||
### E.5 核心层 — Chat 响应编解码
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 响应结构 | 协议响应的顶层结构解析 |
|
||
| 内容块解码 | 各 content block 类型的解码规则 |
|
||
| 停止原因 | stop_reason / finish_reason 的映射表 |
|
||
| Token 用量 | usage 各字段的映射（注意命名差异：input_tokens vs prompt_tokens） |
|
||
| 推理内容 | reasoning_content / thinking block 的处理 |
|
||
| 协议特有内容 | 仅本协议返回的特有字段的处理 |
|
||
|
||
### E.6 核心层 — 流式编解码
|
||
|
||
#### StreamDecoder（协议 SSE → Canonical 事件）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| SSE 格式 | 协议的 SSE 事件格式（named events vs delta chunks） |
|
||
| 事件映射表 | 每种协议 SSE 事件 → CanonicalStreamEvent 的映射规则 |
|
||
| 状态机设计 | 需要跟踪的状态（当前 block index、open blocks、tool call 映射等） |
|
||
| UTF-8 安全 | 是否需要处理跨 chunk 的 UTF-8 截断 |
|
||
| 特殊情况 | 工具调用参数乱序、无限空白检测、延迟字段等 |
|
||
|
||
#### StreamEncoder（Canonical 事件 → 协议 SSE）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 事件映射表 | 每个 CanonicalStreamEvent → 协议 SSE chunk 的映射规则 |
|
||
| 缓冲策略 | 哪些事件需要缓冲、何时输出 |
|
||
| SSE 格式 | event type / data 字段的编码方式 |
|
||
| 结束标记 | 如何输出流结束信号（如 `[DONE]`） |
|
||
|
||
### E.7 扩展层接口
|
||
|
||
对每种支持的扩展层接口（/models、/embeddings、/files、/rerank、/count_tokens），确认：
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 接口是否存在 | 该协议是否原生支持此接口 |
|
||
| URL 路径 | 接口的 URL 路径 |
|
||
| 请求格式 | 请求体的协议特有格式 → Canonical 格式的映射 |
|
||
| 响应格式 | 响应体的协议特有格式 ← Canonical 格式的映射 |
|
||
| 不支持时策略 | 透传 / 返回空响应 / 返回错误 |
|
||
|
||
### E.8 错误编码
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 错误响应格式 | 协议的错误响应 JSON 结构 |
|
||
| encodeError | ConversionError → 协议错误格式的编码规则 |
|
||
| HTTP 状态码 | 协议常用的错误状态码映射 |
|
||
|
||
### E.9 自检清单
|
||
|
||
- [ ] 所有 InterfaceType 的 `supportsInterface` 返回值已确定
|
||
- [ ] 所有 InterfaceType 的 `mapUrl` 映射已确定
|
||
- [ ] Chat 请求的 Decoder 和 Encoder 已实现
|
||
- [ ] Chat 响应的 Decoder 和 Encoder 已实现
|
||
- [ ] 流式 StreamDecoder 和 StreamEncoder 已实现
|
||
- [ ] `buildHeaders(provider)` 已实现
|
||
- [ ] `encodeError` 已实现
|
||
- [ ] 扩展层接口的编解码已实现（支持的接口）
|
||
- [ ] 角色映射和消息顺序约束已处理
|
||
- [ ] 工具调用（tool_calls / tool_use / tool_result）的编解码已处理
|
||
- [ ] stop_reason / finish_reason 映射表已确认
|
||
- [ ] usage 字段映射已确认
|
||
- [ ] 协议特有字段已识别并确定处理方式（忽略/降级）
|
||
- [ ] adapter_config 契约已文档化
|