Skip to content
BranchesTags

Repository files navigation

UMMevalKit

UMMevalKit 是一个面向**文生图（Text-to-Image）与图像编辑（Image Editing）**模型的统一评测框架。提供：

  • 统一推理入口 run.py，同时支持 T2I 和 I2I 流水线
  • 8 个 benchmark，覆盖生成质量、文本渲染、图像编辑、世界知识等多个维度
  • 每个 benchmark 配备独立的可复现 shell 脚本（scripts/infer_*.sh、scripts/eval_*.sh）
  • 统一的 LLM/VLM judge 层（api/），支持 OpenAI 兼容 API 和本地模型
  • 内置 torchrun 多 GPU 分布式推理支持

目录

环境搭建

1. 创建 Conda 环境（推荐）

conda create -n ummeval python=3.11
conda activate ummeval

2. 安装 PyTorch

根据 CUDA 版本选择对应的 PyTorch：

# CUDA 12.4
pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu124

# CUDA 12.1
pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu121

3. 安装核心依赖

pip install -r requirements.txt

核心依赖包括：

类别 关键包 推荐版本
深度学习 torch 2.6.0
torchvision 0.21.0
Transformers transformers 4.51.3
diffusers 0.38.0
accelerate 1.13.0
数据处理 datasets 4.8.5
huggingface_hub 0.36.2
modelscope 1.37+
API openai 2.38.0

4. 安装评测后端（按需）

不同 benchmark 需要不同的评测后端，可根据实际需求选择性安装：

# GenEval 评测需要
pip install mmcv==2.1.0 mmdet==3.3.0 open-clip-torch

# DPG-Bench 评测需要
pip install fairseq

# LeX-Bench / TIIF-Bench 评测需要
pip install paddleocr paddlepaddle-gpu

# OneIG-Bench 评测需要
pip install dreamsim flash-attn

完整包版本列表见 environment/ummeval-key-packages.txt。

快速开始

1. 创建配置文件

python main.py --init-config

这会在项目根目录创建 config.yaml。编辑该文件，填入模型路径和 API 密钥。或者直接使用环境变量：

export CHEERS_CKPT_PATH="/path/to/Cheers/ckpt"
export BAGEL_CKPT_PATH="/path/to/BAGEL-7B-MoT"
export OPENAI_API_KEY="sk-your-key"
export OPENAI_BASE_URL="https://api.openai.com/v1"

2. 下载评测模型

评测中用到的本地模型存放于 hf-models/ 目录下，首次评测前需要下载：

bash scripts/download_hf_models.sh                    # 全部 benchmark（约 30 GB）
bash scripts/download_hf_models.sh --subset geneval   # 仅 GenEval
bash scripts/download_hf_models.sh --subset dpg       # 仅 DPG-Bench

下载脚本优先使用 ModelScope（国内可直接访问），自动回退到 hf-mirror.com 镜像。

3. 下载 benchmark 数据（仅图像编辑 benchmark 需要）

文生图 benchmark 的 prompt 数据已内置在仓库中。图像编辑 benchmark 需要额外下载源图像：

bash scripts/prepare_data.sh --subset imgedit   # ImgEdit 源图像
bash scripts/prepare_data.sh --subset gedit     # GEdit-Bench Arrow 数据集

4. 运行推理

# 单 GPU 推理
python main.py --model cheers --data geneval --mode infer

# 多 GPU 分布式推理
CUDA_VISIBLE_DEVICES=0,1,2,3 torchrun --nproc-per-node=4 main.py \
    --model cheers --data geneval --mode infer

推理结果写入 infer_outputs/<模型名>/<数据集名>/<eval_id>/。

5. 运行评测

python main.py --model cheers --data geneval --mode eval

评测结果写入 eval_result/<模型名>/<benchmark名>/<eval_id>/。

6. 快速验证（仅跑 100 条）

main_fast.py 提供一个精简入口，默认只跑 geneval 的前 100 条 prompt，用于验证 pipeline 是否跑通：

python main_fast.py --model cheers                     # GenEval, 100 条
python main_fast.py --model cheers --data geneval dpg   # 多个 benchmark
python main_fast.py --model cheers --max-samples 50     # 指定条数

输出目录自动添加 fast- 前缀，便于与正式运行区分。

目录结构

