MONAI 教程

此仓库托管 MONAI 教程。

1. 需求

大多数示例和教程需要 matplotlib 和 Jupyter Notebook。

可以通过以下命令安装：

python -m pip install -U pip
python -m pip install -U matplotlib
python -m pip install -U notebook

部分示例可能需要可选依赖项。如果出现任何可选导入错误， 请根据 MONAI 的安装指南安装相关包。 或者通过以下命令安装所有可选依赖项：

pip install -r https://raw.githubusercontent.com/Project-MONAI/MONAI/dev/requirements-dev.txt

在 Colab 中运行笔记本

大多数 Jupyter 笔记本都有“在 Colab 中打开”按钮。 请右键单击该按钮，然后选择“在新标签页中打开链接”，即可启动包含相应笔记本内容的 Colab 页面。

要通过 Colab 使用 GPU 资源，请务必将运行时类型更改为 GPU：

1. 从 Runtime 菜单中选择 Change runtime type
2. 在下拉菜单中选择 GPU
3. 单击 SAVE 这将重置笔记本，并可能会询问您是否是机器人（这些说明假定您不是）。

在单元格中运行以下命令以验证设置是否成功，并查看您可以访问的硬件类型：

!nvidia-smi

Google Colab 设置（CUDA 12.x、PyTorch 2.6、MONAI 1.5）

在 Google Colab 中，默认环境可能会导致与 MONAI 的版本冲突。 为确保兼容性，请按以下方式显式安装 PyTorch 和 MONAI：

安装带有 CUDA 12.4 的 PyTorch 2.6.0

pip install --index-url https://download.pytorch.org/whl/cu124
torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0

安装 MONAI 及常用依赖项

pip install "monai[all]" nibabel pydicom ipywidgets==8.1.2

已知问题及修复方法

• Torchaudio 版本不匹配 Colab 默认可能自带 torchaudio 2.8.0，而它与 torch 2.6.0 不兼容。 安装上述版本可以解决此问题。

• filelock 与 nni 冲突 某些预装软件包（如使用较新 filelock 的 pytensor）可能会产生冲突。 可以通过以下命令修复：

  pip uninstall -y pytensor pip install -U filelock

• 工作进程过多警告 Colab 的 CPU 资源有限，较高的 num_workers 设置可能导致执行卡死。 建议在运行教程时使用 --num_workers=2，并调整笔记本中涉及数据加载器等地方的 num_workers 参数。

快速烟雾测试

安装完成后，可通过以下步骤验证环境是否正常：

git clone https://github.com/Project-MONAI/tutorials.git cd tutorials/3d_segmentation/torch python -u unet_training_array.py --max_epochs 2 --batch_size 1 --num_workers 2

如果日志显示训练损失逐渐下降且 Dice 分数提升，则说明设置正确。

注意： 大多数情况下，用户可以直接在 Colab 笔记本中运行 MONAI 教程，无需额外安装。 上述步骤主要用于解决安装额外包时可能出现的依赖冲突。

数据

部分笔记本可能需要额外的数据。 每个用户需自行检查数据集的内容及适用许可，并判断其是否适合预期用途。

2. 问题与 bug

• 如有关于 MONAI 使用的问题，请在 MONAI 主仓库的讨论区提问。
• 如发现 MONAI 功能相关的 bug，请在主仓库提交 issue。
• 如遇到教程运行相关的 bug，请在此仓库提交 issue。

3. 成为贡献者

有关添加教程的详细信息，请参阅我们的贡献指南。

4. 笔记本与示例列表

2D 分类

mednist_tutorial

本笔记本展示了如何轻松地将 MONAI 功能集成到现有的 PyTorch 程序中。 它基于 MedNIST 数据集，非常适合作为初学者的教程。 本教程还利用了 MONAI 内置的遮挡敏感性功能。

2D 分割

torch 示例

基于 UNet 和合成数据集的 2D 分割训练与评估示例。 这些示例是标准的 PyTorch 程序，同时提供了基于字典和基于数组的实现版本。

3D 分类

ignite 示例

