# utils

Python API: `luxonis_train.lightning.utils`

Lightning 模块背后的辅助函数。

[Nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
从配置构建节点图，并将每个节点包装在
[NodeWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
中，同时包含其损失、指标和可视化工具。[LossAccumulator](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
保持每个损失在一个 epoch 中的运行平均值。这些函数汇总损失，构建训练策略，展平指标结果，并将指标工件和可视化记录到跟踪器。

## 类

### LossAccumulator

一个 epoch 中每个损失值的运行平均值。

Lightning 模块为 `"train"`、`"val"` 和 `"test"` 阶段各保留一个累加器。它在每个步骤后调用
[update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)，并在
epoch 结束时调用
[clear](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)。从未收到
[update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
的键读取为 `0.0`。

> **示例**
> ```pycon
>>> import torch
>>> losses = LossAccumulator()
>>> losses.update({"loss": torch.tensor(2.0)})
>>> losses.update({"loss": torch.tensor(4.0)})
>>> losses["loss"]
3.0
>>> losses.clear()
>>> dict(losses)
{}
```

#### 方法

##### init

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

##### clear

```python
def clear(self):
```

删除所有存储的平均值和所有计数。

##### update

```python
def update(losses: dict[str, Tensor]):
```

将每个损失的一个值折叠到其运行平均值中。

这会替换 `dict.update`。一个值不会覆盖存储的值。它会移动平均值。

参数

 * `losses` (`dict[str, Tensor]`): 损失名称映射到单元素张量，如 [compute_losses](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md) 返回的第二个值。

### MainMetric

选择最佳检查点的指标。

#### 属性

##### metric_name

指标的标识符。类名包含 `"ConfusionMatrix"` 的指标将获得标识符 `"mcc"`。

##### node_name

持有指标的节点的标识符。当配置设置别名时，它是节点的别名，否则是类名。

### Nodes

模型的节点图，从配置构建。

一个 `torch.nn.ModuleDict`，将每个节点标识符映射到其 [NodeWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)。构造函数按拓扑顺序构建节点。它在零张量上运行每个节点，因此后续节点知道其输入的形状。

#### 方法

##### init

```python
def __init__(cfg: Config, dataset_metadata: DatasetMetadata, input_shapes: dict[str, Size]):
```

构建配置的每个节点并将其包装。

节点按拓扑顺序构建，并在零张量上运行一次，以推断后续节点消耗的形状。相同的过程构建每个节点的损失、指标和可视化工具。

参数

 * `cfg` (`Config`): 配置。`model.nodes` 列出节点，`loader.image_source` 命名图像输入，`trainer.epochs` 解析分数或缺失的 `freezing.unfreeze_after`。
 * `dataset_metadata` (`DatasetMetadata`): 数据集的元数据。它修复未设置任务名称的节点的任务名称，并验证元数据标签类型。它还会到达每个节点构造函数。
 * `input_shapes` (`dict[str, Size]`): 每个加载器输入名称映射到其形状，不带批处理维度。

引发

 * `RuntimeError`: 当节点未设置 `task_name` 且数据集不包含任务时。当节点列出没有节点生成的输入时，或者当图存在循环时。
 * `ValueError`: 当头未设置 `task_name` 且数据集包含多个任务时。当 `input_sources` 条目不是加载器输入时。当 `metadata_task_override` 是字符串但任务不需要恰好一个元数据标签时。当元数据标签的类型不被任务接受时。该检查从配置条目读取 `task_name`，因此仅在设置了任务名称的节点上运行。

##### build_callbacks

```python
def build_callbacks(save_dir: Path) -> list[pl.Callback]:
```

构建训练运行的 Lightning 回调。

列表按以下顺序排列：

 * [TrainingManager](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/training_manager.md)，它应用冻结计划并在每次反向传播后调用训练策略。
 * [LuxonisModelSummary](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_model_summary.md)，深度为 2，当 `rich_logging` 为 true 时作为富表格。
 * 一个 `ModelCheckpoint`，它监控 `val/loss`，保留最低值，并写入 `save_dir / "min_val_loss"`。
 * [AIMETCallback](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/aimet_callback.md)，当 `exporter.aimet.active` 设置时。
 * 一个 `ModelCheckpoint`，它监控主指标的 `val/metric/<node>/<metric>`，当配置定义一个时。`<node>` 是 [formatted_name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md) 中的日志名称。检查点保留最高值，并写入 `save_dir / "best_val_metric"`。
 * `trainer.callbacks` 的每个活动回调，从 [CALLBACKS](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/registry.md) 注册表构建。该函数记录并跳过不活动的。
 * 一个 `GradientAccumulationScheduler` 用于 `trainer.accumulate_grad_batches`，当配置设置该值且上述回调不包含此类调度器时。当它们包含时，该函数记录警告并忽略配置值。

两个检查点都保留 `trainer.save_top_k` 文件。

参数

 * `save_dir` (`Path`): 接收检查点子目录的目录。

返回

 * `list[pl.Callback]`: 回调，按上述顺序。

##### formatted_name

```python
def formatted_name(node_name: str) -> str:
```

返回节点的日志名称。

参数

 * `node_name` (`str`): 节点的标识符。

返回

 * `str`: 当节点有任务名称时为 `"<task_name>-<node_name>"`，否则仅为 `node_name`。

##### traverse

```python
def traverse(self) -> Iterator[tuple[str, NodeWrapper, list[str], list[str]]]:
```

按拓扑顺序遍历图。

遍历仅在每个馈送节点的节点之后才生成节点。

生成

 * 节点标识符、其包装器、馈送它的节点标识符以及尚未生成的节点标识符。

引发

 * `RuntimeError`: 当遍历没有进展时。此时节点列出了图中没有节点生成的输入，或者图存在循环。

#### 属性

##### freeze_schedule

具有 `freezing.active` 的节点的冻结计划。

##### graph

每个节点标识符映射到馈送它的节点标识符。

##### loader_input_shapes

每个节点标识符映射到节点读取的加载器输入，作为输入名称到形状，不带批处理维度。仅由其他节点馈送的节点映射到空字典。

##### main_metric

选择最佳检查点的指标，如果配置中没有则为 `None`。

##### main_metric_reference

`main_metric` 命名的指标实例。

引发

 * `RuntimeError`: 当配置未定义主指标时。

### NodeWrapper

具有其附加模块和计划的图节点。

[Nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md) 为配置中的每个节点创建一个包装器。包装器将每个构造函数参数存储在相同的名称下。`module` 是一个注册的子模块。损失、指标和可视化工具存储在普通字典中，因此 `torch.nn.Module` 的递归方法无法访问它们。

#### 方法

##### init

```python
def __init__(name: str, module: BaseNode, losses: dict[str, BaseLoss], metrics: dict[str, BaseMetric], visualizers: dict[str,
BaseVisualizer], unfreeze_after: int | None, lr_after_unfreeze: float | None, finetuning: list[FinetuningConfig], inputs:
list[str] | None = None):
```

初始化包装器。

参数

 * `name` (`str`): 图中节点的标识符。
 * `module` (`BaseNode`): 节点。
 * `losses` (`dict[str, BaseLoss]`): 附加到节点的损失，以其标识符为键。
 * `metrics` (`dict[str, BaseMetric]`): 附加到节点的指标，以其标识符为键。
 * `visualizers` (`dict[str, BaseVisualizer]`): 附加到节点的可视化工具，以其标识符为键。
 * `unfreeze_after` (`int | None`): 节点开始训练的 epoch。当节点未冻结时为 `None`。
 * `lr_after_unfreeze` (`float | None`): 从解冻 epoch 开始，节点的基学习率。`None` 保留调度器达到的速率。
 * `finetuning` (`list[FinetuningConfig]`): 节点的优化器和调度器覆盖。
 * `inputs` (`list[str] | None`): 馈送此节点的节点名称和加载器源。`None` 变为一个空列表。

##### train

```python
def train(mode: bool = True) -> NodeWrapper:
```

设置节点及其附加模块的训练模式。

`torch.nn.Module.train` 仅适用于注册的子模块，因此此覆盖也设置每个损失、指标和可视化工具的模式。

参数

 * `mode` (`bool`): `True` 表示训练模式，`False` 表示评估模式。

返回

 * `NodeWrapper`: 此包装器。

#### 属性

##### finetuning

##### formatted_name

日志和检查点名称中节点的名称。

当节点有任务名称时为 `"<task_name>-<name>"`，否则仅为 `name`。

##### inputs

##### losses

##### lr_after_unfreeze

##### metrics

##### module

##### name

##### task_name

包装节点的任务名称。

它来自节点配置中的 `task_name`，或者当数据集包含一个任务时来自数据集。否则为空字符串。

##### unfreeze_after

##### visualizers

## 函数

### build_training_strategy

```python
def build_training_strategy(cfg: Config, pl_module: pl.LightningModule) -> BaseTrainingStrategy | None:
```

构建配置命名的训练策略。

策略类来自 [STRATEGIES](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/registry.md) 注册表，`trainer.training_strategy.params` 访问其构造函数。策略通过 [BaseTrainingStrategy.get_base_configs](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/strategies/base_strategy.md) 提供基本优化器和调度器。因此，当 `trainer.optimizer` 或 `trainer.scheduler` 与其默认值不同时，该函数会记录警告。

没有具体 `rules` 方法的类早于基于规则的 API，并且已弃用。该函数记录警告。它构建一个未注册的子类，其中包含抽象 `rules` 和 `get_base_configs` 的存根，以便它可以实例化该类。然后它通过 [LegacyStrategyAdapter](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/strategies/legacy.md) 挂载实例。适配器不贡献任何规则。当旧版类未定义 `get_base_configs` 时，它会引发 `NotImplementedError`。然后训练计划会回退到配置的优化器和调度器。

参数

 * `cfg` (`Config`): 配置。`trainer.training_strategy` 命名策略并包含其参数。
 * `pl_module` (`pl.LightningModule`): 策略附加到的 Lightning 模块。

返回

 * `BaseTrainingStrategy | None`: 策略，如果配置中没有命名则为 `None`。

### check_tensor_device

```python
def check_tensor_device(x: Tensor | list[Tensor], device: torch.device) -> bool:
```

检查张量或列表中的每个张量是否在设备上。

> **示例**
> ```pycon
>>> import torch
>>> cpu = torch.device("cpu")
>>> check_tensor_device(torch.zeros(1), cpu)
True
>>> check_tensor_device([torch.zeros(1), 1.0], cpu)
False
```

参数

 * `x` (`Tensor | list[Tensor]`): 张量，或张量列表或元组。
 * `device` (`torch.device`): 要比较的设备。

返回

 * `bool`: 当张量在 `device` 上时为 `True`，或者当序列中的每个项都是 `device` 上的张量时为 `True`。空序列返回 `True`。

引发

 * `TypeError`: 当 `x` 既不是张量也不是列表或元组时。

### compute_losses

```python
def compute_losses(cfg: Config, losses: dict[str, dict[str, Tensor | tuple[Tensor, dict[str, Tensor]]]], device: torch.device) -> tuple[Tensor, dict[str, Tensor]]:
```

将每个节点的损失汇总为一个总和。

总和是一个简单的求和。[BaseLoss.run](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/base_loss.md)
已经将每个损失乘以其在配置中的 `weight`。子损失不带权重。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.config import Config
>>> bce = (torch.tensor(1.5), {"pos": torch.tensor(0.5)})
>>> total, logged = compute_losses(
...     Config(rich_logging=False),
...     {"head": {"bce": bce}},
...     torch.device("cpu"),
... )
>>> total.tolist()
[1.5]
>>> sorted(logged)
['loss', 'loss/head/bce', 'loss/head/bce/pos']
```

参数

 * `cfg` (`Config`): 配置。`trainer.log_sub_losses` 决定子损失是否到达日志字典。
 * `losses` (`dict[str, dict[str, Tensor | tuple[Tensor, dict[str, Tensor]]]]`): 一个步骤的损失。第一个键是节点标识符，第二个键是损失标识符。值是损失张量，或损失张量及其子损失的元组。
 * `device` (`torch.device`): 总和的设备。

返回

 * `tuple[Tensor, dict[str, Tensor]]`: 总和和用于日志记录的损失。总和是 `device` 上形状为 `[1]` 的张量，它保留其梯度图。字典包含每个损失的 `"loss/<node>/<loss>"`，当设置 `trainer.log_sub_losses` 时每个子损失的 `"loss/<node>/<loss>/<sub-loss>"`，以及总和的 `"loss"`。该函数分离每个记录的张量并将其移动到 CPU。

### compute_visualization_buffer

```python
def compute_visualization_buffer(seq_buffer: list[dict[str, dict[str, Tensor]]], visualizations: dict[str, dict[str, Tensor]],
logged_idxs: list[int], max_log_images: int) -> dict[str, dict[str, Tensor]] | None:
```

收集平衡日志器跳过的批次图像。

缓冲区是批次列表。其填充级别仅是第一个缓冲条目的批次维度，而不是所有条目的总和。当该级别达到 `max_log_images` 时，该函数不再收集任何内容。否则，该函数从每个可视化中获取索引不在 `logged_idxs` 中的样本，最多 `max_log_images` 减去填充级别。

> **示例**
> ```pycon
>>> import torch
>>> batch = {"head": {"boxes": torch.zeros(4, 3, 8, 8)}}
>>> extra = compute_visualization_buffer([], batch, [0, 2], 3)
>>> extra["head"]["boxes"].shape
torch.Size([2, 3, 8, 8])
>>> compute_visualization_buffer([extra], batch, [0, 2], 2) is None
True
```

参数

 * `seq_buffer` (`list[dict[str, dict[str, Tensor]]]`): 到目前为止已缓冲的批次。每个条目都具有 `visualizations` 的结构。
 * `visualizations` (`dict[str, dict[str, Tensor]]`): 节点标识符映射到可视化工具标识符，再映射到形状为 `[B, C, H, W]` 的图像批次。不能为空。
 * `logged_idxs` (`list[int]`): 平衡日志器已记录的批次索引。
 * `max_log_images` (`int`): 一个 epoch 中要记录的图像数量。

返回

 * `dict[str, dict[str, Tensor]] | None`: 跳过的样本，具有 `visualizations` 的结构。当第一个缓冲条目已满，或者平衡日志器已获取批次中的所有样本时为 `None`。

### get_main_metric

```python
def get_main_metric(cfg: Config) -> MainMetric | None:
```

查找配置中标记为 `is_main_metric` 的指标。

该函数按配置顺序扫描节点及其指标，第一个匹配项获胜。配置验证最多允许一个主指标，并在未设置时标记第一个指标。

> **示例**
> ```pycon
>>> from luxonis_train.config import Config
>>> node = {"name": "ResNet", "metrics": [{"name": "ConfusionMatrix"}]}
>>> cfg = Config(rich_logging=False, model={"nodes": [node]})
>>> get_main_metric(cfg)
MainMetric(node_name='ResNet', metric_name='mcc')
```

参数

 * `cfg` (`Config`): 配置。

返回

 * `MainMetric | None`: 节点标识符和指标标识符，或者当没有指标设置 `is_main_metric` 时为 `None`。类名包含 `"ConfusionMatrix"` 的指标将获得标识符 `"mcc"`，无论其别名如何。

### get_model_execution_order

```python
def get_model_execution_order(model: lxt.LuxonisLightningModule) -> list[str]:
```

按运行顺序列出具有参数的叶子模块的名称。

该函数在每个具有参数且没有子模块的模块上注册一个前向钩子。它在 `torch.no_grad` 下以批大小为 2 的零张量运行模型，并删除钩子。检查点存储列表，[LuxonisLightningModule.load_checkpoint](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md) 使用它将旧检查点的权重映射到更改的模块布局。

该函数将模型保留在评估模式。

参数

 * `model` (`lxt.LuxonisLightningModule`): 模型。其 `nodes.loader_input_shapes` 提供输入形状，其 `device` 放置输入。

返回

 * `list[str]`: 模块名称，如 `named_modules` 报告的，按执行顺序。多次运行的模块每次运行只出现一次。

### log_balanced_class_images

```python
def log_balanced_class_images(tracker: LuxonisTrackerPL, nodes: Nodes, visualizations: dict[str, dict[str, Tensor]], labels:
Labels, cls_task_keys: list[str], class_log_counts: list[int], n_logged_images: int, max_log_images: int, mode: Literal['test',
'val'], current_epoch: int) -> tuple[int, list[int], list[int]]:
```

记录批次中保持记录类平衡的图像。

当样本的某个类在 `class_log_counts` 中具有最低计数时，该函数选择该样本。然后，它将样本的每个类的计数加一。它从不选择没有当前类的样本。最后，它使用 [log_sequential_images](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md) 记录每个可视化的选定样本。

参数

 * `tracker` (`LuxonisTrackerPL`): 接收图像的跟踪器。
 * `nodes` (`Nodes`): 节点图，用于节点的日志名称。
 * `visualizations` (`dict[str, dict[str, Tensor]]`): 节点标识符映射到可视化工具标识符，再映射到形状为 `[B, C, H, W]` 的图像批次。不能为空，因为该函数从其第一个条目读取批次大小。
 * `labels` (`Labels`): 批次的标签。
 * `cls_task_keys` (`list[str]`): 包含形状为 `[B, n_classes]` 的多标签分类目标的标签键。该函数按此顺序沿类维度连接张量。当其值大于 0 时，类存在。
 * `class_log_counts` (`list[int]`): 在此 epoch 中，每个类有多少个选定样本。其长度是类的总数。该函数会就地更新它。
 * `n_logged_images` (`int`): 在此批次之前，每个节点在此 epoch 中记录了多少图像。
 * `max_log_images` (`int`): 每个节点在一个 epoch 中记录的最大图像数量。
 * `mode` (`Literal['test', 'val']`): 评估阶段。
 * `current_epoch` (`int`): 当前 epoch，用作步骤。

返回

 * `tuple[int, list[int], list[int]]`: 此批次后最后一个节点的图像计数器，如 [log_sequential_images](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md) 返回的，`class_log_counts` 本身，以及选定样本的批次索引。

### log_metric_artifacts

```python
def log_metric_artifacts(tracker: LuxonisTrackerPL, metric: BaseMetric, computed: Any, *, mode: Literal['test', 'val'],
formatted_node_name: str, metric_name: str, current_epoch: int):
```

渲染并记录一个指标的图像工件。

Lightning 模块在评估 epoch 结束时调用它，在 [BaseMetric.compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md) 之后和指标重置之前。模块在其他进程和健全性检查期间跳过调用。该函数记录每次失败并继续，因此无法生成或上传图形的指标不会停止运行。当 [BaseMetric.get_artifacts](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md) 引发或返回除字典之外的任何内容时，该函数不记录任何工件。

工件必须是形状为 `[C, H, W]` 的张量。该函数记录任何其他工件的警告并跳过它。图像以 `[H, W, C]` 数组的形式发送到跟踪器，名称由 [metric_artifact_image_name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md) 构建，`current_epoch` 用作步骤。

参数

 * `tracker` (`LuxonisTrackerPL`): 接收图像的跟踪器。
 * `metric` (`BaseMetric`): 生成工件的指标。
 * `computed` (`Any`): [BaseMetric.compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md) 的结果。该函数将其传递给 [BaseMetric.get_artifacts](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)。
 * `mode` (`Literal['test', 'val']`): 评估阶段。
 * `formatted_node_name` (`str`): 节点的日志名称。
 * `metric_name` (`str`): 指标的标识符。
 * `current_epoch` (`int`): 当前 epoch，用作步骤。

### log_sequential_images

```python
def log_sequential_images(tracker: LuxonisTrackerPL, nodes: Nodes, visualizations: dict[str, dict[str, Tensor]], n_logged_images:
int, max_log_images: int, mode: Literal['test', 'val'], current_epoch: int) -> int:
```

按批次顺序记录每个可视化的第一批图像。

对于每个节点，计数器从 `n_logged_images` 开始，到 `max_log_images` 停止。节点的每个可视化工具共享计数器，计数器命名图像。一旦计数器达到 `max_log_images`，节点的其余可视化工具将不记录任何内容。图像以 `"<mode>/visualizations/<node>/<visualizer>/<counter>"` 的形式发送到跟踪器，作为 `[H, W, C]` 数组，`current_epoch` 用作步骤。`<node>` 是 [Nodes.formatted_name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md) 中的日志名称。

参数

 * `tracker` (`LuxonisTrackerPL`): 接收图像的跟踪器。
 * `nodes` (`Nodes`): 节点图，用于节点的日志名称。
 * `visualizations` (`dict[str, dict[str, Tensor]]`): 节点标识符映射到可视化工具标识符，再映射到形状为 `[B, C, H, W]` 的图像批次。不能为空。
 * `n_logged_images` (`int`): 每个节点开始时的计数器值。
 * `max_log_images` (`int`): 节点停止时的计数器值。
 * `mode` (`Literal['test', 'val']`): 评估阶段。
 * `current_epoch` (`int`): 当前 epoch，用作步骤。

返回

 * `int`: 此批次后最后一个节点的计数器。

### metric_artifact_image_name

```python
def metric_artifact_image_name(mode: Literal['test', 'val'], formatted_node_name: str, metric_name: str, artifact_name: str) ->
str:
```

构建指标工件的跟踪器图像名称。

名称为 `"<mode>/metrics/<node>/<metric>/<artifact>"`。epoch 不属于其中。对于 MLflow，`log_image` 将标题从名称的最后一个 `/` 处拆分，并将步骤放在两者之间，就像它对可视化图像所做的那样。[mlflow_image_key](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md) 显示了最终的 MLflow 路径。TensorBoard 和 Weights and Biases 接收名称不变。

> **示例**
> ```pycon
>>> metric_artifact_image_name("val", "head", "pr_curve", "curve")
'val/metrics/head/pr_curve/curve'
```

参数

 * `mode` (`Literal['test', 'val']`): 评估阶段。
 * `formatted_node_name` (`str`): 节点的日志名称，请参阅
   [Nodes.formatted_name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)。
 * `metric_name` (`str`): 指标的标识符。
 * `artifact_name` (`str`): 工件的名称，如
   [BaseMetric.get_artifacts](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
   所键入的。

返回

 * `str`: 图像名称。

### mlflow_image_key

```python
def mlflow_image_key(name: str, step: int) -> str:
```

返回已记录图像的 MLflow 工件路径。

`LuxonisTracker.log_image` 在最后一个 `/`
处将标题从名称中拆分，并将步骤放在两部分之间。此函数构建相同的路径。[LuxonisLightningModule.get_mlflow_logging_keys](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
使用它来列出没有跟踪器的运行的预期工件。

> **示例**
> ```pycon
>>> mlflow_image_key("val/metrics/head/pr_curve/curve", 7)
'val/metrics/head/pr_curve/7/curve.png'
```

参数

 * `name` (`str`): `log_image` 接收的图像名称。它必须包含至少一个 `/`。
 * `step` (`int`): 图像的步骤。Lightning 模块传递 epoch。

返回

 * `str`: `"<base path>/<step>/<caption>.png"`。

引发

 * `ValueError`: 当 `name` 不包含 `/` 时。

### postprocess_metrics

```python
def postprocess_metrics(name: str, values: Any, log_sub_metrics: bool = True) -> dict[str, Tensor]:
```

将 [BaseMetric.compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md) 的结果展平为命名值。

> **示例**
> ```pycon
>>> import torch
>>> result = (torch.tensor(0.5), {"map_50": torch.tensor(0.75)})
>>> out = postprocess_metrics("map", result)
>>> {k: v.item() for k, v in out.items()}
{'map': 0.5, 'map_50': 0.75}
```

```pycon
>>> out = postprocess_metrics("map", result, log_sub_metrics=False)
>>> list(out)
['map']
```

```pycon
>>> sub = {"map_50": torch.tensor(0.75)}
>>> postprocess_metrics("map", sub, log_sub_metrics=False)
{}
```

参数

 * `name` (`str`): 指标的标识符。
 * `values` (`Any`): 计算结果。张量是主值。元组包含主值和子指标。字典仅包含子指标。
 * `log_sub_metrics` (`bool`): 保留子指标。当 `False` 时，只保留主值，字典结果返回空字典。

返回

 * `dict[str, Tensor]`: `name` 映射到主值，加上每个子指标在其自己的键下。字典结果仅返回子指标。

引发

 * `ValueError`: 当 `values` 不具有这三种形式之一时。

## 属性

### A

### T
