此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 类
  • BaseNode
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_train.nodes.base_node所有节点继承的基类。BaseNode 为节点提供其输入的形状,以便节点可以调整其层的尺寸。它将输入包映射到 forward 的参数。它还从命名变体构建节点,加载预训练权重,并切换导出模式。

类

BaseNode

模型图所有节点的基类。节点是一个 torch.nn.Module,它读取包并返回一个包。包是一个字典,它将输出名称映射到张量或张量列表。模型为节点的每个输入调用 run,并带有一个包。输入节点的包是其输出。加载器输入的包在键 "features" 下以列表形式保存张量。run 将包值传递给 forward 并将结果作为包返回。每个子类都将其自身注册到 luxonis_train.registry.NODES 中,名称为其类名,因此配置通过该名称引用节点。类语句中的 register_name 替换类名。在类语句中放置 register=False 以跳过注册。子类必须实现 forward。它还可以执行以下步骤:
  • 设置类属性 attach_index 和 task。
  • 覆盖 get_variants 以声明变体。
  • 覆盖 get_weights_url 以提供预训练权重。
  • 覆盖 initialize_weights 以初始化其自己的层。
  • 在类主体中注释属性,例如 in_channels: int。构造函数随后将属性值与注释进行比较。如果不匹配,它会引发 IncompatibleError。当属性引发 RuntimeError 时,构造函数会跳过检查。属性的任何其他错误都会从构造函数中抛出。检查只读取具有注释的最近类的注释。因此,子类的注释会隐藏其父类的注释。

方法

init
Python
1def __init__(*, input_shapes: list[Packet[Size]] | None = None, original_in_shape: Size | None = None, dataset_metadata: DatasetMetadata | None = None, n_classes: int | None = None, n_keypoints: int | None = None, in_sizes: Size | list[Size] | None = None, remove_on_export: bool = False, export_output_names: list[str] | None = None, attach_index: AttachIndexType | None = None, task_name: str | None = None, weights: str | Literal['download', 'yolo', 'none'] | None = None):
初始化节点。所有参数都是仅限关键字且可选的。依赖于缺失元数据的属性在访问时会引发 RuntimeError。参数
  • input_shapes (list[Packet[Size]] | None): 节点的每个输入一个形状包,按输入顺序排列。形状属性,例如 in_channels,会读取它。
  • original_in_shape (Size | None): 模型输入图像的形状,[C, H, W],不带批次维度。
  • dataset_metadata (DatasetMetadata | None): 数据集的元数据。n_classes、n_keypoints、classes 和 class_names 会读取它。
  • n_classes (int | None): 类的数量。设置后,n_classes 返回它,并且不读取 dataset_metadata。
  • n_keypoints (int | None): 关键点的数量。设置后,n_keypoints 返回它,并且不读取 dataset_metadata。
  • in_sizes (Size | list[Size] | None): 附加输入的大小。设置后,in_sizes 返回它,并且不读取 input_shapes。
  • remove_on_export (bool): 当为 True 时,模型在导出模式下会跳过该节点,因此导出的模型不包含该节点。
  • export_output_names (list[str] | None): 导出模型中节点输出的名称。有关导出如何使用它们,请参阅 export_output_names。None 保留默认名称。
  • attach_index (AttachIndexType | None): 节点读取的输入节点的输出。非 None 的值会替换类属性并记录警告。有关接受的值,请参阅 attach_index。
  • task_name (str | None): 节点的数据集任务。它选择 dataset_metadata 中的类和关键点。None 变为 ""。
  • weights (str | Literal['download', 'yolo', 'none'] | None): 权重的来源或初始化方法。变体元类在构造函数之后调用 __post_init__。该步骤读取值:
    • "download" 调用 load_checkpoint,它从 get_weights_url 获取 URL。
    • 包含 "://" 的字符串调用 load_checkpoint 并使用该 URL。
    • 任何其他字符串都作为方法传递给 initialize_weights。本地检查点路径也传递到那里,并且基本实现不加载它。
    • None 和 "" 的作用与 "none" 相同。
引发
  • AssertionError: 当 attach_index 为 None 且 forward 没有参数时。
  • IncompatibleError: 当类主体注释的属性具有不同类型的值时。