基于 DenseNet3D 和 IXI 数据集的 3D 分类训练与评估示例。 这些示例是 PyTorch Ignite 程序，同时提供了基于字典和基于数组的转换版本。

torch 示例

基于 DenseNet3D 和 IXI 数据集的 3D 分类训练与评估示例。 这些示例是标准的 PyTorch 程序，同时提供了基于字典和基于数组的转换版本。

3D 回归

densenet_training_array.ipynb

基于 DenseNet3D 和 IXI 数据集的 3D 回归训练与评估示例。

3D分割

ignite示例

基于UNet3D和合成数据集的3D分割训练与评估示例。这些示例是PyTorch Ignite程序，同时支持基于字典和基于数组的数据变换。

torch示例

基于UNet3D和合成数据集的3D分割训练、评估和推理示例。这些示例是标准的PyTorch程序，同样提供基于字典和基于数组的版本。

brats_segmentation_3d

本教程展示了如何基于MSD脑肿瘤数据集构建多标签分割任务的训练流程，并将PyTorch模型转换为ONNX模型以进行推理和比较。

spleen_segmentation_3d_aim

该笔记本说明了如何将MONAI与aimhubio/aim结合使用。

spleen_segmentation_3d_lightning

该笔记本展示了如何将MONAI与PyTorch Lightning框架结合使用。

spleen_segmentation_3d

本笔记本是一个基于MSD脾脏数据集的3D分割端到端训练与评估示例。 该示例展示了MONAI模块在基于PyTorch的程序中的灵活性：

• 针对基于字典的训练数据结构的变换。
• 加载带有元数据的NIfTI图像。
• 根据预期范围缩放医学图像强度。
• 基于正负标签比例裁剪出一批平衡的图像块样本。
• 缓存IO和变换以加速训练和验证。
• 用于3D分割任务的3D UNet、Dice损失函数和Dice平均指标。
• 滑动窗口推理。
• 确定性训练以提高可重复性。

unet_segmentation_3d_ignite

本笔记本是一个基于合成数据集的3D分割端到端训练与评估示例。该示例是PyTorch Ignite程序，展示了MONAI的几个关键特性，特别是针对医疗领域的特定变换以及用于性能分析的事件处理器（日志记录、TensorBoard、MLFlow等）。

COVID 19-20挑战基线

此文件夹提供了针对2020年COVID-19肺部CT病灶分割挑战赛（一项MICCAI认可的活动）的简单训练、验证和推理基线方法。

unetr_btcv_segmentation_3d

本笔记本演示了如何使用BTCV挑战数据集，在多器官分割任务上构建UNETR的训练流程。

unetr_btcv_segmentation_3d_lightning

本教程演示了如何将MONAI与PyTorch Lightning框架结合使用，利用BTCV挑战数据集构建多器官分割任务中UNETR的训练流程。

vista3d

本教程展示了使用MONAI在MSD脾脏数据集上微调VISTA3D的过程。如需深入了解，请访问VISTA仓库。

2D配准

使用mednist进行配准

本笔记本展示了一个快速演示，学习基于深度学习的64 x 64 X光手部图像的仿射配准。

3D配准

使用成对肺部CT进行3D配准

本教程展示了如何使用MONAI对同一患者在不同时间点采集的肺部CT体积进行配准。

使用不成对脑部MRI进行3D配准

本教程介绍了如何开始使用MONAI中提供的通用配准框架VoxelMorph来配准不成对的脑部MRI体积。

DeepAtlas

本教程演示了如何使用MONAI同时训练配准和分割模型。DeepAtlas方法通过让两个模型相互作为弱监督学习的来源，特别适用于拥有大量未标注图像但仅有少量带分割标签图像的情况。该笔记本使用OASIS-1脑部MRI数据集中的3D图像。

Deepgrow

Deepgrow

该示例展示了如何训练/验证2D/3D Deepgrow模型，同时也演示了如何对已训练的Deepgrow模型进行推理。

DeepEdit

DeepEdit

