docs:"记录 COD-01/02 暂缓、不存储对话与 Sub2API 对齐决定"
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
4b6bdeeef6
commit
bb3baed095
2 files changed
+59
-17
No files matched your search
@@ -1,6 +1,44 @@
|
||||
# Codex 兼容:Responses 续接归属与 WebSocket 设计(COD-01/COD-02)
|
||||
|
||||
日期:2026-10-22(Asia/Shanghai)。状态:**设计待评审,未实现**。对应 24 号任务表 COD-01、COD-02,承接 29 号文档第五节与第八节第二阶段。
|
||||
日期: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. 目标与非目标
|
||||
|
||||
@@ -158,24 +196,19 @@
|
||||
- 每轮核对:上游账号一致、用量与扣费一致、续接失败时客户端能回退完整上下文。
|
||||
- 结果记录到兼容矩阵(客户端 × 协议 × 上游 × 能力),并保存日期与证据。
|
||||
|
||||
## 8. 实施顺序
|
||||
## 8. 恢复实施时的顺序
|
||||
|
||||
1. V51 归属表与 `ResponsesOwnershipService`,附单元与数据库回归。
|
||||
2. Provider 返回实际账号指纹与 pinned-key 入口。
|
||||
3. 按第 9 节的决定二选一:
|
||||
- 保持 `store=false`:做 WebSocket 入口与连接管理(COD-02),增量续接只在连接内有效;HTTP 继续拒绝 `previous_response_id`。
|
||||
- 允许 `store=true`:先放开 HTTP 续接与路由固定(COD-01),WebSocket 之后再做。
|
||||
4. 部署配置评审(WebSocket 需改 nginx)与客户端验收。
|
||||
1. Tair 归属记录(对齐 0.2),附回归。
|
||||
2. Provider 返回实际使用的账号,并支持按账号调用。
|
||||
3. WebSocket 入口与连接管理(0.1),每一轮接入现有计费合同。
|
||||
4. nginx 与云端 Compose 配置评审。
|
||||
5. 客户端验收(需授权真实上游与付费调用)。
|
||||
|
||||
每一步单独提交,全量测试通过后再进入下一步。
|
||||
|
||||
## 9. 待你确认
|
||||
## 9. 已决定事项
|
||||
|
||||
(2026-10-22 按第 10 节 Sub2API 对照修订)
|
||||
|
||||
1. **是否允许上游存储(`store=true`)**。这是最先要定的:不允许,则增量续接只能走 WebSocket;允许,则 HTTP 续接可用,但用户对话会存在上游服务商处,需告知并按用户或 Key 开启。
|
||||
2. 归属记录默认保留 1 小时,可配置。
|
||||
3. 原账号不可用时返回 409、由客户端重发完整上下文,不换号。若做 WebSocket,可在连接内存中保留本连接历史,用于一次性服务端重放(参考 Sub2API)。
|
||||
见第 0 节:暂不实施;不允许上游存储;恢复时与 Sub2API 对齐,保留时间 1 小时,原账号不可用时按 Sub2API 换号并在连接内重放一次。
|
||||
|
||||
## 10. Sub2API 对照(2026-10-22 源码核对)
|
||||
|
||||
@@ -218,4 +251,13 @@
|
||||
| 原账号不可用 | 换号重发(工具输出链路除外);WebSocket 内可用连接内存里的历史自动重放一次 | 保持 **409、由客户端重发**。我们 `store=false`,换号后上游一定找不到该响应,换号只会多一次失败请求;不保存正文也就无法服务端重放。若之后做 WebSocket,可考虑像 Sub2API 一样只在连接内存中保留本连接的历史,用于一次性重放 |
|
||||
| WebSocket | 默认开启,功能完整但复杂度高 | 取决于是否允许 `store=true`(见第 4 节更正):不允许,则 WebSocket 是唯一的增量续接方式;允许,则可先做 HTTP 续接。Sub2API 的规模说明 WebSocket 是独立的一大块工作 |
|
||||
|
||||
注:本节依据源码阅读,没有部署 Sub2API 或实测其行为。
|
||||
注:本节依据源码阅读,没有部署 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 天),需要在条款和隐私说明中告知。本阶段已决定不允许。
|
||||
Reference in new issue
Block a user