Files
moyi-model-intelligence-hub/docs/30-codex-responses-continuation-design.md
T
xppandClaude Opus 5.5 bb3baed095
Repository verification / backend (push) Canceled after 0s
Repository verification / frontend (push) Canceled after 0s
docs:"记录 COD-01/02 暂缓、不存储对话与 Sub2API 对齐决定"
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-22 21:49:56 +08:00

22 KiB
Raw Blame History

Codex 兼容:Responses 续接归属与 WebSocket 设计(COD-01/COD-02)

日期:2026-10-22(Asia/Shanghai)。状态:暂缓实施(2026-10-22 决定,见第 0 节)。对应 24 号任务表 COD-01、COD-02,承接 29 号文档第五节与第八节第二阶段。

0. 决定(2026-10-22)

  1. 暂不实施 COD-01/COD-02。现有行为不变:Responses 入口继续拒绝 previous_response_id,不提供 WebSocket。
  2. 不允许上游存储对话,继续强制 store=false。
  3. 本阶段目标是在 Sub2API 的能力基础上做企业化(组织、权限、人民币计费、审计、运维治理),不做协议层的革新设计。日后恢复续接与 WebSocket 时,以 Sub2API 的行为为基线对齐,见 0.2。

0.1 不存储对话的后果

store=false 时上游不保存响应,HTTP 请求里的 previous_response_id 一定得到 previous_response_not_found。增量续接的唯一途径是 WebSocket:上游只在一条活动连接的内存里缓存最近的响应状态,连接断开或满 60 分钟即失效。因此恢复这项工作时必须同时完成:

  • 服务器 nginx 配置:infra/moyi/nginx/routes.conf 与 prototype/nginx.conf 为 /v1/responses 转发 Upgrade 和 Connection: upgrade;读超时不低于连接上限(Sub2API 上游读超时 900 秒,连接上限 60 分钟);云端 Compose 透传 COD-03 的超时变量。这是线上配置变更,须单独评审。
  • 连接管理:
    • 每个平台 Key 的连接数上限;
    • 首条消息读取超时、两轮之间的空闲超时、60 分钟连接上限;
    • 每个客户端连接绑定一条上游连接及其账号;
    • 连接内存里保留本连接的历史输入,用于续接失败时服务端重放一次,不落库;
    • 客户端或上游断开时,进行中的一轮按现有规则结算或释放预留。

HTTP 续接只有在允许 store=true 时才可行,与第 2 条决定冲突,本阶段不做。

0.2 恢复实施时与 Sub2API 对齐的清单

依据第 10 节的源码核对。

事项 Sub2API 行为 MOYI 实施时
归属存储 Redis,Key 为 response_id 的 SHA-256,按分组隔离;进程内热缓存 对齐:用现有 Tair,同样只存哈希 Key 和账号 ID
保留时间 1 小时(sticky_response_id_ttl_seconds: 3600) 对齐:1 小时,可配置
归属校验 校验用户与 Key,不匹配返回 400 对齐
消息 ID 误用 拒绝 msg_、item_ 等前缀 对齐
原账号不可用 放弃粘连,正常调度另选账号;带未覆盖的 function_call_output 时只能走原账号 对齐
previous_response_not_found WebSocket 内用连接内存的历史去掉 previous_response_id 重放一次(未向客户端输出、无工具输出、每轮一次) 对齐
WebSocket 参数 每 Key 64 连接、轮间空闲 300 秒、首消息 30 秒、上游读 900 秒、store=false 时优先新建连接、预热默认关闭 作为默认值起点,按服务器容量调整

MOYI 保留自己的企业化部分:每一轮独立走人民币钱包预留、续期与结算(GatewayRequestExecutionService)、用量审计、凭据加密存储。这些属于企业化而非协议创新。

第 3–5 节是对齐决定之前的初稿。其中与 0.2 冲突的设计(PostgreSQL 归属表、凭据版本、原账号不可用时 409 不换号)不再采用,归档在第 11 节。

1. 目标与非目标

目标:

  • 让 Codex 等编程客户端通过 MOYI 使用 Responses 协议的增量续接(previous_response_id),不再每轮发送完整上下文。
  • 提供 Responses WebSocket 入口,单连接多轮、顺序执行。
  • 每个上游响应都能追溯到产生它的渠道账号与凭据版本,续接只能发往同一账号;无法满足时明确失败,不静默换号。
  • 计费、预留、并发租约、用量审计与现有 HTTP 路径共用同一套合同(GatewayRequestExecutionService),不另起账本。

