企业官网建设流程全解析

MONAI Bundle 规范详解：可移植深度学习模型的分发格式与 metadata.json 实战

【免费下载链接】MONAIAI Toolkit for Healthcare Imaging项目地址: https://gitcode.com/GitHub_Trending/mo/MONAI

MONAI Bundle（简称 MB）是 MONAI 定义的一种可移植、自描述的深度学习模型打包格式，其目标是把"一个能用的模型"连同"如何使用它"的全部关键信息封装成一个目录或单一文件，让用户和程序无需阅读源码即可理解模型的用途、输入输出格式并正确调用。本指南以仓库中的官方规范文档（mb_specification.rst）为主体，结合 monai/bundle 模块的源码实现与测试用例，系统讲解 Bundle 的目录结构、归档格式、metadata.json字段语义，以及如何使用monai.bundle提供的命令行工具完成打包、导出与校验，最终让读者能够独立创建、验证和分发符合 MB 规范的模型包。

1. Bundle 的设计目标与适用场景

MB 规范回答了一个核心问题：如何把训练好的模型交付给不了解训练细节的用户或程序。一个 MB 包中承载的信息包括：

• 单个网络的存储权重（pickle 格式的 state dict），这是必需的；
• 可选的 TorchScript 对象（model.ts）和/或 ONNX 对象（model.onnx）；
• 一组 JSON 文件，用于记录模型元数据（metadata）、训练/推理/后处理变换序列的构建信息、纯文本描述、法律信息（许可证）以及其他模型作者希望附带的数据。

从设计上看，Bundle 是"为程序与人双方服务"的：程序通过metadata.json中的network_data_format等结构化字段自动判断如何喂入数据、解释输出；人则通过README.md、description、task等字段快速理解模型用途。docs/source/bundle.rst中列出的 ConfigParser、ckpt_export、verify_metadata 等组件共同构成了这套打包、解析、校验、运行的工作链。

2. 目录结构：一个合法 Bundle 的最小骨架

规范规定，Bundle 首先是一个目录，其中包含若干名字固定的子目录与文件。根目录应以模型名命名（下例中的ModelName），标准结构如下：

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

2.1 必需文件（文件名不可更改）

2.2 可选文件（同样有固定命名要求）

2.3 允许的扩展内容

除上述文件外，各目录都可以放额外文件。例如configs中可以放入更多 JSON/YAML 配置，用来定义训练/推理脚本、覆盖配置值、声明网络实例化等环境定义。规范特别提到一个常见文件inference.json：它定义了一个基础推理脚本——用输入文件配合存储的网络产生预测输出文件。仓库的 tests/testing_data 中就提供了 inference.json 与 data_config.json 这类可参考的示例配置。

3. 归档格式：zip 与 TorchScript 两种打包方式

Bundle 目录可以压缩为 zip 文件，构成单一文件包。解压后应完整复现上述目录结构，且zip 文件名本身也应以模型命名。例如ModelName.zip内至少应包含ModelName/configs/metadata.json和ModelName/models/model.pt，解压后文件落入ModelName目录而非当前工作目录，从而避免污染用户环境。

TorchScript 文件格式本质上也是一个 zip 文件，只是结构特定。规范给出了生成 MB 兼容 TorchScript 的明确方法：

1. 使用save_net_with_metadata保存模型；
2. 把metadata.json的内容作为meta_values参数传入；
3. 其余文件通过more_extra_files条目附带；
4. 这些内容会存放在 zip 的extras目录中，可用load_net_with_metadata或任意能读 zip 的工具取回。

在这种格式下不再需要model.*文件，README.md、license.txt等都可以作为 extra files 添加。从源码 monai/data/torchscript_utils.py 可以看到，save_net_with_metadata会把metadata.json编码进extra_files字典（L85），并在include_config_vals=True（默认）时自动注入get_config_values()返回的 MONAI/Numpy/Pytorch 版本信息（L76-L78）；load_net_with_metadata则返回(加载的模块, 元数据字典, 额外文件字典)三元组（L103-L133）。版本信息的具体取值由 monai/config/deviceconfig.py 的get_config_values()提供（L64-L74）。

除了save_net_with_metadata，MONAI 还通过monai.bundle子模块提供了一套命令行程序。要产出 TorchScript Bundle，使用ckpt_export并指定保存的权重文件、元数据文件等组件即可。配置文件可以是 JSON 或 YAML 字典（内部由ConfigParser构造 Python 对象），无论原始格式如何，产出的 Bundle TorchScript 对象一律将文件以 JSON 存储。

