1. 写在前面MONAI是什么为什么要装它第一次听到MONAI这个名字是在一次医学影像组学项目的技术选型会上。当时团队需要在PyTorch框架下做器官分割模型的训练纯手写U-Net的数据管道、增强策略、评估指标工程量确实不小。后来同事扔过来一个链接说“试试这个专门为医疗影像设计的框架”我打开GitHub一看好家伙14k的starNVIDIA和伦敦国王学院联合出品底层封装的是PyTorch原生算子——这就是MONAI。先给还不熟悉的朋友做个定位。MONAI的全称是Medical Open Network for AI它不是一个独立的深度学习框架而是构建在PyTorch之上的医学影像专用工具箱。你可以把它理解成一套“医疗影像领域的高层封装API”专门解决医学数据加载、预处理、网络结构、损失函数、评估指标这些高频重复的脏活累活。比起直接用PyTorch从零搭建MONAI能帮你在数据处理和训练流程上省下大约三分之一的时间而且它原生兼容PyTorch的张量操作。如果你手里有医学影像数据比如CT、MRI、病理切片想跑分割、分类、配准或者检测任务MONAI几乎是你绕不开的一个选择。这篇博客面向的是两类读者一是刚开始接触医学影像深度学习的研究生和工程师二是已经在用PyTorch但想提升医疗项目开发效率的从业者。我会把安装过程中涉及的每一个关键点都拆开来讲包括硬件准备、Python环境管理、PyTorch版本对应关系、MONAI的CPU/GPU安装细节、以及验证环节最后附上我自己踩过的坑。整个流程照着走正常情况下半小时内能从零到能跑起一个官方的3D分割demo。2. 安装前的必备功课硬件、驱动和Python版本2.1 GPU和CUDA版本的确定方法MONAI最核心的依赖是PyTorch而PyTorch的GPU版本安装绕不开CUDA这个坎。很多人在安装阶段翻车不是MONAI本身的问题而是PyTorch和CUDA版本不匹配。所以第一步先搞清楚你自己的机器是什么显卡。先看NVIDIA显卡型号和驱动支持的CUDA版本。在命令行里执行nvidia-smi注意看右上角显示的CUDA Version比如我机器上显示的是CUDA Version: 12.1这表示你当前的NVIDIA驱动最高支持CUDA 12.1版本。这个数字是驱动决定的不是说你机器上已经装了CUDA 12.1的完整工具链而是说“最多可以兼容到这个版本”。第二步根据这个驱动版本选择对应PyTorch的CUDA变体。以当前主流版本为例NVIDIA驱动支持的CUDA版本推荐的PyTorch编译CUDA版本说明11.8及以上cu118PyTorch 2.0-2.1普遍支持12.1及以上cu121PyTorch 2.1及以上版本支持12.4及以上cu124PyTorch 2.4支持如果你用的是30系、40系显卡驱动通常都是新的直接选最新的cu121或cu124都不会有太大问题。如果你还在用10系、20系的老卡建议选择合适的驱动用cu118也行不需要追新。2.2 Python版本到底选哪个MONAI官方文档目前明确支持Python 3.8到3.12。不过我的建议是直接选3.9或3.10原因有两个一是这两个版本对PyTorch各类版本的兼容性最好二是一些编译依赖的wheel包比如monai依赖的nibabel、scipy在新版本上可能有预编译轮子装起来省心。我自己用的是Python 3.10.13配合PyTorch 2.3.1cu121跑MONAI 1.3.0半年下来没出过兼容性问题。需要特别提醒的是别用最新的Python版本比如当前Python 3.13不少医学影像相关的依赖库可能还没有完成适配。MONAI这种依赖链比较深的项目保守一点没有坏处。2.3 安装Anaconda或Miniconda更省心Python环境管理工具我强烈推荐conda系列Mini和Anaconda都可以。如果你之前没有装过建议装Miniconda体积小占用少创建环境的能力一点都不缺。直接去官网下载对应你系统的安装包Windows装exeLinux装shell脚本。安装完之后建议先看一下conda版本conda --version如果是conda 22.9以上的版本通常都会默认支持conda create后面跟-y参数自动确认比较方便。如果觉得默认的镜像源下载包太慢可以配置国内镜像源具体配置方法我放到后面的常见问题章节去讲。3. 搭建独立环境为什么强烈建议用虚拟环境3.1 创建虚拟环境的操作MONAI的安装最好放在一个独立的Python虚拟环境里不要直接装在base环境或者系统Python里。因为MONAI和PyTorch的版本迭代速度都比较快而且它们依赖的底层库如nibabel、pydicom可能会跟其他项目的依赖版本产生冲突。用虚拟环境隔离是最干净的做法。创建环境的命令非常简单conda create -n monai python3.10 -y conda activate monai激活成功后命令行前面会有一个(monai)前缀。如果你用的是Windows的PowerShell可能是(monai) PS C:\Users\xxx的样子。看到这个前缀就说明你已经进入了一个独立环境。3.2 配置pip镜像源加快下载速度在安装PyTorch或MONAI之前推荐先检查一下pip的镜像源。如果你直接用官方PyPI源下载速度在有些网络环境下可能不太理想。我一般会先切换成国内镜像源比如清华源pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple如果你用的是conda环境也可以额外配置conda的.condarc文件来加速conda install的进度channels: - defaults show_channel_urls: true default_channels: - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2 custom_channels: conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud不过注意PyTorch的官方安装命令推荐用conda源conda会自动帮你处理CUDA相关的依赖链比pip处理得更干净。但也存在一个缺点conda源里的PyTorch版本常常有滞后有时官方最新版还没同步到conda。所以更灵活的方案是用pip从PyTorch的官方index安装加一个URL指定CUDA版本即可。4. 正式安装从PyTorch到MONAI完整实录4.1 安装PyTorchCPU版和GPU版分开讲MONAI依赖PyTorch所以必须先装好PyTorch。根据你的硬件条件分成两条路。路线A没有独立显卡或只跑推理预处如果你用的是集成显卡的笔记本或者暂时不想折腾CUDA可以先装CPU版的PyTorch。CPU版本跑小型数据集的训练和验证是没问题的只是大规模训练速度和GPU相比会有明显差距。pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu这样装的PyTorch不依赖CUDA工具链安装包体积也小一些。虽然名字叫CPU版但你在MONAI里的数据加载、预处理、模型推理代码完全不用改只是底层计算都跑在CPU上。路线B有NVIDIA GPU正常安装nvidia-smi显示驱动支持CUDA 12.1那我建议直接安装cu121版本pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121如果你的驱动更老只支持到11.8就改成pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118这里有一个非常常见的误区很多人以为还需要手动去NVIDIA官网下载并安装完整的CUDA Toolkit然后配置CUDA_HOME环境变量。实际上用pip安装的PyTorch自带CUDA运行时组件不需要额外安装完整工具链。只有在需要自己编译CUDA扩展算子的时候才需要装完整的CUDA Toolkit。装完之后验证一下GPU是否对PyTorch可见python -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))输出结果应该是这样的2.3.1cu121 True NVIDIA GeForce RTX 4090如果torch.cuda.is_available()返回的是False那就说明CUDA相关的依赖没配置好需要回过来检查驱动版本或PyTorch的编译CUDA版本。这一步是后面所有工作的前提务必确认正确。4.2 安装MONAI核心库PyTorch就位之后MONAI本体安装几乎没有障碍。直接一句话pip install monai这会把MONAI连同它的核心依赖一起装上包括nibabel医学影像格式读写、numpy、scipy、Pillow、pydicom等。由于MONAI的依赖链比较丰富安装过程可能需要下载几百MB的包耐心等待即可。如果你需要更多扩展功能比如医学影像的预处理增强、可视化调试用的itk支持可以安装带扩展的版本pip install monai[nibabel,itk,tqdm,fire]itk是一个比较重的依赖主要用于处理一些nibabel不直接支持的格式和可视化操作如果一开始不确定需不需要可以先跳过等用到再装也不迟。安装完成之后验证一下MONAI版本python -c import monai; print(monai.__version__)如果输出类似1.3.0说明MONAI已经成功装进了当前环境。4.3 通过源码安装可选方案普通用户用不上现在MONAI的发布节奏是约三个月一个release版本通过pip安装的基本够用。但如果你的项目直接依赖了官方GitHub仓库的最新改动比如新修复的bug或者新增的融合模块那就需要从源码安装。做法是先克隆仓库然后再用pip以可编辑模式安装git clone https://github.com/Project-MONAI/MONAI.git cd MONAI pip install -e .[all]需要注意的是源码安装对build工具链的要求更高需要确保build和setuptools是最新的。而且pip install -e再配合[all]选项会安装大量扩展依赖在国内网络环境下下载时间会比较长。普通场景下我不推荐首选这种方式。5. 验证安装跑一个官方的3D分割Demo5.1 demo代码执行流程装好之后最怕什么最怕代码一跑就报“module not found”。与其等到项目里再排查不如装完立刻验证。MONAI官方文档里提供了一个端到端的3D分割demo虽然篇幅不长但覆盖了数据下载、预处理、模型构建、训练循环、评估指标这几个关键环节。我自己复现过一次代码大概长这样import monai import torch from monai.networks.nets import UNet from monai.transforms import ( EnsureChannelFirstd, Compose, LoadImaged, ScaleIntensityd, RandSpatialCropd, RandRotate90d, ToTensord, ) from monai.data import CacheDataset, DataLoader, decollate_batch from monai.losses import DiceLoss from monai.metrics import DiceMetric from monai.data import decollate_batch整个demo涉及的核心流程是通过LoadImaged读取NIfTI格式的影像经过EnsureChannelFirstd确保通道维度在前ScaleIntensityd做强度归一化RandSpatialCropd做随机裁剪生成训练样本最后组装一个3D的U-Net模型并开始训练。如果你在跑这个demo的第一步就报错多数情况是数据下载的问题因为官方demo默认会从网上下载一个公开的医学影像样例数据集。如果下载不顺畅可以直接去MONAI的GitHub页面单独下载数据手动放进代码指定的目录。5.2 测试数据下载与目录结构以官方推荐方式执行的demo会在当前目录下创建dataset文件夹里面存放训练集、验证集和测试集。官方样例数据是一个前列腺MRI数据集来自Medical Segmentation Decathlon一共大约几十个病例下载下来有几百MB。如果你不想等完整下载也可以先用一个小样本做冒烟测试。随便找一个NIfTI格式的文件把它处理成MONAI能接受的格式比如dataset/ ├── images/ │ └── sample.nii.gz └── labels/ └── sample_seg.nii.gz然后改写demo中读取数据的路径利用CacheDataset把预处理后的数据缓存到内存或磁盘跑上两步训练循环确认前向和反向传播都没问题就能证明MONAI安装到位了。5.3 训练和推理的快速确认我实际测试时用的是一张入门级的GTX 1660 Ti显卡6GB显存。MONAI的官方训练demo把图像裁剪成了[128, 128, 64]这样的尺寸batch size设置为2跑起来显存占用在4GB左右刚好放得下。如果你的显卡比这个还老或者显存只有4GB建议把裁剪尺寸和batch size调小一点。跑完一个epoch之后Dice指标应该在0.5左右说明模型确实在学习不是瞎跑。如果打印出来的loss一直是nan那大概率是数据预处理出了问题比如某些图像在全零裁剪块上没有有效标签这种情况下排除掉空样本就行。6. 安装过程中最容易踩的五个坑附解决方案这一节是全文最有价值的部分。我实际安装MONAI的次数加起来超过十次了每次遇到的坑都不太一样但归类下来就下面这几种情况记下来能帮后面的人少走弯路。6.1 PyTorch装成了CPU版GPU用不上这是最常见的坑。症状是import torch之后torch.cuda.is_available()返回False。查了原因有的人是先装了CPU版后来加了--index-url重新装GPU版但没带--force-reinstall导致pip认为模块已存在跳过安装。解决办法很简单强制重新安装pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 --force-reinstall6.2 不同版本的MONAI API调用方式差异较大MONAI从0.9到1.0是个大版本跃迁很多API改了名字或调整了参数。比如之前很常用的Compose在较新版本里加了ensure_shape之类的参数控制RandSpatialCropd的使用方式也有调整。如果看的教程是旧版本的代码在1.x版本上跑会报错这时候不要硬用旧语法建议直接查一下当前版本对应的官方文档。建议安装时直接装最新版教程也要找匹配的。6.3 下载数据慢或超时MONAI官方demo里的数据源在国外服务器上国内直连下载经常很慢甚至断流。解决思路有三种一是用支持断点续传的下载工具手动下载数据二是从数据集官网找到同样的数据用镜像渠道下载三是让周围同学分享一份已验证的样例数据。数据文件只要放到代码预期的目录结构上就能正常跑通。6.4 conda环境内pip安装权限问题在conda环境下有时候会出现“ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied”的报错。看起来像权限问题但本质上是pip试图往系统目录安装。解决办法是把pip升级到新版并显式指定安装到当前环境python -m pip install --upgrade pip python -m pip install monai使用python -m pip这个格式比直接输入pip更稳妥因为它会明确调用当前Python环境对应的pip。6.5 nibabel版本冲突导致加载NIfTI时报错nibabel是MONAI读取.nii.gz文件的核心依赖。如果你把MONAI装进了base环境而base环境里又跑了一些老的医学影像处理项目nibabel可能升到了新版本某些接口弃用了造成加载数据时的间接报错。这种情况用虚拟环境隔离就能从根源上避免。如果在同一环境里非要同时用不同依赖版本只能考虑用pip install nibabel2.5.1这类锁定版本的方式临时解决。7. 日常工作中的MONAI环境管理经验7.1 用requirements文件锁定环境环境配好之后我强烈建议导出一份依赖清单放进项目的requirements.txt里。这样无论换机器还是后来了新同事加入一条命令就能复现pip freeze requirements.txt不过要注意pip freeze会把环境中所有包都列出来包括一些间接依赖。更精确的做法是只记录顶层依赖手动写上monai、torch、torchvision等然后注明Python版本和CUDA版本信息。7.2 多版本MONAI并存的思路深度学习的项目迭代快经常遇到不同项目需要不同MONAI版本的情况。此时可以创建多个conda环境每个环境装不同版本的MONAI用环境名区分即可conda create -n monai1.2 python3.10 -y conda create -n monai1.3 python3.10 -y这是最优雅的方案比在同一个环境里来回卸载重装要省心得多。因为MONAI的依赖链比较重频繁卸载重装既浪费时间也容易在残留文件上产生隐患。7.3 无GPU环境下的MONAI使用建议如果你所在的实验室服务器有多张GPU但你没有root权限也不要担心。miniconda装到自己的用户目录下创建的虚拟环境也是放在用户目录完全不需要sudo权限。pip安装PyTorch时也是同理CUDA相关的运行库会被pip装到用户级目录而不是系统目录不会影响其他人。唯一需要注意的问题是在无GPU的本地环境调试MONAI的数据管道时很多代码逻辑跟GPU训练逻辑是分开的。你可以用CPU版PyTorch跑数据加载和预处理逻辑调通了再把同样的环境复现到GPU服务器上这样效率更高。7.4 MONAI环境变量和缓存目录MONAI默认会使用~/.cache/monai作为缓存目录包括下载的数据集和临时文件都会存到这里。如果服务器home目录空间有限可以通过环境变量指定缓存位置。在.bashrc里加上export MONAI_DATA_DIR/your/large/disk/monai_data也可以直接设置TMPDIR让临时文件写到更大的分区。这一点在跑大规模3D数据集时尤其重要我见过有人的home目录只有20GB数据集几十个GB肉眼可见地塞满然后无穷无尽的报错。8. 一次实际安装过程的完整记录为了让大家看得更直观我把我自己最近一次在某台新到手的Linux服务器上安装MONAI的过程完整记录在这里。这台机器就是普通配置RTX 3090显卡驱动支持的CUDA版本是12.2系统是Ubuntu 22.04。以下是关键操作步骤和当时的终端输出# 检查显卡驱动支持的CUDA版本 (base) userserver:~$ nvidia-smi # 输出里看到 CUDA Version: 12.2 # 创建独立环境 (base) userserver:~$ conda create -n monai python3.10 -y # 激活环境 (base) userserver:~$ conda activate monai # 检查Python版本 (monai) userserver:~$ python --version Python 3.10.13 # 安装PyTorch GPU版 (monai) userserver:~$ pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 # 验证PyTorch和GPU (monai) userserver:~$ python -c import torch; print(torch.__version__, torch.cuda.is_available()) 2.1.2cu121 True # 安装MONAI (monai) userserver:~$ pip install monai # 验证MONAI (monai) userserver:~$ python -c import monai; print(monai.__version__) 1.3.0整个过程不到十五分钟。然后我直接跑了一个MONAI官方的分类训练示例来测试端到端流程输入图像尺寸设为96x96x96batch size为4在RTX 3090上迭代速度大概是每秒8步左右GPU利用率从刚开始的50%慢慢稳定到了90%以上说明CUDA相关的资源调用一切正常。这里需要提醒一下安装完MONAI之后GPU利用率刚开始跑不高是常见现象。因为医学影像数据加载和预处理通常是IO密集型的如果DataLoader的num_workers设置得太低数据供给跟不上GPU计算速度就会导致GPU空转。解决办法是把num_workers调到8或更高同时配合MONAI的CacheDataset预先缓存处理后的数据效率会立刻好很多。关于这些后面写训练调优的经验时再展开。9. 扩展MONAI生态中值得关注的配套工具MONAI本身只是地基上面还能搭起不少实用的工具。安装阶段虽然只需要装上核心库就够了但提前了解生态对你后续选型有好处。9.1 MONAI LabelMONAI Label是MONAI生态中做交互式标注的工具可以在标注软件中集成深度学习模型作为辅助工具。如果你以后要做医学影像数据标注并且希望用模型来半自动标注可以考虑关注一下。它的安装依赖MONAI装好MONAI之后再装MONAI Label会顺畅很多。9.2 MONAI DeployMONAI Deploy专注于把训练好的模型打包成可供临床或科研环境使用的应用解决了模型部署环节的工程化问题。如果你的项目最终要交付给医院或者合作伙伴使用这个工具挺关键但目前还不太适合快速上手建议先把MONAI几个核心模块用熟练。9.3 MONAI Core中的常用子模块MONAI Core本身按功能划分了几个子模块其中monai.transforms是最核心也最常用的部分。数据增强、归一化、裁剪、旋转等预处理操作在医学影像场景下基本都要用到。其次就是monai.networks里面封装了U-Net、Attention U-Net、Swin-UNETR等常用网络结构省去了大量手写模型的时间。如果想先熟悉一个子模块就从transforms入手。9.4 和PyTorch配合的典型目录结构在实际项目中我一般会这样组织代码和目录project/ ├── datasets/ │ ├── imagesTr/ │ ├── labelsTr/ │ └── imagesTs/ ├── configs/ │ └── config.yaml ├── scripts/ │ ├── train.py │ ├── evaluate.py │ └── infer.py ├── models/ └── requirements.txt把数据、配置、脚本分离是为了让项目更容易复现。MONAI的官方示例代码往往把数据路径直接写死在脚本里这在跑通demo阶段没问题但真正进入项目开发阶段还是要用yaml或者json把路径和超参数管理起来。我这里提一嘴是因为很多入门者一开始不注意目录规范后面数据一多就乱了。10. 一些使用习惯上的忠告安装只是万里长征第一步但有几点习惯如果能从入门阶段就养成后面会省很多事。第一每次安装新包之前记下当前环境的版本快照。这样如果装出问题方便回溯和对比。pip list --formatfreeze before.txt pip install somepackage pip list --formatfreeze after.txt diff before.txt after.txt这个习惯的成本几乎为零但调试时有它你能很快知道是哪一步引入的问题。第二别盲目使用--upgrade升级包。MONAI和PyTorch在的生态里经常出现“升级一个包导致另一个包的API不兼容”的情况。如果不是明确需要新特性锁定目前的稳定版本会更省心。第三定期关注MONAI的Release Notes。官方每出一个新版本都会在GitHub的Release页面列出改动包括新增模块、API变动、bug修复。有时候一个版本修复的问题正是你之前苦思冥想解决不了的。文字不长读一下花不了几分钟。第四在自己的环境里随手跑通所有官方示例。MONAI官方仓库的tutorials文件夹里包含了大量从入门到进阶的notebook比如3D分割、2D分类、医学影像配准、模型可解释性分析等。找一个空闲的下午把它们全部跑一遍比你翻十篇博客都管用。安装完成只是开始真正熟练是靠在真实数据上反复调试磨出来的。第五也是最重要的善用MONAI社区。MONAI在GitHub上有官方的Discussion版区还在月度例会上同步开发进展。遇到报错把日志和版本信息贴出来开发者回应速度挺快的。医学影像AI这个圈子不算大大家遇到的坑高度重合你问的问题大概率被之前的人踩过。谈到这儿MONAI的安装算是完整梳理了一遍。从确认驱动版本、搭建Python环境到安装PyTorch和MONAI本体再到验证和排查常见问题每一步都有明确的检查点和判断标准。后续我会继续更新这个系列包括MONAI的数据加载细节、transforms怎么用、如何搭建自己的3D分割网络、训练过程中的调优经验等欢迎持续关注。