模型Bundle#

配置项#

class monai.bundle.Instantiable[source]#

可实例化对象的基类。

abstract instantiate(*args, **kwargs)[source]#

实例化目标组件并返回实例。

返回类型:

对象

abstract is_disabled(*args, **kwargs)[source]#

返回一个布尔标志，指示是否应实例化该对象。

返回类型:

bool

class monai.bundle.ComponentLocator(excludes=None)[source]#

扫描 MONAI 包中的所有可用类和函数，并将它们与模块路径映射到一个表中。用于查找给定组件名称的模块路径。

参数:

excludes – 如果在完整的模块名称中存在 excludes 中的任何字符串，则不导入此模块。

get_component_module_name(name)[source]#

获取具有指定 name 的类或函数的完整模块名称。如果目标组件名称存在于多个包或模块中，则返回完整的模块名称列表。

参数:

name – 预期类或函数的名称。

class monai.bundle.ConfigComponent(config, id='', locator=None, excludes=None)[source]#

monai.bundle.ConfigItem 的子类，此类使用带有字符串键的字典表示 class 或 function 组件，并支持实例化。

目前，定义了三个特殊键（由 _ 包围的字符串），它们在常规字面量之外被解释：

  • Python 模块的类或函数标识符，由 "_target_" 指定，指示 MONAI 内置的 Python 类或函数，例如 "LoadImageDict"，或完整的模块名称，例如 "monai.transforms.LoadImageDict"，或一个可调用对象，例如 "$@model.forward"。

  • "_requires_"（可选）：指定此 ConfigComponent 对象的依赖项的引用 ID（以 "@" 开头的字符串）或 ConfigExpression。这些依赖项将在实例化此对象之前被评估/实例化。当组件不通过其参数明确依赖于其他 ConfigItems，但需要事先实例化/评估依赖项时，这非常有用。

  • "_disabled_"（可选）：一个标志，指示是否跳过实例化。

  • "_desc_"（可选）：组件的自由文本描述，用于提高代码可读性。

  • "_mode_"（可选）：用于调用由 "_target_" 定义的可调用 component 的操作模式。

    • "default"：返回 component(**kwargs)

    • "callable"：返回 component，或者如果提供了 kwargs，则返回 functools.partial(component, **kwargs)

    • "debug"：返回 pdb.runcall(component, **kwargs)

配置内容中的其他字段是 Python 模块的输入参数。

from monai.bundle import ComponentLocator, ConfigComponent

locator = ComponentLocator(excludes=["modules_to_exclude"])
config = {
    "_target_": "LoadImaged",
    "keys": ["image", "label"]
}

configer = ConfigComponent(config, id="test", locator=locator)
image_loader = configer.instantiate()
print(image_loader)  # <monai.transforms.io.dictionary.LoadImaged object at 0x7fba7ad1ee50>
参数:

  • config – 配置项的内容。

  • id – 当前配置项的名称，默认为空字符串。

  • locator – 用于将模块名称字符串转换为实际 Python 模块的 ComponentLocator。如果为 None，将使用 ComponentLocator(excludes=excludes)。

  • excludes – 如果 locator 为 None，则创建一个新的 ComponentLocator 并带有 excludes。另请参阅：monai.bundle.ComponentLocator。

instantiate(**kwargs)[source]#

根据 self.config 内容实例化组件。目标组件必须是 class 或 function，否则返回 None。

参数:

kwargs (Any) – 实例化时用于覆盖/添加配置参数的参数。

返回类型:

对象

is_disabled()[source]#

在 instantiate() 中使用的实用函数，用于检查是否跳过实例化。

返回类型:

bool

static is_instantiable(config)[source]#

检查此配置是否表示将要实例化的 class 或 function。

参数:

config (Any) – 输入的配置内容以检查。

返回类型:

bool

resolve_args()[source]#

在 instantiate() 中使用的实用函数，用于从当前配置内容解析参数。

resolve_module_name()[source]#

从当前配置内容解析目标模块名称。配置内容必须包含 "_target_" 键。

class monai.bundle.ConfigExpression(config, id='', globals=None)[source]#

monai.bundle.ConfigItem 的子类，ConfigItem 表示一个可执行表达式（基于 eval() 执行，或者如果它是 import 语句，则导入模块到 globals 中）。

另请参阅

例如

import monai
from monai.bundle import ConfigExpression

config = "$monai.__version__"
expression = ConfigExpression(config, id="test", globals={"monai": monai})
print(expression.evaluate())
参数:

  • config – 配置项的内容。

  • id – 当前配置项的名称，默认为空字符串。

  • globals – 用于评估字符串的额外全局上下文。

evaluate(globals=None, locals=None)[source]#

执行当前配置内容并返回结果（如果它是表达式），基于 Python 的 eval()。更多详细信息：https://docs.pythonlang.cn/3/library/functions.html#eval。

参数:

  • globals – 除了 self.globals 之外，运行时表达式中使用的其他全局符号。

  • locals – 除了 globals 之外，还可能有一些运行时表达式中使用的局部符号。

classmethod is_expression(config)[source]#

检查配置是否为可执行表达式字符串。目前，以 "$" 字符开头的字符串被解释为表达式。

参数:

config – 输入的配置内容以检查。

classmethod is_import_statement(config)[source]#

检查配置是否为 import 语句（表达式的一种特殊情况）。

参数:

config – 输入的配置内容以检查。

class monai.bundle.ConfigItem(config, id='')[source]#

表示配置项的基本数据结构。

一个 ConfigItem 实例可以选择有一个字符串 id，以便其他项可以引用它。它有一个内置的 config 属性来存储配置对象。

参数:

  • config (Any) – 配置项的内容，可以是任何类型的对象，配置解析器可能会解释内容以生成配置对象。

  • id (str) – 当前配置项的名称，默认为空字符串。

get_config()[source]#

获取当前配置项的配置内容。

get_id()[source]#

获取当前配置项的 ID 名称，在解析过程中用于识别配置项。

返回类型:

str

update_config(config)[source]#

用新的 config 替换 self.config 的内容。典型用法是在运行时修改初始配置内容。

参数:

config (Any) – ConfigItem 的内容。

返回类型:

None

引用解析器#

class monai.bundle.ReferenceResolver(items=None)[source]#

管理一组 ConfigItem 并解析它们之间引用的实用类。

