# training_plan

Python API: `luxonis_train.lightning.training_plan`

模型参数到优化器组的划分。

该模块将节点 `finetuning` 条目、训练策略规则和节点冻结转换为一个优化器配置。它分两个阶段工作：

 1. [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)。该计划将每个节点的每个参数都精确地保存在一个参数组中，包括冻结的参数。传统训练策略的参数是唯一的例外。每个组都属于一个内部优化器及其调度器。该函数不创建计划的优化器或调度器。
 2. [build_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
    从计划创建内部优化器及其成员调度器。对于一个内部优化器，Lightning 直接接收该优化器及其调度器，因此普通配置的检查点包含一个普通的优化器状态。对于多个内部优化器，一个
    [CompositeOptimizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/optimizers/composite_optimizer.md)
    和复合调度器将它们包装起来，因此模型保持在 Lightning 的自动优化中。

分区是静态的。当节点解冻时，其参数保留在各自的组中。只有 `requires_grad` 发生变化，并且 torch 优化器会跳过梯度为 `None` 的参数。因此，从检查点恢复是一个普通的 `state_dict` 往返。

## 类

### GroupHandle

一个参数组的稳定地址。

句柄保存索引，而不是组字典。`Optimizer.load_state_dict` 在加载检查点时替换组字典。分区是静态的，因此索引保持有效。

#### 属性

##### group_index

组在
[InnerSpec.groups](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
和内部优化器的 `param_groups` 中的索引。

##### inner_index

内部优化器在
[TrainingPlan.inners](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
和
[TrainingPlanRuntime.inner_optimizers](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
中的索引。

### GroupSpec

计划的一个参数组。

#### 属性

##### name

组的名称，在整个计划中是唯一的。它是规则的标签，当
[resolve_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
为节点提供其自己的规则组时，后面跟着 `/<node>`。重复的名称会得到后缀 `-2`、`-3` 等。

##### node_names

在组中具有参数的节点的名称，按首次声明的顺序。

##### options

参数组选项，来自规则优化器的 `params`。

##### parameter_names

每个参数的名称，按 `parameters` 的顺序。名称是节点名称、一个点和节点中参数的点式名称，例如 `"backbone.stem.conv.weight"`。

##### parameters

组的参数，按声明顺序。

### InnerSpec

计划的一个内部优化器及其调度器。

#### 属性

##### groups

优化器的参数组，按创建顺序。

##### optimizer_name

优化器在 `OPTIMIZERS` 注册表中的类名。

##### scheduler

优化器的调度器。

### OptimizerSpec

一个规则的优化器。

具有相同优化器名称和相同调度器
[SchedulerSpec.key](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
的规则共享一个内部优化器。`params` 不影响该选择，因为每个组都将其作为自己的选项。

#### 方法

##### from_config

```python
def from_config(config: OptimizerConfig) -> OptimizerSpec:
```

从优化器配置创建规范。

参数

 * `config` (`OptimizerConfig`): 优化器配置。

返回

 * `OptimizerSpec`: `config` 的名称及其 `params` 的浅拷贝。

引发

 * `KeyError`: 当 `OPTIMIZERS` 注册表中没有与 `config` 名称相同的优化器时。

#### 属性

##### name

优化器在 `OPTIMIZERS` 注册表中的类名。

##### params

优化器参数，例如 `lr`。规则的每个参数组都将其作为选项接收。

### Rule

将参数声明到计划组中的规则。

[resolve_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
为每个节点 `finetuning` 条目创建一个规则，为每个
[StrategyRule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)
创建一个规则，并创建一个默认规则来声明所有剩余的参数。

#### 属性

##### label

规则组的基本名称：`finetuning` 条目的 `<node>/<index>`，策略规则的 `strategy/<tag>`，以及默认规则的 `default`。

##### optimizer

声明参数的优化器。

##### scheduler

声明参数的调度器。

##### selector

决定规则声明哪些参数的谓词。

##### tag

策略规则的标签，其他规则为 `None`。

### SchedulerSpec

一个规则的调度器。

#### 方法

##### from_config

```python
def from_config(config: SchedulerConfig, total_epochs: int) -> SchedulerSpec:
```

从调度器配置创建规范。

对于 `CosineAnnealingLR`，当 `params` 没有 `T_max` 时，该方法将 `T_max` 设置为 `total_epochs`，并记录警告。当 `T_max` 不等于 `total_epochs` 时，它也会记录警告。该方法在计算
`key` 之前添加默认值。因此，省略 `T_max` 的规则和将其设置为 `total_epochs` 的规则会得到相同的 `key`。

> **示例**
> ```pycon
>>> from luxonis_train.config.config import SchedulerConfig
>>> step = SchedulerConfig(
...     name="StepLR", params={"step_size": 5, "gamma": 0.5}
... )
>>> SchedulerSpec.from_config(step, total_epochs=10).key
'{"name": "StepLR", "params": {"gamma": 0.5, "step_size": 5}}'
```

参数

 * `config` (`SchedulerConfig`): 调度器配置。
 * `total_epochs` (`int`): 训练 epoch 的数量，来自 `trainer.epochs`。

返回

 * `SchedulerSpec`: `config` 的名称，其 `params` 的浅拷贝（如果方法添加了 `T_max` 默认值），以及 `key`。

引发

 * `KeyError`: 当 `SCHEDULERS` 注册表中没有与 `config` 名称相同的调度器时。

#### 属性

##### key

`name` 和 `params` 的 JSON 字符串，键已排序。JSON 无法编码的值将以其 `repr` 形式放入字符串中。具有相同优化器名称和相同 `key` 的规则共享一个内部优化器。数据类的相等性检查会忽略此字段。

##### name

调度器在 `SCHEDULERS` 注册表中的类名。

##### params

调度器参数。当 `CosineAnnealingLR` 配置没有 `T_max` 时，[SchedulerSpec.from_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 会添加 `T_max`。

### Selector

决定规则是否声明参数的谓词。

[pattern_selector](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 从节点 `finetuning` 条目的 `parameters` 模式构建一个选择器。训练策略在每个 [StrategyRule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 中提供自己的选择器。选择器只查看没有早期规则声明的参数。

### StrategyRule

训练策略贡献的参数组规则。

[BaseTrainingStrategy.rules](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/strategies/base_strategy.md) 返回这些规则。[resolve_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 在所有节点的 `finetuning` 条目之后和默认规则之前按顺序评估它们。一个规则在下一个规则开始之前访问每个节点。它声明其 `selector` 接受且没有早期规则声明的每个参数。

规则的组命名为 `strategy/<tag>`。具有 `freezing.active` 的节点会获得其自己的组 `strategy/<tag>/<node>`。

#### 属性

##### optimizer

声明参数的优化器。计划按原样使用它，不将其与基本优化器合并。

##### scheduler

声明参数的调度器。`None` 使用策略的基本调度器，或者当 [BaseTrainingStrategy.get_base_configs](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/strategies/base_strategy.md) 引发 `NotImplementedError` 时使用 `trainer.scheduler`。

##### selector

决定规则声明哪些参数的谓词。

##### tag

规则的名称。[BaseTrainingStrategy.attach](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/strategies/base_strategy.md) 在此键下接收规则组的句柄。当规则未声明任何参数时，映射中没有该标签的条目。

### TrainingPlan

模型参数到组的静态划分。

[resolve_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 将每个节点的每个参数放入一个组中，包括冻结的参数。唯一的例外是传统训练策略为其自己的优化器声明的参数。

#### 属性

##### handles_by_node

对于每个节点名称，保存节点参数的组的句柄，按计划顺序。计划中没有参数的节点没有条目。

##### handles_by_tag

对于每个策略规则标签，规则组的句柄，按计划顺序。其规则未声明任何参数的标签没有条目。

##### inners

内部优化器的规范，按创建顺序。

### TrainingPlanRuntime

[build_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 创建的优化器和调度器。

运行时还通过其 [GroupHandle](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 访问参数组。冻结计划和训练策略使用此访问来更改其组的选项，例如学习率。

#### 方法

##### group

```python
def group(handle: GroupHandle) -> dict[str, Any]:
```

返回句柄处的参数组。

参数

 * `handle` (`GroupHandle`): 组的地址。

返回

 * `dict[str, Any]`: 内部优化器中 `param_groups` 的条目。它不是副本，因此对其的更改会更改优化器。

##### handles_for_node

```python
def handles_for_node(node_name: str) -> tuple[GroupHandle, ...]:
```

返回节点组的句柄。

参数

 * `node_name` (`str`): 节点的名称。

返回

 * `tuple[GroupHandle, ...]`: 保存节点参数的组的句柄，按计划顺序。当没有组保存 `node_name` 的参数时，元组为空。

##### set_group_base_lr

```python
def set_group_base_lr(handle: GroupHandle, lr: float):
```

为单个参数组设置新的基本学习率。

该方法设置组的 `lr` 和 `initial_lr`。它还在成员调度器的 `base_lrs` 中设置组的条目。对于 `SequentialLR` 或 `ChainedScheduler`，它在每个子调度器中设置条目。因此，下一个调度器步骤将从新速率开始。该方法跳过没有 `base_lrs` 的调度器，例如 `ReduceLROnPlateau`。当内部优化器没有调度器时，只有组会改变。

参数

 * `handle` (`GroupHandle`): 组的地址。
 * `lr` (`float`): 新的基本学习率。

#### 属性

##### inner_optimizers

计划的每个 [InnerSpec](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 的一个优化器，按计划顺序。传统训练策略的优化器紧随其后。

##### members

每个内部优化器的调度器，按相同顺序。对于没有调度器的传统优化器，条目为 `None`。

##### optimizer

Lightning 接收的优化器。它是唯一的内部优化器，或者是所有内部优化器的 [CompositeOptimizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/optimizers/composite_optimizer.md)。

##### plan

运行时的计划。

##### scheduler_configs

Lightning 接收的调度器和调度器配置。[build_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 描述了这些条目。

## 函数

### build_training_plan

```python
def build_training_plan(plan: TrainingPlan, cfg: Config, main_metric_monitor: str | None, strategy: BaseTrainingStrategy | None =
None) -> TrainingPlanRuntime:
```

创建计划的优化器和调度器。

对于计划的每个内部优化器，该函数从 `OPTIMIZERS` 注册表创建优化器。计划的每个组都成为一个带有组选项的参数组。当计划有多个组时，每个参数组也会获得其组的 `name`。然后，每个组的 `LearningRateMonitor` 键以组名而不是 `pg1`、`pg2` 等结尾。

对于这些优化器中的每一个，该函数还从 `SCHEDULERS` 注册表创建成员调度器。`SequentialLR` 是例外：该函数直接从 torch 创建它。它的 `params` 提供 `milestones`、`last_epoch` 和子调度器，这些都来自注册表。`ReduceLROnPlateau` 在 `max` 模式下监控 `main_metric_monitor`，在任何其他模式下监控 `val/loss`。

[BaseTrainingStrategy.opaque_inners](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/strategies/base_strategy.md) 的优化器紧随计划的优化器。只有传统策略才返回此类优化器。

总共只有一个优化器时，Lightning 接收该优化器及其调度器：

 * `ReduceLROnPlateau` 进入一个字典，键为 `scheduler`、`monitor` 和 `frequency`。
 * 另一个调度器按原样传递。
 * 传统策略的调度器或配置按原样传递。没有调度器的传统优化器不提供调度器条目。

有多个优化器时，一个 [CompositeOptimizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/optimizers/composite_optimizer.md) 将它们包装起来。然后 Lightning 接收这些调度器配置：

 * 一个 [CompositeLRScheduler](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/schedulers/composite_scheduler.md)，命名为 `lr`，它步进所有没有监控器的调度器。它仅在至少一个调度器没有监控器时才存在。
 * 每个监控器一个 [CompositeReduceLROnPlateau](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/schedulers/composite_scheduler.md)，带有 `monitor`、`frequency` 和 `reduce_on_plateau` 键。配置命名为 `lr-plateau`、`lr-plateau-1` 等。

在这种情况下，该函数只读取传统调度器配置的 `scheduler` 和 `monitor` 键。带有 `monitor` 的传统调度器必须是 `ReduceLROnPlateau`。

当多个优化器中的一个是 `LBFGS` 优化器时，[CompositeOptimizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/optimizers/composite_optimizer.md) 会引发 `ValueError`。当计划和策略没有提供优化器时，它也会引发 `ValueError`。

上述每个 `frequency` 都是 `trainer.validation_interval`。

参数

 * `plan` (`TrainingPlan`): 来自 [resolve_training_plan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 的计划。
 * `cfg` (`Config`): 配置。该函数读取 `trainer.validation_interval`。
 * `main_metric_monitor` (`str | None`): 主指标的日志名称，如果模型没有主指标则为 `None`。
 * `strategy` (`BaseTrainingStrategy | None`): 训练策略，或 `None`。该函数读取其 [BaseTrainingStrategy.opaque_inners](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/strategies/base_strategy.md)。

返回

 * `TrainingPlanRuntime`: 优化器、调度器和 Lightning 的调度器配置。

引发

 * `TypeError`: 当组选项不是其优化器 `defaults` 的键时。
 * `ValueError`: 当 `max` 模式下的 `ReduceLROnPlateau` 没有 `main_metric_monitor` 时。

### merge_config_items

```python
def merge_config_items(base: OptimizerConfig | SchedulerConfig, override: FinetuningOptimizerConfig | FinetuningSchedulerConfig |
None) -> OptimizerConfig | SchedulerConfig:
```

将微调覆盖合并到基本优化器或调度器中。

合并遵循以下规则：

 * 如果没有覆盖，结果是 `base` 的副本。
 * 如果覆盖没有 `name`，或者 `name` 与 `base` 相同，则保留 `base` 的名称。结果具有 `base` 的 `params`，并用覆盖的 `params` 更新。
 * 如果覆盖具有不同的 `name`，则替换 `base`。结果只具有覆盖的 `params`。

> **示例**
> ```pycon
>>> from luxonis_train.config.config import (
...     FinetuningOptimizerConfig,
...     OptimizerConfig,
... )
>>> base = OptimizerConfig(
...     name="SGD", params={"lr": 0.01, "momentum": 0.9}
... )
>>> lower_lr = FinetuningOptimizerConfig(params={"lr": 0.001})
>>> merge_config_items(base, lower_lr)
OptimizerConfig(name='SGD', params={'lr': 0.001, 'momentum': 0.9})
>>> adam = FinetuningOptimizerConfig(name="Adam", params={"lr": 0.001})
>>> merge_config_items(base, adam)
OptimizerConfig(name='Adam', params={'lr': 0.001})
```

参数

 * `base` (`OptimizerConfig | SchedulerConfig`): 基本配置：`trainer.optimizer`、`trainer.scheduler` 或训练策略的基本配置。
 * `override` (`FinetuningOptimizerConfig | FinetuningSchedulerConfig | None`): 节点 `finetuning` 条目的覆盖，或 `None`。

返回

 * `OptimizerConfig | SchedulerConfig`: `base` 类型的新配置，因此其 `name` 永远不是 `None`。参数不会改变。

### pattern_selector

```python
def pattern_selector(patterns: Sequence[ParameterPattern]) -> Selector:
```

从 `finetuning` 条目的模式构建一个
[Selector](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)。

选择器将 `module_name` 和 `parameter_name` 连接成点式参数名称，例如 `"stem.conv.weight"`。当 `module_name` 为空时，点式名称仅为
`parameter_name`。当至少一个模式匹配时，选择器接受该参数。当其 `name` 匹配点式名称且其 `module_type` 匹配 `module` 的类名时，模式匹配。留作 `None`
的字段匹配所有内容。两个字段都是正则表达式。`re.search` 在没有锚点和不区分大小写的情况下匹配它们，如
[ParameterPattern](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md)
所述。

> **示例**
> ```pycon
>>> from torch import nn
>>> from luxonis_train.config.config import ParameterPattern
>>> linear = nn.Linear(2, 2)
>>> select = pattern_selector([ParameterPattern(name="head.weight")])
>>> select(linear, "head", linear.weight, "weight")
True
>>> select(linear, "head", linear.bias, "bias")
False
```

参数

 * `patterns` (`Sequence[ParameterPattern]`): 模式。空序列会生成一个不接受任何参数的选择器。

返回

 * `Selector`: 一个函数，带有 [Selector.call](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 的参数。当模式匹配参数时，它返回 `True`。

### resolve_training_plan

```python
def resolve_training_plan(cfg: Config, nodes: Nodes, strategy: BaseTrainingStrategy | None = None) -> TrainingPlan:
```

将模型的参数规则解析为 [TrainingPlan](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md)。

该函数结合了节点 `finetuning` 条目、训练策略规则、节点冻结以及基本优化器和调度器。它不创建计划的优化器或调度器。

第一个接受参数的规则声明它。规则按以下顺序声明：

 1. 节点的 `finetuning` 条目，按配置顺序。一个条目只声明其自身节点的参数。没有 `parameters` 的条目声明节点的所有空闲参数。其优化器和调度器覆盖通过 [merge_config_items](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 合并到基本配置中。
 2. `strategy` 的规则，按顺序。每个规则在下一个规则开始之前访问每个节点。传统策略在这些规则之前声明其自己的参数。这些参数保留在计划之外。
 3. 默认规则。它声明所有剩余的参数，使用基本优化器和调度器。

如果没有策略，默认规则在每个节点的 `finetuning` 条目之后直接运行。如果有策略，所有节点的条目首先运行，然后是策略规则，然后是默认规则。该函数按 `nodes` 的顺序访问节点，按模块顺序访问参数，因此结果是确定性的。规则也声明冻结的参数，因此解冻的节点已经有一个优化器。

组获得以下名称：

 * `finetuning` 条目的 `<node>/<index>`。`<index>` 是条目在节点 `finetuning` 列表中的位置，从 `0` 开始。
 * 策略规则的 `strategy/<tag>`，由所有节点共享。
 * 默认规则的 `default`，由所有节点共享。
 * 具有 `freezing.active` 的节点会获得其自己的策略和默认组，`strategy/<tag>/<node>` 和 `default/<node>`。因此，节点的 `lr_after_unfreeze` 速率不会改变另一个节点的任何组。
 * 如果没有策略，当任何节点具有 `finetuning` 条目时，每个节点都会获得其自己的默认组 `default/<node>`。

具有相同优化器名称和相同 [SchedulerSpec.key](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 的规则共享一个内部优化器。

基本优化器和调度器是 `trainer.optimizer` 和 `trainer.scheduler`。如果有策略，它们来自 [BaseTrainingStrategy.get_base_configs](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/strategies/base_strategy.md)，除非该方法引发 `NotImplementedError`。

[SchedulerSpec.from_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/training_plan.md) 会为每个 `CosineAnnealingLR` 规则记录警告，如果其 `T_max` 缺失或与 `trainer.epochs` 不同。

参数

 * `cfg` (`Config`): 配置。该函数读取 `trainer.epochs`、`trainer.optimizer` 和 `trainer.scheduler`。
 * `nodes` (`Nodes`): 模型的节点。该函数读取每个 [NodeWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md) 的 `name`、`module`、`finetuning` 和 `unfreeze_after`。
 * `strategy` (`BaseTrainingStrategy | None`): 训练策略，或 `None`。

返回

 * `TrainingPlan`: 计划。

引发

 * `ValueError`: 当 `finetuning` 条目未声明任何参数时，例如因为早期条目声明了其所有匹配项。当传统策略声明了 `finetuning` 条目声明的参数时。
 * `KeyError`: 当优化器或调度器名称不在其注册表中时。
