MONAI Bundle 规范详解可移植深度学习模型的分发格式与 metadata.json 实战【免费下载链接】MONAIAI Toolkit for Healthcare Imaging项目地址: https://gitcode.com/GitHub_Trending/mo/MONAIMONAI 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.txt2.1 必需文件文件名不可更改文件位置作用LICENSE根目录针对配置文件和模型权重构成的软件本身的许可证metadata.jsonconfigs/JSON 格式的元数据描述模型类型、输入/输出张量定义、模型版本与所用软件版本等model.ptmodels/已保存模型的 state dict实例化模型所需的信息必须能在 metadata 中找到2.2 可选文件同样有固定命名要求文件位置作用model.tsmodels/若模型能以 TorchScript 正确保存则提供 TorchScript 版本model.onnxmodels/若模型支持则提供 ONNX 版本README.mddocs/面向人的模型说明用途、使用方法、作者信息等Markdown 格式license.txtdocs/附加在数据上的软件许可证无许可需求时可留空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 的明确方法使用save_net_with_metadata保存模型把metadata.json的内容作为meta_values参数传入其余文件通过more_extra_files条目附带这些内容会存放在 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_valsTrue默认时自动注入get_config_values()返回的 MONAI/Numpy/Pytorch 版本信息L76-L78load_net_with_metadata则返回(加载的模块, 元数据字典, 额外文件字典)三元组L103-L133。版本信息的具体取值由 monai/config/deviceconfig.py 的get_config_values()提供L64-L74。除了save_net_with_metadataMONAI 还通过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 必需键键含义version模型版本号建议遵循语义化版本且只包含文件名合法的字符版本可能被用于拼接 Bundle 文件名monai_version生成该 Bundle 时使用的 MONAI 版本后续版本预期兼容pytorch_version生成时使用的 PyTorch 版本后续版本预期兼容numpy_version生成时使用的 Numpy 版本后续版本预期兼容required_packages_version字典必需的附加包名 → 版本。即除 MONAI 基础依赖外 Bundle 运行绝对需要的包例如需加载 Nifti 文件时就要求 Nibabeltask模型任务的纯文本描述description更长的纯文本说明模型是什么、做什么authors模型作者copyright模型版权声明network_data_format定义主模型输入/输出的格式、形状与语义含inputs、outputs两个键分别把命名输入/输出映射到格式说明符见 4.3另有可选键post_processed_outputs用于描述经后处理变换后的最终输出格式若与网络原始输出不同。这些键也可以映射到原始值数字、字符串、布尔而不必是张量格式4.2 可选键键含义changelog字典历史版本号 → 变更说明intended_use模型预期用途完成什么任务data_source训练/验证数据的来源说明data_type训练/验证所用源数据类型references与模型相关的已发表文献列表supported_apps支持使用该 Bundle 的应用列表例如与 MONAI Label 兼容时应包含monai-label*_data_format次要辅助模型输入/输出的格式定义内容与network_data_format同类。典型场景定位网络先用*_data_format描述其找出图像 ROI 并裁剪的输入输出裁剪结果再送入主网络4.3 张量格式说明符Tensor format specifiernetwork_data_format及*_data_format中的每个命名输入/输出都是一个字典至少包含以下键键含义与取值type张量代表的数据种类image任何空间规则数据未必是真图像、series信号等时间值序列、tuples由已知数量值定义的项目序列如 ND 空间中的 N 维点、probabilities分类器输出这类概率集合。该字段帮助解释各维度含义让用户能推测如何绘制数据format存储的信息格式见 4.4 的已知格式清单可自定义扩展modality数据模态/协议类型/采集技术等type与format之外的属性。已知模态包括MR、CT、US、EKG也允许自定义类型或协议类型如T1默认值为n/anum_channels张量通道数默认通道维在前spatial_shape空间维度形状形式为[H]、[H, W]或[H, W, D]取值规则见 4.5dtype张量数据类型如float32、int32value_range输入数据预期的最小/最大值形式[MIN, MAX]未知时写[]is_patch_data该数据是输入/输出张量的一个 patch或整个张量时为true否则falsechannel_def字典通道索引 → 该通道内容的纯文本描述4.4 已知的 format 取值format用于给出张量的语义含义后续处理 Bundle 的软件会据此决定如何加工与解释数据。规范给出的清单并非穷尽用户可自定义语义由模型使用者自行解释format含义magnitude单通道或多通道的连续幅值 ND 场如单通道 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中描述的标签pointsND 空间中的点/节点/坐标/顶点/向量列表形状为[I, N]I 个点 × N 维normalsND 空间中的向量列表可能为单位长度形状为[I, N]indices指向顶点数组和/或其他形状数组的索引列表形状为[I, N]I 个形状 × N 个值sequence时间相关单通道或多通道值序列信号、字典查询句等形状为[C, N]C 个通道 × N 个时间点latent来自网络某层的潜在空间 ND 张量gradient来自网络某层的梯度 ND 张量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参数默认值说明net_idnetwork_def配置中网络组件必须是torch.nn.Module的 IDfilepathbundle_root/models/model.ts导出路径无扩展名时自动补.ts未指定bundle_root时以当前工作目录为准ckpt_filebundle_root/models/model.pt待加载的 checkpoint 路径文件不存在会抛出FileNotFoundErrormeta_filebundle_root/configs/metadata.jsonmetadata 文件路径支持传入列表自动合并config_file无要保存进 TorchScript 的配置文件TorchScript 内保存键为去扩展名的文件名值统一序列化为 JSONkey_in_ckpt空嵌套 checkpoint如{model: ..., optimizer: ...}时指定权重所在键use_traceFalse是否用torch.jit.trace而非script转换input_shape从 metadata 推断转换时生成随机输入用的形状如[N, C, H, W]或[N, C, H, W, D]args_file无用 JSON/YAML 文件集中提供上述参数的默认值override无以--_meta#network_data_format#inputs#image#num_channels 3这类 id-value 对覆盖配置内容与目录式 Bundle 不同此命令产出的单文件 TorchScript 本身就是一个自包含 zipmeta 与 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.jsonrun接收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 校验 metadatapython -m monai.bundle verify_metadata --meta_file configs/metadata.json前提metadata 内必须有schema字段Schema URL实现会先下载 Schema 再调用jsonschema.validate校验monai/bundle/scripts.py支持filepathSchema 落盘路径、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. 实践要点与常见误区目录与文件命名是契约LICENSE、metadata.json、model.pt的名字和位置不可改动工具链按约定路径查找如 ckpt_export 默认拼接bundle_root/configs/metadata.json与bundle_root/models/model.pt。版本字符串必须文件名安全version可能参与 Bundle 文件名拼接避免/、空格等非法字符并遵循语义化版本。TorchScript Bundle 中元数据是 JSONsave_net_with_metadata会把meta_values序列化为 JSON 存入extras/metadata.jsonmonai/data/torchscript_utils.py读取时经json.loads还原因此meta_values必须能被标准库json.dumps序列化。channel_def是解释输出语义的关键对labels/classes/segmentation格式软件依赖它判断每个通道/类别的含义模型作者应确保其与训练时的标签定义一致。modality有默认值未填写时视为n/a不要依赖缺失字段表达语义。表达式变量跨维度共享[*, 16*n, 2**p*n]中的n在同一输入的所有维度表达式中含义一致设计 shape 约束时不要在不同维度复用同名变量表达不同含义。校验先行发布前至少运行verify_metadata与verify_net_in_out前者保证元数据符合 Schema后者保证元数据与真实网络行为一致——这两步是自动化流水线接入 Bundle 时最基础的质量门禁。8. 参考实现与延伸阅读规范原文docs/source/mb_specification.rstBundle 模块 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.pyTorchScript 存取 monai/data/torchscript_utils.py测试参考tests/bundle/test_bundle_ckpt_export.pytests/bundle/test_bundle_verify_metadata.pytests/bundle/test_bundle_verify_net.pytests/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考