nnU-Net · 体验报告

从零跑通
脑 MRI 分割
流水线

FrameworknnU-Net v2 + HD-BET
ComputeCPU only · 无 GPU
DatasetMSD Task04 · 260 cases
Total time约 15 分钟
体验报告 · 全 18 页 2026 / 06
00 · 项目目标02 / 18
我们要做什么

在没有 GPU 的笔记本上,
跑通医学图像分割的真实 AI 流水线

不依赖云服务、不租 GPU,验证一个问题:学术界主流的医学分割框架能不能在普通设备上跑通? 整个过程从数据下载、自动配置、真 AI 推理到最终报告,全部自动化、可复现。

01 · 目标

跑通 nnU-Net

完整跑完 nnU-Net 自动流水线的 数据指纹 + plan 生成,验证 "无需调参" 这个核心承诺。

02 · 目标

跑出真 AI 推理

用 HD-BET 在标准脑模板上做真实脑提取,CPU 模式下端到端可用

03 · 交付

可复现的产物

所有脚本 + 数据 + 产物打包,他人 4 步可在自己电脑上复现

01 · 技术栈03 / 18
用到的工具

三个开源工具 ·
各司其职。

框架 · DKFZ

nnU-Net v2

医学分割框架,2021 年 Nature Methods。核心创新:根据数据自动推导训练配置,无需调参。

pip install nnunetv2

推理 · DKFZ

HD-BET

基于 nnU-Net 训好的脑提取专用模型。开箱即用,支持 CPU,~400 MB 权重。

pip install hd-bet

数据 · MSD

Task04 Hippocampus

Medical Segmentation Decathlon 中最小的 benchmark 数据集,27 MB,260 训练 + 130 测试。

msd-for-monai.s3...

02 · 流程总览04 / 18
7 个步骤 · 全自动 · 全幂等

从空目录到 HTML 报告,
一条命令跑通。

01

下载数据

MSD Task04 + ICBM152 模板

02

转格式 + Plan

MSD→nnU-Net v2 · auto plan

03

HD-BET 推理

真 AI 脑提取 · CPU 3-5 min

04

样本可视化

数据集三视图 · PNG

05

Plan 信息图

plan 解释成卡片

06

推理可视化

HD-BET 输出三视图

07

拼报告

HTML 单文件 · 自动开

7
流水线步骤
幂等
已完成步骤自动跳过
~15分钟
端到端耗时(首次)
0
需要的 GPU 数量
03 · 步骤 0105 / 18
STEP 01 耗时 · 1-2 分钟 脚本 · 01_download_data.py

下载数据 + 标准脑模板

用 requests 从 AWS S3 下载 MSD Task04 数据集(27 MB),再用 nilearn 拉一份 ICBM152 标准脑(HD-BET 的测试输入)。

# 自动跑(在 run_all.sh 里)
$ python scripts/01_download_data.py

# 实际下载:
 https://msd-for-monai.s3-us-west-2.amazonaws.com/Task04_Hippocampus.tar     # 27 MB
 nilearn.datasets.fetch_icbm152_2009()                                            # T1 标准脑
⬇ INPUT
  • (无)从网络下载
⬆ OUTPUT
  • downloads/Task04_Hippocampus/imagesTr · labelsTr · imagesTs
  • hdbet_test/test_brain.nii.gzICBM152 T1 标准脑
04 · 步骤 0206 / 18
STEP 02 耗时 · ~37 秒 脚本 · 02_preprocess.py

转格式 + 自动 plan

MSD 的目录结构跟 nnU-Net v2 不一样——先调 nnUNetv2_convert_MSD_dataset 转换; 再跑 plan_and_preprocess 让 nnU-Net 自动分析数据指纹、生成训练计划。

# 子步骤 1:MSD → nnU-Net v2 格式
$ nnUNetv2_convert_MSD_dataset -i downloads/Task04_Hippocampus -overwrite_id 4

# 子步骤 2:数据指纹 + 自动 plan
$ nnUNetv2_plan_and_preprocess -d 4 --verify_dataset_integrity
⬇ INPUT
  • downloads/Task04_Hippocampus/MSD 原始格式
