# embedding_losses

Python API: `luxonis_train.attached_modules.losses.embedding_losses`

`pytorch-metric-learning` 损失，已注册。

该模块为 `EMBEDDING_LOSSES` 中的每个名称创建一个
[EmbeddingLossWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/embedding_losses.md)
类。每个类都在
[LOSSES](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/registry.md)
注册表中以其损失的名称注册，因此配置直接命名损失，例如 `TripletMarginLoss`。每个类都接受一个 miner、一个距离、一个 reducer 和一个 regularizer。

## 类

### EmbeddingLossWrapper

`pytorch-metric-learning` 嵌入损失的包装器。

 * `输入:`: * `predictions` (`Tensor`): [B, D] 嵌入
    * `target` (`Tensor`): [B] 来自 `metadata/id` 的身份标签
 * `输出:`: * `Tensor`: 带有默认 reducer 的标量
 * `公式:`: 包装器返回注册名称的 `pytorch-metric-learning` 损失值。使用 miner 时，包装器还会将 miner 在批次中选择的对或三元组提供给损失。每个损失都以自己的方式使用它们。当节点设置
   `cross_batch_memory_size` 时，`CrossBatchMemory` 包装器还会将批次与最后 `cross_batch_memory_size` 个嵌入的内存进行比较。

> **参考**
> * 来源: 包装 [pytorch-metric-learning](https://github.com/KevinMusgrave/pytorch-metric-learning) (MIT)。
 * 许可证: Apache-2.0 (本项目)

> **注意**
> 该模块为 `EMBEDDING_LOSSES` 中的每个名称创建一个类。所有类都名为 `EmbeddingLossWrapper`，并且每个类都以其损失的名称注册。[name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/embedding_losses.md) 属性返回该损失名称。`CrossBatchMemory` 仅支持部分损失。对于其他损失，包装器会记录警告并忽略 `cross_batch_memory_size`。

> **示例**
> 附加到 `model.nodes` 中的 `GhostFaceNetHead`:

```yaml
- name: GhostFaceNetHead
  inputs: [GhostFaceNet]
  losses:
    - name: AngularLoss
```

 * `兼容:`: * 节点:
   [GhostFaceNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md)
    * 注册为: * `AngularLoss`
       * `CircleLoss`
       * `ContrastiveLoss`
       * `DynamicSoftMarginLoss`
       * `FastAPLoss`
       * `GeneralizedLiftedStructureLoss`
       * `HistogramLoss`
       * `InstanceLoss`
       * `IntraPairVarianceLoss`
       * `LiftedStructureLoss`
       * `MarginLoss`
       * `MultiSimilarityLoss`
       * `NCALoss`
       * `NPairsLoss`
       * `NTXentLoss`
       * `PNPLoss`
       * `RankedListLoss`
       * `SignalToNoiseRatioContrastiveLoss`
       * `SupConLoss`
       * `ThresholdConsistentMarginLoss`
       * `TripletMarginLoss`
       * `TupletMarginLoss`

#### 方法

##### init

```python
def __init__(*, miner: str | None = None, miner_params: Params | None = None, distance: str | None = None, distance_params: Params | None = None, reducer: str | None = None, reducer_params: Params | None = None, regularizer: str | None = None, regularizer_params: Params | None = None, node: BaseNode | None = None, final_loss_weight: float = 1.0, _loss_name: str = _loss_name, **kwargs):
```

创建包装的损失及其可选组件。

该方法在匹配的 `pytorch-metric-learning` 模块中查找每个命名组件。它使用其 `*_params` 参数的关键字参数创建组件。包装的损失接收 reducer 作为 `reducer`，regularizer 作为
`embedding_regularizer`，距离作为 `distance`，以及 `**kwargs`。

当节点设置 `cross_batch_memory_size` 并且 `CrossBatchMemory` 支持该损失时，该方法将损失包装在 `CrossBatchMemory` 中。包装器获取节点的 `embedding_size` 和
`cross_batch_memory_size`，以及 miner。对于 `CrossBatchMemory` 不支持的损失，该方法会记录警告。损失需要一个节点：如果没有
`node`，[BaseAttachedModule.node](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
会引发 `RuntimeError`。

参数

 * `miner` (`str | None`): `pytorch_metric_learning.miners` 中类的名称，例如 `"MultiSimilarityMiner"`。`None` 表示不使用 miner。
 * `miner_params` (`Params | None`): miner 的关键字参数。`None` 表示不传递参数。
 * `distance` (`str | None`): `pytorch_metric_learning.distances` 中类的名称，例如 `"CosineSimilarity"`。`None` 表示保留损失的默认距离。
 * `distance_params` (`Params | None`): 距离的关键字参数。`None` 表示不传递参数。
 * `reducer` (`str | None`): `pytorch_metric_learning.reducers` 中类的名称。`None` 表示保留损失的默认 reducer。
 * `reducer_params` (`Params | None`): reducer 的关键字参数。`None` 表示不传递参数。
 * `regularizer` (`str | None`): `pytorch_metric_learning.regularizers` 中类的名称，损失将其应用于嵌入。`None` 表示不使用 regularizer。
 * `regularizer_params` (`Params | None`): regularizer 的关键字参数。`None` 表示不传递参数。
 * `node` (`BaseNode | None`): 损失附加到的
   [GhostFaceNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md)。
 * `final_loss_weight` (`float`):
   [BaseLoss.run](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/base_loss.md)
   乘以损失的因子。
 * `_loss_name` (`str`): `pytorch-metric-learning` 损失类的名称。其默认值是此类的注册名称。
 * `**kwargs`: 损失类的关键字参数，例如 `TripletMarginLoss` 的 `margin`。

引发

 * `ValueError`: 当 `pytorch-metric-learning` 没有具有给定名称的损失、miner、距离、reducer 或 regularizer 时。

##### forward

```python
def forward(predictions: Tensor, target: Tensor) -> Tensor:
```

计算一批嵌入的包装损失。

使用 miner 时，该方法首先挖掘批次。它将挖掘的索引作为第三个参数传递给包装的损失。没有 miner 时，包装的损失只接收嵌入和标签。`CrossBatchMemory` 包装器还会将批次添加到其内存中。

> **示例**
> 该示例从 [LOSSES](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/registry.md) 注册表中获取 `TripletMarginLoss` 类。在 `grouped` 中，每个身份的两个嵌入相等，因此损失为 `0`。在 `mixed` 中，每个身份有两个不同的嵌入，因此损失为正：

```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import GhostFaceNetHead
>>> from luxonis_train.registry import LOSSES
>>> head = GhostFaceNetHead(
...     embedding_size=2,
...     input_shapes=[{"features": [Size([1, 8, 1, 1])]}],
...     original_in_shape=Size([3, 32, 32]),
... )
>>> loss = LOSSES.get("TripletMarginLoss")(node=head)
>>> target = torch.tensor([0, 0, 1, 1])
>>> grouped = torch.eye(2).repeat_interleave(2, dim=0)
>>> loss(grouped, target).item()
0.0
>>> mixed = torch.eye(2).repeat(2, 1)
>>> round(loss(mixed, target).item(), 4)
0.7571
```

参数

 * `predictions` (`Tensor`): 形状为 `[B, D]` 的嵌入，是节点的主要输出。
 * `target` (`Tensor`): 形状为 `[B]` 的身份标签，来自 `metadata/id` 标签。

返回

 * `Tensor`: 包装损失的值，带有默认 reducer 的标量。

#### 属性

##### loss

##### miner

##### name

包装的 `pytorch-metric-learning` 损失的名称。

该值是 `_loss_name` 参数，例如
`"TripletMarginLoss"`。默认情况下，它是类的注册名称。[BaseAttachedModule.name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
返回类名，对于每个嵌入损失都是
`EmbeddingLossWrapper`。此覆盖返回包装损失的名称。[BaseAttachedModule.get_parameters](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
的错误消息使用它。

##### node

##### supported_tasks

## 属性

### EMBEDDING_LOSSES