export.setter
Python
1def export.setter(mode: bool):
使用 set_export_mode 开启或关闭导出模式。
forward
Python
1def forward(inputs: Tensor | list[Tensor] | Packet[Tensor] | list[Packet[Tensor]]) -> Tensor | list[Tensor] | Packet[Tensor]:
计算节点的输出。子类必须实现它。run 读取每个参数的名称和类型注释以决定参数获取什么。使用 inputs 的四种类型之一注释每个参数。有关规则,请参阅 run。参数
  • inputs (Tensor | list[Tensor] | Packet[Tensor] | list[Packet[Tensor]]): 节点的输入。实现可以重命名参数并添加更多参数。
返回
  • Tensor | list[Tensor] | Packet[Tensor]: 节点的输出。run 将张量或张量列表放入包中。
get_attached
Python
1def get_attached(value: list[T] | T) -> list[T] | T:
选择 attach_index 命名的列表元素。非列表值保持不变。索引必须为 None、-1 或 0。对于列表,索引选择:
  • 使用 "all",整个列表。
  • 使用整数,一个元素。负索引从末尾开始计数。
  • 使用一对 (i, j) 或三元组 (i, j, k),一个从 i 到 j 的切片,步长为 k。切片包含 i 并排除 j,如 Python 中所示。负索引从末尾开始计数。当 i > j 且两个索引都为负或都为非负时,默认步长为 -1。否则,为 1。
**异常:**当 i 和 j 都为负且 i < j 时,范围排除 i 并包含 j。此时步长始终为 1。因此 (-3, -1) 选择最后两个元素,而不是 Python 切片 [-3:-1]。参数
  • value (list[T] | T): 张量或大小的列表,或单个张量或大小。
返回
  • list[T] | T: 对于整数索引,一个元素;对于 "all" 或元组,一个列表;或者当 value 不是列表时,value 本身。
引发
  • ValueError: 当 value 不是列表且索引不是 None、-1 或 0 时。当整数索引为 len(value) 或更大时。
  • RuntimeError: 当 value 是列表且索引为 None 时。
get_variants
Python
1def get_variants() -> tuple[str, dict[str, Kwargs]]:
返回节点的默认变体名称和变体。具有变体的节点会覆盖此静态方法。诸如 Node(variant="n") 之类的调用会选择一个变体,而 "default" 会选择默认变体。变体元类随后将变体的参数传递给构造函数。调用显式给出的参数会替换同名的变体参数。字典中不存在的变体名称会使元类引发 ValueError。返回
  • tuple[str, dict[str, Kwargs]]: 默认变体的名称,以及一个将每个变体名称映射到其构造函数关键字参数的字典。
引发
  • NotImplementedError: 当节点没有变体时。基本实现总是引发它。
get_weights_url
Python
1def get_weights_url(self) -> str:
返回节点预训练权重的 URL。具有预训练权重的节点会覆盖此方法。基本实现会引发 NotImplementedError,这意味着该节点没有预训练权重。load_checkpoint 在没有检查点时调用该方法,例如 weights="download"。URL 可以包含以下占位符:
  • {github} 变为 https://github.com/luxonis/luxonis-train/releases/download/v0.3.10-beta/。版本是固定的。已安装的版本不会更改它。
  • {github:v0.3.0} 选择版本 v0.3.0。版本需要三个数字,并且可以有后缀,如 v0.3.0-beta。
  • {variant} 变为构建节点的变体名称。节点必须来自变体。
URL 处的文件必须在 "state_dict" 键下保存节点的状态字典。该字典的键必须是节点的参数和缓冲区名称。返回
  • str: 检查点的 URL。它可以包含占位符。
引发
  • NotImplementedError: 当节点没有预训练权重时。
initialize_weights
Python
1def initialize_weights(method: Literal['yolo', 'none'] | str | None = None):
初始化节点的权重。节点在构造后调用它,将 weights 参数作为 method,除非 weights 请求检查点。子类覆盖它以初始化其自己的层。基本实现知道一种方法,即 "yolo"。它将每个 torch.nn.BatchNorm2d 中的 eps 设置为 0.001,将 momentum 设置为 0.03。它还将每个 Hardswish、LeakyReLU、ReLU、ReLU6 和 SiLU 激活中的 inplace 设置为 True。其他值不改变任何内容。参数
  • method (Literal['yolo', 'none'] | str | None): 初始化方法的名称。None 和 "none" 不改变任何内容。