4. metadata.json 字段全解

metadata.json是 Bundle 的"说明书"，记录模型输入/输出的形状与格式、输出语义、模型类型等信息。整体是一个 JSON 字典，包含一组规范定义的键+ 用户自定义键。仓库的元数据校验依赖verify_metadata（见第 6 节），其实现（monai/bundle/scripts.py）会先读取 metadata 中的schema字段定位 JSON Schema 下载地址，再通过jsonschema.validate校验整个文件。

4.1 必需键

4.2 可选键

4.3 张量格式说明符（Tensor format specifier）

network_data_format（及*_data_format）中的每个命名输入/输出都是一个字典，至少包含以下键：

4.4 已知的 format 取值

format用于给出张量的语义含义，后续处理 Bundle 的软件会据此决定如何加工与解释数据。规范给出的清单并非穷尽，用户可自定义，语义由模型使用者自行解释：

4.5 spatial_shape 的表达式规则

接受变长输入的模型，其形状定义可能很复杂，尤其是存在特定形状约束时。形状是列表，元素要么是表示固定尺寸的正整数，要么是字符串表达式——后者用 Python 数学运算符和单字符变量描述对某个未知量的依赖：

• "*"：任意尺寸；
• 含表达式的字符串，如"2**p"表示尺寸必须是 2 的幂，"2**p*n"表示必须是 2 的幂的倍数；
• 变量在各维度表达式之间共享。

规范给出的示例：["*", "16*n", "2**p*n"]表示第一维任意、第二维是 16 的倍数、第三维同时受 2 的幂约束。这一表达式体系也被 CLI 校验工具消费：verify_net_in_out的实现（monai/bundle/scripts.py 中的_get_fake_spatial_shape）会从这些字符串表达式推导出用于构造假输入张量的具体形状，再实际跑一次前向传播验证网络输入输出与 metadata 描述是否一致，测试见 tests/bundle/test_bundle_verify_net.py。

4.6 schema 字段

metadata.json内可通过键schema给出用于校验本文件的 JSON Schema 下载链接。

4.7 完整示例：Decathlon 脾脏分割模型

以下是规范文档给出的完整示例 metadata 文件，可对照 4.1–4.6 的字段逐一理解：

{ "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"} } } } }

这个例子值得注意的细节：

• image_classes、label_classes、pred_classes、eval_metrics都是用户自定义键，规范允许任意扩展，软件处理时会忽略未知键；
• 输入image声明为单通道magnitude图像、模态MR、形状[160, 160, 160]、强度归一化到[0, 1]；
• 输出pred声明为 2 通道labels格式，channel_def明确 0 通道为背景、1 通道为脾脏，对应 one-hot 语义下"最大通道索引即预测标签"的约定；
• required_packages_version声明了 Nibabel 这一附加依赖，data_type为dicom，两者相互印证。

5. 用 monai.bundle 命令行工具打包与运行

monai.bundle通过 monai/bundle/main.py 暴露 CLI（内部基于fire将 monai/bundle/scripts.py 中的函数映射为子命令）。常用的几个命令如下。

5.1 ckpt_export：导出 TorchScript Bundle

将 checkpoint 连同 metadata、config 导出为 TorchScript 文件：

python -m monai.bundle ckpt_export network_def \ --filepath /path/to/export/model.ts \ --ckpt_file /path/to/models/model.pt \ --meta_file /path/to/configs/metadata.json \ --config_file /path/to/configs/inference.json

参数语义（对应源码 ckpt_export）：

与目录式 Bundle 不同，此命令产出的单文件 TorchScript 本身就是一个"自包含 zip"，meta 与 config 都作为 extras 存入，无需再单独分发metadata.json。测试用例见 tests/bundle/test_bundle_ckpt_export.py（直接以python -m monai.bundle ckpt_export ...方式调用）。

5.2 其他导出命令

• onnx_export：将模型导出为 ONNX，参数与ckpt_export基本一致；
• trt_export：导出 TensorRT 引擎，支持precision、dynamic_batchsize等参数；
• init_bundle：基于已有 checkpoint 与网络初始化一个标准 Bundle 目录骨架。

5.3 run 与 workflow 运行

python -m monai.bundle run --config_file /path/to/inference.json

