此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 类
  • BaseLuxonisProgressBar
  • LuxonisRichProgressBar
  • LuxonisTQDMProgressBar
  • 函数
  • build_optimizer_summary
  • log_optimizer_summary
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

luxonis_progress_bar

最后更新
Python API: luxonis_train.callbacks.luxonis_progress_bar训练器的进度条和优化器摘要。LuxonisRichProgressBar 和 LuxonisTQDMProgressBar 显示批处理进度并打印每个评估周期的结果。两个进度条都将打印结果镜像到日志文件。build_optimizer_summary 和 log_optimizer_summary 报告模型参数如何在优化器及其参数组中分配。摘要显示了微调规则和配置训练策略的效果。

类

BaseLuxonisProgressBar

训练器进度条的基类。该类从进度条中删除 v_num 项,并添加训练损失的运行平均值作为 Loss。子类使用 BaseLuxonisProgressBar.print_results 和 BaseLuxonisProgressBar.print_table 打印评估周期的结果。子类还将每个训练周期的摘要行写入日志文件。

方法

format_matrix_for_printing
Python
1def 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")。参数
  • node (Any): 指标附加到的节点。当对象具有 module 属性时,如 NodeWrapper,该方法从该属性读取类名。
  • name (str): 指标名称。未使用。
  • value (Tensor): 矩阵,形状为 [R, C]。
返回
  • dict[str, Any]: 矩阵值及其标签。
get_metrics
Python
1def 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]]: 要显示的项目,按名称键入。
Python
1def 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 格式的字典。
Python
1def 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 使用此进度条。进度条将评估周期的结果作为 rich 表打印到控制台。它将相同的表(不带终端样式)渲染到缓冲区,并仅将缓冲区写入日志文件。

方法

init
Python
1def __init__(self):
使用 leave=True 和日志控制台初始化进度条。完成的训练进度条在每个周期结束时保留在终端中。日志控制台将不带终端样式的内存缓冲区写入。LuxonisRichProgressBar.print_results 将缓冲区写入日志文件并清除它。
on_train_epoch_end
Python
1def on_train_epoch_end(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule):
刷新训练任务并记录周期摘要。Lightning 在每个训练周期结束时调用此钩子。Lightning RichProgressBar 基类更新启用显示器的指标列并刷新显示器。项目来自 BaseLuxonisProgressBar.get_metrics,其中每个张量都替换为其 item() 值。然后,一条摘要行仅写入日志文件,格式为 [Epoch <n>/<max>] Duration: <s>s | Train Loss: <loss>。持续时间是自 LuxonisRichProgressBar.on_train_epoch_start 以来的时间,包括该周期的验证。损失是 trainer.callback_metrics 的 train/loss 值。Lightning 在 LuxonisLightningModule.on_train_epoch_end 之前运行此钩子,该钩子记录 train/loss。因此,该行显示的是上一个周期的值。当值缺失或为零时(例如在第一个周期),它显示 N/A。参数
  • trainer (pl.Trainer): 训练器。
  • pl_module (lxt.LuxonisLightningModule): 模型。基类读取其指标以获取指标列。
on_train_epoch_start
Python
1def on_train_epoch_start(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule):
启动训练任务并记录周期开始时间。Lightning 在每个训练周期开始时调用此钩子。Lightning RichProgressBar 基类添加一个以周期命名的训练任务。从第二个周期开始,它首先停止当前显示并启动一个新的显示,因为 leave 为 True。禁用的进度条会跳过所有这些。开始时间为 LuxonisRichProgressBar.on_train_epoch_end 中的持续时间提供数据。参数
  • trainer (pl.Trainer): 训练器。
  • pl_module (lxt.LuxonisLightningModule): 模型。未使用。
Python
1def 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 的格式。
引发
Python
1def 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 表示进度条的控制台,即终端。
引发

属性

console
进度条打印到的 rich 控制台。Lightning RichProgressBar 基类在阶段开始且进度条启用时创建控制台。在阶段开始时禁用的进度条不会获得控制台。引发
  • RuntimeError: 当控制台尚不存在时。消息要求用户在配置中将 rich_logging 设置为 False。

LuxonisTQDMProgressBar

使用 tqdm 打印纯文本的进度条。当配置中 rich_logging 为 False 时,LuxonisModel 使用此进度条。进度条通过记录器将评估周期的结果作为 tabulate 网格打印,以便控制台和日志文件接收相同的文本。

方法

init
Python
1def __init__(self):
使用 leave=True 初始化进度条。完成的训练进度条在每个周期结束时保留在终端中,下一个周期会获得一个新的进度条。
on_train_epoch_end
Python
1def on_train_epoch_end(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule):
关闭训练进度条并记录周期摘要。Lightning 在每个训练周期结束时调用此钩子。Lightning TQDMProgressBar 基类根据 BaseLuxonisProgressBar.get_metrics 设置启用进度条的后缀并关闭进度条。然后,一条摘要行仅写入日志文件,格式为 [Epoch <n>/<max>] Duration: <s>s | Train Loss: <loss>。持续时间是自 LuxonisTQDMProgressBar.on_train_epoch_start 以来的时间,包括该周期的验证。损失是 trainer.callback_metrics 的 train/loss 值。Lightning 在 LuxonisLightningModule.on_train_epoch_end 之前运行此钩子,该钩子记录 train/loss。因此,该行显示的是上一个周期的值。当值缺失或为零时(例如在第一个周期),它显示 N/A。参数
  • trainer (pl.Trainer): 训练器。
  • pl_module (lxt.LuxonisLightningModule): 模型。基类读取其指标以获取进度条后缀。
on_train_epoch_start
Python
1def on_train_epoch_start(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule):
启动新的训练进度条并记录周期开始时间。Lightning 在每个训练周期开始时调用此钩子。Lightning TQDMProgressBar 基类创建一个新的进度条,因为 leave 为 True,并将其描述设置为 Epoch N。开始时间为 LuxonisTQDMProgressBar.on_train_epoch_end 中的持续时间提供数据。参数
  • trainer (pl.Trainer): 训练器。
  • pl_module (lxt.LuxonisLightningModule): 模型。未使用。
Python
1def 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 的格式。
Python
1def 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
1def build_optimizer_summary(optimizers: Sequence[Optimizer], schedulers: Sequence[LRSchedulerTypeUnion | LRSchedulerConfig], modules: Mapping[str, nn.Module]) -> dict[str, Any]:
构建优化器及其参数组的摘要。摘要是一个嵌套字典,log_optimizer_summary 将其渲染并以 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 以及可训练和冻结计数。参数
  • 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
1def log_optimizer_summary(summary: dict[str, Any], use_rich: bool = True):
记录来自 build_optimizer_summary 的摘要。使用 use_rich 时,摘要以嵌套面板的形式显示在全局 rich 控制台上。标题面板包含总数。然后每个优化器一个面板,每个面板包含一个组面板。组面板包含一个超参数面板和一个所有者面板。不使用 use_rich 时,摘要通过 logger.info 以缩进的纯文本列表形式显示,该列表到达控制台和日志文件。在这两种情况下,函数还将摘要以 JSON 格式写入日志文件,对于 JSON 无法编码的值使用 str。参数
  • summary (dict[str, Any]): 来自 build_optimizer_summary 的摘要。
  • use_rich (bool): 是否使用 rich 面板渲染摘要。