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

本页目录

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

luxonis_lightning

最后更新
Python API: luxonis_train.lightning.luxonis_lightning运行节点图的 Lightning 模块。它构建节点,按拓扑顺序运行它们,计算损失和指标,并决定在每个 epoch 记录什么。

类

LuxonisLightningModule

包含整个模型的 Lightning 模块。该模块构建配置的每个节点,并将其保存在 nodes 中,以及附加到每个节点的损失、指标和可视化工具。模型拓扑是一个有向无环图。nodes.graph 将其存储为从节点名称到馈送它的节点名称的映射。full_forward 运行图。Lightning 通过 *_step 方法和 on_* 钩子驱动训练、验证、测试和预测。LuxonisModel 拥有该模块并将其附加到训练器。

方法

init
Python
1def __init__(cfg: Config, save_dir: PathType, input_shapes: dict[str, Size], dataset_metadata: DatasetMetadata | None = None, *, _core: luxonis_train.core.LuxonisModel | None = None, **kwargs):
从配置构建模块。构造函数执行以下步骤:
  • 它构建节点及其附加模块。
  • 它构建训练策略。
  • 当存在时,它加载 cfg.model.weights 命名的检查点。该加载使模块处于评估模式。
  • 它将 luxonis_train 和 luxonis_ml 的版本保存为超参数。
参数
  • cfg (Config): 定义模型、加载器和训练器的配置。
  • save_dir (PathType): 检查点和日志的目录,作为字符串或 pathlib.Path。
  • input_shapes (dict[str, Size]): 每个加载器输入的形状,以输入名称为键,不带批处理维度。
  • dataset_metadata (DatasetMetadata | None): 数据集的元数据。None 构建一个空的 DatasetMetadata。
  • _core (luxonis_train.core.LuxonisModel | None): 拥有此模块的 LuxonisModel。没有它,core 会引发错误。
  • **kwargs: LightningModule 构造函数的额外关键字参数。
