如何统一三大模型协议:Eta对OpenAI、Responses与Anthropic Messages的适配深度剖析

原创2026-10-10 17:41:191,982 阅读

如何统一三大模型协议:Eta对OpenAI、Responses与Anthropic Messages的适配深度剖析

Eta 聊天界面与模型配置预览

Eta 是一款系统级 Android AI Agent,它最容易被忽视、却最见工程功底的部分,是对三大模型协议(OpenAI Chat Completions、OpenAI Responses、Anthropic Messages)的统一适配:你在同一份 Eta 里切换 OpenAI、Claude 或任意 OpenAI-compatible 服务商,Agent Loop 的代码完全不用改。本文带你拆解 Eta 是如何把这三套"方言"收敛成一种"普通话"的。

为什么协议适配是 AI Agent 的隐形深水区 🧩

三家 API 的差异远不止"换个请求体":

维度 Chat Completions Responses API Anthropic Messages
鉴权 Authorization: Bearer Authorization: Bearer x-api-key + anthropic-version
系统指令 messages 中的 system 消息 顶层 instructions 顶层 system 字段
工具结果 role: tool 独立消息 input Item 并入 user 消息的 tool_result 块
流式终止 finish_reason + [DONE] response.completed message_stop

如果每接一个协议就复制一套"请求-流式-解析"代码,UI、重试、取消、测试全都要乘三倍。Eta 的做法是:把协议差异压缩进一层薄薄的边界,边界之内各说各话,边界之外只有一种语言。

Eta 设置页的提供商与模型配置

统一抽象:AgentProviderClient 是唯一的"协议边界"

Eta 在 AgentProvider.kt 中定义了全部三个协议共用的接口:

internal interface AgentProviderClient {
    val id: String
    val capabilities: ProviderCapabilities
    fun complete(
        request: ProviderRequest,
        runController: AgentRunController,
        onEvent: (ProviderEvent) -> Unit = {}
    ): ProviderResponse
}

入参是统一的 ProviderRequest(配置 + 消息 + 工具),流式过程通过统一的 ProviderEvent(BlockStart / BlockDelta / BlockEnd / Usage / Completed)上报,返回值是统一的 ProviderResponse。上游的 Agent Loop、UI 与工具执行器永远只面对这一种事件,彻底与协议解耦。

哪个协议上场,由工厂根据配置决定——见 ProviderClientFactory.kt:

ProviderTypes.OPENAI_COMPATIBLE -> when (config.openAiEndpointMode) {
    OpenAiEndpointMode.RESPONSES -> OpenAiResponsesProvider
    else -> OpenAiChatCompletionsProvider
}
ProviderTypes.ANTHROPIC -> AnthropicMessagesProvider

配置模型上,服务商只有两类:openai_compatible(内部再细分 chat_completions / responses 两种端点模式)和 anthropic,定义在 Provider.kt。另外每个 Provider 都自带一份 ProviderCapabilities 能力声明(流式文本、流式工具、图片输入、并行工具调用等),上层功能按能力位降级,而不是写死协议名。

协议一:Chat Completions——兼容面最广的"老方言"

OpenAiChatCompletionsProvider.kt 面向绝大多数 OpenAI-compatible 端点,几个关键处理:

  • URL 拼装:在 Base URL 后追加 chat/completions,见 ProviderUrls.kt;
  • system 合并:OpenAiRequestMessages.kt 把上下文中全部 system 内容按原顺序合并为首条唯一系统消息,兼容那些要求系统消息只能出现在开头的模型 Chat Template;
  • 工具 ID 修复:流式工具调用按 index 聚合,空 ID 不覆盖已收到的有效 ID;响应结束时为缺失/冲突的 ID 分配响应级唯一值,且只修复出站副本、不改写持久历史;
  • 用量统计:默认附加 stream_options.include_usage,唯独对 OpenRouter 关闭(避免其兼容层报错)。

协议二:Responses API——OpenAI 新范式与托管搜索

OpenAiResponsesProvider.kt 与请求构造器 ResponsesRequestBuilder.kt 处理的是 OpenAI 的新范式:

  • 请求体不再是 messages,而是 instructions + input Items;Eta 把 system/developer 消息投影到 instructions,历史重建为带 type: "message" 的 input Item,并显式写入 store: false 避免服务端留存;
  • 并行工具调用是它的独有开关:Chat Completions 的 capabilities 中 parallelToolCalls = false,而 Responses 端为 true;
  • 托管网页搜索:仅 Responses 协议有独立开关,开启后请求只增加 web_search 托管工具,搜索开始/结束作为独立运行事件投影到 UI,且不受本地 browserTools 开关控制;最终回答中的 url_citation 会去重并转成可点击的 Markdown 引用。

