base_node
最后更新
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时,构造函数会跳过检查。属性的任何其他错误都会从构造函数中抛出。检查只读取具有注释的最近类的注释。因此,子类的注释会隐藏其父类的注释。
示例
一个从输入形状调整其层大小的节点。
register=False 使示例不包含在注册表中。Pycon
1>>> import torch
2>>> from torch import Size, Tensor, nn
3>>> from luxonis_train.nodes import BaseNode
4>>> class Conv(BaseNode, register=False):
5... def __init__(self, **kwargs):
6... super().__init__(**kwargs)
7... self.conv = nn.Conv2d(self.in_channels, 8, kernel_size=1)
8...
9... def forward(self, x: Tensor) -> Tensor:
10... return self.conv(x)
11>>> node = Conv(input_shapes=[{"features": [Size([2, 3, 32, 32])]}])
12>>> node.attach_index, node.in_channels
13(-1, 3)
14>>> packet = node.run([{"features": [torch.zeros(2, 3, 32, 32)]}])
15>>> packet["features"].shape
16torch.Size([2, 8, 32, 32])方法
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):forward
Python
1def forward(inputs: Tensor | list[Tensor] | Packet[Tensor] | list[Packet[Tensor]]) -> Tensor | list[Tensor] | Packet[Tensor]: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: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]。示例
Pycon
1>>> from torch import Tensor
2>>> from luxonis_train.nodes import BaseNode
3>>> class Node(BaseNode, register=False):
4... def forward(self, x: Tensor) -> Tensor:
5... return x
6>>> node = Node()
7>>> node.get_attached([1, 2, 3, 4, 5])
85
9>>> node.attach_index = (1, -1)
10>>> node.get_attached([1, 2, 3, 4, 5])
11[2, 3, 4]
12>>> node.attach_index = (-3, -1)
13>>> node.get_attached([1, 2, 3, 4, 5])
14[4, 5]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。示例
Pycon
1>>> from torch import Tensor
2>>> from luxonis_train.nodes import BaseNode
3>>> class Node(BaseNode, register=False):
4... def __init__(self, width: int = 1, **kwargs):
5... super().__init__(**kwargs)
6... self.width = width
7...
8... def forward(self, x: Tensor) -> Tensor:
9... return x
10...
11... @staticmethod
12... def get_variants():
13... return "n", {"n": {"width": 8}, "s": {"width": 16}}
14>>> node = Node(variant="default")
15>>> node.variant, node.width
16('n', 8)
17>>> Node(variant="s").width
1816
19>>> Node().width
201tuple[str, dict[str, Kwargs]]: 默认变体的名称,以及一个将每个变体名称映射到其构造函数关键字参数的字典。
NotImplementedError: 当节点没有变体时。基本实现总是引发它。
get_weights_url
Python
1def get_weights_url(self) -> str: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}变为构建节点的变体名称。节点必须来自变体。
"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。其他值不改变任何内容。示例
构造函数的
weights 参数选择方法。Pycon
1>>> from torch import Tensor, nn
2>>> from luxonis_train.nodes import BaseNode
3>>> class Node(BaseNode, register=False):
4... def __init__(self, **kwargs):
5... super().__init__(**kwargs)
6... self.bn = nn.BatchNorm2d(4)
7...
8... def forward(self, x: Tensor) -> Tensor:
9... return self.bn(x)
10>>> Node().bn.eps
111e-05
12>>> node = Node(weights="yolo")
13>>> node.bn.eps, node.bn.momentum
14(0.001, 0.03)method(Literal['yolo', 'none'] | str | None): 初始化方法的名称。None和"none"不改变任何内容。
load_checkpoint
Python
1def load_checkpoint(ckpt: str | dict[str, Tensor] | None = None, *, strict: bool = True):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" 键下。示例
Pycon
1>>> import torch
2>>> from torch import Tensor
3>>> from luxonis_train.nodes import BaseNode
4>>> class Add(BaseNode, register=False):
5... attach_index = -1
6...
7... def forward(self, x: Tensor, y: Tensor) -> Tensor:
8... return x + y
9>>> packets = [
10... {"features": [torch.ones(2)]},
11... {"features": [torch.ones(2)]},
12... ]
13>>> Add().run(packets)["features"].tolist()
14[2.0, 2.0]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):True 时,它会在每个 Reparameterizable 模块上调用 reparameterize。当为 False 时,它会在每个模块上调用 restore。它会在调试级别记录每次调用。参数mode(bool):True开启导出模式,False关闭导出模式。
属性
attach_index
"all" 用于所有输出。-1 是最后一个输出。当子类将其保留为 None 时,构造函数会从 forward 推断它。一个带有一个注释为 Tensor 的参数的 forward 会给出 -1。一个带有一个注释为 list[Tensor] 的参数的 forward 会给出 "all"。对于任何其他带参数的 forward,构造函数会记录警告,并且索引保持 None。class_names
RuntimeError: 当构造函数没有获取dataset_metadata时。ValueError: 当数据集没有名为 task_name 的任务时。
classes
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
RuntimeError: 当 in_sizes 找不到输入大小时。ValueError: 当 attach_index 不适合大小时。
in_height
RuntimeError: 当 in_sizes 找不到输入大小时。ValueError: 当 attach_index 不适合大小时。
in_sizes
in_sizes构造函数参数,如果已设置。- 唯一输入包的
"features"条目。 - 该包的唯一条目。
- 该包中键与
forward参数名称匹配的条目。它们的大小必须相等,并且该属性使用第一个。
"all" 或范围的大小列表。具有多个输入或形状不符合规则的节点必须改为读取 input_shapes。示例
Pycon
1>>> from torch import Size, Tensor
2>>> from luxonis_train.nodes import BaseNode
3>>> class Node(BaseNode, register=False):
4... def forward(self, x: list[Tensor]) -> list[Tensor]:
5... return x
6>>> shapes = [
7... {"features": [Size([2, 8, 64, 64]), Size([2, 16, 32, 32])]}
8... ]
9>>> node = Node(input_shapes=shapes)
10>>> node.attach_index
11'all'
12>>> node.in_sizes
13[torch.Size([2, 8, 64, 64]), torch.Size([2, 16, 32, 32])]
14>>> node.in_channels, node.in_height, node.in_width
15([8, 16], [64, 32], [64, 32])RuntimeError: 当input_shapes缺失或不包含恰好一个包时。当没有键匹配forward参数时,或者当匹配的大小不同时。当 attach_index 为None且条目为列表时。ValueError: 当 attach_index 不适合大小时。
in_width
RuntimeError: 当 in_sizes 找不到输入大小时。ValueError: 当 attach_index 不适合大小时。
input_shapes
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
"default" 变体解析为默认变体的名称。引发AttributeError: 当没有变体构建节点时。这发生在variant为"none"或None时,以及在没有变体的节点上为"default"时。因此hasattr(node, "variant")返回False。