该示例展示了如何训练/测试DeepEdit模型。本教程包含一个笔记本，演示如何对预训练的DeepEdit模型进行推理。

部署

BentoML

这是一个简单的示例，展示了如何使用BentoML作为Web服务器来训练和部署MONAI网络，既可以本地使用BentoML仓库，也可以作为容器化服务。

Ray

本示例利用先前笔记本中训练好的网络，演示如何使用Ray进行Web服务器部署。

Triton

本示例通过在MedNIST分类问题上使用Triton服务器和Python客户端来演示MONAI的应用。演示内容自包含，README文件解释了如何使用Triton“后端”将MONAI代码注入到服务器中。请参阅Triton推理服务器/Python后端文档。

实验管理

Aim

这是一个使用Aim进行实验管理的示例，以3D脾脏分割为例。

MLFlow

这是一个使用MLFlow进行实验管理的示例，以3D脾脏分割为例。

MONAI bundle集成MLFlow

该示例展示了如何轻松启用并自定义MONAI bundle中的MLFlow功能，以实现实验管理。

ClearML

这是一个使用ClearML进行实验管理的示例，以UNet的3D分割为例。

联邦学习

NVFlare

这些示例展示了如何使用 NVFlare 和基于 MONAI 的训练器来训练联邦学习模型。

OpenFL

这些示例展示了如何基于 OpenFL 和 MONAI 来训练联邦学习模型。

Substra

该示例展示了如何在联邦学习平台 Substra 上执行 3D 分割的 PyTorch 教程。

乳腺密度 FL 挑战赛

这是 MICCAI 2022 ACR-NVIDIA-NCI 乳腺密度 FL 挑战赛 中使用的参考实现。

数字病理学

全切片肿瘤检测

该示例展示了如何在全切片组织病理学图像上训练和评估基于补丁分类的肿瘤检测模型。

全切片肿瘤检测性能分析

该示例展示了如何使用 MONAI NVTX 转换器标记并分析数字病理学全切片肿瘤检测流程中的预处理和后处理转换。

多实例学习 WSI 分类

这是一个基于前列腺组织病理学全切片图像（WSI）的多实例学习（MIL）分类示例。

NuClick 注释

该笔记本演示了带有交互式注释的病理学训练和推理流程示例。NuClick 用于勾勒细胞核、细胞以及描绘腺体轮廓的波浪线。

HoVerNet：核分割与分类任务

本教程演示了如何使用 CoNSep 数据集构建 HoVerNet 在核分割与分类任务上的训练流程。

细胞核分类

该笔记本演示了带有交互式注释的病理学训练和推理流程示例。NuClick 用于勾勒细胞核、细胞以及描绘腺体轮廓的波浪线。

加速

fast_model_training_guide

本文档介绍了如何对训练流程进行性能剖析、如何分析数据集并选择合适的算法，以及如何优化单 GPU、多 GPU 甚至多节点环境下的 GPU 利用率。

distributed_training

这些示例展示了如何基于三种不同框架执行分布式训练和评估：

• PyTorch 原生 DistributedDataParallel 模块配合 torch.distributed.launch。
• Horovod API 配合 horovodrun。
• PyTorch ignite 和 MONAI 工作流。

这些示例可以在多个分布式节点上运行，每个节点配备多块 GPU 设备。

automatic_mixed_precision

该笔记本比较了启用与禁用 AMP 时的训练速度和内存使用情况。

dataset_type_performance

该笔记本比较了 Dataset、CacheDataset 和 PersistentDataset 的性能。这些类在数据存储方式（内存或磁盘）以及应用转换的时间点上有所不同。

fast_training_tutorial

本教程比较了基于 NVIDIA GPU 设备和最新 CUDA 库的纯 PyTorch 程序与经过 MONAI 优化后的程序的训练性能。优化方法主要包括：AMP、CacheDataset、GPU 转换、ThreadDataLoader、DiceCELoss 和 SGD。

threadbuffer_performance

该笔记本演示了 ThreadBuffer 类的使用，它可以在单独的线程中生成训练过程中的数据批次。

transform_speed

