luxonis_lightning
最后更新
luxonis_train.lightning.luxonis_lightning运行节点图的 Lightning 模块。它构建节点,按拓扑顺序运行它们,计算损失和指标,并决定在每个 epoch 记录什么。类
LuxonisLightningModule
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:train_batch(tuple[dict[str, Tensor] | Tensor, Labels]): 批次的加载器输入和标签。
Tensor: 每个损失的总和,每个损失都已按其配置weight进行缩放,形状为模块设备上的[1]。
ValueError: 当没有节点产生损失时。
configure_callbacks
Python
1def configure_callbacks(self) -> list[pl.Callback]: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]]: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:[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, ...]: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]]: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,在 epochcfg.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: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]):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):test 前缀,不改变验证间隔。引发RuntimeError: 当运行使用 DDP 且指标值不在模块的设备上时。
on_train_epoch_end
Python
1def on_train_epoch_end(self):train/<name>,并带有 sync_dist=True。它将 <name> 中的节点名称替换为节点的日志名称,请参阅 Nodes.formatted_name。然后它清除累加器。on_train_epoch_start
Python
1def on_train_epoch_start(self):current_epoch,节点及其附加模块会读取该值。on_validation_epoch_end
Python
1def on_validation_epoch_end(self):- 它将平均验证损失记录为
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 缓冲的可视化。当计数匹配时,它会停止在运行的其余部分缓冲跳过的图像。 - 它清除缓冲的可视化、图像计数器和损失累加器。
trainer.check_val_every_n_epoch 放回。引发RuntimeError: 当运行使用 DDP 且指标值不在模块的设备上时。
predict_step
Python
1def predict_step(batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> LuxonisOutput:uint8 图像。然后它在这些图像上运行 full_forward,并打开可视化工具,关闭损失和指标。参数batch(tuple[dict[str, Tensor] | Tensor, Labels]): 批次的加载器输入和标签。
LuxonisOutput: 每个输出节点的包和每个可视化工具的图像。losses和metrics为空。
reparameterize
Python
1def reparameterize(self) -> Self:False 恢复块。LuxonisModel.quantize 在量化之前调用它。返回Self: 模块。
set_export_mode
Python
1def set_export_mode(mode: bool) -> Self:False,调用会恢复这些块。参数mode(bool):True进入导出模式,False退出导出模式。
Self: 模块。
setup
Python
1def setup(stage: str):- 阶段是
fit。 cfg.trainer.run_validation_after_first_epoch开启。- 当前 epoch 为 0。
trainer.check_val_every_n_epoch已设置且大于 1。
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]:test 损失累加器和 test 图像前缀。参数test_batch(tuple[dict[str, Tensor] | Tensor, Labels]): 批次的加载器输入和标签。
dict[str, Tensor]: CPU 上批次的损失值,键如 validation_step。
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:train_batch(tuple[dict[str, Tensor] | Tensor, Labels]): 批次的加载器输入和标签。
Tensor: 来自 compute_training_loss 的总损失。
validation_step
Python
1def validation_step(val_batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> dict[str, Tensor]: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
ValueError: 当模块在没有_core的情况下构建时。
dataset_metadata
image_source
cfg.loader.image_source。logger
nodes
outputs
cfg.model.outputs。progress_bar
AttributeError。save_dir
tracker
None。trainer
training_plan
None。它包含训练计划的优化器和调度器。在第一次 configure_optimizers 调用之前,该值为 None。training_strategy
cfg.trainer.training_strategy 命名的策略,或者当配置中没有命名时为 None。早于基于规则的 API 的策略包装在 LegacyStrategyAdapter 中。