run接收meta_file、config_file、logging_file等参数；run_workflow则针对BundleWorkflow按initialize → run → finalize流程执行训练/推理（见 monai/bundle/workflows.py）。这些命令都支持args_file，把大量参数固化到配置文件中，命令行只保留最小输入。

6. 校验工具：verify_metadata 与 verify_net_in_out

规范落地离不开校验。monai.bundle提供两条质量关卡：

6.1 verify_metadata：按 JSON Schema 校验 metadata

python -m monai.bundle verify_metadata --meta_file configs/metadata.json

• 前提：metadata 内必须有schema字段（Schema URL），实现会先下载 Schema 再调用jsonschema.validate校验（monai/bundle/scripts.py）；
• 支持filepath（Schema 落盘路径）、hash_val/hash_type（默认md5，校验下载的 Schema 文件）、create_dir（默认True）、args_file；
• 校验失败时只截取Failed validating ...关键错误信息并附上 Schema URL，便于定位问题；
• 测试覆盖见 tests/bundle/test_bundle_verify_metadata.py。

6.2 verify_net_in_out：前向传播验证网络输入输出

python -m monai.bundle verify_net_in_out network_def \ --meta_file configs/metadata.json \ --config_file configs/inference.json

• 从_meta_#network_data_format解析 metadata 中声明的输入输出信息（monai/bundle/scripts.py）；
• 依据spatial_shape表达式生成假输入（p、n、any参数可控制表达式变量的取值），实际执行一次前向传播；
• 只有网络真实输入输出与 metadata 声明一致时校验通过。仓库提供了专门的示例网络 tests/testing_data/bundle_test_network.py 供测试使用，对应测试见 tests/bundle/test_bundle_verify_net.py。

7. 实践要点与常见误区

1. 目录与文件命名是"契约"：LICENSE、metadata.json、model.pt的名字和位置不可改动，工具链按约定路径查找（如 ckpt_export 默认拼接bundle_root/configs/metadata.json与bundle_root/models/model.pt）。
2. 版本字符串必须文件名安全：version可能参与 Bundle 文件名拼接，避免/、空格等非法字符，并遵循语义化版本。
3. TorchScript Bundle 中元数据是 JSON：save_net_with_metadata会把meta_values序列化为 JSON 存入extras/metadata.json（monai/data/torchscript_utils.py），读取时经json.loads还原，因此meta_values必须能被标准库json.dumps序列化。
4. channel_def是解释输出语义的关键：对labels/classes/segmentation格式，软件依赖它判断每个通道/类别的含义；模型作者应确保其与训练时的标签定义一致。
5. modality有默认值：未填写时视为"n/a"，不要依赖缺失字段表达语义。
6. 表达式变量跨维度共享：["*", "16*n", "2**p*n"]中的n在同一输入的所有维度表达式中含义一致，设计 shape 约束时不要在不同维度复用同名变量表达不同含义。
7. 校验先行：发布前至少运行verify_metadata与verify_net_in_out，前者保证元数据符合 Schema，后者保证元数据与真实网络行为一致——这两步是自动化流水线接入 Bundle 时最基础的质量门禁。

8. 参考实现与延伸阅读

• 规范原文：docs/source/mb_specification.rst
• Bundle 模块 API 文档：docs/source/bundle.rst
• 核心实现：
  • CLI 入口 monai/bundle/main.py
  • 命令实现 monai/bundle/scripts.py
  • 配置解析 monai/bundle/config_parser.py 与 monai/bundle/config_item.py
  • 引用解析 monai/bundle/reference_resolver.py
  • 工作流 monai/bundle/workflows.py
  • TorchScript 存取 monai/data/torchscript_utils.py
• 测试参考：
  • tests/bundle/test_bundle_ckpt_export.py
  • tests/bundle/test_bundle_verify_metadata.py
  • tests/bundle/test_bundle_verify_net.py
  • tests/bundle/test_config_parser.py
• 示例配置数据：tests/testing_data/inference.json、tests/testing_data/metadata.json、tests/testing_data/data_config.json

掌握本文所述的目录骨架、归档规则、metadata.json字段语义与 CLI 工具链，即可为任意 MONAI 模型制作出符合 MB 规范的、可被工具与程序自动识别和调用的标准模型包。

【免费下载链接】MONAIAI Toolkit for Healthcare Imaging项目地址: https://gitcode.com/GitHub_Trending/mo/MONAI