UMMevalKit/
├── main.py                       # 统一入口（配置感知）
├── main_fast.py                  # 快速验证入口（默认 100 条）
├── config.example.yaml           # 配置文件模板
├── run.py                        # 核心推理引擎
├── requirements.txt              # Python 依赖
├── MLLM/                         # 被测模型 wrapper
│   ├── __init__.py               # build_model() 工厂函数
│   ├── base_eval_model.py        # 抽象基类
│   ├── cheers.py                 # Cheers wrapper
│   ├── bagel.py                  # BAGEL-7B-MoT wrapper
│   └── Bagel/                    # BAGEL 上游源码
├── benchmarks/                   # Benchmark 数据集与评测实现
│   ├── __init__.py               # Dataset_eval 注册表
│   ├── model_paths.py            # 评测用本地模型路径配置
│   ├── geneval/                  #   GenEval
│   ├── dpg/                      #   DPG-Bench
│   ├── imgedit/                  #   ImgEdit-Bench
│   ├── gedit/                    #   GEdit-Bench
│   ├── LeX_Art/                  #   LeX-Bench
│   ├── OneIG_Benchmark/          #   OneIG-Bench
│   ├── TIIF_Bench/               #   TIIF-Bench
│   └── wise/                     #   WISE
├── api/                          # LLM/VLM judge 统一调用层
│   ├── judge.py                  # JudgeClient 实现
│   └── judge_config.py           # Judge 注册与配置
├── scripts/                      # Shell 入口脚本
│   ├── infer_*.sh / eval_*.sh    # 各 benchmark 的推理/评测脚本
│   ├── download_hf_models.sh     # 评测模型下载器
│   ├── prepare_data.sh           # Benchmark 数据下载器
│   ├── _infer_utils.sh           # 公共工具函数
│   ├── _infer_launcher.sh        # 推理启动器
│   └── _eval_launcher.sh         # 评测启动器
├── environment/                  # 环境依赖文档
├── hf-models/                    # 评测模型存放目录（下载后生成，gitignored）
├── infer_outputs/                # 推理输出（gitignored）
├── eval_result/                  # 评测结果（gitignored）
└── logs/                         # 运行日志（gitignored）

支持的模型

模型 T2I I2I CFG Alpha Steps 备注
Cheers ✓ ✓ text/image, interval, renorm (global/channel) ✓ ✓ —
BAGEL-7B-MoT ✓ ✓ text/image, interval, renorm (global/channel/text_channel) timestep_shift num_timesteps —

详细参数说明见 MLLM/README.md。

Benchmark 详解

共 8 个 benchmark，全部通过 run.py 进行推理，通过 scripts/eval_*.sh 进行评测。

概览

Benchmark 类型 评测方式 需要 API Key？ 评测模型
GenEval 文生图 目标检测 + CLIP 分类 否 Mask2Former, OpenCLIP
DPG-Bench 文生图 VQA + 依赖图 否 mPLUG
ImgEdit-Bench 图像编辑 LLM/VLM judge 打分 是 —
GEdit-Bench 图像编辑 VIEScore (LLM/VLM judge) 是 —
LeX-Bench 文生图 (文本生成) OCR + 美学 + LLM judge 部分 (color/font) PaddleOCR, one-align
OneIG-Bench 文生图 5 维度 metric 组合 否* CLIP, LLM2CLIP, CSD, DINO, DreamSim, StyleEncoder
TIIF-Bench 文生图 (文本遵循) VLM judge + OCR 是 (VLM 模式) PaddleOCR
WISE 文生图 (世界知识) VLM judge 二值评分 是 —

* OneIG 的 Qwen2.5-VL 默认走 API；设置 ONEIG_USE_API=0 可切换到本地推理。

1. GenEval

类型：文生图

概述：评估生成图像是否满足结构化 prompt 中描述的对象、数量、颜色和空间关系。每个 prompt 被分解为一组 include/exclude 约束子句。

评测流程：

  1. Mask2Former（Swin-S backbone，COCO 预训练）对生成图像进行实例分割和目标检测。
  2. OpenCLIP ViT-L/14 对检测到的物体区域进行零样本颜色分类。
  3. 将检测结果与约束规则逐一比对（物体类别、数量、颜色属性、空间位置），判定每张图是否为 correct（soft correctness）。
  4. Overall score = 6 类任务（single object, two object, counting, colors, position, color attribute）正确率的平均值。