协议三:Anthropic Messages——结构差异最大的一支

AnthropicMessagesProvider.kt 承担最多的结构翻译工作:

  • system 消息抽离到顶层 system 字段,鉴权改用 x-api-key + anthropic-version(默认 2023-06-01,用户可配);
  • tool 消息的"再入 user":OpenAI 风格的 role: tool 会被转换成 user 消息内的 tool_result 块,并与紧随其后的观察图片、用户补充合并进同一条 user 消息——因为官方接口会合并连续同角色消息,但兼容端点不一定这么做,第二条孤立的 tool_result 会被判为非法块(见 appendTurn 的注释);
  • 工具 schema 翻译:Anthropic 不接受 oneOf / anyOf / allOf 顶层组合关键字,转换时会剥离;
  • max_tokens 按模型名自动给默认值,用户在 custom body 里显式填写的值优先级最高;
  • 思考签名回传:工具回合会在当前 run 的模型上下文中按原顺序回传思考块、签名及加密块,供后续 tool_result 继续使用;自动压缩会被延后到签名回合完成,强制压缩则明确报错。

Eta 工具能力面板,展示协议适配支撑的多类工具

流式解析:共享 SSE 分帧,终态各回各家

三套协议都走 SSE,但事件语义完全不同(choices<a href="https://link.gitcode.com/i/6725f27e333cfc836cd1838e6dd5cf6a" target="_blank">0].delta / response.* 事件族 / content_block_* 事件族)。Eta 把协议无关的分帧逻辑抽到共享函数 [ProviderSseReader.kt:多行 data:、注释心跳、UTF-8 解码统一处理,回调返回 false 即视为"已收到终态",立即停止读取、不等服务端关闭连接。

收尾语义则各有讲究:

协议 结束条件
Chat Completions finish_reason 到达时结束可见块,再接收用量与 [DONE]
Responses response.completed 到达即收尾
Anthropic message_stop 到达即收尾

缺少合法终态、或 Anthropic 可见块/工具块未闭合时,Eta 会返回"未完成"错误而不是静默吞掉。三种协议的推理内容也各自消费(reasoning_content / reasoning summary / thinking_delta),最终统一投影为 THINKING 块供 UI 展示。

统一出口:停止原因与事件的"归一化"

无论哪个协议,最终结果都会归一化到 AssistantStopReason:stop/end_turn → END_TURN,tool_calls/tool_use → TOOL_USE,length/max_tokens → OUTPUT_LIMIT,content_filter/refusal → CONTENT_FILTER。Agent Loop 只需判断"要不要执行工具批次",不需要知道对面是谁。

流式侧同理:三个 Provider 把各自的分片翻译成同一套 BlockStart → BlockDelta → BlockEnd 事件,并用 round + block index 的块身份避免正文、思考、工具三类内容互相串块;类型一旦切换,上一段可见块立即定稿。UI 只消费这套事件,天然协议无关。

细节打磨:从模型目录到推理强度

协议统一之外,Eta 还铺了几条"隐形道路":

  • 推理强度映射:ProviderReasoning.kt 把统一的 reasoningEffort 翻译成各服务商的私有写法(百炼、SiliconFlow、DeepSeek、Moonshot、OpenAI……每家一套),用户只感知"开/关/力度";
  • 模型目录:从 models.dev 拉取公开元数据(随 APK 附带压缩快照),只列出可按 Chat Completions 接入且具备文本输出与工具调用能力的模型;读取目录不会外发 API Key;
  • 自定义能力:自定义 Header / Body 在请求组装时合并,但 model、instructions 等决定协议正确性的字段由运行时最终写入,用户配置无法"污染"协议骨架。

如何验证与延伸阅读

Eta 为每条协议链路都配了独立的单元测试,是阅读实现的最佳入口:

官方文档 docs/AGENT_RUNTIME.md 的"Provider 边界"章节逐条记录了消息投影、ID 修复、思考签名与托管搜索的行为约定,docs/TECHNICAL.md 则覆盖整体技术架构。

结语:一份会话,三种协议,零感知

这套设计的收益可以一句话概括:UI 只消费一种 ProviderEvent,工具目录只生成一份 JSON Schema,历史只存一种会话结构——协议差异被牢牢关在三个 Provider 对象与若干转换器里。对普通用户,这意味着在设置页切换服务商、在 Chat Completions 与 Responses 之间选择端点,甚至接入 Claude,都只是"换个模型"这么简单;而对开发者,Eta 的 agent/model/ 目录本身就是一份"多协议 AI Agent 适配"的可借鉴样板。

登录后查看全文
Eta