本篇学习目标

这是《nnU-Net 0基础入门》系列的第 7 篇。前面我们已经完成训练和最佳配置选择。本文把推理和评估串起来：怎样批量预测，什么时候保存 probabilities，如何 ensemble 和 postprocessing，以及怎样计算基础 Dice 指标。

读完本文，你应该能够：

1. 正确准备 nnUNetv2_predict 的输入目录。
2. 理解 --save_probabilities、nnUNetv2_ensemble 和 nnUNetv2_apply_postprocessing 的作用。
3. 知道何时使用 inference_instructions.txt。
4. 用官方评估入口计算预测结果和 ground truth 之间的 Dice。

1. 推理前先确认输入命名

推理就是用训练好的模型对新图像生成分割结果。nnU-Net v2 的推理输入不是随便放图像就行，而是必须匹配训练数据集的命名规则和文件后缀。

单通道输入示例：

input_images/
├── case_001_0000.nii.gz
└── case_002_0000.nii.gz

两通道输入示例：

input_images/
├── case_001_0000.nii.gz
├── case_001_0001.nii.gz
├── case_002_0000.nii.gz
└── case_002_0001.nii.gz

这里的 _0000、_0001 是 channel 编号。推理输入没有标签文件，因为标签正是模型要预测的结果。

2. 最基础的预测命令

官方推理文档给出的基础命令是：

nnUNetv2_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -d DATASET_NAME_OR_ID -c CONFIGURATION

例如：

nnUNetv2_predict \
  -i ./input_images \
  -o ./predictions_3d_fullres \
  -d 1 \
  -c 3d_fullres

参数解释：

参数	含义
-i	输入图像目录
-o	预测结果输出目录
-d	数据集编号或名称
-c	configuration，例如 2d 或 3d_fullres

官方文档提醒：如果你已经运行过 nnUNetv2_find_best_configuration，应优先使用它生成的 inference_instructions.txt。这个文件会写出推荐推理命令，尤其在使用 ensemble 和 postprocessing 时更可靠。

3. fold 的选择：默认 5 folds ensemble

官方推理文档说明，默认情况下推理会使用 5 个已训练 fold 做 ensemble。也就是说，如果你训练了 fold 0 到 fold 4，默认推理会组合这些模型。

如果你训练的是 all fold，并且只想用这个模型，可以显式指定：

nnUNetv2_predict \
  -i ./input_images \
  -o ./predictions_all \
  -d 1 \
  -c 3d_fullres \
  -f all

all fold 通常指用全部训练数据训练一个模型。它适合最终训练，但没有独立验证 fold，因此不应用来替代前面的 5-fold 模型选择过程。

4. 什么时候保存 probabilities

默认预测结果通常是最终分割标签。如果后面要做不同 configuration 的 ensemble，就需要保存概率输出：

nnUNetv2_predict \
  -i ./input_images \
  -o ./predictions_3d_fullres \
  -d 1 \
  -c 3d_fullres \
  --save_probabilities

probabilities 指模型对每个类别的概率图。ensemble 不是简单投票文件名，而是需要这些概率文件作为输入。官方文档明确说明，nnUNetv2_ensemble 的输入目录必须包含由 --save_probabilities 生成的 probability files。

5. 多配置 ensemble

假设你分别预测了 2d 和 3d_fullres，并且都保存了 probabilities：

nnUNetv2_predict \
  -i ./input_images \
  -o ./predictions_2d \
  -d 1 \
  -c 2d \
  --save_probabilities

nnUNetv2_predict \
  -i ./input_images \
  -o ./predictions_3d_fullres \
  -d 1 \
  -c 3d_fullres \
  --save_probabilities

然后可以 ensemble：

nnUNetv2_ensemble \
  -i ./predictions_2d ./predictions_3d_fullres \
  -o ./predictions_ensemble \
  -np 8

-np 表示使用的进程数。ensemble 可能提升稳定性，但会增加推理成本。正式项目里，应优先参考 find_best_configuration 的推荐，而不是盲目 ensemble 所有配置。