非目标(本期不做):

  • 上游 store=true 的云端会话、conversation 对象、background 后台任务。
  • 图片、文件、托管工具(web_search、code_interpreter 等)。它们需要单独计费适配器,仍按现状拒绝。
  • OAuth 订阅账号池(OPS-02,可选方案,须先核实授权)。
  • 跨实例共享 WebSocket 连接。单个连接只存在于持有它的 API 实例。

2. 依据与当前代码事实

外部协议依据(Azure OpenAI Responses WebSocket 文档,2026-10-22 读取;OpenAI 官方页面在本机网络不可访问,未直接核对):

  • 连接路径为 /v1/responses,客户端发送 {"type":"response.create", ...},载荷同 HTTP 创建请求,但不适用 stream、background。
  • 同一连接内顺序执行,同时只有一个进行中的响应。(部分资料提及按 stream_id 并行的新版本,未经核实,本设计按顺序执行实现,并在客户端验收中确认实际版本。)
  • 连接本地缓存最近一个响应状态;store=false 时引用不在缓存中的 ID 返回 previous_response_not_found;某一轮 4xx/5xx 失败会从缓存驱逐被引用的父响应。
  • 连接最长 60 分钟,到期返回 websocket_connection_limit_reached,须重连;store=false 下重连后只能不带 previous_response_id、重发完整上下文。
  • 可用 generate:false 预热,返回可续接的响应 ID 但不产生输出。

本仓库当前事实(已读代码核实):

位置 现状 对本设计的影响
gateway/NativeProtocolMeter.java 拒绝 previous_response_id、conversation、background;强制 store=false;请求上限 256 KiB;输出上限 32768 续接需放开 previous_response_id,其余限制保留
provider/UpstreamHealth.java X-Moyi-Session 加平台 Key 做 rendezvous 哈希选号;账号冷却后会改选其他账号 只能算“尽量同号”,不能保证续接归属
provider/OpenAiCompatibleProvider.java 账号选择、401/403/429 换号重试都在一次请求内部完成;不对外暴露最终使用的账号 需要把“实际使用的账号指纹”返回给调用方
model_tasks.provider_key_fingerprint(V33) 异步任务已按账号指纹绑定轮询 同步续接沿用相同的指纹方案,不存明文 Key
gateway/request/GatewayRequestExecutionService 统一准入、预留、续期(COD-03)、结算、失败释放 WebSocket 每一轮都走它,复用续期
nginx infra/moyi/nginx/routes.conf、prototype/nginx.conf 无 Upgrade/Connection 转发,读超时 120 秒 WebSocket 必须改代理配置,属部署变更

3. 核心设计:响应归属记录

3.1 记录什么

新增表 responses_ownership(迁移 V51),每个成功完成的上游 Responses 响应写一行:

列 说明
response_id 上游返回的 id,主键(varchar(128))
user_id、api_key_id 发起方。续接时必须与当前调用方一致,防止拿别人的 ID 续接
route_id、provider_id、upstream_model 产生该响应的路由快照
account_fingerprint 实际使用账号的 SHA-256 指纹(同 UpstreamHealth.fingerprint),不存明文
credential_version 渠道凭据版本,见 3.3
transport http 或 websocket
connection_id WebSocket 连接 ID(HTTP 为空)
parent_response_id 本轮引用的上一响应,便于审计链路
usage_event_id 对应 usage_events.id(即计费 ticket)
created_at、expires_at 默认保留 1 小时(可配置,与上游 WebSocket 连接上限及 Sub2API 默认值一致),到期由定时任务清理

不存储请求或响应正文。只存路由与账号指纹,满足“可追溯但不留内容”。

3.2 续接时如何使用

收到带 previous_response_id 的请求(HTTP 或 WebSocket):

  1. 按 response_id 查归属行。不存在或已过期:返回 400 previous_response_not_found(与上游错误码一致),不发往上游、不预留。
  2. user_id/api_key_id 与当前调用方不一致:同样返回 previous_response_not_found,不泄露该 ID 是否存在。
  3. 路由已下线、模型不一致、账号指纹不在当前可用账号集合中、凭据版本已变化、或账号处于冷却:返回 409 RESPONSE_OWNER_UNAVAILABLE,提示客户端不带 previous_response_id 重发完整上下文。不换号:其他账号持有的上游状态里没有这个响应,换号只会得到上游的 previous_response_not_found,还可能已经产生费用。
  4. 校验通过:以“指定账号”方式调用上游(新增 OpenAiCompatibleProvider 的 pinned-key 入口),禁用该请求内的 401/403/429 换号重试与 GatewayFailover 备用路由。

