# base_predefined_model

Python API: `luxonis_train.config.predefined_models.base_predefined_model`

预定义模型的基础类。

[BasePredefinedModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md)
是每个预定义模型的基础。[SimplePredefinedModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md)
构建了通常的主干、颈部和头部链，因此具体模型只声明其组件和变体。[PredefinedModelMeta](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md)
在版本化名称下注册每个模型。

## 类

### BasePredefinedModel

预定义模型的基础类。

子类从
[nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md)
返回节点图，并在
[get_variants](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md)
中声明其变体。[luxonis_train.config.config.ModelConfig.validate_predefined_model](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md)
从配置的 `model.predefined_model` 部分构建模型，并将
[generate_nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md)
的结果附加到 `model.nodes`。当图不是简单的主干、颈部和头部链时，直接子类化此类别。否则，子类化
[SimplePredefinedModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md)。

[PredefinedModelMeta](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md)
在 `MODELS` 注册表中将每个具体子类注册为 `<name>:v<N>`。它还将家族的最高版本注册为 `<name>` 和 `<name>:latest`。

#### 方法

##### generate_nodes

```python
def generate_nodes(include_losses: bool = True, include_metrics: bool = True, include_visualizers: bool = True) -> list[NodeConfig]:
```

返回带有过滤后的附加模块的节点图。

[luxonis_train.config.config.ModelConfig.validate_predefined_model](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md)
使用 `predefined_model` 部分的 `include_*` 标志调用它。设置为 `False` 的标志会清空每个节点上匹配的列表。该方法会就地编辑
[nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md)
中的配置。

> **示例**
> ```pycon
>>> from luxonis_train.config.predefined_models import (
...     ClassificationModel,
... )
>>> model = ClassificationModel(variant="light")
>>> head = model.generate_nodes(include_metrics=False)[-1]
>>> [loss.name for loss in head.losses]
['CrossEntropyLoss']
>>> head.metrics
[]
```

参数

 * `include_losses` (`bool`): 保留节点的损失。
 * `include_metrics` (`bool`): 保留节点的指标。
 * `include_visualizers` (`bool`): 保留节点的视觉化器。

返回

 * `list[NodeConfig]`: 来自 [nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md) 的配置，已过滤。

##### get_variants

```python
def get_variants() -> tuple[str, dict[str, Params]]:
```

获取默认变体名称和可用变体。

字典的键是变体名称。每个值都包含模型构造函数的关键字参数。[VariantMeta](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/variants.md) 将所选变体的参数传递给 `__init__`，`variant="default"` 选择默认变体。调用者也给出的参数会整体替换变体值，因此 [VariantMeta](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/variants.md) 不会合并字典值。

返回

 * `tuple[str, dict[str, Params]]`: 默认变体名称，以及带有其构造函数参数的变体。

#### 属性

##### nodes

模型图的节点配置。

每次访问时，实现都必须构建新的配置，因为 [generate_nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md) 会编辑它接收到的配置。每个配置都包含其节点的损失、指标和视觉化器。

### PredefinedModelMeta

元类，用于在版本化名称下注册预定义模型。

版本来自定义类的 `v<N>` 包。`predefined_models/detection/v2/` 中的 `DetectionModel` 类注册为 `DetectionModel:v2`，因此模型的每个版本都保留类名。此类包之外的类使用其 `_VERSION` 属性。元类还将最高版本注册在裸家族名称下和 `<family>:latest` 下。

### SimplePredefinedModel

具有主干、可选颈部和头部的预定义模型。

子类命名其组件和变体。此类将它们连接成一个链，并将损失、指标和视觉化器附加到头部。它还应用配置要求的冻结和微调。配置中 `model.predefined_model.params` 的键是 `__init__` 的关键字参数。`variant` 键不会到达 `__init__`。它选择变体。

#### 方法

##### init

```python
def __init__(*, backbone: str, backbone_variant: str | None = None, head: str, head_variant: str | None = None, neck: str | None =
None, neck_variant: str | None = None, loss: str, metrics: str | list[str] | None, main_metric: str | None = None, visualizer: str
| None = None, confusion_matrix_available: bool = False, backbone_params: Params | None = None, neck_params: Params | None = None,
use_neck: bool = True, head_params: Params | None = None, loss_params: Params | None = None, metrics_params: Params | None = None,
visualizer_params: Params | None = None, enable_confusion_matrix: bool = True, confusion_matrix_params: Params | None = None,
task_name: str | None = None, torchmetrics_task: Literal['binary', 'multiclass', 'multilabel'] | None = None, per_class_metrics:
bool | None = None, finetuning: dict[Literal['backbone', 'neck', 'head'], list[Params]] | None = None):
```

从其组件名称初始化模型。

所有参数都是仅限关键字的。`typechecked` 装饰器在运行时检查它们的类型。

> **注意**
> `backbone_params`、`neck_params` 或 `head_params` 中的 `freezing` 键包含该节点的 [FreezingConfig](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md)，可以是实例或其字段的字典。没有 `active` 的字典会冻结节点。[nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/base_predefined_model.md) 在构建配置时会删除该键。

参数

 * `backbone` (`str`): 注册主干节点的类名。
 * `backbone_variant` (`str | None`): 主干的变体。`None` 构建没有变体参数的主干。
 * `head` (`str`): 注册头部节点的类名。
 * `head_variant` (`str | None`): 头部的变体。`None` 构建没有变体参数的头部。
 * `neck` (`str | None`): 注册颈部节点的类名。`None` 将头部连接到主干。
 * `neck_variant` (`str | None`): 颈部的变体。`None` 构建没有变体参数的颈部。
 * `loss` (`str`): 注册损失的类名。模型以 `1.0` 的权重将其附加到头部。
 * `metrics` (`str | list[str] | None`): 附加到头部的注册指标的类名。字符串命名一个指标。`None` 不附加任何指标。
 * `main_metric` (`str | None`): 标记为主指标的指标。训练器在 `best_val_metric` 中保留此指标最高值的检查点。`None` 采用 `metrics` 中唯一的名称，或者当 `metrics` 为空时没有指标。不在 `metrics` 中的名称不标记任何指标。当配置中没有指标被标记时，[ModelConfig.check_main_metric](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md) 标记第一个。
 * `visualizer` (`str | None`): 附加到头部的注册视觉化器的类名。`None` 不附加任何视觉化器。
 * `confusion_matrix_available` (`bool`): 头部是否支持 [ConfusionMatrix](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/confusion_matrix.md) 指标。子类为其头部设置它。
 * `backbone_params` (`Params | None`): 主干的构造函数参数。`freezing` 键不会到达构造函数。参见注释。
 * `neck_params` (`Params | None`): 颈部的构造函数参数，具有相同的 `freezing` 键。
 * `use_neck` (`bool`): 构建颈部。即使设置了 `neck`，`False` 也会省略颈部，并且头部从主干读取。
 * `head_params` (`Params | None`): 头部的构造函数参数，具有相同的 `freezing` 键。
 * `loss_params` (`Params | None`): 损失的构造函数参数。
 * `metrics_params` (`Params | None`): `metrics` 中每个指标接收的构造函数参数。`enable_confusion_matrix` 添加的 `ConfusionMatrix` 指标不接收它们。
 * `visualizer_params` (`Params | None`): 视觉化器的构造函数参数。
 * `enable_confusion_matrix` (`bool`): 将 `ConfusionMatrix` 指标附加到头部，不带主指标标志。当 `confusion_matrix_available` 为 `False` 时，它没有效果。
 * `confusion_matrix_params` (`Params | None`): `ConfusionMatrix` 指标的构造函数参数。
 * `task_name` (`str | None`): 头部读取的数据集任务。它成为头部节点的 `task_name`。
 * `torchmetrics_task` (`Literal['binary', 'multiclass', 'multilabel'] | None`): `metrics` 中每个指标接收的 `torchmetrics_task` 键的值。`None` 不添加任何键。该键进入 `metrics_params`，因此非空的 `metrics_params` 字典会就地更改。此包中的任何指标都不读取该键。[TorchMetricWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 指标读取 `task` 并将 `torchmetrics_task` 传递给 `torchmetrics`，这会引发 `ValueError`。请改为在 `metrics_params` 中设置 `task`。
 * `per_class_metrics` (`bool | None`): `metrics` 中每个指标接收的 `per_class_metrics` 键的值。`None` 不添加任何键。当 [LuxonisLightningModule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md) 构建指标时，该键成为指标类声明的每个类参数。当类未声明时，模块会删除该键并记录警告。
 * `finetuning` (`dict[Literal['backbone', 'neck', 'head'], list[Params]] | None`): 每个组件的微调条目。每个字典都成为该节点的 [FinetuningConfig](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md)。

引发

 * `ValueError`: 当 `main_metric` 为 `None` 且 `metrics` 命名多个指标时。

#### 属性

##### nodes

主干、使用时的颈部和头部，作为配置。

主干没有输入，因此它从加载器读取。颈部从主干读取。头部从颈部读取，或者当 `use_neck` 为 `False` 或 `neck` 为 `None` 时从主干读取。每个配置都带有其节点的 `params`、`variant`、`freezing` 和 `finetuning`。头部还带有 `task_name`、权重为 `1.0` 的损失、指标、启用时的 `ConfusionMatrix` 指标和视觉化器。

该属性从节点的存储参数字典中弹出 `freezing` 键。因此，第二次访问会构建未冻结的节点。

> **示例**
> ```pycon
>>> from luxonis_train.config.predefined_models import (
...     DetectionModel,
... )
>>> model = DetectionModel(variant="light")
>>> [(node.name, node.inputs) for node in model.nodes]
[('EfficientRep', []),
 ('RepPANNeck', ['EfficientRep']),
 ('EfficientBBoxHead', ['RepPANNeck'])]
>>> [metric.name for metric in model.nodes[-1].metrics]
['MeanAveragePrecision', 'ConfusionMatrix']
>>> model = DetectionModel(variant="light", use_neck=False)
>>> [(node.name, node.inputs) for node in model.nodes]
[('EfficientRep', []), ('EfficientBBoxHead', ['EfficientRep'])]
```