⬆ OUTPUT
  • nnUNet_raw/Dataset004_Hippocampus/v2 格式
  • .../nnUNetPlans.json⭐ 训练计划
  • .../dataset_fingerprint.json数据指纹
04 · Plan 详解07 / 18
STEP 02 · 产物详解

37 秒后,
它把训练计划
自己写出来了。

扫了 260 个病例,统计 shape / spacing / 强度分布,然后基于规则推导出:

  • patch size [56, 40]
  • batch size 366
  • 归一化方式 Z-score
  • 网络深度 4 stages

没有人调参。

nnU-Net plan
nnUNetPlans.json · 自动生成的训练 plan
04 · 关键洞察08 / 18
"
这是 nnU-Net 的核心创新——
医学图像分割界的 "rule-based AutoML"

没有梯度下降搜超参,没有 Optuna 调试,没有 W&B sweep。
一组规则 × 一个数据指纹 = 一份训练计划。 这种"确定性 AutoML"在医学影像领域出奇地有效。

05 · 步骤 0309 / 18
STEP 03 耗时 · 3-5 分钟 (CPU) 脚本 · 03_hdbet.py

HD-BET · 真 AI 脑提取

nnU-Net 自己不带预训练权重;但同团队基于它做的 HD-BET 是个开箱即用的脑提取模型。 首次运行会下 ~400 MB 模型权重(缓存到 ~/.cache/torch/)。

# 一行命令:
$ hd-bet -i test_brain.nii.gz -o brain.nii.gz -device cpu --disable_tta --save_bet_mask

# 参数说明:
  --disable_tta   关闭 test-time augmentation,速度快 4x,质量损失轻微(CPU 推荐)
  --save_bet_mask 同时输出二值 mask,方便可视化叠加
⬇ INPUT
  • hdbet_test/test_brain.nii.gzICBM152 T1,197×233×189
⬆ OUTPUT
  • output/test_brain_bet.nii.gz抠掉头骨的纯脑组织
  • output/test_brain_bet_bet.nii.gz二值 mask(哪些 voxel 是脑)
05 · HD-BET 推理结果10 / 18

真 AI 推理 · 在 ICBM152 标准脑模板上

HD-BET output
左:输入原图 · 中:AI 提取出的纯脑组织 · 右:mask 叠加在原图上 · ~22% voxel 为脑
06 · 步骤 04-0611 / 18
STEP 04 / 05 / 06 耗时 · 每个几秒 脚本 · 04 / 05 / 06_*.py

把数据 / Plan / 推理结果 · 都画成图

用 matplotlib + nibabel 把前面几步的产物(NIfTI 体数据、JSON plan)渲染成 PNG,统一 Claude/Anthropic 米色调色板。

STEP 04

数据集样本图

用 nibabel 加载 hippocampus_001,自动找标注体素最多的切片,三视图 + 真值叠加

→ outputs/hippocampus_sample.png

STEP 05

Plan 信息图

nnUNetPlans.json,用 matplotlib FancyBboxPatch 画成 3 张卡片:指纹 / 决策 / 理由。

→ outputs/nnunet_plan.png

STEP 06

HD-BET 结果图

加载 HD-BET 输出的 NIfTI,3×3 网格:三轴 × (原图 / 抠脑 / mask 叠加)。

→ outputs/hdbet_result.png

06 · 数据集样本12 / 18
DATASET · case 001

海马 MRI ·
前部 vs 后部。

MSD Task04 任务:把海马切成
前部 (anterior)后部 (posterior) 两个区域。

单个病例 shape ≈ 35×51×35,spacing 1mm 各向同性。
260 训练 + 130 测试,全部带标注。

hippocampus sample
case 001 · 三视图 · 真值标注叠加在 MRI 上
07 · 步骤 0713 / 18
STEP 07 耗时 · ~1 秒 脚本 · 07_generate_report.py

拼最终 HTML 报告

