# luxonis_progress_bar

Python API: `luxonis_train.callbacks.luxonis_progress_bar`

训练器的进度条和优化器摘要。

[LuxonisRichProgressBar](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)
和
[LuxonisTQDMProgressBar](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)
显示批处理进度并打印每个评估周期的结果。两个进度条都将打印结果镜像到日志文件。

[build_optimizer_summary](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)
和
[log_optimizer_summary](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)
报告模型参数如何在优化器及其参数组中分配。摘要显示了微调规则和配置训练策略的效果。

## 类

### BaseLuxonisProgressBar

训练器进度条的基类。

该类从进度条中删除 `v_num` 项，并添加训练损失的运行平均值作为 `Loss`。子类使用
[BaseLuxonisProgressBar.print_results](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)
和
[BaseLuxonisProgressBar.print_table](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)
打印评估周期的结果。子类还将每个训练周期的摘要行写入日志文件。

#### 方法

##### format_matrix_for_printing

```python
def format_matrix_for_printing(node: Any, name: str, value: Tensor) -> dict[str, Any]:
```

将矩阵指标转换为可打印的字典。

当矩阵每类有一行（列）时，行和列标签是 `node` 的类名。当矩阵多出一行（列）时，标签是类名加上 `"no match"`。否则，标签是字符串形式的索引。当 `node` 的类名引发 `RuntimeError`
时，例如因为节点没有数据集元数据，类名被视为空。该查找的任何其他异常都会传播。

结果包含键 `"values"`（嵌套列表形式的矩阵）、`"row_labels"`、`"col_labels"`、`"row_axis"` (`"GT"`) 和 `"col_axis"` (`"Pred"`)。

> **示例**
> ```pycon
>>> import torch
>>> from types import SimpleNamespace
>>> bar = LuxonisTQDMProgressBar()
>>> node = SimpleNamespace(class_names=["cat", "dog"])
>>> matrix = torch.tensor([[3, 1, 0], [0, 2, 1]])
>>> info = bar.format_matrix_for_printing(node, "cm", matrix)
>>> info["row_labels"], info["col_labels"]
(['cat', 'dog'], ['cat', 'dog', 'no match'])
>>> info["values"]
[[3, 1, 0], [0, 2, 1]]
>>> info["row_axis"], info["col_axis"]
('GT', 'Pred')
```

参数

 * `node` (`Any`): 指标附加到的节点。当对象具有 `module` 属性时，如 [NodeWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)，该方法从该属性读取类名。
 * `name` (`str`): 指标名称。未使用。
 * `value` (`Tensor`): 矩阵，形状为 `[R, C]`。

返回

 * `dict[str, Any]`: 矩阵值及其标签。

##### get_metrics

```python
def get_metrics(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule) -> dict[str, int | str | float | dict[str, float]]:
```

返回进度条末尾显示的项目。

这些项目是模型使用 `prog_bar=True` 记录的指标，由 `ProgressBar.get_metrics` 收集，不包含 `v_num` 条目。当 `pl_module` 的训练损失累加器包含 `"loss"` 条目时，该方法将其添加为 `Loss`。该值是当前周期批次总损失的运行平均值。

参数

 * `trainer` (`pl.Trainer`): 训练器。
 * `pl_module` (`lxt.LuxonisLightningModule`): 模型。其训练损失累加器提供 `Loss` 值。

返回

 * `dict[str, int | str | float | dict[str, float]]`: 要显示的项目，按名称键入。

##### print_results

```python
def print_results(stage: str, loss: float, metrics: Mapping[str, Mapping[str, int | str | float]], matrices: Mapping[str,
Mapping[str, Mapping[str, Any]]]):
```

打印评估周期的结果。

实现必须打印阶段名称、损失、每个节点在 `metrics` 中的一个表，以及每个矩阵在 `matrices` 中的一个表。