变体：geneval（short，553 条 prompt）、geneval_long（long，553 条复杂 prompt）

输出：geneval_results.txt — 各任务及 Overall 正确率。

2. DPG-Bench

类型：文生图

概述：DPG-Bench（Dense Proposition Graph）将每个 prompt 细粒度地拆分为多个命题问题（proposition），问题之间存在依赖关系（dependency DAG），评估生成图像对复杂语义的遵循程度。

评测流程：

  1. 每个 prompt 被拆成多个 proposition question（如"图中是否有猫？""猫是否在桌子上？"），标注了父子依赖关系。
  2. 将生成的 2×2 图像网格裁剪为 4 张独立图像，使用 mPLUG VQA 模型对每张图回答所有命题的 yes/no 问题。
  3. 依赖传播：父命题答案为 no 时，子命题分数强制置零。
  4. DPG-Bench score = 全部命题 yes 回答比例的聚合分数。

输出：按 L1/L2 类别的 DPG-Bench 分数。

3. ImgEdit-Bench

类型：图像编辑

概述：评估单轮图像编辑质量。给定原图 + 编辑指令，被测模型生成编辑后的图像，由 LLM/VLM judge 从多个子维度进行 1-5 分评分。

评测流程：

  1. 覆盖 8 种编辑类型（背景替换、物体添加/删除/替换、颜色/纹理/风格编辑、视角变换等）。
  2. 将 [原图, 编辑图, 编辑指令] 发送给 judge，对多个子维度给出 1-5 分。
  3. step1_get_avgscore.py 聚合每个样本的分维度分数，step2_typescore.py 按编辑类型聚合。

数据：源图像通过 scripts/prepare_data.sh --subset imgedit 从 sysuyy/ImgEdit 下载。

默认 judge：gpt4.1

输出：JSONL 结果文件 + 按编辑类型聚合的分数。

4. GEdit-Bench

类型：图像编辑

概述：基于 VIEScore 框架的通用图像编辑评测，同时评估语义一致性和图像质量。支持中英文编辑指令。

评测流程：

  1. 覆盖 11 个编辑组（background_change, color_alter, material_alter, motion_change, ps_human, style_change, subject-add/remove/replace, text_change, tone_transfer）。
  2. VIEScore：judge 接收 [原图, 编辑图, 指令]，返回：
    • semantics_score — 编辑后图像与指令的语义一致性
    • quality_score — 编辑后图像的视觉质量
    • overall_score = sqrt(semantics × quality)
  3. calculate_statistics.py 按编辑组和语言聚合。

数据：Arrow 格式数据集 stepfun-ai/GEdit-Bench，通过 scripts/prepare_data.sh --subset gedit 下载。

默认 judge：gpt4o

输出：按编辑组的 CSV 分数文件 + 统计总表。

5. LeX-Bench

类型：文生图（文本生成图像）

概述：专门评估文本生成图像（text-rich image generation）的文本准确性、美学质量、位置控制、颜色和字体遵循度。支持 easy/medium/hard 三个难度等级。

评测流程：

  1. PaddleOCR（检测 + 识别 + 方向分类）从生成图像中提取文字及其 bounding box。
  2. PNED & Recall：识别文字与期望文字之间的位置无关归一化编辑距离和召回率。
  3. One-align：美学质量和图像质量评分。
  4. 位置准确率：基于 OCR bounding box 判断文字是否位于 prompt 指定的位置。
  5. 颜色与字体：裁剪 OCR 检测到的文字区域，发送给 LLM judge 判断颜色和字体是否与 prompt 一致。
  6. summarize_lex_results.py 汇总 7 项指标：PNED、Recall、Quality、Aesthetic、Position Acc、Color Acc、Font Acc。

默认 judge：gpt4.1（仅 color/font 指标使用）

输出：按 difficulty 和 prompt type 拆分的汇总表。

6. OneIG-Bench

类型：文生图

概述：六维度综合评估 T2I 生成质量，覆盖语义对齐、文本渲染、风格、推理能力和多样性。支持英文和中文。

评测维度（5 个独立 metric）：