把 3 张 PNG 用 base64 内嵌到 HTML 模板里,读取 plan.json 的实际数值填进去, 输出单文件 HTML 报告(约 1.1 MB,无外部依赖)。

# 核心逻辑:
def b64(p): return base64.b64encode(open(p,'rb').read()).decode()

plan_b64  = b64('outputs/nnunet_plan.png')        # 175 KB → base64
hdbet_b64 = b64('outputs/hdbet_result.png')       # 612 KB → base64
hippo_b64 = b64('outputs/hippocampus_sample.png') #  57 KB → base64

# 用 f-string 把 b64 数据 + plan.json 数值填进模板,写出去
Path('outputs/nnunet_report.html').write_text(html, encoding='utf-8')
⬇ INPUT
  • outputs/*.png3 张可视化
  • nnUNetPlans.json填实际数值
⬆ OUTPUT
  • outputs/nnunet_report.html⭐ 最终报告 · 1.1 MB
08 · 边界14 / 18
关键区分

这次跑了什么,
没跑什么。

nnU-Net v2

训练框架

  • 需要带标注数据集
  • 需要 GPU · 10 GB+ 显存
  • 本次只跑了 预处理 + plan 生成
  • 没真训练 · 没在 hippocampus 上推理
  • 命令在脚本里:nnUNetv2_train 4 2d 0
HD-BET

开箱即用推理

  • 基于 nnU-Net 已训好的预训练权重
  • 支持 CPU 推理 · 虽然慢
  • 只做脑提取这一件事
  • 本次跑出了真分割结果 ✓
  • 临床/科研 MRI 处理的第一步
09 · 产物清单15 / 18
跑完后磁盘上长什么样

所有产物 · 留在磁盘可查证。

nnunet_repro/
├── scripts/                                       # 7 个步骤脚本
├── downloads/Task04_Hippocampus/                  # MSD 原始数据 · 27 MB
│   ├── imagesTr/  # 260 训练 .nii.gz
│   ├── labelsTr/  # 260 真值标注
│   └── imagesTs/  # 130 测试
├── hdbet_test/
│   ├── test_brain.nii.gz                            # ICBM152 输入
│   └── output/test_brain_bet*.nii.gz                ⭐ HD-BET 真 AI 输出
├── nnUNet_raw/Dataset004_Hippocampus/             # 转格式后
├── nnUNet_preprocessed/Dataset004_Hippocampus/
│   ├── nnUNetPlans.json自动生成的训练计划
│   └── dataset_fingerprint.json数据指纹
└── outputs/
    ├── nnunet_report.html                       ⭐⭐ 最终报告
    ├── nnunet_slides.html                            # 这份演示稿
    └── *.png                                         # 3 张可视化
10 · 复现指南16 / 18
在你电脑上 · macOS / Windows

解压 → 装环境 → 跑 → 看报告。

01

解压压缩包

路径不带空格中文 · ~/projects/nnunet_repro_mac/

手动1 分钟
02

./setup.sh

建 .venv · 装 PyTorch + nnU-Net + HD-BET + 可视化依赖

一次性3-5 分钟
03

./run_all.sh

跑全流水线 · 7 步幂等 · 中途断了直接重跑

每次30秒 - 15分钟
04

看报告

自动用浏览器打开 outputs/nnunet_report.html

享受
11 · 结论17 / 18
回顾

从零到 AI 推理 ·
15 分钟 · 0 GPU。

学到什么 · 01

"无需调参" 是真的

nnU-Net 的 plan 生成机制设计严谨——只用规则不用梯度,但能 cover 大部分医学分割场景。

学到什么 · 02

CPU 推理可行

HD-BET 的 nnU-Net inference 在 CPU 上 3-5 分钟出脑提取结果,对临床/科研流程的第一步够用了。

下一步 · 03

真训练要 GPU

想在自己的数据上做真分割,绕不开 GPU。但框架已经准备好,单条命令即可启动。

End of deck · 18 / 18

谢谢。

代码 · 数据 · 产物 · 全部留在
~/projects/nnunet_repro_mac/

nnU-Net v2 · HD-BET · MSD Task04 End
1 / 18