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

本页目录

  • 类
  • LossAccumulator
  • MainMetric
  • Nodes
  • NodeWrapper
  • 函数
  • build_training_strategy
  • check_tensor_device
  • compute_losses
  • compute_visualization_buffer
  • get_main_metric
  • get_model_execution_order
  • log_balanced_class_images
  • log_metric_artifacts
  • log_sequential_images
  • metric_artifact_image_name
  • mlflow_image_key
  • postprocess_metrics
  • 属性
  • A
  • T
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_train.lightning.utilsLightning 模块背后的辅助函数。Nodes 从配置构建节点图,并将每个节点包装在 NodeWrapper 中,同时包含其损失、指标和可视化工具。LossAccumulator 保持每个损失在一个 epoch 中的运行平均值。这些函数汇总损失,构建训练策略,展平指标结果,并将指标工件和可视化记录到跟踪器。

类

LossAccumulator

一个 epoch 中每个损失值的运行平均值。Lightning 模块为 "train"、"val" 和 "test" 阶段各保留一个累加器。它在每个步骤后调用 update,并在 epoch 结束时调用 clear。从未收到 update 的键读取为 0.0。

方法

init
Python
1def __init__(*args, **kwargs):
clear
Python
1def clear(self):
删除所有存储的平均值和所有计数。
update
Python
1def update(losses: dict[str, Tensor]):
将每个损失的一个值折叠到其运行平均值中。这会替换 dict.update。一个值不会覆盖存储的值。它会移动平均值。参数
  • losses (dict[str, Tensor]): 损失名称映射到单元素张量,如 compute_losses 返回的第二个值。

MainMetric

选择最佳检查点的指标。

属性

metric_name
指标的标识符。类名包含 "ConfusionMatrix" 的指标将获得标识符 "mcc"。
node_name
持有指标的节点的标识符。当配置设置别名时,它是节点的别名,否则是类名。

Nodes

模型的节点图,从配置构建。一个 torch.nn.ModuleDict,将每个节点标识符映射到其 NodeWrapper。构造函数按拓扑顺序构建节点。它在零张量上运行每个节点,因此后续节点知道其输入的形状。

方法

init
Python
1def __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
1def build_callbacks(save_dir: Path) -> list[pl.Callback]:
构建训练运行的 Lightning 回调。列表按以下顺序排列:
  • TrainingManager,它应用冻结计划并在每次反向传播后调用训练策略。
  • LuxonisModelSummary,深度为 2,当 rich_logging 为 true 时作为富表格。
  • 一个 ModelCheckpoint,它监控 val/loss,保留最低值,并写入 save_dir / "min_val_loss"。
  • AIMETCallback,当 exporter.aimet.active 设置时。
  • 一个 ModelCheckpoint,它监控主指标的 val/metric/<node>/<metric>,当配置定义一个时。<node> 是 formatted_name 中的日志名称。检查点保留最高值,并写入 save_dir / "best_val_metric"。
  • trainer.callbacks 的每个活动回调,从 CALLBACKS 注册表构建。该函数记录并跳过不活动的。
  • 一个 GradientAccumulationScheduler 用于 trainer.accumulate_grad_batches,当配置设置该值且上述回调不包含此类调度器时。当它们包含时,该函数记录警告并忽略配置值。
两个检查点都保留 trainer.save_top_k 文件。参数
  • save_dir (Path): 接收检查点子目录的目录。
返回
  • list[pl.Callback]: 回调,按上述顺序。
formatted_name
Python
1def formatted_name(node_name: str) -> str:
返回节点的日志名称。参数
  • node_name (str): 节点的标识符。
返回
  • str: 当节点有任务名称时为 "<task_name>-<node_name>",否则仅为 node_name。
traverse
Python
1def 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 为配置中的每个节点创建一个包装器。包装器将每个构造函数参数存储在相同的名称下。module 是一个注册的子模块。损失、指标和可视化工具存储在普通字典中,因此 torch.nn.Module 的递归方法无法访问它们。

方法

init
Python
1def __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
1def 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
1def build_training_strategy(cfg: Config, pl_module: pl.LightningModule) -> BaseTrainingStrategy | None:
构建配置命名的训练策略。策略类来自 STRATEGIES 注册表,trainer.training_strategy.params 访问其构造函数。策略通过 BaseTrainingStrategy.get_base_configs 提供基本优化器和调度器。因此,当 trainer.optimizer 或 trainer.scheduler 与其默认值不同时,该函数会记录警告。没有具体 rules 方法的类早于基于规则的 API,并且已弃用。该函数记录警告。它构建一个未注册的子类,其中包含抽象 rules 和 get_base_configs 的存根,以便它可以实例化该类。然后它通过 LegacyStrategyAdapter 挂载实例。适配器不贡献任何规则。当旧版类未定义 get_base_configs 时,它会引发 NotImplementedError。然后训练计划会回退到配置的优化器和调度器。参数
  • cfg (Config): 配置。trainer.training_strategy 命名策略并包含其参数。
  • pl_module (pl.LightningModule): 策略附加到的 Lightning 模块。
返回
  • BaseTrainingStrategy | None: 策略,如果配置中没有命名则为 None。