3.3 凭据版本

当前渠道 Key 来自 model_providers.credential_ciphertext 或环境变量 Key 池,没有版本号。方案:

  • 数据库渠道:credential_version 取渠道 updated_at。注意当前任何渠道编辑(包括改名)都会更新该字段,所以编辑渠道会让已有续接失效。这是偏保守的取舍,不新增管理界面。
  • 环境变量 Key 池:没有版本号,只靠账号指纹。Key 被替换后指纹必然改变,旧响应同样失效。
  • 自 1a608f8 起,修改渠道 Base URL 必须重填凭据,因此地址变更一定会触发失效,走 3.2 第 3 步。

真正独立的账号实体与版本属于 SCH-01,本期不扩展。

3.4 写入时机与一致性

  • HTTP 非流式:在 settle 成功之后写入归属行。结算失败(SETTLEMENT_PENDING)时仍写入,因为上游响应已存在;归属不影响账务。
  • 流式/WebSocket:收到 response.completed 或 response.incomplete 事件、拿到 response.id 后写入。
  • 写入失败只记日志、不影响本轮返回;代价是下一轮续接得到 previous_response_not_found,客户端按规范回退为完整上下文。这是安全方向的失败。

4. HTTP 续接(COD-01)

更正(2026-10-22,核对 Sub2API 后):HTTP 续接要求上游保存响应(store=true)。本设计强制 store=false,上游不保存,HTTP 请求里的 previous_response_id 会稳定返回 previous_response_not_found。Sub2API 同样只允许 API Key 类账号在 HTTP 下续接,也是依赖上游存储。因此:

  • 若保持 store=false(不让上游保存用户对话,当前的隐私与数据驻留立场),HTTP 续接没有意义,增量续接只能通过 WebSocket 连接内的缓存实现,见第 5 节。
  • 若允许 store=true,HTTP 续接可用,但用户的输入和输出会存储在上游服务商处(OpenAI 默认保留 30 天),须在服务条款和隐私说明中告知,并按用户或 Key 单独开启。

以下改动点在两种选择下都需要(归属记录、指定账号、跳过备用路由),只是第 1 条的 store 处理不同。

改动点:

  1. NativeProtocolMeter.request:允许 previous_response_id(字符串,1–128 字符);继续拒绝 conversation、background、媒体与托管工具。store 按上面的决定处理:默认仍强制 false;若开启存储,则只对已授权的用户或 Key 允许 true。
  2. 新增 ResponsesOwnershipService(gateway/responses 包):查询、校验、写入、清理。依赖方向测试中禁止它依赖 HTTP 客户端与凭据解密。
  3. OpenAiCompatibleProvider:
    • 新增返回“实际使用账号指纹”的结果包装,供写归属。
    • 新增 pinned-key 调用:只用指定指纹对应的 Key;该 Key 不在 Key 池或已冷却时在发送前报 RESPONSE_OWNER_UNAVAILABLE。
  4. NativeGatewayController:带 previous_response_id 时跳过 GatewayFailover,只走原路由。
  5. 计费:不变。续接请求的输入 Token 由上游 usage.input_tokens 计量(包含被续接的历史上下文),input_tokens_details.cached_tokens 走现有缓存价。预留按本轮请求体估算,偏低部分由结算时的实际用量和现有欠费处理兜底。

5. WebSocket 入口(COD-02)

5.1 连接与鉴权

  • 路径 GET /v1/responses,Upgrade: websocket。使用 Spring WebSocket(新增 spring-boot-starter-websocket,版本跟随 Spring Boot parent)。
  • 握手时用 Authorization: Bearer <MOYI Key> 鉴权,复用 CatalogService.authenticateKey 与 EnterprisePolicies.access(IP 白名单、过期)。不接受 URL 查询参数里的 Key。
  • 每个平台 Key 的并发 WebSocket 连接数设上限(默认 4,复用 Key 并发配置),超出时拒绝握手。

5.2 连接内的每一轮

  • 每个 response.create 视为一次独立的计费请求:走 GatewayRequestExecutionService.execute,独立准入、预留、续期、结算、用量记录。连接本身不预留费用。
  • 同一连接顺序执行:上一轮未结束时收到新的 response.create,返回 error 事件(code: response_in_progress),不排队,避免隐性占用资源。
  • 上游侧:每个客户端连接对应一个上游 WebSocket 连接,绑定首轮选中的账号。后续轮次固定使用该账号,不换号。上游连接断开时,本地也关闭客户端连接,并返回上游的错误码,让客户端按协议重连。
  • 首轮无 previous_response_id 时正常选号;首轮带 previous_response_id 时,按第 3.2 节归属选择上游账号。
  • 连接最长 60 分钟(与上游一致,可配置更短)。到期发送 websocket_connection_limit_reached 后关闭。