load_checkpoint
Python
1def load_checkpoint(ckpt: str | dict[str, Tensor] | None = None, *, strict: bool = True):
将检查点加载到节点中。对于文件,该方法会记录路径或 URL。safe_download 首先将远程文件复制到本地缓存中。当下载失败时,该方法会记录警告并保持权重不变。该方法使用 torch.load 在 CPU 上读取文件,并使用 weights_only=False。仅加载受信任的文件,因为文件在加载时可以运行代码。加载后,该方法通过标准 logging 模块记录信息消息。参数
  • ckpt (str | dict[str, Tensor] | None): 状态字典,或 .ckpt 文件的本地路径或 URL。文件必须在 "state_dict" 键下保存状态字典。None 或 "" 从 get_weights_url 获取 URL。
  • strict (bool): 状态字典的键是否必须与节点的键完全匹配。该值传递给 torch.nn.Module.load_state_dict。当为 True 时,如果键不同,该方法会引发 RuntimeError。
引发
  • RuntimeError: 当 ckpt 是空字典时。
  • ValueError: 当 ckpt 为 None 且节点未覆盖 get_weights_url 时,或者当 URL 使用 {variant} 且没有变体构建节点时。
run
Python
1def run(inputs: list[Packet[Tensor]]) -> Packet[Tensor]:
在输入包上运行节点。该方法为每个 forward 参数赋值,调用节点,并将结果放入包中。参数的类型注释和名称决定其值:
  • list[Packet[Tensor]] 参数获取所有输入包。它必须是唯一的参数。
  • Packet[Tensor] 参数获取参数位置的输入包。
  • Tensor 或 list[Tensor] 参数可以具有名称 x、y 或 z,或以 input 开头的名称。然后它获取一个输入包的 "features" 条目。x、y 和 z 读取包 0、1 和 2。input 或 inputs 后面的数字,如 input_1,选择该包。其他名称读取包 0。列表条目通过 get_attached。
  • 具有其他名称的 Tensor 或 list[Tensor] 参数获取具有相同键的条目,不变。特殊情况:没有包具有该键,节点有一个输入包,并且 forward 有一个参数。然后参数通过 get_attached 获取该包的第一个条目,并且该方法记录警告。
forward 可以返回一个包、一个张量或一个张量列表。该方法将张量或列表放在 task.main_output 键下,或者当 task 为 None 时,放在 "features" 键下。参数
  • inputs (list[Packet[Tensor]]): 节点的每个输入一个包,按输入顺序排列。
返回
  • Packet[Tensor]: 节点的输出,例如 {"features": [feature_map_1, feature_map_2]}。
引发
  • TypeError: 当 forward 参数的注释不是上述四种类型之一时。当所需参数没有值时,对 forward 的调用也会引发它。
  • RuntimeError: 当 list[Packet[Tensor]] 参数不是唯一参数时,或者当输入包太少时。当读取 "features" 条目的参数获取没有该键的包时。当条目类型错误时,或者当两个包具有相同的键时。当 get_attached 获取列表且 attach_index 为 None 时。
  • ValueError: 当 forward 返回其他类型的值时。当 attach_index 不适合通过 get_attached 的条目时。
set_export_mode
Python
1def set_export_mode(/, mode: bool):
开启或关闭导出模式。该方法设置 export。然后它访问节点及其所有子模块。当为 True 时,它会在每个 Reparameterizable 模块上调用 reparameterize。当为 False 时,它会在每个模块上调用 restore。它会在调试级别记录每次调用。参数
  • mode (bool): True 开启导出模式,False 关闭导出模式。

属性

attach_index
节点读取的输入节点的输出。get_attached 应用它。该值是一个整数索引,一个用于范围的两个或三个整数的元组,或者 "all" 用于所有输出。-1 是最后一个输出。当子类将其保留为 None 时,构造函数会从 forward 推断它。一个带有一个注释为 Tensor 的参数的 forward 会给出 -1。一个带有一个注释为 list[Tensor] 的参数的 forward 会给出 "all"。对于任何其他带参数的 forward,构造函数会记录警告,并且索引保持 None。
class_names
节点任务的类名,按类索引排序。引发
  • RuntimeError: 当构造函数没有获取 dataset_metadata 时。
  • ValueError: 当数据集没有名为 task_name 的任务时。
