MONAI Bundle 规范#

概述#

这是关于便携式描述的深度学习模型的一种 MONAI Bundle (MB) 格式的规范。MB 的目标是定义一个打包的网络或模型，其中包含允许用户和程序理解如何使用该模型以及用于何种目的所需的关键信息。一个 Bundle 包含单个网络的存储权重，以 pickled 状态字典的形式，并可选地包含一个 Torchscript 对象和/或一个 ONNX 对象。此外，还包含 JSON 文件，用于存储有关模型的元数据、用于构建训练、推理和后处理转换序列的信息、纯文本描述、法律信息以及模型创建者希望包含的其他数据。

本规范定义了 Bundle 必须具有的目录结构以及必须包含的必要文件。可以包含其他文件，并且可以将目录打包成 zip 文件或直接作为附加文件包含在 Torchscript 文件中。

目录结构#

MONAI Bundle 主要定义为一个包含一组特定命名子目录的目录，这些子目录包含模型、元数据文件和许可证。根目录应以模型命名，在此示例中为“ModelName”，并且应包含以下结构

ModelName
┣━ LICENSE
┣━ configs
┃  ┗━ metadata.json
┣━ models
┃  ┣━ model.pt
┃  ┣━ *model.ts
┃  ┗━ *model.onnx
┗━ docs
   ┣━ *README.md
   ┗━ *license.txt

以下文件是定义有效 Bundle 所必需的，且必须具有给定的文件名

  • LICENSE: 配置文件的软件许可证以及模型权重。

  • metadata.json: JSON 格式的元数据信息，涉及模型的类型、输入和输出张量的定义、模型和所用软件的版本以及下面描述的其他信息。

  • model.pt: 保存模型的状体字典，实例化模型所需的信息必须在元数据文件中找到。

以下文件是可选的，但必须在上述目录中具有这些名称

  • model.ts: 如果模型兼容以这种格式正确保存，则为 Torchscript 保存模型。

  • model.onnx: 如果模型兼容以这种格式正确保存，则为 ONNX 模型。

  • README.md: 关于模型的通俗易懂信息，包括如何使用、作者信息等，使用 Markdown 格式。

  • license.txt: 附加到数据的软件许可证，如果不需要许可证，可以留空。

可以在上述任何目录中包含其他文件。例如，configs 可以包含更多配置 JSON 或 YAML 文件，以定义训练或推理脚本、覆盖配置值、环境定义（如网络实例化）等等。一个常见包含的文件是 inference.json，它用于定义一个基本的推理脚本，该脚本使用输入文件和存储的网络生成预测输出文件。

归档格式#

Bundle 目录及其内容可以被压缩成一个 zip 文件，构成一个单文件包。解压缩到目录时，该文件将重现上述目录结构，并且其本身也应以其包含的模型命名。例如，ModelName.zip 将至少包含 ModelName/configs/metadata.json 和 ModelName/models/model.pt，因此解压缩时会将文件放入 ModelName 目录而不是当前工作目录。

Torchscript 文件格式本身也是一个具有特定结构的 zip 文件。使用 save_net_with_metadata 创建此类归档时，可以通过将 metadata.json 的内容作为函数的 meta_values 参数，并将其他文件作为 more_extra_files 条目包含在内，从而创建一个符合 MB 规范的 Torchscript 文件。这些文件将存储在 zip 文件中的 extras 目录中，可以使用 load_net_with_metadata 或任何其他可以读取 zip 数据的库/工具检索。在这种格式中，显然不需要 model.* 文件，但 README.md 和 license.txt 以及提供的任何其他文件都可以作为更多附加文件添加。

MONAI 的 bundle 子模块包含许多命令行程序。要生成 Torchscript Bundle，请使用 ckpt_export 并指定一组组件，例如保存的权重文件和元数据文件。配置文件可以作为 JSON 或 YAML 字典提供，定义由 ConfigParser 使用的 Python 构造，但无论格式如何，生成的 Bundle Torchscript 对象都将文件存储为 JSON。

metadata.json 文件#