此类维护一组 ConfigItem 对象及其关联的 ID。ID 在此集合中必须是唯一的。ConfigItem 中以 @ 开头的字符串将被视为按 ID 引用其他 ConfigItem 对象。由于 ConfigItem 可能具有嵌套的字典或列表结构，因此引用字符串可能还包含分隔符 ::，以通过字典的键索引或列表的整数索引来引用子结构。

在此类中，解析引用本质上是将引用字符串替换为相应的 Python 对象。典型的引用解析工作流程如下：

  • 通过 add_item() 将多个 ConfigItem 对象添加到 ReferenceResolver 中。

  • 调用 get_resolved_content() 自动解析引用。这通过（递归）以下方式完成：
    • 将没有引用其他项的项转换为对象。

      • 如果可实例化，则实例化它并将类实例缓存到 resolved_content 中。

      • 如果它是表达式，则评估它并将值保存到 resolved_content 中。

    • 将引用字符串替换为相应的对象。

参数:

items – 要解析的 ConfigItem``s，稍后可以使用 ``add_item() 添加。

add_item(item)[source]#

将 ConfigItem 添加到解析器中。

参数:

item (ConfigItem) – 一个 ConfigItem。

返回类型:

None

classmethod find_refs_in_config(config, id, refs=None)[source]#

递归搜索输入配置项的所有内容以获取引用的 ID。引用表示：其他配置项的 ID（此配置项中的 "@XXX"），或者配置中的子项是 instantiable，或者配置中的子项是 expression。对于 dict 和 list，递归检查子项。

参数:

  • config – 要搜索的输入配置内容。

  • id – 输入配置项的 ID 名称。

  • refs – 找到的引用 ID 名称及其数量的字典，默认为 None。

get_item(id, resolve=False, **kwargs)[source]#

按 id 获取 ConfigItem。

如果 resolve=True，返回的项将被解析，即所有引用字符串都将替换为相应的 ConfigItem 对象。

参数:

  • id – 预期配置项的 id。

  • resolve – 如果项未解析，是否解析它，默认为 False。

  • kwargs – 传递给 _resolve_one_item() 的关键字参数。目前支持 instantiate 和 eval_expr。两者都默认为 True。

get_resolved_content(id, **kwargs)[source]#

按 id 获取已解析的 ConfigItem。