compute_training_loss
Python
1def compute_training_loss(train_batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> Tensor:
运行一个训练批次并返回其总损失。该方法运行 full_forward,并打开损失,使用 compute_losses 对它们求和,并将每个损失值记录在训练损失累加器中,on_train_epoch_end 会记录该累加器。参数
  • train_batch (tuple[dict[str, Tensor] | Tensor, Labels]): 批次的加载器输入和标签。
返回
  • Tensor: 每个损失的总和,每个损失都已按其配置 weight 进行缩放,形状为模块设备上的 [1]。
引发
  • ValueError: 当没有节点产生损失时。
configure_callbacks
Python
1def configure_callbacks(self) -> list[pl.Callback]:
构建每次运行的回调。Lightning 在训练器的每次 fit、validate、test 或 predict 调用开始时调用它。该方法返回 save_dir 的 Nodes.build_callbacks,它按此顺序包含:
  • 一个 TrainingManager;
  • 一个 LuxonisModelSummary;
  • 一个 ModelCheckpoint,用于 val/loss,保存在 save_dir / "min_val_loss" 中;
  • 一个 AIMETCallback,当 cfg.exporter.aimet.active 开启时;
  • 一个 ModelCheckpoint,用于主指标,保存在 save_dir / "best_val_metric" 中,当配置中存在时;
  • cfg.trainer.callbacks 的每个活动回调;
  • 一个 GradientAccumulationScheduler,当 cfg.trainer.accumulate_grad_batches 设置且尚无该类的回调时。
返回
  • list[pl.Callback]: 回调,按该顺序。
configure_optimizers
Python
1def configure_optimizers(self) -> tuple[Sequence[Optimizer], Sequence[LRSchedulerTypeUnion | LRSchedulerConfig]]:
构建运行的优化器和调度器。Lightning 在 fit 开始时调用它。该方法使用 resolve_training_plan 构建一个 TrainingPlan。该计划结合了节点的微调规则、训练策略的规则以及训练器级别的优化器和调度器。该方法使用 build_training_plan 实例化该计划。然后它将组句柄交给训练策略和节点的冻结调度。它将运行时存储在 training_plan 中,并记录参数组的摘要。max 模式下的 ReduceLROnPlateau 调度器将主指标作为 val/metric/<task>-<node>/<metric> 进行监控。如果没有主指标,build_training_plan 会引发 ValueError。在任何其他模式下,调度器都会监控 val/loss。返回
  • tuple[Sequence[Optimizer], Sequence[LRSchedulerTypeUnion | LRSchedulerConfig]]: 包含计划的一个优化器的列表,当计划有多个内部优化器时,它是一个 CompositeOptimizer,以及计划的调度器配置。
detach
Python
1def detach(self):
将模块从其训练器中分离。该方法将 trainer 设置为 None。之后,tracker 返回 None,progress_bar 引发 AttributeError。
export_onnx
Python
1def export_onnx(save_path: PathType, **kwargs) -> Path:
将模型导出为 ONNX。该方法将模块置于评估模式,将其移动到 CPU,并进入导出模式。它为每个节点读取的加载器输入构建一个形状为 [1, *shape] 的零输入。它运行图一次以命名输出,并调用 Lightning 模块的 to_onnx。然后它记录路径,退出导出模式,将模块置于训练模式,并将其移回其设备。默认的 input_names 是加载器输入名称。默认的 output_names 是节点的 export_output_names,当它们的计数与其输出匹配时,否则为 <task>/<node>/<output>/<index>。计数不匹配会记录警告。在 PyTorch 2.5 及更高版本中,dynamo 默认为 False。参数
  • save_path (PathType): ONNX 文件的路径,作为字符串或 pathlib.Path。
  • **kwargs: torch.onnx.export 的额外关键字参数,例如 opset_version 和 dynamic_axes。
返回
  • Path: save_path 作为 pathlib.Path。
forward
Python
1def forward(inputs: dict[str, Tensor] | Tensor) -> tuple[Tensor, ...]:
运行图并以扁平元组形式返回输出。这是模块直接调用和 ONNX 导出的入口点。它运行 full_forward,不带损失、指标和可视化,并扁平化输出节点的包。元组按节点名称排序,然后按输出键排序,然后按索引排序。列表值贡献其每个张量。单个张量值在其第一个维度的每个条目重复一次。导出使用一个批次。参数
  • inputs (dict[str, Tensor] | Tensor): 加载器输入,以输入名称为键。裸张量是名为 image_source 的输入。
返回
  • tuple[Tensor, ...]: 输出节点的扁平化输出。
full_forward
Python
1def full_forward(inputs: dict[str, Tensor] | Tensor, labels: Labels | None = None, images: Tensor | None = None, *, compute_loss: bool = True, compute_metrics: bool = False, compute_visualizations: bool = False) -> LuxonisOutput:
运行图的每个节点并收集其结果。节点按拓扑顺序运行。一个节点在其所有馈送节点运行后运行。该方法跳过其 export 标志和 remove_on_export 都设置的节点。一旦没有后续节点读取节点的输出,该方法就会从内存中删除该输出,除非该节点是输出节点。每个节点运行后,其附加模块移动到模块的设备并运行:
  • 当 compute_loss 开启且 labels 给定时,节点的每个损失都在输出和标签上运行。当模块处于训练模式时,该方法首先将损失置于训练模式。
  • 当 compute_metrics 开启且 labels 给定时,节点的每个指标都会更新其状态。该方法不返回指标值。
  • 当 compute_visualizations 开启且 images 给定时,节点的每个可视化工具都会在 images 上绘制,并且 combine_visualizations 将其结果合并为一个图像批次。
参数
  • inputs (dict[str, Tensor] | Tensor): 加载器输入,以输入名称为键。裸张量是名为 image_source 的输入。张量移动到模块的设备。
  • labels (Labels | None): 批次的标签,以 <task>/<label> 为键。张量移动到模块的设备。None 跳过损失和指标。
  • images (Tensor | None): 批次的去归一化图像,形状为 [B, C, H, W],可视化工具在其上绘制。None 跳过可视化。
  • compute_loss (bool): 是否运行损失。
  • compute_metrics (bool): 是否更新指标。
  • compute_visualizations (bool): 是否运行可视化工具。
返回
  • LuxonisOutput: outputs 包含每个运行的输出节点的包,以节点名称为键。losses 包含每个损失的值,以节点名称和损失名称为键;一个值是一个张量,或一个张量及其子损失的元组。visualizations 包含每个可视化工具的图像批次,形状为 [B, C, H, W],以节点名称和可视化工具名称为键。metrics 保持为空。
get_mlflow_logging_keys
Python
1def get_mlflow_logging_keys(self) -> dict[str, list[str]]:
返回完整运行的指标键和工件路径。结果预测了跟踪器在当前配置下运行所接收的内容。LuxonisModel.tune 读取它以查找主指标的监控键。该方法在每个指标上调用 compute 以了解其子指标的名称,而无需重置。在每个键中,<task>-<node> 是节点的日志名称,请参阅 Nodes.formatted_name。"metrics" 列表包含:
  • train、val 和 test 的 <mode>/loss 和 <mode>/loss/<task>-<node>/<loss>。子损失键未列出;
  • val/metric/<task>-<node>/<name> 和 test/metric/<task>-<node>/<name>,用于名称不包含 confusion_matrix 的每个指标值。当运行没有验证 epoch 时,即当 validation_interval 为 -1 且 run_validation_after_first_epoch 关闭时,val 键不存在;
  • TrainingProgressCallback 的计时键,当配置中列出时。
"artifacts" 列表包含:
  • <mode>/metrics/<epoch>/<task>-<node>/<name>.json,用于名称包含 confusion_matrix 的每个指标值,在 epoch 0 和每个验证 epoch 用于 val,在 epoch cfg.trainer.epochs 用于 test;
  • <mode>/metrics/<task>-<node>/<metric>/<epoch>/<artifact>.png,用于每个指标的每个工件名称,在相同的 epoch;
  • <mode>/visualizations/<task>-<node>/<visualizer>/<epoch>/<i>.png,用于每个可视化工具,在相同的 epoch,对于 <i> 小于 cfg.trainer.n_log_images;
  • 配置中列出的回调文件,无论是否活动。<name> 是 cfg.exporter.name,或者没有它时是 cfg.model.name:
    • UploadCheckpoint: best_val_metric.ckpt 和 min_val_loss.ckpt;
    • ExportOnTrainEnd: <name>.onnx;
    • ArchiveOnTrainEnd: <name>.onnx.tar.xz;
    • ConvertOnTrainEnd: <name>.onnx 和 <name>.onnx.tar.xz;
    • AIMETCallback: <name>.onnx、<name>.onnx.data、<name>.onnx.tar.xz 和 <name>.encodings;
  • luxonis_train.log、training_config.yaml 和 <model name>.yaml,其中 <model name> 是 cfg.model.name。
返回
  • dict[str, list[str]]: "metrics" 和 "artifacts" 列表,每个都已排序。
load_checkpoint
Python
1def load_checkpoint(ckpt: PathType | dict[str, Any] | None):
从检查点加载每个节点的权重。当它获得路径时,该方法在模块的设备上加载检查点文件。当 cfg.trainer.resume_training 开启且检查点配置的 trainer.epochs 高于 cfg.trainer.epochs 时,它会发出警告。当配置的预定义模型和检查点的预定义模型解析为不同的类时,它也会发出警告。当检查点的预定义模型不再解析时,它也会发出警告。该方法按节点拆分状态字典。0.4 或更高版本的检查点将节点键为 nodes.<node>.module.,旧版本为 nodes.<node>.。没有 version 键的检查点计为 0.3.0。每个部分都以 strict=True 加载到其节点中。当加载失败时:
  • 当 cfg.trainer.strict_weights_loading 开启时,该方法会引发错误。
  • 否则,该方法通过检查点和模型的 execution_order 重新映射键,并再次加载该部分。如果没有执行顺序,或者重新映射失败,则该部分以 strict=False 加载,并报告日志消息。
该方法在零输入上运行一次前向传播以记录模型的执行顺序,这使模块处于评估模式。参数
  • ckpt (PathType | dict[str, Any] | None): 检查点文件的路径,或已加载的检查点字典,其中包含 state_dict 键。None 不加载任何内容。
引发
  • ValueError: 当检查点没有 state_dict 键时。
  • RuntimeError: 当节点在 cfg.trainer.strict_weights_loading 开启时加载失败,或者检查点中没有节点的键时。
load_state_dict
Python
1def load_state_dict(state_dict: Mapping[str, Tensor], strict: bool = True) -> _IncompatibleKeys:
加载状态字典,并在运行恢复时放宽检查。Lightning 在从检查点恢复运行时调用此方法,strict 设置为模块的 strict_loading,默认为 True。当 cfg.trainer.resume_training 关闭时,该方法的行为类似于 torch.nn.Module.load_state_dict。当 cfg.trainer.resume_training 开启时:
  • 当 cfg.trainer.strict_weights_loading 关闭时,该方法以 strict=False 加载状态字典并返回每个不匹配项。
  • 当 cfg.trainer.strict_weights_loading 开启时,该方法省略了从损失、指标或可视化工具指向其节点的键。此类键以 nodes.<node>.losses.、nodes.<node>.metrics. 或 nodes.<node>.visualizers. 开头,并包含 _node.。该方法忽略结果中的相同键。对于任何其他缺失或意外的键,它会引发错误。
参数
  • state_dict (Mapping[str, Tensor]): 要加载的参数和缓冲区,以它们在此模块中的名称为键。
  • strict (bool): 是否每个键都必须匹配。在运行恢复时忽略。
返回
  • _IncompatibleKeys: 加载的 missing_keys 和 unexpected_keys。严格恢复后两者都为空。
引发
  • RuntimeError: 当运行以严格权重加载恢复时,且不是此类附加模块键的键缺失或意外时。
on_save_checkpoint
Python
1def on_save_checkpoint(checkpoint: dict[str, Any]):
将运行的元数据添加到检查点。Lightning 在写入检查点之前调用它。该方法就地更改 checkpoint:
  • 它删除了 state_dict 中从损失、指标或可视化工具指向其节点的键。
  • 它添加了 version,即 luxonis_train 的版本。
  • 它添加了 execution_order,即包含参数的叶模块的名称,按前向传播运行它们的顺序。
  • 它添加了 config,即配置的转储。
  • 它添加了 dataset_metadata,即数据集元数据的转储。
  • 它添加了 predefined_model:配置中的模型,其中 latest 解析为版本号,否则继承自加载的检查点。如果没有,该方法会删除该键。
执行顺序来自零输入上的前向传播,这使模块处于评估模式。参数
  • checkpoint (dict[str, Any]): Lightning 即将写入的检查点字典。
on_test_epoch_end
Python
1def on_test_epoch_end(self):
记录 epoch 的测试结果。Lightning 在测试 epoch 结束时调用它。该方法与 on_validation_epoch_end 相同,带有 test 前缀,不改变验证间隔。引发
  • RuntimeError: 当运行使用 DDP 且指标值不在模块的设备上时。
on_train_epoch_end
Python
1def on_train_epoch_end(self):
记录 epoch 的平均训练损失。Lightning 在每个训练 epoch 结束时调用它。该方法将训练损失累加器的每个条目记录为 train/<name>,并带有 sync_dist=True。它将 <name> 中的节点名称替换为节点的日志名称,请参阅 Nodes.formatted_name。然后它清除累加器。
on_train_epoch_start
Python
1def on_train_epoch_start(self):
告诉每个节点开始的 epoch 号。Lightning 在每个训练 epoch 开始时调用它。该方法在每个节点的模块上设置 current_epoch,节点及其附加模块会读取该值。
on_validation_epoch_end
Python
1def on_validation_epoch_end(self):
记录 epoch 的验证结果。Lightning 在每个验证 epoch 结束时调用它,包括健全性检查。该方法执行以下步骤:
  • 它将平均验证损失记录为 val/<name>,与 on_train_epoch_end 对训练所做的一样。
  • 它计算每个指标。在主进程上,在健全性检查之外,它将指标的图像工件上传到跟踪器。然后它重置指标。它将标量值记录为 val/metric/<task>-<node>/<name>,并带有 sync_dist=True。2-D 值作为名为 val/metrics/<epoch>/<task>-<node>/<name> 的矩阵发送到跟踪器,其中 BaseLuxonisProgressBar.format_matrix_for_printing 的行标签作为其类名。<task>-<node> 是节点的日志名称,请参阅 Nodes.formatted_name。<name> 是指标标识符,或者当 cfg.trainer.log_sub_metrics 开启时是子指标的名称。
  • 在主进程上,它记录损失,通过进度条打印指标,并记录主指标值。
  • 当 epoch 记录的图像少于 cfg.trainer.n_log_images 时,它会记录警告。然后它记录 epoch 缓冲的可视化。当计数匹配时,它会停止在运行的其余部分缓冲跳过的图像。
  • 它清除缓冲的可视化、图像计数器和损失累加器。
在 epoch 0 的验证之后,在健全性检查之外,它将 setup 替换的 trainer.check_val_every_n_epoch 放回。引发
  • RuntimeError: 当运行使用 DDP 且指标值不在模块的设备上时。
predict_step
Python
1def predict_step(batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> LuxonisOutput:
运行预测循环的一个批次。Lightning 为预测加载器的每个批次调用它一次。该方法将图像输入去归一化为 uint8 图像。然后它在这些图像上运行 full_forward,并打开可视化工具,关闭损失和指标。参数
  • batch (tuple[dict[str, Tensor] | Tensor, Labels]): 批次的加载器输入和标签。
返回
  • LuxonisOutput: 每个输出节点的包和每个可视化工具的图像。losses 和 metrics 为空。
reparameterize
Python
1def reparameterize(self) -> Self:
重新参数化模型的每个 Reparameterizable 块。与 set_export_mode 不同,该方法保持节点的导出模式不变。set_export_mode 与 False 恢复块。LuxonisModel.quantize 在量化之前调用它。返回
  • Self: 模块。
set_export_mode
Python
1def set_export_mode(mode: bool) -> Self:
将每个节点切换到导出模式或退出导出模式。该方法在模块的子模块(包括嵌套子模块)中的每个 BaseNode 上调用 BaseNode.set_export_mode。节点读取其导出标志以更改其输出,并且调用会重新参数化其 Reparameterizable 块。使用 False,调用会恢复这些块。参数
  • mode (bool): True 进入导出模式,False 退出导出模式。
返回
  • Self: 模块。
setup
Python
1def setup(stage: str):
当配置要求时,使第一个 epoch 验证。Lightning 在每个阶段开始时调用它。该方法仅在以下所有条件都成立时才起作用:
  • 阶段是 fit。
  • cfg.trainer.run_validation_after_first_epoch 开启。
  • 当前 epoch 为 0。
  • trainer.check_val_every_n_epoch 已设置且大于 1。
它每次运行只作用一次。Lightning 在 epoch 结束时决定是否从 trainer.check_val_every_n_epoch 运行验证。该方法存储该值并将其设置为 1,因此即使 validation_interval 会跳过它,第一个 epoch 也会验证。on_validation_epoch_end 在第一次验证后恢复存储的值,因此运行的其余部分遵循配置的间隔。参数
  • stage (str): 开始的阶段:"fit"、"validate"、"test" 或 "predict"。
test_step
Python
1def test_step(test_batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> dict[str, Tensor]:
运行测试循环的一个批次。Lightning 为测试加载器的每个批次调用它一次。该方法与 validation_step 相同,带有 test 损失累加器和 test 图像前缀。参数
  • test_batch (tuple[dict[str, Tensor] | Tensor, Labels]): 批次的加载器输入和标签。
返回
train
Python
1def train(mode: bool = True) -> Self:
设置模块和每个节点的训练模式。除了 torch.nn.Module.train 的递归之外,该方法在每个 NodeWrapper 上调用 train。包装器将模式传递给节点及其附加的损失、指标和可视化工具。参数
  • mode (bool): True 表示训练模式,False 表示评估模式。
返回
  • Self: 模块。
training_step
Python
1def training_step(train_batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> Tensor:
运行训练循环的一个批次。Lightning 为训练加载器的每个批次调用它一次,并反向传播返回的损失。参数
  • train_batch (tuple[dict[str, Tensor] | Tensor, Labels]): 批次的加载器输入和标签。
返回
validation_step
Python
1def validation_step(val_batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> dict[str, Tensor]:
运行验证循环的一个批次。Lightning 为验证加载器的每个批次调用它一次。该方法运行 full_forward,并打开损失、指标和可视化工具。它将损失值记录在验证损失累加器中。它仅在 epoch 记录的图像少于 cfg.trainer.n_log_images 时运行可视化工具。它将其图像记录到跟踪器。当标签键包含 /classification 时,它会在类之间平衡记录的图像,并为 on_validation_epoch_end 缓冲跳过的图像。否则,它会记录 epoch 的第一批图像。参数
  • val_batch (tuple[dict[str, Tensor] | Tensor, Labels]): 批次的加载器输入和标签。
返回
  • dict[str, Tensor]: CPU 上批次的损失值,总损失键为 "loss",每个损失键为 "loss/<node>/<loss>",当 cfg.trainer.log_sub_losses 开启时,每个子损失键为 "loss/<node>/<loss>/<sub>"。

属性

cfg
构建模块的配置。
core
拥有此模块的 LuxonisModel。引发
  • ValueError: 当模块在没有 _core 的情况下构建时。
dataset_metadata
数据集的元数据。当构造函数没有获得任何元数据时,它是一个空的 DatasetMetadata。
image_source
保存图像的加载器输入的名称,来自 cfg.loader.image_source。
logger
nodes
节点包装器,以节点名称为键。
outputs
输出节点的名称,来自 cfg.model.outputs。
progress_bar
附加训练器的进度条回调。LuxonisModel 注册一个 LuxonisRichProgressBar 或一个 LuxonisTQDMProgressBar,模块通过它打印评估 epoch 的结果。如果没有附加训练器,查找会引发 AttributeError。
save_dir
检查点和日志的目录。
tracker
附加训练器的记录器,作为 LuxonisTrackerPL。LuxonisModel 使用 LuxonisTrackerPL 作为其记录器创建训练器。当没有附加训练器时,该值为 None。
trainer
training_plan
configure_optimizers 构建的运行时,或 None。它包含训练计划的优化器和调度器。在第一次 configure_optimizers 调用之前,该值为 None。
training_strategy
cfg.trainer.training_strategy 命名的策略,或者当配置中没有命名时为 None。早于基于规则的 API 的策略包装在 LegacyStrategyAdapter 中。