> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/reference/protocol-matrix · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 协议互通矩阵

网关支持 12 种协议互译：客户端用的协议和上游用的协议可以不同，网关双向翻译请求与响应。

## 协议清单

| 协议 | 说明 |
|------|------|
| `openai` | OpenAI Chat Completions |
| `openai_response` | OpenAI Responses API |
| `openai_images` | OpenAI 图像 |
| `openai_embeddings` | OpenAI 向量 |
| `openai_audio` | OpenAI 语音（ASR/TTS） |
| `openai_rerank` | OpenAI 兼容重排序 |
| `anthropic` | Anthropic Messages |
| `google` | Gemini Generative Language |
| `aws_converse` | AWS Bedrock Converse |
| `aws_invoke` | AWS Bedrock InvokeModel |
| `dashscope` | 阿里 DashScope |
| `openai_realtime` | OpenAI Realtime（WebSocket 会话，见 [Realtime 实时会话](/zh-CN/reference/realtime.md)） |
| `dashscope_realtime` | DashScope Realtime（WebSocket 会话） |
| `passthrough` | 透传，不翻译 |

> `openai_realtime` / `dashscope_realtime` 是**会话作用域的 WebSocket 协议**，走独立的 `/v1/realtime` 桥接路径，不参与上面的 HTTP 互译矩阵（矩阵里的都是「一问一答」式 HTTP 协议）。

## 互通矩阵（双向）

下列每对都是双向翻译（一个适配器同时处理 请求→ 与 响应←）：

| 客户端协议 | 可互译的上游协议 |
|-----------|-----------------|
| `openai` | `anthropic`、`aws_invoke`、`google`、`aws_converse`、`openai_response`、`dashscope` |
| `anthropic` | `openai`(经 chat)、`aws_invoke`、`google`、`aws_converse`、`openai_response`、`dashscope` |
| `openai_response` | `openai`(经 chat)、`aws_converse`、`google`、`dashscope` |
| `google` | `openai`、`anthropic`、`openai_response`、`dashscope`、`openai_images` |
| `openai_embeddings` | `dashscope` |
| `openai_rerank` | `dashscope` |
| `openai_audio` | `dashscope` |
| `openai_images` | `google`（仅与 Google 互译） |
| `aws_converse` | `openai`、`anthropic`、`openai_response` |
| `aws_invoke` | `openai`、`anthropic` |
| `dashscope` | `openai`、`anthropic`、`openai_response`、`google`、`openai_embeddings`、`openai_rerank`、`openai_audio` |
| `passthrough` | 任意（不翻译，原样转发） |

> 客户端协议与上游协议相同的组合走 identity（请求体原样转发）；其中 `Anthropic→Anthropic` 是同协议非透传翻译器（会剥离网关编码的思考签名，用于跨实例往返保持兼容）。

## 透传入口

- `passthrough` 协议：直接转发，不做协议转换。
- `/v3/{model}/{*rest}`：identity 透传入口。当客户端协议 == 该模型配置的目标协议时，请求体原样转发到上游。
- DashScope 客户端两路：
  - `/v1/services/{*rest}`：透传，请求体原样发 DashScope。
  - `/v1/chat/completions`：翻译模式，OpenAI 格式翻译成 DashScope 格式。

## 已知翻译限制

跨协议翻译不是无损的，已知的边界：

- **图像**：`openai_images` 只与 `google` 互译（经 `generateContent` 的内联图像输出）；其他上游需原生兼容 OpenAI 图像接口。
- **向量**：`openai_embeddings` 是单向 API（无对话轮次），跨协议互译仅限 `dashscope`；多数向量供应商（OpenAI / Azure / Voyage 等）直接提供 OpenAI 兼容端点，按 `openai` 协议接入即可。
- **语音**：`openai_audio` 与 `dashscope` 多模态互译转写 / 翻译（multipart 音频 ↔ 多模态 JSON）；但文字转语音（TTS）在 DashScope 无对应能力，返回 `unsupported_feature`。
- **一般字段**：目标协议没有对应概念的请求字段，翻译时会被降级或丢弃。若某字段必须到达上游，先确认目标协议是否有对应字段，或改用透传（见上）。

## 无翻译器时

请求的「客户端协议 → 上游协议」组合没有翻译器 → 返回 **400**（`unsupported_feature`）。

## 怎么用这个矩阵

1. 确定你客户端用的协议（如 OpenAI SDK → `openai`）。
2. 确定上游协议（如 Claude → `anthropic`）。
3. 查上表 `openai` 行是否含 `anthropic`——含则支持互译，客户端不用改协议，网关自动翻译。
4. 不含则要么换客户端协议，要么把上游协议改成支持的。

## 常见问题

**Q：客户端报 400 unsupported_feature？**
该「客户端协议 → 上游协议」组合没有翻译器。查本矩阵，换客户端协议或上游协议。

**Q：`Anthropic → Anthropic` 是 identity 吗？**
是同协议非透传翻译器（会剥离网关编码的思考签名，用于跨实例往返保持兼容）。其他客户端协议 == 上游协议的组合走 identity（请求体原样转发）。

**Q：AWS Bedrock 客户端协议在矩阵里没看到？**
AWS Bedrock 是上游侧协议，不是客户端协议。客户端用 OpenAI / Anthropic / Gemini 等协议端点访问 Bedrock 模型，网关做协议互译。详见 [端点 · 认证 · 协议互通](/zh-CN/reference/endpoints.md#aws-bedrock-passthrough)。

**Q：怎么绕过翻译？**
用 `/v3/{model}/{*rest}` 透传入口，当客户端协议 == 目标协议时请求体原样转发。或上游协议选 `passthrough`。

**下一步**：[端点 · 认证 · 协议互通](/zh-CN/reference/endpoints.md) 看完整端点清单；[客户端接入与网关差异](/zh-CN/reference/clients-and-gateway-diffs.md) 看各 SDK 接法；[上游与模型字段](/zh-CN/reference/upstreams-models-fields.md) 看模型协议配置。