参数

 * `stage` (`str`): 阶段名称，例如 `"Validation"`。
 * `loss` (`float`): 周期的平均损失。
 * `metrics` (`Mapping[str, Mapping[str, int | str | float]]`): 标量指标，格式为 `{node_name: {metric_name: value}}`。
 * `matrices` (`Mapping[str, Mapping[str, Mapping[str, Any]]]`): 矩阵指标，格式为 `{node_name: {metric_name: matrix}}`。每个矩阵都是 [BaseLuxonisProgressBar.format_matrix_for_printing](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 格式的字典。

##### print_table

```python
def print_table(title: str, table: Iterable[tuple[str | int | float, ...]], column_names: list[str]):
```

打印一个表。

实现必须打印 `title`，然后是一个表，其中 `column_names` 的每个条目都有一个标题，`table` 的每个元组都有一行。

参数

 * `title` (`str`): 表的标题。
 * `table` (`Iterable[tuple[str | int | float, ...]]`): 行。每行是一个元组，每个列有一个值。
 * `column_names` (`list[str]`): 列名。

### LuxonisRichProgressBar

使用 `rich` 打印样式文本的进度条。

当配置中 `rich_logging` 为 `True` 时，[LuxonisModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md) 使用此进度条。进度条将评估周期的结果作为 `rich` 表打印到控制台。它将相同的表（不带终端样式）渲染到缓冲区，并仅将缓冲区写入日志文件。

#### 方法

##### init

```python
def __init__(self):
```

使用 `leave=True` 和日志控制台初始化进度条。

完成的训练进度条在每个周期结束时保留在终端中。日志控制台将不带终端样式的内存缓冲区写入。[LuxonisRichProgressBar.print_results](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 将缓冲区写入日志文件并清除它。

##### on_train_epoch_end

```python
def on_train_epoch_end(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule):
```

刷新训练任务并记录周期摘要。

Lightning 在每个训练周期结束时调用此钩子。Lightning `RichProgressBar` 基类更新启用显示器的指标列并刷新显示器。项目来自 [BaseLuxonisProgressBar.get_metrics](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)，其中每个张量都替换为其 `item()` 值。然后，一条摘要行仅写入日志文件，格式为 `[Epoch <n>/<max>] Duration: <s>s | Train Loss: <loss>`。持续时间是自 [LuxonisRichProgressBar.on_train_epoch_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 以来的时间，包括该周期的验证。损失是 `trainer.callback_metrics` 的 `train/loss` 值。

Lightning 在 [LuxonisLightningModule.on_train_epoch_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md) 之前运行此钩子，该钩子记录 `train/loss`。因此，该行显示的是上一个周期的值。当值缺失或为零时（例如在第一个周期），它显示 `N/A`。

参数

 * `trainer` (`pl.Trainer`): 训练器。
 * `pl_module` (`lxt.LuxonisLightningModule`): 模型。基类读取其指标以获取指标列。

##### on_train_epoch_start

```python
def on_train_epoch_start(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule):
```

启动训练任务并记录周期开始时间。

Lightning 在每个训练周期开始时调用此钩子。Lightning `RichProgressBar` 基类添加一个以周期命名的训练任务。从第二个周期开始，它首先停止当前显示并启动一个新的显示，因为 `leave` 为 `True`。禁用的进度条会跳过所有这些。开始时间为 [LuxonisRichProgressBar.on_train_epoch_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 中的持续时间提供数据。

参数

 * `trainer` (`pl.Trainer`): 训练器。
 * `pl_module` (`lxt.LuxonisLightningModule`): 模型。未使用。

##### print_results

```python
def print_results(stage: str, loss: float, metrics: Mapping[str, Mapping[str, int | str | float]], matrices: Mapping[str,
Mapping[str, Mapping[str, Any]]]):
```

打印评估周期的结果。

在控制台上，输出以一个包含阶段名称的洋红色规则开始，然后是损失和 `Metrics:` 标题。`metrics` 中的每个节点都会获得一个 `rich` 表，其名称作为标题，列为 `Name` 和 `Value`。该节点的矩阵紧随其表。没有标量指标的节点的矩阵最后出现，标题为 `<node>/<matrix title>`。矩阵的标题是其名称的标题大小写，下划线替换为空格。矩阵以表的形式打印。其标题包含矩阵的 `row_axis` 和 `col_axis` 名称以及列标签。每行以其行标签开始。一个结束规则结束输出。相同的输出，不带终端样式，仅写入日志文件。然后该方法清除日志缓冲区。

参数

 * `stage` (`str`): 阶段名称，例如 `"Validation"`。
 * `loss` (`float`): 周期的平均损失。
 * `metrics` (`Mapping[str, Mapping[str, int | str | float]]`): 标量指标，格式为 `{node_name: {metric_name: value}}`。
 * `matrices` (`Mapping[str, Mapping[str, Mapping[str, Any]]]`): 矩阵指标，格式为 `{node_name: {metric_name: matrix}}`，采用 [BaseLuxonisProgressBar.format_matrix_for_printing](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 的格式。

引发

 * `RuntimeError`: 当进度条的控制台尚不存在时，请参阅 [LuxonisRichProgressBar.console](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)。

##### print_table

```python
def print_table(title: str, table: Iterable[tuple[str | int | float, ...]], column_names: list[str], console: Console | None =
None):
```

将一个表打印为 `rich` 表。

标题为粗体，标题为粗体洋红色。第一列为洋红色，其他列为白色。`str` 转换每行的第一个元素。其他元素中的 `float` 以五位小数打印。任何其他元素都以 `str` 打印。

参数

 * `title` (`str`): 表的标题。
 * `table` (`Iterable[tuple[str | int | float, ...]]`): 行。每行是一个元组，每个列有一个值。
 * `column_names` (`list[str]`): 列名。
 * `console` (`Console | None`): 要打印到的控制台。`None` 表示进度条的控制台，即终端。

引发

 * `RuntimeError`: 当 `console` 为 `None` 且进度条的控制台尚不存在时，请参阅 [LuxonisRichProgressBar.console](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)。

#### 属性

##### console

进度条打印到的 `rich` 控制台。

Lightning `RichProgressBar` 基类在阶段开始且进度条启用时创建控制台。在阶段开始时禁用的进度条不会获得控制台。

引发

 * `RuntimeError`: 当控制台尚不存在时。消息要求用户在配置中将 `rich_logging` 设置为 `False`。

### LuxonisTQDMProgressBar

使用 `tqdm` 打印纯文本的进度条。

当配置中 `rich_logging` 为 `False` 时，[LuxonisModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md) 使用此进度条。进度条通过记录器将评估周期的结果作为 `tabulate` 网格打印，以便控制台和日志文件接收相同的文本。

#### 方法

##### init

```python
def __init__(self):
```

使用 `leave=True` 初始化进度条。

完成的训练进度条在每个周期结束时保留在终端中，下一个周期会获得一个新的进度条。

##### on_train_epoch_end

```python
def on_train_epoch_end(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule):
```

关闭训练进度条并记录周期摘要。

Lightning 在每个训练周期结束时调用此钩子。Lightning `TQDMProgressBar` 基类根据 [BaseLuxonisProgressBar.get_metrics](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 设置启用进度条的后缀并关闭进度条。然后，一条摘要行仅写入日志文件，格式为 `[Epoch <n>/<max>] Duration: <s>s | Train Loss: <loss>`。持续时间是自 [LuxonisTQDMProgressBar.on_train_epoch_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 以来的时间，包括该周期的验证。损失是 `trainer.callback_metrics` 的 `train/loss` 值。

Lightning 在 [LuxonisLightningModule.on_train_epoch_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md) 之前运行此钩子，该钩子记录 `train/loss`。因此，该行显示的是上一个周期的值。当值缺失或为零时（例如在第一个周期），它显示 `N/A`。

参数

 * `trainer` (`pl.Trainer`): 训练器。
 * `pl_module` (`lxt.LuxonisLightningModule`): 模型。基类读取其指标以获取进度条后缀。

##### on_train_epoch_start

```python
def on_train_epoch_start(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule):
```

启动新的训练进度条并记录周期开始时间。

Lightning 在每个训练周期开始时调用此钩子。Lightning `TQDMProgressBar` 基类创建一个新的进度条，因为 `leave` 为 `True`，并将其描述设置为 `Epoch N`。开始时间为 [LuxonisTQDMProgressBar.on_train_epoch_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 中的持续时间提供数据。

参数

 * `trainer` (`pl.Trainer`): 训练器。
 * `pl_module` (`lxt.LuxonisLightningModule`): 模型。未使用。

##### print_results

```python
def print_results(stage: str, loss: float, metrics: Mapping[str, Mapping[str, int | str | float]], matrices: Mapping[str,
Mapping[str, Mapping[str, Any]]]):
```

通过记录器打印评估周期的结果。

输出以一个包含阶段名称的规则开始，然后是损失和 `Metrics:` 标题。`metrics` 中的每个节点都会获得一个包含其名称的规则和一个包含 `Name` 和 `Value` 列的 `tabulate` 网格。该节点的矩阵紧随其网格。没有标量指标的节点的矩阵最后出现，标题为 `<node>/<matrix title>`。矩阵的标题是其名称的标题大小写，下划线替换为空格。矩阵以包含其标题的规则和网格的形式打印。网格的标题包含矩阵的 `row_axis` 和 `col_axis` 名称以及列标签。每行以其行标签开始。一个结束规则结束输出。每行都通过 `logger.info`，因此它到达控制台和日志文件。

参数

 * `stage` (`str`): 阶段名称，例如 `"Validation"`。
 * `loss` (`float`): 周期的平均损失。
 * `metrics` (`Mapping[str, Mapping[str, int | str | float]]`): 标量指标，格式为 `{node_name: {metric_name: value}}`。
 * `matrices` (`Mapping[str, Mapping[str, Mapping[str, Any]]]`): 矩阵指标，格式为 `{node_name: {metric_name: matrix}}`，采用 [BaseLuxonisProgressBar.format_matrix_for_printing](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 的格式。

##### print_table

```python
def print_table(title: str, table: Iterable[tuple[str | int | float, ...]], column_names: list[str]):
```

通过记录器将一个表打印为 `tabulate` 网格。

输出是一个包含 `title` 的规则，然后是 `fancy_grid` 格式的表，数字右对齐。

参数

 * `title` (`str`): 表的标题。
 * `table` (`Iterable[tuple[str | int | float, ...]]`): 行。每行是一个元组，每个列有一个值。
 * `column_names` (`list[str]`): 列名。

## 函数

### build_optimizer_summary

```python
def build_optimizer_summary(optimizers: Sequence[Optimizer], schedulers: Sequence[LRSchedulerTypeUnion | LRSchedulerConfig],
modules: Mapping[str, nn.Module]) -> dict[str, Any]:
```

构建优化器及其参数组的摘要。

摘要是一个嵌套字典，[log_optimizer_summary](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md) 将其渲染并以 JSON 格式写入日志文件。每个参数组列出其超参数及其 所有者，即 `modules` 中包含其参数的模块。

使用了两个分母：

 * 组级别的百分比 `tensors_pct_of_model` 和 `params_pct_of_model` 是相对于模型所有参数的。所有优化器的所有组的总和是 100% 减去没有组持有的参数的份额。两个组持有的参数在该总和中计算两次。
 * 所有者级别的百分比 `tensors_pct_of_owner` 和 `params_pct_of_owner` 是相对于该所有者所有参数的。在一个所有者的所有出现中，当所有者的每个参数恰好在一个组中时，它们加起来为 100%。这显示了节点的参数如何在组之间分配。

冻结参数在其组中像任何其他参数一样计算。百分比包括冻结参数，每个组和所有者分别报告其可训练和冻结计数。

所有者 `"<external>"` 收集组持有但 `modules` 中没有模块拥有的参数。多个模块共享的参数属于 `modules` 中第一个列出它的模块。在每个计数中，`*_tensors` 是参数张量的数量，`*_params` 是元素的数量。当分母为零时，百分比为 `0.0`。

结果包含以下键：

 * `n_optimizers`: 优化器数量。
 * `model_tensors`, `model_params`: 所有所有者的总数，包括外部所有者。
 * `trainable_tensors`, `trainable_params`, `frozen_tensors`, `frozen_params`: 按 `requires_grad` 划分的总数。
 * `optimizers`: 每个优化器一个条目，包含 `index`、`optimizer` 和 `scheduler`（类名）、`n_groups` 和 `groups`。

每个组包含 `index`、`n_tensors`、`n_params`、可训练和冻结计数、`tensors_pct_of_model`、`params_pct_of_model`、`hyperparams` 和 `owners`。`hyperparams` 包含参数组的条目，除了 `params`、可调用对象、列表、元组和字典。`owners` 列出按其在组中的 `n_params` 降序排列的所有者。每个所有者包含 `name`、`n_tensors`、`n_tensors_of_owner`、`tensors_pct_of_owner`、`n_params`、`n_params_of_owner`、`params_pct_of_owner` 以及可训练和冻结计数。

> **示例**
> ```pycon
>>> from torch import nn
>>> from torch.optim import SGD
>>> from torch.optim.lr_scheduler import ConstantLR
>>> backbone = nn.Linear(4, 8)
>>> head = nn.Linear(8, 2)
>>> optimizer = SGD(
...     [
...         {"params": backbone.parameters()},
...         {"params": head.parameters(), "lr": 0.1},
...     ],
...     lr=0.01,
... )
>>> summary = build_optimizer_summary(
...     [optimizer],
...     [ConstantLR(optimizer, factor=1.0)],
...     {"backbone": backbone, "head": head},
... )
>>> summary["n_optimizers"], summary["model_params"]
(1, 58)
>>> group = summary["optimizers"][0]["groups"][0]
>>> group["hyperparams"]["lr"]
0.01
>>> round(group["params_pct_of_model"], 1)
69.0
>>> [owner["name"] for owner in group["owners"]]
['backbone']
```

参数

 * `optimizers` (`Sequence[Optimizer]`): 优化器，按顺序排列。
 * `schedulers` (`Sequence[LRSchedulerTypeUnion | LRSchedulerConfig]`): 每个优化器一个条目。字典贡献其 `"scheduler"` 条目的类名，因为 Lightning
   调度器配置字典包含一个。任何其他对象贡献其自己的类名，因此没有调度器的优化器的 `None` 显示为 `"NoneType"`。Lightning `LRSchedulerConfig` 数据类不是字典，因此它显示为
   `"LRSchedulerConfig"`。
 * `modules` (`Mapping[str, nn.Module]`): 按名称键入的所有者模块，通常是按节点名称键入的模型节点。

返回

 * `dict[str, Any]`: 上述摘要。

引发

 * `ValueError`: 当 `optimizers` 和 `schedulers` 的长度不同时。

### log_optimizer_summary

```python
def log_optimizer_summary(summary: dict[str, Any], use_rich: bool = True):
```

记录来自
[build_optimizer_summary](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)
的摘要。

使用 `use_rich` 时，摘要以嵌套面板的形式显示在全局 `rich` 控制台上。标题面板包含总数。然后每个优化器一个面板，每个面板包含一个组面板。组面板包含一个超参数面板和一个所有者面板。不使用 `use_rich` 时，摘要通过
`logger.info` 以缩进的纯文本列表形式显示，该列表到达控制台和日志文件。在这两种情况下，函数还将摘要以 JSON 格式写入日志文件，对于 JSON 无法编码的值使用 `str`。

参数

 * `summary` (`dict[str, Any]`): 来自
   [build_optimizer_summary](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)
   的摘要。
 * `use_rich` (`bool`): 是否使用 `rich` 面板渲染摘要。
