Files
moyi-model-intelligence-hub/docs/30-codex-responses-continuation-design.md
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

264 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](https://github.com/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 天),需要在条款和隐私说明中告知。本阶段已决定不允许。