MedUniEval评测医疗大模型:Hulu-Med-32B官方评测框架完全用法(覆盖文本/2D/3D/视频)
MedUniEval评测医疗大模型:Hulu-Med-32B官方评测框架完全用法(覆盖文本/2D/3D/视频)
如何用 MedUniEval 评测医疗大模型?本文面向新手,完整讲解 Hulu-Med-32B 官方配套评测框架 MedUniEval(基于 MedEvalKit 构建)的用法,一站式覆盖文本、2D 图像、3D 体数据与视频四类模态,带你从零搭建环境到跑通评测,快速获得可复现的医疗视觉语言模型评测结果。
一、什么是 MedUniEval:医疗大模型评测的统一框架
📊 MedUniEval 是 Hulu-Med 团队于 2025-11-01 发布的官方评测代码,构建在开源评测库 MedEvalKit 之上,专门用于对医疗视觉语言模型(Medical VLM)做跨模态全面评测,评测维度包括:
| 评测模态 | 典型数据形态 | 覆盖的评测任务 |
|---|---|---|
| 📝 文本 | 纯文字问答 | 医学知识、推理、报告理解(MMLU-Med、MedQA、PubMedQA 等) |
| 🖼️ 2D 图像 | X-Ray、CT 平片、病理切片、眼底照等 | 医学 VQA、异常检测、报告生成(OM.VQA、PMC-VQA、VQA-RAD 等) |
| 🧊 3D 体数据 | NIfTI(.nii)格式 CT/MRI 体数据 | 3D 影像报告生成、解剖理解 |
| 🎬 视频 | 手术视频等时序影像 | 手术阶段识别、手术视频理解 |
被测模型 Hulu-Med 是一个完全透明的通用医疗视觉语言模型:基于 1670 万样本训练,覆盖 12 大解剖系统与 14 种医学影像模态(CT、MRI、X-Ray、超声、PET、OCT、内镜、显微镜、组织病理、眼底、皮肤镜等),并提供 4B / 7B / 14B / 32B 四种参数规模。本文以旗舰版 Hulu-Med-32B 为例演示完整评测流程。
二、先认识被测对象:Hulu-Med-32B 模型档案
在开始评测前,先了解模型的"配置单",这直接决定了显存需求与推理方式。核心信息来自 config.json:
| 配置项 | 数值 | 说明 |
|---|---|---|
| 参数规模 | 32B | 基于 Qwen2.5-32B 语言底座,训练成本约 40,000 GPU 小时 |
| hidden_size | 5120 | 64 层 Transformer,40 个注意力头,8 个 KV 头 |
| 视觉编码器 | SigLIP + 2D RoPE | 27 层、hidden 1152、patch_size 14,统一处理 2D/3D/视频 |
| 精度 | bfloat16 | 评测与推理均建议以 bfloat16 加载 |
| 上下文长度 | 32768 | rope_theta 为 1e6,适合长报告与长文档 |
| Token 压缩 | 医学感知 Token 缩减 | 约 55% 的视觉 token 压缩,长序列推理更省显存 |
模型实现代码可直接查阅:
- 主干网络:modeling_hulumed_qwen2.py
- 视觉编码器:modeling_hulumed_encoder.py
- 处理器(对话/图像/3D/视频预处理):processing_hulumed.py
- 图像处理器:image_processing_hulumed.py
- 权重分片索引(13 个分片):model.safetensors.index.json
三、评测环境一键搭建(支持文本/2D/3D/视频全模态)
💡 评测环境按模态安装依赖即可,一次性装全最省心。推荐 Python 3.10:
conda create -n hulumed python=3.10
conda activate hulumed
# PyTorch(CUDA 11.8)与 Flash-Attention
pip install torch==2.4.0 torchvision==0.19.0 --extra-index-url https://download.pytorch.org/whl/cu118
pip install flash-attn==2.7.3 --no-build-isolation --upgrade
# Transformers 与加速
pip install transformers==4.51.2 accelerate==1.7.0
# 视频评测依赖(decord 抽帧)
pip install decord ffmpeg-python imageio opencv-python
# 3D 影像评测依赖(NIfTI 文件)
pip install nibabel
如果需要在本地管理模型仓库文件,可使用:
git clone https://gitcode.com/hf_mirrors/ZJU-AI4H/Hulu-Med-32B
⚡ 32B 参数规模评测耗时较长,官方已兼容最新版 vLLM,支持张量并行与更快推理,见 README.md 的 vLLM Installation 章节。
四、MedUniEval 四类模态评测怎么用
四类模态共用同一套加载方式与 HulumedProcessor 对话接口(见 processor_config.json),区别只在于输入条目的 type 与参数。
4.1 文本评测:医学知识与推理基准
纯文本评测只需传入 type: "text",对应 MedXQA、MedQA、MedMCQA、PubMedQA、MMLU-Pro、SGPQA 等基准。加载模型与跑文本样例的核心代码如下:
from transformers import AutoModelForCausalLM, AutoProcessor
import torch
model_path = "ZJU-AI4H/Hulu-Med-32B"
model = AutoModelForCausalLM.from_pretrained(
model_path, trust_remote_code=True,
torch_dtype="bfloat16", device_map="auto",
attn_implementation="flash_attention_2",
)
processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True)
🧠 思考模式技巧:评测开放式题目时,在问题后附加 "Please reason step by step, and put your final answer within \boxed{}.",并通过解码参数
use_think=True查看推理过程(use_think=False只返回最终答案),可提升复杂医学推理题的得分稳定性。
4.2 2D 图像评测:单图、多图与图文交错
2D 评测覆盖 OM.VQA、PMC-VQA、VQA-RAD、SLAKE、PathVQA、MMMU-Med 等基准。图像通过 type: "image" + image_path 传入,支持三种组织方式:
- 单图问答:一张图 + 一个问题(如"为这张 X-Ray 生成医学报告");
- 多图对比:多张图 + 一个比较类问题(如"这两张图是否一致");
- 图文交错:文本与图像按顺序穿插(如"Image A:(图)Image B:(图)哪张是病理切片?")。
图像预处理由 preprocessor_config.json 控制:动态 token 数在 16~16384 之间自适应,patch 大小为 14,归一化均值/标准差均为 0.5——病理、X-Ray 等低对比度影像也能保持稳定的视觉特征。
4.3 3D 影像评测:NIfTI 体数据的三轴切片
3D 评测是 Hulu-Med 的亮点能力。传入 .nii 文件时需指定两个关键参数:
| 参数 | 含义 | 示例 |
|---|---|---|
nii_num_slices |
从体数据中抽取的切片数 | 180 |
nii_axis |
切分轴:0=矢状面(sagittal),1=冠状面(coronal),2=轴位(axial) | 2 |
content = [
{"type": "3d", "3d": {
"image_path": "./demo/amos_0013.nii",
"nii_num_slices": 180,
"nii_axis": 2, # 0=sagittal, 1=coronal, 2=axial
}},
{"type": "text", "text": "Generate a medical report for this 3D CT scan."},
]
视觉编码器内置 2D RoPE,将 3D 切片序列与时序视频统一到同一套位置编码中,因此 3D 评测无需额外模型变体。运行前请确保已安装
nibabel。
4.4 视频评测:手术视频等时序影像
视频通过 type: "video" 传入,两个核心参数为 fps(抽帧率,默认 1)与 max_frames(最大帧数,处理器默认 128,可按需放宽)。视频相邻帧还会做 2 合 1 的 token 合并(video_merge_size: 2),进一步压缩长序列开销:
content = [
{"type": "video", "video": {
"video_path": "./demo/1min_demo.mp4",
"fps": 1,
"max_frames": 1800,
}},
{"type": "text", "text": "Describe this video in detail."},
]
🎬 四类模态速查表:
| 模态 | 输入 type | 关键参数 | 必备依赖 | 典型评测场景 |
|---|---|---|---|---|
| 文本 | text |
无 | — | MedQA、MMLU-Med、PubMedQA |
| 2D 图像 | image |
image_path |
opencv-python | OM.VQA、SLAKE、PathVQA |
| 3D 体数据 | 3d |
image_path / nii_num_slices / nii_axis |
nibabel | 3D CT 报告生成 |
| 视频 | video |
video_path / fps / max_frames |
decord、ffmpeg-python | 手术视频理解 |
五、Hulu-Med-32B 官方评测成绩单解读
📊 跑通流程后,你得到的分数应能与官方结果对齐(完整表格见 README.md)。Hulu-Med-32B 在开源医疗 VLM 中的代表性成绩:
多模态基准(对比部分强基线)
| 模型 | OM.VQA | PMC-VQA | VQA-RAD | SLAKE | PathVQA | MedXQA | MMMU-Med |
|---|---|---|---|---|---|---|---|
| GPT-4.1 | 75.5 | 55.2 | 65.0 | 72.2 | 55.5 | 45.2 | 75.2 |
| Lingshu-32B | 83.4 | 57.9 | 76.7 | 86.7 | 65.5 | 30.9 | - |
| Hulu-Med-32B | 84.6 | 69.4 | 81.4 | 85.7 | 67.3 | 34.0 | 60.4 |
医学文本基准(对比部分强基线)
| 模型 | MMLU-Pro | MedXQA | Medbullets | SGPQA | PubMedQA | MedMCQA | MedQA | MMLU-Med |
|---|---|---|---|---|---|---|---|---|
| GPT-4.1 | 78.0 | 30.9 | 77.0 | 49.9 | 75.6 | 77.7 | 89.1 | 89.6 |
| Lingshu-32B | 70.2 | 22.7 | 65.4 | 41.1 | 77.8 | 66.1 | 74.7 | 84.7 |
| Hulu-Med-32B | 72.9 | 24.2 | 68.8 | 41.8 | 80.8 | 72.8 | 80.4 | 85.6 |
📌 成绩亮点:VQA-RAD(81.4)与 PathVQA(67.3)大幅领先同规模开源模型;PubMedQA(80.8)超过 GPT-4.1,显示其医学文献推理能力;MMLU-Med 达到 85.6,仅次于顶级闭源模型。
六、评测参数与生成配置速查(新手避坑)
- 🌡️ 生成参数:官方默认见 generation_config.json——
temperature 0.7、top_k 20、top_p 0.8、repetition_penalty 1.05、do_sample True。做选择题评测建议改用确定性解码(do_sample=False)以减少随机性波动。 - 🎯 评测提示词:图像/3D/视频评测时务必设置
add_system_prompt=True与add_generation_prompt=True,保证与官方基准一致。 - 🧮 精度与注意力:保持 bfloat16 + Flash-Attention 2;输入中的
pixel_values需显式转为torch.bfloat16。 - 🖥️ 显存规划:32B 权重约 60GB(bfloat16),单卡 80G 可运行,建议
device_map="auto"多卡分摊,或用 vLLM 开启张量并行加速大规模评测。 - 🧠 思考模式:主观题评测开启
use_think=True获取推理链,客观题评测保持use_think=False只取最终答案。
七、项目关键文件导航
| 文件 | 用途 |
|---|---|
| README.md | 完整文档:安装、四模态示例、基准成绩 |
| config.json | 模型结构配置(LLM + 视觉编码器) |
| modeling_hulumed_qwen2.py | 主模型实现(HulumedQwen2ForCausalLM) |
| modeling_hulumed_encoder.py | SigLIP 视觉编码器实现 |
| processing_hulumed.py | 对话/图像/3D/视频统一处理器 |
| image_processing_hulumed.py | 图像预处理(动态 token) |
| preprocessor_config.json | 图像预处理超参数 |
| generation_config.json | 默认生成参数 |
| tokenizer_config.json / vocab.json | 分词器配置与词表 |
| model.safetensors.index.json | 13 个权重分片的索引 |
✅ 小结:MedUniEval 为医疗大模型评测提供了文本、2D、3D、视频四位一体的统一口径。按本文流程——搭环境、加载 Hulu-Med-32B、按模态组织输入、对齐官方生成参数——你就能在数小时内完成一次可复现的全模态评测。MedUniEval 团队表示更多基准正在路上,建议持续跟踪 README.md 的 News 更新。