本篇学习目标

这是《nnU-Net 0基础入门》系列的第 3 篇。前两篇我们讲了 nnU-Net v2 的定位和安装环境。本文进入第一个真正容易踩坑的环节：数据集格式。

读完本文，你应该能够：

1. 理解 nnU-Net v2 为什么要求固定的数据集目录结构。
2. 正确区分 imagesTr、labelsTr、imagesTs 的作用。
3. 掌握 case id、channel 编号和标签文件命名规则。
4. 写出一个最小可用的 dataset.json。
5. 知道用什么命令检查数据集格式是否正确。

1. 为什么数据集格式这么重要

nnU-Net v2 的核心思想是自动分析数据并生成训练配置。要做到这一点，它必须先可靠地找到训练图像、标签、通道信息、类别信息和文件格式。如果你的数据目录混乱，nnU-Net 就无法判断哪个文件是图像、哪个文件是标签、哪些文件属于同一个病例。

因此，nnU-Net v2 对数据集有一套明确格式要求。你可以把它理解成“和框架签订的数据接口”。只要接口正确，后面的 plan、preprocess、train、predict 才能顺利衔接。

2. 标准目录结构

官方文档要求，每个数据集都放在 nnUNet_raw 下面，并命名为 DatasetXXX_Name。其中 XXX 是三位数字数据集编号，Name 是你给数据集起的名字。

nnUNet_raw/
└── Dataset001_Liver
    ├── dataset.json
    ├── imagesTr/
    ├── labelsTr/
    └── imagesTs/

三个子目录的含义如下：

目录	是否必须	作用	是否有标签
imagesTr	必须	训练图像	对应 labelsTr
labelsTr	必须	训练标签，也就是人工标注的分割 mask	自身就是标签
imagesTs	可选	测试图像或无标签推理图像	没有标签

mask 在分割任务中通常指标签图。它和原图大小一致，每个像素或体素的数值代表类别。例如背景是 0，肝脏是 1，肿瘤是 2。

3. case id：同一个病例如何对应起来

case id 是病例编号或样本编号。nnU-Net v2 通过 case id 判断哪些图像通道和哪个标签属于同一个病例。

训练图像文件命名格式是：

{CASE_IDENTIFIER}_{XXXX}.{FILE_ENDING}

标签文件命名格式是：

{CASE_IDENTIFIER}.{FILE_ENDING}

这里的 XXXX 是四位 channel 编号，例如 0000、0001。标签文件不带 channel 编号。

一个单通道 3D NIfTI 数据集可以这样命名：

Dataset001_Liver/
├── imagesTr/
│   ├── liver_001_0000.nii.gz
│   ├── liver_002_0000.nii.gz
│   └── liver_003_0000.nii.gz
├── labelsTr/
│   ├── liver_001.nii.gz
│   ├── liver_002.nii.gz
│   └── liver_003.nii.gz
└── dataset.json

注意 liver_001_0000.nii.gz 和 liver_001.nii.gz 通过共同的 case id liver_001 对应起来。

4. 多通道数据怎么放

医学图像里经常会有多模态或多通道输入。例如脑肿瘤 MRI 可能有 T1、T1ce、T2、FLAIR；前列腺 MRI 可能有 T2 和 ADC。nnU-Net v2 对非 RGB 多通道输入的要求是：每个通道单独存成一个文件，并用四位 channel 编号区分。

Dataset002_Prostate/
├── imagesTr/
│   ├── case_001_0000.nii.gz
│   ├── case_001_0001.nii.gz
│   ├── case_002_0000.nii.gz
│   └── case_002_0001.nii.gz
├── labelsTr/
│   ├── case_001.nii.gz
│   └── case_002.nii.gz
└── dataset.json

这里 case_001_0000.nii.gz 和 case_001_0001.nii.gz 是同一个病例的两个输入通道。官方文档强调：同一病例的所有通道必须几何一致并且对齐，通道顺序在所有病例中必须一致。

文件	含义	通道编号
case_001_0000.nii.gz	第 1 个病例的第 0 个输入通道	0000
case_001_0001.nii.gz	第 1 个病例的第 1 个输入通道	0001
case_001.nii.gz	第 1 个病例的标签	无 channel 编号

5. dataset.json：告诉 nnU-Net 这个数据集是什么