该笔记本说明了读取 NIfTI 文件的过程，并测试了不同转换在不同设备上的速度。

TensorRT 推理加速

该笔记本展示了如何使用 TensorRT 加速模型，以获得更低的推理延迟。

模型库

easy_integrate_bundle

本教程展示了一种简单的集成应用，指导用户如何将现有包集成到自己的项目中。只需更改数据路径和包所在路径，即可进行训练和集成推理。

计算机辅助介入

视频分割

本教程展示了如何训练一个手术器械分割模型，以在给定图像中定位器械。此外，还构建了一个端到端视频器械分割的示例流程，包含视频输入和输出。

内窥镜体内分类

本教程展示了基于相应预训练包对内窥镜体内分类模型进行微调的流程。

Hugging Face

MONAI Hugging Face 流水线

本教程演示了如何将现有的 MONAI 模型工作流封装成 Hugging Face 流水线，这种流水线在开源社区中被广泛采用。

针对 Hugging Face 流水线的微调

本教程解释了微调 VISTA3D 模型并将其集成到 Hugging Face 流水线中进行推理的过程。

模块

bundle

关于 MONAI 包功能的入门教程及具体的训练/推理示例。

competitions

基于 MONAI 的医疗影像竞赛解决方案。

engines

基于 UNet3D 和合成数据集的 3D 分割训练和评估示例，使用 MONAI 工作流，其中包含引擎、事件处理器和后处理转换。此外，还有一个医学图像生成对抗网络的 GAN 训练和评估示例。简易运行的训练脚本使用 GanTrainer 来训练一个 2D CT 扫描重建网络。评估脚本则从已训练好的网络中生成随机样本。

这些示例基于 MONAI 工作流构建，主要包括：训练器/评估器、处理器、后处理转换等。

3D图像变换

本笔记本演示了对体积图像的各类变换操作。

2D推理3D体积

本教程展示了当需要将3D体积输入逐切片地提供给2D模型，并最终聚合为3D体积时，如何使用 MONAI 的 SlidingWindowInferer。

自编码器MedNIST

本教程使用 MedNIST 手部CT扫描数据集来演示 MONAI 的自编码器类。自编码器既可用于身份编码/解码（即输入什么就应得到什么），也可用于去模糊和去噪。

批量输出转换

本教程解释并演示如何设置处理器的 batch_transform 和 output_transform，以配合 MONAI 引擎工作。

弯曲能量扩散损失说明

本笔记本演示了何时以及如何计算归一化的弯曲能量和扩散损失。

计算指标

示例展示了如何利用 PyTorch 多进程支持，从已保存的预测结果和标签中计算指标。

CSV数据集

本教程展示了 CSVDataset 和 CSVIterableDataset 的用法，包括加载多个 CSV 文件并执行后处理逻辑。

批处理解耦

本教程展示了如何将批次数据解耦，以简化后处理转换，并执行更灵活的后续操作。

图像数据集

本笔记本介绍了 monai.data.ImageDataset 模块的基本用法。

dynUNet教程

本教程展示了如何在 MONAI 中重新实现 dynUNet，并利用它在所有10个Decathlon数据集上训练3D分割任务。

集成第三方变换

本教程展示了如何将第三方变换集成到 MONAI 程序中。主要演示了来自 BatchGenerator、TorchIO、Rising 和 ITK 的变换。

逆变换与测试时增强

本笔记本演示了可逆变换的使用，以及如何利用逆变换进行测试时增强。

分层学习率

本笔记本演示了如何选择或过滤出期望的网络层，并为其设置自定义的学习率值。

学习率查找器

本笔记本演示了如何使用 LearningRateFinder API 来调整网络的学习率。

加载医学图像

本笔记本介绍了如何在 MONAI 中轻松加载不同格式的医学图像，并执行多种附加操作。

MedNIST GAN教程

本笔记本说明了如何使用 MONAI 训练一个网络，使其能够根据随机输入张量生成图像。这里采用了一个简单的GAN架构，包含独立的生成器和判别器网络。

MedNIST GAN工作流字典版