classes
节点任务的类索引,以类名作为键。该值始终来自 dataset_metadata,用于 task_name。n_classes 构造函数参数不改变它。该值是一个新的 bidict。它的 inverse 将类索引映射到类名。引发
  • RuntimeError: 当构造函数没有获取 dataset_metadata 时。
  • ValueError: 当数据集没有名为 task_name 的任务时。
current_epoch
当前训练周期的编号,从 0 开始。LuxonisLightningModule 在每个训练周期开始时设置它。
dataset_metadata
数据集的元数据。引发
  • RuntimeError: 当构造函数没有获取 dataset_metadata 时。
export
导出模式是否开启。节点在 forward 中读取它以返回导出模型的输出。赋值调用 set_export_mode。
export_output_names
导出模型中节点输出的名称。基本实现返回 export_output_names 构造函数参数。None 保留默认名称。ONNX 导出仅在名称数量与节点输出数量匹配时使用这些名称。否则,它会记录警告并保留默认名称。头的 NN 存档将这些名称列为头输出。
in_channels
附加输入的通道数。它是 in_sizes 的倒数第三个维度,因此带或不带批次维度的形状会给出相同的值。大小列表会给出通道计数的列表。引发
  • RuntimeError: 当 in_sizes 找不到输入大小时。
  • ValueError: 当 attach_index 不适合大小时。
in_height
附加输入的高度。它是 in_sizes 的倒数第二个维度。大小列表会给出高度列表。引发
  • RuntimeError: 当 in_sizes 找不到输入大小时。
  • ValueError: 当 attach_index 不适合大小时。
in_sizes
附加输入的大小。该属性使用适用的第一个规则:
  1. in_sizes 构造函数参数,如果已设置。
  2. 唯一输入包的 "features" 条目。
  3. 该包的唯一条目。
  4. 该包中键与 forward 参数名称匹配的条目。它们的大小必须相等,并且该属性使用第一个。
规则 2 到 4 通过 get_attached 传递条目。结果是整数 attach_index 的单个大小,以及 "all" 或范围的大小列表。具有多个输入或形状不符合规则的节点必须改为读取 input_shapes。引发
  • RuntimeError: 当 input_shapes 缺失或不包含恰好一个包时。当没有键匹配 forward 参数时,或者当匹配的大小不同时。当 attach_index 为 None 且条目为列表时。
  • ValueError: 当 attach_index 不适合大小时。
in_width
附加输入的宽度。它是 in_sizes 的最后一个维度。大小列表会给出宽度列表。引发
  • RuntimeError: 当 in_sizes 找不到输入大小时。
  • ValueError: 当 attach_index 不适合大小时。
input_shapes
节点输入的形状包,每个输入一个。模型从零张量运行中获取形状,批次大小为 2,因此形状包含批次维度。引发
  • RuntimeError: 当构造函数没有获取 input_shapes 时。
n_classes
节点任务的类数。n_classes 构造函数参数优先。如果没有它,该值来自 dataset_metadata,用于 task_name。引发
  • RuntimeError: 当构造函数既没有获取 n_classes 也没有获取 dataset_metadata 时。
  • ValueError: 当数据集没有名为 task_name 的任务时。
n_keypoints
节点任务的关键点数量。n_keypoints 构造函数参数优先。如果没有它,该值来自 dataset_metadata,用于 task_name。当数据集没有该任务的关键点时,它为 0。引发
  • RuntimeError: 当构造函数既没有获取 n_keypoints 也没有获取 dataset_metadata 时。
name
节点的类名。它不是配置中节点的别名。
original_in_shape
模型输入图像的形状,[C, H, W]。形状不包含批次维度。引发
  • RuntimeError: 当构造函数没有获取 original_in_shape 时。
remove_on_export
模型在导出模式下是否跳过该节点。导出的模型不包含该节点。
T
Tensor 或 Size。
task
节点的任务。头设置它。当 forward 返回张量或张量列表时,run 将结果放在 task.main_output 键下。当任务为 None 时,键为 "features"。
task_name
节点的数据集任务。当构造函数没有获取 task_name 时,它为 ""。
variant
构建节点的变体名称。当调用选择覆盖 get_variants 的节点的变体时,变体元类会设置它。"default" 变体解析为默认变体的名称。引发
  • AttributeError: 当没有变体构建节点时。这发生在 variant 为 "none" 或 None 时,以及在没有变体的节点上为 "default" 时。因此 hasattr(node, "variant") 返回 False。