dataset.json 是每个数据集必须包含的元信息文件。元信息指描述数据的数据，例如通道名称、标签类别、训练样本数量和文件后缀。

官方参考文档中最重要的字段包括 channel_names、labels、numTraining 和 file_ending。下面是一个最小示例：

{
  "channel_names": {
    "0": "CT"
  },
  "labels": {
    "background": 0,
    "liver": 1,
    "tumor": 2
  },
  "numTraining": 3,
  "file_ending": ".nii.gz"
}

字段解释如下：

字段	含义	常见错误
channel_names	输入通道名称，会影响归一化行为	多通道顺序和文件编号不一致
labels	标签名称到整数类别的映射	标签文件里出现了未声明的类别值
numTraining	训练病例数量	数量和 labelsTr 中标签文件数不一致
file_ending	图像和标签使用的文件后缀	图像是 .nii.gz，但写成 .nii

6. 支持哪些文件格式

官方 reference 说明，nnU-Net v2 支持多种输入文件格式。常见内置选项包括：

• .nii.gz、.nrrd、.mha
• .png、.bmp、.tif
• 带 spacing sidecar JSON 的 3D TIFF

对医学 3D 数据来说，.nii.gz 是很常见的选择。对 2D 图像来说，.png 或 .tif 也常见。官方文档还特别提醒：图像和标签必须使用同一个数据集级别的格式，.jpg 这类有损格式不适合用作分割训练数据。

7. 推理输入也要遵守命名规则

很多人训练时整理对了数据，但推理时又忘了命名规则。官方 reference 明确说明：推理输入也必须匹配训练数据集的文件后缀和 channel 命名规则。

例如两通道推理输入应该类似：

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

预测结果会写成不带 channel 编号的形式：

case_001.nii.gz
case_002.nii.gz

8. 数据集整理流程图

把原始数据整理成 nnU-Net 格式，可以按下面的流程做：

flowchart TD
    A[收集原始图像和标签] --> B[确定每个病例的 case id]
    B --> C[确认输入通道数量和顺序]
    C --> D[按 case_id_channel 编号重命名 imagesTr]
    D --> E[按 case_id 重命名 labelsTr]
    E --> F[编写 dataset.json]
    F --> G[运行 plan_and_preprocess 的完整性检查]
    G --> H{检查通过?}
    H -- 是 --> I[进入 preprocessing 和训练]
    H -- 否 --> J[修正命名/标签/通道/文件格式]
    J --> G

9. 最小检查命令

准备好数据集后，不建议直接开始训练。先运行官方推荐的完整性检查：

nnUNetv2_plan_and_preprocess -d 1 --verify_dataset_integrity

这里 -d 1 表示数据集编号 1，也就是 Dataset001_...。如果你的数据集是 Dataset123_MyDataset，就写：

nnUNetv2_plan_and_preprocess -d 123 --verify_dataset_integrity

这条命令会进入 plan 和 preprocess 流程，并在前面检查数据集完整性。对初学者来说，第一次准备数据集时一定要加 --verify_dataset_integrity。如果这里报错，优先检查：

• 数据集目录是否在 nnUNet_raw 下。
• 目录名是否是 DatasetXXX_Name。
• imagesTr 和 labelsTr 的 case id 是否一一对应。
• 图像是否带 _0000、_0001 这类 channel 编号。
• 标签文件是否不带 channel 编号。
• dataset.json 中的 file_ending 是否和真实文件后缀一致。
• 标签图中是否存在 labels 字段没有声明的类别值。

10. 官方资料入口

本文主要参考：

• Dataset and Input Format Reference
• Prepare a Dataset
• Plan and Preprocess
• MIC-DKFZ/nnUNet 官方仓库

本篇总结

nnU-Net v2 的数据集格式可以记成一句话：每个数据集放在 nnUNet_raw/DatasetXXX_Name 下，训练图像放 imagesTr，训练标签放 labelsTr，测试图像可选放 imagesTs，图像文件必须带四位 channel 编号，标签文件不带 channel 编号，并且每个数据集必须有 dataset.json。

只要数据接口整理正确，后面的 plan、preprocess、train 和 predict 就会顺畅很多。

下一篇预告

下一篇我们会真正跑通 nnU-Net v2 的第一个完整闭环：plan_and_preprocess、train、predict。你会看到从数据集编号到训练 fold，再到预测输出文件的完整命令链。