CodexManager网关内幕：/v1/chat/completions与/v1/responses如何实现协议适配与SSE流式转换

CodexManager网关内幕/v1/chat/completions与/v1/responses如何实现协议适配与SSE流式转换【免费下载链接】Codex-Manager一个Codex cli 账号管理与切换工具。为 Codex cli提供本地网关转发。项目地址: https://gitcode.com/gh_mirrors/co/Codex-ManagerCodex-ManagerCodexManager是一款面向 Codex CLI 的账号管理与切换工具内置本地网关转发能力。它的网关同时受理 OpenAI 生态中最常用的两条接口/v1/chat/completionsChat Completions与/v1/responsesResponses API。两者请求结构、事件流格式完全不同CodexManager 通过一套“协议适配 SSE 流式转换”机制让任意客户端都能透明接入上游 Codex 账号这篇文章带你拆解它的实现内幕。先搞懂问题两条协议差在哪想理解网关的难度先要清楚两套协议的“语言习惯”不同维度/v1/chat/completions/v1/responses输入结构messages数组role contentinputitemstext、function_call 等角色user/assistant/systemuser/assistant/developer工具调用tool_calls增量 arguments 片段function_call/function_call_outputitems流式输出data: {...choices...}逐块 data: [DONE]带event:名的语义事件response.output_text.delta等也就是说即便客户端都发的是“流式请求”Chat Completions 拿到的是块级 delta而 Responses 拿到的是带事件名的语义流。网关要做的事就是让两条链路在入口改写请求、在出口逐帧改写响应做到客户端无感。网关总架构请求进来后走了哪些子模块CodexManager 的网关实现集中在 crates/service/src/gateway/ 目录官方协作文档把职责拆得很清晰典型链路是request/入站请求规范化与 chat/responses 请求改写routing/按模型目录 V2 选择候选账号与路由策略auth/upstream/补全上游鉴权并发送请求protocol_adapter/产出内部统一请求结构与响应适配标记observability/写入 trace、请求日志与指标其中决定“这条响应该怎么做适配”的核心是 protocol_adapter/types.rs 中的ResponseAdapter枚举它定义了网关支持的全部适配方向包括Passthrough原样透传、ChatCompletionsFromResponsesResponses 流转 Chat Completions 流、ResponsesFromAnthropicMessages、ImagesB64JsonFromResponses等——这正是文章标题里“协议适配”的代码级对应物。/v1/chat/completions 入站改写把“旧协议”翻译成 Responses当客户端以 Chat Completions 协议接入、而上游链路是 Responses 时请求体会先在 request_rewrite_chat_completions.rs 中完成结构化改写关键动作包括角色映射developer/system归一为systemassistant、tool保持其余落入user内容扁平化Responses 的多段 contentinput_text、input_image等被展平为 Chat Completions 的字符串或image_url结构流式判定读取请求体中的stream字段决定后续走 SSE 转换器还是 JSON 直出配套的路径识别与字段白名单逻辑放在 request_rewrite_shared.rs协议路由的总入口则是 protocol_adapter/request_router.rs 中的adapt_request_for_protocol。改写完成后网关内部持有的是一份统一结构AdaptedGatewayRequestpath body 响应适配器 工具名还原映射上游发出去的才是对应协议的原始报文。/v1/responses 直通链路能不动就不动与 Chat Completions 需要“翻译”不同/v1/responses是 Codex 官方链路CodexManager 对它采取透传优先策略请求侧默认完全跟随客户端model字段不做隐式改写仅在显式转发规则、平台密钥强绑模型等明确配置下才替换流式响应由 stream_readers/openai_responses.rs 中的OpenAIResponsesPassthroughSseReader逐帧透传唯一的“加工”是旁路收集 usage 与首响应耗时供日志与计费使用这种设计保证了 Codex CLI 官方体验不被网关“损耗”而跨协议兼容只在确实需要时才发生。SSE 流式转换核心Responses 事件流 → Chat Completions 帧真正体现工程功力的是出口侧的ChatCompletionsFromResponsesSseReader实现位于 stream_readers/chat_completions.rs。它的工作方式可以概括为“读一帧、翻译一帧、立刻下发”帧泵驱动底层的UpstreamSseFramePump从上游响应体中持续切出 SSE 帧解析data:与event:行[DONE]被识别为终止信号元数据记忆首个带response的帧会被提取id、model、created_at并顺手合并 usage 到共享收集器保证计费数据完整状态机去重读者内部维护emitted_assistant_role、emitted_text、emitted_tool_call_indices等状态确保choices[0].delta.role只发一次、工具调用按索引顺序聚合 arguments 片段不会把 Responses 的语义事件“原样泄漏”给 Chat Completions 客户端流保护配合公共模块 stream_readers/common.rs 提供首响应计时、流空闲超时判定与 keepalive 帧慢首字时下游不会被挂死非流式场景则由 http_bridge 的 body_conversion.rs 完成整包 JSON 的结构转换错误体统一由 compact_errors.rs 收敛客户端看到始终是标准 OpenAI 错误格式。可观测性每一次适配都留痕协议转换最怕“出了问题查不到”因此 observability/request_log.rs 会把每条请求的入站路径、适配方向、账号命中、token 用量与耗时写入请求日志metrics.rs 则汇总成面板趋势。网关侧还保留了与官方 Codex 请求头/参数的逐项对照文档方便排查兼容性问题docs/zh-CN/report/当前网关与Codex官方请求参数对照表.mddocs/zh-CN/report/当前网关与Codex请求头和参数差异表.mddocs/zh-CN/ARCHITECTURE.md关键文件速查表模块路径职责协议路由protocol_adapter/request_router.rs选择适配方向并改写请求Chat 入站改写request/request_rewrite_chat_completions.rs角色映射、内容扁平化SSE 帧转换observability/http_bridge/stream_readers/chat_completions.rsResponses 流 → Chat Completions 流透传读取observability/http_bridge/stream_readers/openai_responses.rs/v1/responses 原样透传非流式转换observability/http_bridge/body_conversion.rs整包 JSON 协议互转目录协作文档crates/service/src/gateway/README.md子模块职责与修改建议小结网关价值的本质是“翻译层”CodexManager 网关的设计哲学可以总结为三点入站先归一、上游能透传就透传、出口按客户端协议逐帧回译。/v1/responses链路追求零损耗直通/v1/chat/completions链路靠请求改写与 SSE 状态机实现无损兼容两条链路共用同一套路由、鉴权与可观测性底座。理解了这套协议适配与 SSE 流式转换机制你也就理解了它为什么能让 Codex 账号同时服务 Chat Completions、Responses、Anthropic 乃至图像等多类客户端。【免费下载链接】Codex-Manager一个Codex cli 账号管理与切换工具。为 Codex cli提供本地网关转发。项目地址: https://gitcode.com/gh_mirrors/co/Codex-Manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考