utils
最后更新
luxonis_train.lightning.utilsLightning 模块背后的辅助函数。Nodes 从配置构建节点图,并将每个节点包装在 NodeWrapper 中,同时包含其损失、指标和可视化工具。LossAccumulator 保持每个损失在一个 epoch 中的运行平均值。这些函数汇总损失,构建训练策略,展平指标结果,并将指标工件和可视化记录到跟踪器。类
LossAccumulator
"train"、"val" 和 "test" 阶段各保留一个累加器。它在每个步骤后调用 update,并在 epoch 结束时调用 clear。从未收到 update 的键读取为 0.0。示例
Pycon
1>>> import torch
2>>> losses = LossAccumulator()
3>>> losses.update({"loss": torch.tensor(2.0)})
4>>> losses.update({"loss": torch.tensor(4.0)})
5>>> losses["loss"]
63.0
7>>> losses.clear()
8>>> dict(losses)
9{}方法
init
Python
1def __init__(*args, **kwargs):clear
Python
1def clear(self):update
Python
1def update(losses: dict[str, Tensor]):dict.update。一个值不会覆盖存储的值。它会移动平均值。参数losses(dict[str, Tensor]): 损失名称映射到单元素张量,如 compute_losses 返回的第二个值。
MainMetric
属性
metric_name
"ConfusionMatrix" 的指标将获得标识符 "mcc"。node_name
Nodes
torch.nn.ModuleDict,将每个节点标识符映射到其 NodeWrapper。构造函数按拓扑顺序构建节点。它在零张量上运行每个节点,因此后续节点知道其输入的形状。方法
init
Python
1def __init__(cfg: Config, dataset_metadata: DatasetMetadata, input_shapes: dict[str, Size]):cfg(Config): 配置。model.nodes列出节点,loader.image_source命名图像输入,trainer.epochs解析分数或缺失的freezing.unfreeze_after。dataset_metadata(DatasetMetadata): 数据集的元数据。它修复未设置任务名称的节点的任务名称,并验证元数据标签类型。它还会到达每个节点构造函数。input_shapes(dict[str, Size]): 每个加载器输入名称映射到其形状,不带批处理维度。
RuntimeError: 当节点未设置task_name且数据集不包含任务时。当节点列出没有节点生成的输入时,或者当图存在循环时。ValueError: 当头未设置task_name且数据集包含多个任务时。当input_sources条目不是加载器输入时。当metadata_task_override是字符串但任务不需要恰好一个元数据标签时。当元数据标签的类型不被任务接受时。该检查从配置条目读取task_name,因此仅在设置了任务名称的节点上运行。
build_callbacks
Python
1def build_callbacks(save_dir: Path) -> list[pl.Callback]:- TrainingManager,它应用冻结计划并在每次反向传播后调用训练策略。
- LuxonisModelSummary,深度为 2,当
rich_logging为 true 时作为富表格。 - 一个
ModelCheckpoint,它监控val/loss,保留最低值,并写入save_dir / "min_val_loss"。 - AIMETCallback,当
exporter.aimet.active设置时。 - 一个
ModelCheckpoint,它监控主指标的val/metric/<node>/<metric>,当配置定义一个时。<node>是 formatted_name 中的日志名称。检查点保留最高值,并写入save_dir / "best_val_metric"。 trainer.callbacks的每个活动回调,从 CALLBACKS 注册表构建。该函数记录并跳过不活动的。- 一个
GradientAccumulationScheduler用于trainer.accumulate_grad_batches,当配置设置该值且上述回调不包含此类调度器时。当它们包含时,该函数记录警告并忽略配置值。
trainer.save_top_k 文件。参数save_dir(Path): 接收检查点子目录的目录。
list[pl.Callback]: 回调,按上述顺序。
formatted_name
Python
1def formatted_name(node_name: str) -> str:node_name(str): 节点的标识符。
str: 当节点有任务名称时为"<task_name>-<node_name>",否则仅为node_name。
traverse
Python
1def traverse(self) -> Iterator[tuple[str, NodeWrapper, list[str], list[str]]]:- 节点标识符、其包装器、馈送它的节点标识符以及尚未生成的节点标识符。
RuntimeError: 当遍历没有进展时。此时节点列出了图中没有节点生成的输入,或者图存在循环。
属性
freeze_schedule
freezing.active 的节点的冻结计划。graph
loader_input_shapes
main_metric
None。main_metric_reference
main_metric 命名的指标实例。引发RuntimeError: 当配置未定义主指标时。
NodeWrapper
module 是一个注册的子模块。损失、指标和可视化工具存储在普通字典中,因此 torch.nn.Module 的递归方法无法访问它们。方法
init
Python
1def __init__(name: str, module: BaseNode, losses: dict[str, BaseLoss], metrics: dict[str, BaseMetric], visualizers: dict[str, BaseVisualizer], unfreeze_after: int | None, lr_after_unfreeze: float | None, finetuning: list[FinetuningConfig], inputs: list[str] | None = None):name(str): 图中节点的标识符。module(BaseNode): 节点。losses(dict[str, BaseLoss]): 附加到节点的损失,以其标识符为键。metrics(dict[str, BaseMetric]): 附加到节点的指标,以其标识符为键。visualizers(dict[str, BaseVisualizer]): 附加到节点的可视化工具,以其标识符为键。unfreeze_after(int | None): 节点开始训练的 epoch。当节点未冻结时为None。lr_after_unfreeze(float | None): 从解冻 epoch 开始,节点的基学习率。None保留调度器达到的速率。finetuning(list[FinetuningConfig]): 节点的优化器和调度器覆盖。inputs(list[str] | None): 馈送此节点的节点名称和加载器源。None变为一个空列表。
train
Python
1def train(mode: bool = True) -> NodeWrapper:torch.nn.Module.train 仅适用于注册的子模块,因此此覆盖也设置每个损失、指标和可视化工具的模式。参数mode(bool):True表示训练模式,False表示评估模式。
NodeWrapper: 此包装器。
属性
finetuning
formatted_name
"<task_name>-<name>",否则仅为 name。inputs
losses
lr_after_unfreeze
metrics
module
name
task_name
task_name,或者当数据集包含一个任务时来自数据集。否则为空字符串。unfreeze_after
visualizers
函数
build_training_strategy
Python
1def build_training_strategy(cfg: Config, pl_module: pl.LightningModule) -> BaseTrainingStrategy | None:trainer.training_strategy.params 访问其构造函数。策略通过 BaseTrainingStrategy.get_base_configs 提供基本优化器和调度器。因此,当 trainer.optimizer 或 trainer.scheduler 与其默认值不同时,该函数会记录警告。没有具体 rules 方法的类早于基于规则的 API,并且已弃用。该函数记录警告。它构建一个未注册的子类,其中包含抽象 rules 和 get_base_configs 的存根,以便它可以实例化该类。然后它通过 LegacyStrategyAdapter 挂载实例。适配器不贡献任何规则。当旧版类未定义 get_base_configs 时,它会引发 NotImplementedError。然后训练计划会回退到配置的优化器和调度器。参数cfg(Config): 配置。trainer.training_strategy命名策略并包含其参数。pl_module(pl.LightningModule): 策略附加到的 Lightning 模块。
BaseTrainingStrategy | None: 策略,如果配置中没有命名则为None。
check_tensor_device
Python
1def check_tensor_device(x: Tensor | list[Tensor], device: torch.device) -> bool:示例
Pycon
1>>> import torch
2>>> cpu = torch.device("cpu")
3>>> check_tensor_device(torch.zeros(1), cpu)
4True
5>>> check_tensor_device([torch.zeros(1), 1.0], cpu)
6Falsex(Tensor | list[Tensor]): 张量,或张量列表或元组。device(torch.device): 要比较的设备。
bool: 当张量在device上时为True,或者当序列中的每个项都是device上的张量时为True。空序列返回True。
TypeError: 当x既不是张量也不是列表或元组时。
compute_losses
Python
1def compute_losses(cfg: Config, losses: dict[str, dict[str, Tensor | tuple[Tensor, dict[str, Tensor]]]], device: torch.device) -> tuple[Tensor, dict[str, Tensor]]:weight。子损失不带权重。示例
Pycon
1>>> import torch
2>>> from luxonis_train.config import Config
3>>> bce = (torch.tensor(1.5), {"pos": torch.tensor(0.5)})
4>>> total, logged = compute_losses(
5... Config(rich_logging=False),
6... {"head": {"bce": bce}},
7... torch.device("cpu"),
8... )
9>>> total.tolist()
10[1.5]
11>>> sorted(logged)
12['loss', 'loss/head/bce', 'loss/head/bce/pos']cfg(Config): 配置。trainer.log_sub_losses决定子损失是否到达日志字典。losses(dict[str, dict[str, Tensor | tuple[Tensor, dict[str, Tensor]]]]): 一个步骤的损失。第一个键是节点标识符,第二个键是损失标识符。值是损失张量,或损失张量及其子损失的元组。device(torch.device): 总和的设备。
tuple[Tensor, dict[str, Tensor]]: 总和和用于日志记录的损失。总和是device上形状为[1]的张量,它保留其梯度图。字典包含每个损失的"loss/<node>/<loss>",当设置trainer.log_sub_losses时每个子损失的"loss/<node>/<loss>/<sub-loss>",以及总和的"loss"。该函数分离每个记录的张量并将其移动到 CPU。
compute_visualization_buffer
Python
1def compute_visualization_buffer(seq_buffer: list[dict[str, dict[str, Tensor]]], visualizations: dict[str, dict[str, Tensor]], logged_idxs: list[int], max_log_images: int) -> dict[str, dict[str, Tensor]] | None:max_log_images 时,该函数不再收集任何内容。否则,该函数从每个可视化中获取索引不在 logged_idxs 中的样本,最多 max_log_images 减去填充级别。示例
Pycon
1>>> import torch
2>>> batch = {"head": {"boxes": torch.zeros(4, 3, 8, 8)}}
3>>> extra = compute_visualization_buffer([], batch, [0, 2], 3)
4>>> extra["head"]["boxes"].shape
5torch.Size([2, 3, 8, 8])
6>>> compute_visualization_buffer([extra], batch, [0, 2], 2) is None
7Trueseq_buffer(list[dict[str, dict[str, Tensor]]]): 到目前为止已缓冲的批次。每个条目都具有visualizations的结构。visualizations(dict[str, dict[str, Tensor]]): 节点标识符映射到可视化工具标识符,再映射到形状为[B, C, H, W]的图像批次。不能为空。logged_idxs(list[int]): 平衡日志器已记录的批次索引。max_log_images(int): 一个 epoch 中要记录的图像数量。
dict[str, dict[str, Tensor]] | None: 跳过的样本,具有visualizations的结构。当第一个缓冲条目已满,或者平衡日志器已获取批次中的所有样本时为None。
get_main_metric
Python
1def get_main_metric(cfg: Config) -> MainMetric | None:is_main_metric 的指标。该函数按配置顺序扫描节点及其指标,第一个匹配项获胜。配置验证最多允许一个主指标,并在未设置时标记第一个指标。示例
Pycon
1>>> from luxonis_train.config import Config
2>>> node = {"name": "ResNet", "metrics": [{"name": "ConfusionMatrix"}]}
3>>> cfg = Config(rich_logging=False, model={"nodes": [node]})
4>>> get_main_metric(cfg)
5MainMetric(node_name='ResNet', metric_name='mcc')cfg(Config): 配置。
MainMetric | None: 节点标识符和指标标识符,或者当没有指标设置is_main_metric时为None。类名包含"ConfusionMatrix"的指标将获得标识符"mcc",无论其别名如何。
get_model_execution_order
Python
1def get_model_execution_order(model: lxt.LuxonisLightningModule) -> list[str]:torch.no_grad 下以批大小为 2 的零张量运行模型,并删除钩子。检查点存储列表,LuxonisLightningModule.load_checkpoint 使用它将旧检查点的权重映射到更改的模块布局。该函数将模型保留在评估模式。参数model(lxt.LuxonisLightningModule): 模型。其nodes.loader_input_shapes提供输入形状,其device放置输入。
list[str]: 模块名称,如named_modules报告的,按执行顺序。多次运行的模块每次运行只出现一次。
log_balanced_class_images
Python
1def log_balanced_class_images(tracker: LuxonisTrackerPL, nodes: Nodes, visualizations: dict[str, dict[str, Tensor]], labels: Labels, cls_task_keys: list[str], class_log_counts: list[int], n_logged_images: int, max_log_images: int, mode: Literal['test', 'val'], current_epoch: int) -> tuple[int, list[int], list[int]]:class_log_counts 中具有最低计数时,该函数选择该样本。然后,它将样本的每个类的计数加一。它从不选择没有当前类的样本。最后,它使用 log_sequential_images 记录每个可视化的选定样本。参数tracker(LuxonisTrackerPL): 接收图像的跟踪器。nodes(Nodes): 节点图,用于节点的日志名称。visualizations(dict[str, dict[str, Tensor]]): 节点标识符映射到可视化工具标识符,再映射到形状为[B, C, H, W]的图像批次。不能为空,因为该函数从其第一个条目读取批次大小。labels(Labels): 批次的标签。cls_task_keys(list[str]): 包含形状为[B, n_classes]的多标签分类目标的标签键。该函数按此顺序沿类维度连接张量。当其值大于 0 时,类存在。class_log_counts(list[int]): 在此 epoch 中,每个类有多少个选定样本。其长度是类的总数。该函数会就地更新它。n_logged_images(int): 在此批次之前,每个节点在此 epoch 中记录了多少图像。max_log_images(int): 每个节点在一个 epoch 中记录的最大图像数量。mode(Literal['test', 'val']): 评估阶段。current_epoch(int): 当前 epoch,用作步骤。
tuple[int, list[int], list[int]]: 此批次后最后一个节点的图像计数器,如 log_sequential_images 返回的,class_log_counts本身,以及选定样本的批次索引。
log_metric_artifacts
Python
1def log_metric_artifacts(tracker: LuxonisTrackerPL, metric: BaseMetric, computed: Any, *, mode: Literal['test', 'val'], formatted_node_name: str, metric_name: str, current_epoch: int):[C, H, W] 的张量。该函数记录任何其他工件的警告并跳过它。图像以 [H, W, C] 数组的形式发送到跟踪器,名称由 metric_artifact_image_name 构建,current_epoch 用作步骤。参数tracker(LuxonisTrackerPL): 接收图像的跟踪器。metric(BaseMetric): 生成工件的指标。computed(Any): BaseMetric.compute 的结果。该函数将其传递给 BaseMetric.get_artifacts。mode(Literal['test', 'val']): 评估阶段。formatted_node_name(str): 节点的日志名称。metric_name(str): 指标的标识符。current_epoch(int): 当前 epoch,用作步骤。
log_sequential_images
Python
1def log_sequential_images(tracker: LuxonisTrackerPL, nodes: Nodes, visualizations: dict[str, dict[str, Tensor]], n_logged_images: int, max_log_images: int, mode: Literal['test', 'val'], current_epoch: int) -> int:n_logged_images 开始,到 max_log_images 停止。节点的每个可视化工具共享计数器,计数器命名图像。一旦计数器达到 max_log_images,节点的其余可视化工具将不记录任何内容。图像以 "<mode>/visualizations/<node>/<visualizer>/<counter>" 的形式发送到跟踪器,作为 [H, W, C] 数组,current_epoch 用作步骤。<node> 是 Nodes.formatted_name 中的日志名称。参数tracker(LuxonisTrackerPL): 接收图像的跟踪器。nodes(Nodes): 节点图,用于节点的日志名称。visualizations(dict[str, dict[str, Tensor]]): 节点标识符映射到可视化工具标识符,再映射到形状为[B, C, H, W]的图像批次。不能为空。n_logged_images(int): 每个节点开始时的计数器值。max_log_images(int): 节点停止时的计数器值。mode(Literal['test', 'val']): 评估阶段。current_epoch(int): 当前 epoch,用作步骤。
int: 此批次后最后一个节点的计数器。
metric_artifact_image_name
Python
1def metric_artifact_image_name(mode: Literal['test', 'val'], formatted_node_name: str, metric_name: str, artifact_name: str) -> str:"<mode>/metrics/<node>/<metric>/<artifact>"。epoch 不属于其中。对于 MLflow,log_image 将标题从名称的最后一个 / 处拆分,并将步骤放在两者之间,就像它对可视化图像所做的那样。mlflow_image_key 显示了最终的 MLflow 路径。TensorBoard 和 Weights and Biases 接收名称不变。示例
Pycon
1>>> metric_artifact_image_name("val", "head", "pr_curve", "curve")
2'val/metrics/head/pr_curve/curve'mode(Literal['test', 'val']): 评估阶段。formatted_node_name(str): 节点的日志名称,请参阅 Nodes.formatted_name。metric_name(str): 指标的标识符。artifact_name(str): 工件的名称,如 BaseMetric.get_artifacts 所键入的。
str: 图像名称。
mlflow_image_key
Python
1def mlflow_image_key(name: str, step: int) -> str:LuxonisTracker.log_image 在最后一个 / 处将标题从名称中拆分,并将步骤放在两部分之间。此函数构建相同的路径。LuxonisLightningModule.get_mlflow_logging_keys 使用它来列出没有跟踪器的运行的预期工件。示例
Pycon
1>>> mlflow_image_key("val/metrics/head/pr_curve/curve", 7)
2'val/metrics/head/pr_curve/7/curve.png'name(str):log_image接收的图像名称。它必须包含至少一个/。step(int): 图像的步骤。Lightning 模块传递 epoch。
str:"<base path>/<step>/<caption>.png"。
ValueError: 当name不包含/时。
postprocess_metrics
Python
1def postprocess_metrics(name: str, values: Any, log_sub_metrics: bool = True) -> dict[str, Tensor]:示例
Pycon
1>>> import torch
2>>> result = (torch.tensor(0.5), {"map_50": torch.tensor(0.75)})
3>>> out = postprocess_metrics("map", result)
4>>> {k: v.item() for k, v in out.items()}
5{'map': 0.5, 'map_50': 0.75}Pycon
1>>> out = postprocess_metrics("map", result, log_sub_metrics=False)
2>>> list(out)
3['map']Pycon
1>>> sub = {"map_50": torch.tensor(0.75)}
2>>> postprocess_metrics("map", sub, log_sub_metrics=False)
3{}name(str): 指标的标识符。values(Any): 计算结果。张量是主值。元组包含主值和子指标。字典仅包含子指标。log_sub_metrics(bool): 保留子指标。当False时,只保留主值,字典结果返回空字典。
dict[str, Tensor]:name映射到主值,加上每个子指标在其自己的键下。字典结果仅返回子指标。
ValueError: 当values不具有这三种形式之一时。