本笔记本展示了用于模块化对抗学习的 MONAI 工作流引擎 GanTrainer。使用 MedNIST 手部CT扫描数据集训练医学图像重建网络。字典版本。

MedNIST GAN工作流数组版

本笔记本展示了用于模块化对抗学习的 MONAI 工作流引擎 GanTrainer。使用 MedNIST 手部CT扫描数据集训练医学图像重建网络。数组版本。

交叉验证与模型集成

本教程展示了如何利用 MONAI 中的 CrossValidation、EnsembleEvaluator、MeanEnsemble 和 VoteEnsemble 模块，搭建交叉验证和集成程序。

NIfTI文件读取示例

演示如何读取 NIfTI 文件，并遍历从中加载的体积图像切片。

网络API

本教程展示了灵活的网络API和实用工具。

后处理变换

本笔记本展示了基于脾脏分割任务模型输出的几种后处理变换的用法。

公开数据集

本笔记本展示了如何基于 MedNISTDataset 和 DecathlonDataset 快速搭建训练流程，以及如何创建新的数据集。

TCIA CSV处理

本笔记本展示了如何使用 CSVDataset 从CSV文件加载TCIA数据，并提取信息以便通过REST API获取DICOM图像。

2D变换演示

本笔记本演示了使用……对组织学图像进行的图像变换。

UNet输入尺寸约束

本教程展示了如何为 MONAI UNet 确定合理的输入数据空间尺寸，该UNet不仅支持残差单元，还可以使用比基础UNet实现更多的超参数（如 strides、kernel_size 和 up_kernel_size）。

TorchIO、MONAI、PyTorch Lightning

本笔记本演示了如何将来自官方 PyTorch 生态系统的这三款库协同使用，以对来自 Medical Segmentation Decathlon 的脑部MRI图像进行海马体分割。

变分自编码器MedNIST

本教程使用 MedNIST 扫描数据集（或MNIST数据集）来演示 MONAI 的变分自编码器类。

可解释性

本文件夹中的教程展示了 MONAI 的模型可视化和可解释性功能。目前包括针对3D分类模型的类激活映射和遮挡敏感性分析。

变换可视化

本教程展示了在变换增强过程中对3D图像的几种可视化方法。

Auto3DSeg

本文件夹展示了如何使用最少的输入运行全面的 Auto3DSeg 流程，并根据不同的用户需求自定义 Auto3Dseg 模块。

自监督学习

self_supervised_pretraining

本教程展示了如何构建一个利用无标签数据的自监督学习训练流程。教程演示了如何在TCIA数据集上对无标签的新冠肺炎病例进行模型训练。

self_supervised_pretraining_based_finetuning

本教程展示了如何利用基于无标签数据的自监督学习框架中预训练得到的权重。教程演示了使用预训练权重进行多类别三维分割任务的模型训练方法。

生成模型

3D 潜在扩散模型

本教程展示了训练和验证3D潜在扩散模型的应用场景。

2D 潜在扩散模型

本教程展示了训练和验证2D潜在扩散模型的应用场景。

Brats 3D 潜在扩散模型

示例展示了在Brats 2016和2017数据上训练和验证3D潜在扩散模型的应用场景，是对上述笔记本内容的扩展。

MAISI 3D 潜在扩散模型

示例展示了训练和验证Nvidia MAISI（用于合成成像的医学人工智能）模型的应用场景，该模型是一种3D潜在扩散模型，能够生成带有配对分割掩码的大尺寸CT图像，支持可变的体积大小和体素分辨率，并且可以控制器官或肿瘤的大小。

SPADE 在VAE-GAN中的应用：用于2D BraTS数据的语义图像合成

示例展示了将基于VAE-GAN的语义图像合成神经网络SPADE应用于BraTS数据子集的方法。该子集已注册到MNI空间并重采样为2mm各向同性分辨率，其分割结果是通过测地信息流（GIF）获得的。

将潜在扩散模型应用于2D BraTS数据以实现语义图像合成

