# model

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

嵌入学习模型。

## 类

### EmbeddingsModel

用于人脸识别或再识别的嵌入学习。

该模型将图像映射到向量。损失函数将同一身份的向量拉近，并将不同身份的向量推开。通过向量之间的距离比较两张图像，因此新身份无需重新训练。

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

```yaml
model:
  predefined_model:
    name: EmbeddingsModel
    params:
      variant: default
```

 * `组件：`： *
   节点：[GhostFaceNet](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ghostfacenet/ghostfacenet.md)
   ->
   [GhostFaceNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md)
    * 损失：`SupConLoss`
    * 指标： *
      [ClosestIsPositiveAccuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md)
       * [MedianDistances](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md)
    * 可视化工具：[EmbeddingsVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md)
    * 变体：`default`

#### 方法

##### init

```python
def __init__(embedding_size: int = 16, metadata_task_override: str = 'color', alias: str | None = None):
```

初始化模型。

参数

 * `embedding_size` (`int`)：头部生成的嵌入向量的长度。它以 `embedding_size` 的形式到达头部。
 * `metadata_task_override` (`str`)：数据集中保存每个样本身份的元数据字段。它重命名头部嵌入任务所需的 `id` 元数据标签。示例配置 `embeddings_model.yaml` 使用 `"color"`。
 * `alias` (`str | None`)：头部节点的别名。`None` 给出 `"<metadata_task_override>-embeddings"`。

##### get_variants

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

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

该模型有一个变体，`default`，没有参数。

> **示例**
> ```pycon
>>> EmbeddingsModel.get_variants()
('default', {'default': {}})
```

返回

 * `tuple[str, dict[str, Params]]`：`"default"` 和单个空变体。

#### 属性

##### nodes

[GhostFaceNet](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ghostfacenet/ghostfacenet.md) 主干和 [GhostFaceNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md)。

主干没有输入，因此它从加载器读取。头部从主干读取。两个节点都保留 `"default"` 变体。头部将 `alias` 和 `metadata_task_override` 作为节点字段，并将 `embedding_size` 放在其 `params` 中。其附加模块是：

 * `SupConLoss` 损失，带有 `MultiSimilarityMiner`、`CosineSimilarity` 距离、`ThresholdReducer`（`high` 为 `0.3`）和 `LpRegularizer`；
 * [ClosestIsPositiveAccuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md) 和 [MedianDistances](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md) 指标，两者均未标记为主指标；
 * [EmbeddingsVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md) 可视化工具。

当配置中没有指标是主指标时，[ModelConfig.check_main_metric](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md) 会标记配置的第一个指标。当配置列出的节点没有指标时，即 [ClosestIsPositiveAccuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md)。

> **示例**
> ```pycon
>>> model = EmbeddingsModel(embedding_size=32)
>>> head = model.nodes[-1]
>>> head.alias, head.metadata_task_override, head.params
('color-embeddings', 'color', {'embedding_size': 32})
```