Metric 方法 评测模型
Alignment Qwen2.5-VL 对语义问题回答 yes/no，按依赖关系过滤后取平均正确率 Qwen2.5-VL (API)
Text Qwen2.5-VL OCR 输出文本，计算 ED（编辑距离）、CR（字符率）、WAC（词准确率），综合为 text score Qwen2.5-VL (API)
Style CSD 风格编码器 + OneIG StyleEncoder 分别提取风格 embedding，与参考风格 embedding 计算余弦相似度 CSD, OneIG-StyleEncoder
Reasoning LLM2CLIP 计算答案文本与生成图像之间的跨模态相似度 LLM2CLIP-OpenAI, LLM2CLIP-Llama
Diversity DreamSim 计算同一 prompt 生成的 4 张图像之间的 pairwise distance DreamSim

每个 prompt 生成 4 张图并拼成 2×2 grid，按类别（anime, human, object, text, reasoning, multilingualism）组织输出。

Qwen2.5-VL 默认通过 API 调用。设置 ONEIG_USE_API=0 可强制使用本地模型。

输出：按维度、按类别的 CSV 分数文件。

7. TIIF-Bench

类型：文生图（文本遵循）

概述：TIIF-Bench（Text-Integrated Image Following）评估 T2I 模型对短/长文本指令的遵循程度，每个 prompt 都配有细粒度的 binary evaluation question。

评测流程：

  1. VLM 模式：judge 对每张生成图像提出多个 fine-grained evaluation question 进行 yes/no 判断，与标准答案比对得到 accuracy。
  2. OCR 模式：PaddleOCR 检测识别图像中文字，计算 GNED（Global Normalized Edit Distance）和 Recall。
  3. 按 attribute、dimension group（Basic, Advanced, Real World, Art 等）、short/long 分别汇总。

变体：test（完整集）/ testmini（子集），× short / long prompt 类型。

默认 judge：gpt4o

输出：按 attribute/type/dimension 的 accuracy 表 + GNED/Recall。

8. WISE

类型：文生图（世界知识）

概述：WISE（World Knowledge-Informed Semantic Evaluation）评估 T2I 模型对世界知识的理解和整合能力。Prompt 是间接的、需要推理的（如 "The plant often gifted on Mother's Day" → 模型需推理出是康乃馨）。

评测流程：

  1. 1000 个 prompt，覆盖 3 大领域 25 个子类别：
    • 文化常识：节日、运动、宗教、工艺品、建筑、动物、植物、艺术、名人、日常生活
    • 时空推理：横向/纵向时间推理、不同视角、地理关系、相对位置
    • 自然科学：生物学、物理学、化学
  2. VLM judge 对 [图像, prompt, 解释] 进行 二值 0/1 评分。
  3. 按 6 个 category 分组计算 accuracy，加权得到 Overall：文化 0.40、时间 0.12、空间 0.12、生物 0.12、物理 0.12、化学 0.12。

默认 judge：qwen35_35b

输出：wise_scores.jsonl（逐样本分数）+ wise_summary.json（汇总）。

Judge 配置

LLM/VLM judge 通过统一的 api.create_judge() 接口调用，支持远程 API 和本地模型两种后端。

远程 API（OpenAI 兼容）

Judge Key 后端模型 支持视觉
gpt4.1 gpt-4.1 ✓
gpt4o gpt-4o ✓
gpt-4-turbo gpt-4-turbo ✓
qwen35_35b qwen3.5-35b-a3b ✓
qwen25vl qwen3.5-35b-a3b（API 模式） ✓

本地模型

Judge Key 实现方式 支持视觉
qwen25vl Qwen2.5-VL-7B-Instruct（设置 ONEIG_USE_API=0） ✓

需要 Judge 的 Benchmark 汇总

Benchmark 默认 Judge 是否必需
ImgEdit-Bench gpt4.1 是
GEdit-Bench gpt4o 是
LeX-Bench gpt4.1 部分（仅 color/font）
TIIF-Bench gpt4o VLM 模式需要
WISE qwen35_35b 是

GenEval、DPG-Bench、OneIG-Bench 不需要 API judge，完全使用本地评测模型。

配置方式见 配置参考 及 api/README.md。

使用指南

推理

# 单 GPU
python main.py --model cheers --data geneval --mode infer

# 多 GPU
CUDA_VISIBLE_DEVICES=0,1,2,3 torchrun --nproc-per-node=4 main.py \
    --model cheers --data geneval --mode infer

推理引擎根据 dataset.datatype() 自动分发：

  • "gen"（文生图）→ model.gen_t2i(prompt, batchsize, dataset_name)
  • "edit"（图像编辑）→ model.gen_i2i(prompt, input_images, batchsize, dataset_name)

