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

本页目录

  • 类
  • GroupHandle
  • GroupSpec
  • InnerSpec
  • OptimizerSpec
  • Rule
  • SchedulerSpec
  • Selector
  • StrategyRule
  • TrainingPlan
  • TrainingPlanRuntime
  • 函数
  • build_training_plan
  • merge_config_items
  • pattern_selector
  • resolve_training_plan
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

training_plan

最后更新
Python API: luxonis_train.lightning.training_plan模型参数到优化器组的划分。该模块将节点 finetuning 条目、训练策略规则和节点冻结转换为一个优化器配置。它分两个阶段工作:
  1. resolve_training_plan 从配置和节点构建一个 TrainingPlan。该计划将每个节点的每个参数都精确地保存在一个参数组中,包括冻结的参数。传统训练策略的参数是唯一的例外。每个组都属于一个内部优化器及其调度器。该函数不创建计划的优化器或调度器。
  2. build_training_plan 从计划创建内部优化器及其成员调度器。对于一个内部优化器,Lightning 直接接收该优化器及其调度器,因此普通配置的检查点包含一个普通的优化器状态。对于多个内部优化器,一个 CompositeOptimizer 和复合调度器将它们包装起来,因此模型保持在 Lightning 的自动优化中。
分区是静态的。当节点解冻时,其参数保留在各自的组中。只有 requires_grad 发生变化,并且 torch 优化器会跳过梯度为 None 的参数。因此,从检查点恢复是一个普通的 state_dict 往返。

类

GroupHandle

一个参数组的稳定地址。句柄保存索引,而不是组字典。Optimizer.load_state_dict 在加载检查点时替换组字典。分区是静态的,因此索引保持有效。

属性

group_index
组在 InnerSpec.groups 和内部优化器的 param_groups 中的索引。
inner_index
内部优化器在 TrainingPlan.inners 和 TrainingPlanRuntime.inner_optimizers 中的索引。

GroupSpec

计划的一个参数组。

属性

name
组的名称,在整个计划中是唯一的。它是规则的标签,当 resolve_training_plan 为节点提供其自己的规则组时,后面跟着 /<node>。重复的名称会得到后缀 -2、-3 等。
node_names
在组中具有参数的节点的名称,按首次声明的顺序。
options
参数组选项,来自规则优化器的 params。
parameter_names
每个参数的名称,按 parameters 的顺序。名称是节点名称、一个点和节点中参数的点式名称,例如 "backbone.stem.conv.weight"。
parameters
组的参数,按声明顺序。

InnerSpec

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

属性

groups
优化器的参数组,按创建顺序。
optimizer_name
优化器在 OPTIMIZERS 注册表中的类名。
scheduler
优化器的调度器。

OptimizerSpec

一个规则的优化器。具有相同优化器名称和相同调度器 SchedulerSpec.key 的规则共享一个内部优化器。params 不影响该选择,因为每个组都将其作为自己的选项。

方法

from_config
Python
1def from_config(config: OptimizerConfig) -> OptimizerSpec:
从优化器配置创建规范。参数
  • config (OptimizerConfig): 优化器配置。
返回
  • OptimizerSpec: config 的名称及其 params 的浅拷贝。
引发
  • KeyError: 当 OPTIMIZERS 注册表中没有与 config 名称相同的优化器时。

属性

name
优化器在 OPTIMIZERS 注册表中的类名。
params
优化器参数,例如 lr。规则的每个参数组都将其作为选项接收。

Rule

将参数声明到计划组中的规则。resolve_training_plan 为每个节点 finetuning 条目创建一个规则,为每个 StrategyRule 创建一个规则,并创建一个默认规则来声明所有剩余的参数。

属性

label
规则组的基本名称:finetuning 条目的 <node>/<index>,策略规则的 strategy/<tag>,以及默认规则的 default。
optimizer
声明参数的优化器。
scheduler
声明参数的调度器。
selector
决定规则声明哪些参数的谓词。
tag
策略规则的标签,其他规则为 None。

SchedulerSpec

一个规则的调度器。

方法

from_config
Python
1def 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。参数
  • 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 会添加 T_max。

Selector

决定规则是否声明参数的谓词。pattern_selector 从节点 finetuning 条目的 parameters 模式构建一个选择器。训练策略在每个 StrategyRule 中提供自己的选择器。选择器只查看没有早期规则声明的参数。

