MedUniEval 评测框架实战:30+ 医学基准覆盖 2D/3D/视频的一键评测完整指南
MedUniEval 评测框架实战:30+ 医学基准覆盖 2D/3D/视频的一键评测完整指南
MedUniEval 评测框架是 Hulu-Med(透明医疗视觉-语言模型)项目内置的医学大模型评测工具:一套代码即可对文本、2D 医学影像、3D 体数据与视频四大模态的医疗多模态模型进行基准测试,内置 30 余个权威医学基准,支持一键评测脚本与多 GPU 分块并行,是进行医学视觉-语言模型横向对比的完整指南与实用工具。
📌 本指南基于 Hulu-Med 仓库中的
MedUniEval/目录编写,全部相对路径均以仓库根目录为基准。
为什么需要 MedUniEval 评测框架
医疗多模态大模型的评测远比"跑个准确率"复杂:
- 模态多:文本 QA、X-Ray/病理 2D 图像、CT/MRI 3D 体数据、手术视频,各自的输入格式与预处理完全不同;
- 题型杂:单选题、开放式问答、报告生成、判断题混在一起,无法用统一指标衡量;
- 模型多:Qwen2-VL、InternVL、MedGemma、HuatuoGPT、HealthGPT……各家接口千差万别。
MedUniEval 的核心价值,就是把上述差异全部封装在统一接口之下:你只需要指定"模型 + 基准名",框架自动完成数据加载、消息构造、批量推理、指标计算与结果落盘。它构建在 MedEvalKit 之上,专为医疗视觉-语言模型设计,并随 Hulu-Med 项目持续扩展新基准。
MedUniEval 架构解析:注册表 + 统一流水线
框架代码集中在 MedUniEval/ 目录,核心文件只有 4 个,结构非常清晰:
| 文件 | 职责 |
|---|---|
| MedUniEval/eval.py | 评测入口:解析命令行参数、初始化模型、遍历基准逐个执行 |
| MedUniEval/benchmarks.py | 基准注册表:基准名 → 对应数据集类的映射与分发 |
| MedUniEval/LLMs.py | 模型注册表:模型名 → 推理实现的映射(LLMRegistry) |
| MedUniEval/utils/base_dataset.py | BaseDataset 统一评测流水线 |
模型注册表:20+ 模型统一接入
MedUniEval/LLMs.py 通过装饰器 @LLMRegistry.register("模型名") 注册了 20 余个主流医疗/通用多模态模型,包括:
Hulumed_qwen2、Hulumed_qwen3、Qwen2-VL、Qwen2.5-VL、InternVL、Huatuo、HealthGPT、LLava、LLava_Med、BiMediX2、BiomedGPT、MedGemma、Llama-3.2、Janus、Med_Flamingo、Vllm_Text(纯文本 vLLM 模型)等。
多数模型同时提供 vLLM 加速版与 HF Transformers 版两条推理路径,由 --use_vllm 参数一键切换;所有模型统一继承 MedUniEval/models/base_llm.py 中定义的 BaseLLM 抽象接口(generate_outputs 批量生成)。
评测流水线:四步完成一个基准
每个基准都是 MedUniEval/utils/base_dataset.py 中 BaseDataset 的子类,执行时自动走固定流水线:
- load_data:加载数据集,支持从 HuggingFace 自动下载或本地目录读取,并按
chunk_idx / num_chunks切分样本; - construct_messages:把原始样本转成模型可理解的
messages(自动拼接选择题提示、开放式提示等); - run:按批次调用
model.generate_outputs批量生成回答,并保存中间结果; - cal_metrics:调用 MedUniEval/utils/evaluate_metrics.py 中的准确率、F1、BLEU 等指标函数计算得分,写入
metrics.json。
选择题自动提取选项字母判分,开放式题目可启用 LLM 裁判(LLM Judge)自动打分,报告生成类基准则走 3D/图像专用评测逻辑(如 MedUniEval/utils/eval_3d.py)。
支持的 30+ 医学基准清单
基准名在 MedUniEval/benchmarks.py 的 prepare_benchmark 中注册,--eval_datasets 参数支持逗号分隔传入多个,一次跑完。各基准源码位于 MedUniEval/utils/<基准名>/ 下,例如 MedUniEval/utils/M3D/M3D.py、MedUniEval/utils/MedFrameQA/MedFrameQA.py。
📝 文本模态:医学知识与考试
| 基准 | 考察能力 |
|---|---|
MedQA_USMLE / MedQA_MCMLE |
USMLE 医学执照考试题 |
MedMCQA |
印度医学入学考试 MCQ |
MMLU-medical / MMLU-all / MMLU_Pro |
多学科知识(医学子集)与高阶推理 |
MedXpertQA-Text |
专家级医学问答(文本) |
Medbullets_op4 / Medbullets_op5 |
开放式医学问答 |
PubMedQA |
论文结论推理 |
SuperGPQA |
超学科研究生级 QA |
CMMLU / CMB / CMExam |
中文医学知识 |
🩻 2D 影像模态:医学影像 VQA
| 基准 | 考察能力 |
|---|---|
PMC_VQA / OmniMedVQA |
综述级医学影像问答 |
VQA_RAD |
放射影像报告问答 |
SLAKE |
临床知识+影像双维度问答 |
PATH_VQA |
病理学影像问答 |
MMMU-Medical-test / MMMU-Medical-val |
多模态大学级学科(医学) |
IU_XRAY / CheXpert_Plus |
胸片异常理解 |
MIMIC_CXR |
胸片报告理解与推理 |
🧊 3D 体数据模态:CT / 报告重建
| 基准 | 考察能力 |
|---|---|
M3D |
3D 医学影像问答(源码) |
3DRad |
3D 放射影像评测(源码) |
Radrestruct |
放射报告重建(源码) |
🎬 视频模态:动态医学影像
| 基准 | 考察能力 |
|---|---|
MedFrameQA |
医学视频帧序列问答(源码) |
此外,HealthBench 等开放式基准通过 LLM Judge 自动评分,MedUniEval/utils/HealthBench/ 目录内含官方评测代码。一张 CT 演示图可以让你对 2D 影像问答的输入形式有直观印象:
快速开始:一键跑通评测
第一步:准备依赖
MedUniEval 依赖与 Hulu-Med 推理环境一致,核心依赖在 requirements.txt 中(torch 2.4.0、transformers 4.51.2、datasets、nibabel、decord 等):
conda create -n hulumed python=3.10 -y
conda activate hulumed
pip install torch==2.4.0 torchvision==0.19.0 --extra-index-url https://download.pytorch.org/whl/cu118
pip install -r requirements.txt
第二步:配置并运行评测脚本
仓库提供了现成的一键脚本 MedUniEval/eval.sh,只需修改几个关键变量:
cd MedUniEval
export HF_HOME="./datas" # 数据集缓存目录
DATASETS_PATH="hf" # "hf"=自动从 HuggingFace 下载
OUTPUT_PATH="./eval_results_hulumed" # 结果输出目录
EVAL_DATASETS="MMLU_Pro,MedMCQA,MedQA_USMLE,PubMedQA,PMC_VQA,VQA_RAD,SLAKE" # 要评测的基准
MODEL_NAME="Hulumed_qwen2" # 模型注册名(见 LLMs.py)
MODEL_PATH="ZJU-AI4H/Hulu-Med-7B" # 模型仓库或本地路径
USE_VLLM="False" # True=用 vLLM 加速,False=transformers
bash eval.sh
脚本内部即调用 MedUniEval/eval.py 并传入全部参数,常用参数说明如下:
| 参数 | 说明 | 示例 |
|---|---|---|
--eval_datasets |
逗号分隔的基准名列表 | MedQA_USMLE,PMC_VQA |
--model_name / --model_path |
模型注册名 / 模型路径 | Hulumed_qwen2、本地路径 |
--use_vllm |
是否用 vLLM 加速推理 | True / False |
--datasets_path |
hf(自动下载)或本地数据目录 |
hf |
--output_path |
结果保存目录 | ./eval_results_hulumed |
--reasoning |
是否启用推理(CoT)模式 | True / False |
--temperature / --top_p |
采样参数 | 0、0.95 |
--use_llm_judge |
是否启用 LLM 裁判评分 | True(需配 API Key) |
--seed |
随机种子,保证可复现 | 42 |
💡 国内网络下载数据集较慢时,可取消 MedUniEval/eval.sh 中
export HF_ENDPOINT=https://hf-mirror.com一行的注释,改用镜像加速。
多 GPU 分块并行:大幅缩短评测时间
医学基准样本量大,单卡评测耗时很长。MedUniEval 原生支持分块并行:把样本均分到 N 张卡,每卡独立加载模型跑自己的子集,最后自动合并计算总分(合并逻辑见 MedUniEval/utils/base_dataset.py 的 eval 方法)。
现成脚本 MedUniEval/eval_chunked.sh 会根据 CUDA_VISIBLE_DEVICES 自动决定分块数:
CUDA_VISIBLE_DEVICES="0,1,2,3,4,5,6,7" # 8 卡 → 自动切成 8 块
bash eval_chunked.sh
每个进程通过 --num_chunks 与 --chunk_idx 知道自己负责哪一块,结果分别保存为 results_0.json ~ results_7.json;当全部块完成后,框架自动合并为 results.json 并生成 metrics.json。单卡时直接传 --num_chunks 1 --chunk_idx 0(默认值)即可。
结果输出与 LLM Judge
每个基准的产物保存在 <output_path>/<基准名>/ 下:
results.json—— 逐条原始回答(含模型 response);metrics.json—— 汇总指标(accuracy、F1、BLEU 等,由 MedUniEval/utils/evaluate_metrics.py 计算);- 分块场景下另有
results_<i>.json分块文件。
对于开放式问答、报告生成等"无法直接比对"的题目,可启用 LLM Judge:设置 --use_llm_judge True --judge_gpt_model gpt-4.1-2025-04-14 --openai_api_key <你的Key>,由 GPT 裁判按标准提示词打分(实现见 MedUniEval/utils/eval_metrics/)。未启用时,开放式题目回退到字面相似度等规则指标。
常见问题 FAQ
Q1:支持评测哪些模型?
以 MedUniEval/LLMs.py 中注册的名为准:Hulumed_qwen2、Hulumed_qwen3、Qwen2-VL、Qwen2.5-VL、InternVL、Huatuo、HealthGPT、LLava_Med、MedGemma、BiomedGPT、Llama-3.2 等 20+ 个。新模型只要在 LLMs.py 中加一个注册类即可。
Q2:vLLM 与 HF Transformers 推理如何选择?
--use_vllm True 走 vLLM 引擎,吞吐更高,可配合 --tensor_parallel_size 做张量并行;False 则用 Transformers 原生推理,环境更简单、依赖更少。脚本默认 USE_VLLM="False",新手建议先用 HF 模式跑通,再切 vLLM 提速。
Q3:数据集从哪里来?
--datasets_path hf 时框架通过 datasets 库自动下载并缓存到 HF_HOME;也可把处理好的数据放到本地目录并传入绝对路径。部分 3D 数据(如 M3D、3DRad)需要本地 NIfTI 文件。
Q4:如何评测自己微调的模型?
把 MODEL_PATH 指向本地权重目录、MODEL_NAME 填对应的注册名即可;输出路径换个名字,方便多组结果对比。
Q5:如何扩展新基准?
继承 BaseDataset,实现 load_data、construct_messages、cal_metrics 三个方法,然后在 MedUniEval/benchmarks.py 中加一个分支注册基准名——参考 MedUniEval/utils/SuperGPQA/SuperGPQA.py 即可,几十行代码即可接入。
总结
MedUniEval 是 Hulu-Med 开源生态中"评测侧"的完整答案:
- 一站式:30+ 医学基准,文本 / 2D / 3D / 视频全模态覆盖;
- 低门槛:改几行变量、
bash eval.sh即可一键评测; - 可扩展:注册表设计让新模型、新基准的接入成本极低;
- 可并行:多 GPU 分块自动合并,大幅缩短大规模评测时间;
- 可复现:固定种子 + 逐条结果落盘 + LLM Judge 自动评分。
无论你是要复现 Hulu-Med 论文指标,还是横向对比多个医疗多模态模型,从 MedUniEval/eval.sh 开始就是最短路径。
