★ FEATURED ARTICLE 【免费下载链接】ai-toolboxPersonal AI Toolbox项目地址https://gitcode.com/gh_mirrors/aitoolbo/ai-toolbox点击查看免费下载AI Toolbox 是一个开源的个人 AI 工具箱其中最硬核的模块之一就是它的AI 协议网关Proxy Gateway。它运行在你的本机负责把 Claude Code、Codex、Grok CLI、Kimi CLI、Gemini CLI 这些 AI 编程工具的请求转发到任意你选择的模型供应商——哪怕两端说的是不同的语言。这篇深度剖析将带你从零理解四大 AI 协议网关转换架构是如何实现的为什么它的转换方案既优雅又稳健。先看它在产品里的位置每个 CLI 工具的供应商列表里都可以配置不同协议的 API 端点为什么需要 AI 协议网关 一个绕不开的现实问题不同 AI 工具说不同的协议。客户端入站协议上游可能需要转换的目标协议Claude CodeAnthropic MessagesOpenAI Chat、OpenAI Responses、Gemini NativeCodexOpenAI Responses / ChatAnthropic Messages、OpenAI Chat、Gemini NativeGrok CLIOpenAI ResponsesAnthropic Messages、OpenAI Chat、Gemini NativeKimi CLIOpenAI ChatAnthropic Messages、OpenAI Responses、Gemini NativeGemini CLIGemini NativeAnthropic Messages、OpenAI Chat、OpenAI Responses比如你的 Claude Code 只会说Anthropic Messages但你手里 DeepSeek 的端点是OpenAI Chat格式。直接转发400 错误。这时 AI Toolbox 的协议网关就登场了——它把请求翻译成上游听得懂的格式再把响应翻译回来。而供应商端点的具体协议在表单里以apiFormat形式选择两层架构runtime 管编排transformer 管翻译理解整个网关的关键是先看清它的分层设计。AI Toolbox 把协议转换拆成两个互不越权的层1️⃣ runtime 层runtime/请求编排负责流程控制的一切匹配入站路由、读取供应商配置、确定源协议/目标协议、决定是否转换、拼接上游 URL 与鉴权头、执行供应商方言兼容、记录日志统计、处理重试与故障转移。2️⃣ transformer 层transformer/纯协议翻译负责内容翻译的一切把四种聊天协议的 JSON 请求体、错误体和 SSE 流相互转换。它不读数据库、不拼 URL、不注入 API Key只接收源协议 → 目标协议的转换路由和原始载荷输出转换后的载荷。这个边界划得非常干净——协议结构互转换给 transformer供应商方言兼容DeepSeek 的 thinking 门控、Bedrock 的路径差异、Ollama 的 wire 格式全部留在 runtime。新增一家供应商时永远不用改 transformer 一行代码。四大协议与 4×4 转换矩阵协议枚举定义在 transformer/types.rs协议代码字符串典型 wire APIAnthropicMessagesanthropic_messagesAnthropic/v1/messagesOpenAiResponsesopenai_responsesOpenAI/v1/responsesOpenAiChatopenai_chatOpenAI/v1/chat/completionsGeminiNativegemini_nativeGeminigenerateContent/streamGenerateContent四种协议两两互转构成12 个非恒等转换方向4×4 去掉 4 个恒等方向JSON 请求、JSON 响应、错误体和 SSE 流全部走同一套转换路由语义。一个值得注意的优化同协议请求根本不进转换器。当源协议与目标协议相同时走直通链路只做模型名改写、鉴权注入等 runtime 处理保持字节保真。转换核心统一中间表示LLM IR如果四种协议两两互写需要 12 套转换器——这是蜘蛛网式的噩梦。AI Toolbox 用了经典而高效的星型架构所有协议都先翻译成统一中间模型IR再由 IR 翻译成目标协议。源协议 JSON ──入站转换器──▶ LLM IR ──出站转换器──▶ 目标协议 JSONLLM IR 定义在 llm/model.rs 和 llm/tools.rs它不是对外 API只是转换内部的通用语承载消息列表角色、文本/图片内容、工具调用与工具结果、推理内容reasoning请求参数model、max_tokens、temperature、top_p、stop、stream 等工具定义tools、tool_choice、parallel_tool_calls响应元数据choices、usage、finish_reason这样每种协议只需要维护入站 出站两个转换器双向共 4 个12 个方向全部由4 个协议 × 2 个方向的组合覆盖。转换内核入口在 transformer/kernel.rs。一次请求的完整旅程以Claude Code 请求转发到 DeepSeekOpenAI Chat 端点为例整条链路在 runtime/upstream.rs 中编排路由匹配入站前缀/anthropic命中 Claude Code 路由runtime/routes.rs推导出源协议 AnthropicMessages读取供应商从供应商配置解析目标协议 OpenAiChatruntime/providers.rs决策源 ≠ 目标创建ConversionRoute请求转换源 JSON → LLM IR → 目标 JSON供应商方言适配最后一跳执行 DeepSeek 专属规则thinking 字段门控、JSON schema 降级等拼 URL / 鉴权头发出上游请求响应回转响应按反向路由target → source翻译回 Anthropic Messages 格式返回客户端流式响应SSE 的边读边转AI 编程工具大量使用流式输出SSE这给转换带来了额外挑战不能把整个流缓冲下来再翻译必须边读边写。StreamKerneltransformer/stream.rs的处理模型处理 UTF-8 跨 chunk 边界解析 SSE 事件块同时兼容 LF 和 CRLF 行尾源协议解析器把各协议事件解析成统一流事件Start、TextDelta、ReasoningDelta、ToolCall、Finish 等目标协议写入器把统一事件写成目标协议的 SSE各协议流式的方言Chat 的[DONE]、Anthropic 的message_stop、Responses 的终态事件、Gemini 的 finish chunk都被归一化且结束事件幂等处理不会重复输出完成信号。跨请求状态Side Stores 的巧妙隔离多轮对话里有一些状态天然跨越 HTTP 请求。AI Toolbox 把它们统一放在runtime/side_stores/与 transformer 完全隔离CodexHistoryStore记录上一轮的工具调用当 Codex 下一轮只带previous_response_id时自动补回缺失的前序工具调用GeminiShadowStore回放带thoughtSignature的模型函数调用保证 Gemini 多轮工具链不断裂InvalidResponsesCipherStore负缓存记住上游明确拒绝过的加密内容摘要避免反复撞墙三者都有容量上限和可靠的会话键且不落数据库。供应商方言兼容runtime 的专属领域看起来像协议转换的逻辑其实大多属于供应商方言——比如 DeepSeek 不接受 OpenAI 的 JSON Schema wrapper、Ollama 的最后一跳是/api/chat而非标准 Chat。这些规则全部收敛在 runtime 的 outbound body pipeline 中按providerType target_protocol识别供应商方言DeepSeek、Moonshot、GLM、xAI、Bedrock、Vertex、Copilot、Ollama 等十余种永远不下沉到 transformer。判断依据是供应商配置里显式声明的 profile 引用而不是靠模型名或 Base URL 猜供应商——这意味着自定义供应商不会被误套官方方言聚合商也不会被当成官方渠道。有损转换检测宁可信其有不是所有字段都能无损翻译。check_lossy_conversion()transformer/shared/lossy.rs在转换前检测高风险项——例如 Responses 的 hosted tool、Anthropic 的 server tool、Gemini 专属的 safetySettings 等目标协议无法表达的内容。它只检测、不决策是否拒绝由 runtime 策略决定默认只把警告写入响应头X-Transformer-Lossy当用户开启有损拒绝且请求未带X-Allow-Lossy头时才返回本地 400。宁可透明地告诉你这里可能有损失也不静默丢字段。关键源码与文档索引想继续深挖这些入口最值得阅读模块路径职责协议枚举与转换路由transformer/types.rsAiProtocol、ConversionRoute转换内核transformer/kernel.rsJSON/错误体/SSE 转换入口LLM IRtransformer/llm/model.rs统一中间表示流式转换transformer/stream.rsStreamKernel与统一流事件上游编排runtime/upstream.rs请求/响应主编排有损检测transformer/shared/lossy.rs纯检测函数完整协议转换源码在 transformer/ 模块架构主文档见 docs/gateway-protocol-conversion.md逐供应商兼容细节见 docs/gateway-provider-compatibility.md。总结AI Toolbox 的协议网关转换架构核心思想可以浓缩成三句话星型架构用统一 LLM IR 把 12 个转换方向降维成 4 个协议的入站/出站转换器严格分层transformer 只管协议翻译runtime 管编排与供应商方言边界清晰到新增供应商零改动转换器透明可信有损检测、字节保真直通、终态精确判定宁可失败也不伪造成功。下次当你的 Claude Code 在 Codex 格式的供应商上流畅对话时背后正是这套四大 AI 协议网关在默默完成无数次双向翻译。赞分享【免费下载链接】ai-toolboxPersonal AI Toolbox项目地址https://gitcode.com/gh_mirrors/aitoolbo/ai-toolbox点击查看免费下载相关推荐最稳AI架构揭秘如何用Portkey实现99.99%可用性的企业级LLM网关最稳AI架构揭秘如何用Portkey实现99.99%可用性的企业级LLM网关 在当今AI驱动的商业环境中企业对大语言模型LLM服务的依赖程度日益加深而LLM 网关API网关后端负载均衡人工智能多协议网关架构Authelia协议转换与统一认证多协议网关架构Authelia协议转换与统一认证 引言现代应用认证的挑战 在当今复杂的微服务架构中应用认证面临着前所未有的挑战。不同服务可能使用不同的认证后端认证鉴权单点登录身份认证应用安全FunASR 完全指南从会议转写到实时字幕一套免费开源语音识别工具搞定FunASR 完全指南从会议转写到实时字幕一套免费开源语音识别工具搞定 一场两小时的会议纪要、几百段客服录音、需要实时字幕的直播——这些场景背后都是同一个需语音音频人工智能大模型模型推理服务本地部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