参数:

  • id – 预期项的 id 名称。

  • kwargs – 传递给 _resolve_one_item() 的关键字参数。目前支持 instantiate、eval_expr 和 default。instantiate 和 eval_expr 默认为 True，default 是如果 id 不在配置内容中，则为默认配置项，它必须是一个 ConfigItem` 对象。

classmethod iter_subconfigs(id, config)[source]#

迭代输入配置的子配置，输出 sub_id 使用 cls.sep 表示子结构。

参数:

  • id (str) – 当前输入配置的 id 字符串。

  • config (Any) – 要迭代的输入配置。

返回类型:

Iterator[tuple[str, str, Any]]

classmethod match_refs_pattern(value)[source]#

对输入字符串匹配正则表达式以查找引用。引用字符串以 "@" 开头，例如："@XXX::YYY::ZZZ"。

参数:

value (str) – 用于匹配正则表达式的输入值。

返回类型:

dict[str, int]

classmethod normalize_id(id)[source]#

标准化 id 字符串以始终使用 cls.sep。

参数:

id – 要标准化的 id 字符串。

normalize_meta_id(config)[source]#

使用 DEPRECATED_ID_MAPPING 更新 config 中的弃用标识符。这将把标记为弃用的名称替换为其替代名称。

参数:

config (Any) – 要更新的输入配置。

返回类型:

Any

reset()[source]#

清除所有添加的 ConfigItem 和所有已解析的内容。

classmethod split_id(id, last=False)[source]#

按 cls.sep 将 id 字符串分割成字符串列表。

参数:

  • id – 要分割的 id 字符串。

  • last – 是否分割 id 的最右侧部分。默认为 False（分割所有部分）。

classmethod update_config_with_refs(config, id, refs=None)[source]#

利用 refs 中的所有引用，更新输入配置内容并返回新的配置。

参数:

  • config – 要更新的输入配置内容。

  • id – 输入配置的 ID 名称。

  • refs – 包含 id 的所有引用内容，默认为 None。

classmethod update_refs_pattern(value, refs)[source]#

对输入字符串匹配正则表达式，以使用引用更新内容。引用部分以 "@" 开头，例如："@XXX::YYY::ZZZ"。引用字典必须包含引用 ID 作为键。

参数:

  • value (str) – 用于匹配正则表达式的输入值。

  • refs (dict) – 所有包含 id 作为键的引用组件，默认为 None。

返回类型:

str

配置解析器#

class monai.bundle.ConfigParser(config=None, excludes=None, globals=None)[source]#

主要的配置解析器。它遍历结构化配置（嵌套的 Python 字典或列表形式），创建 ConfigItem，并根据结构分配唯一的 ID。

此类提供了通过 ID 方便访问配置中 ConfigItem 集合的方式。典型的配置解析工作流程如下：

  • 使用 config 源初始化 ConfigParser。

  • 调用 get_parsed_content() 获取具有指定 id 的预期组件。

from monai.bundle import ConfigParser

config = {
    "my_dims": 2,
    "dims_1": "$@my_dims + 1",
    "my_xform": {"_target_": "LoadImage"},
    "my_net": {"_target_": "BasicUNet", "spatial_dims": "@dims_1", "in_channels": 1, "out_channels": 4},
    "trainer": {"_target_": "SupervisedTrainer", "network": "@my_net", "preprocessing": "@my_xform"}
}
# in the example $@my_dims + 1 is an expression, which adds 1 to the value of @my_dims
parser = ConfigParser(config)

# get/set configuration content, the set method should happen before calling parse()
print(parser["my_net"]["in_channels"])  # original input channels 1
parser["my_net"]["in_channels"] = 4  # change input channels to 4
print(parser["my_net"]["in_channels"])

# instantiate the network component
parser.parse(True)
net = parser.get_parsed_content("my_net", instantiate=True)
print(net)

# also support to get the configuration content of parsed `ConfigItem`
trainer = parser.get_parsed_content("trainer", instantiate=False)
print(trainer)
参数:

  • config – 要解析的输入配置源。

  • excludes – 导入模块以实例化组件时，排除 excludes 中指定的模块中的组件。

  • globals – 预导入包作为全局变量到 ConfigExpression 中，以便表达式（例如 "$monai.data.list_data_collate"）可以使用 monai 模块。当前支持的全局变量和别名包括 {"monai": "monai", "torch": "torch", "np": "numpy", "numpy": "numpy"}。这些是 MONAI 的最小依赖项。可以通过 globals={“itk”: “itk”} 包含额外的包。将其设置为 False 可禁用 self.globals 模块导入。

另请参阅

__contains__(id)[source]#

如果此配置中存储了 id，则返回 True。

参数:

id – 用于指定预期位置的 id。另请参阅 __getitem__()。

__getattr__(id)[source]#

获取具有指定 id 的 ConfigItem 的解析结果，使用默认参数（例如 lazy=True、instantiate=True 和 eval_expr=True）。

参数:

id – ConfigItem 的 id。

另请参阅

get_parsed_content()

__getitem__(id)[source]#

按 id 获取配置。

参数:

id – ConfigItem 的 id，id 中的 "::"（或 "#"）被解释为特殊字符，用于进一步进入嵌套结构一层。对于列表，使用从“0”开始的数字索引；对于字典，使用其他字符串索引。例如："xform::5"、"net::channels"。"" 表示整个 self.config。

__init__(config=None, excludes=None, globals=None)[source]#
__repr__()[source]#

返回 repr(self)。

__setitem__(id, config)[source]#

按 id 设置配置。请注意，应在 parse() 或 get_parsed_content() 之前使用此方法，以确保更新包含在解析内容中。

参数:

  • id – ConfigItem 的 id，id 中的 "::"（或 "#"）被解释为特殊字符，用于进一步进入嵌套结构一层。对于列表，使用从“0”开始的数字索引；对于字典，使用其他字符串索引。例如："xform::5"、"net::channels"。"" 表示整个 self.config。

  • config – 要在位置 id 设置的配置。

__weakref__#

指向对象的弱引用列表（如果已定义）

classmethod export_config_file(config, filepath, fmt='json', **kwargs)[source]#

将配置内容导出到指定的文件路径（当前支持 JSON 和 YAML 文件）。

参数:

  • config (dict) – 要导出的源配置内容。

  • filepath (Union[str, PathLike]) – 目标保存文件路径。

  • fmt (str) – 配置内容的格式，当前支持 "json" 和 "yaml"。

  • kwargs (Any) – json.dump 或 yaml.safe_dump 的其他参数，取决于文件格式。

返回类型:

None

get(id='', default=None)[source]#

按 id 获取配置。

参数:

  • id – 用于指定预期位置的 id。另请参阅 __getitem__()。

  • default – 如果指定的 id 无效，则返回的默认值。

get_parsed_content(id='', **kwargs)[source]#

获取具有指定 id 的 ConfigItem 的解析结果。

  • 如果项是 ConfigComponent 且 instantiate=True，结果是实例。

  • 如果项是 ConfigExpression 且 eval_expr=True，结果是评估输出。

  • 否则，结果是 ConfigItem 的配置内容。

参数:

  • id (str) – ConfigItem 的 id，id 中的 "::"（或 "#"）被解释为特殊字符，用于进一步进入嵌套结构一层。对于列表，使用从“0”开始的数字索引；对于字典，使用其他字符串索引。例如："xform::5"、"net::channels"。"" 表示整个 self.config。

  • kwargs (Any) – 要传递给 _resolve_one_item 的额外关键字参数。目前支持 lazy（是否保留当前配置缓存，默认为 True）、instantiate（是否实例化 ConfigComponent，默认为 True）和 eval_expr（是否评估 ConfigExpression，默认为 True）、default（如果 id 不在配置内容中，则为默认配置项）。

返回类型:

Any

classmethod load_config_file(filepath, **kwargs)[source]#

加载指定文件路径的单个配置文件（当前支持 JSON 和 YAML 文件）。

参数:

  • filepath (Union[str, PathLike]) – 要加载的目标文件路径，支持的后缀：.json，.yml，.yaml。

  • kwargs (Any) – json.load 或 ``yaml.safe_load`` 的其他参数，取决于文件格式。

返回类型:

dict

classmethod load_config_files(files, **kwargs)[source]#

将多个配置文件加载到单个配置字典中。列表中的后一个配置文件将覆盖或添加前一个配置文件。配置键中的 "::"（或 "#"）被解释为特殊字符，用于进一步进入嵌套结构一层。

参数:

  • files – 要加载的目标文件路径，支持的后缀：.json，.yml，.yaml。如果提供文件列表，将合并它们的内容。如果提供带有逗号分隔文件路径的字符串，将合并它们的内容。如果提供字典，则直接返回。

  • kwargs – json.load 或 ``yaml.safe_load`` 的其他参数，取决于文件格式。

parse(reset=True)[source]#

递归解析 self.config，用目标内容替换宏标记。然后递归解析配置源，将每个项作为 ConfigItem 添加到引用解析器中。

参数:

reset (bool) – 解析前是否重置 reference_resolver。默认为 True。

返回类型:

None

read_config(f, **kwargs)[source]#

从指定的 JSON/YAML 文件或字典读取配置，并覆盖 self.config 字典中的配置内容。

参数:

  • f – 配置文件的文件路径，内容必须是一个字典。如果提供文件列表，将合并它们的内容。如果直接提供字典，则将其用作配置。

  • kwargs – json.load 或 yaml.safe_load 的其他参数，取决于文件格式。

read_meta(f, **kwargs)[source]#

从指定的 JSON 或 YAML 文件读取元数据。元数据作为字典将存储在 self.config["_meta_"] 中。

参数:

  • f – 元数据文件的文件路径，内容必须是一个字典。如果提供文件列表，将合并它们的内容。如果直接提供字典，则将其用作元数据。

  • kwargs – json.load 或 yaml.safe_load 的其他参数，取决于文件格式。

resolve_macro_and_relative_ids()[source]#

递归解析 self.config，将相对 id 替换为绝对 id，例如，@##A 表示上一级别的 A。并用目标内容替换宏标记，宏标记以“%”开头，可以来自另一个结构化文件，例如："%default_net"，"%/data/config.json::net"。

classmethod resolve_relative_ids(id, value)[source]#

为了简化嵌套配置内容中的引用或宏标记 ID，可以使用以 ID_SEP_KEY 开头的相对 ID 名称，例如，“@#A” 表示同一级别的 A，“@##A” 表示上一级别的 A。它将相对 id 解析为绝对 id。例如，如果输入数据是

{
    "A": 1,
    "B": {"key": "@##A", "value1": 2, "value2": "%#value1", "value3": [3, 4, "@#1"]},
}

它将把 B 解析为 {“key”: “@A”, “value1”: 2, “value2”: “%B#value1”, “value3”: [3, 4, “@B#value3#1”]}。

参数:

  • id (str) – 当前配置项的 id 名称，用于计算相对 id。

  • value (str) – 要解析相对 id 的输入值。

返回类型:

str

set(config, id='', recursive=True)[source]#

按 id 设置配置。

参数:

  • config (Any) – 要在位置 id 设置的配置。

  • id (str) – 用于指定预期位置的 id。另请参阅 __setitem__()。

  • recursive (bool) – 如果嵌套 id 不存在，是否递归创建配置中的嵌套项。默认为 True。对于嵌套 id，缺失的部分只支持 dict。

返回类型:

None

classmethod split_path_id(src)[source]#

将 src 字符串分割为两部分：配置文件路径和组件 id。文件路径应以 (json|yaml|yml) 结尾。如果存在，组件 id 应由 :: 分隔。如果没有路径或没有 id，则返回 ""。

参数:

src (str) – 要分割的源字符串。

返回类型:

tuple[str, str]

update(pairs)[source]#

成对设置 id 和相应的配置内容，另请参阅 __setitem__()。例如，parser.update({"train::epoch": 100, "train::lr": 0.02})

参数:

pairs (dict[str, Any]) – id 和配置对的字典。

返回类型:

None

脚本#

monai.bundle.ckpt_export(net_id=None, filepath=None, ckpt_file=None, meta_file=None, config_file=None, key_in_ckpt=None, use_trace=None, input_shape=None, args_file=None, converter_kwargs=None, **override)[source]#

将模型检查点导出到给定文件路径，包含元数据和配置（作为 JSON 文件）。

典型用法示例

python -m monai.bundle ckpt_export network --filepath <export path> --ckpt_file <checkpoint path> ...
参数:

  • net_id – 配置中网络组件的 ID 名称，必须是 torch.nn.Module。默认为“network_def”。

  • filepath – 要导出的文件路径，如果文件名没有扩展名，则变为 .ts。如果未指定 bundle_root，则默认为“os.getcwd()”下的“models/model.ts”。

  • ckpt_file – 要加载的模型检查点的文件路径。如果未指定 bundle_root，则默认为“os.getcwd()”下的“models/model.pt”。

  • meta_file – 元数据文件的文件路径，如果它是文件路径列表，将合并其内容。如果未指定 bundle_root，则默认为“os.getcwd()”下的“configs/metadata.json”。

  • config_file – 要保存到 TorchScript 模型中并提取网络信息的配置文件的文件路径，在 TorchScript 模型中保存的键是去掉了扩展名的配置文件名，并且无论原始文件格式是 JSON 还是 YAML，保存的配置值始终序列化为 JSON 格式。它可以是单个文件或文件列表。如果为 None，则必须在 args_file 中提供。

  • key_in_ckpt – 对于嵌套检查点，例如 {“model”: XXX, “optimizer”: XXX, …}，指定模型权重的键。如果不是嵌套检查点，则无需设置。

  • use_trace – 是否使用 torch.jit.trace 将 PyTorch 模型转换为 TorchScript 模型。

  • input_shape – 用于在将模型转换为 TorchScript 模型时生成网络随机输入的形状。应为 [N, C, H, W] 或 [N, C, H, W, D] 这样的列表。如果未给出，将尝试从 metadata 配置中解析。

  • args_file – 一个 JSON 或 YAML 文件，用于为此函数的所有参数提供默认值，以便简化命令行输入。

  • converter_kwargs – convert_to_torchscript 需要的额外参数，除了输入参数中已有的参数之外。

  • override – 用于覆盖或添加相应配置内容的 id-value 对。例如 --_meta#network_data_format#inputs#image#num_channels 3。

monai.bundle.trt_export(net_id=None, filepath=None, ckpt_file=None, meta_file=None, config_file=None, key_in_ckpt=None, precision=None, input_shape=None, use_trace=None, dynamic_batchsize=None, device=None, use_onnx=None, onnx_input_names=None, onnx_output_names=None, args_file=None, converter_kwargs=None, **override)[source]#

将模型检查点导出到给定文件路径作为基于 TensorRT 引擎的 TorchScript。目前，此 API 仅支持转换输入均为张量的模型。

有两种导出模型的方式：1. Torch-TensorRT 方式：PyTorch 模块 —> TorchScript 模块 —> 基于 TensorRT 引擎的 TorchScript。2. ONNX-TensorRT 方式：PyTorch 模块 —> TorchScript 模块 —> ONNX 模型 —> TensorRT 引擎 —> 基于 TensorRT 引擎的 TorchScript。

通过第一种方式导出时，某些模型会出现慢速问题，因为 Torch-TensorRT 可能只将 PyTorch 模型的一小部分转换为 TensorRT 引擎。然而，通过第二种方式导出时，不支持某些 Python 数据结构，例如 dict。并且，如果通过 torch.jit.script 导出的某些 TorchScript 模型，ONNX 也不支持。

典型用法示例

python -m monai.bundle trt_export --net_id <network definition> --filepath <export path>             --ckpt_file <checkpoint path> --input_shape <input shape> --dynamic_batchsize <batch range> ...
参数:

  • net_id – 配置中网络组件的 ID 名称，它必须是 torch.nn.Module。

  • filepath – 导出文件路径，如果文件名没有扩展名，则将变为 .ts。

  • ckpt_file – 要加载的模型检查点的文件路径。

  • meta_file – 元数据文件路径，如果是一个文件路径列表，它们的内容将被合并。

  • config_file – 在基于 TensorRT 的 TorchScript 模型中保存配置的文件路径，用于提取网络信息。模型中保存的键是没有扩展名的配置文件名，保存的配置值始终以 JSON 格式序列化，无论原始文件格式是 JSON 还是 YAML。它可以是单个文件或文件列表。如果为 None，则必须在 args_file 中提供。

  • key_in_ckpt – 对于嵌套检查点，例如 {“model”: XXX, “optimizer”: XXX, …}，指定模型权重的键。如果不是嵌套检查点，则无需设置。

  • precision – 转换后的基于 TensorRT 引擎的 TorchScript 模型的权重精度。应为“fp32”或“fp16”。

  • input_shape – 用于转换模型的输入形状。应为类似 [N, C, H, W] 或 [N, C, H, W, D] 的列表。如果未给出，将尝试从 metadata 配置中解析。

  • use_trace – 是否使用 torch.jit.trace 将 PyTorch 模型转换为 TorchScript 模型，然后将其转换为基于 TensorRT 引擎的 TorchScript 模型或 ONNX 模型（如果 use_onnx 为 True）。

  • dynamic_batchsize – 定义要转换模型的输入的批大小范围的包含三个元素的序列。应为类似 [MIN_BATCH, OPT_BATCH, MAX_BATCH] 的序列。转换后，模型输入的批大小应介于 MIN_BATCH 和 MAX_BATCH 之间，而 OPT_BATCH 是 TensorRT 尝试拟合的最佳性能批大小。OPT_BATCH 应是应用程序中最常使用的输入批大小。

  • device – 用于转换和验证模型的目标 GPU 索引。

  • use_onnx – 是否使用 ONNX-TensorRT 方式导出基于 TensorRT 引擎的 TorchScript 模型。

  • onnx_input_names – ONNX 模型的可选输入名称。此参数仅在 use_onnx 为 True 时有用。应为类似 [‘input_0’, ‘input_1’, …, ‘input_N’] 的序列，其中 N 等于模型输入的数量。如果未给出，将使用 [‘input_0’]，这表示模型只有一个输入。

  • onnx_output_names – ONNX 模型的可选输出名称。此参数仅在 use_onnx 为 True 时有用。应为类似 [‘output_0’, ‘output_1’, …, ‘output_N’] 的序列，其中 N 等于模型输出的数量。如果未给出，将使用 [‘output_0’]，这表示模型只有一个输出。

  • args_file – 一个 JSON 或 YAML 文件，用于为此函数的所有参数提供默认值，以便简化命令行输入。

  • converter_kwargs – convert_to_trt 需要的额外参数，除了输入参数中已有的参数。

  • override – 用于覆盖或添加相应配置内容的 id-value 对。例如 --_meta#network_data_format#inputs#image#num_channels 3。

monai.bundle.onnx_export(net_id=None, filepath=None, ckpt_file=None, meta_file=None, config_file=None, key_in_ckpt=None, use_trace=None, input_shape=None, args_file=None, converter_kwargs=None, **override)[source]#

将模型检查点导出到 onnx 模型。

典型用法示例

python -m monai.bundle onnx_export network --filepath <export path> --ckpt_file <checkpoint path> ...
参数:

  • net_id – 配置中网络组件的 ID 名称，它必须是 torch.nn.Module。

  • filepath – 保存 onnx 模型的文件路径。

  • ckpt_file – 要加载的模型检查点的文件路径。

  • meta_file – 元数据文件路径，如果是一个文件路径列表，它们的内容将被合并。

  • config_file – 包含提取网络信息的配置文件路径，

  • key_in_ckpt – 对于嵌套检查点，例如 {“model”: XXX, “optimizer”: XXX, …}，指定模型权重的键。如果不是嵌套检查点，则无需设置。

  • use_trace – 是否使用 torch.jit.trace 将 pytorch 模型转换为 torchscript 模型。

  • input_shape – 用于在将模型转换为 onnx 模型时生成网络随机输入的形状。应为类似 [N, C, H, W] 或 [N, C, H, W, D] 的列表。如果未给出，将尝试从 metadata 配置中解析。

  • args_file – 一个 JSON 或 YAML 文件，用于为此函数的所有参数提供默认值，以便简化命令行输入。

  • converter_kwargs – convert_to_onnx 需要的额外参数，除了输入参数中已有的参数。

  • override – 用于覆盖或添加相应配置内容的 id-value 对。例如 --_meta#network_data_format#inputs#image#num_channels 3。

monai.bundle.download(name=None, version=None, bundle_dir=None, source='monaihosting', repo=None, url=None, remove_prefix='monai_', progress=True, args_file=None)[source]#

从指定的源或 URL 下载 Bundle。Bundle 应该是 ZIP 文件，下载后会解压。此函数参考：https://pytorch.ac.cn/docs/stable/_modules/torch/hub.html

典型用法示例

# Execute this module as a CLI entry, and download bundle from the model-zoo repo:
python -m monai.bundle download --name <bundle_name> --version "0.1.0" --bundle_dir "./"

# Execute this module as a CLI entry, and download bundle from specified github repo:
python -m monai.bundle download --name <bundle_name> --source "github" --repo "repo_owner/repo_name/release_tag"

# Execute this module as a CLI entry, and download bundle from ngc with latest version:
python -m monai.bundle download --name <bundle_name> --source "ngc" --bundle_dir "./"

# Execute this module as a CLI entry, and download bundle from monaihosting with latest version:
python -m monai.bundle download --name <bundle_name> --source "monaihosting" --bundle_dir "./"

# Execute this module as a CLI entry, and download bundle from Hugging Face Hub:
python -m monai.bundle download --name "bundle_name" --source "huggingface_hub" --repo "repo_owner/repo_name"

# Execute this module as a CLI entry, and download bundle via URL:
python -m monai.bundle download --name <bundle_name> --url <url>

# Execute this module as a CLI entry, and download bundle from ngc_private with latest version:
python -m monai.bundle download --name <bundle_name> --source "ngc_private" --bundle_dir "./" --repo "org/org_name"

# Set default args of `run` in a JSON / YAML file, help to record and simplify the command line.
# Other args still can override the default args at runtime.
# The content of the JSON / YAML file is a dictionary. For example:
# {"name": "spleen", "bundle_dir": "download", "source": ""}
# then do the following command for downloading:
python -m monai.bundle download --args_file "args.json" --source "github"
参数:

  • name – Bundle 名称。如果为 None 且 url 为 None，则必须在 args_file 中提供。例如：model-zoo 中的 “spleen_ct_segmentation”、“prostate_mri_anatomy”：Project-MONAI/model-zoo。ngc 中的 “monai_brats_mri_segmentation”：https://catalog.ngc.nvidia.com/models?filters=&orderBy=scoreDESC&query=monai。

  • version – 要下载的目标 Bundle 的版本名称，如：“0.1.0”。如果为 None，将下载最新版本（或在 Hugging Face Hub 的情况下是 main 分支的最后一次提交）。

  • bundle_dir – 存储下载数据的目标目录。默认为 torch.hub.get_dir() 下的 bundle 子文件夹。

  • source – 存储位置名称。当 url 为 None 时使用此参数。默认情况下，该值从环境变量 BUNDLE_DOWNLOAD_SRC 获取，应为“ngc”、“monaihosting”、“github”、“ngc_private”或“huggingface_hub”。如果 source 为“ngc_private”，则需要在环境变量中指定 NGC_API_KEY。

  • repo – 仓库名称。当 url 为 None 且 source 为“github”或“huggingface_hub”时使用此参数。如果 source 为“github”，格式应为“repo_owner/repo_name/release_tag”。如果 source 为“huggingface_hub”，格式应为“repo_owner/repo_name”。如果 source 为“ngc_private”，格式应为“org/org_name”或“org/org_name/team/team_name”，或者您可以指定环境变量 NGC_ORG 和 NGC_TEAM。

  • url – 下载数据的 URL。如果不是 None，将直接下载数据，且不检查 source。如果 name 为 None，文件名由 monai.apps.utils._basename(url) 确定。

  • remove_prefix – 此参数在 source 为“ngc”或“ngc_private”时使用。目前，所有 ngc Bundle 都有 monai_ 前缀，这在它们的 model zoo 对比中不存在。为了保持这两种来源之间的一致性，删除前缀是必要的。因此，如果指定了前缀，下载的文件夹名称将删除该前缀。

  • progress – 是否显示进度条。

  • args_file – 一个 JSON 或 YAML 文件，为本函数中的所有参数提供默认值，以便简化命令行输入。

monai.bundle.load(name, model=None, version=None, workflow_type='train', model_file=None, load_ts_module=False, bundle_dir=None, source='monaihosting', repo=None, remove_prefix='monai_', progress=True, device=None, key_in_ckpt=None, config_files=(), workflow_name=None, args_file=None, copy_model_args=None, return_state_dict=True, net_override=None, net_name=None, **net_kwargs)[source]#

加载 Bundle 的模型权重或 TorchScript 模块。

参数:

  • name – Bundle 名称。如果为 None 且 url 为 None，则必须在 args_file 中提供。例如：model-zoo 中的 “spleen_ct_segmentation”、“prostate_mri_anatomy”：Project-MONAI/model-zoo。ngc 中的 “monai_brats_mri_segmentation”：https://catalog.ngc.nvidia.com/models?filters=&orderBy=scoreDESC&query=monai。monaihosting 中的 “mednist_gan”：https://api.ngc.nvidia.com/v2/models/nvidia/monaihosting/mednist_gan/versions/0.2.0/files/mednist_gan_v0.2.0.zip

  • model – 要更新的 pytorch 模块。默认为 None，使用 Bundle 中的“network_def”。

  • version – 要下载的目标 Bundle 的版本名称，如：“0.1.0”。如果为 None，将下载最新版本。如果 source 为“huggingface_hub”，此参数为 Git 修订 ID。

  • workflow_type – 指定工作流类型：“train”或“training”用于训练工作流，“infer”、“inference”、“eval”、“evaluation”用于推理工作流，其他不支持的字符串将引发 ValueError。训练工作流默认为 train。

  • model_file – Bundle 内模型权重或 TorchScript 模块的相对路径。如果为 None，将使用“models/model.pt”或“models/model.ts”。

  • load_ts_module – 一个标志，用于指定是否加载 TorchScript 模块。

  • bundle_dir – 加载权重/TorchScript 模块的目录。默认为 torch.hub.get_dir() 下的 bundle 子文件夹。

  • source – 存储位置名称。当 model_file 本地不存在且需要先下载时使用此参数。默认情况下，该值从环境变量 BUNDLE_DOWNLOAD_SRC 获取，应为“ngc”、“monaihosting”、“github”或“huggingface_hub”。

  • repo – 仓库名称。当 url 为 None 且 source 为“github”或“huggingface_hub”时使用此参数。如果 source 为“github”，格式应为“repo_owner/repo_name/release_tag”。如果 source 为“huggingface_hub”，格式应为“repo_owner/repo_name”。

  • remove_prefix – 此参数在 source 为“ngc”时使用。目前，所有 ngc Bundle 都有 monai_ 前缀，这在它们的 model zoo 对比中不存在。为了保持这三种来源之间的一致性，删除前缀是必要的。因此，如果指定了前缀，下载的文件夹名称将删除该前缀。

  • progress – 下载时是否显示进度条。

  • device – 返回的权重或模块的目标设备，如果为 None，优先使用“cuda”（如果存在）。

  • key_in_ckpt – 对于嵌套检查点，例如 {“model”: XXX, “optimizer”: XXX, …}，指定模型权重的键。如果不是嵌套检查点，则无需设置。

  • config_files – 要加载的额外文件名。此参数仅在加载 TorchScript 模块时有效，更多详情请参阅 torch.jit.load 中的 _extra_files。

  • workflow_name – 指定的 Bundle 工作流名称，应为字符串或类，默认为“ConfigWorkflow”。

  • args_file – 一个 JSON 或 YAML 文件，为“download”函数中的所有参数提供默认值。

  • copy_model_args – monai.networks.copy_model_state 函数的其他参数。

  • return_state_dict – 是否返回状态字典，如果为 True，则返回 state_dict，否则将实例化 _workflow.network_def 中相应的网络并加载获取的权重。

  • net_override – ID-值对，用于覆盖 Bundle 网络中的参数，默认为 None。

  • net_name – 如果不为 None，将实例化相应的网络并加载获取的权重。此参数仅在加载权重时有效。

  • net_kwargs – 用于实例化由 net_name 定义的网络类的其他参数。

返回:

  1. 如果 load_ts_module 为 False 且 model 为 None，

    如果 Bundle 中找不到“network_def”，则返回模型权重，否则返回已加载权重的实例化网络。

  2. 如果 load_ts_module 为 False 且 model 不为 None，

    返回已加载权重的实例化网络。

  3. 如果 load_ts_module 为 True，则返回一个三元组，包括 TorchScript 模块，

    相应的元数据字典和额外文件字典。更多详情请查阅 monai.data.load_net_with_metadata。

  4. 如果 return_state_dict 为 True，则返回模型权重，仅用于兼容性

    当 model 和 net_name 均为 None 时。

monai.bundle.get_all_bundles_list(repo='Project-MONAI/model-zoo', tag='dev', auth_token=None)[source]#

获取存储在指定仓库发布版本中具有指定标签的所有 Bundle 名称（和最新版本）。如果标签为“dev”，将从 https://raw.githubusercontent.com/repo_owner/repo_name/dev/models/model_info.json 获取模型信息。参数的默认值对应于 MONAI model zoo 的发布版本。为了增加调用 Github API 的速率限制，您可以输入个人访问令牌。有关速率限制的更多详情，请参阅以下链接：https://githubdocs.cn/en/rest/overview/resources-in-the-rest-api#rate-limiting

以下链接显示如何创建个人访问令牌：https://githubdocs.cn/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

参数:

  • repo – 格式应为“repo_owner/repo_name/”。

  • tag – 发布版本的标签名称。

  • auth_token – Github 个人访问令牌。

返回:

格式为（Bundle 名称，最新版本）的元组列表。

monai.bundle.get_bundle_info(bundle_name, version=None, repo='Project-MONAI/model-zoo', tag='dev', auth_token=None)[source]#

获取具有指定 Bundle 名称和版本的所有信息（包括“name”和“browser_download_url”），这些信息存储在指定仓库发布版本中具有指定标签。为了增加调用 Github API 的速率限制，您可以输入个人访问令牌。有关速率限制的更多详情，请参阅以下链接：https://githubdocs.cn/en/rest/overview/resources-in-the-rest-api#rate-limiting

以下链接显示如何创建个人访问令牌：https://githubdocs.cn/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

参数:

  • bundle_name – Bundle 名称。

  • version – 目标 Bundle 的版本名称，如果为 None，将使用最新版本。

  • repo – 格式应为“repo_owner/repo_name/”。

  • tag – 发布版本的标签名称。

  • auth_token – Github 个人访问令牌。

返回:

包含 Bundle 信息的字典。

monai.bundle.get_bundle_versions(bundle_name, repo='Project-MONAI/model-zoo', tag='dev', auth_token=None)[source]#

获取存储在指定仓库发布版本中具有指定标签的 Bundle 的最新版本以及所有现有版本。如果标签为“dev”，将从 https://raw.githubusercontent.com/repo_owner/repo_name/dev/models/model_info.json 获取模型信息。为了增加调用 Github API 的速率限制，您可以输入个人访问令牌。有关速率限制的更多详情，请参阅以下链接：https://githubdocs.cn/en/rest/overview/resources-in-the-rest-api#rate-limiting

以下链接显示如何创建个人访问令牌：https://githubdocs.cn/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

参数:

  • bundle_name – Bundle 名称。

  • repo – 格式应为“repo_owner/repo_name/”。

  • tag – 发布版本的标签名称。

  • auth_token – Github 个人访问令牌。

返回:

包含 Bundle 最新版本和所有版本的字典。

monai.bundle.run(run_id=None, init_id=None, final_id=None, meta_file=None, config_file=None, logging_file=None, tracking=None, args_file=None, **override)[source]#

指定 config_file 运行 MONAI Bundle 组件和工作流。

典型用法示例

# Execute this module as a CLI entry:
python -m monai.bundle run --meta_file <meta path> --config_file <config path>

# Execute with specified `run_id=training`:
python -m monai.bundle run training --meta_file <meta path> --config_file <config path>

# Execute with all specified `run_id=runtest`, `init_id=inittest`, `final_id=finaltest`:
python -m monai.bundle run --run_id runtest --init_id inittest --final_id finaltest ...

# Override config values at runtime by specifying the component id and its new value:
python -m monai.bundle run --net#input_chns 1 ...

# Override config values with another config file `/path/to/another.json`:
python -m monai.bundle run --net %/path/to/another.json ...

# Override config values with part content of another config file:
python -m monai.bundle run --net %/data/other.json#net_arg ...

# Set default args of `run` in a JSON / YAML file, help to record and simplify the command line.
# Other args still can override the default args at runtime:
python -m monai.bundle run --args_file "/workspace/data/args.json" --config_file <config path>
参数:

  • run_id – 要运行的预期配置表达式的 ID 名称，默认为“run”。要运行配置，目标配置必须包含此 ID。

  • init_id – 在运行前要初始化的预期配置表达式的 ID 名称，默认为“initialize”。对于配置和此 run 函数都是可选的。

  • final_id – 运行后要完成的预期配置表达式的 ID 名称，默认为“finalize”。对于配置和此 run 函数都是可选的。

  • meta_file – 元数据文件路径，如果是一个文件路径列表，它们的内容将被合并。默认为 None。

  • config_file – 配置文件路径，如果为 None，则必须在 args_file 中提供。如果是一个文件路径列表，它们的内容将被合并。

  • logging_file – 程序中 logging 模块的配置文件。更多详情：https://docs.pythonlang.cn/3/library/logging.config.html#logging.config.fileConfig。默认为 None。

  • tracking –

    如果不为 None，则在运行时启用实验跟踪，可选择进行配置和扩展。如果为“mlflow”，将向解析后的 Bundle 添加 MLFlowHandler，并使用默认跟踪设置，其中将添加一组如下所示的常用参数，这些参数可通过此方法的 override 参数传递。

    • "output_dir": 本地保存 mlflow 跟踪输出的路径，默认为“<Bundle 根目录>/eval”。

    • "tracking_uri": 保存 mlflow 跟踪输出的 URI，默认为“/output_dir/mlruns”。

    • "experiment_name": 此运行的实验名称，默认为“monai_experiment”。

    • "run_name": 当前运行的名称。

    • "save_execute_config": 是否保存执行的配置文件。它可以是 False、/path/to/artifacts 或 True。如果设置为 True，将保存到默认路径“<Bundle 根目录>/eval”。默认为 True。

    如果是其他字符串，则视为加载跟踪设置的文件路径。如果是 dict，则视为跟踪设置。将使用 tracking handlers 和 configs 的顶级项来修补目标配置内容。详细使用示例请查阅教程：Project-MONAI/tutorials。

  • args_file – 一个 JSON 或 YAML 文件，为 run_id、meta_file、config_file、logging 和覆盖对提供默认值，以便简化命令行输入。

  • override – ID-值对，用于覆盖或添加相应的配置内容。例如：--net#input_chns 42, --net %/data/other.json#net_arg。

monai.bundle.verify_metadata(meta_file=None, filepath=None, create_dir=None, hash_val=None, hash_type=None, args_file=None, **kwargs)[source]#

根据预定义的 schema 验证提供的 metadata 文件。metadata 内容必须包含 schema 字段，用于下载 schema 文件的 URL。schema 标准遵循：https://json-schema.fullstack.org.cn/。

参数:

  • meta_file – 要验证的元数据文件路径，如果为 None，则必须在 args_file 中提供。如果是一个文件路径列表，它们的内容将被合并。

  • filepath – 存储下载的 schema 的文件路径。

  • create_dir – 目录不存在时是否创建目录，默认为 True。

  • hash_val – 如果不为 None，定义用于验证下载的 schema 文件的哈希值。

  • hash_type – 如果不为 None，定义用于验证下载的 schema 文件的哈希类型。默认为“md5”。

  • args_file – 一个 JSON 或 YAML 文件，为本函数中的所有参数提供默认值，以便简化命令行输入。

  • kwargs – jsonschema.validate() 的其他参数。更多详情：https://python-jsonschema.readthedocs.io/en/stable/validate/#jsonschema.validate。

monai.bundle.verify_net_in_out(net_id=None, meta_file=None, config_file=None, device=None, p=None, n=None, any=None, extra_forward_args=None, args_file=None, **override)[source]#

验证元数据中定义的网络的输入和输出数据形状及数据类型。将根据 metadata 中所需的数据形状使用虚假 Tensor 数据进行测试。

典型用法示例

python -m monai.bundle verify_net_in_out network --meta_file <meta path> --config_file <config path>
参数:

  • net_id – 要验证的网络组件的 ID 名称，它必须是 torch.nn.Module。

  • meta_file – 用于获取网络参数的元数据文件路径，如果为 None，则必须在 args_file 中提供。如果是一个文件路径列表，它们的内容将被合并。

  • config_file – 用于获取网络定义的配置文件路径，如果为 None，则必须在 args_file 中提供。如果是一个文件路径列表，它们的内容将被合并。

  • device – 运行网络前向计算的目标设备，如果为 None，优先使用“cuda”（如果存在）。

  • p – 如果预期形状的维度为“x**p”，则用于生成虚假数据形状的幂因子，默认为 1。

  • n – 如果预期形状的维度为“x*n”，则用于生成虚假数据形状的乘法因子，默认为 1。

  • any – 如果预期形状的维度为“*”，则用于生成虚假数据形状的指定大小，默认为 1。

  • extra_forward_args – 包含网络 forward 函数其他参数的字典。默认为空字典。

  • args_file – 一个 JSON 或 YAML 文件，为 net_id、meta_file、config_file、device、p、n、any 和覆盖对提供默认值，以便简化命令行输入。

  • override – 用于覆盖或添加相应配置内容的 id-value 对。例如 --_meta#network_data_format#inputs#image#num_channels 3。

monai.bundle.init_bundle(bundle_dir, ckpt_file=None, network=None, dataset_license=False, metadata_str=None, inference_str=None)[source]#

使用一些默认配置文件和可选的网络权重初始化新的 Bundle 目录。

典型使用示例

python -m monai.bundle init_bundle /path/to/bundle_dir network_ckpt.pt
参数:

  • bundle_dir – 要创建的目录名称，必须不存在，但父目录必须存在

  • ckpt_file – 要复制到 Bundle 的可选检查点文件

  • network – 如果给出此网络而不是 ckpt_file，则此网络的权重将存储在 Bundle 中

  • dataset_license – 如果为 True，将生成一个名为“data_license.txt”的默认许可证文件。如果您的 Bundle 使用的数据声明了任何许可证条件，则需要此文件。

  • metadata_str – 要写入 Bundle 的可选元数据字符串，如果未给出，将使用默认值。

  • inference_str – 要写入 Bundle 的可选推理字符串，如果未给出，将使用默认值。

monai.bundle.push_to_hf_hub(repo, name, bundle_dir, token=None, private=True, version=None, tag_as_latest_version=False, **upload_folder_kwargs)[source]#

将 MONAI Bundle 推送到 Hugging Face Hub。

典型用法示例

python -m monai.bundle push_to_hf_hub --repo <HF repository id> --name <bundle name>             --bundle_dir <bundle directory> --version <version> ...
参数:

  • repo – 命名空间（用户或组织）和仓库名称，用 / 分隔，例如 hf_username/bundle_name

  • bundle_name – 要推送的 Bundle 目录的名称。

  • bundle_dir – Bundle 目录的路径。

  • token – Hugging Face 身份验证令牌。默认为 None（将默认为存储的令牌）。

  • private – Hugging Face 仓库的私有可见性。默认为 True。

  • version_name – 要创建的版本标签的名称。默认为 None（不创建版本标签）。

  • tag_as_latest_version – 是否将提交标记为 latest_version。使用 bundle.download() 时将默认下载此版本。默认为 False。

  • upload_folder_kwargs – 传递给 HfApi.upload_folder 的关键字参数。

返回:

Hugging Face 仓库的 URL

返回类型:

repo_url

monai.bundle.update_kwargs(args=None, ignore_none=True, **kwargs)[source]#

使用输入的 kwargs 更新 args 字典。对于 dict 数据，根据键递归更新内容。

示例

from monai.bundle import update_kwargs
update_kwargs({'exist': 1}, exist=2, new_arg=3)
# return {'exist': 2, 'new_arg': 3}
参数:

  • args – 要更新的源 args 字典（或读取为字典的 json/yaml 文件名）。

  • ignore_none – 是否忽略 None 值的输入参数，默认为 True。

  • kwargs – 要合并到 args 中的键=值对。

本页内容
显示源代码