StrategyRule

训练策略贡献的参数组规则。BaseTrainingStrategy.rules 返回这些规则。resolve_training_plan 在所有节点的 finetuning 条目之后和默认规则之前按顺序评估它们。一个规则在下一个规则开始之前访问每个节点。它声明其 selector 接受且没有早期规则声明的每个参数。规则的组命名为 strategy/<tag>。具有 freezing.active 的节点会获得其自己的组 strategy/<tag>/<node>。

属性

optimizer
声明参数的优化器。计划按原样使用它,不将其与基本优化器合并。
scheduler
声明参数的调度器。None 使用策略的基本调度器,或者当 BaseTrainingStrategy.get_base_configs 引发 NotImplementedError 时使用 trainer.scheduler。
selector
决定规则声明哪些参数的谓词。
tag
规则的名称。BaseTrainingStrategy.attach 在此键下接收规则组的句柄。当规则未声明任何参数时,映射中没有该标签的条目。

TrainingPlan

模型参数到组的静态划分。resolve_training_plan 将每个节点的每个参数放入一个组中,包括冻结的参数。唯一的例外是传统训练策略为其自己的优化器声明的参数。

属性

handles_by_node
对于每个节点名称,保存节点参数的组的句柄,按计划顺序。计划中没有参数的节点没有条目。
handles_by_tag
对于每个策略规则标签,规则组的句柄,按计划顺序。其规则未声明任何参数的标签没有条目。
inners
内部优化器的规范,按创建顺序。

TrainingPlanRuntime

build_training_plan 创建的优化器和调度器。运行时还通过其 GroupHandle 访问参数组。冻结计划和训练策略使用此访问来更改其组的选项,例如学习率。

方法

group
Python
1def group(handle: GroupHandle) -> dict[str, Any]:
返回句柄处的参数组。参数
  • handle (GroupHandle): 组的地址。
返回
  • dict[str, Any]: 内部优化器中 param_groups 的条目。它不是副本,因此对其的更改会更改优化器。
handles_for_node
Python
1def handles_for_node(node_name: str) -> tuple[GroupHandle, ...]:
返回节点组的句柄。参数
  • node_name (str): 节点的名称。
返回
  • tuple[GroupHandle, ...]: 保存节点参数的组的句柄,按计划顺序。当没有组保存 node_name 的参数时,元组为空。
set_group_base_lr
Python
1def 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 的一个优化器,按计划顺序。传统训练策略的优化器紧随其后。
members
每个内部优化器的调度器,按相同顺序。对于没有调度器的传统优化器,条目为 None。
optimizer
Lightning 接收的优化器。它是唯一的内部优化器,或者是所有内部优化器的 CompositeOptimizer。
plan
运行时的计划。
scheduler_configs
Lightning 接收的调度器和调度器配置。build_training_plan 描述了这些条目。

函数

build_training_plan

Python
1def 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 的优化器紧随计划的优化器。只有传统策略才返回此类优化器。总共只有一个优化器时,Lightning 接收该优化器及其调度器:
  • ReduceLROnPlateau 进入一个字典,键为 scheduler、monitor 和 frequency。
  • 另一个调度器按原样传递。
  • 传统策略的调度器或配置按原样传递。没有调度器的传统优化器不提供调度器条目。
有多个优化器时,一个 CompositeOptimizer 将它们包装起来。然后 Lightning 接收这些调度器配置:
  • 一个 CompositeLRScheduler,命名为 lr,它步进所有没有监控器的调度器。它仅在至少一个调度器没有监控器时才存在。
  • 每个监控器一个 CompositeReduceLROnPlateau,带有 monitor、frequency 和 reduce_on_plateau 键。配置命名为 lr-plateau、lr-plateau-1 等。
在这种情况下,该函数只读取传统调度器配置的 scheduler 和 monitor 键。带有 monitor 的传统调度器必须是 ReduceLROnPlateau。当多个优化器中的一个是 LBFGS 优化器时,CompositeOptimizer 会引发 ValueError。当计划和策略没有提供优化器时,它也会引发 ValueError。上述每个 frequency 都是 trainer.validation_interval。参数
  • plan (TrainingPlan): 来自 resolve_training_plan 的计划。
  • cfg (Config): 配置。该函数读取 trainer.validation_interval。
  • main_metric_monitor (str | None): 主指标的日志名称,如果模型没有主指标则为 None。
  • strategy (BaseTrainingStrategy | None): 训练策略,或 None。该函数读取其 BaseTrainingStrategy.opaque_inners。