6. 应用 postprocessing

如果 find_best_configuration 推荐了后处理，可以使用官方推理文档中的命令形式：

nnUNetv2_apply_postprocessing \
  -i FOLDER_WITH_PREDICTIONS \
  -o OUTPUT_FOLDER \
  --pp_pkl_file POSTPROCESSING_FILE \
  -plans_json PLANS_FILE \
  -dataset_json DATASET_JSON_FILE

这里不要凭记忆填写路径。官方文档说明，单配置预测时 plans.json 和 dataset.json 通常会自动复制；ensemble 输出则需要显式提供。实际使用时，优先直接复制 inference_instructions.txt 中给出的完整命令，那里会包含当前实验对应的真实 POSTPROCESSING_FILE、PLANS_FILE 和 DATASET_JSON_FILE。

7. 推理流程图

flowchart TD
    A[准备 input_images] --> B{是否已有 inference_instructions.txt?}
    B -- 是 --> C[优先执行推荐命令]
    B -- 否 --> D[nnUNetv2_predict 单配置预测]
    D --> E{是否要多配置 ensemble?}
    E -- 是 --> F[预测时加 --save_probabilities]
    F --> G[nnUNetv2_ensemble]
    E -- 否 --> H[得到预测标签]
    G --> I{是否推荐 postprocessing?}
    I -- 是 --> J[nnUNetv2_apply_postprocessing]
    I -- 否 --> K[最终预测结果]
    J --> K
    H --> K

8. 基础 Dice 评估

如果你有 ground truth 标签，可以用官方评估入口计算 Dice 等指标。官方源码中的 evaluate_folder_entry_point 使用的位置参数是 ground truth 文件夹和预测文件夹，并要求提供 dataset.json 与 plans.json：

nnUNetv2_evaluate_folder \
  "$nnUNet_raw"/Dataset001_Liver/labelsTr \
  ./predictions_ensemble_pp \
  -djfile "$nnUNet_results"/Dataset001_Liver/nnUNetTrainer__nnUNetPlans__3d_fullres/dataset.json \
  -pfile "$nnUNet_results"/Dataset001_Liver/nnUNetTrainer__nnUNetPlans__3d_fullres/plans.json \
  -o ./predictions_ensemble_pp/summary.json

如果你只是做简单评估，也可以使用 simple 入口，显式指定标签编号：

nnUNetv2_evaluate_simple \
  ./ground_truth \
  ./predictions \
  -l 1 2 \
  -o ./predictions/summary.json

这里的 -l 1 2 表示评估标签 1 和 2。输出的 summary.json 会包含每个病例和平均指标。注意，评估文件名必须能一一对应；如果预测结果和标签 case id 不一致，评估会失败或结果无意义。

9. 常见错误检查表

现象	原因	检查方式
预测时报找不到输入文件	输入没有 channel 编号或后缀不匹配	检查是否为 case_001_0000.nii.gz 这类格式
ensemble 报错	预测时没有加 --save_probabilities	确认输入目录中存在概率文件
postprocessing 路径报错	postprocessing.pkl、plans 或 dataset json 路径不对	优先复制 inference_instructions.txt 的命令
Dice 异常低	文件对应关系、标签值或空间方向可能错误	先可视化原图、标签和预测，不要只看数字

10. 官方资料入口

本文主要参考：

• Run Inference
• Find the Best Configuration
• Dataset and Input Format Reference
• evaluate_predictions.py 官方源码

本篇总结

nnU-Net v2 推理的关键是输入命名、configuration、fold 和概率文件。单配置预测使用 nnUNetv2_predict；多配置 ensemble 需要先用 --save_probabilities 保存概率；postprocessing 应优先按 find_best_configuration 生成的命令执行；有标签时可以用官方评估入口计算 Dice。

下一篇预告

下一篇我们开始进入 nnU-Net v2 内部框架：fingerprint、plans、preprocessing、Trainer 和 Predictor 分别负责什么，以及为什么理解这些模块是后续修改 Trainer、loss、augmentation 和 network architecture 的前提。