87 lines
6.3 KiB
Markdown
87 lines
6.3 KiB
Markdown
---
|
|
id: T-678
|
|
title: 自定义网关图片模型锁定 OpenAI 图片编辑接口并支持多图输入
|
|
phase: 7
|
|
deps: [T-677]
|
|
status: TODO
|
|
created: 2026-07-20
|
|
---
|
|
|
|
# T-678 自定义网关图片模型锁定 OpenAI 图片编辑接口并支持多图输入
|
|
|
|
## 问题 / 背景
|
|
|
|
T-677 恢复了⑤的自定义网关（`ai.backend=direct`）。当前 `api_type` 同时用于文字与图片模型：文字模型需要 `chat/completions`，而图片模型的 `chat` / `auto` 分支则依赖非标准聚合网关把图片塞进对话响应。将 `appconfig.API_TYPES` 全局收敛成单一值会直接破坏自定义网关生文，因此必须按模型类别收敛。
|
|
|
|
当前 direct 图片编辑也只能提交单张图：`_image_edit_body()` 的 `files` 是单键字典，`_multipart_body()` 不能表达重复字段。商品套图需要按顺序提交“主体图 + 参考图”，其前置能力应在本任务完成。
|
|
|
|
本任务锁定的外部契约是 OpenAI Image API 的图片编辑接口：`POST /v1/images/edits`、multipart 重复 `image[]` 文件字段、响应从 `data[0].b64_json` 或 `data[0].url` 读取。第一张为主体图是本项目的业务约定；OpenAI 文档只明确多图及遮罩作用于首图，不能据此声称模型一定保持主体一致性。
|
|
|
|
## 方案
|
|
|
|
### 1. 按类别收敛模型接口
|
|
|
|
- 保留全局 `API_TYPES = {"chat", "images_edits", "auto"}`，避免影响 `category=text` 的既有生文请求。
|
|
- 新增“图片编辑能力”校验：仅 `category=image` 且 `api_type=images_edits` 的模型可用于②生成封面与后续⑥商品套图；文字模型保持既有 `chat` / `auto` 行为。
|
|
- 图片模型的 `chat` / `auto` 存量配置原样保存、可查看，但在⑤显示“当前图片模型不支持 OpenAI 图片编辑接口”的中文状态，并在②、⑥预检中阻止提交。不得静默迁移、禁用或删除，避免触发“至少一个 image 模型启用”的既有校验冲突。
|
|
- ⑤根据模型类别展示接口类型：文字模型保留现有可选项；图片模型只允许选择并显示“OpenAI 图片编辑接口”。不再以全局文案宣称 `chat/completions` 永远不能生成图片，而是说明其不符合本项目锁定的图片编辑响应契约。
|
|
|
|
### 2. 图片编辑请求与响应契约
|
|
|
|
- 删除 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. 配置、预检与回归
|
|
|
|
- 使用图片模型前，预检同时检查启用状态、`images_edits` 接口类型、URL、模型名、密钥和超时；错误只给中文可操作说明，不暴露密钥、完整上游 URL 或原始响应体。
|
|
- ②已有的重试、并发、日志、“自定义网关不计点数”口径不变；本任务不改变默认网关及其 cmhub 生图路径。
|
|
- 在执行记录中记录 OpenAI 官方文档核实日期、`image[]` 字段、标准响应字段和支持的尺寸范围；外部兼容服务若不满足该契约，第一版明确不支持，不做自动探测或私有适配。
|
|
|
|
## 验收要点
|
|
|
|
- [ ] 自定义网关文字模型仍可走原有 `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`：文字 `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 的依赖关系。
|
|
|
|
## 验证
|
|
|
|
```bash
|
|
py -3.10 -m unittest tests.test_ai tests.test_appconfig tests.test_gui
|
|
py -3.10 -m unittest discover -s tests
|
|
py -3.10 -m ruff check app tests main.py
|
|
py -3.10 -m compileall app main.py
|
|
git diff --check
|
|
```
|
|
|
|
## 边界（不改什么）
|
|
|
|
- 不改商品套图；其接入拆分为 T-679a、T-679b、T-679c，由 T-679 集成验收。
|
|
- 不新增 provider 私有适配、接口自动探测、任意 URL 放行或图片理解的自定义网关路径。
|
|
- 不改 SQLite schema、Chrome/CDP、Excel 回写、蝦皮更新流程。
|
|
- 不改 cmhub 的请求协议、重试与超时策略、异步 submit/poll 状态机、幂等键、预扣退点账本。
|
|
- 不解除 T-596 的 BYOK 门禁；本任务仍属客户端直连的过渡形态。
|
|
|
|
## 关联
|
|
|
|
- T-677：⑤生成网关来源切换。
|
|
- T-679a：套图多来源任务状态机，依赖本任务的多图请求能力。
|
|
- T-596：BYOK 总设计与启动门禁。
|
|
|
|
## 执行记录
|
|
|
|
（做完在这里写：改了什么文件、跑了什么验证命令及结果、官方接口契约核实来源与日期、遇到的阻塞和关键决策。）
|