# model

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

The embedding learning model.

## Classes

### EmbeddingsModel

Embedding learning for face recognition or re-identification.

The model maps an image to a vector. The loss pulls the vectors of one identity together and pushes the vectors of different
identities apart. Compare two images by the distance between their vectors, so a new identity needs no retraining.

> **Example**
> The `model` section of a config:

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

 * `Components:`: * Nodes:
   [GhostFaceNet](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ghostfacenet/ghostfacenet.md)
   ->
   [GhostFaceNetHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md)
    * Losses: `SupConLoss`
    * Metrics: *
      [ClosestIsPositiveAccuracy](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md)
       * [MedianDistances](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md)
    * Visualizers:
      [EmbeddingsVisualizer](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md)
    * Variants: `default`

#### Methods

##### init

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

Initialize the model.

Parameters

 * `embedding_size` (`int`): The length of the embedding vector the head produces. It reaches the head as `embedding_size`.
 * `metadata_task_override` (`str`): The metadata field of the dataset that holds the identity of each sample. It renames the `id`
   metadata label that the embeddings task of the head requires. The example config `embeddings_model.yaml` uses `"color"`.
 * `alias` (`str | None`): The alias of the head node. `None` gives `"<metadata_task_override>-embeddings"`.

##### get_variants

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

Get the default variant name and the available variants.

The model has one variant, `default`, with no parameters.

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

Returns

 * `tuple[str, dict[str, Params]]`: `"default"` and the single empty variant.

#### Attributes

##### nodes

The [GhostFaceNet](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ghostfacenet/ghostfacenet.md) backbone and the [GhostFaceNetHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md).

The backbone has no inputs, so it reads from the loader. The head reads from the backbone. Both nodes keep the `"default"` variant. The head carries `alias` and `metadata_task_override` as node fields, and `embedding_size` in its `params`. Its attached modules are:

 * the `SupConLoss` loss with a `MultiSimilarityMiner`, a `CosineSimilarity` distance, a `ThresholdReducer` with `high` of `0.3`, and an `LpRegularizer`;
 * the [ClosestIsPositiveAccuracy](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md) and [MedianDistances](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md) metrics, neither marked as the main metric;
 * the [EmbeddingsVisualizer](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md) visualizer.

When no metric of the config is the main metric, [ModelConfig.check_main_metric](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md) marks the first metric of the config. When the nodes that the config lists have no metrics, that is [ClosestIsPositiveAccuracy](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md).

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