# embedding_metrics

Python API: `luxonis_train.attached_modules.metrics.embedding_metrics`

检查
[GhostFaceNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md)
嵌入空间的指标。

[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)
报告嵌入之间的中值欧几里得距离。当头部设置 `cross_batch_memory_size` 时，这两个指标还会对早期批次的嵌入进行评分。

## 类

### ClosestIsPositiveAccuracy

嵌入最近邻身份匹配的准确性。

 * `输入:`: * `predictions` (`Tensor`): [B, D] 嵌入
    * `target` (`Tensor`): [B] 身份标签
 * `输出:`: * `Tensor`: [0, 1] 范围内的标量准确性
 * `公式:`: 该指标计算每对嵌入之间的欧几里得距离。只有当至少一个其他嵌入具有相同标签时，嵌入才会被计数。准确性是最近的其他嵌入具有相同标签的计数嵌入数量，除以计数嵌入的总数。

> **参考**
> * 来源：从 [omoindrot.github.io/triplet-loss](https://omoindrot.github.io/triplet-loss) 的 TensorFlow 代码转换为 PyTorch。
 * 许可证：Apache-2.0（本项目）

> **注意**
> 当头部设置 `cross_batch_memory_size` 时，该指标会保留所有批次中最新的嵌入，直到达到该数量。在内存满之前，它不会进行评分。之后，它会在每个批次中再次对内存中的所有嵌入进行评分。当指标重置时，内存会清空。

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

```yaml
- name: GhostFaceNetHead
  inputs: [GhostFaceNet]
  metrics:
    - name: ClosestIsPositiveAccuracy
```

 * `兼容:`: *
   使用者：[EmbeddingsModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/embeddings/v1/model.md)
    * 节点：[GhostFaceNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md)

#### 方法

##### init

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

初始化指标并注册其指标状态。

该方法读取类及其基类的类型提示。它注册每个属性，其 `Annotated` 提示包含
[MetricState](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)，并使用
`torchmetrics` 的 `add_state`
方法。[MetricState](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
描述了状态的默认值和归约如何从标记中得出。

参数

 * `**kwargs`: 转发给
   [BaseAttachedModule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
   的关键字参数，例如 `node`。其余参数到达 `torchmetrics` `Metric`，它只接受自己的选项，例如 `sync_on_compute`，并对任何其他名称引发 `ValueError`。

引发

 * `ValueError`: 当指标状态没有 `default` 且其类型既不是 `Tensor` 也不是 `list[...]` 时。当指标状态的 `default` 是非空列表时也是如此。

##### compute

```python
def compute(self) -> Tensor:
```

返回具有正确匹配的计数嵌入的份额。

返回

 * `Tensor`: `correct / total`，一个从 `0` 到 `1` 的标量。自上次重置以来没有嵌入计数时，它为 `NaN`。

##### update

```python
def update(predictions: Tensor, target: Tensor):
```

将一个批次的最近邻匹配添加到计数中。

如果没有跨批次内存，该方法只对该批次进行评分。如果有，该方法将每个嵌入及其标签附加到内存中。然后它会删除超出内存大小的最旧条目。当内存中的条目少于内存大小时，该方法返回并不会进行评分。否则，它会对内存中的所有嵌入进行评分。

只有当另一个嵌入具有相同标签时，嵌入才会被计数。`correct` 会增加，增加的数量是最近的其他嵌入具有相同标签的计数嵌入。`total` 会增加，增加的数量是计数嵌入的总数。

参数

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

#### 属性

##### correct

##### cross_batch_memory

##### node

##### supported_tasks

##### total

### MedianDistances

嵌入之间的中值距离，用于诊断。

 * `输入:`: * `embeddings` (`Tensor`): [B, D]
    * `target` (`Tensor`): [B] 身份标签
 * `输出:`: * `MedianDistance`, `MedianClosestDistance`, `MedianClosestPositiveDistance`, `MedianClosestVsClosestPositiveDistance`
   (`Tensor`): 标量中值
 * `公式:`: 该指标计算每对嵌入之间的欧几里得距离。它收集所有批次中的四组距离并报告每个距离的中值： * `MedianDistance`: 每对无序嵌入。
    * `MedianClosestDistance`: 每个嵌入及其最近的其他嵌入。
    * `MedianClosestPositiveDistance`: 每个嵌入及其最近的具有相同标签的其他嵌入。
    * `MedianClosestVsClosestPositiveDistance`: 对于每个嵌入，最近的相同标签距离减去最近的距离。 当没有其他嵌入具有其标签时，最后两组会跳过一个嵌入。对于偶数个值，`torch.median`
      返回两个中间值中较小的一个。

> **参考**
> * 来源：从 [omoindrot.github.io/triplet-loss](https://omoindrot.github.io/triplet-loss) 的 TensorFlow 代码转换为 PyTorch。
 * 许可证：Apache-2.0（本项目）

> **注意**
> 头部的跨批次内存的工作方式与 [ClosestIsPositiveAccuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md) 相同。当指标没有对任何批次进行评分时，所有四个值都为 `NaN`。结果只包含子指标，因此该指标不能作为主要指标。

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

```yaml
- name: GhostFaceNetHead
  inputs: [GhostFaceNet]
  metrics:
    - name: MedianDistances
```

 * `兼容:`: *
   使用者：[EmbeddingsModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/embeddings/v1/model.md)
    * 节点：[GhostFaceNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md)

#### 方法

##### init

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

初始化指标并注册其指标状态。

该方法读取类及其基类的类型提示。它注册每个属性，其 `Annotated` 提示包含
[MetricState](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)，并使用
`torchmetrics` 的 `add_state`
方法。[MetricState](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
描述了状态的默认值和归约如何从标记中得出。

参数

 * `**kwargs`: 转发给
   [BaseAttachedModule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
   的关键字参数，例如 `node`。其余参数到达 `torchmetrics` `Metric`，它只接受自己的选项，例如 `sync_on_compute`，并对任何其他名称引发 `ValueError`。

引发

 * `ValueError`: 当指标状态没有 `default` 且其类型既不是 `Tensor` 也不是 `list[...]` 时。当指标状态的 `default` 是非空列表时也是如此。

##### compute

```python
def compute(self) -> dict[str, Tensor]:
```

返回每个距离列表的中值。

返回

 * `dict[str, Tensor]`: 键为 `"MedianDistance"`、`"MedianClosestDistance"`、`"MedianClosestPositiveDistance"` 和
   `"MedianClosestVsClosestPositiveDistance"` 的标量中值。当自上次重置以来
   [update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md)
   没有添加任何内容时，所有四个都为 `NaN`。只包含空张量的列表也会给出 `NaN`。

##### update

```python
def update(embeddings: Tensor, target: Tensor):
```

将一个批次的距离添加到四个距离列表中。

跨批次内存的工作方式与
[ClosestIsPositiveAccuracy.update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md)
相同。当内存未满时，该方法存储批次，不向列表中添加任何内容。

该方法将一个张量附加到每个列表：

 * `all_distances`: 每对无序的距离。
 * `closest_distances`: 每个嵌入的最近距离。
 * `positive_distances`: 每个具有相同标签的其他嵌入的最近相同标签距离。
 * `closest_vs_positive_distances`: 对于相同的嵌入，最近的相同标签距离减去最近的距离。

参数

 * `embeddings` (`Tensor`): 形状为 `[B, D]` 的嵌入，是节点的 `embeddings` 输出。
 * `target` (`Tensor`): 每个嵌入的 `metadata/id` 标签，形状为 `[B]`。

#### 属性

##### all_distances

##### closest_distances

##### closest_vs_positive_distances

##### cross_batch_memory

##### node

##### positive_distances

##### supported_tasks
