qgfvadfuvads/qprefer-expert-baselines

Video Expert Benchmark

这个仓库把七个视频质量 / reward model 的推理与统一评测拆成两层：

• expertbench 只依赖 Python 标准库，负责数据校验、任务编排和指标计算。
• workers/ 在各模型自己的 Python 环境中运行，避免 DOVER、Qwen2-VL、LLaVA 和 VideoScore2 的依赖互相冲突。

支持论文表中的 DOVER、Q-Align、Q-Eval、FAST-VQA、VideoReward、UnifiedReward-7B 和 VideoScore2。模型源码与权重不打包进本仓库；请遵守各上游项目的许可证。

1. 准备新的 test set

输入是 JSONL，每行是一对视频。相对路径以 manifest 所在目录为基准。

{"pair_id":"p001","task":"t2v","prompt":"A red kite above a beach.","video_a":"media/p001/a.mp4","video_b":"media/p001/b.mp4","label_quality":1,"label_alignment":0}

字段约定：

• task: t2v 或 i2v。
• video_a, video_b: 必填；每个 expert 都在固定 A/B 轴上输出分数。
• conditioning_image: I2V 可选。当前七个论文 baseline 都按各自原生接口评分，未使用该图；保留字段便于后续模型使用。
• label_quality, label_alignment: 可选，1 表示 A 更好，-1 表示 B 更好，0 表示 tie，null 表示该维度不计分。

先校验数据：

python -m expertbench validate /path/to/test.jsonl

如果使用原始 Q-Prefer-Bench kit，可一次生成包含 T2V 和 I2V 的 549 对 manifest：

python tools/convert_qprefer.py --kit /path/to/benchmark_kit --task all \
  --output qprefer_all.jsonl --check-files

仓库附带的 examples/manifest.jsonl 只展示格式，不包含视频。

2. 配置模型

每个模型使用独立环境。复制示例配置并设置路径：

cp configs/models.example.json configs/models.local.json

export DOVER_PYTHON=/path/to/dover-env/bin/python
export DOVER_ROOT=/path/to/DOVER
export DOVER_CHECKPOINT=/path/to/DOVER.pth

export FASTVQA_ROOT=/path/to/FAST-VQA-and-FasterVQA
export FASTVQA_CHECKPOINT='/path/to/FAST_VQA_B_1*4.pth'
export FASTVQA_PYTHON=/path/to/fastvqa-env/bin/python

export VIDEOSCORE2_ROOT=/path/to/VideoScore2
export VIDEOSCORE2_PYTHON=/path/to/videoscore2-env/bin/python
export VIDEOREWARD_PYTHON=/path/to/video-reward-env/bin/python
export VIDEOREWARD_ROOT=/path/to/VideoAlign
export VIDEOREWARD_CHECKPOINT=/path/to/VideoReward/checkpoints

VideoScore2 的 worker 已自包含，不要求克隆其上游 repo；VIDEOSCORE2_ROOT 仅供 Q-Align 和 UnifiedReward adapters 使用。

VideoScore2 不要复用任意现成 Qwen 环境。用 CPython 3.12.12 单独安装 envs/videoscore2-cu128.lock.txt，并保留 FORCE_QWENVL_VIDEO_READER=torchvision、PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True 与 attn_implementation=sdpa。示例配置已把 Hugging Face revision 锁到完整 SHA； 权重 shard 的 LFS SHA-256 见 reference/videoscore2_weights.json。

其余 *_PYTHON 同理。Hugging Face model id 可以直接留在 JSON 中。检查配置但不加载模型：

python -m expertbench doctor --config configs/models.local.json

各模型的准确版本、信号映射和注意事项见 docs/MODELS.md。

3. 推理

先 dry-run 检查将执行的命令：

python -m expertbench run \
  --manifest /path/to/test.jsonl \
  --config configs/models.local.json \
  --models dover,q_align,q_eval,fastvqa,video_reward,unified_reward,video_score2 \
  --output-dir results \
  --device cuda \
  --dry-run

去掉 --dry-run 即开始推理。调试时加 --limit 1，中断后加 --resume。每个模型输出一个 JSONL；每完成一对就落盘，因此长任务可以安全续跑。

单个模型需要多卡并行时，可直接给同一个 worker 传互斥的 stride shard。例如 5 张卡分别使用 --num-shards 5 --shard-index 0 到 4，输出到不同 JSONL；中断重启时加 --resume。

如果在多张 GPU 上手工切分 manifest，可以在计分前合并互斥 shard；工具会拒绝重复 pair_id：

python tools/merge_predictions.py --inputs results/model.part*.jsonl \
  --output results/model.jsonl

4. 计算论文口径指标

python -m expertbench score \
  --manifest /path/to/test.jsonl \
  --predictions results/video_score2.jsonl \
  --output results/video_score2.metrics.json

实现与 Q-Prefer-Bench 一致：

• acc_with_ties: 在模型分数差上搜索使三分类准确率最大的 epsilon。
• acc_without_ties: 去掉人工 tie 样本，按 score(A) - score(B) 的符号计算。
• overall_macro_*: 对模型实际支持的 T2V/I2V × quality/alignment cell 做等权宏平均。

报告还给出 acc_without_ties_if_flipped。如果翻转 A/B 后显著更好，会产生 polarity_warning，防止把方向映射错误写进论文。 默认情况下，只要一个已支持的 cell 有部分样本缺失或推理报错，计分就会失败；--allow-missing 仅用于诊断，不能用于正式报表。

5. 与论文的关系

reference/paper_numbers.json 保存论文表格值；reference/gpu_reproduction_2026-08-25.json 保存修正协议后的 DOVER、FAST-VQA-B 1x4 和 VideoReward 完整 GPU 结果、环境与 artifact hash。VideoScore2 的 2026-08-25 fresh 549/549 GPU 精确复现及失败环境对照见 reference/videoscore2_gpu_reproduction_2026-08-25.json，历史聚合 artifact 见 reference/videoscore2_retained_aggregate.json，重新下载的锁定权重见 reference/videoscore2_weights.json。完整审计见 docs/REPRO_AUDIT.md；旧 Codex/Claude 会话里究竟复现了什么、用的命令和本地 repo 见 docs/HISTORICAL_PROVENANCE.md，其机器可读副本是 reference/historical_provenance_2026-08-25.json。

本仓库刻意不包含私有测试标签、视频、模型权重或第三方源码，适合单独推送到 GitHub 并交给合作者替换 test set。

开发测试

python -m unittest discover -s tests -v
python -m compileall expertbench workers