5.3 中断、取消与计费

情况 处理
客户端在一轮进行中断开 继续读取上游直至该轮完成并结算(与现有 SSE“浏览器断开不变成免费调用”一致),然后关闭上游连接
上游在一轮进行中断开 已有完整 response.completed 则结算;否则按现有规则 UPSTREAM_STREAM_INCOMPLETE,释放预留,记 cost_status='pending' 待核账
空闲(无进行中轮次)超时 关闭连接,无费用
服务重启 进行中轮次由预留过期恢复处理(COD-03 续期停止后最多 5 分钟释放或按已持久化用量结算)

5.4 部署前置条件

  • nginx 两处配置都要为 /v1/responses 增加 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";,读超时不低于连接上限。
  • 云端 Compose 透传 COD-03 的超时变量。
  • 这些都是线上配置变更,单独评审,不随代码自动生效。

6. 安全与滥用边界

  • 归属校验是访问控制:A 用户的响应 ID 对 B 用户统一表现为“不存在”。
  • 不接受客户端指定上游账号、Base URL、凭据(现有限制保留)。
  • previous_response_id 只作为字符串透传,长度限制并做字符集校验([A-Za-z0-9_-]),避免日志或 SQL 注入面。
  • WebSocket 单帧大小上限沿用 256 KiB 请求上限;超限关闭连接。

7. 测试与验收

自动化(本地,与现有门禁一起跑):

  • 归属:写入、过期、跨用户统一返回 previous_response_not_found、路由下线/指纹变化/冷却时 409 且不发上游请求。
  • pinned-key:只用指定 Key,不触发换号重试与备用路由。
  • HTTP 续接:上游桩返回带 id 的完成响应,第二轮带 previous_response_id 只打到同一 Key。
  • WebSocket:握手鉴权、顺序执行拒绝并发、客户端断开仍结算一次、上游中断释放预留、60 分钟上限(用可配置短时限测试)。
  • 依赖方向:gateway/responses 不依赖 HTTP 客户端与凭据。

客户端验收(需要你授权真实上游与付费调用,未授权前不做):

  • 指定 Codex CLI 版本,配置 MOYI 为 Responses 端点,跑一组固定任务:多轮工具调用、断线重连、超过 60 分钟的会话。
  • 每轮核对:上游账号一致、用量与扣费一致、续接失败时客户端能回退完整上下文。
  • 结果记录到兼容矩阵(客户端 × 协议 × 上游 × 能力),并保存日期与证据。

8. 恢复实施时的顺序

  1. Tair 归属记录(对齐 0.2),附回归。
  2. Provider 返回实际使用的账号,并支持按账号调用。
  3. WebSocket 入口与连接管理(0.1),每一轮接入现有计费合同。
  4. nginx 与云端 Compose 配置评审。
  5. 客户端验收(需授权真实上游与付费调用)。

每一步单独提交,全量测试通过后再进入下一步。

9. 已决定事项

见第 0 节:暂不实施;不允许上游存储;恢复时与 Sub2API 对齐,保留时间 1 小时,原账号不可用时按 Sub2API 换号并在连接内重放一次。

10. Sub2API 对照(2026-10-22 源码核对)

核对对象:Wei-Shaw/sub2api 主分支 dba770d5(2026-10-22),最新发布 v0.2.17。通过 GitHub API 读取以下文件,只读未复制代码(Sub2API 为 LGPL):backend/internal/service/openai_ws_state_store.go、openai_account_scheduler.go、openai_ws_forwarder*.go、openai_ws_forwarder_payload.go、backend/internal/handler/openai_gateway_handler.go、deploy/config.example.yaml。

10.1 归属记录与保留时间

  • 存储:response_id → account_id 与 response_id → (user_id, api_key_id) 存 Redis,Key 为 response_id 的 SHA-256,进程内另有热缓存(单表上限 65536 条,满了随机淘汰一条)。response_id → conn_id 只在进程内。按分组 ID 隔离。
  • 保留时间:sticky_response_id_ttl_seconds: 3600,即 1 小时,会话粘性 sticky_session_ttl_seconds 也是 1 小时。代码默认值同为 1 小时。
  • 读不到 Redis 时按“未命中”降级,不阻断请求。
  • 归属校验:HTTP 带 previous_response_id 时先校验用户与 Key,不匹配返回 400 previous_response_id is not available for this user。另外会拒绝看起来像消息 ID(msg_、item_ 等)的值。