此文件包含与模型相关的元数据信息，包括输入和输出的形状和格式、输出的含义、存在的模型类型以及其他信息。JSON 结构是一个字典，包含一组定义的键以及附加的用户指定键。强制键如下

  • version: 存储模型的版本，这允许区分同一模型的多个版本。版本应遵循语义版本控制，且仅包含文件名中有效的字符，因为我们可能会包含版本来构造 Bundle 文件名。

  • monai_version: 生成 Bundle 所使用的 MONAI 版本，预期后续版本也能工作。

  • pytorch_version: 生成 Bundle 所使用的 PyTorch 版本，预期后续版本也能工作。

  • numpy_version: 生成 Bundle 所使用的 NumPy 版本，预期后续版本也能工作。

  • required_packages_version: 将所需的包名与其版本关联的字典。这些是 MONAI 基本要求之外，此 Bundle 绝对需要的包。例如，如果 Bundle 必须加载 Nifti 文件，则需要 Nibabel 包。

  • task: 模型主要作用的通俗易懂描述。

  • description: 关于模型是什么、做什么等的较长篇幅通俗易懂描述。

  • authors: 说明模型的作者。

  • copyright: 说明模型的版权。

  • network_data_format: 定义（主要）模型的输入和输出的格式、形状和含义，包含将命名输入/输出与其格式说明符（定义如下）关联的键“inputs”和“outputs”。还有一个可选的“post_processed_outputs”键，说明应用后处理转换后“outputs”的格式，用于描述 Bundle 的最终输出（如果与原始网络输出不同）。这些键也可以关联到原始值（数字、字符串、布尔值），而不是下面指定的张量格式。

张量格式说明符用于定义输入和输出张量及其含义，并且必须是一个包含至少这些键的字典

  • type: 张量表示的数据类型：“image”用于任何空间规则数据，无论是实际图像还是仅具有该形状的数据；“series”用于值序列（时间序列），如信号；“tuples”用于一系列由已知数量值定义的项目，如 ND 空间中的 N 个点；“probabilities”用于一组概率，如分类器输出，这有助于解释数据的维度和形状所代表的含义，并允许用户猜测如何绘制数据。

  • format: 存储的信息格式，参见下面的已知格式列表。

  • modality: 描述数据的模态、协议类型、捕获技术或其他属性，这些属性既未通过其类型也未通过其格式描述。已知模态有“MR”、“CT”、“US”、“EKG”，但可以包括任何自定义类型或协议类型（如“T1”），默认值为“n/a”。

  • num_channels: 张量的通道数，假设通道维度在前。

  • spatial_shape: 空间维度的形状，格式为“[H]”、“[H, W]”或“[H, W, D]”，参见下面 H、W 和 D 的可能值。

  • dtype: 张量的数据类型，例如“float32”、“int32”。

  • value_range: 输入数据预期的最小值和最大值，格式为“[MIN, MAX]”，如果未知则为“[]”。

  • is_patch_data: 如果数据是输入/输出张量的一个 Patch 或整个张量，则为“true”，否则为“false”。

  • channel_def: 将通道索引与通道内容的通俗易懂描述关联的字典。

可选键

  • changelog: 将以前的版本名称与描述该版本的字符串关联的字典。

  • intended_use: 模型的预期用途，即它完成的任务。

  • data_source: 训练/验证数据来源的描述。

  • data_type: 用于训练/验证的源数据类型。

  • references: 与模型相关的已发表参考文献列表。

  • supported_apps: 支持使用 Bundles 的应用程序列表，例如，如果 Bundle 与 MONAI Label 应用程序兼容，则会包含“monai-label”。

  • *_data_format: 定义相对于主模型而言，次要模型的输入和输出的格式、形状和含义。这包含与 network_data_format 相同类型的信息，用于描述提供次要功能的网络，例如，一个用于在将数据发送到此 Bundle 的主网络之前识别图像中 ROI 以进行裁剪的定位网络。

