MedUniEval 评测框架实战:30+ 医学基准覆盖 2D/3D/视频的一键评测完整指南

原创2026-10-16 13:12:381,675 阅读

MedUniEval 评测框架实战:30+ 医学基准覆盖 2D/3D/视频的一键评测完整指南

MedUniEval 评测框架是 Hulu-Med(透明医疗视觉-语言模型)项目内置的医学大模型评测工具:一套代码即可对文本、2D 医学影像、3D 体数据与视频四大模态的医疗多模态模型进行基准测试,内置 30 余个权威医学基准,支持一键评测脚本与多 GPU 分块并行,是进行医学视觉-语言模型横向对比的完整指南与实用工具。

Hulu-Med 医学视觉语言模型总览与 MedUniEval 评测框架

📌 本指南基于 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 的子类,执行时自动走固定流水线:

  1. load_data:加载数据集,支持从 HuggingFace 自动下载或本地目录读取,并按 chunk_idx / num_chunks 切分样本;
  2. construct_messages:把原始样本转成模型可理解的 messages(自动拼接选择题提示、开放式提示等);
  3. run:按批次调用 model.generate_outputs 批量生成回答,并保存中间结果;
  4. 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 评测框架支持的 CT 影像问答输入示例

快速开始:一键跑通评测

第一步:准备依赖

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 开始就是最短路径。

登录后查看全文
Hulu-Med