# torchmetrics

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

封装 `torchmetrics` 分类指标的指标。

[TorchMetricWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
在配置未设置 `task` 和类别数时，会从指标所附加的节点推断它们。其他参数（例如 `average`）会传递给 `torchmetrics` 指标。

## 类

### Accuracy

封装 `torchmetrics.Accuracy` 的准确率指标。

 * `输入:`: * `predictions` (`Tensor`): `[B, n_classes, ...]` logits 或概率
    * `target` (`Tensor`): `[B, n_classes, ...]` one-hot 或 multi-hot 标签
 * `输出:`: * `Tensor`: 标量
    * `tuple[Tensor, dict[str, Tensor]]`: 平均值和每个类别的值，当构建的指标为每个类别返回一个值时，例如 `average: "none"`
 * `公式:`: 对于 `"binary"`，使用真阳性、真阴性、假阳性和假阴性的计数： 准确率 = (TP + TN)/(TP + TN + FP + FN) 对于 `"multiclass"` 和
   `"multilabel"`，`torchmetrics.Accuracy` 计算每个类别的统计数据，并根据其 `average` 参数选择组合类别。

> **参考**
> * 来源: 封装 [torchmetrics](https://github.com/Lightning-AI/torchmetrics) (Apache-2.0)。
 * 许可证: Apache-2.0 (本项目)

> **注意**
> [TorchMetricWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 解析 `task` 和类别数。其他 `params` 传递给 `torchmetrics.Accuracy`，例如 `average`、`threshold` 或 `top_k`。

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

```yaml
- name: ClassificationHead
  inputs: [ResNet]
  metrics:
    - name: Accuracy
```

 * `兼容:`: * 使用者:
   [ClassificationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/classification/v1/model.md)
    * 节点: *
      [BiSeNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [ClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/classification_head.md)
       * [DDRNetSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_head.md)
       * [SegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_classification_head.md)
       * [TransformerSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### 属性

##### supported_tasks

### F1Score

封装 `torchmetrics.F1Score` 的 F1 分数指标。

 * `输入:`: * `predictions` (`Tensor`): `[B, n_classes, ...]` logits 或概率
    * `target` (`Tensor`): `[B, n_classes, ...]` one-hot 或 multi-hot 标签
 * `输出:`: * `Tensor`: 标量
    * `tuple[Tensor, dict[str, Tensor]]`: 平均值和每个类别的值，当构建的指标为每个类别返回一个值时，例如 `average: "none"`
 * `公式:`: 使用真阳性、假阳性和假阴性的计数： F1 = (2 TP)/(2 TP + FP + FN) 对于 `"multiclass"` 和 `"multilabel"`，`torchmetrics.F1Score`
   计算每个类别的统计数据，并根据其 `average` 参数选择组合类别。

> **参考**
> * 来源: 封装 [torchmetrics](https://github.com/Lightning-AI/torchmetrics) (Apache-2.0)。
 * 许可证: Apache-2.0 (本项目)

> **注意**
> [TorchMetricWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 解析 `task` 和类别数。其他 `params` 传递给 `torchmetrics.F1Score`，例如 `average`、`threshold` 或 `top_k`。

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

```yaml
- name: ClassificationHead
  inputs: [ResNet]
  metrics:
    - name: F1Score
```

 * `兼容:`: * 使用者: *
   [ClassificationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/classification/v1/model.md)
       * [SegmentationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/segmentation/v1/model.md)
    * 节点: *
      [BiSeNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [ClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/classification_head.md)
       * [DDRNetSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_head.md)
       * [SegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_classification_head.md)
       * [TransformerSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### 属性

##### supported_tasks

### JaccardIndex

封装 `torchmetrics.JaccardIndex` 的 Jaccard 指数指标。

 * `输入:`: * `predictions` (`Tensor`): `[B, n_classes, ...]` logits 或概率
    * `target` (`Tensor`): `[B, n_classes, ...]` one-hot 或 multi-hot 标签
 * `输出:`: * `Tensor`: 标量
    * `tuple[Tensor, dict[str, Tensor]]`: 平均值和每个类别的值，当构建的指标为每个类别返回一个值时，例如 `average: "none"`
 * `公式:`: 使用真阳性、假阳性和假阴性的计数： J = (TP)/(TP + FP + FN) 对于 `"multiclass"` 和 `"multilabel"`，`torchmetrics.JaccardIndex`
   计算每个类别的统计数据，并根据其 `average` 参数选择组合类别。

> **参考**
> * 来源: 封装 [torchmetrics](https://github.com/Lightning-AI/torchmetrics) (Apache-2.0)。
 * 许可证: Apache-2.0 (本项目)

> **注意**
> [TorchMetricWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 解析 `task` 和类别数。其他 `params` 传递给 `torchmetrics.JaccardIndex`，例如 `average`、`threshold` 或 `ignore_index`。

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

```yaml
- name: ClassificationHead
  inputs: [ResNet]
  metrics:
    - name: JaccardIndex
```

 * `兼容:`: * 使用者: *
   [AnomalyDetectionModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/anomaly_detection/v1/model.md)
       * [SegmentationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/segmentation/v1/model.md)
    * 节点: *
      [BiSeNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [ClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/classification_head.md)
       * [DDRNetSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_head.md)
       * [SegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_classification_head.md)
       * [TransformerSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### 属性

##### supported_tasks

### Precision

封装 `torchmetrics.Precision` 的精确率指标。

 * `输入:`: * `predictions` (`Tensor`): `[B, n_classes, ...]` logits 或概率
    * `target` (`Tensor`): `[B, n_classes, ...]` one-hot 或 multi-hot 标签
 * `输出:`: * `Tensor`: 标量
    * `tuple[Tensor, dict[str, Tensor]]`: 平均值和每个类别的值，当构建的指标为每个类别返回一个值时，例如 `average: "none"`
 * `公式:`: 使用真阳性和假阳性的计数： 精确率 = (TP)/(TP + FP) 对于 `"multiclass"` 和 `"multilabel"`，`torchmetrics.Precision` 计算每个类别的统计数据，并根据其
   `average` 参数选择组合类别。

> **参考**
> * 来源: 封装 [torchmetrics](https://github.com/Lightning-AI/torchmetrics) (Apache-2.0)。
 * 许可证: Apache-2.0 (本项目)

> **注意**
> [TorchMetricWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 解析 `task` 和类别数。其他 `params` 传递给 `torchmetrics.Precision`，例如 `average`、`threshold` 或 `top_k`。

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

```yaml
- name: ClassificationHead
  inputs: [ResNet]
  metrics:
    - name: Precision
```

 * `兼容:`: * 节点: *
   [BiSeNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [ClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/classification_head.md)
       * [DDRNetSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_head.md)
       * [SegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_classification_head.md)
       * [TransformerSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### 属性

##### supported_tasks

### Recall

封装 `torchmetrics.Recall` 的召回率指标。

 * `输入:`: * `predictions` (`Tensor`): `[B, n_classes, ...]` logits 或概率
    * `target` (`Tensor`): `[B, n_classes, ...]` one-hot 或 multi-hot 标签
 * `输出:`: * `Tensor`: 标量
    * `tuple[Tensor, dict[str, Tensor]]`: 平均值和每个类别的值，当构建的指标为每个类别返回一个值时，例如 `average: "none"`
 * `公式:`: 使用真阳性和假阴性的计数： 召回率 = (TP)/(TP + FN) 对于 `"multiclass"` 和 `"multilabel"`，`torchmetrics.Recall` 计算每个类别的统计数据，并根据其 `average`
   参数选择组合类别。

> **参考**
> * 来源: 封装 [torchmetrics](https://github.com/Lightning-AI/torchmetrics) (Apache-2.0)。
 * 许可证: Apache-2.0 (本项目)

> **注意**
> [TorchMetricWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 解析 `task` 和类别数。其他 `params` 传递给 `torchmetrics.Recall`，例如 `average`、`threshold` 或 `top_k`。

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

```yaml
- name: ClassificationHead
  inputs: [ResNet]
  metrics:
    - name: Recall
```

 * `兼容:`: * 使用者:
   [ClassificationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/classification/v1/model.md)
    * 节点: *
      [BiSeNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [ClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/classification_head.md)
       * [DDRNetSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_head.md)
       * [SegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_classification_head.md)
       * [TransformerSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### 属性

##### supported_tasks

### TorchMetricWrapper

封装 `torchmetrics` 指标的指标的基类。

子类将类属性 `Metric` 设置为 `torchmetrics` 的任务包装器，例如
`torchmetrics.Accuracy`。[init](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
解析 `task` 和类别数，并将构建的指标存储在 `metric`
属性中。[update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)、[compute](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
和
[reset](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
调用构建的指标。此类别不设置 `Metric`，因此命名它的配置会因 `AttributeError` 而失败。请改为命名子类。

 * `输入:`: * `predictions` (`Tensor`): `[B, n_classes, ...]` logits 或概率
    * `target` (`Tensor`): `[B, n_classes, ...]` one-hot 或 multi-hot 标签
 * `输出:`: * `Tensor`: 标量
    * `tuple[Tensor, dict[str, Tensor]]`: 平均值和每个类别的值，当构建的指标为每个类别返回一个值时，例如 `average: "none"`

> **参考**
> * 来源: 封装 [torchmetrics](https://github.com/Lightning-AI/torchmetrics) (Apache-2.0)。
 * 许可证: Apache-2.0 (本项目)

> **注意**
> `task` 是 `"binary"`、`"multiclass"` 或 `"multilabel"`。当 `params` 未设置时，指标会推断它并记录警告。对于 `"multiclass"`，[update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 将 one-hot 目标转换为类别索引。在 `anomaly_detection` 节点上，指标读取 `segmentation` 标签。

> **示例**
> 一个子类，此处为 [Accuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)，附加到 `model.nodes` 中的 `DiscSubNetHead`：

```yaml
- name: DiscSubNetHead
  inputs: [RecSubNet]
  metrics:
    - name: Accuracy
```

 * `兼容:`: * 节点: *
   [BiSeNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [DDRNetSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_head.md)
       * [SegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### 方法

##### init

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

解析任务并构建封装的 `torchmetrics` 指标。

`task` 来自 `kwargs`。如果没有，该方法会从 `num_classes` 为 `1` 推断 `"binary"`，从另一个 `num_classes` 推断 `"multiclass"`，从 `num_labels` 推断
`"multilabel"`。如果没有这些参数，它会为具有一个类别的节点推断 `"binary"`，为其他节点推断 `"multiclass"`。当它推断任务时，它会记录警告。

类别数来自 `num_classes`，然后来自 `num_labels`，然后来自节点。该方法将其作为 `num_classes` 传递给 `Metric` 用于 `"multiclass"`，作为 `num_labels` 传递给 `Metric` 用于
`"multilabel"`。

> **示例**
> ```pycon
>>> metric = Accuracy(task="multilabel", num_labels=3)
>>> type(metric.metric).__name__
'MultilabelAccuracy'
```

参数

 * `**kwargs`: `node` 传递给 [BaseMetric](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)。其他参数和解析的 `task` 传递给 `Metric` 的构造函数，例如 `average` 或 `threshold`。

引发

 * `ValueError`: 当方法无法推断 `task`，或者 `task` 不是 `"binary"`、`"multiclass"` 或 `"multilabel"` 时。当类别数不符合任务时也会引发此错误：对于 `"multiclass"` 和 `"multilabel"`，类别数未知或为 `1`；对于 `"binary"`，类别数大于 `1`。

##### compute

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

计算封装指标的值。

该方法返回一个元素不变的结果。它将具有多个元素的结果视为每个类别一个值，例如 `average: "none"`。然后它返回这些值的平均值和类别值的字典。键是 `"<Metric>_<class name>"`，其中 `<Metric>` 是构建指标的类名，例如 `MulticlassAccuracy`。类名来自节点。如果没有节点，`classes` 属性会引发 `RuntimeError`。

> **示例**
> 两个预测中有一个正确：

```pycon
>>> import torch
>>> metric = Accuracy(task="multiclass", num_classes=3)
>>> predictions = torch.tensor([[2.0, 0.0, 0.0], [0.0, 2.0, 0.0]])
>>> target = torch.tensor([[1.0, 0.0, 0.0], [0.0, 0.0, 1.0]])
>>> metric.update(predictions, target)
>>> metric.compute().item()
0.5
```

返回

 * `Tensor | tuple[Tensor, dict[str, Tensor]]`: 标量值，或类别值的平均值和类别值的字典。

引发

 * `ValueError`: 当结果有多个元素且节点没有类名时。

##### reset

```python
def reset(self):
```

重置封装指标的状态。

该方法仅在 `metric` 属性上调用 `reset`。它不会在包装器上调用 `torchmetrics` 基类的 `reset`。因此，包装器会保留其上次 [compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 的缓存结果，并且 [compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 会返回该结果，直到下一次 [update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)。

##### update

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

向封装指标添加一个批次。

对于 `"multiclass"`，该方法将 `target` 转换为类别索引，通过对维度 `1` 进行 `argmax`。对于其他任务，它会原样传递 `target`。

参数

 * `predictions` (`Tensor`): 节点的主要输出，形状为 `[B, n_classes, ...]`。Logits 或概率。
 * `target` (`Tensor`): 任务的标签，形状为 `[B, n_classes, ...]`。对于 `"binary"` 是二值掩码，对于 `"multiclass"` 是 one-hot，对于 `"multilabel"` 是 multi-hot。

#### 属性

##### Metric

##### metric

##### required_labels

[update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 的 `target` 参数的标签。

[BaseAttachedModule.get_parameters](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md) 读取此集合以获取 [update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md) 的 `target` 参数，该参数没有标签后缀。在 `anomaly_detection` 节点上，该集合仅包含 `"segmentation"`，因此 `target` 接收异常掩码。在其他节点上，它包含任务的标签。当指标没有任务时，该属性会引发 `RuntimeError`。