用于输入和输出张量的格式可以用于指定这些值的语义含义，并且稍后会由处理 Bundle 的软件用来确定如何处理和解释这些数据。MONAI 使用各种类型的图像数据，以及其他数据类型，如点云、字典序列、时间信号等。以下列表提供了一组支持的张量“format”定义，但并非详尽无遗，用户可以提供自己的定义，由模型使用者自行解释

  • magnitude: 具有一个或多个通道的连续幅度值的 ND 场，例如具有 1 个通道的 MR T1 图像或具有 3 个通道的自然 RGB 图像。

  • hounsfield: 以 Hounsfield 单位给出的半分类值的 ND 场，例如 CT 图像。

  • kspace: 与 MR 成像相关的 2D/3D 傅里叶变换图像。

  • raw: 从图像采集设备获取的未处理值的 ND 场，例如直接从 MR 扫描仪获取而未经重建或其他处理。

  • labels: 具有 N 个 one-hot 通道的 ND 分类图像，用于 N 类分割/标签，“channel_def”用通俗易懂的语言说明每个通道的解释。对于每个像素/体素，预测标签是最大通道值的索引。

  • classes: 具有 N 个通道的 ND 分类图像，用于 N 类类别，“channel_def”用通俗易懂的语言说明每个通道的解释。这允许进行多类标注，因为通道不需要是 one-hot 编码的。

  • segmentation: 具有一个通道的 ND 分类图像，将每个像素/体素分配给“channel_def”中描述的标签。

  • points: ND 空间中的点/节点/坐标/顶点/向量列表，形状为 [I, N]，表示 I 个点，每个点 N 个维度。

  • normals: ND 空间中的向量（可能为单位长度）列表，形状为 [I, N]，表示 I 个向量，每个向量 N 个维度。

  • indices: 顶点数组和/或其他数组中的索引列表，表示一组形状，形状为 [I, N]，表示 I 个形状，每个形状由 N 个值定义。

  • sequence: 具有一个或多个通道的时间相关值序列，例如信号或字典查找句子，形状为 [C, N]，表示在 N 个时间点有 C 个通道的数据。

  • latent: 网络某一层来自隐空间的 ND 数据张量。

  • gradient: 网络某一层来自梯度的 ND 张量。

对于接受不同形状输入的模型，空间形状定义可能很复杂，特别是当这些形状有特定条件时。形状被指定为列表，其中元素可以是固定大小的正整数，也可以是包含定义大小所依赖条件的表达式的字符串。这可以是“*”，表示任何大小，也可以使用带有 Python 数学运算符和一个字符变量的表达式来表示对未知量的依赖关系。例如，“2**p”表示大小必须是 2 的幂，“2**p*n”必须是 2 的幂的倍数。变量在维度表达式之间共享，空间形状示例：[“*”, “16*n”, “2**p*n”]。

可用于验证此文件的 JSON Schema 下载链接可以在其中找到，键为“schema”。

一个 metadata.json 示例文件

{
    "schema": "https://github.com/Project-MONAI/MONAI-extra-test-data/releases/download/0.8.1/meta_schema_20220324.json",
    "version": "0.1.0",
    "changelog": {
        "0.1.0": "complete the model package",
        "0.0.1": "initialize the model package structure"
    },
    "monai_version": "0.9.0",
    "pytorch_version": "1.10.0",
    "numpy_version": "1.21.2",
    "required_packages_version": {"nibabel": "3.2.1"},
    "task": "Decathlon spleen segmentation",
    "description": "A pre-trained model for volumetric (3D) segmentation of the spleen from CT image",
    "authors": "MONAI team",
    "copyright": "Copyright (c) MONAI Consortium",
    "data_source": "Task09_Spleen.tar from http://medicaldecathlon.com/",
    "data_type": "dicom",
    "image_classes": "single channel data, intensity scaled to [0, 1]",
    "label_classes": "single channel data, 1 is spleen, 0 is everything else",
    "pred_classes": "2 channels OneHot data, channel 1 is spleen, channel 0 is background",
    "eval_metrics": {
        "mean_dice": 0.96
    },
    "intended_use": "This is an example, not to be used for diagnostic purposes",
    "references": [
        "Xia, Yingda, et al. '3D Semi-Supervised Learning with Uncertainty-Aware Multi-View Co-Training.' arXiv preprint arXiv:1811.12506 (2018). https://arxiv.org/abs/1811.12506.",
        "Kerfoot E., Clough J., Oksuz I., Lee J., King A.P., Schnabel J.A. (2019) Left-Ventricle Quantification Using Residual U-Net. In: Pop M. et al. (eds) Statistical Atlases and Computational Models of the Heart. Atrial Segmentation and LV Quantification Challenges. STACOM 2018. Lecture Notes in Computer Science, vol 11395. Springer, Cham. https://doi.org/10.1007/978-3-030-12029-0_40"
    ],
    "network_data_format":{
        "inputs": {
            "image": {
                "type": "image",
                "format": "magnitude",
                "modality": "MR",
                "num_channels": 1,
                "spatial_shape": [160, 160, 160],
                "dtype": "float32",
                "value_range": [0, 1],
                "is_patch_data": false,
                "channel_def": {"0": "image"}
            }
        },
        "outputs":{
            "pred": {
                "type": "image",
                "format": "labels",
                "num_channels": 2,
                "spatial_shape": [160, 160, 160],
                "dtype": "float32",
                "value_range": [],
                "is_patch_data": false,
                "channel_def": {"0": "background", "1": "spleen"}
            }
        }
    }
}
本页内容
显示源文件