示例展示了按照Wang等人的方法，将SPADE归一化技术应用于潜在扩散模型，从而在已注册到MNI空间并重采样为2mm各向同性分辨率的BraTS数据子集上进行语义图像合成，其分割结果同样由测地信息流（GIF）提供。

用于隐式图像分割集成的扩散模型

示例展示了如何使用MONAI结合DDPMs对图像进行2D分割。同样的结构也可以用于条件图像生成或图像到图像的转换任务。

评估生成图像的真实性和多样性

示例展示了如何使用MONAI通过计算弗雷歇起始距离（FID）、最大均值差异（MMD）等指标来评估生成模型的真实性，以及使用MS-SSIM和SSIM来评估图像的多样性。

VISTA2D

本教程演示了如何使用MONAI框架和Segment Anything Model (SAM)，基于Cellpose数据集训练细胞分割模型。 ECHO°¡ ¼³Á¤µÇ¾î ÀÖ½À´Ï´Ù.

MONAI Tutorials 快速上手指南

本指南帮助中国开发者快速配置并运行 MONAI 官方教程，涵盖环境搭建、安装步骤及基础验证。

1. 环境准备

在开始之前，请确保您的开发环境满足以下基本要求：

• 操作系统：Linux, macOS 或 Windows (推荐 Linux 以获得最佳兼容性)
• Python 版本：建议 Python 3.8+
• 核心依赖：
  • Jupyter Notebook：用于运行交互式教程。
  • Matplotlib：用于数据可视化。
• 硬件加速（可选但推荐）：如需运行 3D 分割或训练任务，建议使用支持 CUDA 的 NVIDIA GPU。

2. 安装步骤

基础依赖安装

首先升级 pip 并安装核心工具：

python -m pip install -U pip
python -m pip install -U matplotlib
python -m pip install -U notebook

安装 MONAI 及可选依赖

根据您的需求选择以下一种方式安装：

方式 A：按需安装（推荐） 如果遇到导入错误，请参考 MONAI 安装指南 安装特定包。

方式 B：安装所有可选依赖 一次性安装开发所需的所有依赖包（注意：国内网络环境下下载可能较慢，建议配置镜像源）：

# 使用清华镜像源加速安装（推荐国内用户）
pip install -r https://raw.githubusercontent.com/Project-MONAI/MONAI/dev/requirements-dev.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

Google Colab 用户专属配置

如果您在 Google Colab 中运行，默认环境可能存在版本冲突。请显式安装兼容的 PyTorch 2.6 和 MONAI 1.5：

# Install PyTorch 2.6.0 with CUDA 12.4
pip install --index-url https://download.pytorch.org/whl/cu124 \
  torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0

# Install MONAI and common dependencies
pip install "monai[all]" nibabel pydicom ipywidgets==8.1.2

注意：在 Colab 中使用时，请务必将运行时类型更改为 GPU (Runtime -> Change runtime type -> GPU)。

3. 基本使用

获取教程代码

克隆官方教程仓库到本地：

git clone https://github.com/Project-MONAI/tutorials.git
cd tutorials

运行快速烟雾测试 (Smoke Test)

运行一个简单的 3D 分割训练脚本，验证环境是否配置正确。该脚本将运行 2 个 epoch，使用小批量数据以节省时间。

cd 3d_segmentation/torch
python -u unet_training_array.py --max_epochs 2 --batch_size 1 --num_workers 2

验证成功标准： 如果日志中显示训练损失（training loss）逐渐下降，并输出了 Dice 分数，则说明环境配置成功。

直接使用 Jupyter Notebook

大多数教程位于各个子目录下的 .ipynb 文件中。启动 Jupyter Notebook 即可直接浏览和运行：

# 在 tutorials 根目录下执行
jupyter notebook

提示：许多 Notebook 文件顶部包含 "Open in Colab" 按钮，右键点击选择在新标签页打开，即可直接在云端运行。

数据说明

部分教程需要额外的数据集（如 MedNIST, IXI, MSD 等）。请根据具体 Notebook 中的说明下载数据，并务必检查数据集的许可协议以确保符合您的使用场景。