Files
moyi-model-intelligence-hub/docs/30-codex-responses-continuation-design.md
T
2026-10-22 16:13:00 +08:00

169 lines
13 KiB
Markdown
Raw 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)。状态:**设计待评审,未实现**。对应 24 号任务表 COD-01、COD-02,承接 29 号文档第五节与第八节第二阶段。
## 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` | 默认保留 24 小时,到期由定时任务清理 |
不存储请求或响应正文。只存路由与账号指纹,满足“可追溯但不留内容”。
### 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,先做)
改动点:
1. `NativeProtocolMeter.request`:允许 `previous_response_id`(字符串,1–128 字符);继续拒绝 `conversation`、`background`、媒体与托管工具;继续强制 `store=false`。
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. V51 归属表与 `ResponsesOwnershipService`,附单元与数据库回归。
2. Provider 返回实际账号指纹与 pinned-key 入口。
3. HTTP 续接放开与路由固定(COD-01 主体)。
4. WebSocket 入口与连接管理(COD-02)。
5. 部署配置评审与客户端验收。
每一步单独提交,全量测试通过后再进入下一步。
## 9. 待你确认
1. 归属记录默认保留 24 小时是否合适(越长越占库,越短越容易让长会话回退完整上下文)。
2. 归属账号不可用时直接返回 409、由客户端重发完整上下文,而不是服务端自动重放历史。服务端不保存正文,所以无法自动重放,这是设计取舍。
3. 是否需要 WebSocket。只做 HTTP 续接(第 1–3 步)已经能让 Codex 增量续接,WebSocket 主要节省延迟,代价是代理配置和连接管理。