评测

bash scripts/eval_geneval.sh    # 编辑脚本头部设置 MODEL_NAME, EVAL_ID

脚本速查表

Benchmark 推理脚本 评测脚本 --data 示例
GenEval infer_geneval.sh eval_geneval.sh geneval, geneval_long
DPG-Bench infer_dpg.sh eval_dpg.sh dpg
ImgEdit infer_imgedit.sh eval_imgedit.sh imgedit
GEdit infer_gedit.sh eval_gedit.sh gedit
LeX-Bench infer_lex.sh eval_lex.sh lex_easy_simple, lex_easy_enhanced, …
OneIG infer_oneig.sh eval_oneig.sh OneIG-EN, OneIG-ZH, …
TIIF infer_tiif.sh eval_tiif.sh tiif_test_short, tiif_testmini_long, …
WISE infer_wise.sh eval_wise.sh wise

脚本主要参数

参数 说明
MODEL_NAME 模型名：cheers 或 BAGEL-7B-MoT
MODEL_PATH 模型权重路径（为空时使用 wrapper 默认值）
CFG CFG scale：数字、None 或 {"text": 7.5, "image": 1.5}
ALPHA Alpha 参数
STEPS 推理步数
CFG_INTERVAL CFG 区间（如 "0.0 0.6"）
CFG_RENORM CFG renorm 模式（global / channel / text_channel）
EVAL_ID 设为空则自动新建；填入已有 ID 可复用输出目录
SKIP_COMPLETED 开启后跳过已生成的样本（断点续跑）
GPUS / NPROC GPU 和进程数配置

配置参考

模型 checkpoint 路径

# config.yaml
model_paths:
  cheers_ckpt: "/path/to/Cheers/ckpt"
  bagel_ckpt:  "/path/to/BAGEL-7B-MoT"
  bench_models_root: "./hf-models"    # 评测模型根目录

或通过环境变量：CHEERS_CKPT_PATH、BAGEL_CKPT_PATH、BENCH_KIT_MODELS。

API 密钥

judge:
  default_api_key: "sk-your-key"
  default_base_url: "https://api.openai.com/v1"

或通过环境变量：OPENAI_API_KEY、OPENAI_BASE_URL。

Benchmark 数据路径

benchmark_data:
  gedit_data_dir: "./benchmarks/gedit/edit_data"
  wise_data_path: "./benchmarks/wise/prompts/final_data.json"
  geneval_data_root: "./benchmarks/geneval/prompts"
  dpg_bench_csv: "./benchmarks/dpg/dpg_bench.csv"
  tiif_data_root: "./benchmarks/TIIF_Bench/data"
  oneig_data_root: "./benchmarks/OneIG_Benchmark/OneIG-Bench"

所有路径均默认指向 benchmarks/ 下的内置数据，仅在需要自定义路径时覆盖。

评测模型路径

各评测模型的路径在 benchmarks/model_paths.py 中统一配置，默认根目录为 ./hf-models/，可通过 BENCH_KIT_MODELS 环境变量覆盖。

扩展指南

添加新模型

  1. 在 MLLM/ 下创建新的 wrapper 文件，继承 BaseEvalModel。
  2. 实现 gen_t2i()、gen_i2i()、build_prompt() 等方法。
  3. 在 MLLM/__init__.py 的 _load_model_class() 中注册。
  4. 如需新增配置项，在 config.example.yaml 和 main.py 中添加对应映射。

添加新 Benchmark

  1. 在 benchmarks/ 下创建新目录，实现 dataset wrapper（提供 datatype()、__getitem__()、gen_num_images()、output_form()）。
  2. 在 benchmarks/__init__.py 的 Dataset_eval 字典中注册。
  3. 编写评测代码和对应的 scripts/eval_*.sh 脚本。
  4. 如需本地评测模型，将其路径添加到 benchmarks/model_paths.py。
  5. 如需下载外部数据，在 scripts/prepare_data.sh 中添加下载函数。

添加新 Judge

  1. 在 api/judge.py 中（或新建文件）实现 JudgeClient 接口。
  2. 在 api/judge_config.py 中注册。

License

本项目基于 MIT License 发布。

各 benchmark 和评测模型受其各自许可证约束，详见各 benchmark 目录及模型下载页面的说明。

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages