# model

Python API: `luxonis_train.config.predefined_models.keypoint_detection.v1.model`

实例关键点检测模型。

## 类

### KeypointDetectionModel

实例关键点检测，它同时预测一个框及其关键点。

 * `吞吐量:`: 384x512 时的每秒帧数。 * `light`: RVC2 上 45，RVC4 上 137
    * `medium`: RVC2 上 24，RVC4 上 120
    * `heavy`: RVC2 上 7，RVC4 上 101

> **注意**
> 设置 `per_class_metrics` 以记录每个类的 `kpt_map`、`kpt_mar` 和 `kpt_f1`。

> **示例**
> 配置的 `model` 部分：

```yaml
model:
  predefined_model:
    name: KeypointDetectionModel
    params:
      variant: light
```

 * `组件:`: *
   节点：[EfficientRep](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientrep/efficientrep.md)
   ->
   [RepPANNeck](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/necks/reppan_neck/reppan_neck.md)
   ->
   [EfficientKeypointBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_keypoint_bbox_head.md)
    * 损失：[EfficientKeypointBBoxLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/efficient_keypoint_bbox_loss.md)
    * 指标： *
      [ConfusionMatrix](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/confusion_matrix.md)
       * [MeanAveragePrecision](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/mean_average_precision.md)
       * [ObjectKeypointSimilarity](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/object_keypoint_similarity.md)
    * 可视化工具：[KeypointVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md)
    * 主要指标：[MeanAveragePrecision](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/mean_average_precision.md)
    * 变体： * `light`
       * `medium`
       * `heavy`

#### 方法

##### init

```python
def __init__(**kwargs):
```

从组件名称初始化模型。

所有参数均为仅限关键字参数。`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`: 注册骨干节点的类名。
 * `backbone_variant`: 骨干的变体。`None` 构建没有变体参数的骨干。
 * `head`: 注册头节点的类名。
 * `head_variant`: 头的变体。`None` 构建没有变体参数的头。
 * `neck`: 注册颈节点的类名。`None` 将头连接到骨干。
 * `neck_variant`: 颈的变体。`None` 构建没有变体参数的颈。
 * `loss`: 注册损失的类名。模型以权重 `1.0` 将其附加到头。
 * `metrics`: 附加到头的注册指标的类名。字符串表示一个指标。`None` 不附加任何指标。
 * `main_metric`: 标记为主指标的指标。训练器将此指标最高值的检查点保留在 `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`: 附加到头的注册可视化工具的类名。`None` 不附加任何可视化工具。
 * `confusion_matrix_available`: 头是否支持
   [ConfusionMatrix](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/confusion_matrix.md)
   指标。子类为其头设置它。
 * `backbone_params`: 骨干的构造函数参数。`freezing` 键不会到达构造函数。请参阅注释。
 * `neck_params`: 颈的构造函数参数，具有相同的 `freezing` 键。
 * `use_neck`: 构建颈。即使设置了 `neck`，`False` 也会将颈排除在外，并且头从骨干读取。
 * `head_params`: 头的构造函数参数，具有相同的 `freezing` 键。
 * `loss_params`: 损失的构造函数参数。
 * `metrics_params`: `metrics` 中每个指标接收的构造函数参数。`enable_confusion_matrix` 添加的 `ConfusionMatrix` 指标不接收它们。
 * `visualizer_params`: 可视化工具的构造函数参数。
 * `enable_confusion_matrix`: 将 `ConfusionMatrix` 指标附加到头，不带主指标标志。当 `confusion_matrix_available` 为 `False` 时，它不起作用。
 * `confusion_matrix_params`: `ConfusionMatrix` 指标的构造函数参数。
 * `task_name`: 头读取的数据集任务。它成为头节点的 `task_name`。
 * `torchmetrics_task`: `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`: `metrics` 中每个指标接收的 `per_class_metrics` 键的值。`None` 不添加任何键。当
   [LuxonisLightningModule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
   构建指标时，该键成为指标类声明的每个类参数。当类未声明时，模块会删除该键并记录警告。
 * `finetuning`: 每个组件的微调条目。每个字典都成为该节点的
   [FinetuningConfig](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md)。
 * `**kwargs`

引发

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

##### get_variants

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

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

默认值为 `light`。每个变体将 `backbone_variant` 和 `neck_variant` 设置为一种大小：

 * `light`: `"n"`
 * `medium`: `"s"`
 * `heavy`: `"l"`

每个变体还将 `backbone_params` 和 `neck_params` 中的 `weights` 设置为 `"download"`。然后，这两个节点会下载并加载其变体的 COCO 检查点。变体不设置
`head_params`，因此头在没有检查点的情况下启动。配置中给出的 `backbone_params` 或 `neck_params` 会替换变体的整个字典。再次设置其中的 `weights` 以保留 COCO 检查点。

> **示例**
> ```pycon
>>> default, variants = KeypointDetectionModel.get_variants()
>>> default
'light'
>>> variants["medium"]["backbone_variant"]
's'
```

返回

 * `tuple[str, dict[str, Params]]`: `"light"` 和三个变体及其构造函数参数。