与本设计的差异:我们用 PostgreSQL 表(原定 24 小时,已按此改为 1 小时);Sub2API 用 Redis、1 小时。Sub2API 不记录凭据版本。

10.2 原账号不可用时

  • 调度器先按 previous_response_id 找原账号;原账号不兼容(分组、模型、传输方式、被封禁、隔离等)时放弃粘连,按正常调度另选账号,请求照常发出,不直接报错。
  • 例外:输入里带 function_call_output 且上下文不能覆盖所有调用 ID 时,previous_response_id 视为不可迁移(previousResponseCanMove=false),只能走原账号。
  • HTTP 模式下 OAuth 订阅账号不支持 previous_response_id,会跳过这类账号,全部不行时返回 400。

10.3 续接失败的恢复

  • WebSocket 接入模式下,上游返回 previous_response_not_found 时,默认 ingress_previous_response_recovery_enabled: true:服务端去掉 previous_response_id,用自己保留的前几轮输入拼成完整上下文,重放一次。
  • 前提:这一轮还没向客户端写出内容;请求不含 function_call_output(否则上游会报找不到工具调用);每轮最多尝试一次。
  • 重放所需的历史输入只保存在该 WebSocket 连接的内存里,不落库,连接断开即丢失。所以重连后仍需客户端自己发完整上下文。
  • HTTP 模式没有这种服务端重放,失败直接返回错误。

10.4 WebSocket

  • 默认开启(openai_ws.enabled: true,协议特性 responses_websockets_v2: true),有全局回退 HTTP 的紧急开关 force_http。
  • 关键参数:每个 Key 最多 64 个客户端连接;两轮之间空闲 300 秒关闭;首条消息读取超时 30 秒;上游读超时 900 秒;每个上游账号最多 128 条连接、按账号并发 × 5 动态限制;store=false 且无可复用连接时默认强制新建连接(隔离优先);generate:false 预热默认关闭。
  • 有多种接入模式(ctx_pool 连接池、passthrough 直通、http_bridge 转成 HTTP 请求),实现规模大(WebSocket 相关源码超过 30 万字节)。
  • 部署文档未单独说明反向代理的 WebSocket 配置(未找到相关段落)。

10.5 对本设计三个问题的影响

问题 Sub2API 做法 建议
保留时间 Redis 1 小时 已改为默认 1 小时、可配置。上游 WebSocket 连接最长 60 分钟,store=false 下连接一断响应就找不到,保留更久意义不大
原账号不可用 换号重发(工具输出链路除外);WebSocket 内可用连接内存里的历史自动重放一次 保持 409、由客户端重发。我们 store=false,换号后上游一定找不到该响应,换号只会多一次失败请求;不保存正文也就无法服务端重放。若之后做 WebSocket,可考虑像 Sub2API 一样只在连接内存中保留本连接的历史,用于一次性重放
WebSocket 默认开启,功能完整但复杂度高 取决于是否允许 store=true(见第 4 节更正):不允许,则 WebSocket 是唯一的增量续接方式;允许,则可先做 HTTP 续接。Sub2API 的规模说明 WebSocket 是独立的一大块工作

注:本节依据源码阅读,没有部署 Sub2API 或实测其行为。表中“建议”一列是对齐决定之前的看法,已被第 0 节取代。

11. 备选想法(未采纳,留档)

以下是对齐 Sub2API 之前的设计思路,保留供以后企业化或合规需要时参考:

  • PostgreSQL 归属表:比 Redis 更利于审计追溯(第 3.1 节字段),代价是写库压力。若日后客户要求“每个响应可追溯到上游账号”,可在 Tair 之外异步落库。
  • 凭据版本:把渠道凭据版本记入归属,凭据替换后旧响应立即失效(第 3.3 节)。Sub2API 不做这一层。
  • 原账号不可用时 409、不换号:在 store=false 下换号必然得到 previous_response_not_found,直接让客户端重发完整上下文可以少一次上游请求。对齐后改为 Sub2API 的“换号 + 连接内重放一次”,效果相近,但多一次失败的上游请求。
  • 按 Key 开启 store=true 的 HTTP 续接:实现最简单,但用户对话会保存在上游服务商处(OpenAI 默认 30 天),需要在条款和隐私说明中告知。本阶段已决定不允许。