check_tensor_device

Python
1def check_tensor_device(x: Tensor | list[Tensor], device: torch.device) -> bool:
检查张量或列表中的每个张量是否在设备上。参数
  • x (Tensor | list[Tensor]): 张量,或张量列表或元组。
  • device (torch.device): 要比较的设备。
返回
  • bool: 当张量在 device 上时为 True,或者当序列中的每个项都是 device 上的张量时为 True。空序列返回 True。
引发
  • TypeError: 当 x 既不是张量也不是列表或元组时。

compute_losses

Python
1def 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 已经将每个损失乘以其在配置中的 weight。子损失不带权重。参数
  • 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
1def 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 减去填充级别。参数
  • 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
1def get_main_metric(cfg: Config) -> MainMetric | None:
查找配置中标记为 is_main_metric 的指标。该函数按配置顺序扫描节点及其指标,第一个匹配项获胜。配置验证最多允许一个主指标,并在未设置时标记第一个指标。参数
  • cfg (Config): 配置。
返回
  • MainMetric | None: 节点标识符和指标标识符,或者当没有指标设置 is_main_metric 时为 None。类名包含 "ConfusionMatrix" 的指标将获得标识符 "mcc",无论其别名如何。

get_model_execution_order

Python
1def get_model_execution_order(model: lxt.LuxonisLightningModule) -> list[str]:
按运行顺序列出具有参数的叶子模块的名称。该函数在每个具有参数且没有子模块的模块上注册一个前向钩子。它在 torch.no_grad 下以批大小为 2 的零张量运行模型,并删除钩子。检查点存储列表,LuxonisLightningModule.load_checkpoint 使用它将旧检查点的权重映射到更改的模块布局。该函数将模型保留在评估模式。参数
  • model (lxt.LuxonisLightningModule): 模型。其 nodes.loader_input_shapes 提供输入形状,其 device 放置输入。
返回
  • list[str]: 模块名称,如 named_modules 报告的,按执行顺序。多次运行的模块每次运行只出现一次。

log_balanced_class_images

Python
1def 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 记录每个可视化的选定样本。参数
  • 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 返回的,class_log_counts 本身,以及选定样本的批次索引。

log_metric_artifacts

Python
1def 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 之后和指标重置之前。模块在其他进程和健全性检查期间跳过调用。该函数记录每次失败并继续,因此无法生成或上传图形的指标不会停止运行。当 BaseMetric.get_artifacts 引发或返回除字典之外的任何内容时,该函数不记录任何工件。工件必须是形状为 [C, H, W] 的张量。该函数记录任何其他工件的警告并跳过它。图像以 [H, W, C] 数组的形式发送到跟踪器,名称由 metric_artifact_image_name 构建,current_epoch 用作步骤。参数
  • tracker (LuxonisTrackerPL): 接收图像的跟踪器。
  • metric (BaseMetric): 生成工件的指标。
  • computed (Any): BaseMetric.compute 的结果。该函数将其传递给 BaseMetric.get_artifacts。
  • mode (Literal['test', 'val']): 评估阶段。
  • formatted_node_name (str): 节点的日志名称。
  • metric_name (str): 指标的标识符。
  • current_epoch (int): 当前 epoch,用作步骤。

log_sequential_images

Python
1def 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 中的日志名称。参数
  • 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
1def 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 显示了最终的 MLflow 路径。TensorBoard 和 Weights and Biases 接收名称不变。参数
  • mode (Literal['test', 'val']): 评估阶段。
  • formatted_node_name (str): 节点的日志名称,请参阅 Nodes.formatted_name。
  • metric_name (str): 指标的标识符。
  • artifact_name (str): 工件的名称,如 BaseMetric.get_artifacts 所键入的。
返回
  • str: 图像名称。

mlflow_image_key

Python
1def mlflow_image_key(name: str, step: int) -> str:
返回已记录图像的 MLflow 工件路径。LuxonisTracker.log_image 在最后一个 / 处将标题从名称中拆分,并将步骤放在两部分之间。此函数构建相同的路径。LuxonisLightningModule.get_mlflow_logging_keys 使用它来列出没有跟踪器的运行的预期工件。参数
  • name (str): log_image 接收的图像名称。它必须包含至少一个 /。
  • step (int): 图像的步骤。Lightning 模块传递 epoch。
返回
  • str: "<base path>/<step>/<caption>.png"。
引发
  • ValueError: 当 name 不包含 / 时。

postprocess_metrics

Python
1def postprocess_metrics(name: str, values: Any, log_sub_metrics: bool = True) -> dict[str, Tensor]:
将 BaseMetric.compute 的结果展平为命名值。参数
  • name (str): 指标的标识符。
  • values (Any): 计算结果。张量是主值。元组包含主值和子指标。字典仅包含子指标。
  • log_sub_metrics (bool): 保留子指标。当 False 时,只保留主值,字典结果返回空字典。
返回
  • dict[str, Tensor]: name 映射到主值,加上每个子指标在其自己的键下。字典结果仅返回子指标。
引发
  • ValueError: 当 values 不具有这三种形式之一时。

属性

A

T