task.md

# Evaluation Codebase — Task List (v2)

已定方案（2026-07-07）：

1. **接入方式**：所有候选模型统一走 API。
2. **评测底座**：fork [GenEditEvalKit](https://github.com/open-compass/GenEditEvalKit)（OpenCompass），复用其 registry 式模型 adapter、多环境管理和已内置的 benchmark。
3. **补齐 benchmark**：按 GenEditEvalKit 的插件模式补 **T2I-CompBench** 和 **MagicBrush** 两个官方评估器。
4. **通用指标层**：独立 `metrics` 模块（t2v_metrics + clean-fid + image-reward），对任意 run 输出目录事后计算，不依赖具体 benchmark。
5. **实验 UI 接口**：Gradio 应用新增 `Evaluation lab` Tab（已完成，见 `app.py`）——同一 prompt（可带源图/参考图）跨多个候选模型并排生成对比，输出存 `output/eval/`；后续再接 benchmark runner 的结果展示。

benchmark 矩阵：

| 侧 | Benchmark | 来源 |
|---|---|---|
| 生成 | GenEval、DPG-Bench（+ 可选 OneIG / UniGenBench / WISE 等） | GenEditEvalKit 内置 |
| 生成 | T2I-CompBench(++) | 自行补插件 |
| 编辑 | GEdit-Bench (EN/CN)、ImgEdit | GenEditEvalKit 内置 |
| 编辑 | MagicBrush | 自行补插件 |
| 指标 | FID、CLIP Score、ImageReward、HPS、PickScore、VQAScore | 独立 metrics 模块 |

---

## Phase 0 — 剩余决策与准备

- [ ] 定候选模型清单及各自的 API 端点/鉴权（`gpt-image-2` 必有；其余如 Gemini 图像、Seedream/SeedEdit、FLUX API 等待定）。
- [ ] 定 judge 模型：GEdit-Bench / ImgEdit 的 LLM judge 用哪个模型、走哪个 key（官方协议用 GPT-4.1 系，换 judge 会导致数字与文献不可比，需固定并记录）。
- [ ] 定统一生成参数：分辨率、每 prompt 采样张数（GenEval 惯例 4 张）、seed 策略、是否允许 prompt rewriting（写进报告）。
- [ ] 确认 GPU 评测机：GenEval(mmdet)、DPG(mPLUG)、T2I-CompBench(BLIP-VQA/UniDet)、FID/HPS 都需要 GPU。
- [ ] 收集对齐锚点：每个 benchmark 记 2–3 个已发表模型的公开分数（验 pipeline 用）。

## Phase 1 — Fork GenEditEvalKit 并跑通

- [x] Clone GenEditEvalKit（→ `eval/GenEditEvalKit/`，已 gitignore，后续转正式 fork），通读 `load_model.py`、`eval.sh`、`config.sh`、benchmark 目录结构，摸清 registry 与环境映射机制。结论：API 推理走 `infer/infer_mp_api.py`，模型名直接作为 OpenAI model id 传入 `OpenAIAPIT2I/Edit`，凭 `API_KEY`/`BASE_URL` 环境变量；断点续跑靠输出文件存在性；`eval.sh` 假设 conda + Linux GPU，评分侧需 GPU 机器。
- [x] **推理侧小样跑通**：`eval/smoke_geneval.py`（复用 kit 的 adapter 与输出布局）用 `gpt-image-2` 跑 GenEval 前 5 条 prompt，5/5 成功（约 60s/张，medium 质量），kit 自带 `check_empty_image` 校验通过。输出在 `eval/GenEditEvalKit/output/gpt-image-2/geneval/`，全量运行可无缝续跑。
- [ ] 评分侧：在 GPU 机器上配 geneval 评估环境（mmdet），对小样图片跑通 `eval/geneval.sh` 评分。
- [ ] 配置 `config.sh` + conda 环境映射（GPU 机器上），验证 `eval.sh --infer true --eval true` 官方全链路。
- [x] **编辑侧全链路小样跑通**（`eval/smoke_gedit.py`）：GEdit-Bench EN 取 5 个编辑类型各 1 条 → `gpt-image-2` 经 kit 的 `OpenAIAPIEdit` 编辑（5/5 成功，60–133s/张）→ kit 自带 VIEScore + gpt-4.1 judge 出分（协议与官方 step2 一致）。小样结果：SC=9.80 / PQ=7.40 / O=8.44，明细在 `output/gpt-image-2/gedit/smoke_scores.json`。
  - 修复了 kit 的 bug：`openai_api_edit.py` 传裸 bytes 导致 OpenAI 400（octet-stream 被拒），改为 `(filename, bytes, mimetype)` 元组——待回馈 fork 的第一个补丁。
  - 官方 `step2_gedit_bench.py` 全量跑时需要 `pip install megfile datasets` 并下载 HF 数据集 `stepfun-ai/GEdit-Bench`（仅用元数据）；judge 评分不需要 GPU，已确认。
- [ ] 补工程细节：API 重试/退避（当前 adapter 无重试）、限流并发、run manifest（模型版本、参数、成本、时间戳）。

## Phase 2 — 候选模型 Adapter

- [ ] 定义我们自己的 adapter 约定（在 GenEditEvalKit 接口之上）：T2I `generate(prompt, seed)`、编辑 `generate(input_list, seed)` 双能力声明。
- [ ] `gpt-image-2` adapter（生成 + 编辑）。
- [ ] 其余候选模型 adapter，逐个接入并各跑一次小样冒烟。
- [ ] 每个 adapter 记录：模型版本号、计费口径、限流参数、支持的分辨率。

## Phase 3 — 内置 Benchmark 全量运行

- [ ] **GenEval**：全部 553 prompt × 4 张，全部候选模型；输出六子类 + Overall。
- [ ] **DPG-Bench**：1065 条 dense prompt；输出 Overall + 分项。
- [ ] **GEdit-Bench EN/CN**：配好 judge key；输出 SC / PQ / O + 按编辑类型细分。
- [ ] **ImgEdit**：basic + challenging 套件；输出各任务类型分数。
- [ ] （可选加测）OneIG / UniGenBench / WISE 中挑 1–2 个新 benchmark 增强说服力。
- [ ] 每个 benchmark 首跑后与文献锚点比对，误差异常则先查协议再扩量。

## Phase 4 — 补齐两个 Benchmark 插件

### 4.1 T2I-CompBench(++)

- [ ] 拉官方 repo 与 prompt 集，确定用原版还是 ++ 版（报告注明）。
- [ ] 按 GenEditEvalKit 的 benchmark 目录/registry 模式包一层：prompt 加载 → 推理 → 官方评估器（BLIP-VQA / UniDet / CLIP / 3-in-1）。
- [ ] 独立 requirements + 环境映射登记。
- [ ] 用锚点模型验证分数量级后全量跑。

### 4.2 MagicBrush

- [ ] 下载测试集（先 single-turn），转成 GenEditEvalKit 编辑任务的输入格式。
- [ ] 接官方指标脚本：L1、L2、CLIP-I、DINO、CLIP-T。
- [ ] 同样以插件形式登记环境与评估入口。

## Phase 5 — 独立 metrics 模块

- [ ] 模块骨架：统一输入接口 = run 输出目录 + prompt/元数据清单（与 Phase 1 的存储规范对齐），任何一次 run 均可事后计算。
- [ ] 接 [t2v_metrics](https://github.com/linzhiqiu/t2v_metrics)：CLIP Score、HPSv2、PickScore、VQAScore（统一打分接口）。
- [ ] 接官方 `image-reward` 包：ImageReward。
- [ ] 接 `clean-fid`：FID，参考集 MS-COCO 2014 val 30K（含 COCO 下载/抽样脚本）。
- [ ] 固定并记录各指标的 backbone/权重版本（CLIP ViT-B/32 vs L/14 等），写进输出。
- [ ] 每个指标最小单测：已知图文对断言分数区间。
- [ ] CLI：`python -m metrics score --run <dir> --metrics fid,clip,ir,hps`，输出 JSON/CSV。

## Phase 6 — 报告与对齐验证

- [ ] 汇总脚本：模型 × benchmark 总矩阵（含 metrics 模块结果），附文献公开数字对照列。
- [ ] **对齐验证关卡**：选一个有公开分数的模型完整复现 GenEval + FID，确认误差合理后才对外报数。
- [ ] HTML/Markdown 报告：总表 + 每任务好/坏 case 并排样例图。
- [ ] `README`：记录 fork 基线 commit、各 benchmark/评估器版本、judge 模型版本、与文献设定的差异清单。

## Phase 7 —（可选）Vinhome 领域内评测

- [ ] 从九个 workflow 收集真实输入构建内部测试集。
- [ ] 领域指标：结构保持度（DINO/depth 一致性）、相机角度一致性、编辑局部性（mask 外 L1）、LLM-judge preservation 评分。
- [ ] 复用同一套 runner 与报告格式，与标准 benchmark 并列输出。

---

## 执行顺序

1. **Phase 1**（fork + GenEval 小样跑通 gpt-image-2）——第一个里程碑，验证底座可用。
2. **Phase 3 的 GenEval/DPG** + **Phase 5 的 CLIP/ImageReward/HPS** ——最快产出第一批可比数字。
3. **Phase 3 编辑侧**（GEdit/ImgEdit，需 judge 预算确认）。
4. **Phase 4** 两个插件 + **Phase 5 FID**。
5. **Phase 6** 对齐验证与报告；Phase 7 视需要。