# base_metric

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

所有指标的基类和指标状态的标记。

[BaseMetric](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
将
[BaseAttachedModule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
与 `torchmetrics` 的 `Metric` 类结合。
[MetricState](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
标记
[BaseMetric](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
注册为指标状态的类属性。 `DistReduceFx` 是合并跨进程状态的归约类型，`MetricResult` 是
[BaseMetric.compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
结果的类型。

## 类

### BaseMetric

所有指标的基类。

指标是
[BaseAttachedModule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
和 `torchmetrics` 的 `Metric`。每个子类都会在
[METRICS](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/registry.md)
注册表中以其类名注册自己，除非其类语句传递 `register=False`。配置通过该字符串命名注册的指标。子类实现
[update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
和
[compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)。它使用
[MetricState](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
声明其状态，或者在其 `__init__` 中使用 `add_state`。
[MetricState](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
的示例展示了一个完整的子类。

[BaseAttachedModule.get_parameters](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
描述了
[run_update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
如何从预测和标签中填充
[update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
的参数。

训练器在每个验证和测试批次上调用
[run_update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)。在
epoch 结束时，它调用
[compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
并记录
[get_artifacts](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
的图像。然后它调用 `reset` 并记录
[get_loggable_values](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
选择的值。

只有当两个指标是同一个对象时，它们才相等，指标的哈希值是其 `id`。在 `torchmetrics` 中，`==` 构建一个新的组合指标，哈希值读取状态。

#### 方法

##### init

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

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

该方法读取类及其基类的类型提示。它使用 `torchmetrics` 的 `add_state` 方法注册每个 `Annotated` 提示包含
[MetricState](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
的属性。
[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 | tuple[Tensor, dict[str, Tensor]] | dict[str, Tensor]:
```

根据其状态计算指标的值。

返回

 * `Tensor | tuple[Tensor, dict[str, Tensor]] | dict[str, Tensor]`: 结果有三种形式。 * 主值作为 `Tensor`。
    * 主值和子指标字典的元组。
    * 仅子指标字典。训练器不会在指标名称下记录任何值，因此该指标不能作为主指标。

##### get_artifact_names

```python
def get_artifact_names(self) -> tuple[str, ...]:
```

返回
[get_artifacts](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
发出的稳定名称。

返回

 * `tuple[str, ...]`:
   [get_artifacts](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
   返回的字典的键。

##### get_artifacts

```python
def get_artifacts(values: MetricResult) -> dict[str, Tensor]:
```

从计算结果渲染图像。

参数

 * `values` (`MetricResult`):
   [compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
   的结果。

返回

 * `dict[str, Tensor]`: 形状为 `[C, H, W]` 的图像，键为
   [get_artifact_names](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
   返回的名称。

##### get_loggable_values

```python
def get_loggable_values(values: MetricResult) -> MetricResult:
```

选择计算结果中要记录的部分。

当
[compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
返回属于工件而非标量日志的数据时，覆盖此方法。

参数

 * `values` (`MetricResult`):
   [compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
   的结果。

返回

 * `MetricResult`: 要记录的值，采用
   [compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
   的一种形式。

##### get_predefined_model_params_aliases

```python
def get_predefined_model_params_aliases(task: Task | None = None) -> dict[str, str]:
```

返回预定义模型参数的构造函数名称。

预定义模型可以向其每个指标的 `params` 添加 `per_class_metrics`。当
[Nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
构建指标时，它会在返回的字典中查找键，并以找到的参数名称传递值。当字典中没有此类键时，[Nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
会丢弃该值并记录警告。它会丢弃 `None` 值而不进行查找。

此实现忽略 `task` 并返回类属性 `predefined_model_params_aliases`。该属性在
[BaseMetric](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
上为空，[MIoU](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_iou.md)
将 `per_class_metrics` 映射到 `per_class`。
[MeanAveragePrecision](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/mean_average_precision.md)
不是子类。它定义自己的方法，因为其映射取决于任务。

> **示例**
> ```pycon
>>> from luxonis_train.attached_modules.metrics import MIoU
>>> BaseMetric.get_predefined_model_params_aliases()
{}
>>> MIoU.get_predefined_model_params_aliases()
{'per_class_metrics': 'per_class'}
```

参数

 * `task` (`Task | None`): 指标附加到的节点的任务，如果节点没有任务，则为 `None`。

返回

 * `dict[str, str]`: 预定义模型参数名称，映射到构造函数的参数名称。

##### run_update

```python
def run_update(inputs: Packet[Tensor], labels: Labels):
```

解析 [update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md) 的输入并添加一个批次。

[BaseAttachedModule.get_parameters](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md) 记录了参数名称如何选择预测和标签。

参数

 * `inputs` (`Packet[Tensor]`): 节点的输出包。
 * `labels` (`Labels`): 批次的标签，键为 `<task_name>/<label>`。

##### update

```python
def update(*args: Tensor | list[Tensor]):
```

向指标状态添加一个批次。

参数

 * `*args` (`Tensor | list[Tensor]`): 批次的输入。实现会用命名参数替换它们。

#### 属性

##### predefined_model_params_aliases

### MetricState

标记成为指标状态的类属性。

将实例放入 [BaseMetric](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md) 子类的类属性的 `Annotated` 类型提示中。 [BaseMetric.init](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md) 在类及其基类中查找每个此类属性。它使用 `torchmetrics` 的 `add_state` 方法注册该属性，因此状态是指标实例的属性。 `Annotated` 的第一个参数是状态的类型。

`torchmetrics` 将状态视为缓冲区：`.to()` 移动它。 `reset` 为张量状态提供其默认值的副本，并清空列表状态。

> **示例**
> 具有两个张量状态的子类。 `register=False` 使该类不包含在 [METRICS](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/registry.md) 注册表中。

```pycon
>>> from typing import Annotated
>>> import torch
>>> from torch import Tensor
>>> class PositiveRate(BaseMetric, register=False):
...     positives: Annotated[Tensor, MetricState()]
...     total: Annotated[Tensor, MetricState(default=0)]
...
...     def update(self, predictions: Tensor) -> None:
...         self.positives += (predictions > 0).sum()
...         self.total += predictions.numel()
...
...     def compute(self) -> Tensor:
...         return self.positives / self.total
>>> metric = PositiveRate()
>>> metric.update(torch.tensor([1.0, -1.0, 2.0, 3.0]))
>>> metric.compute().item()
0.75
>>> metric.reset()
>>> metric.positives.item(), metric.total.item()
(0.0, 0)
```

#### 属性

##### default

初始化后和 `reset` 后的状态值。数字变为零维张量，因此 `0` 给出 `int64` 状态，`0.0` 给出 `float32` 状态。 `None` 为 `Tensor` 属性选择 `0.0`，为 `list[...]` 属性选择 `[]`。对于任何其他类型的属性，`None` 会使 [BaseMetric.init](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md) 引发 `ValueError`。列表默认值必须为空，否则 `add_state` 会引发 `ValueError`。 每个实例都会按原样接收张量或列表默认值，而不是副本。 类的所有实例然后共享一个状态对象。一个指标中的就地更改（例如 `+=` 或 `append`）也会更改其他指标。 `reset` 为一个指标提供一个新的张量，因此该指标不再共享张量状态。 `reset` 就地清空列表状态，因此列表保持共享并对所有指标清空。数字或 `None` 为每个实例提供自己的状态。

##### dist_reduce_fx

合并所有进程状态的归约。字符串选择 `torch.sum`、`torch.mean`、`torch.cat`、`torch.min` 或 `torch.max` 沿维度 `0`。可调用对象接收收集到的状态：沿新的第一个维度堆叠的张量状态，或包含所有进程项的一个列表。 `None` 保持收集到的状态不变。默认 `...` 为列表状态选择 `"cat"`，为张量状态选择 `"sum"`。

##### persistent

指标的 `state_dict` 是否包含状态。

## 属性

### DistReduceFx

### MetricResult
