# luxonis_lightning

Python API: `luxonis_train.lightning.luxonis_lightning`

运行节点图的 Lightning 模块。

它构建节点，按拓扑顺序运行它们，计算损失和指标，并决定在每个 epoch 记录什么。

## 类

### LuxonisLightningModule

包含整个模型的 Lightning 模块。

该模块构建配置的每个节点，并将其保存在 `nodes` 中，以及附加到每个节点的损失、指标和可视化工具。模型拓扑是一个有向无环图。`nodes.graph` 将其存储为从节点名称到馈送它的节点名称的映射。

[full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
运行图。Lightning 通过 `*_step` 方法和 `on_*`
钩子驱动训练、验证、测试和预测。[LuxonisModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
拥有该模块并将其附加到训练器。

#### 方法

##### init

```python
def __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](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/dataset_metadata.md)。
 * `_core` (`luxonis_train.core.LuxonisModel | None`): 拥有此模块的
   [LuxonisModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)。没有它，[core](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
   会引发错误。
 * `**kwargs`: `LightningModule` 构造函数的额外关键字参数。

##### compute_training_loss

```python
def compute_training_loss(train_batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> Tensor:
```

运行一个训练批次并返回其总损失。

该方法运行
[full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)，并打开损失，使用
[compute_losses](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
对它们求和，并将每个损失值记录在训练损失累加器中，[on_train_epoch_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
会记录该累加器。

参数

 * `train_batch` (`tuple[dict[str, Tensor] | Tensor, Labels]`): 批次的加载器输入和标签。

返回

 * `Tensor`: 每个损失的总和，每个损失都已按其配置 `weight` 进行缩放，形状为模块设备上的 `[1]`。

引发

 * `ValueError`: 当没有节点产生损失时。

##### configure_callbacks

```python
def configure_callbacks(self) -> list[pl.Callback]:
```

构建每次运行的回调。

Lightning 在训练器的每次 `fit`、`validate`、`test` 或 `predict` 调用开始时调用它。该方法返回 `save_dir` 的
[Nodes.build_callbacks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)，它按此顺序包含：

 * 一个
   [TrainingManager](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/training_manager.md)；
 * 一个
   [LuxonisModelSummary](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_model_summary.md)；
 * 一个 `ModelCheckpoint`，用于 `val/loss`，保存在 `save_dir / "min_val_loss"` 中；
 * 一个
   [AIMETCallback](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/aimet_callback.md)，当
   `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
def configure_optimizers(self) -> tuple[Sequence[Optimizer], Sequence[LRSchedulerTypeUnion | LRSchedulerConfig]]:
```

构建运行的优化器和调度器。

Lightning 在 fit 开始时调用它。该方法使用
[resolve_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
构建一个
[TrainingPlan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)。该计划结合了节点的微调规则、训练策略的规则以及训练器级别的优化器和调度器。该方法使用
[build_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
实例化该计划。然后它将组句柄交给训练策略和节点的冻结调度。它将运行时存储在
[training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
中，并记录参数组的摘要。

`max` 模式下的 `ReduceLROnPlateau` 调度器将主指标作为 `val/metric/<task>-<node>/<metric>`
进行监控。如果没有主指标，[build_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
会引发 `ValueError`。在任何其他模式下，调度器都会监控 `val/loss`。

返回

 * `tuple[Sequence[Optimizer], Sequence[LRSchedulerTypeUnion | LRSchedulerConfig]]`: 包含计划的一个优化器的列表，当计划有多个内部优化器时，它是一个
   [CompositeOptimizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/optimizers/composite_optimizer.md)，以及计划的调度器配置。

##### detach

```python
def detach(self):
```

将模块从其训练器中分离。

该方法将 `trainer` 设置为
`None`。之后，[tracker](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
返回
`None`，[progress_bar](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
引发 `AttributeError`。

##### export_onnx

```python
def 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
def forward(inputs: dict[str, Tensor] | Tensor) -> tuple[Tensor, ...]:
```

运行图并以扁平元组形式返回输出。

这是模块直接调用和 ONNX 导出的入口点。它运行
[full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)，不带损失、指标和可视化，并扁平化输出节点的包。

元组按节点名称排序，然后按输出键排序，然后按索引排序。列表值贡献其每个张量。单个张量值在其第一个维度的每个条目重复一次。导出使用一个批次。

参数

 * `inputs` (`dict[str, Tensor] | Tensor`): 加载器输入，以输入名称为键。裸张量是名为 `image_source` 的输入。

返回

 * `tuple[Tensor, ...]`: 输出节点的扁平化输出。

##### full_forward

```python
def 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](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
   将其结果合并为一个图像批次。

参数

 * `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
def get_mlflow_logging_keys(self) -> dict[str, list[str]]:
```

返回完整运行的指标键和工件路径。

结果预测了跟踪器在当前配置下运行所接收的内容。[LuxonisModel.tune](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
读取它以查找主指标的监控键。该方法在每个指标上调用 `compute` 以了解其子指标的名称，而无需重置。

在每个键中，`<task>-<node>` 是节点的日志名称，请参阅
[Nodes.formatted_name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)。

`"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](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/training_progress_callback.md)
   的计时键，当配置中列出时。

`"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
def 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
def 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
def 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
def on_test_epoch_end(self):
```

记录 epoch 的测试结果。

Lightning 在测试 epoch 结束时调用它。该方法与
[on_validation_epoch_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
相同，带有 `test` 前缀，不改变验证间隔。

引发

 * `RuntimeError`: 当运行使用 DDP 且指标值不在模块的设备上时。

##### on_train_epoch_end

```python
def on_train_epoch_end(self):
```

记录 epoch 的平均训练损失。

Lightning 在每个训练 epoch 结束时调用它。该方法将训练损失累加器的每个条目记录为 `train/<name>`，并带有 `sync_dist=True`。它将 `<name>` 中的节点名称替换为节点的日志名称，请参阅
[Nodes.formatted_name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)。然后它清除累加器。

##### on_train_epoch_start

```python
def on_train_epoch_start(self):
```

告诉每个节点开始的 epoch 号。

Lightning 在每个训练 epoch 开始时调用它。该方法在每个节点的模块上设置 `current_epoch`，节点及其附加模块会读取该值。

##### on_validation_epoch_end

```python
def on_validation_epoch_end(self):
```

记录 epoch 的验证结果。

Lightning 在每个验证 epoch 结束时调用它，包括健全性检查。该方法执行以下步骤：

 * 它将平均验证损失记录为 `val/<name>`，与
   [on_train_epoch_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
   对训练所做的一样。
 * 它计算每个指标。在主进程上，在健全性检查之外，它将指标的图像工件上传到跟踪器。然后它重置指标。它将标量值记录为 `val/metric/<task>-<node>/<name>`，并带有 `sync_dist=True`。2-D 值作为名为
   `val/metrics/<epoch>/<task>-<node>/<name>` 的矩阵发送到跟踪器，其中
   [BaseLuxonisProgressBar.format_matrix_for_printing](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/luxonis_progress_bar.md)
   的行标签作为其类名。`<task>-<node>` 是节点的日志名称，请参阅
   [Nodes.formatted_name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)。`<name>`
   是指标标识符，或者当 `cfg.trainer.log_sub_metrics` 开启时是子指标的名称。
 * 在主进程上，它记录损失，通过进度条打印指标，并记录主指标值。
 * 当 epoch 记录的图像少于 `cfg.trainer.n_log_images` 时，它会记录警告。然后它记录 epoch 缓冲的可视化。当计数匹配时，它会停止在运行的其余部分缓冲跳过的图像。
 * 它清除缓冲的可视化、图像计数器和损失累加器。

在 epoch 0 的验证之后，在健全性检查之外，它将
[setup](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
替换的 `trainer.check_val_every_n_epoch` 放回。

引发

 * `RuntimeError`: 当运行使用 DDP 且指标值不在模块的设备上时。

##### predict_step

```python
def predict_step(batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> LuxonisOutput:
```

运行预测循环的一个批次。

Lightning 为预测加载器的每个批次调用它一次。该方法将图像输入去归一化为 `uint8` 图像。然后它在这些图像上运行
[full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)，并打开可视化工具，关闭损失和指标。

参数

 * `batch` (`tuple[dict[str, Tensor] | Tensor, Labels]`): 批次的加载器输入和标签。

返回

 * `LuxonisOutput`: 每个输出节点的包和每个可视化工具的图像。`losses` 和 `metrics` 为空。

##### reparameterize

```python
def reparameterize(self) -> Self:
```

重新参数化模型的每个
[Reparameterizable](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/reparameterizable.md)
块。

与
[set_export_mode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
不同，该方法保持节点的导出模式不变。[set_export_mode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
与 `False`
恢复块。[LuxonisModel.quantize](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
在量化之前调用它。

返回

 * `Self`: 模块。

##### set_export_mode

```python
def set_export_mode(mode: bool) -> Self:
```

将每个节点切换到导出模式或退出导出模式。

该方法在模块的子模块（包括嵌套子模块）中的每个
[BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
上调用
[BaseNode.set_export_mode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)。节点读取其导出标志以更改其输出，并且调用会重新参数化其
[Reparameterizable](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/reparameterizable.md)
块。使用 `False`，调用会恢复这些块。

参数

 * `mode` (`bool`): `True` 进入导出模式，`False` 退出导出模式。

返回

 * `Self`: 模块。

##### setup

```python
def 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](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
在第一次验证后恢复存储的值，因此运行的其余部分遵循配置的间隔。

参数

 * `stage` (`str`): 开始的阶段：`"fit"`、`"validate"`、`"test"` 或 `"predict"`。

##### test_step

```python
def test_step(test_batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> dict[str, Tensor]:
```

运行测试循环的一个批次。

Lightning 为测试加载器的每个批次调用它一次。该方法与
[validation_step](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
相同，带有 `test` 损失累加器和 `test` 图像前缀。

参数

 * `test_batch` (`tuple[dict[str, Tensor] | Tensor, Labels]`): 批次的加载器输入和标签。

返回

 * `dict[str, Tensor]`: CPU 上批次的损失值，键如
   [validation_step](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)。

##### train

```python
def train(mode: bool = True) -> Self:
```

设置模块和每个节点的训练模式。

除了 `torch.nn.Module.train` 的递归之外，该方法在每个
[NodeWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
上调用 `train`。包装器将模式传递给节点及其附加的损失、指标和可视化工具。

参数

 * `mode` (`bool`): `True` 表示训练模式，`False` 表示评估模式。

返回

 * `Self`: 模块。

##### training_step

```python
def training_step(train_batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> Tensor:
```

运行训练循环的一个批次。

Lightning 为训练加载器的每个批次调用它一次，并反向传播返回的损失。

参数

 * `train_batch` (`tuple[dict[str, Tensor] | Tensor, Labels]`): 批次的加载器输入和标签。

返回

 * `Tensor`: 来自
   [compute_training_loss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
   的总损失。

##### validation_step

```python
def validation_step(val_batch: tuple[dict[str, Tensor] | Tensor, Labels]) -> dict[str, Tensor]:
```

运行验证循环的一个批次。

Lightning 为验证加载器的每个批次调用它一次。该方法运行
[full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)，并打开损失、指标和可视化工具。它将损失值记录在验证损失累加器中。它仅在
epoch 记录的图像少于 `cfg.trainer.n_log_images` 时运行可视化工具。它将其图像记录到跟踪器。当标签键包含 `/classification` 时，它会在类之间平衡记录的图像，并为
[on_validation_epoch_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
缓冲跳过的图像。否则，它会记录 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](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)。

引发

 * `ValueError`: 当模块在没有 `_core` 的情况下构建时。

##### dataset_metadata

数据集的元数据。当构造函数没有获得任何元数据时，它是一个空的
[DatasetMetadata](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/dataset_metadata.md)。

##### image_source

保存图像的加载器输入的名称，来自 `cfg.loader.image_source`。

##### logger

##### nodes

节点包装器，以节点名称为键。

##### outputs

输出节点的名称，来自 `cfg.model.outputs`。

##### progress_bar

附加训练器的进度条回调。

[LuxonisModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
注册一个
[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)，模块通过它打印评估
epoch 的结果。如果没有附加训练器，查找会引发 `AttributeError`。

##### save_dir

检查点和日志的目录。

##### tracker

附加训练器的记录器，作为
[LuxonisTrackerPL](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/tracker.md)。

[LuxonisModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
使用
[LuxonisTrackerPL](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/tracker.md)
作为其记录器创建训练器。当没有附加训练器时，该值为 `None`。

##### trainer

##### training_plan

[configure_optimizers](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
构建的运行时，或 `None`。

它包含训练计划的优化器和调度器。在第一次
[configure_optimizers](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
调用之前，该值为 `None`。

##### training_strategy

`cfg.trainer.training_strategy` 命名的策略，或者当配置中没有命名时为 `None`。早于基于规则的 API 的策略包装在
[LegacyStrategyAdapter](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/strategies/legacy.md)
中。
