eval_scripts/README-zh.md

English | 中文

---

UNO评估框架

为了更通用地评估各种Omni评测集，我们构建了一个轻量级的Omni评估框架，并发布了一个高性能的打分模型用以支持评分，你可以自由且便捷地基于此框架新增数据集或评测模型。接下来，我们将以UNO-Bench和Qwen-2.5-Omni-7B为例，介绍如何运行框架。

🚀 快速开始

🛠️ 环境准备

运行前请确保安装以下Python核心依赖。注意：由于vLLM的安装涉及PyTorch、CUDA等复杂依赖，建议在新的虚拟环境中进行安装，以避免潜在的依赖冲突问题。

pip install -r requirements.txt

接下来你可以通过以下命令下载必要的模型权重和数据集：

huggingface-cli download xxx --repo-type dataset --local-dir /path/to/UNO-Bench
huggingface-cli download xxx --local-dir /path/to/UNO-Scorer
huggingface-cli download Qwen/Qwen2.5-Omni-7B --local-dir /path/to/Qwen2.5-Omni

🎯 实验复现

通过执行如下代码，你可以复现论文中Qwen-2.5-Omni-7B的实验结果。记得将MODEL_PATH、DATASET_LOCAL_DIR和SCORER_MODEL_PATH替换为你本地数据集路径。

bash examples/run_unobench_qwen_omni_hf.sh

更推荐执行vLLM版本的推理服务，具有更好的性能表现。

bash examples/run_unobench_qwen_omni_vllm.sh

• 程序采用串行逻辑进行评估，依次执行：启动推理服务 -> 结果生成 -> 资源释放 -> 启动打分服务 -> 计算分数 -> 资源释放
• 支持断点续评，推理进度和打分进度均会以一定间隔保存到本地。

📈 Compositional Law

Compositional Law的拟合曲线可以参考如下代码。

python3 compositional_law.py

🤖 只使用打分模型

我们推荐使用vLLM以获取更高的效率，你可以参考：

bash examples/test_scorer_vllm.sh

或者基于transformers，但是效率较低：

python3 examples/test_scorer_hf.py

⚙️ 配置指南

在运行之前，必须 修改 run_unobench_qwen_omni_*.sh 顶部的配置区域以适配你的环境。

1. 推理模型配置 (Target Model)

变量名	说明	示例
MODEL_NAME	模型注册名称 (对应 models 代码中定义的名称)	"Qwen-2.5-Omni-7B" "VLLMClient"
MODEL_PATH	模型权重所在的本地绝对路径	/path/to/Qwen2.5-Omni
INFERENCE_BACKEND	推理后端选择："vllm" 或 "hf"	"vllm"
TARGET_GPU_IDS	推理阶段使用的 GPU 编号	"0,1"
TARGET_TP_SIZE	推理模型的 Tensor Parallelism 大小	2
TARGET_PORT	vLLM 服务端口	8000

2. 打分模型配置 (Scorer Model)

变量名	说明	示例
SCORER_MODEL_PATH	打分模型UNO-Scorer的路径	/path/to/UNO-Scorer
SCORER_GPU_IDS	打分阶段使用的 GPU 编号	"0,1"
SCORER_PORT	打分服务vLLM端口	8001

3. 数据集与路径

变量名	说明
DATASET_NAME	评测数据集名称 (如 "UNO-Bench")
HF_CACHE_DIR	HuggingFace 缓存或多媒体数据目录，自动下载的数据集会保存在此处
DATASET_LOCAL_DIR	数据集本地路径， 程序会优先从DATASET_LOCAL_DIR读取数据，否则自动下载至HF_CACHE_DIR
EXP_MARKING	实验标记后缀 (如 _test)，用于区分实验设置以及输出文件名

🌀 运行评测

配置完成后，授予脚本执行权限并运行：

bash run_eval.sh

脚本执行流程详解

1. Stage 1: Inference (推理)
   • 若选择 vllm 模式，脚本将在后台启动目标模型的 API Server。
   • 运行 eval.py --mode inference 进行数据推理。
   • 关键步骤：推理完成后，脚本会自动 kill 掉目标模型的 vLLM 进程，完全释放 GPU 显存。
2. Stage 2: Scorer Setup (启动打分)
   • 在后台启动打分模型（Scorer）的 vLLM 服务。
3. Stage 3: Evaluation (评分)
   • 运行 eval.py --mode scoring，将生成结果发送给打分模型进行评估。
4. Cleanup (清理)
   • 任务结束，自动关闭打分模型服务。

📊 结果输出

评测结果将生成 JSON 文件，默认保存在 ./eval_results/ 目录下。

• 文件名格式: {MODEL_NAME}{EXP_MARKING}:{DATASET_NAME}.json

📂 极简开发指南

.
├── run_eval.sh    # [主程序] 负责配置参数、服务生命周期管理及流程控制
├── eval.py             # [执行脚本] 负责数据加载、API交互及结果存储
├── utils/              # [依赖] 通用工具函数集
├── models/             # [依赖] 模型注册与加载
└── benchmarks/         # [依赖] 数据集注册与加载

项目主要分为评测集和评测模型两部分，你可以在benchmarks/下注册新数据集，在models/下注册新模型。

新增评测集

1. 在benchmarks/下新建一个新数据集.py文件，如unobench.py，内部继承BaseDataset类，并实现其中的抽象方法。
   • load_and_prepare，下载并加载评测集，并将每条数据组织为utils.EvaluationRecord格式。
   • build_message，构建发送到模型侧的消息，格式为OpenAI Chat Message。
   • build_score_message，构建发送到打分模型的消息，格式为OpenAI Chat Message。
   • compute_score，计算单条数据的分数。
   • compute_metrics，计算整个数据集的所有指标。
2. 在__init__.py中注册该数据集。

新增评测模型

1. 在models/下新建一个新模型.py文件，如何qwen_2d5_omni_7b.py，内部继承BaseModel类，并实现其中的抽象方法。
   • load_model，加载模型。
   • generate，单次调用模型接口生成文本。
   • generate_batch，批量调用模型接口生成文本。
2. 在__init__.py中注册该模型。

⚠️ 注意事项

• 路径检查: 请确保脚本中的路径已修改为你服务器上的实际路径。