diff --git a/docs/README.md b/docs/README.md index 789996d..9e21409 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,6 +22,7 @@ - [模块 / CLI 合约](api.md)：本地模块接口、Chrome 启动参数、账号配置 schema。 - [界面与流程结构](routes.md)：GUI 窗口、操作流程、按钮职责（无前端路由，用 GUI 流程替代）。 - [AI工场端到端验收](ai-studio-e2e-checklist.md)：⑥ AI工场 cmhub 托管主线的自动化覆盖、人工只读验收和发布检查。 +- [AI工场托管模型评测与默认档位策略](ai-studio-model-evaluation.md)：OpenAI / GPT 托管能力经 cmhub 别名落地前的评测样本、档位策略、上线门槛与运营用法。 - [当前实现状态](current-state.md)：当前代码现实、可运行命令、下一步可做任务。 - [常见问题排查](troubleshooting.md)：本地配置、启动报错、敏感文件修复等排障记录。 - [产品与 UI 评估](ux-review.md)：以 PM + UI 设计视角评估主流程模块 / 组件合理性，含优化方案与优先级清单。 diff --git a/docs/ai-studio-model-evaluation.md b/docs/ai-studio-model-evaluation.md new file mode 100644 index 0000000..2b4f62b --- /dev/null +++ b/docs/ai-studio-model-evaluation.md @@ -0,0 +1,87 @@ +# AI工场托管模型评测与默认档位策略 + +> 任务来源：T-597。本文是 AI工场从“cmhub 当前默认托管模型”评估切换到 OpenAI / GPT 系列托管能力时的选型说明与评测模板。本文不代表已经执行付费真实样本测试；真实结论必须由运营样本跑数后补充。 + +## 资料来源 + +- OpenAI Model guidance：`https://developers.openai.com/api/docs/guides/latest-model` +- OpenAI Image generation：`https://developers.openai.com/api/docs/guides/image-generation` +- 核对日期：2026-07-11 + +官方文档当前把 GPT-5.6 家族分成 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`，分别对应旗舰能力、能力与成本平衡、高频低成本任务；`gpt-5.6` alias 指向 `gpt-5.6-sol`。图片方向可参考 GPT Image 能力，尤其 `gpt-image-2`，但落地到本项目时仍由 cmhub 暴露能力别名，客户端不得保存 OpenAI 原始 Key 或把 OpenAI slug 当执行事实。 + +## 产品原则 + +- 普通用户只看到“cmhub 托管模型 / 默认档 / 高质量档 / 省点档 / 扣点成本”，不暴露 Provider URL、OpenAI API Key、上游接口路径或内部请求体。 +- cmshopee 客户端只保存 cmhub 返回的 `title_alias` / `image_alias`，不把 `gpt-5.6-*`、`gpt-image-*` 写成强执行配置。 +- 默认档必须以真实商品样本的一次通过率、平均耗时、P95 耗时和扣点成本决定；未跑样本前不得因为模型名更强就替换默认。 +- 图片生成是高成本能力，推荐默认走“平衡档”，重点商品/失败重试才用“高质量档”，低价值 SKU 初稿才用“省点档”。 + +## 推荐档位 + +| 档位 | 文本/提示词辅助建议 | 图片生成/编辑建议 | 使用场景 | 默认策略 | +| --- | --- | --- | --- | --- | +| 默认档 | cmhub 平衡文本别名，后台可映射 `gpt-5.6-terra` 或等价能力 | cmhub 平衡图像别名，后台可映射 `gpt-image-2` 或当前稳定图像能力 | 日常批量主图/详情图候选、提示词改写、标题/卖点辅助 | 真实样本通过率不低于当前默认模型且扣点可接受后，才设为默认 | +| 高质量档 | cmhub 高质量文本别名，后台可映射 `gpt-5.6-sol` 或等价能力 | cmhub 高质量图像别名，优先用于重点商品、复杂背景、失败重试 | 高毛利 SKU、广告款、默认档失败后重试 | 不作为全局默认，避免成本失控 | +| 省点档 | cmhub 省点文本别名，后台可映射 `gpt-5.6-luna` 或等价能力 | cmhub 省点图像别名，只用于低价值 SKU 初稿或批量探索 | 大批量草稿、运营快速预览 | 不建议直接作为最终主图默认档 | + +## 评测样本集 + +真实评测建议建立 `STUDIO-EVAL-YYYYMMDD` 样本包，至少 20～30 个商品，覆盖以下类型。样本文件和真实商品图属于业务数据，不提交 Git。 + +| 样本组 | 数量 | 商品类型 | 旧图特征 | 重点观察 | +| --- | ---: | --- | --- | --- | +| A | 5 | 服饰/配件 | 模特图、材质细节、颜色差异明显 | 主体保真、颜色不漂、服饰结构不乱 | +| B | 5 | 生活用品 | 白底主图、多个小件组合 | 主体数量不变、边缘干净、白底合规 | +| C | 5 | 美妆/个护 | 包装文字、瓶身反光、细节图 | 不乱写品牌/文字、包装比例稳定 | +| D | 5 | 小物/工具 | 尺寸小、部件多、背景杂 | 细节不丢、构图清楚、可商用感 | +| E | 5 | 详情图/信息图 | 文字多、说明块多、版式复杂 | 文字处理是否可接受，是否需要转人工 | +| F | 5 | 失败回归样本 | 当前模型曾失败或效果差 | 新档位是否显著改善 | + +## 评分口径 + +每张候选图按 1～5 分打分，4 分以上才算“一次通过”。标题/提示词辅助按“可直接使用 / 需轻改 / 不可用”记录。 + +| 指标 | 说明 | 权重 | +| --- | --- | ---: | +| 商品主体保真 | 主体形状、数量、颜色、关键细节是否保持 | 25% | +| 商用感 | 是否像可上线主图/详情图，光影、背景、清晰度是否专业 | 20% | +| 主图合规 | 白底/构图/主体占比/无多余元素是否符合运营要求 | 15% | +| 少幻觉 | 不添加不存在的配件、文字、Logo 或错误卖点 | 15% | +| 文字稳定 | 包装文字、详情图文字是否可接受；文字多的图允许标记需人工 | 10% | +| 耗时 | 平均耗时、P95 耗时，是否影响批量生产节奏 | 10% | +| 成本 | 单图扣点、一次通过成本、失败重试成本 | 5% | + +## 上线门槛 + +- 默认档候选的一次通过率必须不低于当前 cmhub 默认图像模型；若提升小于 5%，不建议仅因模型名切换默认。 +- 平均耗时不超过当前默认模型 20%，P95 耗时不超过运营可接受阈值；超出时只放高质量档或重点商品档。 +- 单图扣点上涨时，必须用“一次通过成本”判断：如果质量提升减少重试，才可接受更高单次成本。 +- 文本辅助默认优先平衡档；高质量档只用于复杂商品、失败原因分析、重点 SKU 复核。 +- `gpt-image-2` 或等价高质量图像别名如果文字/包装稳定性仍不满足详情图要求，详情图文字密集场景必须保留人工复核。 + +## 当前建议 + +在没有真实样本跑数前，AI工场默认仍保持当前 cmhub 托管图像别名，不直接切换。T-598 可以先把 UI 和日志口径收口成“默认 / 高质量 / 省点”档位提示，并继续以 cmhub `/models` 返回的别名、展示名、能力标签和扣点作为真实执行依据。 + +建议第一轮真实评测结果这样填写： + +| 日期 | 样本包 | cmhub 别名 | 后台能力 | 一次通过率 | 平均耗时 | P95耗时 | 平均扣点 | 结论 | +| --- | --- | --- | --- | ---: | ---: | ---: | ---: | --- | +| 待补 | STUDIO-EVAL-YYYYMMDD | 当前默认图像别名 | 当前 cmhub 默认 | 待补 | 待补 | 待补 | 待补 | 对照组 | +| 待补 | STUDIO-EVAL-YYYYMMDD | 平衡图像别名 | GPT Image 等价能力 | 待补 | 待补 | 待补 | 待补 | 候选默认档 | +| 待补 | STUDIO-EVAL-YYYYMMDD | 高质量图像别名 | GPT Image 高质量能力 | 待补 | 待补 | 待补 | 待补 | 重点商品/重试 | +| 待补 | STUDIO-EVAL-YYYYMMDD | 省点图像别名 | 低成本图像能力 | 待补 | 待补 | 待补 | 待补 | 初稿/低价值 SKU | + +## 给运营的用法说明 + +- 默认档：日常批量先用它，目标是“成本可控、稳定可用”。 +- 高质量档：用于重点商品、默认档失败后的第二次生成、复杂背景或需要更强保真的商品。 +- 省点档：用于低价值 SKU、灵感草稿或大批量初筛；上线前仍要人工看图。 +- 失败重试是否换档：如果失败原因是主体变形、文字乱、构图不合规，优先换高质量档；如果失败原因是网络、下载、上游任务超时，不应换模型，应继续查询或重试原任务。 + +## 客户端落地边界 + +- T-598 只做档位展示和日志口径，不新增 BYOK、自定义 Provider 或 OpenAI Key UI。 +- cmhub 后台可以调整档位对应的真实模型；客户端不需要发版即可承接。 +- 日志只写“cmhub 托管高质量档 / 扣点 / call_id / task_id”等业务可读字段，不写上游接口路径、Authorization、OpenAI API Key、完整 prompt 或请求体。 diff --git a/docs/tasks/T-597.md b/docs/tasks/T-597.md index 3b3cf26..4176410 100644 --- a/docs/tasks/T-597.md +++ b/docs/tasks/T-597.md @@ -3,7 +3,7 @@ id: T-597 title: AI工场 GPT / OpenAI 托管模型选型评测与默认档位策略 phase: 8 deps: [T-595] -status: TODO +status: DONE created: 2026-07-11 --- @@ -11,7 +11,7 @@ created: 2026-07-11 T-586～T-595 固定使用 cmhub 托管生图模型，不接入自定义 Provider。AI工场主线完成后，如果要让 cmhub 后台切到 OpenAI / GPT 系列模型，不能只凭模型名直接上线，需要先建立运营可理解的质量、速度、成本评测口径。 -当前官方模型指导中，GPT-5.6 家族分为偏旗舰能力的 `gpt-5.6-sol`、平衡能力与成本的 `gpt-5.6-terra`、成本敏感高频任务的 `gpt-5.6-luna`；图片生成/编辑方向以 `gpt-image-2` 作为当前高质量图像模型参考。落地到本项目时仍必须通过 cmhub 能力别名调用，不在 cmshopee 客户端直连 OpenAI。 +2026-07-11 已按 OpenAI 官方文档核对：GPT-5.6 家族可作为文本/提示词辅助的后台能力参考，其中 `gpt-5.6-sol` 偏旗舰能力、`gpt-5.6-terra` 平衡能力与成本、`gpt-5.6-luna` 面向高频低成本任务；图片生成/编辑方向以 GPT Image 能力（如 `gpt-image-2`）作为高质量图像能力参考。落地到本项目时仍必须通过 cmhub 能力别名调用，不在 cmshopee 客户端直连 OpenAI。 ## 方案 @@ -48,4 +48,10 @@ T-586～T-595 固定使用 cmhub 托管生图模型，不接入自定义 Provide ## 执行记录 -（完成后记录评测样本、推荐档位、采用的 cmhub 别名和验证方式。） +2026-07-11 完成文档选型收口： + +- 新增 `docs/ai-studio-model-evaluation.md`，记录官方资料来源、档位建议、20～30 个商品评测样本集、评分口径、上线门槛、运营使用建议和客户端落地边界。 +- 明确 T-597 不伪造付费实测数据：当前结论是“未跑真实样本前保持当前 cmhub 托管默认别名”，T-598 只先做默认/高质量/省点档位展示与日志口径。 +- 明确客户端只保存 cmhub alias，不保存 OpenAI Key、Provider URL 或 OpenAI 原始模型 slug 作为执行事实。 +- 同步 `docs/README.md` 文档导航。 +- 验证：`git diff --check -- docs/ai-studio-model-evaluation.md docs/README.md docs/tasks/T-597.md` 通过。