docs(tasks): refine custom gateway product suite plan
This commit is contained in:
chengma
+39
-48
@@ -1,68 +1,61 @@
|
||||
---
|
||||
id: T-678
|
||||
title: 自定义网关锁定 OpenAI 图片接口规范并支持多图输入
|
||||
title: 自定义网关图片模型锁定 OpenAI 图片编辑接口并支持多图输入
|
||||
phase: 7
|
||||
deps: [T-677]
|
||||
status: TODO
|
||||
created: 2026-07-20
|
||||
---
|
||||
|
||||
# T-678 自定义网关锁定 OpenAI 图片接口规范并支持多图输入
|
||||
# T-678 自定义网关图片模型锁定 OpenAI 图片编辑接口并支持多图输入
|
||||
|
||||
## 问题 / 背景
|
||||
|
||||
T-677 把⑤的自定义网关（`ai.backend=direct`）重新放出来后，暴露了 direct 生图路径的两个结构问题。
|
||||
T-677 恢复了⑤的自定义网关（`ai.backend=direct`）。当前 `api_type` 同时用于文字与图片模型：文字模型需要 `chat/completions`，而图片模型的 `chat` / `auto` 分支则依赖非标准聚合网关把图片塞进对话响应。将 `appconfig.API_TYPES` 全局收敛成单一值会直接破坏自定义网关生文，因此必须按模型类别收敛。
|
||||
|
||||
**当前的 `chat` 接口类型并不是 OpenAI 规范。** 标准 OpenAI 的 `chat/completions` 不返回生成的图片。本项目的 chat 生图之所以能工作，是因为 `_find_image_ref()`（`app/ai.py:2667`）是一个非常宽容的递归搜刮器，会在 `choices`、`message`、`content`、`data`、`images`、`files` 等结构里到处寻找 `b64_json` / `image_base64` / `url`。这套逻辑是为把生成图塞进 chat 响应的**非标准中转聚合网关**准备的。`api_type=auto` 同样不做接口探测，`chat` 与 `auto` 实际走同一条对话请求，T-677 只能在 UI 上写一段"自动不会探测接口"的说明来遮盖这个事实。
|
||||
当前 direct 图片编辑也只能提交单张图：`_image_edit_body()` 的 `files` 是单键字典，`_multipart_body()` 不能表达重复字段。商品套图需要按顺序提交“主体图 + 参考图”，其前置能力应在本任务完成。
|
||||
|
||||
**direct 只能提交单张输入图。** `_image_chat_payload()`（`app/ai.py:2557`）的 `content` 数组只放一个 `image_url`；`_image_edit_body()`（`app/ai.py:2569`）的 `files` 是字典且只有一个 `"image"` 键，`_multipart_body()` 按字典遍历，结构上无法发送重复字段名。因此 T-679 要让商品套图在自定义网关下使用「主图 + 参考图」时，无法复用现有请求构造。
|
||||
|
||||
**本任务存在时间窗口，晚做代价显著上升。** T-529 之后⑤的自定义模型 UI 被 `_on_backend_changed()` 无条件 `setVisible(False)` 硬藏，普通用户没有入口配置 `chat` 类型模型；该入口在 T-677（2026-07-20）才重新放出。因此当前装机量中几乎不存在可用的 `chat`/`auto` 直连配置，收敛接口规范的迁移成本接近于零。等 T-677 上线一段时间、用户配出一批 chat 模型后再收敛，就会变成真正的破坏性变更。
|
||||
本任务锁定的外部契约是 OpenAI Image API 的图片编辑接口：`POST /v1/images/edits`、multipart 重复 `image[]` 文件字段、响应从 `data[0].b64_json` 或 `data[0].url` 读取。第一张为主体图是本项目的业务约定；OpenAI 文档只明确多图及遮罩作用于首图，不能据此声称模型一定保持主体一致性。
|
||||
|
||||
## 方案
|
||||
|
||||
### 1. 接口规范收敛
|
||||
### 1. 按类别收敛模型接口
|
||||
|
||||
- 自定义网关只支持 OpenAI 图片编辑接口（`/v1/images/edits` 形式的 multipart 请求）。`appconfig.API_TYPES`（`app/appconfig.py:41`）由 `{"chat", "images_edits", "auto"}` 收敛为单一取值。
|
||||
- 实现前必须按当前 OpenAI 官方文档核实多图输入字段名与模型支持范围（预期为 `image[]` 配合 `gpt-image-1`），并把核实结果与文档版本写入执行记录。**文档与实现不一致时不得猜字段**，按 T-596 既有约定停下并记录缺口。
|
||||
- 删除 `_image_chat_payload()`（`app/ai.py:2557`）及其在 `gen_cover` 中的分支（`app/ai.py:348-386`）。
|
||||
- `_find_image_ref()`（`app/ai.py:2667`）收敛为按标准响应结构取图（`data[].b64_json` / `data[].url`），不再跨 `choices`/`message`/`content` 递归搜刮。保留 data URL 与 base64 的解码分支和 `_download_image()` 回退。
|
||||
- 保留全局 `API_TYPES = {"chat", "images_edits", "auto"}`，避免影响 `category=text` 的既有生文请求。
|
||||
- 新增“图片编辑能力”校验：仅 `category=image` 且 `api_type=images_edits` 的模型可用于②生成封面与后续⑥商品套图；文字模型保持既有 `chat` / `auto` 行为。
|
||||
- 图片模型的 `chat` / `auto` 存量配置原样保存、可查看，但在⑤显示“当前图片模型不支持 OpenAI 图片编辑接口”的中文状态，并在②、⑥预检中阻止提交。不得静默迁移、禁用或删除，避免触发“至少一个 image 模型启用”的既有校验冲突。
|
||||
- ⑤根据模型类别展示接口类型：文字模型保留现有可选项；图片模型只允许选择并显示“OpenAI 图片编辑接口”。不再以全局文案宣称 `chat/completions` 永远不能生成图片，而是说明其不符合本项目锁定的图片编辑响应契约。
|
||||
|
||||
### 2. 多图输入能力
|
||||
### 2. 图片编辑请求与响应契约
|
||||
|
||||
- `_image_edit_body()` 接受有序图片路径列表而不是单个路径：第一张为主体图，其余为参考图，按核实后的字段名发送。
|
||||
- `_multipart_body()`（`app/ai.py:2586`）的 `files` 由字典改为有序序列，支持同名重复字段。
|
||||
- 保留单图调用形式：②生成封面继续只发一张图，请求形式收敛但**行为不变**，不得因本任务改变②的生图结果口径或计费口径。
|
||||
- 本任务只提供多图能力，**不改商品套图**；套图接入由 T-679 完成。
|
||||
- 删除 direct 图片生成的 `_image_chat_payload()` 分支；`category=image` 的 direct 请求一律走 `/v1/images/edits` multipart，文字请求不在本任务范围内。
|
||||
- `_image_edit_body()` 接受有序本地路径序列；multipart 用重复的 `image[]` 字段提交，首项为主体图，其余为参考图。保留单图入口，②仍只提交一张图。
|
||||
- 请求体固定一张输出（`n=1`）；套图数量仍由“一个 job 一次请求”表达，不能让一次响应内的多图破坏单 job 历史、重试与计费语义。
|
||||
- `_find_image_ref()` 收敛为只读取标准 `data` 数组中的 `b64_json` / `url`。保留合法 data URL、base64 和 HTTP(S) URL 下载分支；非标准响应必须给出中文错误，不能递归猜测 `choices`、`message` 等字段。
|
||||
- 继续使用现有 URL 安全校验；不得因兼容自定义网关放开 `file:`、本地路径或其他非 HTTP(S) 返回地址。
|
||||
|
||||
### 3. 存量配置迁移
|
||||
### 3. 配置、预检与回归
|
||||
|
||||
- `ai_models.json` 中 `api_type` 为 `chat` 或 `auto` 的存量模型不得静默改写为新取值——请求形式不同，静默迁移会让用户在不知情的情况下把请求打到不支持的端点。
|
||||
- 载入时把这类模型标记为不可用，在⑤模型列表中以中文说明其原因（如「接口类型已不再支持，请改为 OpenAI 图片编辑接口并确认服务商支持」），并在②的自定义网关预检中作为"去⑤补齐"的一种原因。
|
||||
- 沿用 v3.1 约定：允许先保存不完整或不可用配置，不在切换来源或保存时弹阻断式校验。
|
||||
|
||||
### 4. ⑤ UI 与文案
|
||||
|
||||
- 移除或降级 T-677 新增的「接口类型」下拉：只剩一种取值时不应继续以可选控件呈现。同步删除 T-677 为 `auto` 写的"不会探测接口"帮助文案。
|
||||
- ⑤自定义面板补充说明：自定义网关只支持 OpenAI 图片编辑接口，只做 chat 生图的中转聚合服务不可用。文案不得暴露内部实现细节或密钥。
|
||||
- 保留既有 `objectName`、配置键、日志字段和 `app/ai.py` 中文错误消息中的 `cmhub` 字样（沿用 T-677 第 5 节边界）。
|
||||
- 使用图片模型前，预检同时检查启用状态、`images_edits` 接口类型、URL、模型名、密钥和超时；错误只给中文可操作说明，不暴露密钥、完整上游 URL 或原始响应体。
|
||||
- ②已有的重试、并发、日志、“自定义网关不计点数”口径不变；本任务不改变默认网关及其 cmhub 生图路径。
|
||||
- 在执行记录中记录 OpenAI 官方文档核实日期、`image[]` 字段、标准响应字段和支持的尺寸范围；外部兼容服务若不满足该契约，第一版明确不支持，不做自动探测或私有适配。
|
||||
|
||||
## 验收要点
|
||||
|
||||
- [ ] `API_TYPES` 只剩 OpenAI 图片编辑接口一种取值；`chat` 与 `auto` 的请求构造代码已删除，不留死分支。
|
||||
- [ ] `_find_image_ref()` 只按标准响应结构取图，不再跨 `choices`/`message` 搜刮；非标准响应给出可读中文错误而不是静默取错字段。
|
||||
- [ ] `_image_edit_body()` 与 `_multipart_body()` 支持有序多图，第一张为主体图；单图调用路径行为不变。
|
||||
- [ ] ②自定义网关生成封面的结果、重试、并发、日志和"不计点数"文案不回归。
|
||||
- [ ] 存量 `chat`/`auto` 模型不被静默改写，在⑤显示不可用原因，在②预检中作为补齐提示出现。
|
||||
- [ ] ⑤不再显示多取值的接口类型控件与 `auto` 帮助文案；新增的规范限制说明为中文且不暴露实现细节。
|
||||
- [ ] 默认网关（cmhub）的生文、生图、图片理解、异步 submit/poll、幂等键、计费与③更新蝦皮全部不受影响。
|
||||
- [ ] 自定义网关文字模型仍可走原有 `chat` / `auto` 生文路径；全局 `API_TYPES` 未被收窄。
|
||||
- [ ] `category=image` 仅在 `api_type=images_edits` 时可提交图片生成；存量 `chat` / `auto` 图片模型保留且不被静默改写。
|
||||
- [ ] multipart 使用有序重复 `image[]` 字段；单图与多图均有字段、顺序与首图主体的单元测试。
|
||||
- [ ] 图片响应仅接受 `data[].b64_json` / `data[].url`；非标准响应有可读中文错误，非法 URL 不会下载。
|
||||
- [ ] ②单图生成的结果、重试、并发、日志和不计点数口径不回归。
|
||||
- [ ] ⑤的图片模型限制和②预检均为中文，不泄露密钥、完整上游 URL 或原始响应体。
|
||||
- [ ] 默认网关的生文、生图、图片理解、异步 submit/poll、幂等键、计费与③更新蝦皮不受影响。
|
||||
|
||||
## 测试与文档
|
||||
|
||||
- `tests/test_ai.py`：现有 4 处 `api_type` 断言（:63、:75、:307、:348）改为新规范；新增多图请求体断言（字段名、顺序、主体图在首位）与非标准响应的错误路径。
|
||||
- `tests/test_appconfig.py`：现有 10 处 `api_type` 断言（:542 起）改为新取值；补存量 `chat`/`auto` 模型载入后标记不可用且不被改写的用例。
|
||||
- `tests/test_gui.py`：⑤接口类型控件移除、不可用模型的中文提示、②预检把不可用模型作为补齐原因。
|
||||
- 更新 `docs/cmhub-integration-design.md` 修订说明（T-677 有限放开 direct，本任务进一步把 direct 收敛到 OpenAI 规范）、`docs/routes.md`、`docs/api.md`。
|
||||
- `tests/test_ai.py`：文字 `chat` / `auto` 回归、图片 `images_edits` 单图与多图 `image[]` 请求、`n=1`、标准响应和非法/非标准响应错误路径。
|
||||
- `tests/test_appconfig.py`：按类别的可用性校验、存量 `chat` / `auto` 图片模型不被改写、文字模型保存与加载不回归。
|
||||
- `tests/test_gui.py`：⑤按类别显示接口类型、②预检拦截不可用图片模型且文案中文。
|
||||
- 更新 `docs/cmhub-integration-design.md`、`docs/routes.md`、`docs/api.md`，标明图片编辑的固定契约和 T-679 的依赖关系。
|
||||
|
||||
## 验证
|
||||
|
||||
@@ -76,20 +69,18 @@ git diff --check
|
||||
|
||||
## 边界（不改什么）
|
||||
|
||||
- 不改商品套图（`app/image_studio_generation.py`）与图片理解（`analyze_product_images()`），套图接入见 T-679。
|
||||
- 不新增 vision 类别，`appconfig.CATEGORIES` 保持 `{"text", "image"}`；⑥「AI 帮写」在自定义网关下继续不可用。
|
||||
- 不改 cmhub 的请求协议、重试与超时策略、异步 submit/poll 状态机、幂等键、预扣退点账本。
|
||||
- 不新增 provider 适配、接口自动探测或任意上游 URL 放行。
|
||||
- 不改商品套图；其接入拆分为 T-679a、T-679b、T-679c，由 T-679 集成验收。
|
||||
- 不新增 provider 私有适配、接口自动探测、任意 URL 放行或图片理解的自定义网关路径。
|
||||
- 不改 SQLite schema、Chrome/CDP、Excel 回写、蝦皮更新流程。
|
||||
- 不解除 T-596 的 BYOK 门禁；本任务仍属 direct 过渡形态范围内。
|
||||
- 不改 cmhub 的请求协议、重试与超时策略、异步 submit/poll 状态机、幂等键、预扣退点账本。
|
||||
- 不解除 T-596 的 BYOK 门禁；本任务仍属客户端直连的过渡形态。
|
||||
|
||||
## 关联
|
||||
|
||||
- T-677：⑤生成网关来源切换（本任务收敛其放出的 direct 接口形态）。
|
||||
- T-679：商品套图接入自定义网关（依赖本任务的多图能力）。
|
||||
- T-529：默认 cmhub 网关并隐藏 AI 后端选择（其隐藏期造就了本任务的低成本迁移窗口）。
|
||||
- T-596：BYOK 总设计与启动门禁（`status: BLOCKED`；正式形态仍要求经 cmhub 代理，本任务不解除该门禁）。
|
||||
- T-677：⑤生成网关来源切换。
|
||||
- T-679a：套图多来源任务状态机，依赖本任务的多图请求能力。
|
||||
- T-596：BYOK 总设计与启动门禁。
|
||||
|
||||
## 执行记录
|
||||
|
||||
（做完在这里写：改了什么文件、跑了什么验证命令及结果、遇到的阻塞、关键决策；务必记录 OpenAI 多图字段名的核实来源与文档日期。）
|
||||
（做完在这里写：改了什么文件、跑了什么验证命令及结果、官方接口契约核实来源与日期、遇到的阻塞和关键决策。）
|
||||
|
||||
Reference in New Issue
Block a user