返回
  • TrainingPlanRuntime: 优化器、调度器和 Lightning 的调度器配置。
引发
  • TypeError: 当组选项不是其优化器 defaults 的键时。
  • ValueError: 当 max 模式下的 ReduceLROnPlateau 没有 main_metric_monitor 时。

merge_config_items

Python
1def merge_config_items(base: OptimizerConfig | SchedulerConfig, override: FinetuningOptimizerConfig | FinetuningSchedulerConfig | None) -> OptimizerConfig | SchedulerConfig:
将微调覆盖合并到基本优化器或调度器中。合并遵循以下规则:
  • 如果没有覆盖,结果是 base 的副本。
  • 如果覆盖没有 name,或者 name 与 base 相同,则保留 base 的名称。结果具有 base 的 params,并用覆盖的 params 更新。
  • 如果覆盖具有不同的 name,则替换 base。结果只具有覆盖的 params。
参数
  • base (OptimizerConfig | SchedulerConfig): 基本配置:trainer.optimizer、trainer.scheduler 或训练策略的基本配置。
  • override (FinetuningOptimizerConfig | FinetuningSchedulerConfig | None): 节点 finetuning 条目的覆盖,或 None。
返回
  • OptimizerConfig | SchedulerConfig: base 类型的新配置,因此其 name 永远不是 None。参数不会改变。

pattern_selector

Python
1def pattern_selector(patterns: Sequence[ParameterPattern]) -> Selector:
从 finetuning 条目的模式构建一个 Selector。选择器将 module_name 和 parameter_name 连接成点式参数名称,例如 "stem.conv.weight"。当 module_name 为空时,点式名称仅为 parameter_name。当至少一个模式匹配时,选择器接受该参数。当其 name 匹配点式名称且其 module_type 匹配 module 的类名时,模式匹配。留作 None 的字段匹配所有内容。两个字段都是正则表达式。re.search 在没有锚点和不区分大小写的情况下匹配它们,如 ParameterPattern 所述。参数
  • patterns (Sequence[ParameterPattern]): 模式。空序列会生成一个不接受任何参数的选择器。
返回
  • Selector: 一个函数,带有 Selector.call 的参数。当模式匹配参数时,它返回 True。

resolve_training_plan

Python
1def resolve_training_plan(cfg: Config, nodes: Nodes, strategy: BaseTrainingStrategy | None = None) -> TrainingPlan:
将模型的参数规则解析为 TrainingPlan。该函数结合了节点 finetuning 条目、训练策略规则、节点冻结以及基本优化器和调度器。它不创建计划的优化器或调度器。第一个接受参数的规则声明它。规则按以下顺序声明:
  1. 节点的 finetuning 条目,按配置顺序。一个条目只声明其自身节点的参数。没有 parameters 的条目声明节点的所有空闲参数。其优化器和调度器覆盖通过 merge_config_items 合并到基本配置中。
  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 的规则共享一个内部优化器。基本优化器和调度器是 trainer.optimizer 和 trainer.scheduler。如果有策略,它们来自 BaseTrainingStrategy.get_base_configs,除非该方法引发 NotImplementedError。SchedulerSpec.from_config 会为每个 CosineAnnealingLR 规则记录警告,如果其 T_max 缺失或与 trainer.epochs 不同。参数
  • cfg (Config): 配置。该函数读取 trainer.epochs、trainer.optimizer 和 trainer.scheduler。
  • nodes (Nodes): 模型的节点。该函数读取每个 NodeWrapper 的 name、module、finetuning 和 unfreeze_after。
  • strategy (BaseTrainingStrategy | None): 训练策略,或 None。
返回
  • TrainingPlan: 计划。
引发
  • ValueError: 当 finetuning 条目未声明任何参数时,例如因为早期条目声明了其所有匹配项。当传统策略声明了 finetuning 条目声明的参数时。
  • KeyError: 当优化器或调度器名称不在其注册表中时。