跨协议调用时的字段映射、端点策略与已知限制。日常使用建议走 OpenAI 兼容端点;需要厂商独有参数时再用原生端点。
协议转换参考
OmniGate 支持三种 LLM 协议的自动转换,使客户端能够使用统一的 OpenAI 格式访问任意后端模型。本文档详细说明转换机制、字段映射和已知限制。
转换架构
核心原则
OmniGate 采用 OpenAI 作为统一接口格式,通过协议适配器实现双向转换:
客户端 OpenAI 请求
↓
[入站转换] OpenAI → 目标协议 (openai/anthropic/responses)
↓
上游返回目标协议响应
↓
[出站转换] 目标协议 → OpenAI
↓
客户端收到 OpenAI 响应
端点策略
| 端点 | 输入格式 | 输出格式 | 协议过滤 | 转换模式 |
|---|---|---|---|---|
/v1/chat/completions | OpenAI | OpenAI | type=chat (不限 protocol) | 双向转换 |
/v1/messages | Anthropic | Anthropic | protocol=anthropic | 直通透传 |
/v1/responses | OpenAI Responses | OpenAI Responses | protocol=responses | 直通透传 |
/v1/gemini:generateContent / /v1/gemini:streamGenerateContent | Gemini generateContent | Gemini generateContent | protocol=gemini | 直通透传 |
/v1/embeddings | OpenAI | OpenAI | type=embedding | 直通(仅改 model) |
/v1/rerank | Cohere | Cohere | type=rerank | 直通(仅改 model) |
/v1/images/generations | OpenAI Images | OpenAI | type=image | 直通(仅改 model;stream 原样透传) |
/v1/audio/speech | OpenAI TTS | 音频/SSE | type=tts | 直通(仅改 model;二进制或 SSE 流式透传) |
/v1/audio/transcriptions | OpenAI STT multipart | JSON/文本 | type=stt | 直通(仅改 model;入站全缓冲) |
/v1/videos | OpenAI Videos(Sora 格式) | 任务对象 JSON | type=video | 直通(仅改 model;异步任务,见下) |
/v1/videos/{id} | — | 任务对象 JSON | 按 video_task 映射 | 回查透传(不产生新调用记录) |
/v1/videos/{id}/content | — | 视频字节流 | 按 video_task 映射 | 回查透传(流式) |
OpenAI ↔ Anthropic 转换
支持的功能
| 功能 | OpenAI → Anthropic | Anthropic → OpenAI | 备注 |
|---|---|---|---|
| 基础对话 | ✅ | ✅ | |
| 流式响应 | ✅ | ✅ | SSE 事件格式转换 |
| System 消息 | ✅ | ✅ | 提取到 system 字段 |
| 图像输入 | ✅ | ✅ | base64 编码转换 |
| 工具调用 | ✅ | ✅ | tool_calls ↔ tool_use |
| 工具结果 | ✅ | ✅ | role=tool → tool_result 块 |
| Usage 统计 | ✅ | ✅ | token 计数映射 |
请求字段映射 (OpenAI → Anthropic)
顶层字段
| OpenAI | Anthropic | 转换规则 |
|---|---|---|
model | model | 直接映射,替换为真实模型名 |
messages | messages + system | role=system 提取到顶层 system 字段 |
max_tokens | max_tokens | 直接映射,缺省时补 4096 |
temperature | temperature | 直接映射 |
top_p | top_p | 直接映射 |
stream | stream | 直接映射 |
tools | tools | 函数签名转换(见下) |
tool_choice | tool_choice | {type, function} → {type, name} |
top_k | top_k | 直接映射(OpenAI 原生不支持) |
消息转换
普通文本消息:
// OpenAI
{"role": "user", "content": "Hello"}
// Anthropic
{"role": "user", "content": [{"type": "text", "text": "Hello"}]}
System 消息:
// OpenAI (在 messages 数组中)
{"role": "system", "content": "You are a helpful assistant"}
// Anthropic (提取到顶层)
{
"system": "You are a helpful assistant",
"messages": [...]
}
图像消息:
// OpenAI
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
]
}
// Anthropic
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "..."
}
}
]
}
工具调用消息:
// OpenAI
{
"role": "assistant",
"content": "Let me check the weather",
"tool_calls": [{
"id": "call_abc",
"type": "function",
"function": {"name": "get_weather", "arguments": "{\"city\":\"SF\"}"}
}]
}
// Anthropic
{
"role": "assistant",
"content": [
{"type": "text", "text": "Let me check the weather"},
{
"type": "tool_use",
"id": "call_abc",
"name": "get_weather",
"input": {"city": "SF"}
}
]
}
工具结果消息:
// OpenAI
{
"role": "tool",
"tool_call_id": "call_abc",
"content": "Sunny, 72°F"
}
// Anthropic
{
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": "call_abc",
"content": "Sunny, 72°F"
}]
}
工具定义转换
// OpenAI
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
}
}
}
// Anthropic
{
"name": "get_weather",
"description": "Get weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
}
}
Tool Choice 转换
OpenAI tool_choice | Anthropic tool_choice |
|---|---|
"none" | (不发送 tools 字段) |
"auto" | {"type": "auto"} |
"required" / "any" | {"type": "any"} |
{"type": "function", "function": {"name": "X"}} | {"type": "tool", "name": "X"} |
响应字段映射 (Anthropic → OpenAI)
非流式响应
// Anthropic
{
"id": "msg_01ABC",
"type": "message",
"role": "assistant",
"content": [
{"type": "text", "text": "Hello!"}
],
"model": "claude-3-5-sonnet-20241022",
"stop_reason": "end_turn",
"usage": {
"input_tokens": 10,
"output_tokens": 5
}
}
// OpenAI
{
"id": "chatcmpl-01ABC",
"object": "chat.completion",
"model": "claude-3-5-sonnet-20241022",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello!"
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 5,
"total_tokens": 15
}
}
Finish Reason 映射
Anthropic stop_reason | OpenAI finish_reason |
|---|---|
end_turn | stop |
stop_sequence | stop |
max_tokens | length |
tool_use | tool_calls |
流式响应事件转换
消息开始:
// Anthropic
{"type": "message_start", "message": {...}}
// OpenAI (内部记录,不发送给客户端)
内容块开始:
// Anthropic
{"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
// OpenAI
{
"id": "chatcmpl-...",
"object": "chat.completion.chunk",
"choices": [{
"index": 0,
"delta": {"role": "assistant", "content": ""},
"finish_reason": null
}]
}
内容增量:
// Anthropic
{"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}
// OpenAI
{
"choices": [{
"index": 0,
"delta": {"content": "Hello"},
"finish_reason": null
}]
}
工具调用流:
// Anthropic (开始)
{"type": "content_block_start", "content_block": {"type": "tool_use", "id": "call_abc", "name": "get_weather"}}
// OpenAI
{
"choices": [{
"delta": {
"tool_calls": [{
"index": 0,
"id": "call_abc",
"type": "function",
"function": {"name": "get_weather", "arguments": ""}
}]
}
}]
}
// Anthropic (参数增量)
{"type": "content_block_delta", "delta": {"type": "input_json_delta", "partial_json": "{\"city\""}}
// OpenAI
{
"choices": [{
"delta": {
"tool_calls": [{"index": 0, "function": {"arguments": "{\"city\""}}]
}
}]
}
消息结束:
// Anthropic
{"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {...}}
// OpenAI
{
"choices": [{
"delta": {},
"finish_reason": "stop"
}]
}
已知限制
| 特性 | 限制说明 | 解决方案 |
|---|---|---|
| Thinking | OpenAI 格式不支持 thinking 参数和响应字段 | 使用 /v1/messages 原生端点 |
| Prompt Caching | 无法通过 OpenAI 格式传递缓存控制参数 | 使用 /v1/messages 原生端点 |
| PDF 输入 | Anthropic 支持 PDF 文档块,OpenAI 格式无对应字段 | 不转换,丢弃 PDF 块 |
| 多 System 消息 | Anthropic 只支持单个 system 字段 | 合并多条 system 消息 |
| 消息顺序 | OpenAI 允许连续的 assistant 消息,Anthropic 不允许 | 自动合并连续同角色消息 |
OpenAI ↔ OpenAI Responses 转换
支持的功能
| 功能 | OpenAI → Responses | Responses → OpenAI | 备注 |
|---|---|---|---|
| 基础对话 | ✅ | ✅ | |
| 流式响应 | ✅ | ✅ | |
| 工具调用 | ✅ | ✅ | tool_calls ↔ function_call |
| 推理过程 | ❌ | ✅ | reasoning_content 转为 content |
请求字段映射 (OpenAI → Responses)
消息转换
// OpenAI messages
[
{"role": "system", "content": "You are helpful"},
{"role": "user", "content": "Hi"},
{"role": "assistant", "content": "Hello", "tool_calls": [...]},
{"role": "tool", "tool_call_id": "call_abc", "content": "result"}
]
// Responses input
[
{"type": "message", "role": "system", "content": "You are helpful"},
{"type": "message", "role": "user", "content": "Hi"},
{
"type": "function_call",
"call_id": "call_abc",
"name": "function_name",
"arguments": "{...}"
},
{
"type": "function_call_output",
"call_id": "call_abc",
"output": "result"
}
]
工具定义转换
// OpenAI
{
"type": "function",
"function": {
"name": "get_weather",
"description": "...",
"parameters": {...}
}
}
// Responses
{
"type": "function",
"name": "get_weather",
"description": "...",
"parameters": {...}
}
响应字段映射 (Responses → OpenAI)
非流式响应
// Responses
{
"id": "resp_abc",
"model": "gpt-4o",
"status": "completed",
"output_text": "Hello!",
"output": [
{"type": "message", "content": [{"type": "output_text", "text": "Hello!"}]}
],
"usage": {
"input_tokens": 10,
"output_tokens": 5
}
}
// OpenAI
{
"id": "chatcmpl-abc",
"object": "chat.completion",
"model": "gpt-4o",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello!"
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 5,
"total_tokens": 15
}
}
Status 映射
Responses status | OpenAI finish_reason |
|---|---|
completed | stop |
incomplete | length |
failed | (返回错误响应) |
已知限制
| 特性 | 限制说明 | 解决方案 |
|---|---|---|
| Reasoning Content | OpenAI 格式不保留 reasoning_content 字段 | 使用 /v1/responses 原生端点 |
| 推理过程 | 转换后丢失模型内部推理步骤 | 使用 /v1/responses 原生端点 |
OpenAI ↔ Google Gemini 转换
客户端照常使用 OpenAI chat/completions 格式,网关对 protocol=gemini 的模型做
generateContent 出站构造与响应还原(适配器 internal/proxy/adapter_gemini.go)。
上游鉴权用 x-goog-api-key 头,provider base 填 https://generativelanguage.googleapis.com/v1beta,
出站路径为 baseURL + /models/<模型名>:generateContent(流式为 :streamGenerateContent?alt=sse,
由请求里的 stream 决定,Gemini 请求体本身没有 stream 字段)。
支持的功能
| 功能 | OpenAI → Gemini | Gemini → OpenAI | 备注 |
|---|---|---|---|
| 基础对话 | ✅ | ✅ | |
| 流式响应 | ✅ | ✅ | SSE 逐片段转 OpenAI chunk |
| System 消息 | ✅ | — | 提取到顶层 systemInstruction,多条合并 |
| 图像输入 | ✅ | — | data URL → inlineData |
| 工具调用 | ✅ | ✅ | tools[] ↔ functionDeclarations |
| 工具结果 | ✅ | — | role=tool → functionResponse(按 tool_call_id 回填函数名) |
| Thinking(思考过程) | ✅ 回传 | ✅ | thought part ↔ reasoning_content |
| Usage 统计 | — | ✅ | usageMetadata token 数映射 |
请求字段映射 (OpenAI → Gemini)
顶层字段
| OpenAI | Gemini | 转换规则 |
|---|---|---|
model | URL 路径段 | 不进请求体,替换为真实模型名拼进 /models/<name>:generateContent |
messages | contents[] + systemInstruction | system 提取到顶层;assistant → role:"model" |
max_tokens | generationConfig.maxOutputTokens | 缺省不补(Gemini 用模型自身上限) |
temperature / top_p / top_k | generationConfig.* | 直接映射(camelCase) |
frequency_penalty / presence_penalty | generationConfig.* | 非零才发送 |
stop | generationConfig.stopSequences | 字符串或数组统一成数组 |
stream | 路径动作 | true → :streamGenerateContent?alt=sse |
tools | tools[].functionDeclarations | 函数签名改名 |
tool_choice | toolConfig.functionCallingConfig | 见下表 |
Tool Choice 映射
OpenAI tool_choice | Gemini functionCallingConfig |
|---|---|
"none" | (不发送 tools) |
"auto" | 默认(AUTO),不带 toolConfig |
"required" | {mode: "ANY"} |
{"type":"function","function":{"name":"X"}} | {mode:"ANY", allowedFunctionNames:["X"]} |
消息转换
// OpenAI
{
"messages": [
{"role": "system", "content": "You are helpful"},
{"role": "user", "content": [
{"type": "text", "text": "What's in this image?"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,QUJD"}}
]},
{"role": "assistant", "tool_calls": [{"id":"call_1","function":{"name":"get_weather","arguments":"{\"city\":\"SF\"}"}}]},
{"role": "tool", "tool_call_id": "call_1", "content": "Sunny"}
]
}
// Gemini
{
"systemInstruction": {"parts": [{"text": "You are helpful"}]},
"contents": [
{"role": "user", "parts": [
{"text": "What's in this image?"},
{"inlineData": {"mimeType": "image/png", "data": "QUJD"}}
]},
{"role": "model", "parts": [{"functionCall": {"name": "get_weather", "args": {"city": "SF"}}}]},
{"role": "user", "parts": [{"functionResponse": {"name": "get_weather", "response": {"result": "Sunny"}}}]}
]
}
工具定义转换
// OpenAI
{"type": "function", "function": {"name": "get_weather", "description": "…", "parameters": {…}}}
// Gemini
{"name": "get_weather", "description": "…", "parameters": {…}} // 放进 tools[0].functionDeclarations[]
响应字段映射 (Gemini → OpenAI)
非流式响应
// Gemini
{
"candidates": [{"content": {"parts": [{"text": "Hello!"}], "role": "model"}, "finishReason": "STOP"}],
"usageMetadata": {"promptTokenCount": 10, "candidatesTokenCount": 5, "totalTokenCount": 15},
"modelVersion": "gemini-2.5-flash"
}
// OpenAI(网关还原)
{
"id": "chatcmpl-gemini-…", "object": "chat.completion", "model": "gemini-2.5-flash",
"choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
"usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}
}
Finish Reason 映射
Gemini finishReason | OpenAI finish_reason |
|---|---|
STOP / 其它(SAFETY、RECITATION…) | stop |
MAX_TOKENS | length |
存在 functionCall part | tool_calls |
promptFeedback.blockReason 非空且无 candidates 时,网关按协议转换失败处理(可重试转移),
而不是把一个空回答伪装成正常响应。
流式响应
Gemini 流式(?alt=sse)每条 data: 是一个完整 GenerateContentResponse 片段,网关逐片段转成
OpenAI chunk:text part → delta.content;thought:true part → delta.reasoning_content;
functionCall part → delta.tool_calls;finishReason → 带 finish_reason 的收尾 chunk;
usageMetadata 汇入最终 usage 块。
已知限制
| 特性 | 限制说明 | 解决方案 |
|---|---|---|
| thought 签名/回传 | Gemini 2.x 的 thought 签名无法经 OpenAI 格式保留,多轮思考上下文退化 | 使用 /v1/gemini:* 原生端点 |
| 思考预算 | generationConfig.thinkingConfig 无 OpenAI 对应字段 | body_override 注入或原生端点 |
| 多候选 | 转换层只取第一个 candidate(OpenAI 格式按单 choice 映射) | 原生端点 |
| 非 data URL 图片 | 外链 URL 以 fileData 形式透传,是否可用由上游判定 | 预下载转 base64 |
n 参数 | Gemini 无对应字段,忽略 | — |
type=video 模型挂 /v1/videos,是网关里唯一的异步端点族。上游格式无跨厂商标准
(OpenAI Sora 用 /videos、Runway 用 /image_to_video,参数集互不兼容),因此与
images/tts/stt 同方针:请求体直通,仅重写 model 字段,不做跨厂商转换。
三步流程
① POST /v1/videos {"model":"<路由>","prompt":"...","size":"1280x720","seconds":"8"}
└ 路由选择(type=video) → 密钥轮询 → 直通上游 → 原样回写任务对象 {id, status:"queued", ...}
└ 响应含 id 时登记 video_task(id → 提供商×模型×密钥),提交本身按 per_call 计费落 request_log
② GET /v1/videos/{id} 轮询直到 status=completed/failed
└ 查 video_task 定位上游与当初命中的密钥 → 原样透传 JSON(不落新日志)
③ GET /v1/videos/{id}/content 下载成片
└ 同上,透传 Content-Type/Content-Length 与字节流
设计约束
- 只认自己登记过的任务:
video_task未命中的 id 一律 404。否则任意 id 都会被 带上提供商密钥转发,网关退化为开放代理。 - 回查不走路由/熔断:任务必须回到创建它的上游(渲染产物存在那里),因此按
video_task的落点直连,而非重新做加权选择;也不产生request_log(费用已在 提交时结算,轮询是客户端行为,不该刷统计)。 - 计费:推荐
billing_mode=per_call(提交成功即计一次)。上游回显seconds(Sora 为字符串"8",也有厂商写数字)时记入audio_seconds(仅统计用)。 - 保留期:
video_task跟随log_retention_days清理;映射被清后旧 id 回查 404。 - 模型上游要求:
base_url需为暴露/videos族的端点(如https://api.openai.com/v1)。body_override可改提交体字段;提交与回查路径均按baseURL + /videos//videos/{id}拼接,网关不按api_path改写(typed 端点族同此约定)。路径不兼容时只能由客户端直连上游轮询。
使用建议
选择合适的端点
最佳实践
-
默认使用
/v1/chat/completions- 80% 的场景不需要厂商特性
- 代码统一,易于切换提供商
- 自动负载均衡和容错
-
原生端点用于特殊需求
- Anthropic thinking/extended_thinking
- Anthropic prompt caching
- OpenAI reasoning_content
-
工具调用推荐主端点
- 转换层完整支持工具调用
- 可以在 OpenAI/Anthropic/Responses 间无缝切换
- 注意复杂工具定义可能有边界情况
-
流式响应注意事项
- 转换后的 SSE 格式符合 OpenAI 规范
- TTFT(首字节延迟)统计准确
- 流中断会触发重试(如果配置允许)
验证转换正确性
在生产环境使用前,建议:
- 对比测试: 同时调用原生端点和转换端点,对比响应差异
- 边界用例: 测试多轮对话、工具调用、图像输入等复杂场景
- 错误处理: 验证上游错误能正确透传
- 性能基准: 转换层开销 <1ms,不影响 TTFT
参考实现
- 适配器代码:
internal/proxy/adapter.go - 转换测试:
internal/proxy/adapter_test.go - OpenAI 格式: OpenAI API Reference
- Anthropic 格式: Anthropic Messages API
- Responses 格式: OpenAI Responses API
行业对比
OmniGate 的协议转换方案与主流 AI 网关保持一致:
| 项目 | 转换策略 | 混合端点 | 文档完善度 |
|---|---|---|---|
| OmniGate | 双向完整 | ✅ 3个端点 | ✅ 本文档 |
| LiteLLM | 适配器模式 | ✅ Pass-through | ✅ 官方文档 |
| API7 Gateway | 双向完整 | ✅ URI识别 | ✅ 字段映射表 |
| one-api | 双向完整 | ❌ 单端点 | ⚠️ 代码注释 |
反馈与改进
如果遇到转换问题:
- 检查日志: 开启
debug_stream_log查看原始请求/响应 - 查看尝试日志:
request_attempt表记录每次转发细节 - 提交 Issue: 附带请求体(脱敏)和错误信息
- 降级方案: 使用原生端点绕过转换层