# base_attached_module

Python API: `luxonis_train.attached_modules.base_attached_module`

所有损失、指标和可视化工具的基类。

[BaseAttachedModule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
检查模块是否适合任务及其节点的类型。[BaseAttachedModule.get_parameters](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
根据模块的参数名称，从节点的输出包和标签中选择模块的输入。

## 类

### BaseAttachedModule

所有附加到
[BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
的模块的基类。

[BaseLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/base_loss.md)、[BaseMetric](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
和
[BaseVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md)
都是它的子类。子类可以通过两种方式限制它接受的节点：

 * 设置类属性 `supported_tasks`。
 * 在类主体中注释 `node`，例如 `node: OCRCTCHead`。如果节点不是该类的实例，则构造函数会引发
   [IncompatibleError](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/exceptions.md)。检查只读取具有注释的最近类的注释。因此，子类的注释会隐藏其父类的
   `node` 注释。

读取节点的属性（例如
[n_classes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)）在模块没有节点时会引发
`RuntimeError`。

#### 方法

##### init

```python
def __init__(*, node: BaseNode | None = None, **kwargs):
```

初始化模块并选择其任务。

节点的任务成为模块的任务。如果没有节点，或者节点没有任务，则 `supported_tasks` 的唯一项成为任务。在其他情况下，模块没有任务，并且
[task](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
会引发 `RuntimeError`。

参数

 * `node` (`BaseNode | None`): 模块附加到的节点。训练器会传递它。`None` 会使读取节点的属性引发 `RuntimeError`。
 * `**kwargs`: 转发到下一个基类的关键字参数。对于指标，它是 `torchmetrics` `Metric`。对于损失或可视化工具，它是 `torch.nn.Module`，它会为任何关键字参数引发 `TypeError`。

引发

 * `IncompatibleError`: 当节点的任务不在 `supported_tasks` 中，或者当节点不是 `node` 注释中类的实例时。

##### get_parameters

```python
def get_parameters(predictions: Packet[Tensor], labels: Labels | None = None) -> dict[str, Tensor | list[Tensor] | None]:
```

从批次中选择模块的参数。

该方法读取
[BaseLoss.forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/base_loss.md)、[BaseMetric.update](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
或
[BaseVisualizer.forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md)
的参数，不包括 `self`、`kwargs` 和可视化工具的画布。它根据参数名称为每个参数选择一个值：

 * 以 `target` 开头的名称选择一个标签。第一个下划线之后的部分是标签，因此 `target_boundingbox` 选择 `<task_name>/boundingbox`。没有下划线的名称（例如 `target`）选择
   [required_labels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
   中的唯一标签。
 * 以 `pred` 开头的名称选择第一个下划线之后的包键。没有下划线的名称（例如 `predictions`）选择
   [task](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
   的 `main_output`。
 * 任何其他名称选择该名称的包键。

`<task_name>` 是
[node](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
的 `task_name`。该方法克隆每个选定的张量，以及选定列表的每个张量。当缺少值时，用 `| None` 注释的参数会得到 `None`。具有默认值的另一个参数不会得到条目，因此应用默认值。

> **示例**
> 缺失的可选值变为 `None`。选定的张量是副本：

```pycon
>>> import torch
>>> from torch import Tensor
>>> from luxonis_train.attached_modules.losses import BaseLoss
>>> class Loss(BaseLoss, register=False):
...     def forward(
...         self, features: Tensor, scale: Tensor | None = None
...     ) -> Tensor:
...         return features.sum()
>>> packet = {"features": torch.ones(2)}
>>> kwargs = Loss().get_parameters(packet)
>>> kwargs["scale"] is None
True
>>> kwargs["features"] is packet["features"]
False
```

参数

 * `predictions` (`Packet[Tensor]`): 节点的输出包。
 * `labels` (`Labels | None`): 批次的标签，键为 `<task_name>/<label>`。`None` 充当空字典。

返回

 * `dict[str, Tensor | list[Tensor] | None]`: 以参数名称为键的值，准备作为关键字参数传递。

引发

 * `RuntimeError`: 当没有默认值的参数没有值时。当 `target` 名称没有下划线且任务不需要正好一个标签时。当名称需要模块没有的节点或任务时。
 * `TypeError`: 当值与参数的注释不匹配时。

#### 属性

##### classes

节点任务的类索引，以类名称为键。

该值是
[BaseNode.classes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
的
[node](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)，一个新的
`bidict`。

引发

 * `RuntimeError`: 当模块没有节点，或者节点没有 `dataset_metadata` 时。
 * `ValueError`: 当数据集没有具有节点 `task_name` 的任务时。

##### current_epoch

当前训练周期的编号，从 `0` 开始。

该值来自
[node](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)。[LuxonisLightningModule](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
在每个训练周期开始时在节点上设置它。

引发

 * `RuntimeError`: 当模块没有节点时。

##### n_classes

节点任务的类数。

该值是
[BaseNode.n_classes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
的
[node](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)。

引发

 * `RuntimeError`: 当模块没有节点，或者节点既没有 `n_classes` 也没有 `dataset_metadata` 时。
 * `ValueError`: 当数据集没有具有节点 `task_name` 的任务时。

##### n_keypoints

节点任务的关键点数。

该值是
[BaseNode.n_keypoints](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
的
[node](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)。当数据集没有节点任务的关键点时，它为
`0`。

引发

 * `RuntimeError`: 当模块没有节点，或者节点既没有 `n_keypoints` 也没有 `dataset_metadata` 时。

##### name

模块的类名。

它不是配置中模块的别名。模块的错误消息使用它。

##### node

模块附加到的节点。

引发

 * `RuntimeError`: 当构造函数没有节点时。

##### original_in_shape

模型输入图像的形状，`[C, H, W]`。

该值是
[BaseNode.original_in_shape](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
的
[node](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)。该形状不包括批次维度。

引发

 * `RuntimeError`: 当模块没有节点，或者节点没有 `original_in_shape` 时。

##### required_labels

模块任务所需的标签。

基本实现返回
[Task.required_labels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/tasks.md)
的
[task](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)。没有下划线的
`target` 参数选择此集合中唯一的标签。

引发

 * `RuntimeError`: 当模块没有任务时。

##### supported_tasks

模块支持的任务。当节点的任务不在序列中时，构造函数会引发
[IncompatibleError](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/exceptions.md)。当模块没有从其节点获取任务且序列包含一个任务时，该任务将成为模块的任务。`None`
接受具有任何任务的节点。

##### task

模块的任务。

构造函数从节点或 `supported_tasks` 中选择它。

引发

 * `RuntimeError`: 当模块没有任务时。
