<无标题> — darts 文档

此文件包含确定性和概率性 PyTorch Lightning 模块的抽象类

class darts.models.forecasting.pl_forecasting_module.PLDualCovariatesModule(input_chunk_length, output_chunk_length, output_chunk_shift=0, train_sample_shape=None, loss_fn=MSELoss(), torch_metrics=None, likelihood=None, optimizer_cls=<class 'torch.optim.adam.Adam'>, optimizer_kwargs=None, lr_scheduler_cls=None, lr_scheduler_kwargs=None, use_reversible_instance_norm=False)[source]¶

基类：PLForecastingModule, ABC

基于 PyTorch Lightning 的预测模块。

此类旨在被继承以创建新的基于 PyTorch Lightning 的预测模块。子类化此类时，请确保添加具有以下签名的方

PLForecastingModule.__init__()

PLForecastingModule.forward()

PLForecastingModule._process_input_batch()

PLForecastingModule._produce_train_output()

PLForecastingModule._get_batch_prediction()

在子类 MyModel 的 __init__() 函数中调用 super(MyModel, self).__init__(**kwargs)，其中 kwargs 是 PLForecastingModule 的参数。

参数

input_chunk_length (int) – 模型输入的时间步长数量（每块）。适用于目标序列以及过去和/或未来协变量（如果模型支持）。
output_chunk_length (int) – 内部模型一次预测（每块）的时间步长数量。此外，未来协变量的未来值用作模型输入的数量（如果模型支持未来协变量）。它与 predict() 中使用的预测视野 n 不同，后者是使用一次性预测或自回归预测生成的所需预测点数。设置 n <= output_chunk_length 可防止自回归。当协变量未能充分延伸到未来时，这非常有用，或者为了禁止模型使用过去和/或未来协变量的未来值进行预测（取决于模型的协变量支持）。
train_sample_shape (Optional[tuple, None]) – 模型的输入形状，用于在不调用 fit_from_dataset 的情况下实例化模型，并对用于重新训练或预测的新训练/推理数据集执行健全性检查。
loss_fn (_Loss) – 用于训练的 PyTorch 损失函数。如果指定了 likelihood 参数，则此参数对于概率模型将被忽略。默认值：torch.nn.MSELoss()。
torch_metrics (Union[Metric, MetricCollection, None]) – 用于评估的 torch 指标或 MetricCollection。可在 https://torchmetrics.readthedocs.io/en/latest/ 找到可用指标的完整列表。默认值：None。
likelihood (Optional[TorchLikelihood, None]) – Darts 的 Likelihood 模型之一，用于概率预测。默认值：None。
optimizer_cls (Optimizer) – 要使用的 PyTorch 优化器类。默认值：torch.optim.Adam。
optimizer_kwargs (Optional[dict, None]) – 可选地，PyTorch 优化器的一些关键字参数（例如，{'lr': 1e-3} 用于指定学习率）。否则将使用选定的 optimizer_cls 的默认值。默认值：None。
lr_scheduler_cls (Optional[_LRScheduler, None]) – 可选地，要使用的 PyTorch 学习率调度器类。指定 None 对应于使用恒定学习率。默认值：None。
lr_scheduler_kwargs (Optional[dict, None]) – 可选地，PyTorch 学习率调度器的一些关键字参数。默认值：None。
use_reversible_instance_norm (bool) – 是否使用可逆实例归一化 RINorm 来抵抗分布漂移，如 [1] 所示。它仅应用于目标序列的特征，而不应用于协变量。

参考

1: T. Kim et al. “Reversible Instance Normalization for Accurate Time-Series Forecasting against Distribution Shift”, https://openreview.net/forum?id=cGDAkQo1C0p

属性

`automatic_optimization`	如果设置为 `False`，则您负责调用 `.backward()`, `.step()`, `.zero_grad()`。
`current_epoch`	`Trainer` 中的当前 epoch，如果未附加则为 0。
`device_mesh`	`ModelParallelStrategy` 等策略将创建设备网格，可在 `configure_model()` 钩子中访问该网格以并行化 LightningModule。
`example_input_array`	示例输入数组指定了模块在 `forward()` 方法中可以使用的内容。
`global_rank`	当前进程在所有节点和设备中的索引。
`global_step`	所有 epoch 中看到的总训练批次。
`hparams`	使用 `save_hyperparameters()` 保存的超参数集合。
`hparams_initial`	使用 `save_hyperparameters()` 保存的超参数集合。
`local_rank`	当前进程在单个节点内的索引。
`logger`	指向 Trainer 中 logger 对象的引用。
`loggers`	指向 Trainer 中 loggers 列表的引用。
`on_gpu`	如果此模型当前位于 GPU 上，则返回 `True`。
`output_chunk_length`	模型一次预测的时间步长数量。
`strict_loading`	确定 Lightning 如何使用 .load_state_dict(..., strict=model.strict_loading) 加载此模型。

device
dtype
epochs_trained
fabric
supports_probabilistic_prediction
trainer

方法

`add_module`(name, module)	向当前模块添加子模块。
`all_gather`(data[, group, sync_grads])	从多个进程聚合张量或张量集合。
`apply`(fn)	将 `fn` 递归地应用于每个子模块（由 `.children()` 返回）以及自身。
`backward`(loss, args, *kwargs)	调用此方法对 `training_step()` 返回的损失进行反向传播。
`bfloat16`()	将所有浮点参数和缓冲区转换为 `bfloat16` 数据类型。
`buffers`([recurse])	返回模块缓冲区的迭代器。
`children`()	返回直接子模块的迭代器。
`clip_gradients`(optimizer[, ...])	内部处理梯度裁剪。
`compile`(args, *kwargs)	使用 `torch.compile()` 编译此模块的前向传播。
`configure_callbacks`()	配置模型特定的回调。
`configure_gradient_clipping`(optimizer[, ...])	对优化器参数执行梯度裁剪。
`configure_model`()	在策略和精度感知上下文中创建模块的钩子。
`configure_optimizers`()	配置用于模型优化的优化器和学习率调度器。
`configure_sharded_model`()	已弃用。
`configure_torch_metrics`(torch_metrics)	处理 torch_metrics 参数。
`cpu`()	参见 `torch.nn.Module.cpu()`。
`cuda`([device])	将所有模型参数和缓冲区移动到 GPU。
`double`()	参见 `torch.nn.Module.double()`。
`eval`()	将模块设置为评估模式。
`extra_repr`()	返回模块的额外表示。
`float`()	参见 `torch.nn.Module.float()`。
`forward`(args, *kwargs)	与 `torch.nn.Module.forward()` 相同。
`freeze`()	冻结所有参数以进行推理。
`get_buffer`(target)	如果存在，则返回由 `target` 指定的缓冲区，否则抛出错误。
`get_extra_state`()	返回要包含在模块 state_dict 中的任何额外状态。
`get_parameter`(target)	如果存在，则返回由 `target` 指定的参数，否则抛出错误。
`get_submodule`(target)	如果存在，则返回由 `target` 指定的子模块，否则抛出错误。
`half`()	参见 `torch.nn.Module.half()`。
`ipu`([device])	将所有模型参数和缓冲区移动到 IPU。
`load_from_checkpoint`(checkpoint_path[, ...])	从检查点加载模型的主要方式。
`load_state_dict`(state_dict[, strict, assign])	将 `state_dict` 中的参数和缓冲区复制到此模块及其后代中。
`log`(name, value[, prog_bar, logger, ...])	记录键值对。
`log_dict`(dictionary[, prog_bar, logger, ...])	一次记录字典中的值。
`lr_scheduler_step`(scheduler, metric)	覆盖此方法以调整 `Trainer` 调用每个调度器的默认方式。
`lr_schedulers`()	返回训练期间使用的学习率调度器。
`manual_backward`(loss, args, *kwargs)	手动优化时，直接从 `training_step()` 调用此方法。
`modules`()	返回网络中所有模块的迭代器。
`mtia`([device])	将所有模型参数和缓冲区移动到 MTIA。
`named_buffers`([prefix, recurse, ...])	返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。
`named_children`()	返回直接子模块的迭代器，同时产生模块名称和模块本身。
`named_modules`([memo, prefix, remove_duplicate])	返回网络中所有模块的迭代器，同时产生模块名称和模块本身。
`named_parameters`([prefix, recurse, ...])	返回模块参数的迭代器，同时产生参数名称和参数本身。
`on_after_backward`()	在 `loss.backward()` 之后且在优化器步进之前调用。
`on_after_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备后修改或应用批次增强。
`on_before_backward`(loss)	在 `loss.backward()` 之前调用。
`on_before_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备之前修改或应用批次增强。
`on_before_optimizer_step`(optimizer)	在 `optimizer.step()` 之前调用。
`on_before_zero_grad`(optimizer)	在 `training_step()` 之后且在 `optimizer.zero_grad()` 之前调用。
`on_fit_end`()	在 fit 的最后调用。
`on_fit_start`()	在 fit 的最开始调用。
`on_load_checkpoint`(checkpoint)	由 Lightning 调用以恢复您的模型。
`on_predict_batch_end`(outputs, batch, batch_idx)	在预测循环中批次之后调用。
`on_predict_batch_start`(batch, batch_idx[, ...])	在预测循环中该批次发生任何事情之前调用。
`on_predict_end`()	在预测结束时调用。
`on_predict_epoch_end`()	在预测结束时调用。
`on_predict_epoch_start`()	在预测开始时调用。
`on_predict_model_eval`()	预测循环开始时调用。
`on_predict_start`()	在预测开始时调用。
`on_save_checkpoint`(checkpoint)	Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。
`on_test_batch_end`(outputs, batch, batch_idx)	在测试循环中批次之后调用。
`on_test_batch_start`(batch, batch_idx[, ...])	在测试循环中该批次发生任何事情之前调用。
`on_test_end`()	在测试结束时调用。
`on_test_epoch_end`()	在测试循环中 epoch 的最后调用。
`on_test_epoch_start`()	在测试循环中 epoch 的最开始调用。
`on_test_model_eval`()	测试循环开始时调用。
`on_test_model_train`()	测试循环结束时调用。
`on_test_start`()	在测试开始时调用。
`on_train_batch_end`(outputs, batch, batch_idx)	在训练循环中批次之后调用。
`on_train_batch_start`(batch, batch_idx)	在训练循环中该批次发生任何事情之前调用。
`on_train_end`()	在训练结束、logger 实验关闭之前调用。
`on_train_epoch_end`()	在训练循环中 epoch 的最后调用。
`on_train_epoch_start`()	在训练循环中 epoch 的最开始调用。
`on_train_start`()	在健全性检查之后、训练开始时调用。
`on_validation_batch_end`(outputs, batch, ...)	在验证循环中批次之后调用。
`on_validation_batch_start`(batch, batch_idx)	在验证循环中该批次发生任何事情之前调用。
`on_validation_end`()	在验证结束时调用。
`on_validation_epoch_end`()	在验证循环中 epoch 的最后调用。
`on_validation_epoch_start`()	在验证循环中 epoch 的最开始调用。
`on_validation_model_eval`()	验证循环开始时调用。
`on_validation_model_train`()	验证循环结束时调用。
`on_validation_model_zero_grad`()	由训练循环调用，在进入验证循环之前释放梯度。
`on_validation_start`()	在验证开始时调用。
`optimizer_step`(epoch, batch_idx, optimizer)	覆盖此方法以调整 `Trainer` 调用优化器的默认方式。
`optimizer_zero_grad`(epoch, batch_idx, optimizer)	覆盖此方法以更改 `optimizer.zero_grad()` 的默认行为。
`optimizers`([use_pl_optimizer])	返回训练期间使用的优化器。
`parameters`([recurse])	返回模块参数的迭代器。
`predict_dataloader`()	指定预测样本的可迭代对象或可迭代对象集合。
`predict_step`(batch, batch_idx[, dataloader_idx])	执行预测步骤
`prepare_data`()	使用此方法下载和准备数据。
`print`(args, *kwargs)	仅从进程 0 打印。
`register_backward_hook`(hook)	在模块上注册后向钩子。
`register_buffer`(name, tensor[, persistent])	向模块添加缓冲区。
`register_forward_hook`(hook, *[, prepend, ...])	在模块上注册前向钩子。
`register_forward_pre_hook`(hook, *[, ...])	在模块上注册前向预钩子。
`register_full_backward_hook`(hook[, prepend])	在模块上注册后向钩子。
`register_full_backward_pre_hook`(hook[, prepend])	在模块上注册后向预钩子。
`register_load_state_dict_post_hook`(hook)	注册一个后钩子，该钩子在模块的 `load_state_dict()` 被调用后运行。
`register_load_state_dict_pre_hook`(hook)	注册一个预钩子，该钩子在模块的 `load_state_dict()` 被调用前运行。
`register_module`(name, module)	`add_module()` 的别名。
`register_parameter`(name, param)	向模块添加参数。
`register_state_dict_post_hook`(hook)	为 `state_dict()` 方法注册一个后钩子。
`register_state_dict_pre_hook`(hook)	为 `state_dict()` 方法注册一个预钩子。
`requires_grad_`([requires_grad])	更改此模块中是否应记录参数上的自动梯度操作。
`save_hyperparameters`(*args[, ignore, frame, ...])	将参数保存到 `hparams` 属性。
`set_extra_state`(state)	设置加载的 state_dict 中包含的额外状态。
`set_predict_parameters`(n, num_samples, ...)	在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置
`set_submodule`(target, module)	如果存在，则设置由 `target` 指定的子模块，否则抛出错误。
`setup`(stage)	在 fit（训练 + 验证）、验证、测试或预测开始时调用。
`share_memory`()	参见 `torch.Tensor.share_memory_()`。
`state_dict`(*args[, destination, prefix, ...])	返回包含模块完整状态引用的字典。
`teardown`(stage)	在 fit（训练 + 验证）、验证、测试或预测结束时调用。
`test_dataloader`()	指定测试样本的可迭代对象或可迭代对象集合。
`test_step`(args, *kwargs)	处理测试集中的单个批次数据。
`to`(args, *kwargs)	参见 `torch.nn.Module.to()`。
`to_dtype`(dtype)	将模块精度（默认为 float32）转换为其他精度。
`to_empty`(*, device[, recurse])	在不复制存储的情况下，将参数和缓冲区移动到指定设备。
`to_onnx`(file_path[, input_sample])	将模型保存为 ONNX 格式。
`to_torchscript`([file_path, method, ...])	默认情况下，将整个模型编译为 `ScriptModule`。
`toggle_optimizer`(optimizer)	确保在训练步骤中仅计算当前优化器参数的梯度，以防止多优化器设置中出现悬空梯度。
`train`([mode])	将模块设置为训练模式。
`train_dataloader`()	指定训练样本的可迭代对象或可迭代对象集合。
`training_step`(train_batch, batch_idx)	执行训练步骤
`transfer_batch_to_device`(batch, device, ...)	如果您的 `DataLoader` 返回包装在自定义数据结构中的张量，请覆盖此钩子。
`type`(dst_type)	参见 `torch.nn.Module.type()`。
`unfreeze`()	解冻所有参数以进行训练。
`untoggle_optimizer`(optimizer)	重置使用 `toggle_optimizer()` 切换的所需梯度的状态。
`val_dataloader`()	指定验证样本的可迭代对象或可迭代对象集合。
`validation_step`(val_batch, batch_idx)	执行验证步骤
`xpu`([device])	将所有模型参数和缓冲区移动到 XPU。
`zero_grad`([set_to_none])	重置所有模型参数的梯度。

__call__
set_mc_dropout

CHECKPOINT_HYPER_PARAMS_KEY = 'hyper_parameters'¶

CHECKPOINT_HYPER_PARAMS_NAME = 'hparams_name'¶

CHECKPOINT_HYPER_PARAMS_TYPE = 'hparams_type'¶

T_destination¶: TypeVar(‘T_destination’, bound=Dict[str, Any]) 的别名

add_module(name, module)¶

向当前模块添加子模块。

模块可以使用给定的名称作为属性访问。

参数

name (str) – 子模块的名称。可以使用此名称从当前模块访问子模块
module (Module) – 要添加到模块的子模块。

返回类型

None

all_gather(data, group=None, sync_grads=False)¶

从多个进程聚合张量或张量集合。

此方法需要在所有进程上调用，并且张量需要在所有进程上具有相同的形状，否则您的程序将永远暂停。

参数

data (Union[Tensor, dict, list, tuple]) – int、float、形状为 (batch, …) 的张量，或其（可能嵌套的）集合。
group (Optional[Any, None]) – 要从中收集结果的进程组。默认为所有进程 (world)。
sync_grads (bool) – 允许用户同步 all_gather 操作的梯度的标志。

返回类型

Union[Tensor, dict, list, tuple]

返回值

形状为 (world_size, batch, …) 的张量，如果输入是集合，则输出也将是包含此形状张量的集合。对于 world_size 为 1 的特殊情况，不会向张量添加额外维度。

apply(fn)¶

将 fn 递归地应用于每个子模块（由 .children() 返回）以及自身。

典型用法包括初始化模型的参数（另见 nn-init-doc）。

参数: fn (Module -> None) – 要应用于每个子模块的函数
返回值: self
返回类型: Module

示例

>>> @torch.no_grad()
>>> def init_weights(m):
>>>     print(m)
>>>     if type(m) == nn.Linear:
>>>         m.weight.fill_(1.0)
>>>         print(m.weight)
>>> net = nn.Sequential(nn.Linear(2, 2), nn.Linear(2, 2))
>>> net.apply(init_weights)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)

property automatic_optimization: bool¶

如果设置为 False，则您负责调用 .backward(), .step(), .zero_grad()。

返回类型: bool

backward(loss, *args, **kwargs)¶

调用此方法对 training_step() 返回的损失执行反向传播。如果您需要自定义实现，请覆盖此钩子。

参数: loss (Tensor) – training_step() 返回的损失张量。如果使用了梯度累积，这里的损失保持归一化值（按 1 / 累积步数缩放）。

示例

def backward(self, loss):
    loss.backward()

返回类型: None

bfloat16()¶

将所有浮点参数和缓冲区转换为 bfloat16 数据类型。

注意

此方法会修改模块本身。

返回值: self
返回类型: Module

buffers(recurse=True)¶

返回模块缓冲区的迭代器。

参数: recurse (bool) – 如果为 True，则产生此模块和所有子模块的缓冲区。否则，仅产生此模块的直接成员缓冲区。
Yields: torch.Tensor – 模块缓冲区

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for buf in model.buffers():
>>>     print(type(buf), buf.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Tensor]

call_super_init: bool = False¶

children()¶

返回直接子模块的迭代器。

Yields: Module – 子模块
返回类型: Iterator[Module]

clip_gradients(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

内部处理梯度裁剪。

注意

不要覆盖此方法。如果要自定义梯度裁剪，请考虑使用 configure_gradient_clipping() 方法。
对于手动优化 (self.automatic_optimization = False)，如果要使用梯度裁剪，请考虑在训练步骤中手动调用 self.clip_gradients(opt, gradient_clip_val=0.5, gradient_clip_algorithm="norm")。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 裁剪梯度的值。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。传递 gradient_clip_algorithm="value" 按值裁剪，传递 gradient_clip_algorithm="norm" 按范数裁剪。

返回类型

None

compile(*args, **kwargs)¶

使用 torch.compile() 编译此模块的前向传播。

此模块的 __call__ 方法将被编译，并且所有参数将原样传递给 torch.compile()。

有关此函数的参数详细信息，请参见 torch.compile()。

configure_callbacks()¶

配置模型特定的回调。当模型被附加时，例如调用 .fit() 或 .test() 时，此处返回的列表或回调将与传递给 Trainer 的 callbacks 参数的回调列表合并。如果此处返回的回调类型与 Trainer 回调列表中已存在的一个或多个回调相同，则它将优先并替换它们。此外，Lightning 将确保 ModelCheckpoint 回调最后运行。

返回类型: Union[Sequence[Callback], Callback]
返回值: 一个或多个回调，它们将扩展 Trainer 中的回调列表。

示例

def configure_callbacks(self):
    early_stop = EarlyStopping(monitor="val_acc", mode="max")
    checkpoint = ModelCheckpoint(monitor="val_loss")
    return [early_stop, checkpoint]

configure_gradient_clipping(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

对优化器参数执行梯度裁剪。在 optimizer_step() 之前调用。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 裁剪梯度的值。默认情况下，Trainer 中传递的值将在此处可用。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。默认情况下，Trainer 中传入的值将在此处可用。

示例

def configure_gradient_clipping(self, optimizer, gradient_clip_val, gradient_clip_algorithm):
    # Implement your own custom logic to clip gradients
    # You can call `self.clip_gradients` with your settings:
    self.clip_gradients(
        optimizer,
        gradient_clip_val=gradient_clip_val,
        gradient_clip_algorithm=gradient_clip_algorithm
    )

返回类型: None

configure_model()¶

在策略和精度感知上下文中创建模块的钩子。

这对于使用分片策略（FSDP 和 DeepSpeed）时特别有用，在这种情况下，我们希望立即分片模型以节省内存和初始化时间。对于非分片策略，您可以选择覆盖此钩子或在 init_module() 上下文管理器下初始化您的模型。

此钩子在同一进程的 fit/val/test/predict 各阶段都会被调用，因此请确保此钩子的实现是幂等的，即在第一次调用此钩子后，后续调用应该是空操作。

返回类型: None

configure_optimizers()¶: 配置用于模型优化的优化器和学习率调度器。

configure_sharded_model()¶

已弃用。

请改用 configure_model()。

返回类型: None

static configure_torch_metrics(torch_metrics)¶

处理 torch_metrics 参数。

返回类型: MetricCollection

cpu()¶

参见 torch.nn.Module.cpu()。

返回类型: Self

cuda(device=None)¶

将所有模型参数和缓冲区移动到 GPU。这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 GPU 上进行优化，则应在构建优化器之前调用此方法。

参数: device (Union[int, device, None]) – 如果指定，所有参数将被复制到该设备。如果为 None，将使用当前的 CUDA 设备索引。
返回值: self
返回类型: Module

property current_epoch: int¶

Trainer 中的当前 epoch，如果未附加则为 0。

返回类型: int

property device: device¶

返回类型: device

property device_mesh: Optional[DeviceMesh]¶

ModelParallelStrategy 等策略将创建设备网格，可在 configure_model() 钩子中访问该网格以并行化 LightningModule。

返回类型: Optional[ForwardRef, None]

double()¶

参见 torch.nn.Module.double()。

返回类型: Self

property dtype: Union[str, dtype]¶

返回类型: Union[str, dtype]

dump_patches: bool = False¶

property epochs_trained¶

eval()¶

将模块设置为评估模式。

这仅对某些模块有效。有关特定模块在训练/评估模式下的行为详情，即它们是否受到影响，请参阅其文档，例如 Dropout、BatchNorm 等。

这等同于 self.train(False)。

有关 .eval() 与可能与其混淆的几个类似机制之间的比较，请参见 locally-disable-grad-doc。

返回值: self
返回类型: Module

property example_input_array: Optional[Union[Tensor, tuple, dict]]¶

示例输入数组指定了模块在 forward() 方法中可以接受的内容。返回类型解释如下：

单个张量：假定模型接受一个参数，即 model.forward(model.example_input_array)
元组：输入数组应被解释为位置参数序列，即 model.forward(*model.example_input_array)
字典：输入数组表示命名关键字参数，即 model.forward(**model.example_input_array)

返回类型: Union[Tensor, tuple, dict, None]

extra_repr()¶

返回模块的额外表示。

要打印自定义的额外信息，您应该在自己的模块中重新实现此方法。单行和多行字符串都可接受。

返回类型: str

property fabric: Optional[Fabric]¶

返回类型: Optional[Fabric, None]

float()¶

参见 torch.nn.Module.float()。

返回类型: Self

abstract forward(*args, **kwargs)¶

与 torch.nn.Module.forward() 相同。

参数

*args – 您决定传递给 forward 方法的任何内容。
**kwargs – 关键字参数也是可以的。

返回类型

Any

返回值

您的模型的输出

freeze()¶

冻结所有参数以进行推理。

示例

model = MyLightningModule(...)
model.freeze()

返回类型: None

get_buffer(target)¶

如果存在，则返回由 target 指定的缓冲区，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的缓冲区的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的缓冲区
返回类型: torch.Tensor
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是缓冲区

get_extra_state()¶

返回要包含在模块 state_dict 中的任何额外状态。

如果您需要存储额外状态，请为您的模块实现此方法以及相应的 set_extra_state()。在构建模块的 state_dict() 时会调用此函数。

请注意，额外状态应该是可序列化的 (picklable)，以确保 state_dict 的序列化工作正常。我们仅为张量 (Tensors) 的序列化提供向后兼容性保证；如果其他对象的序列化 picklable 形式发生变化，可能会破坏向后兼容性。

返回值: 要存储在模块 state_dict 中的任何额外状态
返回类型: object

get_parameter(target)¶

如果存在，则返回由 target 指定的参数，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的参数的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的参数
返回类型: torch.nn.Parameter
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Parameter

get_submodule(target)¶

如果存在，则返回由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

（图表显示了一个 nn.Module A。 A 有一个嵌套子模块 net_b，它本身有两个子模块 net_c 和 linear。 net_c 还有一个子模块 conv。）

要检查是否存在 linear 子模块，我们可以调用 get_submodule("net_b.linear")。要检查是否存在 conv 子模块，我们可以调用 get_submodule("net_b.net_c.conv")。

get_submodule 的运行时受 target 中模块嵌套深度的限制。查询 named_modules 也可以达到相同的效果，但其时间复杂度是传递模块数量的 O(N)。因此，对于简单地检查某个子模块是否存在，应始终使用 get_submodule。

参数: target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
返回值: target 引用的子模块
返回类型: torch.nn.Module
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

property global_rank: int¶

当前进程在所有节点和设备中的索引。

返回类型: int

property global_step: int¶

所有 epoch 中看到的总训练批次。

如果未附加 Trainer，此属性值为 0。

返回类型: int

half()¶

参见 torch.nn.Module.half()。

返回类型: Self

property hparams: Union[AttributeDict, MutableMapping]¶

使用 save_hyperparameters() 保存的超参数集合。用户可以修改它。对于初始超参数的冻结集合，请使用 hparams_initial。

返回类型: Union[AttributeDict, MutableMapping]
返回值: 可变的超参数字典

property hparams_initial: AttributeDict¶

使用 save_hyperparameters() 保存的超参数集合。这些内容是只读的。对已保存超参数的手动更新可以通过 hparams 进行。

返回值: 不可变初始超参数
返回类型: AttributeDict

ipu(device=None)¶

将所有模型参数和缓冲区移动到 IPU。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 IPU 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

load_from_checkpoint(checkpoint_path, map_location=None, hparams_file=None, strict=None, **kwargs)¶

从检查点加载模型的主要方式。当 Lightning 保存检查点时，它会将传递给 __init__ 的参数存储在检查点中的 "hyper_parameters" 下。

通过 **kwargs 指定的任何参数将覆盖存储在 "hyper_parameters" 中的参数。

参数

checkpoint_path (Union[str, Path, IO]) – 检查点路径。这也可以是 URL 或文件类对象
map_location (Union[device, str, int, Callable[[UntypedStorage, str], Optional[UntypedStorage, None]], dict[Union[device, str, int], Union[device, str, int]], None]) – 如果您的检查点保存的是 GPU 模型，而您现在在 CPU 或不同数量的 GPU 上加载，请使用此参数映射到新的配置。其行为与 torch.load() 中相同。
hparams_file (Union[str, Path, None]) –
可选的 .yaml 或 .csv 文件路径，其结构如下例所示
```
drop_prob: 0.2
dataloader:
    batch_size: 32
```
您很可能不需要此参数，因为 Lightning 总是会将超参数保存到检查点中。但是，如果您的检查点权重没有保存超参数，请使用此方法传入一个包含您希望使用的超参数的 .yaml 文件。这些超参数将被转换为 dict 并传递给您的 LightningModule 使用。

如果您的模型的 hparams 参数是 Namespace 并且 .yaml 文件具有分层结构，您需要重构您的模型以将 hparams 视为 dict。
strict (Optional[bool, None]) – 是否严格强制 checkpoint_path 中的键与此模块的 state dict 返回的键完全匹配。默认为 True，除非设置了 LightningModule.strict_loading，在这种情况下，它将默认为 LightningModule.strict_loading 的值。
**kwargs – 初始化模型所需的任何额外关键字参数。也可以用于覆盖已保存的超参数值。

返回类型

Self

返回值

加载了权重和超参数（如果可用）的 LightningModule 实例。

注意

load_from_checkpoint 是一个类方法。您应该使用 LightningModule 类来调用它，而不是 LightningModule 实例，否则将引发 TypeError。

注意

为了确保所有层都能从检查点加载，如果您的 LightningModule 中覆盖了此钩子，此函数将在实例化模型后直接调用 configure_model()。但是请注意，load_from_checkpoint 不支持加载分片检查点，如果模型太大，您可能会遇到内存不足的情况。在这种情况下，请考虑通过 Trainer 使用 .fit(ckpt_path=...) 进行加载。

示例

# load weights without mapping ...
model = MyLightningModule.load_from_checkpoint('path/to/checkpoint.ckpt')

# or load weights mapping all weights from GPU 1 to GPU 0 ...
map_location = {'cuda:1':'cuda:0'}
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    map_location=map_location
)

# or load weights and hyperparameters from separate files.
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    hparams_file='/path/to/hparams_file.yaml'
)

# override some of the params with new values
model = MyLightningModule.load_from_checkpoint(
    PATH,
    num_layers=128,
    pretrained_ckpt_path=NEW_PATH,
)

# predict
pretrained_model.eval()
pretrained_model.freeze()
y_hat = pretrained_model(x)

load_state_dict(state_dict, strict=True, assign=False)¶

将 state_dict 中的参数和缓冲区复制到此模块及其后代中。

如果 strict 为 True，则 state_dict 的键必须与此模块的 state_dict() 函数返回的键完全匹配。

警告

如果 assign 为 True，则必须在调用 load_state_dict 之后创建优化器，除非 get_swap_module_params_on_conversion() 为 True。

参数

state_dict (dict) – 包含参数和持久缓冲区的字典。
strict (bool, optional) – 是否严格强制 state_dict 中的键与此模块的 state_dict() 函数返回的键匹配。默认值：True
assign (bool, optional) – 设置为 False 时，保留当前模块中张量的属性，而设置为 True 时，保留 state dict 中张量的属性。唯一的例外是 Default: ``False` 的 requires_grad 字段

返回值

missing_keys 是一个字符串列表，包含此模块需要但
提供的 state_dict 中缺失的键。
unexpected_keys 是一个字符串列表，包含此模块
不预期但提供的 state_dict 中存在的键。

返回类型

包含 missing_keys 和 unexpected_keys 字段的 NamedTuple

注意

如果参数或缓冲区注册为 None 且其对应的键存在于 state_dict 中，load_state_dict() 将引发 RuntimeError。

property local_rank: int¶

当前进程在单个节点内的索引。

返回类型: int

log(name, value, prog_bar=False, logger=None, on_step=None, on_epoch=None, reduce_fx='mean', enable_graph=False, sync_dist=False, sync_dist_group=None, add_dataloader_idx=True, batch_size=None, metric_attribute=None, rank_zero_only=False)¶

记录键值对。

示例

self.log('train_loss', loss)

每个钩子的默认行为在此处有文档说明：extensions/logging:Automatic Logging。

参数

name (str) – 要记录的键。如果使用 DDP 或任何其他分布式策略，则必须在所有进程中保持一致。
value (Union[Metric, Tensor, int, float]) – 要记录的值。可以是 float、Tensor 或 Metric。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图。
sync_dist (bool) – 如果为 True，则在设备之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 DDP 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个 dataloader 时）。如果 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch_size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
metric_attribute (Optional[str, None]) – 为了恢复指标状态，Lightning 需要您的模型中 torchmetrics.Metric 的引用。如果它是一个模型属性，则会自动找到。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

log_dict(dictionary, prog_bar=False, logger=None, on_step=None, on_epoch=None, reduce_fx='mean', enable_graph=False, sync_dist=False, sync_dist_group=None, add_dataloader_idx=True, batch_size=None, rank_zero_only=False)¶

一次记录字典中的值。

示例

values = {'loss': loss, 'acc': acc, ..., 'metric_n': metric_n}
self.log_dict(values)

参数

dictionary (Union[Mapping[str, Union[Metric, Tensor, int, float]], MetricCollection]) – 键值对。如果使用 DDP 或任何其他分布式策略，则键必须在所有进程中保持一致。值可以是 float、Tensor、Metric 或 MetricCollection。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。None 会自动记录 training_step，但不记录 validation/test_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。None 会自动记录 val/test step，但不记录 training_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图
sync_dist (bool) – 如果为 True，则在 GPU/TPU 之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 ddp 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个时）。如果为 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

property logger: Optional[Union[Logger, Logger]]¶

指向 Trainer 中 logger 对象的引用。

返回类型: Union[Logger, Logger, None]

property loggers: Union[list[pytorch_lightning.loggers.logger.Logger], list[lightning_fabric.loggers.logger.Logger]]¶

指向 Trainer 中 loggers 列表的引用。

返回类型: Union[list[Logger], list[Logger]]

lr_scheduler_step(scheduler, metric)¶

覆盖此方法以调整 Trainer 调用每个调度器的默认方式。默认情况下，Lightning 根据每个调度器的 interval 调用 step()，如示例所示。

参数

scheduler (Union[LRScheduler, ReduceLROnPlateau]) – 学习率调度器。
metric (Optional[Any, None]) – 用于像 ReduceLROnPlateau 这样的调度器的监视器值。

示例

# DEFAULT
def lr_scheduler_step(self, scheduler, metric):
    if metric is None:
        scheduler.step()
    else:
        scheduler.step(metric)

# Alternative way to update schedulers if it requires an epoch value
def lr_scheduler_step(self, scheduler, metric):
    scheduler.step(epoch=self.current_epoch)

返回类型: None

lr_schedulers()¶

返回训练期间使用的学习率调度器。对于手动优化很有用。

返回类型: Union[None, list[Union[LRScheduler, ReduceLROnPlateau]], LRScheduler, ReduceLROnPlateau]
返回值: 单个调度器，或者在存在多个调度器时返回一个列表，如果在 configure_optimizers() 中没有返回调度器，则返回 None。

manual_backward(loss, *args, **kwargs)¶

在手动进行优化时，直接从您的 training_step() 中调用此方法。通过使用此方法，Lightning 可以确保在使用混合精度时应用所有正确的缩放比例。

更多示例请参见 manual optimization。

示例

def training_step(...):
    opt = self.optimizers()
    loss = ...
    opt.zero_grad()
    # automatically applies scaling, etc...
    self.manual_backward(loss)
    opt.step()

参数

loss (Tensor) – 用于计算梯度的张量。必须附加计算图。
*args – 要转发给 backward() 的额外位置参数
**kwargs – 要转发给 backward() 的额外关键字参数

返回类型

None

modules()¶

返回网络中所有模块的迭代器。

Yields: Module – 网络中的一个模块

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.modules()):
...     print(idx, '->', m)

0 -> Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)
1 -> Linear(in_features=2, out_features=2, bias=True)

返回类型: Iterator[Module]

mtia(device=None)¶

将所有模型参数和缓冲区移动到 MTIA。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 MTIA 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

named_buffers(prefix='', recurse=True, remove_duplicate=True)¶

返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。

参数

prefix (str) – 要添加到所有缓冲区名称前的字符串前缀。
recurse (bool, optional) – 如果为 True，则生成此模块及其所有子模块的缓冲区。否则，仅生成此模块的直接成员缓冲区。默认为 True。
remove_duplicate (bool, optional) – 是否移除结果中的重复缓冲区。默认为 True。

Yields

(str, torch.Tensor) – 包含名称和缓冲区的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, buf in self.named_buffers():
>>>     if name in ['running_var']:
>>>         print(buf.size())

返回类型: Iterator[Tuple[str, Tensor]]

named_children()¶

返回直接子模块的迭代器，同时产生模块名称和模块本身。

Yields: (str, Module) – 包含名称和子模块的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, module in model.named_children():
>>>     if name in ['conv4', 'conv5']:
>>>         print(module)

返回类型: Iterator[Tuple[str, Module]]

named_modules(memo=None, prefix='', remove_duplicate=True)¶

返回网络中所有模块的迭代器，同时产生模块名称和模块本身。

参数

memo (Optional[Set[Module], None]) – 用于存储已添加到结果中的模块集合的备忘录
prefix (str) – 将添加到模块名称前的字符串前缀
remove_duplicate (bool) – 是否移除结果中重复的模块实例

Yields

(str, Module) – 包含名称和模块的元组

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.named_modules()):
...     print(idx, '->', m)

0 -> ('', Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
))
1 -> ('0', Linear(in_features=2, out_features=2, bias=True))

named_parameters(prefix='', recurse=True, remove_duplicate=True)¶

返回模块参数的迭代器，同时产生参数名称和参数本身。

参数

prefix (str) – 要添加到所有参数名称前的字符串前缀。
recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
remove_duplicate (bool, optional) – 是否移除结果中重复的参数。默认为 True。

Yields

(str, Parameter) – 包含名称和参数的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, param in self.named_parameters():
>>>     if name in ['bias']:
>>>         print(param.size())

返回类型: Iterator[Tuple[str, Parameter]]

on_after_backward()¶

在 loss.backward() 之后且在优化器步进之前调用。

注意

如果使用原生 AMP，此时梯度不会被取消缩放。如果您需要未缩放的梯度，请使用 on_before_optimizer_step。

返回类型: None

on_after_batch_transfer(batch, dataloader_idx)¶

覆盖此方法以在批次转移到设备后修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_after_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = gpu_transforms(batch['x'])
    return batch

另请参阅

on_before_batch_transfer()
transfer_batch_to_device()

on_before_backward(loss)¶

在 loss.backward() 之前调用。

参数: loss (Tensor) – 损失值，除以进行梯度累积的批次数，如果使用 AMP 则会进行缩放。
返回类型: None

on_before_batch_transfer(batch, dataloader_idx)¶

覆盖此方法以在批次转移到设备之前修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_before_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = transforms(batch['x'])
    return batch

另请参阅

on_after_batch_transfer()
transfer_batch_to_device()

on_before_optimizer_step(optimizer)¶

在 optimizer.step() 之前调用。

如果使用梯度累积，此钩子会在梯度累积完成后调用一次。参见：:paramref:`~pytorch_lightning.trainer.trainer.Trainer.accumulate_grad_batches`。

如果使用 AMP，损失值在此钩子调用前会取消缩放。有关梯度缩放的更多信息，请参阅这些文档。

如果进行梯度裁剪，此时梯度尚未被裁剪。

参数: optimizer (Optimizer) – 正在使用的当前优化器。

示例

def on_before_optimizer_step(self, optimizer):
    # example to inspect gradient information in tensorboard
    if self.trainer.global_step % 25 == 0:  # don't make the tf file huge
        for k, v in self.named_parameters():
            self.logger.experiment.add_histogram(
                tag=k, values=v.grad, global_step=self.trainer.global_step
            )

返回类型: None

on_before_zero_grad(optimizer)¶

在 training_step() 之后且在 optimizer.zero_grad() 之前调用。

在训练循环中，在优化器步长后和梯度清零前调用。是检查权重更新后权重信息的好地方。

这里是它被调用的地方

for optimizer in optimizers:
    out = training_step(...)

    model.on_before_zero_grad(optimizer) # < ---- called here
    optimizer.zero_grad()

    backward()

参数: optimizer (Optimizer) – 应清零其梯度的优化器。
返回类型: None

on_fit_end()¶

在 fit 的最后调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

on_fit_start()¶

在 fit 的最开始调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

property on_gpu: bool¶

如果此模型当前位于 GPU 上，则返回 True。

对于在 LightningModule 中设置标志以区分 CPU 和 GPU 的行为很有用。

返回类型: bool

on_load_checkpoint(checkpoint)¶

由 Lightning 调用以恢复您的模型。如果您使用 on_save_checkpoint() 保存了一些东西，这是您恢复它们的机会。

参数: checkpoint (dict[str, Any]) – 已加载的检查点

示例

def on_load_checkpoint(self, checkpoint):
    # 99% of the time you don't need to implement this method
    self.something_cool_i_want_to_save = checkpoint['something_cool_i_want_to_save']

注意

Lightning 会自动恢复全局步长、epoch 和训练状态，包括 amp 缩放。您无需恢复任何与训练相关的内容。

返回类型: None

on_predict_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在预测循环中批次之后调用。

参数

outputs (Optional[Any, None]) – predict_step(x) 的输出
batch (Any) – 预测 DataLoader 返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_batch_start(batch, batch_idx, dataloader_idx=0)¶

在预测循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_end()¶

在预测结束时调用。

返回类型: None

on_predict_epoch_end()¶

在预测结束时调用。

返回类型: None

on_predict_epoch_start()¶

在预测开始时调用。

返回类型: None

on_predict_model_eval()¶

预测循环开始时调用。

预测循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。

返回类型: None

on_predict_start()¶

在预测开始时调用。

返回类型: None

on_save_checkpoint(checkpoint)¶

Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。

参数: checkpoint (dict[str, Any]) – 在检查点字典被写入文件之前的完整字典。此钩子函数的实现可以将额外数据插入此字典。

示例

def on_save_checkpoint(self, checkpoint):
    # 99% of use cases you don't need to implement this method
    checkpoint['something_cool_i_want_to_save'] = my_cool_pickable_object

注意

Lightning 会保存训练的所有方面（周期、全局步数等），包括 amp scaling。您无需存储任何关于训练的内容。

返回类型: None

on_test_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在测试循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – test_step(x) 的输出。
batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_batch_start(batch, batch_idx, dataloader_idx=0)¶

在测试循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_end()¶

在测试结束时调用。

返回类型: None

on_test_epoch_end()¶

在测试循环中 epoch 的最后调用。

返回类型: None

on_test_epoch_start()¶

在测试循环中 epoch 的最开始调用。

返回类型: None

on_test_model_eval()¶

测试循环开始时调用。

测试循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_test_model_train()。

返回类型: None

on_test_model_train()¶

测试循环结束时调用。

测试循环默认将 LightningModule 的 training 模式恢复到开始测试之前的状态。重写此钩子函数以改变此行为。另请参见 on_test_model_eval()。

返回类型: None

on_test_start()¶

在测试开始时调用。

返回类型: None

on_train_batch_end(outputs, batch, batch_idx)¶

在训练循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – training_step(x) 的输出。
batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

注意

此处 outputs["loss"] 的值将是根据 accumulate_grad_batches 对 training_step 返回的损失值进行归一化后的值。

返回类型: None

on_train_batch_start(batch, batch_idx)¶

在训练循环中该批次发生任何事情之前调用。

如果此处返回 -1，将跳过当前周期的剩余训练。

参数

batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

返回类型

Optional[int, None]

on_train_end()¶

在训练结束、logger 实验关闭之前调用。

返回类型: None

on_train_epoch_end()¶

在训练循环中 epoch 的最后调用。

要在周期结束时访问所有批次输出，您可以将步输出缓存为 LightningModule 的属性，并在此钩子函数中访问它们

class MyLightningModule(L.LightningModule):
    def __init__(self):
        super().__init__()
        self.training_step_outputs = []

    def training_step(self):
        loss = ...
        self.training_step_outputs.append(loss)
        return loss

    def on_train_epoch_end(self):
        # do something with all training_step outputs, for example:
        epoch_mean = torch.stack(self.training_step_outputs).mean()
        self.log("training_epoch_mean", epoch_mean)
        # free up the memory
        self.training_step_outputs.clear()

on_train_epoch_start()¶

在训练循环中 epoch 的最开始调用。

返回类型: None

on_train_start()¶

在健全性检查之后、训练开始时调用。

返回类型: None

on_validation_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在验证循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – validation_step(x) 的输出。
batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_batch_start(batch, batch_idx, dataloader_idx=0)¶

在验证循环中该批次发生任何事情之前调用。

参数

batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_end()¶

在验证结束时调用。

返回类型: None

on_validation_epoch_end()¶: 在验证循环中 epoch 的最后调用。

on_validation_epoch_start()¶

在验证循环中 epoch 的最开始调用。

返回类型: None

on_validation_model_eval()¶

验证循环开始时调用。

验证循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_validation_model_train()。

返回类型: None

on_validation_model_train()¶

验证循环结束时调用。

验证循环默认将 LightningModule 的 training 模式恢复到开始验证之前的状态。重写此钩子函数以改变此行为。另请参见 on_validation_model_eval()。

返回类型: None

on_validation_model_zero_grad()¶

由训练循环调用，在进入验证循环之前释放梯度。

返回类型: None

on_validation_start()¶

在验证开始时调用。

返回类型: None

optimizer_step(epoch, batch_idx, optimizer, optimizer_closure=None)¶

覆盖此方法以调整 Trainer 调用优化器的默认方式。

默认情况下，Lightning 会按照示例所示调用 step() 和 zero_grad()。当 Trainer(accumulate_grad_batches != 1) 时，此方法（和 zero_grad()）在累积阶段不会被调用。使用手动优化时，重写此钩子函数没有好处。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Union[Optimizer, LightningOptimizer]) – PyTorch 优化器
optimizer_closure (Optional[Callable[[], Any], None]) – 优化器闭包。必须执行此闭包，因为它包含对 training_step()、optimizer.zero_grad() 和 backward() 的调用。

示例

def optimizer_step(self, epoch, batch_idx, optimizer, optimizer_closure):
    # Add your custom logic to run directly before `optimizer.step()`

    optimizer.step(closure=optimizer_closure)

    # Add your custom logic to run directly after `optimizer.step()`

返回类型: None

optimizer_zero_grad(epoch, batch_idx, optimizer)¶

覆盖此方法以更改 optimizer.zero_grad() 的默认行为。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Optimizer) – PyTorch 优化器

示例

# DEFAULT
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad()

# Set gradients to `None` instead of zero to improve performance (not required on `torch>=2.0.0`).
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad(set_to_none=True)

有关上述示例的解释，请参见 torch.optim.Optimizer.zero_grad()。

返回类型: None

optimizers(use_pl_optimizer=True)¶

返回训练期间使用的优化器。对于手动优化很有用。

参数: use_pl_optimizer (bool) – 如果为 True，则会将优化器封装在 LightningOptimizer 中，以自动处理精度、分析以及步调用计数，从而实现正确的日志记录和检查点。它专门封装 step 方法，不支持没有此方法的自定义优化器。
返回类型: Union[Optimizer, LightningOptimizer, _FabricOptimizer, list[Optimizer], list[LightningOptimizer], list[_FabricOptimizer]]
返回值: 单个优化器，或者在存在多个优化器时返回一个列表。

property output_chunk_length: Optional[int]¶

模型一次预测的时间步长数量。

返回类型: Optional[int, None]

parameters(recurse=True)¶

返回模块参数的迭代器。

这通常传递给优化器。

参数: recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
Yields: Parameter – 模块参数

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for param in model.parameters():
>>>     print(type(param), param.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Parameter]

predict_dataloader()¶

指定预测样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

建议所有数据下载和准备都在 prepare_data() 中进行。

predict()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any
返回值: 一个 torch.utils.data.DataLoader 或其序列，指定预测样本。

predict_step(batch, batch_idx, dataloader_idx=None)¶

执行预测步骤

batch: Darts 的 InferenceDataset 的输出 - 包含 (past_target, past_covariates, historic_future_covariates, future_covariates, future_past_covariates, input time series, prediction start time step) 的元组
batch_idx: 当前批次的批次索引
dataloader_idx: 数据加载器索引

返回类型: Sequence[TimeSeries]

prepare_data()¶

使用此方法下载和准备数据。使用多个进程（分布式设置）下载和保存数据将导致数据损坏。Lightning 确保此方法仅在单个进程中调用，因此您可以安全地在此处添加您的下载逻辑。

警告

不要在此方法中为模型设置状态（请改用 setup 方法），因为此方法不会在每个设备上调用

示例

def prepare_data(self):
    # good
    download_data()
    tokenize()
    etc()

    # bad
    self.split = data_split
    self.some_state = some_other_state()

在分布式环境中，prepare_data 可以通过两种方式调用（使用 prepare_data_per_node）

每个节点一次。这是默认设置，仅在 LOCAL_RANK=0 上调用。
总共一次。仅在 GLOBAL_RANK=0 上调用。

示例

# DEFAULT
# called once per node on LOCAL_RANK=0 of that node
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = True

# call on GLOBAL_RANK=0 (great for shared file systems)
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = False

此方法在请求数据加载器之前调用

model.prepare_data()
initialize_distributed()
model.setup(stage)
model.train_dataloader()
model.val_dataloader()
model.test_dataloader()
model.predict_dataloader()

返回类型: None

print(*args, **kwargs)¶

仅从进程 0 打印。在任何分布式模式下使用此方法以仅记录一次。

参数

*args – 要打印的内容。与 Python 内置的 print 函数相同。
**kwargs – 与 Python 内置的 print 函数相同。

示例

def forward(self, x):
    self.print(x, 'in forward')

返回类型: None

register_backward_hook(hook)¶

在模块上注册后向钩子。

此函数已被弃用，推荐使用 register_full_backward_hook()，此函数的行为将在未来版本中改变。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_buffer(name, tensor, persistent=True)¶

向模块添加缓冲区。

这通常用于注册不应被视为模型参数的缓冲区。例如，BatchNorm 的 running_mean 不是参数，但它是模块状态的一部分。默认情况下，缓冲区是持久的，将与参数一起保存。可以通过将 persistent 设置为 False 来改变此行为。持久缓冲区和非持久缓冲区之间的唯一区别在于，后者不属于此模块的 state_dict。

缓冲区可以使用给定的名称作为属性访问。

参数

name (str) – 缓冲区的名称。可以使用给定的名称从此模块访问缓冲区
tensor (Tensor or None) – 要注册的缓冲区。如果为 None，则对缓冲区执行的操作（例如 cuda）将被忽略。如果为 None，则缓冲区**不**包含在模块的 state_dict 中。
persistent (bool) – 缓冲区是否属于此模块的 state_dict。

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> self.register_buffer('running_mean', torch.zeros(num_features))

返回类型: None

register_forward_hook(hook, *, prepend=False, with_kwargs=False, always_call=False)¶

在模块上注册前向钩子。

每次在 forward() 计算出输出后，此钩子函数都将被调用。

如果 with_kwargs 为 False 或未指定，输入仅包含传递给模块的位置参数。关键字参数不会传递给钩子函数，仅传递给 forward 函数。钩子函数可以修改输出。它可以原地修改输入，但由于此钩子函数在 forward() 调用后被调用，因此对 forward 没有影响。此钩子函数应具有以下签名：

hook(module, args, output) -> None or modified output

如果 with_kwargs 为 True，则前向钩子函数将接收传递给 forward 函数的 kwargs，并预期返回可能修改过的输出。此钩子函数应具有以下签名：

hook(module, args, kwargs, output) -> None or modified output

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 True，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之后触发。请注意，使用 register_module_forward_hook() 注册的全局 forward 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 True，hook 将接收传递给 forward 函数的 kwargs。默认值：False
always_call (bool) – 如果为 True，无论在调用模块时是否引发异常，hook 都将被运行。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_forward_pre_hook(hook, *, prepend=False, with_kwargs=False)¶

在模块上注册前向预钩子。

每次在 forward() 被调用之前，此钩子函数都将被调用。

如果 with_kwargs 为 false 或未指定，输入仅包含传递给模块的位置参数。关键字参数不会传递给钩子函数，仅传递给 forward 函数。钩子函数可以修改输入。用户可以在钩子函数中返回一个元组或单个修改后的值。如果返回单个值（除非该值本身就是一个元组），我们将把该值包装成一个元组。此钩子函数应具有以下签名：

hook(module, args) -> None or modified input

如果 with_kwargs 为 true，则前向预钩子函数将接收传递给 forward 函数的 kwargs。如果钩子函数修改了输入，则应返回 args 和 kwargs。此钩子函数应具有以下签名：

hook(module, args, kwargs) -> None or a tuple of modified input and kwargs

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之后触发。请注意，使用 register_module_forward_pre_hook() 注册的全局 forward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 true，hook 将接收传递给 forward 函数的 kwargs。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_hook(hook, prepend=False)¶

在模块上注册后向钩子。

每当计算相对于模块的梯度时，此钩子函数都将被调用，即只有当计算相对于模块输出的梯度时，此钩子函数才会执行。此钩子函数应具有以下签名：

hook(module, grad_input, grad_output) -> tuple(Tensor) or None

grad_input 和 grad_output 是元组，分别包含相对于输入和输出的梯度。钩子函数不应修改其参数，但可以选择性地返回一个相对于输入的新梯度，该梯度将在后续计算中替换 grad_input。grad_input 仅对应于作为位置参数提供的输入，所有 kwarg 参数都被忽略。grad_input 和 grad_output 中的非 Tensor 参数条目将为 None。

出于技术原因，当此钩子函数应用于 Module 时，其 forward 函数将接收传递给 Module 的每个 Tensor 的视图。类似地，调用者将接收 Module 的 forward 函数返回的每个 Tensor 的视图。

警告

使用后向钩子时，不允许原地修改输入或输出，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之后触发。请注意，使用 register_module_full_backward_hook() 注册的全局 backward 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_pre_hook(hook, prepend=False)¶

在模块上注册后向预钩子。

每当计算模块的梯度时，此钩子函数都将被调用。此钩子函数应具有以下签名：

hook(module, grad_output) -> tuple[Tensor] or None

grad_output 是一个元组。钩子函数不应修改其参数，但可以选择性地返回一个相对于输出的新梯度，该梯度将在后续计算中替换 grad_output。grad_output 中的非 Tensor 参数条目将为 None。

警告

使用后向钩子时，不允许原地修改输入，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之后触发。请注意，使用 register_module_full_backward_pre_hook() 注册的全局 backward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_load_state_dict_post_hook(hook)¶

注册一个后钩子函数，在调用模块的 load_state_dict() 后运行。

它应该具有以下签名：: hook(module, incompatible_keys) -> None

module 参数是此钩子函数注册到的当前模块，incompatible_keys 参数是一个 NamedTuple，包含属性 missing_keys 和 unexpected_keys。missing_keys 是包含缺失键的 str list，unexpected_keys 是包含意外键的 str list。

如有需要，可以原地修改给定的 incompatible_keys。

请注意，如预期所示，调用 load_state_dict() 时使用 strict=True 执行的检查会受到钩子函数对 missing_keys 或 unexpected_keys 的修改的影响。向任一组键中添加内容将在 strict=True 时导致错误，清除缺失和意外键将避免错误。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_load_state_dict_pre_hook(hook)¶

注册一个预钩子函数，在调用模块的 load_state_dict() 之前运行。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata, strict, missing_keys, unexpected_keys, error_msgs) -> None # noqa: B950

参数: hook (Callable) – 可调用钩子函数，将在加载状态字典之前被调用。

register_module(name, module)¶

add_module() 的别名。

返回类型: None

register_parameter(name, param)¶

向模块添加参数。

参数可以使用给定的名称作为属性访问。

参数

name (str) – 参数的名称。可以使用给定的名称从此模块访问参数
param (Parameter or None) – 要添加到模块的参数。如果为 None，则对参数执行的操作（例如 cuda）将被忽略。如果为 None，则参数**不**包含在模块的 state_dict 中。

返回类型

None

register_state_dict_post_hook(hook)¶

为 state_dict() 方法注册一个后钩子。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata) -> None

注册的钩子函数可以原地修改 state_dict。

register_state_dict_pre_hook(hook)¶

为 state_dict() 方法注册一个预钩子。

它应该具有以下签名：: hook(module, prefix, keep_vars) -> None

注册的钩子函数可用于在进行 state_dict 调用之前执行预处理。

requires_grad_(requires_grad=True)¶

更改此模块中是否应记录参数上的自动梯度操作。

此方法原地设置参数的 requires_grad 属性。

此方法有助于冻结模块的一部分用于微调，或单独训练模型的各个部分（例如，GAN 训练）。

有关 .requires_grad_() 和几个可能与其混淆的类似机制的比较，请参见 locally-disable-grad-doc。

参数: requires_grad (bool) – 是否应由 autograd 记录此模块中参数的操作。默认值：True。
返回值: self
返回类型: Module

save_hyperparameters(*args, ignore=None, frame=None, logger=True)¶

将参数保存到 hparams 属性。

参数

args (Any) – 可以是 dict、NameSpace 或 OmegaConf 的单个对象，或来自类 __init__ 的字符串名称或参数
ignore (Union[str, Sequence[str], None]) – 要忽略的来自类 __init__ 的参数名称或参数名称列表
frame (Optional[frame, None]) – 一个 frame 对象。默认值为 None
logger (bool) – 是否将超参数发送到日志记录器。默认值：True

示例：

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # manually assign arguments
...         self.save_hyperparameters('arg1', 'arg3')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class AutomaticArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # equivalent automatic
...         self.save_hyperparameters()
...     def forward(self, *args, **kwargs):
...         ...
>>> model = AutomaticArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg2": abc
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class SingleArgModel(HyperparametersMixin):
...     def __init__(self, params):
...         super().__init__()
...         # manually assign single argument
...         self.save_hyperparameters(params)
...     def forward(self, *args, **kwargs):
...         ...
>>> model = SingleArgModel(Namespace(p1=1, p2='abc', p3=3.14))
>>> model.hparams
"p1": 1
"p2": abc
"p3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # pass argument(s) to ignore as a string or in a list
...         self.save_hyperparameters(ignore='arg2')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

返回类型: None

set_extra_state(state)¶

设置加载的 state_dict 中包含的额外状态。

此函数由 load_state_dict() 调用，用于处理在 state_dict 中找到的任何额外状态。如果需要在模块的 state_dict 中存储额外状态，请实现此函数以及相应的 get_extra_state() 函数。

参数: state (dict) – 来自 state_dict 的额外状态
返回类型: None

set_mc_dropout(active)¶

set_predict_parameters(n, num_samples, roll_size, batch_size, n_jobs, predict_likelihood_parameters, mc_dropout)¶

在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置

返回类型: None

set_submodule(target, module)¶

如果存在，则设置由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

(图示为一个 nn.Module A。A 有一个嵌套子模块 net_b，其本身又有两个子模块 net_c 和 linear。net_c 然后有一个子模块 conv。)

要用一个新的子模块 Linear 覆盖 Conv2d，您可以调用 set_submodule("net_b.net_c.conv", nn.Linear(33, 16))。

参数

target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
module (Module) – 用于设置子模块的模块。

Raises

ValueError – 如果目标字符串为空
AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

返回类型

None

setup(stage)¶

在 fit (训练 + 验证)、validate、test 或 predict 开始时调用。当您需要动态构建模型或调整模型时，这是一个很好的钩子函数。使用 DDP 时，此钩子函数在每个进程上调用。

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'

示例

class LitModel(...):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        download_data()
        tokenize()

        # don't do this
        self.something = else

    def setup(self, stage):
        data = load_data(...)
        self.l1 = nn.Linear(28, data.num_classes)

返回类型: None

share_memory()¶

参见 torch.Tensor.share_memory_()。

返回类型: ~T

state_dict(*args, destination=None, prefix='', keep_vars=False)¶

返回包含模块完整状态引用的字典。

参数和持久缓冲区（例如，运行平均值）都包含在内。键是相应的参数和缓冲区名称。设置为 None 的参数和缓冲区不包含在内。

注意

返回的对象是浅拷贝。它包含对模块参数和缓冲区的引用。

警告

目前 state_dict() 也按顺序接受 destination、prefix 和 keep_vars 的位置参数。但是，此用法已被弃用，未来版本将强制使用关键字参数。

警告

请避免使用参数 destination，因为它并非为终端用户设计。

参数

destination (dict, optional) – 如果提供，模块的状态将更新到此字典中，并返回相同的对象。否则，将创建一个 OrderedDict 并返回。默认值：None。
prefix (str, optional) – 添加到参数和缓冲区名称的前缀，用于在 state_dict 中构成键。默认值：''。
keep_vars (bool, optional) – 默认情况下，state dict 中返回的 Tensor s 与 autograd 分离。如果设置为 True，将不会进行分离。默认值：False。

返回值

包含模块完整状态的字典

返回类型

dict

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> module.state_dict().keys()
['bias', 'weight']

property strict_loading: bool¶

确定 Lightning 如何使用 .load_state_dict(…, strict=model.strict_loading) 加载此模型。

返回类型: bool

property supports_probabilistic_prediction: bool¶

返回类型: bool

teardown(stage)¶

在 fit（训练 + 验证）、验证、测试或预测结束时调用。

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'
返回类型: None

test_dataloader()¶

指定测试样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

test()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果您不需要测试数据集和 test_step()，则无需实现此方法。

返回类型: Any

test_step(*args, **kwargs)¶

对测试集中的单个批次数据进行操作。在此步骤中，您通常会生成示例或计算任何感兴趣的内容，例如准确率。

参数

batch – 您的数据可迭代对象（通常是 DataLoader）的输出。
batch_idx – 此批次的索引。
dataloader_idx – 生成此批次的数据加载器索引。（仅在使用多个数据加载器时）

返回类型

Union[Tensor, Mapping[str, Any], None]

返回值

Tensor - 损失张量
dict - 字典。可以包含任意键，但必须包含键 'loss'。
None - 跳到下一个批次。

# if you have one test dataloader:
def test_step(self, batch, batch_idx): ...

# if you have multiple test dataloaders:
def test_step(self, batch, batch_idx, dataloader_idx=0): ...

示例

# CASE 1: A single test dataset
def test_step(self, batch, batch_idx):
    x, y = batch

    # implement your own
    out = self(x)
    loss = self.loss(out, y)

    # log 6 example images
    # or generated text... or whatever
    sample_imgs = x[:6]
    grid = torchvision.utils.make_grid(sample_imgs)
    self.logger.experiment.add_image('example_images', grid, 0)

    # calculate acc
    labels_hat = torch.argmax(out, dim=1)
    test_acc = torch.sum(y == labels_hat).item() / (len(y) * 1.0)

    # log the outputs!
    self.log_dict({'test_loss': loss, 'test_acc': test_acc})

如果您传入多个测试数据加载器，test_step() 将有一个额外的参数。建议将默认值设置为 0，以便您可以在单个和多个数据加载器之间快速切换。

# CASE 2: multiple test dataloaders
def test_step(self, batch, batch_idx, dataloader_idx=0):
    # dataloader_idx tells you which dataset this is.
    ...

注意

如果您不需要测试，则无需实现此方法。

注意

调用 test_step() 时，模型已处于评估模式，并且 PyTorch 梯度已禁用。在测试周期结束时，模型会恢复训练模式，并启用梯度。

to(*args, **kwargs)¶

参见 torch.nn.Module.to()。

返回类型: Self

to_dtype(dtype)¶: 将模块精度（默认为 float32）转换为其他精度。

to_empty(*, device, recurse=True)¶

在不复制存储的情况下，将参数和缓冲区移动到指定设备。

参数

device (torch.device) – 此模块中参数和缓冲区的目标设备。
recurse (bool) – 是否应将子模块的参数和缓冲区递归地移动到指定设备。

返回值

self

返回类型

Module

to_onnx(file_path, input_sample=None, **kwargs)¶

将模型保存为 ONNX 格式。

参数

file_path (Union[str, Path, BytesIO]) – 应保存 onnx 模型的文件路径。
input_sample (Optional[Any, None]) – 用于跟踪的输入。默认值：None（使用 self.example_input_array）
**kwargs – 将传递给 torch.onnx.export 函数。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)

model = SimpleModel()
input_sample = torch.randn(1, 64)
model.to_onnx("export.onnx", input_sample, export_params=True)

返回类型: None

to_torchscript(file_path=None, method='script', example_inputs=None, **kwargs)¶

默认将整个模型编译为 ScriptModule。如果您想使用 tracing，请提供参数 method='trace' 并确保提供了 example_inputs 参数，或者模型已设置 example_input_array。如果您想自定义要脚本化的模块，应重写此方法。如果您想返回多个模块，建议使用字典。

参数

file_path (Union[str, Path, None]) – 保存 torchscript 的路径。默认值：None（不保存文件）。
method (Optional[str, None]) – 是使用 TorchScript 的 script 方法还是 trace 方法。默认值：‘script’
example_inputs (Optional[Any, None]) – 当 method 设置为 ‘trace’ 时用于进行 tracing 的输入。默认值：None（使用 example_input_array）
**kwargs – 将传递给 torch.jit.script() 或 torch.jit.trace() 函数的附加参数。

注意

需要实现 forward() 方法。
导出的脚本将被设置为评估模式。
建议您安装最新支持版本的 PyTorch 以无限制地使用此功能。另请参见 torch.jit 文档以了解支持的功能。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)))

model = SimpleModel()
model.to_torchscript(file_path="model.pt")

torch.jit.save(model.to_torchscript(
    file_path="model_trace.pt", method='trace', example_inputs=torch.randn(1, 64))
)

返回类型: Union[ScriptModule, dict[str, ScriptModule]]
返回值: 此 LightningModule 作为 torchscript，无论是否定义了 file_path。

toggle_optimizer(optimizer)¶

确保在训练步骤中仅计算当前优化器参数的梯度，以防止在多优化器设置中出现悬空梯度。

它与 untoggle_optimizer() 配合使用，以确保 param_requires_grad_state 正确重置。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要切换的优化器。
返回类型: None

train(mode=True)¶

将模块设置为训练模式。

这仅对某些模块有影响。有关它们在训练/评估模式下的行为详情，例如它们是否受影响（例如 Dropout、BatchNorm 等），请参阅特定模块的文档。

参数: mode (bool) – 是否设置训练模式 (True) 或评估模式 (False)。默认值: True。
返回值: self
返回类型: Module

train_dataloader()¶

指定训练样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

你返回的数据加载器将不会重新加载，除非你将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为一个正整数。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

fit()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any

属性 trainer: Trainer¶

返回类型: Trainer

training: bool¶

training_step(train_batch, batch_idx)¶

执行训练步骤

返回类型: Tensor

transfer_batch_to_device(batch, device, dataloader_idx)¶

如果您的 DataLoader 返回包装在自定义数据结构中的张量，请覆盖此钩子。

下面列出的数据类型（以及它们的任意嵌套）是开箱即用的支持

torch.Tensor 或任何实现了 .to(…) 的东西
list
dict
tuple

对于其他任何东西，你需要定义数据如何移动到目标设备 (CPU, GPU, TPU, …)。

注意

这个钩子应该只传输数据而不修改它，也不应该将数据移动到作为参数传入的设备之外的任何其他设备（除非你知道自己在做什么）。要检查这个钩子的当前执行状态，你可以使用 self.trainer.training/testing/validating/predicting，以便你可以根据你的需求添加不同的逻辑。

参数

batch (Any) – 需要转移到新设备的数据批次。
device (device) – PyTorch 中定义的目标设备。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据在新设备上的引用。

示例

def transfer_batch_to_device(self, batch, device, dataloader_idx):
    if isinstance(batch, CustomBatch):
        # move all tensors in your custom data structure to the device
        batch.samples = batch.samples.to(device)
        batch.targets = batch.targets.to(device)
    elif dataloader_idx == 0:
        # skip device transfer for the first dataloader or anything you wish
        pass
    else:
        batch = super().transfer_batch_to_device(batch, device, dataloader_idx)
    return batch

另请参阅

move_data_to_device()
apply_to_collection()

type(dst_type)¶

参见 torch.nn.Module.type()。

返回类型: Self

unfreeze()¶

解冻所有参数以进行训练。

model = MyLightningModule(...)
model.unfreeze()

返回类型: None

untoggle_optimizer(optimizer)¶

重置使用 toggle_optimizer() 切换的所需梯度的状态。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要取消切换的优化器。
返回类型: None

val_dataloader()¶

指定验证样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

你返回的数据加载器将不会重新加载，除非你将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为一个正整数。

建议所有数据下载和准备都在 prepare_data() 中进行。

fit()
validate()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果你不需要验证数据集和 validation_step()，你无需实现此方法。

返回类型: Any

validation_step(val_batch, batch_idx)¶

执行验证步骤

返回类型: Tensor

xpu(device=None)¶

将所有模型参数和缓冲区移动到 XPU。

这也会使得相关的参数和缓冲区成为不同的对象。因此，如果模块将在 XPU 上运行并进行优化，则应该在构建优化器之前调用它。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

zero_grad(set_to_none=True)¶

重置所有模型参数的梯度。

请参阅 torch.optim.Optimizer 下的类似函数，了解更多背景信息。

参数: set_to_none (bool) – 不设置为零，而是将梯度设置为 None。请参阅 torch.optim.Optimizer.zero_grad() 了解详情。
返回类型: None

类 darts.models.forecasting.pl_forecasting_module.PLForecastingModule(input_chunk_length, output_chunk_length, output_chunk_shift=0, train_sample_shape=None, loss_fn=MSELoss(), torch_metrics=None, likelihood=None, optimizer_cls=<class 'torch.optim.adam.Adam'>, optimizer_kwargs=None, lr_scheduler_cls=None, lr_scheduler_kwargs=None, use_reversible_instance_norm=False)[source]¶

基类: LightningModule, ABC

基于 PyTorch Lightning 的预测模块。

此类旨在被继承以创建新的基于 PyTorch Lightning 的预测模块。子类化此类时，请确保添加具有以下签名的方

PLForecastingModule.__init__()

PLForecastingModule.forward()

PLForecastingModule._process_input_batch()

PLForecastingModule._produce_train_output()

PLForecastingModule._get_batch_prediction()

在子类 MyModel 的 __init__() 函数中调用 super(MyModel, self).__init__(**kwargs)，其中 kwargs 是 PLForecastingModule 的参数。

参数

input_chunk_length (int) – 模型输入的时间步长数量（每块）。适用于目标序列以及过去和/或未来协变量（如果模型支持）。
output_chunk_length (int) – 内部模型一次预测（每块）的时间步长数量。此外，未来协变量的未来值用作模型输入的数量（如果模型支持未来协变量）。它与 predict() 中使用的预测视野 n 不同，后者是使用一次性预测或自回归预测生成的所需预测点数。设置 n <= output_chunk_length 可防止自回归。当协变量未能充分延伸到未来时，这非常有用，或者为了禁止模型使用过去和/或未来协变量的未来值进行预测（取决于模型的协变量支持）。
train_sample_shape (Optional[tuple, None]) – 模型的输入形状，用于在不调用 fit_from_dataset 的情况下实例化模型，并对用于重新训练或预测的新训练/推理数据集执行健全性检查。
loss_fn (_Loss) – 用于训练的 PyTorch 损失函数。如果指定了 likelihood 参数，则此参数对于概率模型将被忽略。默认值：torch.nn.MSELoss()。
torch_metrics (Union[Metric, MetricCollection, None]) – 用于评估的 torch 指标或 MetricCollection。可在 https://torchmetrics.readthedocs.io/en/latest/ 找到可用指标的完整列表。默认值：None。
likelihood (Optional[TorchLikelihood, None]) – Darts 的 Likelihood 模型之一，用于概率预测。默认值：None。
optimizer_cls (Optimizer) – 要使用的 PyTorch 优化器类。默认值：torch.optim.Adam。
optimizer_kwargs (Optional[dict, None]) – 可选地，PyTorch 优化器的一些关键字参数（例如，{'lr': 1e-3} 用于指定学习率）。否则将使用选定的 optimizer_cls 的默认值。默认值：None。
lr_scheduler_cls (Optional[_LRScheduler, None]) – 可选地，要使用的 PyTorch 学习率调度器类。指定 None 对应于使用恒定学习率。默认值：None。
lr_scheduler_kwargs (Optional[dict, None]) – 可选地，PyTorch 学习率调度器的一些关键字参数。默认值：None。
use_reversible_instance_norm (bool) – 是否使用可逆实例归一化 RINorm 以对抗分布偏移，如 [1] 中所示。它仅应用于目标序列的特征，而不应用于协变量。

参考

1: T. Kim et al. “Reversible Instance Normalization for Accurate Time-Series Forecasting against Distribution Shift”, https://openreview.net/forum?id=cGDAkQo1C0p

属性

`automatic_optimization`	如果设置为 `False`，则您负责调用 `.backward()`, `.step()`, `.zero_grad()`。
`current_epoch`	`Trainer` 中的当前 epoch，如果未附加则为 0。
`device_mesh`	`ModelParallelStrategy` 等策略将创建设备网格，可在 `configure_model()` 钩子中访问该网格以并行化 LightningModule。
`example_input_array`	示例输入数组是关于模块在 `forward()` 方法中可以消费的内容的规范。
`global_rank`	当前进程在所有节点和设备中的索引。
`global_step`	所有 epoch 中看到的总训练批次。
`hparams`	使用 `save_hyperparameters()` 保存的超参数的集合。
`hparams_initial`	使用 `save_hyperparameters()` 保存的超参数的集合。
`local_rank`	当前进程在单个节点内的索引。
`logger`	指向 Trainer 中 logger 对象的引用。
`loggers`	指向 Trainer 中 loggers 列表的引用。
`on_gpu`	如果此模型当前位于 GPU 上，则返回 `True`。
`output_chunk_length`	模型一次预测的时间步长数量。
`strict_loading`	确定 Lightning 如何使用 .load_state_dict(..., strict=model.strict_loading) 加载此模型。

device
dtype
epochs_trained
fabric
supports_probabilistic_prediction
trainer

方法

`add_module`(name, module)	向当前模块添加子模块。
`all_gather`(data[, group, sync_grads])	从多个进程聚合张量或张量集合。
`apply`(fn)	将 `fn` 递归地应用于每个子模块（由 `.children()` 返回）以及自身。
`backward`(loss, args, *kwargs)	用于对 `training_step()` 返回的损失执行反向传播。
`bfloat16`()	将所有浮点参数和缓冲区转换为 `bfloat16` 数据类型。
`buffers`([recurse])	返回模块缓冲区的迭代器。
`children`()	返回直接子模块的迭代器。
`clip_gradients`(optimizer[, ...])	内部处理梯度裁剪。
`compile`(args, *kwargs)	使用 `torch.compile()` 编译此模块的前向传播。
`configure_callbacks`()	配置模型特定的回调。
`configure_gradient_clipping`(optimizer[, ...])	对优化器参数执行梯度裁剪。
`configure_model`()	在策略和精度感知上下文中创建模块的钩子。
`configure_optimizers`()	配置用于模型优化的优化器和学习率调度器。
`configure_sharded_model`()	已弃用。
`configure_torch_metrics`(torch_metrics)	处理 torch_metrics 参数。
`cpu`()	参见 `torch.nn.Module.cpu()`。
`cuda`([device])	将所有模型参数和缓冲区移动到 GPU。
`double`()	参见 `torch.nn.Module.double()`。
`eval`()	将模块设置为评估模式。
`extra_repr`()	返回模块的额外表示。
`float`()	参见 `torch.nn.Module.float()`。
`forward`(args, *kwargs)	与 `torch.nn.Module.forward()` 相同。
`freeze`()	冻结所有参数以进行推理。
`get_buffer`(target)	如果存在，则返回由 `target` 指定的缓冲区，否则抛出错误。
`get_extra_state`()	返回要包含在模块 state_dict 中的任何额外状态。
`get_parameter`(target)	如果存在，则返回由 `target` 指定的参数，否则抛出错误。
`get_submodule`(target)	如果存在，则返回由 `target` 指定的子模块，否则抛出错误。
`half`()	参见 `torch.nn.Module.half()`。
`ipu`([device])	将所有模型参数和缓冲区移动到 IPU。
`load_from_checkpoint`(checkpoint_path[, ...])	从检查点加载模型的主要方式。
`load_state_dict`(state_dict[, strict, assign])	将参数和缓冲区从 `state_dict` 复制到此模块及其子孙模块中。
`log`(name, value[, prog_bar, logger, ...])	记录键值对。
`log_dict`(dictionary[, prog_bar, logger, ...])	一次记录字典中的值。
`lr_scheduler_step`(scheduler, metric)	覆盖此方法以调整 `Trainer` 调用每个调度器的默认方式。
`lr_schedulers`()	返回训练期间使用的学习率调度器。
`manual_backward`(loss, args, *kwargs)	手动进行优化时，直接从你的 `training_step()` 调用此方法。
`modules`()	返回网络中所有模块的迭代器。
`mtia`([device])	将所有模型参数和缓冲区移动到 MTIA。
`named_buffers`([prefix, recurse, ...])	返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。
`named_children`()	返回直接子模块的迭代器，同时产生模块名称和模块本身。
`named_modules`([memo, prefix, remove_duplicate])	返回网络中所有模块的迭代器，同时产生模块名称和模块本身。
`named_parameters`([prefix, recurse, ...])	返回模块参数的迭代器，同时产生参数名称和参数本身。
`on_after_backward`()	在 `loss.backward()` 之后且在优化器步进之前调用。
`on_after_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备后修改或应用批次增强。
`on_before_backward`(loss)	在 `loss.backward()` 之前调用。
`on_before_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备之前修改或应用批次增强。
`on_before_optimizer_step`(optimizer)	在 `optimizer.step()` 之前调用。
`on_before_zero_grad`(optimizer)	在 `training_step()` 之后且在 `optimizer.zero_grad()` 之前调用。
`on_fit_end`()	在 fit 的最后调用。
`on_fit_start`()	在 fit 的最开始调用。
`on_load_checkpoint`(checkpoint)	由 Lightning 调用以恢复您的模型。
`on_predict_batch_end`(outputs, batch, batch_idx)	在预测循环中批次之后调用。
`on_predict_batch_start`(batch, batch_idx[, ...])	在预测循环中该批次发生任何事情之前调用。
`on_predict_end`()	在预测结束时调用。
`on_predict_epoch_end`()	在预测结束时调用。
`on_predict_epoch_start`()	在预测开始时调用。
`on_predict_model_eval`()	预测循环开始时调用。
`on_predict_start`()	在预测开始时调用。
`on_save_checkpoint`(checkpoint)	Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。
`on_test_batch_end`(outputs, batch, batch_idx)	在测试循环中批次之后调用。
`on_test_batch_start`(batch, batch_idx[, ...])	在测试循环中该批次发生任何事情之前调用。
`on_test_end`()	在测试结束时调用。
`on_test_epoch_end`()	在测试循环中 epoch 的最后调用。
`on_test_epoch_start`()	在测试循环中 epoch 的最开始调用。
`on_test_model_eval`()	测试循环开始时调用。
`on_test_model_train`()	测试循环结束时调用。
`on_test_start`()	在测试开始时调用。
`on_train_batch_end`(outputs, batch, batch_idx)	在训练循环中批次之后调用。
`on_train_batch_start`(batch, batch_idx)	在训练循环中该批次发生任何事情之前调用。
`on_train_end`()	在训练结束、logger 实验关闭之前调用。
`on_train_epoch_end`()	在训练循环中 epoch 的最后调用。
`on_train_epoch_start`()	在训练循环中 epoch 的最开始调用。
`on_train_start`()	在健全性检查之后、训练开始时调用。
`on_validation_batch_end`(outputs, batch, ...)	在验证循环中批次之后调用。
`on_validation_batch_start`(batch, batch_idx)	在验证循环中该批次发生任何事情之前调用。
`on_validation_end`()	在验证结束时调用。
`on_validation_epoch_end`()	在验证循环中 epoch 的最后调用。
`on_validation_epoch_start`()	在验证循环中 epoch 的最开始调用。
`on_validation_model_eval`()	验证循环开始时调用。
`on_validation_model_train`()	验证循环结束时调用。
`on_validation_model_zero_grad`()	由训练循环调用，在进入验证循环之前释放梯度。
`on_validation_start`()	在验证开始时调用。
`optimizer_step`(epoch, batch_idx, optimizer)	覆盖此方法以调整 `Trainer` 调用优化器的默认方式。
`optimizer_zero_grad`(epoch, batch_idx, optimizer)	覆盖此方法以更改 `optimizer.zero_grad()` 的默认行为。
`optimizers`([use_pl_optimizer])	返回训练期间使用的优化器。
`parameters`([recurse])	返回模块参数的迭代器。
`predict_dataloader`()	指定预测样本的可迭代对象或可迭代对象集合。
`predict_step`(batch, batch_idx[, dataloader_idx])	执行预测步骤
`prepare_data`()	使用此方法下载和准备数据。
`print`(args, *kwargs)	仅从进程 0 打印。
`register_backward_hook`(hook)	在模块上注册后向钩子。
`register_buffer`(name, tensor[, persistent])	向模块添加缓冲区。
`register_forward_hook`(hook, *[, prepend, ...])	在模块上注册前向钩子。
`register_forward_pre_hook`(hook, *[, ...])	在模块上注册前向预钩子。
`register_full_backward_hook`(hook[, prepend])	在模块上注册后向钩子。
`register_full_backward_pre_hook`(hook[, prepend])	在模块上注册后向预钩子。
`register_load_state_dict_post_hook`(hook)	注册一个后钩子，该钩子在模块的 `load_state_dict()` 被调用后运行。
`register_load_state_dict_pre_hook`(hook)	注册一个预钩子，该钩子在模块的 `load_state_dict()` 被调用前运行。
`register_module`(name, module)	`add_module()` 的别名。
`register_parameter`(name, param)	向模块添加参数。
`register_state_dict_post_hook`(hook)	为 `state_dict()` 方法注册一个后钩子。
`register_state_dict_pre_hook`(hook)	为 `state_dict()` 方法注册一个预钩子。
`requires_grad_`([requires_grad])	更改此模块中是否应记录参数上的自动梯度操作。
`save_hyperparameters`(*args[, ignore, frame, ...])	将参数保存到 `hparams` 属性。
`set_extra_state`(state)	设置加载的 state_dict 中包含的额外状态。
`set_predict_parameters`(n, num_samples, ...)	在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置
`set_submodule`(target, module)	如果存在，则设置由 `target` 指定的子模块，否则抛出错误。
`setup`(stage)	在 fit（训练 + 验证）、验证、测试或预测开始时调用。
`share_memory`()	参见 `torch.Tensor.share_memory_()`。
`state_dict`(*args[, destination, prefix, ...])	返回包含模块完整状态引用的字典。
`teardown`(stage)	在 fit（训练 + 验证）、验证、测试或预测结束时调用。
`test_dataloader`()	指定测试样本的可迭代对象或可迭代对象集合。
`test_step`(args, *kwargs)	处理测试集中的单个批次数据。
`to`(args, *kwargs)	参见 `torch.nn.Module.to()`。
`to_dtype`(dtype)	将模块精度（默认为 float32）转换为其他精度。
`to_empty`(*, device[, recurse])	在不复制存储的情况下，将参数和缓冲区移动到指定设备。
`to_onnx`(file_path[, input_sample])	将模型保存为 ONNX 格式。
`to_torchscript`([file_path, method, ...])	默认情况下，将整个模型编译为 `ScriptModule`。
`toggle_optimizer`(optimizer)	确保在训练步骤中仅计算当前优化器参数的梯度，以防止多优化器设置中出现悬空梯度。
`train`([mode])	将模块设置为训练模式。
`train_dataloader`()	指定训练样本的可迭代对象或可迭代对象集合。
`training_step`(train_batch, batch_idx)	执行训练步骤
`transfer_batch_to_device`(batch, device, ...)	如果您的 `DataLoader` 返回包装在自定义数据结构中的张量，请覆盖此钩子。
`type`(dst_type)	参见 `torch.nn.Module.type()`。
`unfreeze`()	解冻所有参数以进行训练。
`untoggle_optimizer`(optimizer)	重置使用 `toggle_optimizer()` 切换的所需梯度的状态。
`val_dataloader`()	指定验证样本的可迭代对象或可迭代对象集合。
`validation_step`(val_batch, batch_idx)	执行验证步骤
`xpu`([device])	将所有模型参数和缓冲区移动到 XPU。
`zero_grad`([set_to_none])	重置所有模型参数的梯度。

__call__
set_mc_dropout

CHECKPOINT_HYPER_PARAMS_KEY = 'hyper_parameters'¶

CHECKPOINT_HYPER_PARAMS_NAME = 'hparams_name'¶

CHECKPOINT_HYPER_PARAMS_TYPE = 'hparams_type'¶

T_destination¶: TypeVar(‘T_destination’, bound=Dict[str, Any]) 的别名

add_module(name, module)¶

向当前模块添加子模块。

模块可以使用给定的名称作为属性访问。

参数

name (str) – 子模块的名称。可以使用此名称从当前模块访问子模块
module (Module) – 要添加到模块的子模块。

返回类型

None

all_gather(data, group=None, sync_grads=False)¶

从多个进程聚合张量或张量集合。

此方法需要在所有进程上调用，并且张量需要在所有进程上具有相同的形状，否则您的程序将永远暂停。

参数

data (Union[Tensor, dict, list, tuple]) – int、float、形状为 (batch, …) 的张量，或其（可能嵌套的）集合。
group (Optional[Any, None]) – 要从中收集结果的进程组。默认为所有进程 (world)。
sync_grads (bool) – 允许用户同步 all_gather 操作的梯度的标志。

返回类型

Union[Tensor, dict, list, tuple]

返回值

形状为 (world_size, batch, …) 的张量，如果输入是集合，则输出也将是包含此形状张量的集合。对于 world_size 为 1 的特殊情况，不会向张量添加额外维度。

apply(fn)¶

将 fn 递归地应用于每个子模块（由 .children() 返回）以及自身。

典型用法包括初始化模型的参数（另见 nn-init-doc）。

参数: fn (Module -> None) – 要应用于每个子模块的函数
返回值: self
返回类型: Module

示例

>>> @torch.no_grad()
>>> def init_weights(m):
>>>     print(m)
>>>     if type(m) == nn.Linear:
>>>         m.weight.fill_(1.0)
>>>         print(m.weight)
>>> net = nn.Sequential(nn.Linear(2, 2), nn.Linear(2, 2))
>>> net.apply(init_weights)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)

属性 automatic_optimization: bool¶

如果设置为 False，则您负责调用 .backward(), .step(), .zero_grad()。

返回类型: bool

backward(loss, *args, **kwargs)¶

用于对 training_step() 返回的损失执行反向传播。如果需要，请用你自己的实现覆盖此钩子。

参数: loss (Tensor) – 由 training_step() 返回的损失张量。如果使用梯度累积，这里的损失持有归一化值（按 1 / 累积步数进行缩放）。

示例

def backward(self, loss):
    loss.backward()

返回类型: None

bfloat16()¶

将所有浮点参数和缓冲区转换为 bfloat16 数据类型。

注意

此方法会修改模块本身。

返回值: self
返回类型: Module

buffers(recurse=True)¶

返回模块缓冲区的迭代器。

参数: recurse (bool) – 如果为 True，则产生此模块和所有子模块的缓冲区。否则，仅产生此模块的直接成员缓冲区。
Yields: torch.Tensor – 模块缓冲区

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for buf in model.buffers():
>>>     print(type(buf), buf.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Tensor]

call_super_init: bool = False¶

children()¶

返回直接子模块的迭代器。

Yields: Module – 子模块
返回类型: Iterator[Module]

clip_gradients(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

内部处理梯度裁剪。

注意

不要重写此方法。如果你想自定义梯度裁剪，考虑使用 configure_gradient_clipping() 方法。
对于手动优化 (self.automatic_optimization = False)，如果要使用梯度裁剪，请考虑在训练步骤中手动调用 self.clip_gradients(opt, gradient_clip_val=0.5, gradient_clip_algorithm="norm")。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 裁剪梯度的值。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。传递 gradient_clip_algorithm="value" 按值裁剪，传递 gradient_clip_algorithm="norm" 按范数裁剪。

返回类型

None

compile(*args, **kwargs)¶

使用 torch.compile() 编译此模块的前向传播。

此模块的 __call__ 方法将被编译，并且所有参数将原样传递给 torch.compile()。

有关此函数的参数详细信息，请参见 torch.compile()。

configure_callbacks()¶

返回类型: Union[Sequence[Callback], Callback]
返回值: 一个或多个回调，它们将扩展 Trainer 中的回调列表。

示例

def configure_callbacks(self):
    early_stop = EarlyStopping(monitor="val_acc", mode="max")
    checkpoint = ModelCheckpoint(monitor="val_loss")
    return [early_stop, checkpoint]

configure_gradient_clipping(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

为优化器参数执行梯度裁剪。在 optimizer_step() 之前调用。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 裁剪梯度的值。默认情况下，传入 Trainer 的值将在此处可用。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。默认情况下，Trainer 中传入的值将在此处可用。

示例

def configure_gradient_clipping(self, optimizer, gradient_clip_val, gradient_clip_algorithm):
    # Implement your own custom logic to clip gradients
    # You can call `self.clip_gradients` with your settings:
    self.clip_gradients(
        optimizer,
        gradient_clip_val=gradient_clip_val,
        gradient_clip_algorithm=gradient_clip_algorithm
    )

返回类型: None

configure_model()¶

在策略和精度感知上下文中创建模块的钩子。

此钩子在同一进程的 fit/val/test/predict 各阶段都会被调用，因此请确保此钩子的实现是幂等的，即在第一次调用此钩子后，后续调用应该是空操作。

返回类型: None

configure_optimizers()[source]¶: 配置用于模型优化的优化器和学习率调度器。

configure_sharded_model()¶

已弃用。

请改用 configure_model()。

返回类型: None

静态 configure_torch_metrics(torch_metrics)[source]¶

处理 torch_metrics 参数。

返回类型: MetricCollection

cpu()¶

参见 torch.nn.Module.cpu()。

返回类型: Self

cuda(device=None)¶

参数: device (Union[int, device, None]) – 如果指定，所有参数将被复制到该设备。如果为 None，将使用当前的 CUDA 设备索引。
返回值: self
返回类型: Module

属性 current_epoch: int¶

Trainer 中的当前 epoch，如果未附加则为 0。

返回类型: int

属性 device: device¶

返回类型: device

属性 device_mesh: Optional[DeviceMesh]¶

ModelParallelStrategy 等策略将创建设备网格，可在 configure_model() 钩子中访问该网格以并行化 LightningModule。

返回类型: Optional[ForwardRef, None]

double()¶

参见 torch.nn.Module.double()。

返回类型: Self

属性 dtype: Union[str, dtype]¶

返回类型: Union[str, dtype]

dump_patches: bool = False¶

属性 epochs_trained¶

eval()¶

将模块设置为评估模式。

这仅对某些模块有效。有关特定模块在训练/评估模式下的行为详情，即它们是否受到影响，请参阅其文档，例如 Dropout、BatchNorm 等。

这等同于 self.train(False)。

有关 .eval() 与可能与其混淆的几个类似机制之间的比较，请参见 locally-disable-grad-doc。

返回值: self
返回类型: Module

属性 example_input_array: Optional[Union[Tensor, tuple, dict]]¶

示例输入数组是关于模块在 forward() 方法中可以消费的内容的规范。返回类型解释如下

单个张量：假定模型接受一个参数，即 model.forward(model.example_input_array)
元组：输入数组应被解释为位置参数序列，即 model.forward(*model.example_input_array)
字典：输入数组表示命名关键字参数，即 model.forward(**model.example_input_array)

返回类型: Union[Tensor, tuple, dict, None]

extra_repr()¶

返回模块的额外表示。

要打印自定义的额外信息，您应该在自己的模块中重新实现此方法。单行和多行字符串都可接受。

返回类型: str

属性 fabric: Optional[Fabric]¶

返回类型: Optional[Fabric, None]

float()¶

参见 torch.nn.Module.float()。

返回类型: Self

抽象 forward(*args, **kwargs)[source]¶

与 torch.nn.Module.forward() 相同。

参数

*args – 您决定传递给 forward 方法的任何内容。
**kwargs – 关键字参数也是可以的。

返回类型

Any

返回值

您的模型的输出

freeze()¶

冻结所有参数以进行推理。

示例

model = MyLightningModule(...)
model.freeze()

返回类型: None

get_buffer(target)¶

如果存在，则返回由 target 指定的缓冲区，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的缓冲区的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的缓冲区
返回类型: torch.Tensor
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是缓冲区

get_extra_state()¶

返回要包含在模块 state_dict 中的任何额外状态。

如果你的模块需要存储额外状态，请实现此方法以及相应的 set_extra_state()。此函数在构建模块的 state_dict() 时调用。

返回值: 要存储在模块 state_dict 中的任何额外状态
返回类型: object

get_parameter(target)¶

如果存在，则返回由 target 指定的参数，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的参数的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的参数
返回类型: torch.nn.Parameter
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Parameter

get_submodule(target)¶

如果存在，则返回由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

（图表显示了一个 nn.Module A。 A 有一个嵌套子模块 net_b，它本身有两个子模块 net_c 和 linear。 net_c 还有一个子模块 conv。）

要检查是否存在 linear 子模块，我们可以调用 get_submodule("net_b.linear")。要检查是否存在 conv 子模块，我们可以调用 get_submodule("net_b.net_c.conv")。

参数: target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
返回值: target 引用的子模块
返回类型: torch.nn.Module
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

属性 global_rank: int¶

当前进程在所有节点和设备中的索引。

返回类型: int

属性 global_step: int¶

所有 epoch 中看到的总训练批次。

如果未附加 Trainer，此属性值为 0。

返回类型: int

half()¶

参见 torch.nn.Module.half()。

返回类型: Self

属性 hparams: Union[AttributeDict, MutableMapping]¶

使用 save_hyperparameters() 保存的超参数的集合。用户可以修改它。对于初始超参数的冻结集合，使用 hparams_initial。

返回类型: Union[AttributeDict, MutableMapping]
返回值: 可变的超参数字典

属性 hparams_initial: AttributeDict¶

使用 save_hyperparameters() 保存的超参数的集合。这些内容是只读的。对已保存超参数的手动更新可以通过 hparams 进行。

返回值: 不可变初始超参数
返回类型: AttributeDict

ipu(device=None)¶

将所有模型参数和缓冲区移动到 IPU。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 IPU 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

load_from_checkpoint(checkpoint_path, map_location=None, hparams_file=None, strict=None, **kwargs)¶

从检查点加载模型的主要方式。当 Lightning 保存检查点时，它会将传递给 __init__ 的参数存储在检查点中的 "hyper_parameters" 下。

通过 **kwargs 指定的任何参数将覆盖存储在 "hyper_parameters" 中的参数。

参数

checkpoint_path (Union[str, Path, IO]) – 检查点路径。这也可以是 URL 或文件类对象
map_location (Union[device, str, int, Callable[[UntypedStorage, str], Optional[UntypedStorage, None]], dict[Union[device, str, int], Union[device, str, int]], None]) – 如果您的检查点保存的是 GPU 模型，而您现在在 CPU 或不同数量的 GPU 上加载，请使用此参数映射到新的配置。其行为与 torch.load() 中相同。
hparams_file (Union[str, Path, None]) –
可选的 .yaml 或 .csv 文件路径，其结构如下例所示
```
drop_prob: 0.2
dataloader:
    batch_size: 32
```
您很可能不需要此参数，因为 Lightning 总是会将超参数保存到检查点中。但是，如果您的检查点权重没有保存超参数，请使用此方法传入一个包含您希望使用的超参数的 .yaml 文件。这些超参数将被转换为 dict 并传递给您的 LightningModule 使用。

如果您的模型的 hparams 参数是 Namespace 并且 .yaml 文件具有分层结构，您需要重构您的模型以将 hparams 视为 dict。
strict (Optional[bool, None]) – 是否严格强制 checkpoint_path 中的键与此模块的 state dict 返回的键完全匹配。默认为 True，除非设置了 LightningModule.strict_loading，在这种情况下，它将默认为 LightningModule.strict_loading 的值。
**kwargs – 初始化模型所需的任何额外关键字参数。也可以用于覆盖已保存的超参数值。

返回类型

Self

返回值

加载了权重和超参数（如果可用）的 LightningModule 实例。

注意

load_from_checkpoint 是一个类方法。您应该使用 LightningModule 类来调用它，而不是 LightningModule 实例，否则将引发 TypeError。

注意

示例

# load weights without mapping ...
model = MyLightningModule.load_from_checkpoint('path/to/checkpoint.ckpt')

# or load weights mapping all weights from GPU 1 to GPU 0 ...
map_location = {'cuda:1':'cuda:0'}
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    map_location=map_location
)

# or load weights and hyperparameters from separate files.
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    hparams_file='/path/to/hparams_file.yaml'
)

# override some of the params with new values
model = MyLightningModule.load_from_checkpoint(
    PATH,
    num_layers=128,
    pretrained_ckpt_path=NEW_PATH,
)

# predict
pretrained_model.eval()
pretrained_model.freeze()
y_hat = pretrained_model(x)

load_state_dict(state_dict, strict=True, assign=False)¶

将参数和缓冲区从 state_dict 复制到此模块及其子孙模块中。

如果 strict 为 True，则 state_dict 的键必须与此模块的 state_dict() 函数返回的键完全匹配。

警告

如果 assign 为 True，则优化器必须在调用 load_state_dict 之后创建，除非 get_swap_module_params_on_conversion() 为 True。

参数

state_dict (dict) – 包含参数和持久缓冲区的字典。
strict (bool, optional) – 是否严格执行 state_dict 中的键与此模块的 state_dict() 函数返回的键匹配。默认值: True
assign (bool, optional) – 设置为 False 时，保留当前模块中张量的属性，而设置为 True 时，保留 state dict 中张量的属性。唯一的例外是 Default: ``False` 的 requires_grad 字段

返回值

missing_keys 是一个字符串列表，包含此模块需要但
提供的 state_dict 中缺失的键。
unexpected_keys 是一个字符串列表，包含此模块
不预期但提供的 state_dict 中存在的键。

返回类型

包含 missing_keys 和 unexpected_keys 字段的 NamedTuple

注意

如果一个参数或缓冲区被注册为 None 并且其对应的键存在于 state_dict 中，load_state_dict() 将引发 RuntimeError。

属性 local_rank: int¶

当前进程在单个节点内的索引。

返回类型: int

记录键值对。

示例

self.log('train_loss', loss)

每个钩子的默认行为在此处有文档说明：extensions/logging:Automatic Logging。

参数

name (str) – 要记录的键。如果使用 DDP 或任何其他分布式策略，则必须在所有进程中保持一致。
value (Union[Metric, Tensor, int, float]) – 要记录的值。可以是 float、Tensor 或 Metric。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图。
sync_dist (bool) – 如果为 True，则在设备之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 DDP 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个 dataloader 时）。如果 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch_size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
metric_attribute (Optional[str, None]) – 为了恢复指标状态，Lightning 需要您的模型中 torchmetrics.Metric 的引用。如果它是一个模型属性，则会自动找到。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

一次记录字典中的值。

示例

values = {'loss': loss, 'acc': acc, ..., 'metric_n': metric_n}
self.log_dict(values)

参数

dictionary (Union[Mapping[str, Union[Metric, Tensor, int, float]], MetricCollection]) – 键值对。如果使用 DDP 或任何其他分布式策略，所有进程中的键必须相同。值可以是 float、Tensor、Metric 或 MetricCollection。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。None 会自动记录 training_step，但不记录 validation/test_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。None 会自动记录 val/test step，但不记录 training_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图
sync_dist (bool) – 如果为 True，则在 GPU/TPU 之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 ddp 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个时）。如果为 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

属性 logger: Optional[Union[Logger, Logger]]¶

指向 Trainer 中 logger 对象的引用。

返回类型: Union[Logger, Logger, None]

属性 loggers: Union[list[pytorch_lightning.loggers.logger.Logger], list[lightning_fabric.loggers.logger.Logger]]¶

指向 Trainer 中 loggers 列表的引用。

返回类型: Union[list[Logger], list[Logger]]

lr_scheduler_step(scheduler, metric)¶

覆盖此方法以调整 Trainer 调用每个调度器的默认方式。默认情况下，Lightning 根据每个调度器的 interval 调用 step()，如示例所示。

参数

scheduler (Union[LRScheduler, ReduceLROnPlateau]) – 学习率调度器。
metric (Optional[Any, None]) – 用于像 ReduceLROnPlateau 这样的调度器的监视器值。

示例

# DEFAULT
def lr_scheduler_step(self, scheduler, metric):
    if metric is None:
        scheduler.step()
    else:
        scheduler.step(metric)

# Alternative way to update schedulers if it requires an epoch value
def lr_scheduler_step(self, scheduler, metric):
    scheduler.step(epoch=self.current_epoch)

返回类型: None

lr_schedulers()¶

返回训练期间使用的学习率调度器。对于手动优化很有用。

返回类型: Union[None, list[Union[LRScheduler, ReduceLROnPlateau]], LRScheduler, ReduceLROnPlateau]
返回值: 单个调度器，或者在存在多个调度器时返回一个列表，如果在 configure_optimizers() 中没有返回调度器，则返回 None。

manual_backward(loss, *args, **kwargs)¶

手动进行优化时，直接从你的 training_step() 调用此方法。通过使用此方法，Lightning 可以确保在使用混合精度时应用所有正确的缩放。

更多示例请参见 manual optimization。

示例

def training_step(...):
    opt = self.optimizers()
    loss = ...
    opt.zero_grad()
    # automatically applies scaling, etc...
    self.manual_backward(loss)
    opt.step()

参数

loss (Tensor) – 用于计算梯度的张量。必须附加计算图。
*args – 要转发给 backward() 的额外位置参数
**kwargs – 要转发给 backward() 的额外关键字参数

返回类型

None

modules()¶

返回网络中所有模块的迭代器。

Yields: Module – 网络中的一个模块

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.modules()):
...     print(idx, '->', m)

0 -> Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)
1 -> Linear(in_features=2, out_features=2, bias=True)

返回类型: Iterator[Module]

mtia(device=None)¶

将所有模型参数和缓冲区移动到 MTIA。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 MTIA 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

named_buffers(prefix='', recurse=True, remove_duplicate=True)¶

返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。

参数

prefix (str) – 要添加到所有缓冲区名称前的字符串前缀。
recurse (bool, optional) – 如果为 True，则生成此模块及其所有子模块的缓冲区。否则，仅生成此模块的直接成员缓冲区。默认为 True。
remove_duplicate (bool, optional) – 是否移除结果中的重复缓冲区。默认为 True。

Yields

(str, torch.Tensor) – 包含名称和缓冲区的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, buf in self.named_buffers():
>>>     if name in ['running_var']:
>>>         print(buf.size())

返回类型: Iterator[Tuple[str, Tensor]]

named_children()¶

返回直接子模块的迭代器，同时产生模块名称和模块本身。

Yields: (str, Module) – 包含名称和子模块的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, module in model.named_children():
>>>     if name in ['conv4', 'conv5']:
>>>         print(module)

返回类型: Iterator[Tuple[str, Module]]

named_modules(memo=None, prefix='', remove_duplicate=True)¶

返回网络中所有模块的迭代器，同时产生模块名称和模块本身。

参数

memo (Optional[Set[Module], None]) – 用于存储已添加到结果中的模块集合的备忘录
prefix (str) – 将添加到模块名称前的字符串前缀
remove_duplicate (bool) – 是否移除结果中重复的模块实例

Yields

(str, Module) – 包含名称和模块的元组

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.named_modules()):
...     print(idx, '->', m)

0 -> ('', Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
))
1 -> ('0', Linear(in_features=2, out_features=2, bias=True))

named_parameters(prefix='', recurse=True, remove_duplicate=True)¶

返回模块参数的迭代器，同时产生参数名称和参数本身。

参数

prefix (str) – 要添加到所有参数名称前的字符串前缀。
recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
remove_duplicate (bool, optional) – 是否移除结果中重复的参数。默认为 True。

Yields

(str, Parameter) – 包含名称和参数的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, param in self.named_parameters():
>>>     if name in ['bias']:
>>>         print(param.size())

返回类型: Iterator[Tuple[str, Parameter]]

on_after_backward()¶

在 loss.backward() 之后且在优化器步进之前调用。

注意

如果使用原生 AMP，此时梯度不会被取消缩放。如果您需要未缩放的梯度，请使用 on_before_optimizer_step。

返回类型: None

on_after_batch_transfer(batch, dataloader_idx)¶

覆盖此方法以在批次转移到设备后修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_after_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = gpu_transforms(batch['x'])
    return batch

另请参阅

on_before_batch_transfer()
transfer_batch_to_device()

on_before_backward(loss)¶

在 loss.backward() 之前调用。

参数: loss (Tensor) – 损失值，除以进行梯度累积的批次数，如果使用 AMP 则会进行缩放。
返回类型: None

on_before_batch_transfer(batch, dataloader_idx)¶

覆盖此方法以在批次转移到设备之前修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_before_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = transforms(batch['x'])
    return batch

另请参阅

on_after_batch_transfer()
transfer_batch_to_device()

on_before_optimizer_step(optimizer)¶

在 optimizer.step() 之前调用。

如果使用梯度累积，钩子会在梯度累积完成后调用一次。查看: :paramref:`~pytorch_lightning.trainer.trainer.Trainer.accumulate_grad_batches`。

如果使用 AMP，损失值在此钩子调用前会取消缩放。有关梯度缩放的更多信息，请参阅这些文档。

如果进行梯度裁剪，此时梯度尚未被裁剪。

参数: optimizer (Optimizer) – 正在使用的当前优化器。

示例

def on_before_optimizer_step(self, optimizer):
    # example to inspect gradient information in tensorboard
    if self.trainer.global_step % 25 == 0:  # don't make the tf file huge
        for k, v in self.named_parameters():
            self.logger.experiment.add_histogram(
                tag=k, values=v.grad, global_step=self.trainer.global_step
            )

返回类型: None

on_before_zero_grad(optimizer)¶

在 training_step() 之后且在 optimizer.zero_grad() 之前调用。

在训练循环中，在优化器步长后和梯度清零前调用。是检查权重更新后权重信息的好地方。

这里是它被调用的地方

for optimizer in optimizers:
    out = training_step(...)

    model.on_before_zero_grad(optimizer) # < ---- called here
    optimizer.zero_grad()

    backward()

参数: optimizer (Optimizer) – 应清零其梯度的优化器。
返回类型: None

on_fit_end()[source]¶

在 fit 的最后调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

on_fit_start()¶

在 fit 的最开始调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

属性 on_gpu: bool¶

如果此模型当前位于 GPU 上，则返回 True。

对于在 LightningModule 中设置标志以区分 CPU 和 GPU 的行为很有用。

返回类型: bool

on_load_checkpoint(checkpoint)[source]¶

由 Lightning 调用以恢复你的模型。如果你使用 on_save_checkpoint() 保存了某些内容，这是你恢复这些内容的机会。

参数: checkpoint (dict[str, Any]) – 已加载的检查点

示例

def on_load_checkpoint(self, checkpoint):
    # 99% of the time you don't need to implement this method
    self.something_cool_i_want_to_save = checkpoint['something_cool_i_want_to_save']

注意

Lightning 会自动恢复全局步长、epoch 和训练状态，包括 amp 缩放。您无需恢复任何与训练相关的内容。

返回类型: None

on_predict_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在预测循环中批次之后调用。

参数

outputs (Optional[Any, None]) – predict_step(x) 的输出
batch (Any) – 预测 DataLoader 返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_batch_start(batch, batch_idx, dataloader_idx=0)¶

在预测循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_end()[source]¶

在预测结束时调用。

返回类型: None

on_predict_epoch_end()¶

在预测结束时调用。

返回类型: None

on_predict_epoch_start()¶

在预测开始时调用。

返回类型: None

on_predict_model_eval()¶

预测循环开始时调用。

预测循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。

返回类型: None

on_predict_start()[source]¶

在预测开始时调用。

返回类型: None

on_save_checkpoint(checkpoint)[source]¶

Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。

参数: checkpoint (dict[str, Any]) – 在检查点字典被写入文件之前的完整字典。此钩子函数的实现可以将额外数据插入此字典。

示例

def on_save_checkpoint(self, checkpoint):
    # 99% of use cases you don't need to implement this method
    checkpoint['something_cool_i_want_to_save'] = my_cool_pickable_object

注意

Lightning 会保存训练的所有方面（周期、全局步数等），包括 amp scaling。您无需存储任何关于训练的内容。

返回类型: None

on_test_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在测试循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – test_step(x) 的输出。
batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_batch_start(batch, batch_idx, dataloader_idx=0)¶

在测试循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_end()¶

在测试结束时调用。

返回类型: None

on_test_epoch_end()¶

在测试循环中 epoch 的最后调用。

返回类型: None

on_test_epoch_start()¶

在测试循环中 epoch 的最开始调用。

返回类型: None

on_test_model_eval()¶

测试循环开始时调用。

测试循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_test_model_train()。

返回类型: None

on_test_model_train()¶

测试循环结束时调用。

测试循环默认将 LightningModule 的 training 模式恢复到开始测试之前的状态。重写此钩子函数以改变此行为。另请参见 on_test_model_eval()。

返回类型: None

on_test_start()¶

在测试开始时调用。

返回类型: None

on_train_batch_end(outputs, batch, batch_idx)¶

在训练循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – training_step(x) 的输出。
batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

注意

此处 outputs["loss"] 的值将是根据 accumulate_grad_batches 对 training_step 返回的损失值进行归一化后的值。

返回类型: None

on_train_batch_start(batch, batch_idx)¶

在训练循环中该批次发生任何事情之前调用。

如果此处返回 -1，将跳过当前周期的剩余训练。

参数

batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

返回类型

Optional[int, None]

on_train_end()¶

在训练结束、logger 实验关闭之前调用。

返回类型: None

on_train_epoch_end()[source]¶

在训练循环中 epoch 的最后调用。

要在周期结束时访问所有批次输出，您可以将步输出缓存为 LightningModule 的属性，并在此钩子函数中访问它们

class MyLightningModule(L.LightningModule):
    def __init__(self):
        super().__init__()
        self.training_step_outputs = []

    def training_step(self):
        loss = ...
        self.training_step_outputs.append(loss)
        return loss

    def on_train_epoch_end(self):
        # do something with all training_step outputs, for example:
        epoch_mean = torch.stack(self.training_step_outputs).mean()
        self.log("training_epoch_mean", epoch_mean)
        # free up the memory
        self.training_step_outputs.clear()

on_train_epoch_start()¶

在训练循环中 epoch 的最开始调用。

返回类型: None

on_train_start()¶

在健全性检查之后、训练开始时调用。

返回类型: None

on_validation_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在验证循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – validation_step(x) 的输出。
batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_batch_start(batch, batch_idx, dataloader_idx=0)¶

在验证循环中该批次发生任何事情之前调用。

参数

batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_end()¶

在验证结束时调用。

返回类型: None

on_validation_epoch_end()[source]¶: 在验证循环中 epoch 的最后调用。

on_validation_epoch_start()¶

在验证循环中 epoch 的最开始调用。

返回类型: None

on_validation_model_eval()¶

验证循环开始时调用。

验证循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_validation_model_train()。

返回类型: None

on_validation_model_train()¶

验证循环结束时调用。

验证循环默认将 LightningModule 的 training 模式恢复到开始验证之前的状态。重写此钩子函数以改变此行为。另请参见 on_validation_model_eval()。

返回类型: None

on_validation_model_zero_grad()¶

由训练循环调用，在进入验证循环之前释放梯度。

返回类型: None

on_validation_start()¶

在验证开始时调用。

返回类型: None

optimizer_step(epoch, batch_idx, optimizer, optimizer_closure=None)¶

覆盖此方法以调整 Trainer 调用优化器的默认方式。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Union[Optimizer, LightningOptimizer]) – PyTorch 优化器
optimizer_closure (Optional[Callable[[], Any], None]) – 优化器闭包。必须执行此闭包，因为它包含对 training_step()、optimizer.zero_grad() 和 backward() 的调用。

示例

def optimizer_step(self, epoch, batch_idx, optimizer, optimizer_closure):
    # Add your custom logic to run directly before `optimizer.step()`

    optimizer.step(closure=optimizer_closure)

    # Add your custom logic to run directly after `optimizer.step()`

返回类型: None

optimizer_zero_grad(epoch, batch_idx, optimizer)¶

覆盖此方法以更改 optimizer.zero_grad() 的默认行为。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Optimizer) – PyTorch 优化器

示例

# DEFAULT
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad()

# Set gradients to `None` instead of zero to improve performance (not required on `torch>=2.0.0`).
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad(set_to_none=True)

有关上述示例的解释，请参见 torch.optim.Optimizer.zero_grad()。

返回类型: None

optimizers(use_pl_optimizer=True)¶

返回训练期间使用的优化器。对于手动优化很有用。

参数: use_pl_optimizer (bool) – 如果为 True，则会将优化器封装在 LightningOptimizer 中，以自动处理精度、分析以及步调用计数，从而实现正确的日志记录和检查点。它专门封装 step 方法，不支持没有此方法的自定义优化器。
返回类型: Union[Optimizer, LightningOptimizer, _FabricOptimizer, list[Optimizer], list[LightningOptimizer], list[_FabricOptimizer]]
返回值: 单个优化器，或者在存在多个优化器时返回一个列表。

property output_chunk_length: Optional[int]¶

模型一次预测的时间步长数量。

返回类型: Optional[int, None]

parameters(recurse=True)¶

返回模块参数的迭代器。

这通常传递给优化器。

参数: recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
Yields: Parameter – 模块参数

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for param in model.parameters():
>>>     print(type(param), param.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Parameter]

predict_dataloader()¶

指定预测样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

建议所有数据下载和准备都在 prepare_data() 中进行。

predict()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any
返回值: 一个 torch.utils.data.DataLoader 或其序列，指定预测样本。

predict_step(batch, batch_idx, dataloader_idx=None)[source]¶

执行预测步骤

batch: Darts 的 InferenceDataset 的输出 - 包含 (past_target, past_covariates, historic_future_covariates, future_covariates, future_past_covariates, input time series, prediction start time step) 的元组
batch_idx: 当前批次的批次索引
dataloader_idx: 数据加载器索引

返回类型: Sequence[TimeSeries]

prepare_data()¶

警告

不要在此方法中为模型设置状态（请改用 setup 方法），因为此方法不会在每个设备上调用

示例

def prepare_data(self):
    # good
    download_data()
    tokenize()
    etc()

    # bad
    self.split = data_split
    self.some_state = some_other_state()

在分布式环境中，prepare_data 可以通过两种方式调用（使用 prepare_data_per_node）

每个节点一次。这是默认设置，仅在 LOCAL_RANK=0 上调用。
总共一次。仅在 GLOBAL_RANK=0 上调用。

示例

# DEFAULT
# called once per node on LOCAL_RANK=0 of that node
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = True

# call on GLOBAL_RANK=0 (great for shared file systems)
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = False

此方法在请求数据加载器之前调用

model.prepare_data()
initialize_distributed()
model.setup(stage)
model.train_dataloader()
model.val_dataloader()
model.test_dataloader()
model.predict_dataloader()

返回类型: None

print(*args, **kwargs)¶

仅从进程 0 打印。在任何分布式模式下使用此方法以仅记录一次。

参数

*args – 要打印的内容。与 Python 内置的 print 函数相同。
**kwargs – 与 Python 内置的 print 函数相同。

示例

def forward(self, x):
    self.print(x, 'in forward')

返回类型: None

register_backward_hook(hook)¶

在模块上注册后向钩子。

此函数已被弃用，推荐使用 register_full_backward_hook()，此函数的行为将在未来版本中改变。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_buffer(name, tensor, persistent=True)¶

向模块添加缓冲区。

这通常用于注册不应被视为模型参数的缓冲区。例如，BatchNorm 的 running_mean 不是参数，但它是模块状态的一部分。默认情况下，缓冲区是持久的，将与参数一起保存。可以通过将 persistent 设置为 False 来更改此行为。持久缓冲区和非持久缓冲区之间的唯一区别是后者不会成为此模块 state_dict 的一部分。

缓冲区可以使用给定的名称作为属性访问。

参数

name (str) – 缓冲区的名称。可以使用给定的名称从此模块访问缓冲区
tensor (Tensor 或 None) – 要注册的缓冲区。如果为 None，则忽略对缓冲区执行的操作，例如 cuda。如果为 None，缓冲区将不包含在模块的 state_dict 中。
persistent (bool) – 缓冲区是否为此模块 state_dict 的一部分。

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> self.register_buffer('running_mean', torch.zeros(num_features))

返回类型: None

register_forward_hook(hook, *, prepend=False, with_kwargs=False, always_call=False)¶

在模块上注册前向钩子。

每次 forward() 计算出输出后，都会调用此钩子。

如果 with_kwargs 为 False 或未指定，则输入仅包含传递给模块的位置参数。关键字参数不会传递给钩子，只会传递给 forward。钩子可以修改输出。它可以原地修改输入，但不会对 forward 产生影响，因为这是在调用 forward() 之后调用的。钩子应该具有以下签名

hook(module, args, output) -> None or modified output

如果 with_kwargs 为 True，则前向钩子函数将接收传递给 forward 函数的 kwargs，并预期返回可能修改过的输出。此钩子函数应具有以下签名：

hook(module, args, kwargs, output) -> None or modified output

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 True，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之后触发。请注意，使用 register_module_forward_hook() 注册的全局 forward 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 True，hook 将接收传递给 forward 函数的 kwargs。默认值：False
always_call (bool) – 如果为 True，无论在调用模块时是否引发异常，hook 都将被运行。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_forward_pre_hook(hook, *, prepend=False, with_kwargs=False)¶

在模块上注册前向预钩子。

每次调用 forward() 之前，都会调用此钩子。

hook(module, args) -> None or modified input

hook(module, args, kwargs) -> None or a tuple of modified input and kwargs

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之后触发。请注意，使用 register_module_forward_pre_hook() 注册的全局 forward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 true，hook 将接收传递给 forward 函数的 kwargs。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_hook(hook, prepend=False)¶

在模块上注册后向钩子。

每当计算相对于模块的梯度时，此钩子函数都将被调用，即只有当计算相对于模块输出的梯度时，此钩子函数才会执行。此钩子函数应具有以下签名：

hook(module, grad_input, grad_output) -> tuple(Tensor) or None

警告

使用后向钩子时，不允许原地修改输入或输出，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之后触发。请注意，使用 register_module_full_backward_hook() 注册的全局 backward 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_pre_hook(hook, prepend=False)¶

在模块上注册后向预钩子。

每当计算模块的梯度时，此钩子函数都将被调用。此钩子函数应具有以下签名：

hook(module, grad_output) -> tuple[Tensor] or None

警告

使用后向钩子时，不允许原地修改输入，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之后触发。请注意，使用 register_module_full_backward_pre_hook() 注册的全局 backward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_load_state_dict_post_hook(hook)¶

注册一个后钩子函数，在调用模块的 load_state_dict() 后运行。

它应该具有以下签名：: hook(module, incompatible_keys) -> None

如有需要，可以原地修改给定的 incompatible_keys。

请注意，调用 load_state_dict() 并设置 strict=True 时执行的检查会受到钩子对 missing_keys 或 unexpected_keys 所做修改的影响，这是预期行为。对任一键集添加键会导致在 strict=True 时抛出错误，而清除缺失和意外键则可以避免错误。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_load_state_dict_pre_hook(hook)¶

注册一个预钩子函数，在调用模块的 load_state_dict() 之前运行。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata, strict, missing_keys, unexpected_keys, error_msgs) -> None # noqa: B950

参数: hook (Callable) – 可调用钩子函数，将在加载状态字典之前被调用。

register_module(name, module)¶

add_module() 的别名。

返回类型: None

register_parameter(name, param)¶

向模块添加参数。

参数可以使用给定的名称作为属性访问。

参数

name (str) – 参数的名称。可以使用给定的名称从此模块访问参数
param (Parameter 或 None) – 要添加到模块的参数。如果为 None，则忽略对参数执行的操作，例如 cuda。如果为 None，参数将不包含在模块的 state_dict 中。

返回类型

None

register_state_dict_post_hook(hook)¶

为 state_dict() 方法注册一个后钩子。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata) -> None

注册的钩子函数可以原地修改 state_dict。

register_state_dict_pre_hook(hook)¶

为 state_dict() 方法注册一个预钩子。

它应该具有以下签名：: hook(module, prefix, keep_vars) -> None

注册的钩子函数可用于在进行 state_dict 调用之前执行预处理。

requires_grad_(requires_grad=True)¶

更改此模块中是否应记录参数上的自动梯度操作。

此方法原地设置参数的 requires_grad 属性。

此方法有助于冻结模块的一部分用于微调，或单独训练模型的各个部分（例如，GAN 训练）。

有关 .requires_grad_() 和几个可能与其混淆的类似机制的比较，请参见 locally-disable-grad-doc。

参数: requires_grad (bool) – 是否应由 autograd 记录此模块中参数的操作。默认值：True。
返回值: self
返回类型: Module

save_hyperparameters(*args, ignore=None, frame=None, logger=True)¶

将参数保存到 hparams 属性。

参数

args (Any) – 可以是 dict、NameSpace 或 OmegaConf 的单个对象，或来自类 __init__ 的字符串名称或参数
ignore (Union[str, Sequence[str], None]) – 要忽略的来自类 __init__ 的参数名称或参数名称列表
frame (Optional[frame, None]) – 一个 frame 对象。默认值为 None
logger (bool) – 是否将超参数发送到日志记录器。默认值：True

示例：

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # manually assign arguments
...         self.save_hyperparameters('arg1', 'arg3')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class AutomaticArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # equivalent automatic
...         self.save_hyperparameters()
...     def forward(self, *args, **kwargs):
...         ...
>>> model = AutomaticArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg2": abc
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class SingleArgModel(HyperparametersMixin):
...     def __init__(self, params):
...         super().__init__()
...         # manually assign single argument
...         self.save_hyperparameters(params)
...     def forward(self, *args, **kwargs):
...         ...
>>> model = SingleArgModel(Namespace(p1=1, p2='abc', p3=3.14))
>>> model.hparams
"p1": 1
"p2": abc
"p3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # pass argument(s) to ignore as a string or in a list
...         self.save_hyperparameters(ignore='arg2')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

返回类型: None

set_extra_state(state)¶

设置加载的 state_dict 中包含的额外状态。

此函数从 load_state_dict() 中调用，以处理 state_dict 中找到的任何额外状态。如果需要将额外状态存储在其 state_dict 中，请为此模块实现此函数和相应的 get_extra_state() 函数。

参数: state (dict) – 来自 state_dict 的额外状态
返回类型: None

set_mc_dropout(active)[source]¶

set_predict_parameters(n, num_samples, roll_size, batch_size, n_jobs, predict_likelihood_parameters, mc_dropout)[source]¶

在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置

返回类型: None

set_submodule(target, module)¶

如果存在，则设置由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

(图示为一个 nn.Module A。A 有一个嵌套子模块 net_b，其本身又有两个子模块 net_c 和 linear。net_c 然后有一个子模块 conv。)

要用一个新的子模块 Linear 覆盖 Conv2d，您可以调用 set_submodule("net_b.net_c.conv", nn.Linear(33, 16))。

参数

target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
module (Module) – 用于设置子模块的模块。

Raises

ValueError – 如果目标字符串为空
AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

返回类型

None

setup(stage)¶

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'

示例

class LitModel(...):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        download_data()
        tokenize()

        # don't do this
        self.something = else

    def setup(self, stage):
        data = load_data(...)
        self.l1 = nn.Linear(28, data.num_classes)

返回类型: None

share_memory()¶

参见 torch.Tensor.share_memory_()。

返回类型: ~T

state_dict(*args, destination=None, prefix='', keep_vars=False)¶

返回包含模块完整状态引用的字典。

参数和持久缓冲区（例如，运行平均值）都包含在内。键是相应的参数和缓冲区名称。设置为 None 的参数和缓冲区不包含在内。

注意

返回的对象是浅拷贝。它包含对模块参数和缓冲区的引用。

警告

目前 state_dict() 也按顺序接受 destination、prefix 和 keep_vars 的位置参数。但是，此用法已被弃用，未来版本将强制使用关键字参数。

警告

请避免使用参数 destination，因为它并非为终端用户设计。

参数

destination (dict, optional) – 如果提供，模块的状态将更新到此字典中，并返回相同的对象。否则，将创建一个 OrderedDict 并返回。默认值：None。
prefix (str, optional) – 添加到参数和缓冲区名称的前缀，用于在 state_dict 中构成键。默认值：''。
keep_vars (bool, optional) – 默认情况下，state dict 中返回的 Tensor s 与 autograd 分离。如果设置为 True，将不会进行分离。默认值：False。

返回值

包含模块完整状态的字典

返回类型

dict

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> module.state_dict().keys()
['bias', 'weight']

property strict_loading: bool¶

确定 Lightning 如何使用 .load_state_dict(…, strict=model.strict_loading) 加载此模型。

返回类型: bool

property supports_probabilistic_prediction: bool¶

返回类型: bool

teardown(stage)¶

在 fit（训练 + 验证）、验证、测试或预测结束时调用。

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'
返回类型: None

test_dataloader()¶

指定测试样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和拆分

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

test()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果您不需要测试数据集和 test_step()，则无需实现此方法。

返回类型: Any

test_step(*args, **kwargs)¶

对测试集中的单个批次数据进行操作。在此步骤中，您通常会生成示例或计算任何感兴趣的内容，例如准确率。

参数

batch – 您的数据可迭代对象（通常是 DataLoader）的输出。
batch_idx – 此批次的索引。
dataloader_idx – 生成此批次的数据加载器索引。（仅在使用多个数据加载器时）

返回类型

Union[Tensor, Mapping[str, Any], None]

返回值

Tensor - 损失张量
dict - 字典。可以包含任意键，但必须包含键 'loss'。
None - 跳到下一个批次。

# if you have one test dataloader:
def test_step(self, batch, batch_idx): ...

# if you have multiple test dataloaders:
def test_step(self, batch, batch_idx, dataloader_idx=0): ...

示例

# CASE 1: A single test dataset
def test_step(self, batch, batch_idx):
    x, y = batch

    # implement your own
    out = self(x)
    loss = self.loss(out, y)

    # log 6 example images
    # or generated text... or whatever
    sample_imgs = x[:6]
    grid = torchvision.utils.make_grid(sample_imgs)
    self.logger.experiment.add_image('example_images', grid, 0)

    # calculate acc
    labels_hat = torch.argmax(out, dim=1)
    test_acc = torch.sum(y == labels_hat).item() / (len(y) * 1.0)

    # log the outputs!
    self.log_dict({'test_loss': loss, 'test_acc': test_acc})

如果您传入多个测试数据加载器，test_step() 将会有一个额外的参数。我们建议将默认值设置为 0，这样您就可以在单个和多个数据加载器之间快速切换。

# CASE 2: multiple test dataloaders
def test_step(self, batch, batch_idx, dataloader_idx=0):
    # dataloader_idx tells you which dataset this is.
    ...

注意

如果您不需要测试，则无需实现此方法。

注意

调用 test_step() 时，模型已设置为评估模式，并且 PyTorch 梯度已禁用。在测试轮次结束时，模型会回到训练模式并启用梯度。

to(*args, **kwargs)¶

参见 torch.nn.Module.to()。

返回类型: Self

to_dtype(dtype)[source]¶: 将模块精度（默认为 float32）转换为其他精度。

to_empty(*, device, recurse=True)¶

在不复制存储的情况下，将参数和缓冲区移动到指定设备。

参数

device (torch.device) – 此模块中参数和缓冲区的目标设备。
recurse (bool) – 是否应将子模块的参数和缓冲区递归地移动到指定设备。

返回值

self

返回类型

Module

to_onnx(file_path, input_sample=None, **kwargs)¶

将模型保存为 ONNX 格式。

参数

file_path (Union[str, Path, BytesIO]) – 应保存 onnx 模型的文件路径。
input_sample (Optional[Any, None]) – 用于跟踪的输入。默认值：None（使用 self.example_input_array）
**kwargs – 将传递给 torch.onnx.export 函数。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)

model = SimpleModel()
input_sample = torch.randn(1, 64)
model.to_onnx("export.onnx", input_sample, export_params=True)

返回类型: None

to_torchscript(file_path=None, method='script', example_inputs=None, **kwargs)¶

默认情况下会将整个模型编译成一个 ScriptModule。如果您想使用跟踪（tracing），请提供参数 method='trace'，并确保提供了 example_inputs 参数，或者模型设置了 example_input_array。如果您想自定义需要脚本化的模块，应覆盖此方法。如果您想返回多个模块，建议使用字典。

参数

file_path (Union[str, Path, None]) – 保存 torchscript 的路径。默认值：None（不保存文件）。
method (Optional[str, None]) – 是使用 TorchScript 的 script 方法还是 trace 方法。默认值：‘script’
example_inputs (Optional[Any, None]) – 在将 method 设置为 ‘trace’ 时用于跟踪的输入。默认值：None（使用 example_input_array）
**kwargs – 将传递给 torch.jit.script() 或 torch.jit.trace() 函数的附加参数。

注意

需要实现 forward() 方法。
导出的脚本将被设置为评估模式。
建议您安装最新支持版本的 PyTorch 以无限制地使用此功能。另请参见 torch.jit 文档以了解支持的功能。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)))

model = SimpleModel()
model.to_torchscript(file_path="model.pt")

torch.jit.save(model.to_torchscript(
    file_path="model_trace.pt", method='trace', example_inputs=torch.randn(1, 64))
)

返回类型: Union[ScriptModule, dict[str, ScriptModule]]
返回值: 此 LightningModule 作为 torchscript，无论是否定义了 file_path。

toggle_optimizer(optimizer)¶

确保在训练步骤中仅计算当前优化器参数的梯度，以防止在多优化器设置中出现悬空梯度。

它与 untoggle_optimizer() 一起使用，以确保正确重置 param_requires_grad_state。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要切换的优化器。
返回类型: None

train(mode=True)¶

将模块设置为训练模式。

这仅对某些模块有影响。有关它们在训练/评估模式下的行为详情，例如它们是否受影响（例如 Dropout、BatchNorm 等），请参阅特定模块的文档。

参数: mode (bool) – 是否设置训练模式 (True) 或评估模式 (False)。默认值: True。
返回值: self
返回类型: Module

train_dataloader()¶

指定训练样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

除非您将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数，否则您返回的数据加载器将不会被重新加载。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和拆分

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

fit()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any

property trainer: Trainer¶

返回类型: Trainer

training: bool¶

training_step(train_batch, batch_idx)[source]¶

执行训练步骤

返回类型: Tensor

transfer_batch_to_device(batch, device, dataloader_idx)¶

如果您的 DataLoader 返回包装在自定义数据结构中的张量，请覆盖此钩子。

下面列出的数据类型（以及它们的任意嵌套）是开箱即用的支持

torch.Tensor 或任何实现了 .to(…) 的东西
list
dict
tuple

对于其他任何东西，你需要定义数据如何移动到目标设备 (CPU, GPU, TPU, …)。

注意

参数

batch (Any) – 需要转移到新设备的数据批次。
device (device) – PyTorch 中定义的目标设备。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据在新设备上的引用。

示例

def transfer_batch_to_device(self, batch, device, dataloader_idx):
    if isinstance(batch, CustomBatch):
        # move all tensors in your custom data structure to the device
        batch.samples = batch.samples.to(device)
        batch.targets = batch.targets.to(device)
    elif dataloader_idx == 0:
        # skip device transfer for the first dataloader or anything you wish
        pass
    else:
        batch = super().transfer_batch_to_device(batch, device, dataloader_idx)
    return batch

另请参阅

move_data_to_device()
apply_to_collection()

type(dst_type)¶

参见 torch.nn.Module.type()。

返回类型: Self

unfreeze()¶

解冻所有参数以进行训练。

model = MyLightningModule(...)
model.unfreeze()

返回类型: None

untoggle_optimizer(optimizer)¶

重置使用 toggle_optimizer() 切换的所需梯度的状态。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要取消切换的优化器。
返回类型: None

val_dataloader()¶

指定验证样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

除非您将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数，否则您返回的数据加载器将不会被重新加载。

建议所有数据下载和准备都在 prepare_data() 中进行。

fit()
validate()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果您不需要验证数据集和 validation_step()，则无需实现此方法。

返回类型: Any

validation_step(val_batch, batch_idx)[source]¶

执行验证步骤

返回类型: Tensor

xpu(device=None)¶

将所有模型参数和缓冲区移动到 XPU。

这也会使得相关的参数和缓冲区成为不同的对象。因此，如果模块将在 XPU 上运行并进行优化，则应该在构建优化器之前调用它。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

zero_grad(set_to_none=True)¶

重置所有模型参数的梯度。

请参阅 torch.optim.Optimizer 下的类似函数，了解更多背景信息。

参数: set_to_none (bool) – 不设置为零，而是将梯度设置为 None。请参阅 torch.optim.Optimizer.zero_grad() 了解详情。
返回类型: None

class darts.models.forecasting.pl_forecasting_module.PLFutureCovariatesModule(input_chunk_length, output_chunk_length, output_chunk_shift=0, train_sample_shape=None, loss_fn=MSELoss(), torch_metrics=None, likelihood=None, optimizer_cls=<class 'torch.optim.adam.Adam'>, optimizer_kwargs=None, lr_scheduler_cls=None, lr_scheduler_kwargs=None, use_reversible_instance_norm=False)[source]¶

基类：PLForecastingModule, ABC

基于 PyTorch Lightning 的预测模块。

此类旨在被继承以创建新的基于 PyTorch Lightning 的预测模块。子类化此类时，请确保添加具有以下签名的方

PLForecastingModule.__init__()

PLForecastingModule.forward()

PLForecastingModule._process_input_batch()

PLForecastingModule._produce_train_output()

PLForecastingModule._get_batch_prediction()

在子类 MyModel 的 __init__() 函数中调用 super(MyModel, self).__init__(**kwargs)，其中 kwargs 是 PLForecastingModule 的参数。

参数

input_chunk_length (int) – 模型输入的时间步长数量（每块）。适用于目标序列以及过去和/或未来协变量（如果模型支持）。
output_chunk_length (int) – 内部模型一次预测（每块）的时间步长数量。此外，未来协变量的未来值用作模型输入的数量（如果模型支持未来协变量）。它与 predict() 中使用的预测视野 n 不同，后者是使用一次性预测或自回归预测生成的所需预测点数。设置 n <= output_chunk_length 可防止自回归。当协变量未能充分延伸到未来时，这非常有用，或者为了禁止模型使用过去和/或未来协变量的未来值进行预测（取决于模型的协变量支持）。
train_sample_shape (Optional[tuple, None]) – 模型的输入形状，用于在不调用 fit_from_dataset 的情况下实例化模型，并对用于重新训练或预测的新训练/推理数据集执行健全性检查。
loss_fn (_Loss) – 用于训练的 PyTorch 损失函数。如果指定了 likelihood 参数，则此参数对于概率模型将被忽略。默认值：torch.nn.MSELoss()。
torch_metrics (Union[Metric, MetricCollection, None]) – 用于评估的 torch 指标或 MetricCollection。可在 https://torchmetrics.readthedocs.io/en/latest/ 找到可用指标的完整列表。默认值：None。
likelihood (Optional[TorchLikelihood, None]) – Darts 的 Likelihood 模型之一，用于概率预测。默认值：None。
optimizer_cls (Optimizer) – 要使用的 PyTorch 优化器类。默认值：torch.optim.Adam。
optimizer_kwargs (Optional[dict, None]) – 可选地，PyTorch 优化器的一些关键字参数（例如，{'lr': 1e-3} 用于指定学习率）。否则将使用选定的 optimizer_cls 的默认值。默认值：None。
lr_scheduler_cls (Optional[_LRScheduler, None]) – 可选地，要使用的 PyTorch 学习率调度器类。指定 None 对应于使用恒定学习率。默认值：None。
lr_scheduler_kwargs (Optional[dict, None]) – 可选地，PyTorch 学习率调度器的一些关键字参数。默认值：None。
use_reversible_instance_norm (bool) – 是否使用可逆实例归一化 RINorm 来应对分布偏移，如 [1] 中所示。它仅应用于目标序列的特征，而不应用于协变量。

参考

1: T. Kim et al. “Reversible Instance Normalization for Accurate Time-Series Forecasting against Distribution Shift”, https://openreview.net/forum?id=cGDAkQo1C0p

属性

`automatic_optimization`	如果设置为 `False`，则您负责调用 `.backward()`, `.step()`, `.zero_grad()`。
`current_epoch`	`Trainer` 中的当前 epoch，如果未附加则为 0。
`device_mesh`	`ModelParallelStrategy` 等策略将创建设备网格，可在 `configure_model()` 钩子中访问该网格以并行化 LightningModule。
`example_input_array`	示例输入数组是模块在 `forward()` 方法中可以使用的输入的规范。
`global_rank`	当前进程在所有节点和设备中的索引。
`global_step`	所有 epoch 中看到的总训练批次。
`hparams`	使用 `save_hyperparameters()` 保存的超参数集合。
`hparams_initial`	使用 `save_hyperparameters()` 保存的超参数集合。
`local_rank`	当前进程在单个节点内的索引。
`logger`	指向 Trainer 中 logger 对象的引用。
`loggers`	指向 Trainer 中 loggers 列表的引用。
`on_gpu`	如果此模型当前位于 GPU 上，则返回 `True`。
`output_chunk_length`	模型一次预测的时间步长数量。
`strict_loading`	确定 Lightning 如何使用 .load_state_dict(..., strict=model.strict_loading) 加载此模型。

device
dtype
epochs_trained
fabric
supports_probabilistic_prediction
trainer

方法

`add_module`(name, module)	向当前模块添加子模块。
`all_gather`(data[, group, sync_grads])	从多个进程聚合张量或张量集合。
`apply`(fn)	将 `fn` 递归地应用于每个子模块（由 `.children()` 返回）以及自身。
`backward`(loss, args, *kwargs)	调用此方法对 `training_step()` 返回的损失执行反向传播。
`bfloat16`()	将所有浮点参数和缓冲区转换为 `bfloat16` 数据类型。
`buffers`([recurse])	返回模块缓冲区的迭代器。
`children`()	返回直接子模块的迭代器。
`clip_gradients`(optimizer[, ...])	内部处理梯度裁剪。
`compile`(args, *kwargs)	使用 `torch.compile()` 编译此模块的前向传播。
`configure_callbacks`()	配置模型特定的回调。
`configure_gradient_clipping`(optimizer[, ...])	对优化器参数执行梯度裁剪。
`configure_model`()	在策略和精度感知上下文中创建模块的钩子。
`configure_optimizers`()	配置用于模型优化的优化器和学习率调度器。
`configure_sharded_model`()	已弃用。
`configure_torch_metrics`(torch_metrics)	处理 torch_metrics 参数。
`cpu`()	参见 `torch.nn.Module.cpu()`。
`cuda`([device])	将所有模型参数和缓冲区移动到 GPU。
`double`()	参见 `torch.nn.Module.double()`。
`eval`()	将模块设置为评估模式。
`extra_repr`()	返回模块的额外表示。
`float`()	参见 `torch.nn.Module.float()`。
`forward`(args, *kwargs)	与 `torch.nn.Module.forward()` 相同。
`freeze`()	冻结所有参数以进行推理。
`get_buffer`(target)	如果存在，则返回由 `target` 指定的缓冲区，否则抛出错误。
`get_extra_state`()	返回要包含在模块 state_dict 中的任何额外状态。
`get_parameter`(target)	如果存在，则返回由 `target` 指定的参数，否则抛出错误。
`get_submodule`(target)	如果存在，则返回由 `target` 指定的子模块，否则抛出错误。
`half`()	参见 `torch.nn.Module.half()`。
`ipu`([device])	将所有模型参数和缓冲区移动到 IPU。
`load_from_checkpoint`(checkpoint_path[, ...])	从检查点加载模型的主要方式。
`load_state_dict`(state_dict[, strict, assign])	将参数和缓冲区从 `state_dict` 复制到此模块及其后代中。
`log`(name, value[, prog_bar, logger, ...])	记录键值对。
`log_dict`(dictionary[, prog_bar, logger, ...])	一次记录字典中的值。
`lr_scheduler_step`(scheduler, metric)	覆盖此方法以调整 `Trainer` 调用每个调度器的默认方式。
`lr_schedulers`()	返回训练期间使用的学习率调度器。
`manual_backward`(loss, args, *kwargs)	手动进行优化时，直接从 `training_step()` 中调用此方法。
`modules`()	返回网络中所有模块的迭代器。
`mtia`([device])	将所有模型参数和缓冲区移动到 MTIA。
`named_buffers`([prefix, recurse, ...])	返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。
`named_children`()	返回直接子模块的迭代器，同时产生模块名称和模块本身。
`named_modules`([memo, prefix, remove_duplicate])	返回网络中所有模块的迭代器，同时产生模块名称和模块本身。
`named_parameters`([prefix, recurse, ...])	返回模块参数的迭代器，同时产生参数名称和参数本身。
`on_after_backward`()	在 `loss.backward()` 之后且在优化器步进之前调用。
`on_after_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备后修改或应用批次增强。
`on_before_backward`(loss)	在 `loss.backward()` 之前调用。
`on_before_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备之前修改或应用批次增强。
`on_before_optimizer_step`(optimizer)	在 `optimizer.step()` 之前调用。
`on_before_zero_grad`(optimizer)	在 `training_step()` 之后且在 `optimizer.zero_grad()` 之前调用。
`on_fit_end`()	在 fit 的最后调用。
`on_fit_start`()	在 fit 的最开始调用。
`on_load_checkpoint`(checkpoint)	由 Lightning 调用以恢复您的模型。
`on_predict_batch_end`(outputs, batch, batch_idx)	在预测循环中批次之后调用。
`on_predict_batch_start`(batch, batch_idx[, ...])	在预测循环中该批次发生任何事情之前调用。
`on_predict_end`()	在预测结束时调用。
`on_predict_epoch_end`()	在预测结束时调用。
`on_predict_epoch_start`()	在预测开始时调用。
`on_predict_model_eval`()	预测循环开始时调用。
`on_predict_start`()	在预测开始时调用。
`on_save_checkpoint`(checkpoint)	Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。
`on_test_batch_end`(outputs, batch, batch_idx)	在测试循环中批次之后调用。
`on_test_batch_start`(batch, batch_idx[, ...])	在测试循环中该批次发生任何事情之前调用。
`on_test_end`()	在测试结束时调用。
`on_test_epoch_end`()	在测试循环中 epoch 的最后调用。
`on_test_epoch_start`()	在测试循环中 epoch 的最开始调用。
`on_test_model_eval`()	测试循环开始时调用。
`on_test_model_train`()	测试循环结束时调用。
`on_test_start`()	在测试开始时调用。
`on_train_batch_end`(outputs, batch, batch_idx)	在训练循环中批次之后调用。
`on_train_batch_start`(batch, batch_idx)	在训练循环中该批次发生任何事情之前调用。
`on_train_end`()	在训练结束、logger 实验关闭之前调用。
`on_train_epoch_end`()	在训练循环中 epoch 的最后调用。
`on_train_epoch_start`()	在训练循环中 epoch 的最开始调用。
`on_train_start`()	在健全性检查之后、训练开始时调用。
`on_validation_batch_end`(outputs, batch, ...)	在验证循环中批次之后调用。
`on_validation_batch_start`(batch, batch_idx)	在验证循环中该批次发生任何事情之前调用。
`on_validation_end`()	在验证结束时调用。
`on_validation_epoch_end`()	在验证循环中 epoch 的最后调用。
`on_validation_epoch_start`()	在验证循环中 epoch 的最开始调用。
`on_validation_model_eval`()	验证循环开始时调用。
`on_validation_model_train`()	验证循环结束时调用。
`on_validation_model_zero_grad`()	由训练循环调用，在进入验证循环之前释放梯度。
`on_validation_start`()	在验证开始时调用。
`optimizer_step`(epoch, batch_idx, optimizer)	覆盖此方法以调整 `Trainer` 调用优化器的默认方式。
`optimizer_zero_grad`(epoch, batch_idx, optimizer)	覆盖此方法以更改 `optimizer.zero_grad()` 的默认行为。
`optimizers`([use_pl_optimizer])	返回训练期间使用的优化器。
`parameters`([recurse])	返回模块参数的迭代器。
`predict_dataloader`()	指定预测样本的可迭代对象或可迭代对象集合。
`predict_step`(batch, batch_idx[, dataloader_idx])	执行预测步骤
`prepare_data`()	使用此方法下载和准备数据。
`print`(args, *kwargs)	仅从进程 0 打印。
`register_backward_hook`(hook)	在模块上注册后向钩子。
`register_buffer`(name, tensor[, persistent])	向模块添加缓冲区。
`register_forward_hook`(hook, *[, prepend, ...])	在模块上注册前向钩子。
`register_forward_pre_hook`(hook, *[, ...])	在模块上注册前向预钩子。
`register_full_backward_hook`(hook[, prepend])	在模块上注册后向钩子。
`register_full_backward_pre_hook`(hook[, prepend])	在模块上注册后向预钩子。
`register_load_state_dict_post_hook`(hook)	注册一个后钩子，该钩子在模块的 `load_state_dict()` 被调用后运行。
`register_load_state_dict_pre_hook`(hook)	注册一个预钩子，该钩子在模块的 `load_state_dict()` 被调用前运行。
`register_module`(name, module)	`add_module()` 的别名。
`register_parameter`(name, param)	向模块添加参数。
`register_state_dict_post_hook`(hook)	为 `state_dict()` 方法注册一个后钩子。
`register_state_dict_pre_hook`(hook)	为 `state_dict()` 方法注册一个预钩子。
`requires_grad_`([requires_grad])	更改此模块中是否应记录参数上的自动梯度操作。
`save_hyperparameters`(*args[, ignore, frame, ...])	将参数保存到 `hparams` 属性。
`set_extra_state`(state)	设置加载的 state_dict 中包含的额外状态。
`set_predict_parameters`(n, num_samples, ...)	在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置
`set_submodule`(target, module)	如果存在，则设置由 `target` 指定的子模块，否则抛出错误。
`setup`(stage)	在 fit（训练 + 验证）、验证、测试或预测开始时调用。
`share_memory`()	参见 `torch.Tensor.share_memory_()`。
`state_dict`(*args[, destination, prefix, ...])	返回包含模块完整状态引用的字典。
`teardown`(stage)	在 fit（训练 + 验证）、验证、测试或预测结束时调用。
`test_dataloader`()	指定测试样本的可迭代对象或可迭代对象集合。
`test_step`(args, *kwargs)	处理测试集中的单个批次数据。
`to`(args, *kwargs)	参见 `torch.nn.Module.to()`。
`to_dtype`(dtype)	将模块精度（默认为 float32）转换为其他精度。
`to_empty`(*, device[, recurse])	在不复制存储的情况下，将参数和缓冲区移动到指定设备。
`to_onnx`(file_path[, input_sample])	将模型保存为 ONNX 格式。
`to_torchscript`([file_path, method, ...])	默认情况下，将整个模型编译为 `ScriptModule`。
`toggle_optimizer`(optimizer)	确保在训练步骤中仅计算当前优化器参数的梯度，以防止多优化器设置中出现悬空梯度。
`train`([mode])	将模块设置为训练模式。
`train_dataloader`()	指定训练样本的可迭代对象或可迭代对象集合。
`training_step`(train_batch, batch_idx)	执行训练步骤
`transfer_batch_to_device`(batch, device, ...)	如果您的 `DataLoader` 返回包装在自定义数据结构中的张量，请覆盖此钩子。
`type`(dst_type)	参见 `torch.nn.Module.type()`。
`unfreeze`()	解冻所有参数以进行训练。
`untoggle_optimizer`(optimizer)	重置使用 `toggle_optimizer()` 切换的梯度必需状态。
`val_dataloader`()	指定验证样本的可迭代对象或可迭代对象集合。
`validation_step`(val_batch, batch_idx)	执行验证步骤
`xpu`([device])	将所有模型参数和缓冲区移动到 XPU。
`zero_grad`([set_to_none])	重置所有模型参数的梯度。

__call__
set_mc_dropout

CHECKPOINT_HYPER_PARAMS_KEY = 'hyper_parameters'¶

CHECKPOINT_HYPER_PARAMS_NAME = 'hparams_name'¶

CHECKPOINT_HYPER_PARAMS_TYPE = 'hparams_type'¶

T_destination¶: TypeVar(‘T_destination’, bound=Dict[str, Any]) 的别名

add_module(name, module)¶

向当前模块添加子模块。

模块可以使用给定的名称作为属性访问。

参数

name (str) – 子模块的名称。可以使用此名称从当前模块访问子模块
module (Module) – 要添加到模块的子模块。

返回类型

None

all_gather(data, group=None, sync_grads=False)¶

从多个进程聚合张量或张量集合。

此方法需要在所有进程上调用，并且张量需要在所有进程上具有相同的形状，否则您的程序将永远暂停。

参数

data (Union[Tensor, dict, list, tuple]) – int、float、形状为 (batch, …) 的张量，或其（可能嵌套的）集合。
group (Optional[Any, None]) – 要从中收集结果的进程组。默认为所有进程 (world)。
sync_grads (bool) – 允许用户同步 all_gather 操作的梯度的标志。

返回类型

Union[Tensor, dict, list, tuple]

返回值

形状为 (world_size, batch, …) 的张量，如果输入是集合，则输出也将是包含此形状张量的集合。对于 world_size 为 1 的特殊情况，不会向张量添加额外维度。

allow_zero_length_dataloader_with_multiple_devices: bool¶

apply(fn)¶

将 fn 递归地应用于每个子模块（由 .children() 返回）以及自身。

典型用法包括初始化模型的参数（另见 nn-init-doc）。

参数: fn (Module -> None) – 要应用于每个子模块的函数
返回值: self
返回类型: Module

示例

>>> @torch.no_grad()
>>> def init_weights(m):
>>>     print(m)
>>>     if type(m) == nn.Linear:
>>>         m.weight.fill_(1.0)
>>>         print(m.weight)
>>> net = nn.Sequential(nn.Linear(2, 2), nn.Linear(2, 2))
>>> net.apply(init_weights)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)

property automatic_optimization: bool¶

如果设置为 False，则您负责调用 .backward(), .step(), .zero_grad()。

返回类型: bool

backward(loss, *args, **kwargs)¶

调用此方法对 training_step() 返回的损失执行反向传播。如果需要，可以使用自己的实现覆盖此钩子。

参数: loss (Tensor) – training_step() 返回的损失张量。如果使用梯度累积，则这里的损失为归一化值（按 1 / 累积步数缩放）。

示例

def backward(self, loss):
    loss.backward()

返回类型: None

bfloat16()¶

将所有浮点参数和缓冲区转换为 bfloat16 数据类型。

注意

此方法会修改模块本身。

返回值: self
返回类型: Module

buffers(recurse=True)¶

返回模块缓冲区的迭代器。

参数: recurse (bool) – 如果为 True，则产生此模块和所有子模块的缓冲区。否则，仅产生此模块的直接成员缓冲区。
Yields: torch.Tensor – 模块缓冲区

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for buf in model.buffers():
>>>     print(type(buf), buf.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Tensor]

call_super_init: bool = False¶

children()¶

返回直接子模块的迭代器。

Yields: Module – 子模块
返回类型: Iterator[Module]

clip_gradients(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

内部处理梯度裁剪。

注意

不要覆盖此方法。如果您想自定义梯度裁剪，请考虑使用 configure_gradient_clipping() 方法。
对于手动优化 (self.automatic_optimization = False)，如果要使用梯度裁剪，请考虑在训练步骤中手动调用 self.clip_gradients(opt, gradient_clip_val=0.5, gradient_clip_algorithm="norm")。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 裁剪梯度的值。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。传递 gradient_clip_algorithm="value" 按值裁剪，传递 gradient_clip_algorithm="norm" 按范数裁剪。

返回类型

None

compile(*args, **kwargs)¶

使用 torch.compile() 编译此模块的前向传播。

此模块的 __call__ 方法将被编译，并且所有参数将原样传递给 torch.compile()。

有关此函数的参数详细信息，请参见 torch.compile()。

configure_callbacks()¶

返回类型: Union[Sequence[Callback], Callback]
返回值: 一个或多个回调，它们将扩展 Trainer 中的回调列表。

示例

def configure_callbacks(self):
    early_stop = EarlyStopping(monitor="val_acc", mode="max")
    checkpoint = ModelCheckpoint(monitor="val_loss")
    return [early_stop, checkpoint]

configure_gradient_clipping(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

对优化器参数执行梯度裁剪。在 optimizer_step() 之前调用。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 用于裁剪梯度的值。默认情况下，Trainer 中传递的值将在此处可用。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。默认情况下，Trainer 中传入的值将在此处可用。

示例

def configure_gradient_clipping(self, optimizer, gradient_clip_val, gradient_clip_algorithm):
    # Implement your own custom logic to clip gradients
    # You can call `self.clip_gradients` with your settings:
    self.clip_gradients(
        optimizer,
        gradient_clip_val=gradient_clip_val,
        gradient_clip_algorithm=gradient_clip_algorithm
    )

返回类型: None

configure_model()¶

在策略和精度感知上下文中创建模块的钩子。

此钩子在同一进程的 fit/val/test/predict 各阶段都会被调用，因此请确保此钩子的实现是幂等的，即在第一次调用此钩子后，后续调用应该是空操作。

返回类型: None

configure_optimizers()¶: 配置用于模型优化的优化器和学习率调度器。

configure_sharded_model()¶

已弃用。

请改用 configure_model()。

返回类型: None

static configure_torch_metrics(torch_metrics)¶

处理 torch_metrics 参数。

返回类型: MetricCollection

cpu()¶

参见 torch.nn.Module.cpu()。

返回类型: Self

cuda(device=None)¶

参数: device (Union[int, device, None]) – 如果指定，所有参数将被复制到该设备。如果为 None，将使用当前的 CUDA 设备索引。
返回值: self
返回类型: Module

property current_epoch: int¶

Trainer 中的当前 epoch，如果未附加则为 0。

返回类型: int

property device: device¶

返回类型: device

property device_mesh: Optional[DeviceMesh]¶

ModelParallelStrategy 等策略将创建设备网格，可在 configure_model() 钩子中访问该网格以并行化 LightningModule。

返回类型: Optional[ForwardRef, None]

double()¶

参见 torch.nn.Module.double()。

返回类型: Self

property dtype: Union[str, dtype]¶

返回类型: Union[str, dtype]

dump_patches: bool = False¶

property epochs_trained¶

eval()¶

将模块设置为评估模式。

这仅对某些模块有效。有关特定模块在训练/评估模式下的行为详情，即它们是否受到影响，请参阅其文档，例如 Dropout、BatchNorm 等。

这等同于 self.train(False)。

有关 .eval() 与可能与其混淆的几个类似机制之间的比较，请参见 locally-disable-grad-doc。

返回值: self
返回类型: Module

property example_input_array: Optional[Union[Tensor, tuple, dict]]¶

示例输入数组指定了模块在 forward() 方法中可以接受的内容。返回类型解释如下：

单个张量：假定模型接受一个参数，即 model.forward(model.example_input_array)
元组：输入数组应被解释为位置参数序列，即 model.forward(*model.example_input_array)
字典：输入数组表示命名关键字参数，即 model.forward(**model.example_input_array)

返回类型: Union[Tensor, tuple, dict, None]

extra_repr()¶

返回模块的额外表示。

要打印自定义的额外信息，您应该在自己的模块中重新实现此方法。单行和多行字符串都可接受。

返回类型: str

property fabric: Optional[Fabric]¶

返回类型: Optional[Fabric, None]

float()¶

参见 torch.nn.Module.float()。

返回类型: Self

abstract forward(*args, **kwargs)¶

与 torch.nn.Module.forward() 相同。

参数

*args – 您决定传递给 forward 方法的任何内容。
**kwargs – 关键字参数也是可以的。

返回类型

Any

返回值

您的模型的输出

freeze()¶

冻结所有参数以进行推理。

示例

model = MyLightningModule(...)
model.freeze()

返回类型: None

get_buffer(target)¶

如果存在，则返回由 target 指定的缓冲区，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的缓冲区的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的缓冲区
返回类型: torch.Tensor
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是缓冲区

get_extra_state()¶

返回要包含在模块 state_dict 中的任何额外状态。

如果需要存储额外的状态，请为您的模块实现此方法以及相应的 set_extra_state() 方法。构建模块的 state_dict() 时会调用此函数。

返回值: 要存储在模块 state_dict 中的任何额外状态
返回类型: object

get_parameter(target)¶

如果存在，则返回由 target 指定的参数，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的参数的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的参数
返回类型: torch.nn.Parameter
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Parameter

get_submodule(target)¶

如果存在，则返回由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

（图表显示了一个 nn.Module A。 A 有一个嵌套子模块 net_b，它本身有两个子模块 net_c 和 linear。 net_c 还有一个子模块 conv。）

要检查是否存在 linear 子模块，我们可以调用 get_submodule("net_b.linear")。要检查是否存在 conv 子模块，我们可以调用 get_submodule("net_b.net_c.conv")。

参数: target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
返回值: target 引用的子模块
返回类型: torch.nn.Module
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

property global_rank: int¶

当前进程在所有节点和设备中的索引。

返回类型: int

property global_step: int¶

所有 epoch 中看到的总训练批次。

如果未附加 Trainer，此属性值为 0。

返回类型: int

half()¶

参见 torch.nn.Module.half()。

返回类型: Self

property hparams: Union[AttributeDict, MutableMapping]¶

使用 save_hyperparameters() 保存的超参数集合。用户可以修改它。对于冻结的初始超参数集合，请使用 hparams_initial。

返回类型: Union[AttributeDict, MutableMapping]
返回值: 可变的超参数字典

property hparams_initial: AttributeDict¶

使用 save_hyperparameters() 保存的超参数集合。这些内容是只读的。可以通过 hparams 代替手动更新保存的超参数。

返回值: 不可变初始超参数
返回类型: AttributeDict

ipu(device=None)¶

将所有模型参数和缓冲区移动到 IPU。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 IPU 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

load_from_checkpoint(checkpoint_path, map_location=None, hparams_file=None, strict=None, **kwargs)¶

从检查点加载模型的主要方式。当 Lightning 保存检查点时，它会将传递给 __init__ 的参数存储在检查点中的 "hyper_parameters" 下。

通过 **kwargs 指定的任何参数将覆盖存储在 "hyper_parameters" 中的参数。

参数

checkpoint_path (Union[str, Path, IO]) – 检查点路径。这也可以是 URL 或文件类对象
map_location (Union[device, str, int, Callable[[UntypedStorage, str], Optional[UntypedStorage, None]], dict[Union[device, str, int], Union[device, str, int]], None]) – 如果您的检查点保存的是 GPU 模型，而您现在在 CPU 或不同数量的 GPU 上加载，请使用此参数映射到新的配置。其行为与 torch.load() 中相同。
hparams_file (Union[str, Path, None]) –
可选的 .yaml 或 .csv 文件路径，其结构如下例所示
```
drop_prob: 0.2
dataloader:
    batch_size: 32
```
您很可能不需要此参数，因为 Lightning 总是会将超参数保存到检查点中。但是，如果您的检查点权重没有保存超参数，请使用此方法传入一个包含您希望使用的超参数的 .yaml 文件。这些超参数将被转换为 dict 并传递给您的 LightningModule 使用。

如果您的模型的 hparams 参数是 Namespace 并且 .yaml 文件具有分层结构，您需要重构您的模型以将 hparams 视为 dict。
strict (Optional[bool, None]) – 是否严格强制 checkpoint_path 中的键与此模块的 state dict 返回的键完全匹配。默认为 True，除非设置了 LightningModule.strict_loading，在这种情况下，它将默认为 LightningModule.strict_loading 的值。
**kwargs – 初始化模型所需的任何额外关键字参数。也可以用于覆盖已保存的超参数值。

返回类型

Self

返回值

加载了权重和超参数（如果可用）的 LightningModule 实例。

注意

load_from_checkpoint 是一个类方法。您应该使用 LightningModule 类来调用它，而不是 LightningModule 实例，否则将引发 TypeError。

注意

示例

# load weights without mapping ...
model = MyLightningModule.load_from_checkpoint('path/to/checkpoint.ckpt')

# or load weights mapping all weights from GPU 1 to GPU 0 ...
map_location = {'cuda:1':'cuda:0'}
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    map_location=map_location
)

# or load weights and hyperparameters from separate files.
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    hparams_file='/path/to/hparams_file.yaml'
)

# override some of the params with new values
model = MyLightningModule.load_from_checkpoint(
    PATH,
    num_layers=128,
    pretrained_ckpt_path=NEW_PATH,
)

# predict
pretrained_model.eval()
pretrained_model.freeze()
y_hat = pretrained_model(x)

load_state_dict(state_dict, strict=True, assign=False)¶

将参数和缓冲区从 state_dict 复制到此模块及其后代中。

如果 strict 为 True，则 state_dict 的键必须与此模块的 state_dict() 函数返回的键完全匹配。

警告

如果 assign 为 True，则优化器必须在调用 load_state_dict 之后创建，除非 get_swap_module_params_on_conversion() 为 True。

参数

state_dict (dict) – 包含参数和持久缓冲区的字典。
strict (bool, 可选) – 是否严格要求 state_dict 中的键与此模块的 state_dict() 函数返回的键匹配。默认值: True
assign (bool, optional) – 设置为 False 时，保留当前模块中张量的属性，而设置为 True 时，保留 state dict 中张量的属性。唯一的例外是 Default: ``False` 的 requires_grad 字段

返回值

missing_keys 是一个字符串列表，包含此模块需要但
提供的 state_dict 中缺失的键。
unexpected_keys 是一个字符串列表，包含此模块
不预期但提供的 state_dict 中存在的键。

返回类型

包含 missing_keys 和 unexpected_keys 字段的 NamedTuple

注意

如果参数或缓冲区被注册为 None，并且其对应的键存在于 state_dict 中，load_state_dict() 将引发 RuntimeError。

property local_rank: int¶

当前进程在单个节点内的索引。

返回类型: int

记录键值对。

示例

self.log('train_loss', loss)

每个钩子的默认行为在此处有文档说明：extensions/logging:Automatic Logging。

参数

name (str) – 要记录的键。如果使用 DDP 或任何其他分布式策略，则必须在所有进程中保持一致。
value (Union[Metric, Tensor, int, float]) – 要记录的值。可以是 float、Tensor 或 Metric。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图。
sync_dist (bool) – 如果为 True，则在设备之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 DDP 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个 dataloader 时）。如果 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch_size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
metric_attribute (Optional[str, None]) – 为了恢复指标状态，Lightning 需要您的模型中 torchmetrics.Metric 的引用。如果它是一个模型属性，则会自动找到。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

一次记录字典中的值。

示例

values = {'loss': loss, 'acc': acc, ..., 'metric_n': metric_n}
self.log_dict(values)

参数

dictionary (Union[Mapping[str, Union[Metric, Tensor, int, float]], MetricCollection]) – 键值对。如果使用 DDP 或任何其他分布式策略，所有进程的键必须相同。值可以是 float、Tensor、Metric 或 MetricCollection。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。None 会自动记录 training_step，但不记录 validation/test_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。None 会自动记录 val/test step，但不记录 training_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图
sync_dist (bool) – 如果为 True，则在 GPU/TPU 之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 ddp 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个时）。如果为 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

property logger: Optional[Union[Logger, Logger]]¶

指向 Trainer 中 logger 对象的引用。

返回类型: Union[Logger, Logger, None]

property loggers: Union[list[pytorch_lightning.loggers.logger.Logger], list[lightning_fabric.loggers.logger.Logger]]¶

指向 Trainer 中 loggers 列表的引用。

返回类型: Union[list[Logger], list[Logger]]

lr_scheduler_step(scheduler, metric)¶

覆盖此方法以调整 Trainer 调用每个调度器的默认方式。默认情况下，Lightning 根据每个调度器的 interval 调用 step()，如示例所示。

参数

scheduler (Union[LRScheduler, ReduceLROnPlateau]) – 学习率调度器。
metric (Optional[Any, None]) – 用于像 ReduceLROnPlateau 这样的调度器的监视器值。

示例

# DEFAULT
def lr_scheduler_step(self, scheduler, metric):
    if metric is None:
        scheduler.step()
    else:
        scheduler.step(metric)

# Alternative way to update schedulers if it requires an epoch value
def lr_scheduler_step(self, scheduler, metric):
    scheduler.step(epoch=self.current_epoch)

返回类型: None

lr_schedulers()¶

返回训练期间使用的学习率调度器。对于手动优化很有用。

返回类型: Union[None, list[Union[LRScheduler, ReduceLROnPlateau]], LRScheduler, ReduceLROnPlateau]
返回值: 单个调度器，或者在存在多个调度器时返回一个列表，如果在 configure_optimizers() 中没有返回调度器，则返回 None。

manual_backward(loss, *args, **kwargs)¶

在手动进行优化时，可以直接从您的 training_step() 中调用此方法。通过使用此方法，Lightning 可以确保在使用混合精度时应用所有适当的缩放。

更多示例请参见 manual optimization。

示例

def training_step(...):
    opt = self.optimizers()
    loss = ...
    opt.zero_grad()
    # automatically applies scaling, etc...
    self.manual_backward(loss)
    opt.step()

参数

loss (Tensor) – 用于计算梯度的张量。必须附加计算图。
*args – 要转发给 backward() 的额外位置参数
**kwargs – 要转发给 backward() 的额外关键字参数

返回类型

None

modules()¶

返回网络中所有模块的迭代器。

Yields: Module – 网络中的一个模块

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.modules()):
...     print(idx, '->', m)

0 -> Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)
1 -> Linear(in_features=2, out_features=2, bias=True)

返回类型: Iterator[Module]

mtia(device=None)¶

将所有模型参数和缓冲区移动到 MTIA。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 MTIA 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

named_buffers(prefix='', recurse=True, remove_duplicate=True)¶

返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。

参数

prefix (str) – 要添加到所有缓冲区名称前的字符串前缀。
recurse (bool, optional) – 如果为 True，则生成此模块及其所有子模块的缓冲区。否则，仅生成此模块的直接成员缓冲区。默认为 True。
remove_duplicate (bool, optional) – 是否移除结果中的重复缓冲区。默认为 True。

Yields

(str, torch.Tensor) – 包含名称和缓冲区的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, buf in self.named_buffers():
>>>     if name in ['running_var']:
>>>         print(buf.size())

返回类型: Iterator[Tuple[str, Tensor]]

named_children()¶

返回直接子模块的迭代器，同时产生模块名称和模块本身。

Yields: (str, Module) – 包含名称和子模块的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, module in model.named_children():
>>>     if name in ['conv4', 'conv5']:
>>>         print(module)

返回类型: Iterator[Tuple[str, Module]]

named_modules(memo=None, prefix='', remove_duplicate=True)¶

返回网络中所有模块的迭代器，同时产生模块名称和模块本身。

参数

memo (Optional[Set[Module], None]) – 用于存储已添加到结果中的模块集合的备忘录
prefix (str) – 将添加到模块名称前的字符串前缀
remove_duplicate (bool) – 是否移除结果中重复的模块实例

Yields

(str, Module) – 包含名称和模块的元组

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.named_modules()):
...     print(idx, '->', m)

0 -> ('', Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
))
1 -> ('0', Linear(in_features=2, out_features=2, bias=True))

named_parameters(prefix='', recurse=True, remove_duplicate=True)¶

返回模块参数的迭代器，同时产生参数名称和参数本身。

参数

prefix (str) – 要添加到所有参数名称前的字符串前缀。
recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
remove_duplicate (bool, optional) – 是否移除结果中重复的参数。默认为 True。

Yields

(str, Parameter) – 包含名称和参数的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, param in self.named_parameters():
>>>     if name in ['bias']:
>>>         print(param.size())

返回类型: Iterator[Tuple[str, Parameter]]

on_after_backward()¶

在 loss.backward() 之后且在优化器步进之前调用。

注意

如果使用原生 AMP，此时梯度不会被取消缩放。如果您需要未缩放的梯度，请使用 on_before_optimizer_step。

返回类型: None

on_after_batch_transfer(batch, dataloader_idx)¶

覆盖此方法以在批次转移到设备后修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_after_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = gpu_transforms(batch['x'])
    return batch

另请参阅

on_before_batch_transfer()
transfer_batch_to_device()

on_before_backward(loss)¶

在 loss.backward() 之前调用。

参数: loss (Tensor) – 损失值，除以进行梯度累积的批次数，如果使用 AMP 则会进行缩放。
返回类型: None

on_before_batch_transfer(batch, batch_idx, dataloader_idx=0)¶

覆盖此方法以在批次转移到设备之前修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_before_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = transforms(batch['x'])
    return batch

另请参阅

on_after_batch_transfer()
transfer_batch_to_device()

on_before_optimizer_step(optimizer)¶

在 optimizer.step() 之前调用。

如果使用梯度累积，则在梯度累积完成后调用此 hook。参阅: :paramref:`~pytorch_lightning.trainer.trainer.Trainer.accumulate_grad_batches`。

如果使用 AMP，损失值在此钩子调用前会取消缩放。有关梯度缩放的更多信息，请参阅这些文档。

如果进行梯度裁剪，此时梯度尚未被裁剪。

参数: optimizer (Optimizer) – 正在使用的当前优化器。

示例

def on_before_optimizer_step(self, optimizer):
    # example to inspect gradient information in tensorboard
    if self.trainer.global_step % 25 == 0:  # don't make the tf file huge
        for k, v in self.named_parameters():
            self.logger.experiment.add_histogram(
                tag=k, values=v.grad, global_step=self.trainer.global_step
            )

返回类型: None

on_before_zero_grad(optimizer)¶

在 training_step() 之后且在 optimizer.zero_grad() 之前调用。

在训练循环中，在优化器步长后和梯度清零前调用。是检查权重更新后权重信息的好地方。

这里是它被调用的地方

for optimizer in optimizers:
    out = training_step(...)

    model.on_before_zero_grad(optimizer) # < ---- called here
    optimizer.zero_grad()

    backward()

参数: optimizer (Optimizer) – 应清零其梯度的优化器。
返回类型: None

on_fit_end()¶

在 fit 的最后调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

on_fit_start()¶

在 fit 的最开始调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

property on_gpu: bool¶

如果此模型当前位于 GPU 上，则返回 True。

对于在 LightningModule 中设置标志以区分 CPU 和 GPU 的行为很有用。

返回类型: bool

on_load_checkpoint(checkpoint)¶

由 Lightning 调用以恢复您的模型。如果您使用 on_save_checkpoint() 保存了某些内容，这是您恢复它们的机会。

参数: checkpoint (dict[str, Any]) – 已加载的检查点

示例

def on_load_checkpoint(self, checkpoint):
    # 99% of the time you don't need to implement this method
    self.something_cool_i_want_to_save = checkpoint['something_cool_i_want_to_save']

注意

Lightning 会自动恢复全局步长、epoch 和训练状态，包括 amp 缩放。您无需恢复任何与训练相关的内容。

返回类型: None

on_predict_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在预测循环中批次之后调用。

参数

outputs (Optional[Any, None]) – predict_step(x) 的输出
batch (Any) – 预测 DataLoader 返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_batch_start(batch, batch_idx, dataloader_idx=0)¶

在预测循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_end()¶

在预测结束时调用。

返回类型: None

on_predict_epoch_end()¶

在预测结束时调用。

返回类型: None

on_predict_epoch_start()¶

在预测开始时调用。

返回类型: None

on_predict_model_eval()¶

预测循环开始时调用。

预测循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。

返回类型: None

on_predict_start()¶

在预测开始时调用。

返回类型: None

on_save_checkpoint(checkpoint)¶

Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。

参数: checkpoint (dict[str, Any]) – 在检查点字典被写入文件之前的完整字典。此钩子函数的实现可以将额外数据插入此字典。

示例

def on_save_checkpoint(self, checkpoint):
    # 99% of use cases you don't need to implement this method
    checkpoint['something_cool_i_want_to_save'] = my_cool_pickable_object

注意

Lightning 会保存训练的所有方面（周期、全局步数等），包括 amp scaling。您无需存储任何关于训练的内容。

返回类型: None

on_test_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在测试循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – test_step(x) 的输出。
batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_batch_start(batch, batch_idx, dataloader_idx=0)¶

在测试循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_end()¶

在测试结束时调用。

返回类型: None

on_test_epoch_end()¶

在测试循环中 epoch 的最后调用。

返回类型: None

on_test_epoch_start()¶

在测试循环中 epoch 的最开始调用。

返回类型: None

on_test_model_eval()¶

测试循环开始时调用。

测试循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_test_model_train()。

返回类型: None

on_test_model_train()¶

测试循环结束时调用。

测试循环默认将 LightningModule 的 training 模式恢复到开始测试之前的状态。重写此钩子函数以改变此行为。另请参见 on_test_model_eval()。

返回类型: None

on_test_start()¶

在测试开始时调用。

返回类型: None

on_train_batch_end(outputs, batch, batch_idx)¶

在训练循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – training_step(x) 的输出。
batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

注意

此处 outputs["loss"] 的值将是根据 accumulate_grad_batches 对 training_step 返回的损失值进行归一化后的值。

返回类型: None

on_train_batch_start(batch, batch_idx)¶

在训练循环中该批次发生任何事情之前调用。

如果此处返回 -1，将跳过当前周期的剩余训练。

参数

batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

返回类型

Optional[int, None]

on_train_end()¶

在训练结束、logger 实验关闭之前调用。

返回类型: None

on_train_epoch_end()¶

在训练循环中 epoch 的最后调用。

要在周期结束时访问所有批次输出，您可以将步输出缓存为 LightningModule 的属性，并在此钩子函数中访问它们

class MyLightningModule(L.LightningModule):
    def __init__(self):
        super().__init__()
        self.training_step_outputs = []

    def training_step(self):
        loss = ...
        self.training_step_outputs.append(loss)
        return loss

    def on_train_epoch_end(self):
        # do something with all training_step outputs, for example:
        epoch_mean = torch.stack(self.training_step_outputs).mean()
        self.log("training_epoch_mean", epoch_mean)
        # free up the memory
        self.training_step_outputs.clear()

on_train_epoch_start()¶

在训练循环中 epoch 的最开始调用。

返回类型: None

on_train_start()¶

在健全性检查之后、训练开始时调用。

返回类型: None

on_validation_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在验证循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – validation_step(x) 的输出。
batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_batch_start(batch, batch_idx, dataloader_idx=0)¶

在验证循环中该批次发生任何事情之前调用。

参数

batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_end()¶

在验证结束时调用。

返回类型: None

on_validation_epoch_end()¶: 在验证循环中 epoch 的最后调用。

on_validation_epoch_start()¶

在验证循环中 epoch 的最开始调用。

返回类型: None

on_validation_model_eval()¶

验证循环开始时调用。

验证循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_validation_model_train()。

返回类型: None

on_validation_model_train()¶

验证循环结束时调用。

验证循环默认将 LightningModule 的 training 模式恢复到开始验证之前的状态。重写此钩子函数以改变此行为。另请参见 on_validation_model_eval()。

返回类型: None

on_validation_model_zero_grad()¶

由训练循环调用，在进入验证循环之前释放梯度。

返回类型: None

on_validation_start()¶

在验证开始时调用。

返回类型: None

optimizer_step(epoch, batch_idx, optimizer, optimizer_closure=None)¶

覆盖此方法以调整 Trainer 调用优化器的默认方式。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Union[Optimizer, LightningOptimizer]) – PyTorch 优化器
optimizer_closure (Optional[Callable[[], Any], None]) – 优化器闭包。必须执行此闭包，因为它包含对 training_step()、optimizer.zero_grad() 和 backward() 的调用。

示例

def optimizer_step(self, epoch, batch_idx, optimizer, optimizer_closure):
    # Add your custom logic to run directly before `optimizer.step()`

    optimizer.step(closure=optimizer_closure)

    # Add your custom logic to run directly after `optimizer.step()`

返回类型: None

optimizer_zero_grad(epoch, batch_idx, optimizer)¶

覆盖此方法以更改 optimizer.zero_grad() 的默认行为。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Optimizer) – PyTorch 优化器

示例

# DEFAULT
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad()

# Set gradients to `None` instead of zero to improve performance (not required on `torch>=2.0.0`).
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad(set_to_none=True)

有关上述示例的解释，请参见 torch.optim.Optimizer.zero_grad()。

返回类型: None

optimizers(use_pl_optimizer=True)¶

返回训练期间使用的优化器。对于手动优化很有用。

参数: use_pl_optimizer (bool) – 如果为 True，则会将优化器封装在 LightningOptimizer 中，以自动处理精度、分析以及步调用计数，从而实现正确的日志记录和检查点。它专门封装 step 方法，不支持没有此方法的自定义优化器。
返回类型: Union[Optimizer, LightningOptimizer, _FabricOptimizer, list[Optimizer], list[LightningOptimizer], list[_FabricOptimizer]]
返回值: 单个优化器，或者在存在多个优化器时返回一个列表。

property output_chunk_length: Optional[int]¶

模型一次预测的时间步长数量。

返回类型: Optional[int, None]

parameters(recurse=True)¶

返回模块参数的迭代器。

这通常传递给优化器。

参数: recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
Yields: Parameter – 模块参数

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for param in model.parameters():
>>>     print(type(param), param.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Parameter]

pred_batch_size: Optional[int]¶

pred_mc_dropout: Optional[bool]¶

pred_n: Optional[int]¶

pred_n_jobs: Optional[int]¶

pred_num_samples: Optional[int]¶

pred_roll_size: Optional[int]¶

predict_dataloader()¶

指定预测样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

建议所有数据下载和准备工作都在 prepare_data() 中进行。

predict()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any
返回值: 一个 torch.utils.data.DataLoader 或其序列，指定预测样本。

predict_likelihood_parameters: Optional[bool]¶

predict_step(batch, batch_idx, dataloader_idx=None)¶

执行预测步骤

batch: Darts 的 InferenceDataset 的输出 - 包含 (past_target, past_covariates, historic_future_covariates, future_covariates, future_past_covariates, input time series, prediction start time step) 的元组
batch_idx: 当前批次的批次索引
dataloader_idx: 数据加载器索引

返回类型: Sequence[TimeSeries]

prepare_data()¶

警告

不要在此方法中为模型设置状态（请改用 setup 方法），因为此方法不会在每个设备上调用

示例

def prepare_data(self):
    # good
    download_data()
    tokenize()
    etc()

    # bad
    self.split = data_split
    self.some_state = some_other_state()

在分布式环境中，prepare_data 可以通过两种方式调用（使用 prepare_data_per_node）

每个节点一次。这是默认设置，仅在 LOCAL_RANK=0 上调用。
总共一次。仅在 GLOBAL_RANK=0 上调用。

示例

# DEFAULT
# called once per node on LOCAL_RANK=0 of that node
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = True

# call on GLOBAL_RANK=0 (great for shared file systems)
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = False

此方法在请求数据加载器之前调用

model.prepare_data()
initialize_distributed()
model.setup(stage)
model.train_dataloader()
model.val_dataloader()
model.test_dataloader()
model.predict_dataloader()

返回类型: None

prepare_data_per_node: bool¶

print(*args, **kwargs)¶

仅从进程 0 打印。在任何分布式模式下使用此方法以仅记录一次。

参数

*args – 要打印的内容。与 Python 内置的 print 函数相同。
**kwargs – 与 Python 内置的 print 函数相同。

示例

def forward(self, x):
    self.print(x, 'in forward')

返回类型: None

register_backward_hook(hook)¶

在模块上注册后向钩子。

此函数已被弃用，推荐使用 register_full_backward_hook()，此函数的行为将在未来版本中改变。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_buffer(name, tensor, persistent=True)¶

向模块添加缓冲区。

这通常用于注册不应被视为模型参数的缓冲区。例如，BatchNorm 的 running_mean 不是参数，但却是模块状态的一部分。缓冲区默认是持久化的，并将与参数一起保存。通过将 persistent 设置为 False 可以改变此行为。持久化缓冲区和非持久化缓冲区唯一的区别在于后者将不包含在此模块的 state_dict 中。

缓冲区可以使用给定的名称作为属性访问。

参数

name (str) – 缓冲区的名称。可以使用给定的名称从此模块访问缓冲区
tensor (Tensor 或 None) – 要注册的缓冲区。如果为 None，则对缓冲区执行的操作（例如 cuda）将被忽略。如果为 None，缓冲区将不包含在模块的 state_dict 中。
persistent (bool) – 缓冲区是否是此模块 state_dict 的一部分。

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> self.register_buffer('running_mean', torch.zeros(num_features))

返回类型: None

register_forward_hook(hook, *, prepend=False, with_kwargs=False, always_call=False)¶

在模块上注册前向钩子。

每次 forward() 计算出输出后，都将调用此 hook。

如果 with_kwargs 为 False 或未指定，则输入仅包含提供给模块的位置参数。关键字参数不会传递给 hook，仅传递给 forward。hook 可以修改输出。它可以就地修改输入，但由于它是在 forward() 调用后调用的，因此对 forward 没有影响。此 hook 应具有以下签名：

hook(module, args, output) -> None or modified output

如果 with_kwargs 为 True，则前向钩子函数将接收传递给 forward 函数的 kwargs，并预期返回可能修改过的输出。此钩子函数应具有以下签名：

hook(module, args, kwargs, output) -> None or modified output

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 True，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之后触发。请注意，使用 register_module_forward_hook() 注册的全局 forward 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 True，hook 将接收传递给 forward 函数的 kwargs。默认值：False
always_call (bool) – 如果为 True，无论在调用模块时是否引发异常，hook 都将被运行。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_forward_pre_hook(hook, *, prepend=False, with_kwargs=False)¶

在模块上注册前向预钩子。

每次调用 forward() 之前，都将调用此 hook。

hook(module, args) -> None or modified input

hook(module, args, kwargs) -> None or a tuple of modified input and kwargs

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之后触发。请注意，使用 register_module_forward_pre_hook() 注册的全局 forward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 true，hook 将接收传递给 forward 函数的 kwargs。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_hook(hook, prepend=False)¶

在模块上注册后向钩子。

每当计算相对于模块的梯度时，此钩子函数都将被调用，即只有当计算相对于模块输出的梯度时，此钩子函数才会执行。此钩子函数应具有以下签名：

hook(module, grad_input, grad_output) -> tuple(Tensor) or None

警告

使用后向钩子时，不允许原地修改输入或输出，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之后触发。请注意，使用 register_module_full_backward_hook() 注册的全局 backward 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_pre_hook(hook, prepend=False)¶

在模块上注册后向预钩子。

每当计算模块的梯度时，此钩子函数都将被调用。此钩子函数应具有以下签名：

hook(module, grad_output) -> tuple[Tensor] or None

警告

使用后向钩子时，不允许原地修改输入，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之后触发。请注意，使用 register_module_full_backward_pre_hook() 注册的全局 backward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_load_state_dict_post_hook(hook)¶

注册一个后钩子函数，在调用模块的 load_state_dict() 后运行。

它应该具有以下签名：: hook(module, incompatible_keys) -> None

如有需要，可以原地修改给定的 incompatible_keys。

请注意，当使用 strict=True 调用 load_state_dict() 时执行的检查会受到 hook 对 missing_keys 或 unexpected_keys 所做修改的影响，这是预期行为。向任一键集添加内容将在 strict=True 时导致错误被抛出，而清除所有丢失和意外的键则可以避免错误。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_load_state_dict_pre_hook(hook)¶

注册一个预钩子函数，在调用模块的 load_state_dict() 之前运行。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata, strict, missing_keys, unexpected_keys, error_msgs) -> None # noqa: B950

参数: hook (Callable) – 可调用钩子函数，将在加载状态字典之前被调用。

register_module(name, module)¶

add_module() 的别名。

返回类型: None

register_parameter(name, param)¶

向模块添加参数。

参数可以使用给定的名称作为属性访问。

参数

name (str) – 参数的名称。可以使用给定的名称从此模块访问参数
param (Parameter 或 None) – 要添加到模块的参数。如果为 None，则对参数执行的操作（例如 cuda）将被忽略。如果为 None，参数将不包含在模块的 state_dict 中。

返回类型

None

register_state_dict_post_hook(hook)¶

为 state_dict() 方法注册一个后钩子。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata) -> None

注册的钩子函数可以原地修改 state_dict。

register_state_dict_pre_hook(hook)¶

为 state_dict() 方法注册一个预钩子。

它应该具有以下签名：: hook(module, prefix, keep_vars) -> None

注册的钩子函数可用于在进行 state_dict 调用之前执行预处理。

requires_grad_(requires_grad=True)¶

更改此模块中是否应记录参数上的自动梯度操作。

此方法原地设置参数的 requires_grad 属性。

此方法有助于冻结模块的一部分用于微调，或单独训练模型的各个部分（例如，GAN 训练）。

有关 .requires_grad_() 和几个可能与其混淆的类似机制的比较，请参见 locally-disable-grad-doc。

参数: requires_grad (bool) – 是否应由 autograd 记录此模块中参数的操作。默认值：True。
返回值: self
返回类型: Module

save_hyperparameters(*args, ignore=None, frame=None, logger=True)¶

将参数保存到 hparams 属性。

参数

args (Any) – 可以是 dict、NameSpace 或 OmegaConf 的单个对象，或来自类 __init__ 的字符串名称或参数
ignore (Union[str, Sequence[str], None]) – 要忽略的来自类 __init__ 的参数名称或参数名称列表
frame (Optional[frame, None]) – 一个 frame 对象。默认值为 None
logger (bool) – 是否将超参数发送到日志记录器。默认值：True

示例：

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # manually assign arguments
...         self.save_hyperparameters('arg1', 'arg3')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class AutomaticArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # equivalent automatic
...         self.save_hyperparameters()
...     def forward(self, *args, **kwargs):
...         ...
>>> model = AutomaticArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg2": abc
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class SingleArgModel(HyperparametersMixin):
...     def __init__(self, params):
...         super().__init__()
...         # manually assign single argument
...         self.save_hyperparameters(params)
...     def forward(self, *args, **kwargs):
...         ...
>>> model = SingleArgModel(Namespace(p1=1, p2='abc', p3=3.14))
>>> model.hparams
"p1": 1
"p2": abc
"p3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # pass argument(s) to ignore as a string or in a list
...         self.save_hyperparameters(ignore='arg2')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

返回类型: None

set_extra_state(state)¶

设置加载的 state_dict 中包含的额外状态。

此函数由 load_state_dict() 调用，用于处理 state_dict 中找到的任何额外状态。如果需要在模块的 state_dict 中存储额外状态，请为您的模块实现此函数以及相应的 get_extra_state()。

参数: state (dict) – 来自 state_dict 的额外状态
返回类型: None

set_mc_dropout(active)¶

set_predict_parameters(n, num_samples, roll_size, batch_size, n_jobs, predict_likelihood_parameters, mc_dropout)¶

在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置

返回类型: None

set_submodule(target, module)¶

如果存在，则设置由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

(图示为一个 nn.Module A。A 有一个嵌套子模块 net_b，其本身又有两个子模块 net_c 和 linear。net_c 然后有一个子模块 conv。)

要用一个新的子模块 Linear 覆盖 Conv2d，您可以调用 set_submodule("net_b.net_c.conv", nn.Linear(33, 16))。

参数

target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
module (Module) – 用于设置子模块的模块。

Raises

ValueError – 如果目标字符串为空
AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

返回类型

None

setup(stage)¶

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'

示例

class LitModel(...):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        download_data()
        tokenize()

        # don't do this
        self.something = else

    def setup(self, stage):
        data = load_data(...)
        self.l1 = nn.Linear(28, data.num_classes)

返回类型: None

share_memory()¶

参见 torch.Tensor.share_memory_()。

返回类型: ~T

state_dict(*args, destination=None, prefix='', keep_vars=False)¶

返回包含模块完整状态引用的字典。

参数和持久缓冲区（例如，运行平均值）都包含在内。键是相应的参数和缓冲区名称。设置为 None 的参数和缓冲区不包含在内。

注意

返回的对象是浅拷贝。它包含对模块参数和缓冲区的引用。

警告

目前 state_dict() 也按顺序接受 destination、prefix 和 keep_vars 的位置参数。但是，此用法已被弃用，未来版本将强制使用关键字参数。

警告

请避免使用参数 destination，因为它并非为终端用户设计。

参数

destination (dict, optional) – 如果提供，模块的状态将更新到此字典中，并返回相同的对象。否则，将创建一个 OrderedDict 并返回。默认值：None。
prefix (str, optional) – 添加到参数和缓冲区名称的前缀，用于在 state_dict 中构成键。默认值：''。
keep_vars (bool, optional) – 默认情况下，state dict 中返回的 Tensor s 与 autograd 分离。如果设置为 True，将不会进行分离。默认值：False。

返回值

包含模块完整状态的字典

返回类型

dict

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> module.state_dict().keys()
['bias', 'weight']

property strict_loading: bool¶

确定 Lightning 如何使用 .load_state_dict(…, strict=model.strict_loading) 加载此模型。

返回类型: bool

property supports_probabilistic_prediction: bool¶

返回类型: bool

teardown(stage)¶

在 fit（训练 + 验证）、验证、测试或预测结束时调用。

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'
返回类型: None

test_dataloader()¶

指定测试样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理并分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

test()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果你不需要测试数据集和 test_step()，则无需实现此方法。

返回类型: Any

test_step(*args, **kwargs)¶

对测试集中的单个批次数据进行操作。在此步骤中，您通常会生成示例或计算任何感兴趣的内容，例如准确率。

参数

batch – 您的数据可迭代对象（通常是 DataLoader）的输出。
batch_idx – 此批次的索引。
dataloader_idx – 生成此批次的数据加载器索引。（仅在使用多个数据加载器时）

返回类型

Union[Tensor, Mapping[str, Any], None]

返回值

Tensor - 损失张量
dict - 字典。可以包含任意键，但必须包含键 'loss'。
None - 跳到下一个批次。

# if you have one test dataloader:
def test_step(self, batch, batch_idx): ...

# if you have multiple test dataloaders:
def test_step(self, batch, batch_idx, dataloader_idx=0): ...

示例

# CASE 1: A single test dataset
def test_step(self, batch, batch_idx):
    x, y = batch

    # implement your own
    out = self(x)
    loss = self.loss(out, y)

    # log 6 example images
    # or generated text... or whatever
    sample_imgs = x[:6]
    grid = torchvision.utils.make_grid(sample_imgs)
    self.logger.experiment.add_image('example_images', grid, 0)

    # calculate acc
    labels_hat = torch.argmax(out, dim=1)
    test_acc = torch.sum(y == labels_hat).item() / (len(y) * 1.0)

    # log the outputs!
    self.log_dict({'test_loss': loss, 'test_acc': test_acc})

如果你传入多个测试数据加载器，test_step() 将会有一个附加参数。我们建议将默认值设置为 0，以便你可以在单个和多个数据加载器之间快速切换。 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs`

# CASE 2: multiple test dataloaders
def test_step(self, batch, batch_idx, dataloader_idx=0):
    # dataloader_idx tells you which dataset this is.
    ...

注意

如果您不需要测试，则无需实现此方法。

注意

当调用 test_step() 时，模型已经处于评估模式，并且 PyTorch 梯度已禁用。在测试 epoch 结束时，模型会回到训练模式，并启用梯度。

to(*args, **kwargs)¶

参见 torch.nn.Module.to()。

返回类型: Self

to_dtype(dtype)¶: 将模块精度（默认为 float32）转换为其他精度。

to_empty(*, device, recurse=True)¶

在不复制存储的情况下，将参数和缓冲区移动到指定设备。

参数

device (torch.device) – 此模块中参数和缓冲区的目标设备。
recurse (bool) – 是否应将子模块的参数和缓冲区递归地移动到指定设备。

返回值

self

返回类型

Module

to_onnx(file_path, input_sample=None, **kwargs)¶

将模型保存为 ONNX 格式。

参数

file_path (Union[str, Path, BytesIO]) – 应保存 onnx 模型的文件路径。
input_sample (Optional[Any, None]) – 用于跟踪的输入。默认值：None（使用 self.example_input_array）
**kwargs – 将传递给 torch.onnx.export 函数。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)

model = SimpleModel()
input_sample = torch.randn(1, 64)
model.to_onnx("export.onnx", input_sample, export_params=True)

返回类型: None

to_torchscript(file_path=None, method='script', example_inputs=None, **kwargs)¶

默认情况下将整个模型编译为 ScriptModule。如果想使用追踪（tracing），请提供参数 method='trace' 并确保提供了 example_inputs 参数，或者模型设置了 example_input_array。如果想自定义被脚本化的模块，应该重写此方法。如果想返回多个模块，我们建议使用字典。

参数

file_path (Union[str, Path, None]) – 保存 torchscript 的路径。默认值：None（不保存文件）。
method (Optional[str, None]) – 是使用 TorchScript 的 script 方法还是 trace 方法。默认值：‘script’
example_inputs (Optional[Any, None]) – 当 method 设置为 ‘trace’ 时用于追踪的输入。默认值：None（使用 example_input_array）
**kwargs – 将传递给 torch.jit.script() 或 torch.jit.trace() 函数的附加参数。

注意

需要实现 forward() 方法。
导出的脚本将被设置为评估模式。
建议您安装最新支持版本的 PyTorch 以无限制地使用此功能。另请参见 torch.jit 文档以了解支持的功能。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)))

model = SimpleModel()
model.to_torchscript(file_path="model.pt")

torch.jit.save(model.to_torchscript(
    file_path="model_trace.pt", method='trace', example_inputs=torch.randn(1, 64))
)

返回类型: Union[ScriptModule, dict[str, ScriptModule]]
返回值: 此 LightningModule 作为 torchscript，无论是否定义了 file_path。

toggle_optimizer(optimizer)¶

确保在训练步骤中仅计算当前优化器参数的梯度，以防止在多优化器设置中出现悬空梯度。

它与 untoggle_optimizer() 配合使用，以确保正确重置 param_requires_grad_state。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要切换的优化器。
返回类型: None

train(mode=True)¶

将模块设置为训练模式。

这仅对某些模块有影响。有关它们在训练/评估模式下的行为详情，例如它们是否受影响（例如 Dropout、BatchNorm 等），请参阅特定模块的文档。

参数: mode (bool) – 是否设置训练模式 (True) 或评估模式 (False)。默认值: True。
返回值: self
返回类型: Module

train_criterion_reduction: Optional[str]¶

train_dataloader()¶

指定训练样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

除非将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数，否则返回的数据加载器不会被重新加载。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理并分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

fit()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any

property trainer: Trainer¶

返回类型: Trainer

training: bool¶

training_step(train_batch, batch_idx)¶

执行训练步骤

返回类型: Tensor

transfer_batch_to_device(batch, device, dataloader_idx)¶

如果您的 DataLoader 返回包装在自定义数据结构中的张量，请覆盖此钩子。

下面列出的数据类型（以及它们的任意嵌套）是开箱即用的支持

torch.Tensor 或任何实现了 .to(…) 的东西
list
dict
tuple

对于其他任何东西，你需要定义数据如何移动到目标设备 (CPU, GPU, TPU, …)。

注意

参数

batch (Any) – 需要转移到新设备的数据批次。
device (device) – PyTorch 中定义的目标设备。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据在新设备上的引用。

示例

def transfer_batch_to_device(self, batch, device, dataloader_idx):
    if isinstance(batch, CustomBatch):
        # move all tensors in your custom data structure to the device
        batch.samples = batch.samples.to(device)
        batch.targets = batch.targets.to(device)
    elif dataloader_idx == 0:
        # skip device transfer for the first dataloader or anything you wish
        pass
    else:
        batch = super().transfer_batch_to_device(batch, device, dataloader_idx)
    return batch

另请参阅

move_data_to_device()
apply_to_collection()

type(dst_type)¶

参见 torch.nn.Module.type()。

返回类型: Self

unfreeze()¶

解冻所有参数以进行训练。

model = MyLightningModule(...)
model.unfreeze()

返回类型: None

untoggle_optimizer(optimizer)¶

重置使用 toggle_optimizer() 切换的梯度必需状态。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要取消切换的优化器。
返回类型: None

val_criterion_reduction: Optional[str]¶

val_dataloader()¶

指定验证样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

除非将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数，否则返回的数据加载器不会被重新加载。

建议所有数据下载和准备工作都在 prepare_data() 中进行。

fit()
validate()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果你不需要验证数据集和 validation_step()，则无需实现此方法。

返回类型: Any

validation_step(val_batch, batch_idx)¶

执行验证步骤

返回类型: Tensor

xpu(device=None)¶

将所有模型参数和缓冲区移动到 XPU。

这也会使得相关的参数和缓冲区成为不同的对象。因此，如果模块将在 XPU 上运行并进行优化，则应该在构建优化器之前调用它。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

zero_grad(set_to_none=True)¶

重置所有模型参数的梯度。

请参阅 torch.optim.Optimizer 下的类似函数，了解更多背景信息。

参数: set_to_none (bool) – 不设置为零，而是将梯度设置为 None。请参阅 torch.optim.Optimizer.zero_grad() 了解详情。
返回类型: None

class darts.models.forecasting.pl_forecasting_module.PLMixedCovariatesModule(input_chunk_length, output_chunk_length, output_chunk_shift=0, train_sample_shape=None, loss_fn=MSELoss(), torch_metrics=None, likelihood=None, optimizer_cls=<class 'torch.optim.adam.Adam'>, optimizer_kwargs=None, lr_scheduler_cls=None, lr_scheduler_kwargs=None, use_reversible_instance_norm=False)[源代码]¶

基类：PLForecastingModule, ABC

基于 PyTorch Lightning 的预测模块。

此类旨在被继承以创建新的基于 PyTorch Lightning 的预测模块。子类化此类时，请确保添加具有以下签名的方

PLForecastingModule.__init__()

PLForecastingModule.forward()

PLForecastingModule._process_input_batch()

PLForecastingModule._produce_train_output()

PLForecastingModule._get_batch_prediction()

在子类 MyModel 的 __init__() 函数中调用 super(MyModel, self).__init__(**kwargs)，其中 kwargs 是 PLForecastingModule 的参数。

参数

input_chunk_length (int) – 模型输入的时间步长数量（每块）。适用于目标序列以及过去和/或未来协变量（如果模型支持）。
output_chunk_length (int) – 内部模型一次预测（每块）的时间步长数量。此外，未来协变量的未来值用作模型输入的数量（如果模型支持未来协变量）。它与 predict() 中使用的预测视野 n 不同，后者是使用一次性预测或自回归预测生成的所需预测点数。设置 n <= output_chunk_length 可防止自回归。当协变量未能充分延伸到未来时，这非常有用，或者为了禁止模型使用过去和/或未来协变量的未来值进行预测（取决于模型的协变量支持）。
train_sample_shape (Optional[tuple, None]) – 模型的输入形状，用于在不调用 fit_from_dataset 的情况下实例化模型，并对用于重新训练或预测的新训练/推理数据集执行健全性检查。
loss_fn (_Loss) – 用于训练的 PyTorch 损失函数。如果指定了 likelihood 参数，则此参数对于概率模型将被忽略。默认值：torch.nn.MSELoss()。
torch_metrics (Union[Metric, MetricCollection, None]) – 用于评估的 torch 指标或 MetricCollection。可在 https://torchmetrics.readthedocs.io/en/latest/ 找到可用指标的完整列表。默认值：None。
likelihood (Optional[TorchLikelihood, None]) – Darts 的 Likelihood 模型之一，用于概率预测。默认值：None。
optimizer_cls (Optimizer) – 要使用的 PyTorch 优化器类。默认值：torch.optim.Adam。
optimizer_kwargs (Optional[dict, None]) – 可选地，PyTorch 优化器的一些关键字参数（例如，{'lr': 1e-3} 用于指定学习率）。否则将使用选定的 optimizer_cls 的默认值。默认值：None。
lr_scheduler_cls (Optional[_LRScheduler, None]) – 可选地，要使用的 PyTorch 学习率调度器类。指定 None 对应于使用恒定学习率。默认值：None。
lr_scheduler_kwargs (Optional[dict, None]) – 可选地，PyTorch 学习率调度器的一些关键字参数。默认值：None。
use_reversible_instance_norm (bool) – 是否使用可逆实例归一化 RINorm 来应对分布变化，如 [1] 所示。它仅应用于目标序列的特征，而不应用于协变量。

参考

1: T. Kim et al. “Reversible Instance Normalization for Accurate Time-Series Forecasting against Distribution Shift”, https://openreview.net/forum?id=cGDAkQo1C0p

属性

`automatic_optimization`	如果设置为 `False`，则您负责调用 `.backward()`, `.step()`, `.zero_grad()`。
`current_epoch`	`Trainer` 中的当前 epoch，如果未附加则为 0。
`device_mesh`	`ModelParallelStrategy` 等策略将创建设备网格，可在 `configure_model()` 钩子中访问该网格以并行化 LightningModule。
`example_input_array`	示例输入数组是模块可以在 `forward()` 方法中消耗的内容规范。
`global_rank`	当前进程在所有节点和设备中的索引。
`global_step`	所有 epoch 中看到的总训练批次。
`hparams`	使用 `save_hyperparameters()` 保存的超参数集合。
`hparams_initial`	使用 `save_hyperparameters()` 保存的超参数集合。
`local_rank`	当前进程在单个节点内的索引。
`logger`	指向 Trainer 中 logger 对象的引用。
`loggers`	指向 Trainer 中 loggers 列表的引用。
`on_gpu`	如果此模型当前位于 GPU 上，则返回 `True`。
`output_chunk_length`	模型一次预测的时间步长数量。
`strict_loading`	确定 Lightning 如何使用 .load_state_dict(..., strict=model.strict_loading) 加载此模型。

device
dtype
epochs_trained
fabric
supports_probabilistic_prediction
trainer

方法

`add_module`(name, module)	向当前模块添加子模块。
`all_gather`(data[, group, sync_grads])	从多个进程聚合张量或张量集合。
`apply`(fn)	将 `fn` 递归地应用于每个子模块（由 `.children()` 返回）以及自身。
`backward`(loss, args, *kwargs)	对 `training_step()` 返回的损失执行反向传播时调用。
`bfloat16`()	将所有浮点参数和缓冲区转换为 `bfloat16` 数据类型。
`buffers`([recurse])	返回模块缓冲区的迭代器。
`children`()	返回直接子模块的迭代器。
`clip_gradients`(optimizer[, ...])	内部处理梯度裁剪。
`compile`(args, *kwargs)	使用 `torch.compile()` 编译此模块的前向传播。
`configure_callbacks`()	配置模型特定的回调。
`configure_gradient_clipping`(optimizer[, ...])	对优化器参数执行梯度裁剪。
`configure_model`()	在策略和精度感知上下文中创建模块的钩子。
`configure_optimizers`()	配置用于模型优化的优化器和学习率调度器。
`configure_sharded_model`()	已弃用。
`configure_torch_metrics`(torch_metrics)	处理 torch_metrics 参数。
`cpu`()	参见 `torch.nn.Module.cpu()`。
`cuda`([device])	将所有模型参数和缓冲区移动到 GPU。
`double`()	参见 `torch.nn.Module.double()`。
`eval`()	将模块设置为评估模式。
`extra_repr`()	返回模块的额外表示。
`float`()	参见 `torch.nn.Module.float()`。
`forward`(args, *kwargs)	与 `torch.nn.Module.forward()` 相同。
`freeze`()	冻结所有参数以进行推理。
`get_buffer`(target)	如果存在，则返回由 `target` 指定的缓冲区，否则抛出错误。
`get_extra_state`()	返回要包含在模块 state_dict 中的任何额外状态。
`get_parameter`(target)	如果存在，则返回由 `target` 指定的参数，否则抛出错误。
`get_submodule`(target)	如果存在，则返回由 `target` 指定的子模块，否则抛出错误。
`half`()	参见 `torch.nn.Module.half()`。
`ipu`([device])	将所有模型参数和缓冲区移动到 IPU。
`load_from_checkpoint`(checkpoint_path[, ...])	从检查点加载模型的主要方式。
`load_state_dict`(state_dict[, strict, assign])	将参数和缓冲区从 `state_dict` 复制到此模块及其后代中。
`log`(name, value[, prog_bar, logger, ...])	记录键值对。
`log_dict`(dictionary[, prog_bar, logger, ...])	一次记录字典中的值。
`lr_scheduler_step`(scheduler, metric)	覆盖此方法以调整 `Trainer` 调用每个调度器的默认方式。
`lr_schedulers`()	返回训练期间使用的学习率调度器。
`manual_backward`(loss, args, *kwargs)	当你手动进行优化时，直接从你的 `training_step()` 调用此方法。
`modules`()	返回网络中所有模块的迭代器。
`mtia`([device])	将所有模型参数和缓冲区移动到 MTIA。
`named_buffers`([prefix, recurse, ...])	返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。
`named_children`()	返回直接子模块的迭代器，同时产生模块名称和模块本身。
`named_modules`([memo, prefix, remove_duplicate])	返回网络中所有模块的迭代器，同时产生模块名称和模块本身。
`named_parameters`([prefix, recurse, ...])	返回模块参数的迭代器，同时产生参数名称和参数本身。
`on_after_backward`()	在 `loss.backward()` 之后且在优化器步进之前调用。
`on_after_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备后修改或应用批次增强。
`on_before_backward`(loss)	在 `loss.backward()` 之前调用。
`on_before_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备之前修改或应用批次增强。
`on_before_optimizer_step`(optimizer)	在 `optimizer.step()` 之前调用。
`on_before_zero_grad`(optimizer)	在 `training_step()` 之后且在 `optimizer.zero_grad()` 之前调用。
`on_fit_end`()	在 fit 的最后调用。
`on_fit_start`()	在 fit 的最开始调用。
`on_load_checkpoint`(checkpoint)	由 Lightning 调用以恢复您的模型。
`on_predict_batch_end`(outputs, batch, batch_idx)	在预测循环中批次之后调用。
`on_predict_batch_start`(batch, batch_idx[, ...])	在预测循环中该批次发生任何事情之前调用。
`on_predict_end`()	在预测结束时调用。
`on_predict_epoch_end`()	在预测结束时调用。
`on_predict_epoch_start`()	在预测开始时调用。
`on_predict_model_eval`()	预测循环开始时调用。
`on_predict_start`()	在预测开始时调用。
`on_save_checkpoint`(checkpoint)	Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。
`on_test_batch_end`(outputs, batch, batch_idx)	在测试循环中批次之后调用。
`on_test_batch_start`(batch, batch_idx[, ...])	在测试循环中该批次发生任何事情之前调用。
`on_test_end`()	在测试结束时调用。
`on_test_epoch_end`()	在测试循环中 epoch 的最后调用。
`on_test_epoch_start`()	在测试循环中 epoch 的最开始调用。
`on_test_model_eval`()	测试循环开始时调用。
`on_test_model_train`()	测试循环结束时调用。
`on_test_start`()	在测试开始时调用。
`on_train_batch_end`(outputs, batch, batch_idx)	在训练循环中批次之后调用。
`on_train_batch_start`(batch, batch_idx)	在训练循环中该批次发生任何事情之前调用。
`on_train_end`()	在训练结束、logger 实验关闭之前调用。
`on_train_epoch_end`()	在训练循环中 epoch 的最后调用。
`on_train_epoch_start`()	在训练循环中 epoch 的最开始调用。
`on_train_start`()	在健全性检查之后、训练开始时调用。
`on_validation_batch_end`(outputs, batch, ...)	在验证循环中批次之后调用。
`on_validation_batch_start`(batch, batch_idx)	在验证循环中该批次发生任何事情之前调用。
`on_validation_end`()	在验证结束时调用。
`on_validation_epoch_end`()	在验证循环中 epoch 的最后调用。
`on_validation_epoch_start`()	在验证循环中 epoch 的最开始调用。
`on_validation_model_eval`()	验证循环开始时调用。
`on_validation_model_train`()	验证循环结束时调用。
`on_validation_model_zero_grad`()	由训练循环调用，在进入验证循环之前释放梯度。
`on_validation_start`()	在验证开始时调用。
`optimizer_step`(epoch, batch_idx, optimizer)	覆盖此方法以调整 `Trainer` 调用优化器的默认方式。
`optimizer_zero_grad`(epoch, batch_idx, optimizer)	覆盖此方法以更改 `optimizer.zero_grad()` 的默认行为。
`optimizers`([use_pl_optimizer])	返回训练期间使用的优化器。
`parameters`([recurse])	返回模块参数的迭代器。
`predict_dataloader`()	指定预测样本的可迭代对象或可迭代对象集合。
`predict_step`(batch, batch_idx[, dataloader_idx])	执行预测步骤
`prepare_data`()	使用此方法下载和准备数据。
`print`(args, *kwargs)	仅从进程 0 打印。
`register_backward_hook`(hook)	在模块上注册后向钩子。
`register_buffer`(name, tensor[, persistent])	向模块添加缓冲区。
`register_forward_hook`(hook, *[, prepend, ...])	在模块上注册前向钩子。
`register_forward_pre_hook`(hook, *[, ...])	在模块上注册前向预钩子。
`register_full_backward_hook`(hook[, prepend])	在模块上注册后向钩子。
`register_full_backward_pre_hook`(hook[, prepend])	在模块上注册后向预钩子。
`register_load_state_dict_post_hook`(hook)	注册一个后钩子，该钩子在模块的 `load_state_dict()` 被调用后运行。
`register_load_state_dict_pre_hook`(hook)	注册一个预钩子，该钩子在模块的 `load_state_dict()` 被调用前运行。
`register_module`(name, module)	`add_module()` 的别名。
`register_parameter`(name, param)	向模块添加参数。
`register_state_dict_post_hook`(hook)	为 `state_dict()` 方法注册一个后钩子。
`register_state_dict_pre_hook`(hook)	为 `state_dict()` 方法注册一个预钩子。
`requires_grad_`([requires_grad])	更改此模块中是否应记录参数上的自动梯度操作。
`save_hyperparameters`(*args[, ignore, frame, ...])	将参数保存到 `hparams` 属性。
`set_extra_state`(state)	设置加载的 state_dict 中包含的额外状态。
`set_predict_parameters`(n, num_samples, ...)	在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置
`set_submodule`(target, module)	如果存在，则设置由 `target` 指定的子模块，否则抛出错误。
`setup`(stage)	在 fit（训练 + 验证）、验证、测试或预测开始时调用。
`share_memory`()	参见 `torch.Tensor.share_memory_()`。
`state_dict`(*args[, destination, prefix, ...])	返回包含模块完整状态引用的字典。
`teardown`(stage)	在 fit（训练 + 验证）、验证、测试或预测结束时调用。
`test_dataloader`()	指定测试样本的可迭代对象或可迭代对象集合。
`test_step`(args, *kwargs)	处理测试集中的单个批次数据。
`to`(args, *kwargs)	参见 `torch.nn.Module.to()`。
`to_dtype`(dtype)	将模块精度（默认为 float32）转换为其他精度。
`to_empty`(*, device[, recurse])	在不复制存储的情况下，将参数和缓冲区移动到指定设备。
`to_onnx`(file_path[, input_sample])	将模型保存为 ONNX 格式。
`to_torchscript`([file_path, method, ...])	默认情况下，将整个模型编译为 `ScriptModule`。
`toggle_optimizer`(optimizer)	确保在训练步骤中仅计算当前优化器参数的梯度，以防止多优化器设置中出现悬空梯度。
`train`([mode])	将模块设置为训练模式。
`train_dataloader`()	指定训练样本的可迭代对象或可迭代对象集合。
`training_step`(train_batch, batch_idx)	执行训练步骤
`transfer_batch_to_device`(batch, device, ...)	如果您的 `DataLoader` 返回包装在自定义数据结构中的张量，请覆盖此钩子。
`type`(dst_type)	参见 `torch.nn.Module.type()`。
`unfreeze`()	解冻所有参数以进行训练。
`untoggle_optimizer`(optimizer)	重置使用 `toggle_optimizer()` 切换的必需梯度状态。
`val_dataloader`()	指定验证样本的可迭代对象或可迭代对象集合。
`validation_step`(val_batch, batch_idx)	执行验证步骤
`xpu`([device])	将所有模型参数和缓冲区移动到 XPU。
`zero_grad`([set_to_none])	重置所有模型参数的梯度。

__call__
set_mc_dropout

CHECKPOINT_HYPER_PARAMS_KEY = 'hyper_parameters'¶

CHECKPOINT_HYPER_PARAMS_NAME = 'hparams_name'¶

CHECKPOINT_HYPER_PARAMS_TYPE = 'hparams_type'¶

T_destination¶: TypeVar(‘T_destination’, bound=Dict[str, Any]) 的别名

add_module(name, module)¶

向当前模块添加子模块。

模块可以使用给定的名称作为属性访问。

参数

name (str) – 子模块的名称。可以使用此名称从当前模块访问子模块
module (Module) – 要添加到模块的子模块。

返回类型

None

all_gather(data, group=None, sync_grads=False)¶

从多个进程聚合张量或张量集合。

此方法需要在所有进程上调用，并且张量需要在所有进程上具有相同的形状，否则您的程序将永远暂停。

参数

data (Union[Tensor, dict, list, tuple]) – int、float、形状为 (batch, …) 的张量，或其（可能嵌套的）集合。
group (Optional[Any, None]) – 要从中收集结果的进程组。默认为所有进程 (world)。
sync_grads (bool) – 允许用户同步 all_gather 操作的梯度的标志。

返回类型

Union[Tensor, dict, list, tuple]

返回值

形状为 (world_size, batch, …) 的张量，如果输入是集合，则输出也将是包含此形状张量的集合。对于 world_size 为 1 的特殊情况，不会向张量添加额外维度。

allow_zero_length_dataloader_with_multiple_devices: bool¶

apply(fn)¶

将 fn 递归地应用于每个子模块（由 .children() 返回）以及自身。

典型用法包括初始化模型的参数（另见 nn-init-doc）。

参数: fn (Module -> None) – 要应用于每个子模块的函数
返回值: self
返回类型: Module

示例

>>> @torch.no_grad()
>>> def init_weights(m):
>>>     print(m)
>>>     if type(m) == nn.Linear:
>>>         m.weight.fill_(1.0)
>>>         print(m.weight)
>>> net = nn.Sequential(nn.Linear(2, 2), nn.Linear(2, 2))
>>> net.apply(init_weights)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)

property automatic_optimization: bool¶

如果设置为 False，则您负责调用 .backward(), .step(), .zero_grad()。

返回类型: bool

backward(loss, *args, **kwargs)¶

对 training_step() 返回的损失执行反向传播时调用。如果需要，可以重写此钩子方法以实现自己的逻辑。

参数: loss (Tensor) – training_step() 返回的损失张量。如果使用了梯度累积，这里的损失是归一化值（乘以 1 / 累积步数）。

示例

def backward(self, loss):
    loss.backward()

返回类型: None

bfloat16()¶

将所有浮点参数和缓冲区转换为 bfloat16 数据类型。

注意

此方法会修改模块本身。

返回值: self
返回类型: Module

buffers(recurse=True)¶

返回模块缓冲区的迭代器。

参数: recurse (bool) – 如果为 True，则产生此模块和所有子模块的缓冲区。否则，仅产生此模块的直接成员缓冲区。
Yields: torch.Tensor – 模块缓冲区

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for buf in model.buffers():
>>>     print(type(buf), buf.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Tensor]

call_super_init: bool = False¶

children()¶

返回直接子模块的迭代器。

Yields: Module – 子模块
返回类型: Iterator[Module]

clip_gradients(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

内部处理梯度裁剪。

注意

不要重写此方法。如果想自定义梯度裁剪，请考虑使用 configure_gradient_clipping() 方法。
对于手动优化 (self.automatic_optimization = False)，如果要使用梯度裁剪，请考虑在训练步骤中手动调用 self.clip_gradients(opt, gradient_clip_val=0.5, gradient_clip_algorithm="norm")。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 用于裁剪梯度的值。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。传递 gradient_clip_algorithm="value" 按值裁剪，传递 gradient_clip_algorithm="norm" 按范数裁剪。

返回类型

None

compile(*args, **kwargs)¶

使用 torch.compile() 编译此模块的前向传播。

此模块的 __call__ 方法将被编译，并且所有参数将原样传递给 torch.compile()。

有关此函数的参数详细信息，请参见 torch.compile()。

configure_callbacks()¶

返回类型: Union[Sequence[Callback], Callback]
返回值: 一个或多个回调，它们将扩展 Trainer 中的回调列表。

示例

def configure_callbacks(self):
    early_stop = EarlyStopping(monitor="val_acc", mode="max")
    checkpoint = ModelCheckpoint(monitor="val_loss")
    return [early_stop, checkpoint]

configure_gradient_clipping(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

对优化器参数执行梯度裁剪。在调用 optimizer_step() 之前调用。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 用于裁剪梯度的值。默认情况下，Trainer 中传入的值将在此处可用。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。默认情况下，Trainer 中传入的值将在此处可用。

示例

def configure_gradient_clipping(self, optimizer, gradient_clip_val, gradient_clip_algorithm):
    # Implement your own custom logic to clip gradients
    # You can call `self.clip_gradients` with your settings:
    self.clip_gradients(
        optimizer,
        gradient_clip_val=gradient_clip_val,
        gradient_clip_algorithm=gradient_clip_algorithm
    )

返回类型: None

configure_model()¶

在策略和精度感知上下文中创建模块的钩子。

此钩子在同一进程的 fit/val/test/predict 各阶段都会被调用，因此请确保此钩子的实现是幂等的，即在第一次调用此钩子后，后续调用应该是空操作。

返回类型: None

configure_optimizers()¶: 配置用于模型优化的优化器和学习率调度器。

configure_sharded_model()¶

已弃用。

请改用 configure_model()。

返回类型: None

static configure_torch_metrics(torch_metrics)¶

处理 torch_metrics 参数。

返回类型: MetricCollection

cpu()¶

参见 torch.nn.Module.cpu()。

返回类型: Self

cuda(device=None)¶

参数: device (Union[int, device, None]) – 如果指定，所有参数将被复制到该设备。如果为 None，将使用当前的 CUDA 设备索引。
返回值: self
返回类型: Module

property current_epoch: int¶

Trainer 中的当前 epoch，如果未附加则为 0。

返回类型: int

property device: device¶

返回类型: device

property device_mesh: Optional[DeviceMesh]¶

ModelParallelStrategy 等策略将创建设备网格，可在 configure_model() 钩子中访问该网格以并行化 LightningModule。

返回类型: Optional[ForwardRef, None]

double()¶

参见 torch.nn.Module.double()。

返回类型: Self

property dtype: Union[str, dtype]¶

返回类型: Union[str, dtype]

dump_patches: bool = False¶

property epochs_trained¶

eval()¶

将模块设置为评估模式。

这仅对某些模块有效。有关特定模块在训练/评估模式下的行为详情，即它们是否受到影响，请参阅其文档，例如 Dropout、BatchNorm 等。

这等同于 self.train(False)。

有关 .eval() 与可能与其混淆的几个类似机制之间的比较，请参见 locally-disable-grad-doc。

返回值: self
返回类型: Module

property example_input_array: Optional[Union[Tensor, tuple, dict]]¶

示例输入数组是模块可以在 forward() 方法中消耗的内容规范。返回类型解释如下

单个张量：假定模型接受一个参数，即 model.forward(model.example_input_array)
元组：输入数组应被解释为位置参数序列，即 model.forward(*model.example_input_array)
字典：输入数组表示命名关键字参数，即 model.forward(**model.example_input_array)

返回类型: Union[Tensor, tuple, dict, None]

extra_repr()¶

返回模块的额外表示。

要打印自定义的额外信息，您应该在自己的模块中重新实现此方法。单行和多行字符串都可接受。

返回类型: str

property fabric: Optional[Fabric]¶

返回类型: Optional[Fabric, None]

float()¶

参见 torch.nn.Module.float()。

返回类型: Self

abstract forward(*args, **kwargs)¶

与 torch.nn.Module.forward() 相同。

参数

*args – 您决定传递给 forward 方法的任何内容。
**kwargs – 关键字参数也是可以的。

返回类型

Any

返回值

您的模型的输出

freeze()¶

冻结所有参数以进行推理。

示例

model = MyLightningModule(...)
model.freeze()

返回类型: None

get_buffer(target)¶

如果存在，则返回由 target 指定的缓冲区，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的缓冲区的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的缓冲区
返回类型: torch.Tensor
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是缓冲区

get_extra_state()¶

返回要包含在模块 state_dict 中的任何额外状态。

如果需要存储额外的状态，请为你的模块实现此方法以及相应的 set_extra_state() 方法。构建模块的 state_dict() 时会调用此函数。

返回值: 要存储在模块 state_dict 中的任何额外状态
返回类型: object

get_parameter(target)¶

如果存在，则返回由 target 指定的参数，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的参数的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的参数
返回类型: torch.nn.Parameter
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Parameter

get_submodule(target)¶

如果存在，则返回由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

（图表显示了一个 nn.Module A。 A 有一个嵌套子模块 net_b，它本身有两个子模块 net_c 和 linear。 net_c 还有一个子模块 conv。）

要检查是否存在 linear 子模块，我们可以调用 get_submodule("net_b.linear")。要检查是否存在 conv 子模块，我们可以调用 get_submodule("net_b.net_c.conv")。

参数: target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
返回值: target 引用的子模块
返回类型: torch.nn.Module
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

property global_rank: int¶

当前进程在所有节点和设备中的索引。

返回类型: int

property global_step: int¶

所有 epoch 中看到的总训练批次。

如果未附加 Trainer，此属性值为 0。

返回类型: int

half()¶

参见 torch.nn.Module.half()。

返回类型: Self

property hparams: Union[AttributeDict, MutableMapping]¶

使用 save_hyperparameters() 保存的超参数集合。用户可以对其进行修改。对于初始超参数的固定集合，请使用 hparams_initial。

返回类型: Union[AttributeDict, MutableMapping]
返回值: 可变的超参数字典

property hparams_initial: AttributeDict¶

使用 save_hyperparameters() 保存的超参数集合。这些内容是只读的。可以通过 hparams 手动更新保存的超参数。

返回值: 不可变初始超参数
返回类型: AttributeDict

ipu(device=None)¶

将所有模型参数和缓冲区移动到 IPU。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 IPU 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

load_from_checkpoint(checkpoint_path, map_location=None, hparams_file=None, strict=None, **kwargs)¶

从检查点加载模型的主要方式。当 Lightning 保存检查点时，它会将传递给 __init__ 的参数存储在检查点中的 "hyper_parameters" 下。

通过 **kwargs 指定的任何参数将覆盖存储在 "hyper_parameters" 中的参数。

参数

checkpoint_path (Union[str, Path, IO]) – 检查点路径。这也可以是 URL 或文件类对象
map_location (Union[device, str, int, Callable[[UntypedStorage, str], Optional[UntypedStorage, None]], dict[Union[device, str, int], Union[device, str, int]], None]) – 如果您的检查点保存的是 GPU 模型，而您现在在 CPU 或不同数量的 GPU 上加载，请使用此参数映射到新的配置。其行为与 torch.load() 中相同。
hparams_file (Union[str, Path, None]) –
可选的 .yaml 或 .csv 文件路径，其结构如下例所示
```
drop_prob: 0.2
dataloader:
    batch_size: 32
```
您很可能不需要此参数，因为 Lightning 总是会将超参数保存到检查点中。但是，如果您的检查点权重没有保存超参数，请使用此方法传入一个包含您希望使用的超参数的 .yaml 文件。这些超参数将被转换为 dict 并传递给您的 LightningModule 使用。

如果您的模型的 hparams 参数是 Namespace 并且 .yaml 文件具有分层结构，您需要重构您的模型以将 hparams 视为 dict。
strict (Optional[bool, None]) – 是否严格强制 checkpoint_path 中的键与此模块的 state dict 返回的键完全匹配。默认为 True，除非设置了 LightningModule.strict_loading，在这种情况下，它将默认为 LightningModule.strict_loading 的值。
**kwargs – 初始化模型所需的任何额外关键字参数。也可以用于覆盖已保存的超参数值。

返回类型

Self

返回值

加载了权重和超参数（如果可用）的 LightningModule 实例。

注意

load_from_checkpoint 是一个类方法。您应该使用 LightningModule 类来调用它，而不是 LightningModule 实例，否则将引发 TypeError。

注意

示例

# load weights without mapping ...
model = MyLightningModule.load_from_checkpoint('path/to/checkpoint.ckpt')

# or load weights mapping all weights from GPU 1 to GPU 0 ...
map_location = {'cuda:1':'cuda:0'}
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    map_location=map_location
)

# or load weights and hyperparameters from separate files.
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    hparams_file='/path/to/hparams_file.yaml'
)

# override some of the params with new values
model = MyLightningModule.load_from_checkpoint(
    PATH,
    num_layers=128,
    pretrained_ckpt_path=NEW_PATH,
)

# predict
pretrained_model.eval()
pretrained_model.freeze()
y_hat = pretrained_model(x)

load_state_dict(state_dict, strict=True, assign=False)¶

将参数和缓冲区从 state_dict 复制到此模块及其后代中。

如果 strict 为 True，则 state_dict 的键必须与此模块的 state_dict() 函数返回的键完全匹配。

警告

如果 assign 为 True，则必须在调用 load_state_dict 之后创建优化器，除非 get_swap_module_params_on_conversion() 为 True。

参数

state_dict (dict) – 包含参数和持久缓冲区的字典。
strict (bool, optional) – 是否严格强制 state_dict 中的键与此模块的 state_dict() 函数返回的键匹配。默认值：True
assign (bool, optional) – 设置为 False 时，保留当前模块中张量的属性，而设置为 True 时，保留 state dict 中张量的属性。唯一的例外是 Default: ``False` 的 requires_grad 字段

返回值

missing_keys 是一个字符串列表，包含此模块需要但
提供的 state_dict 中缺失的键。
unexpected_keys 是一个字符串列表，包含此模块
不预期但提供的 state_dict 中存在的键。

返回类型

包含 missing_keys 和 unexpected_keys 字段的 NamedTuple

注意

如果参数或缓冲区注册为 None 且其对应的键存在于 state_dict 中，load_state_dict() 将引发 RuntimeError。

property local_rank: int¶

当前进程在单个节点内的索引。

返回类型: int

记录键值对。

示例

self.log('train_loss', loss)

每个钩子的默认行为在此处有文档说明：extensions/logging:Automatic Logging。

参数

name (str) – 要记录的键。如果使用 DDP 或任何其他分布式策略，则必须在所有进程中保持一致。
value (Union[Metric, Tensor, int, float]) – 要记录的值。可以是 float、Tensor 或 Metric。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图。
sync_dist (bool) – 如果为 True，则在设备之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 DDP 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个 dataloader 时）。如果 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch_size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
metric_attribute (Optional[str, None]) – 为了恢复指标状态，Lightning 需要您的模型中 torchmetrics.Metric 的引用。如果它是一个模型属性，则会自动找到。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

一次记录字典中的值。

示例

values = {'loss': loss, 'acc': acc, ..., 'metric_n': metric_n}
self.log_dict(values)

参数

dictionary (Union[Mapping[str, Union[Metric, Tensor, int, float]], MetricCollection]) – 键值对。如果使用 DDP 或任何其他分布式策略，键必须在所有进程中保持一致。值可以是 float、Tensor、Metric 或 MetricCollection。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。None 会自动记录 training_step，但不记录 validation/test_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。None 会自动记录 val/test step，但不记录 training_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图
sync_dist (bool) – 如果为 True，则在 GPU/TPU 之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 ddp 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个时）。如果为 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

property logger: Optional[Union[Logger, Logger]]¶

指向 Trainer 中 logger 对象的引用。

返回类型: Union[Logger, Logger, None]

property loggers: Union[list[pytorch_lightning.loggers.logger.Logger], list[lightning_fabric.loggers.logger.Logger]]¶

指向 Trainer 中 loggers 列表的引用。

返回类型: Union[list[Logger], list[Logger]]

lr_scheduler_step(scheduler, metric)¶

覆盖此方法以调整 Trainer 调用每个调度器的默认方式。默认情况下，Lightning 根据每个调度器的 interval 调用 step()，如示例所示。

参数

scheduler (Union[LRScheduler, ReduceLROnPlateau]) – 学习率调度器。
metric (Optional[Any, None]) – 用于像 ReduceLROnPlateau 这样的调度器的监视器值。

示例

# DEFAULT
def lr_scheduler_step(self, scheduler, metric):
    if metric is None:
        scheduler.step()
    else:
        scheduler.step(metric)

# Alternative way to update schedulers if it requires an epoch value
def lr_scheduler_step(self, scheduler, metric):
    scheduler.step(epoch=self.current_epoch)

返回类型: None

lr_schedulers()¶

返回训练期间使用的学习率调度器。对于手动优化很有用。

返回类型: Union[None, list[Union[LRScheduler, ReduceLROnPlateau]], LRScheduler, ReduceLROnPlateau]
返回值: 单个调度器，或者在存在多个调度器时返回一个列表，如果在 configure_optimizers() 中没有返回调度器，则返回 None。

manual_backward(loss, *args, **kwargs)¶

在手动执行优化时，直接从您的 training_step() 中调用此方法。通过使用此方法，Lightning 可以确保在使用混合精度时应用所有正确的缩放。

更多示例请参见 manual optimization。

示例

def training_step(...):
    opt = self.optimizers()
    loss = ...
    opt.zero_grad()
    # automatically applies scaling, etc...
    self.manual_backward(loss)
    opt.step()

参数

loss (Tensor) – 用于计算梯度的张量。必须附加计算图。
*args – 要转发给 backward() 的额外位置参数
**kwargs – 要转发给 backward() 的额外关键字参数

返回类型

None

modules()¶

返回网络中所有模块的迭代器。

Yields: Module – 网络中的一个模块

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.modules()):
...     print(idx, '->', m)

0 -> Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)
1 -> Linear(in_features=2, out_features=2, bias=True)

返回类型: Iterator[Module]

mtia(device=None)¶

将所有模型参数和缓冲区移动到 MTIA。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 MTIA 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

named_buffers(prefix='', recurse=True, remove_duplicate=True)¶

返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。

参数

prefix (str) – 要添加到所有缓冲区名称前的字符串前缀。
recurse (bool, optional) – 如果为 True，则生成此模块及其所有子模块的缓冲区。否则，仅生成此模块的直接成员缓冲区。默认为 True。
remove_duplicate (bool, optional) – 是否移除结果中的重复缓冲区。默认为 True。

Yields

(str, torch.Tensor) – 包含名称和缓冲区的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, buf in self.named_buffers():
>>>     if name in ['running_var']:
>>>         print(buf.size())

返回类型: Iterator[Tuple[str, Tensor]]

named_children()¶

返回直接子模块的迭代器，同时产生模块名称和模块本身。

Yields: (str, Module) – 包含名称和子模块的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, module in model.named_children():
>>>     if name in ['conv4', 'conv5']:
>>>         print(module)

返回类型: Iterator[Tuple[str, Module]]

named_modules(memo=None, prefix='', remove_duplicate=True)¶

返回网络中所有模块的迭代器，同时产生模块名称和模块本身。

参数

memo (Optional[Set[Module], None]) – 用于存储已添加到结果中的模块集合的备忘录
prefix (str) – 将添加到模块名称前的字符串前缀
remove_duplicate (bool) – 是否移除结果中重复的模块实例

Yields

(str, Module) – 包含名称和模块的元组

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.named_modules()):
...     print(idx, '->', m)

0 -> ('', Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
))
1 -> ('0', Linear(in_features=2, out_features=2, bias=True))

named_parameters(prefix='', recurse=True, remove_duplicate=True)¶

返回模块参数的迭代器，同时产生参数名称和参数本身。

参数

prefix (str) – 要添加到所有参数名称前的字符串前缀。
recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
remove_duplicate (bool, optional) – 是否移除结果中重复的参数。默认为 True。

Yields

(str, Parameter) – 包含名称和参数的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, param in self.named_parameters():
>>>     if name in ['bias']:
>>>         print(param.size())

返回类型: Iterator[Tuple[str, Parameter]]

on_after_backward()¶

在 loss.backward() 之后且在优化器步进之前调用。

注意

如果使用原生 AMP，此时梯度不会被取消缩放。如果您需要未缩放的梯度，请使用 on_before_optimizer_step。

返回类型: None

on_after_batch_transfer(batch, dataloader_idx)¶

覆盖此方法以在批次转移到设备后修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_after_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = gpu_transforms(batch['x'])
    return batch

另请参阅

on_before_batch_transfer()
transfer_batch_to_device()

on_before_backward(loss)¶

在 loss.backward() 之前调用。

参数: loss (Tensor) – 损失值，除以进行梯度累积的批次数，如果使用 AMP 则会进行缩放。
返回类型: None

on_before_batch_transfer(batch, batch_idx, dataloader_idx)¶

覆盖此方法以在批次转移到设备之前修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_before_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = transforms(batch['x'])
    return batch

另请参阅

on_after_batch_transfer()
transfer_batch_to_device()

on_before_optimizer_step(optimizer)¶

在 optimizer.step() 之前调用。

如果使用梯度累积，则在梯度累积完成后调用此 hook。参见：:paramref:`~pytorch_lightning.trainer.trainer.Trainer.accumulate_grad_batches`。

如果使用 AMP，损失值在此钩子调用前会取消缩放。有关梯度缩放的更多信息，请参阅这些文档。

如果进行梯度裁剪，此时梯度尚未被裁剪。

参数: optimizer (Optimizer) – 正在使用的当前优化器。

示例

def on_before_optimizer_step(self, optimizer):
    # example to inspect gradient information in tensorboard
    if self.trainer.global_step % 25 == 0:  # don't make the tf file huge
        for k, v in self.named_parameters():
            self.logger.experiment.add_histogram(
                tag=k, values=v.grad, global_step=self.trainer.global_step
            )

返回类型: None

on_before_zero_grad(optimizer)¶

在 training_step() 之后且在 optimizer.zero_grad() 之前调用。

在训练循环中，在优化器步长后和梯度清零前调用。是检查权重更新后权重信息的好地方。

这里是它被调用的地方

for optimizer in optimizers:
    out = training_step(...)

    model.on_before_zero_grad(optimizer) # < ---- called here
    optimizer.zero_grad()

    backward()

参数: optimizer (Optimizer) – 应清零其梯度的优化器。
返回类型: None

on_fit_end()¶

在 fit 的最后调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

on_fit_start()¶

在 fit 的最开始调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

property on_gpu: bool¶

如果此模型当前位于 GPU 上，则返回 True。

对于在 LightningModule 中设置标志以区分 CPU 和 GPU 的行为很有用。

返回类型: bool

on_load_checkpoint(checkpoint)¶

由 Lightning 调用以恢复您的模型。如果您使用 on_save_checkpoint() 保存了某些内容，这是您恢复它的机会。

参数: checkpoint (dict[str, Any]) – 已加载的检查点

示例

def on_load_checkpoint(self, checkpoint):
    # 99% of the time you don't need to implement this method
    self.something_cool_i_want_to_save = checkpoint['something_cool_i_want_to_save']

注意

Lightning 会自动恢复全局步长、epoch 和训练状态，包括 amp 缩放。您无需恢复任何与训练相关的内容。

返回类型: None

on_predict_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在预测循环中批次之后调用。

参数

outputs (Optional[Any, None]) – predict_step(x) 的输出
batch (Any) – 预测 DataLoader 返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_batch_start(batch, batch_idx, dataloader_idx=0)¶

在预测循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_end()¶

在预测结束时调用。

返回类型: None

on_predict_epoch_end()¶

在预测结束时调用。

返回类型: None

on_predict_epoch_start()¶

在预测开始时调用。

返回类型: None

on_predict_model_eval()¶

预测循环开始时调用。

预测循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。

返回类型: None

on_predict_start()¶

在预测开始时调用。

返回类型: None

on_save_checkpoint(checkpoint)¶

Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。

参数: checkpoint (dict[str, Any]) – 在检查点字典被写入文件之前的完整字典。此钩子函数的实现可以将额外数据插入此字典。

示例

def on_save_checkpoint(self, checkpoint):
    # 99% of use cases you don't need to implement this method
    checkpoint['something_cool_i_want_to_save'] = my_cool_pickable_object

注意

Lightning 会保存训练的所有方面（周期、全局步数等），包括 amp scaling。您无需存储任何关于训练的内容。

返回类型: None

on_test_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在测试循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – test_step(x) 的输出。
batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_batch_start(batch, batch_idx, dataloader_idx=0)¶

在测试循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_end()¶

在测试结束时调用。

返回类型: None

on_test_epoch_end()¶

在测试循环中 epoch 的最后调用。

返回类型: None

on_test_epoch_start()¶

在测试循环中 epoch 的最开始调用。

返回类型: None

on_test_model_eval()¶

测试循环开始时调用。

测试循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_test_model_train()。

返回类型: None

on_test_model_train()¶

测试循环结束时调用。

测试循环默认将 LightningModule 的 training 模式恢复到开始测试之前的状态。重写此钩子函数以改变此行为。另请参见 on_test_model_eval()。

返回类型: None

on_test_start()¶

在测试开始时调用。

返回类型: None

on_train_batch_end(outputs, batch, batch_idx)¶

在训练循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – training_step(x) 的输出。
batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

注意

此处 outputs["loss"] 的值将是根据 accumulate_grad_batches 对 training_step 返回的损失值进行归一化后的值。

返回类型: None

on_train_batch_start(batch, batch_idx)¶

在训练循环中该批次发生任何事情之前调用。

如果此处返回 -1，将跳过当前周期的剩余训练。

参数

batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

返回类型

Optional[int, None]

on_train_end()¶

在训练结束、logger 实验关闭之前调用。

返回类型: None

on_train_epoch_end()¶

在训练循环中 epoch 的最后调用。

要在周期结束时访问所有批次输出，您可以将步输出缓存为 LightningModule 的属性，并在此钩子函数中访问它们

class MyLightningModule(L.LightningModule):
    def __init__(self):
        super().__init__()
        self.training_step_outputs = []

    def training_step(self):
        loss = ...
        self.training_step_outputs.append(loss)
        return loss

    def on_train_epoch_end(self):
        # do something with all training_step outputs, for example:
        epoch_mean = torch.stack(self.training_step_outputs).mean()
        self.log("training_epoch_mean", epoch_mean)
        # free up the memory
        self.training_step_outputs.clear()

on_train_epoch_start()¶

在训练循环中 epoch 的最开始调用。

返回类型: None

on_train_start()¶

在健全性检查之后、训练开始时调用。

返回类型: None

on_validation_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在验证循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – validation_step(x) 的输出。
batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_batch_start(batch, batch_idx, dataloader_idx=0)¶

在验证循环中该批次发生任何事情之前调用。

参数

batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_end()¶

在验证结束时调用。

返回类型: None

on_validation_epoch_end()¶: 在验证循环中 epoch 的最后调用。

on_validation_epoch_start()¶

在验证循环中 epoch 的最开始调用。

返回类型: None

on_validation_model_eval()¶

验证循环开始时调用。

验证循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_validation_model_train()。

返回类型: None

on_validation_model_train()¶

验证循环结束时调用。

验证循环默认将 LightningModule 的 training 模式恢复到开始验证之前的状态。重写此钩子函数以改变此行为。另请参见 on_validation_model_eval()。

返回类型: None

on_validation_model_zero_grad()¶

由训练循环调用，在进入验证循环之前释放梯度。

返回类型: None

on_validation_start()¶

在验证开始时调用。

返回类型: None

optimizer_step(epoch, batch_idx, optimizer, optimizer_closure=None)¶

覆盖此方法以调整 Trainer 调用优化器的默认方式。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Union[Optimizer, LightningOptimizer]) – PyTorch 优化器
optimizer_closure (Optional[Callable[[], Any], None]) – 优化器闭包。必须执行此闭包，因为它包含对 training_step()、optimizer.zero_grad() 和 backward() 的调用。

示例

def optimizer_step(self, epoch, batch_idx, optimizer, optimizer_closure):
    # Add your custom logic to run directly before `optimizer.step()`

    optimizer.step(closure=optimizer_closure)

    # Add your custom logic to run directly after `optimizer.step()`

返回类型: None

optimizer_zero_grad(epoch, batch_idx, optimizer)¶

覆盖此方法以更改 optimizer.zero_grad() 的默认行为。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Optimizer) – PyTorch 优化器

示例

# DEFAULT
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad()

# Set gradients to `None` instead of zero to improve performance (not required on `torch>=2.0.0`).
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad(set_to_none=True)

有关上述示例的解释，请参见 torch.optim.Optimizer.zero_grad()。

返回类型: None

optimizers(use_pl_optimizer=True)¶

返回训练期间使用的优化器。对于手动优化很有用。

参数: use_pl_optimizer (bool) – 如果为 True，则会将优化器封装在 LightningOptimizer 中，以自动处理精度、分析以及步调用计数，从而实现正确的日志记录和检查点。它专门封装 step 方法，不支持没有此方法的自定义优化器。
返回类型: Union[Optimizer, LightningOptimizer, _FabricOptimizer, list[Optimizer], list[LightningOptimizer], list[_FabricOptimizer]]
返回值: 单个优化器，或者在存在多个优化器时返回一个列表。

property output_chunk_length: Optional[int]¶

模型一次预测的时间步长数量。

返回类型: Optional[int, None]

parameters(recurse=True)¶

返回模块参数的迭代器。

这通常传递给优化器。

参数: recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
Yields: Parameter – 模块参数

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for param in model.parameters():
>>>     print(type(param), param.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Parameter]

pred_batch_size: Optional[int]¶

pred_mc_dropout: Optional[bool]¶

pred_n: Optional[int]¶

pred_n_jobs: Optional[int]¶

pred_num_samples: Optional[int]¶

pred_roll_size: Optional[int]¶

predict_dataloader()¶

指定预测样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

建议所有数据下载和准备工作都在 prepare_data() 中进行。

predict()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any
返回值: 一个 torch.utils.data.DataLoader 或其序列，指定预测样本。

predict_likelihood_parameters: Optional[bool]¶

predict_step(batch, batch_idx, dataloader_idx=None)¶

执行预测步骤

batch: Darts 的 InferenceDataset 的输出 - 包含 (past_target, past_covariates, historic_future_covariates, future_covariates, future_past_covariates, input time series, prediction start time step) 的元组
batch_idx: 当前批次的批次索引
dataloader_idx: 数据加载器索引

返回类型: Sequence[TimeSeries]

prepare_data()¶

警告

不要在此方法中为模型设置状态（请改用 setup 方法），因为此方法不会在每个设备上调用

示例

def prepare_data(self):
    # good
    download_data()
    tokenize()
    etc()

    # bad
    self.split = data_split
    self.some_state = some_other_state()

在分布式环境中，prepare_data 可以通过两种方式调用（使用 prepare_data_per_node）

每个节点一次。这是默认设置，仅在 LOCAL_RANK=0 上调用。
总共一次。仅在 GLOBAL_RANK=0 上调用。

示例

# DEFAULT
# called once per node on LOCAL_RANK=0 of that node
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = True

# call on GLOBAL_RANK=0 (great for shared file systems)
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = False

此方法在请求数据加载器之前调用

model.prepare_data()
initialize_distributed()
model.setup(stage)
model.train_dataloader()
model.val_dataloader()
model.test_dataloader()
model.predict_dataloader()

返回类型: None

prepare_data_per_node: bool¶

print(*args, **kwargs)¶

仅从进程 0 打印。在任何分布式模式下使用此方法以仅记录一次。

参数

*args – 要打印的内容。与 Python 内置的 print 函数相同。
**kwargs – 与 Python 内置的 print 函数相同。

示例

def forward(self, x):
    self.print(x, 'in forward')

返回类型: None

register_backward_hook(hook)¶

在模块上注册后向钩子。

此函数已被弃用，推荐使用 register_full_backward_hook()，此函数的行为将在未来版本中改变。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_buffer(name, tensor, persistent=True)¶

向模块添加缓冲区。

这通常用于注册不应视为模型参数的缓冲区。例如，BatchNorm 的 running_mean 不是参数，但属于模块的状态。缓冲区默认是持久的，将与参数一起保存。通过将 persistent 设置为 False 可以改变此行为。持久缓冲区和非持久缓冲区之间的唯一区别在于，非持久缓冲区不会成为此模块的 state_dict 的一部分。

缓冲区可以使用给定的名称作为属性访问。

参数

name (str) – 缓冲区的名称。可以使用给定的名称从此模块访问缓冲区
tensor (Tensor or None) – 要注册的缓冲区。如果为 None，则忽略在缓冲区上运行的操作，例如 cuda。如果为 None，则缓冲区**不**包含在模块的 state_dict 中。
persistent (bool) – 缓冲区是否为此模块的 state_dict 的一部分。

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> self.register_buffer('running_mean', torch.zeros(num_features))

返回类型: None

register_forward_hook(hook, *, prepend=False, with_kwargs=False, always_call=False)¶

在模块上注册前向钩子。

每次 forward() 计算出输出后，都将调用此 hook。

如果 with_kwargs 为 False 或未指定，则输入仅包含传递给模块的位置参数。关键字参数不会传递给 hook，只会传递给 forward。hook 可以修改输出。它可以就地修改输入，但由于这是在 forward() 被调用后才调用，因此对 forward 没有影响。hook 应具有以下签名：

hook(module, args, output) -> None or modified output

如果 with_kwargs 为 True，则前向钩子函数将接收传递给 forward 函数的 kwargs，并预期返回可能修改过的输出。此钩子函数应具有以下签名：

hook(module, args, kwargs, output) -> None or modified output

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 True，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之后触发。请注意，使用 register_module_forward_hook() 注册的全局 forward 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 True，hook 将接收传递给 forward 函数的 kwargs。默认值：False
always_call (bool) – 如果为 True，无论在调用模块时是否引发异常，hook 都将被运行。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_forward_pre_hook(hook, *, prepend=False, with_kwargs=False)¶

在模块上注册前向预钩子。

每次调用 forward() 之前，都将调用此 hook。

hook(module, args) -> None or modified input

hook(module, args, kwargs) -> None or a tuple of modified input and kwargs

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之后触发。请注意，使用 register_module_forward_pre_hook() 注册的全局 forward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 true，hook 将接收传递给 forward 函数的 kwargs。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_hook(hook, prepend=False)¶

在模块上注册后向钩子。

每当计算相对于模块的梯度时，此钩子函数都将被调用，即只有当计算相对于模块输出的梯度时，此钩子函数才会执行。此钩子函数应具有以下签名：

hook(module, grad_input, grad_output) -> tuple(Tensor) or None

警告

使用后向钩子时，不允许原地修改输入或输出，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之后触发。请注意，使用 register_module_full_backward_hook() 注册的全局 backward 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_pre_hook(hook, prepend=False)¶

在模块上注册后向预钩子。

每当计算模块的梯度时，此钩子函数都将被调用。此钩子函数应具有以下签名：

hook(module, grad_output) -> tuple[Tensor] or None

警告

使用后向钩子时，不允许原地修改输入，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之后触发。请注意，使用 register_module_full_backward_pre_hook() 注册的全局 backward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_load_state_dict_post_hook(hook)¶

注册一个后钩子函数，在调用模块的 load_state_dict() 后运行。

它应该具有以下签名：: hook(module, incompatible_keys) -> None

如有需要，可以原地修改给定的 incompatible_keys。

请注意，在调用 load_state_dict() 并设置 strict=True 时执行的检查会受到 hook 对 missing_keys 或 unexpected_keys 所做修改的影响，这是预期的行为。如果向任一键集添加内容，则在 strict=True 时会引发错误；清空缺失键和意外键则可以避免错误。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_load_state_dict_pre_hook(hook)¶

注册一个预钩子函数，在调用模块的 load_state_dict() 之前运行。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata, strict, missing_keys, unexpected_keys, error_msgs) -> None # noqa: B950

参数: hook (Callable) – 可调用钩子函数，将在加载状态字典之前被调用。

register_module(name, module)¶

add_module() 的别名。

返回类型: None

register_parameter(name, param)¶

向模块添加参数。

参数可以使用给定的名称作为属性访问。

参数

name (str) – 参数的名称。可以使用给定的名称从此模块访问参数
param (Parameter or None) – 要添加到模块的参数。如果为 None，则忽略在参数上运行的操作，例如 cuda。如果为 None，则参数**不**包含在模块的 state_dict 中。

返回类型

None

register_state_dict_post_hook(hook)¶

为 state_dict() 方法注册一个后钩子。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata) -> None

注册的钩子函数可以原地修改 state_dict。

register_state_dict_pre_hook(hook)¶

为 state_dict() 方法注册一个预钩子。

它应该具有以下签名：: hook(module, prefix, keep_vars) -> None

注册的钩子函数可用于在进行 state_dict 调用之前执行预处理。

requires_grad_(requires_grad=True)¶

更改此模块中是否应记录参数上的自动梯度操作。

此方法原地设置参数的 requires_grad 属性。

此方法有助于冻结模块的一部分用于微调，或单独训练模型的各个部分（例如，GAN 训练）。

有关 .requires_grad_() 和几个可能与其混淆的类似机制的比较，请参见 locally-disable-grad-doc。

参数: requires_grad (bool) – 是否应由 autograd 记录此模块中参数的操作。默认值：True。
返回值: self
返回类型: Module

save_hyperparameters(*args, ignore=None, frame=None, logger=True)¶

将参数保存到 hparams 属性。

参数

args (Any) – 可以是 dict、NameSpace 或 OmegaConf 的单个对象，或来自类 __init__ 的字符串名称或参数
ignore (Union[str, Sequence[str], None]) – 要忽略的来自类 __init__ 的参数名称或参数名称列表
frame (Optional[frame, None]) – 一个 frame 对象。默认值为 None
logger (bool) – 是否将超参数发送到日志记录器。默认值：True

示例：

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # manually assign arguments
...         self.save_hyperparameters('arg1', 'arg3')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class AutomaticArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # equivalent automatic
...         self.save_hyperparameters()
...     def forward(self, *args, **kwargs):
...         ...
>>> model = AutomaticArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg2": abc
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class SingleArgModel(HyperparametersMixin):
...     def __init__(self, params):
...         super().__init__()
...         # manually assign single argument
...         self.save_hyperparameters(params)
...     def forward(self, *args, **kwargs):
...         ...
>>> model = SingleArgModel(Namespace(p1=1, p2='abc', p3=3.14))
>>> model.hparams
"p1": 1
"p2": abc
"p3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # pass argument(s) to ignore as a string or in a list
...         self.save_hyperparameters(ignore='arg2')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

返回类型: None

set_extra_state(state)¶

设置加载的 state_dict 中包含的额外状态。

此函数由 load_state_dict() 调用，用于处理 state_dict 中找到的任何额外状态。如果您的模块需要在 state_dict 中存储额外状态，请实现此函数以及相应的 get_extra_state()。

参数: state (dict) – 来自 state_dict 的额外状态
返回类型: None

set_mc_dropout(active)¶

set_predict_parameters(n, num_samples, roll_size, batch_size, n_jobs, predict_likelihood_parameters, mc_dropout)¶

在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置

返回类型: None

set_submodule(target, module)¶

如果存在，则设置由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

(图示为一个 nn.Module A。A 有一个嵌套子模块 net_b，其本身又有两个子模块 net_c 和 linear。net_c 然后有一个子模块 conv。)

要用一个新的子模块 Linear 覆盖 Conv2d，您可以调用 set_submodule("net_b.net_c.conv", nn.Linear(33, 16))。

参数

target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
module (Module) – 用于设置子模块的模块。

Raises

ValueError – 如果目标字符串为空
AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

返回类型

None

setup(stage)¶

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'

示例

class LitModel(...):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        download_data()
        tokenize()

        # don't do this
        self.something = else

    def setup(self, stage):
        data = load_data(...)
        self.l1 = nn.Linear(28, data.num_classes)

返回类型: None

share_memory()¶

参见 torch.Tensor.share_memory_()。

返回类型: ~T

state_dict(*args, destination=None, prefix='', keep_vars=False)¶

返回包含模块完整状态引用的字典。

参数和持久缓冲区（例如，运行平均值）都包含在内。键是相应的参数和缓冲区名称。设置为 None 的参数和缓冲区不包含在内。

注意

返回的对象是浅拷贝。它包含对模块参数和缓冲区的引用。

警告

目前 state_dict() 也按顺序接受 destination、prefix 和 keep_vars 的位置参数。但是，此用法已被弃用，未来版本将强制使用关键字参数。

警告

请避免使用参数 destination，因为它并非为终端用户设计。

参数

destination (dict, optional) – 如果提供，模块的状态将更新到此字典中，并返回相同的对象。否则，将创建一个 OrderedDict 并返回。默认值：None。
prefix (str, optional) – 添加到参数和缓冲区名称的前缀，用于在 state_dict 中构成键。默认值：''。
keep_vars (bool, optional) – 默认情况下，state dict 中返回的 Tensor s 与 autograd 分离。如果设置为 True，将不会进行分离。默认值：False。

返回值

包含模块完整状态的字典

返回类型

dict

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> module.state_dict().keys()
['bias', 'weight']

property strict_loading: bool¶

确定 Lightning 如何使用 .load_state_dict(…, strict=model.strict_loading) 加载此模型。

返回类型: bool

property supports_probabilistic_prediction: bool¶

返回类型: bool

teardown(stage)¶

在 fit（训练 + 验证）、验证、测试或预测结束时调用。

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'
返回类型: None

test_dataloader()¶

指定测试样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

test()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果您不需要测试数据集和 test_step()，则无需实现此方法。

返回类型: Any

test_step(*args, **kwargs)¶

对测试集中的单个批次数据进行操作。在此步骤中，您通常会生成示例或计算任何感兴趣的内容，例如准确率。

参数

batch – 您的数据可迭代对象（通常是 DataLoader）的输出。
batch_idx – 此批次的索引。
dataloader_idx – 生成此批次的数据加载器索引。（仅在使用多个数据加载器时）

返回类型

Union[Tensor, Mapping[str, Any], None]

返回值

Tensor - 损失张量
dict - 字典。可以包含任意键，但必须包含键 'loss'。
None - 跳到下一个批次。

# if you have one test dataloader:
def test_step(self, batch, batch_idx): ...

# if you have multiple test dataloaders:
def test_step(self, batch, batch_idx, dataloader_idx=0): ...

示例

# CASE 1: A single test dataset
def test_step(self, batch, batch_idx):
    x, y = batch

    # implement your own
    out = self(x)
    loss = self.loss(out, y)

    # log 6 example images
    # or generated text... or whatever
    sample_imgs = x[:6]
    grid = torchvision.utils.make_grid(sample_imgs)
    self.logger.experiment.add_image('example_images', grid, 0)

    # calculate acc
    labels_hat = torch.argmax(out, dim=1)
    test_acc = torch.sum(y == labels_hat).item() / (len(y) * 1.0)

    # log the outputs!
    self.log_dict({'test_loss': loss, 'test_acc': test_acc})

如果您传入多个测试数据加载器，test_step() 将有一个额外的参数。我们建议将默认值设置为 0，以便您可以快速在单个和多个数据加载器之间切换。

# CASE 2: multiple test dataloaders
def test_step(self, batch, batch_idx, dataloader_idx=0):
    # dataloader_idx tells you which dataset this is.
    ...

注意

如果您不需要测试，则无需实现此方法。

注意

调用 test_step() 时，模型已进入评估模式，并且 PyTorch 梯度已禁用。在测试 epoch 结束时，模型将返回训练模式并启用梯度。

to(*args, **kwargs)¶

参见 torch.nn.Module.to()。

返回类型: Self

to_dtype(dtype)¶: 将模块精度（默认为 float32）转换为其他精度。

to_empty(*, device, recurse=True)¶

在不复制存储的情况下，将参数和缓冲区移动到指定设备。

参数

device (torch.device) – 此模块中参数和缓冲区的目标设备。
recurse (bool) – 是否应将子模块的参数和缓冲区递归地移动到指定设备。

返回值

self

返回类型

Module

to_onnx(file_path, input_sample=None, **kwargs)¶

将模型保存为 ONNX 格式。

参数

file_path (Union[str, Path, BytesIO]) – 应保存 onnx 模型的文件路径。
input_sample (Optional[Any, None]) – 用于跟踪的输入。默认值：None（使用 self.example_input_array）
**kwargs – 将传递给 torch.onnx.export 函数。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)

model = SimpleModel()
input_sample = torch.randn(1, 64)
model.to_onnx("export.onnx", input_sample, export_params=True)

返回类型: None

to_torchscript(file_path=None, method='script', example_inputs=None, **kwargs)¶

默认情况下，将整个模型编译为 ScriptModule。如果您想使用跟踪，请提供参数 method='trace'，并确保提供了 example_inputs 参数，或设置了模型的 example_input_array。如果您想自定义被 script 的模块，则应覆盖此方法。如果您想返回多个模块，建议使用字典。

参数

file_path (Union[str, Path, None]) – 保存 torchscript 的路径。默认值：None（不保存文件）。
method (Optional[str, None]) – 是使用 TorchScript 的 script 方法还是 trace 方法。默认值：‘script’
example_inputs (Optional[Any, None]) – 当 method 设置为 ‘trace’ 时用于跟踪的输入。默认值：None（使用 example_input_array）
**kwargs – 将传递给 torch.jit.script() 或 torch.jit.trace() 函数的附加参数。

注意

需要实现 forward() 方法。
导出的脚本将被设置为评估模式。
建议您安装最新支持版本的 PyTorch 以无限制地使用此功能。另请参见 torch.jit 文档以了解支持的功能。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)))

model = SimpleModel()
model.to_torchscript(file_path="model.pt")

torch.jit.save(model.to_torchscript(
    file_path="model_trace.pt", method='trace', example_inputs=torch.randn(1, 64))
)

返回类型: Union[ScriptModule, dict[str, ScriptModule]]
返回值: 此 LightningModule 作为 torchscript，无论是否定义了 file_path。

toggle_optimizer(optimizer)¶

确保在训练步骤中仅计算当前优化器参数的梯度，以防止在多优化器设置中出现悬空梯度。

它与 untoggle_optimizer() 配合使用，以确保 param_requires_grad_state 正确重置。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要切换的优化器。
返回类型: None

train(mode=True)¶

将模块设置为训练模式。

这仅对某些模块有影响。有关它们在训练/评估模式下的行为详情，例如它们是否受影响（例如 Dropout、BatchNorm 等），请参阅特定模块的文档。

参数: mode (bool) – 是否设置训练模式 (True) 或评估模式 (False)。默认值: True。
返回值: self
返回类型: Module

train_criterion_reduction: Optional[str]¶

train_dataloader()¶

指定训练样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

您返回的数据加载器不会重新加载，除非您将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

fit()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any

property trainer: Trainer¶

返回类型: Trainer

training: bool¶

training_step(train_batch, batch_idx)¶

执行训练步骤

返回类型: Tensor

transfer_batch_to_device(batch, device, dataloader_idx)¶

如果您的 DataLoader 返回包装在自定义数据结构中的张量，请覆盖此钩子。

下面列出的数据类型（以及它们的任意嵌套）是开箱即用的支持

torch.Tensor 或任何实现了 .to(…) 的东西
list
dict
tuple

对于其他任何东西，你需要定义数据如何移动到目标设备 (CPU, GPU, TPU, …)。

注意

参数

batch (Any) – 需要转移到新设备的数据批次。
device (device) – PyTorch 中定义的目标设备。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据在新设备上的引用。

示例

def transfer_batch_to_device(self, batch, device, dataloader_idx):
    if isinstance(batch, CustomBatch):
        # move all tensors in your custom data structure to the device
        batch.samples = batch.samples.to(device)
        batch.targets = batch.targets.to(device)
    elif dataloader_idx == 0:
        # skip device transfer for the first dataloader or anything you wish
        pass
    else:
        batch = super().transfer_batch_to_device(batch, device, dataloader_idx)
    return batch

另请参阅

move_data_to_device()
apply_to_collection()

type(dst_type)¶

参见 torch.nn.Module.type()。

返回类型: Self

unfreeze()¶

解冻所有参数以进行训练。

model = MyLightningModule(...)
model.unfreeze()

返回类型: None

untoggle_optimizer(optimizer)¶

重置使用 toggle_optimizer() 切换的必需梯度状态。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要取消切换的优化器。
返回类型: None

val_criterion_reduction: Optional[str]¶

val_dataloader()¶

指定验证样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

您返回的数据加载器不会重新加载，除非您将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数。

建议所有数据下载和准备工作都在 prepare_data() 中进行。

fit()
validate()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果您不需要验证数据集和 validation_step()，则无需实现此方法。

返回类型: Any

validation_step(val_batch, batch_idx)¶

执行验证步骤

返回类型: Tensor

xpu(device=None)¶

将所有模型参数和缓冲区移动到 XPU。

这也会使得相关的参数和缓冲区成为不同的对象。因此，如果模块将在 XPU 上运行并进行优化，则应该在构建优化器之前调用它。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

zero_grad(set_to_none=True)¶

重置所有模型参数的梯度。

请参阅 torch.optim.Optimizer 下的类似函数，了解更多背景信息。

参数: set_to_none (bool) – 不设置为零，而是将梯度设置为 None。请参阅 torch.optim.Optimizer.zero_grad() 了解详情。
返回类型: None

class darts.models.forecasting.pl_forecasting_module.PLPastCovariatesModule(input_chunk_length, output_chunk_length, output_chunk_shift=0, train_sample_shape=None, loss_fn=MSELoss(), torch_metrics=None, likelihood=None, optimizer_cls=<class 'torch.optim.adam.Adam'>, optimizer_kwargs=None, lr_scheduler_cls=None, lr_scheduler_kwargs=None, use_reversible_instance_norm=False)[source]¶

基类：PLForecastingModule, ABC

基于 PyTorch Lightning 的预测模块。

此类旨在被继承以创建新的基于 PyTorch Lightning 的预测模块。子类化此类时，请确保添加具有以下签名的方

PLForecastingModule.__init__()

PLForecastingModule.forward()

PLForecastingModule._process_input_batch()

PLForecastingModule._produce_train_output()

PLForecastingModule._get_batch_prediction()

在子类 MyModel 的 __init__() 函数中调用 super(MyModel, self).__init__(**kwargs)，其中 kwargs 是 PLForecastingModule 的参数。

参数

input_chunk_length (int) – 模型输入的时间步长数量（每块）。适用于目标序列以及过去和/或未来协变量（如果模型支持）。
output_chunk_length (int) – 内部模型一次预测（每块）的时间步长数量。此外，未来协变量的未来值用作模型输入的数量（如果模型支持未来协变量）。它与 predict() 中使用的预测视野 n 不同，后者是使用一次性预测或自回归预测生成的所需预测点数。设置 n <= output_chunk_length 可防止自回归。当协变量未能充分延伸到未来时，这非常有用，或者为了禁止模型使用过去和/或未来协变量的未来值进行预测（取决于模型的协变量支持）。
train_sample_shape (Optional[tuple, None]) – 模型的输入形状，用于在不调用 fit_from_dataset 的情况下实例化模型，并对用于重新训练或预测的新训练/推理数据集执行健全性检查。
loss_fn (_Loss) – 用于训练的 PyTorch 损失函数。如果指定了 likelihood 参数，则此参数对于概率模型将被忽略。默认值：torch.nn.MSELoss()。
torch_metrics (Union[Metric, MetricCollection, None]) – 用于评估的 torch 指标或 MetricCollection。可在 https://torchmetrics.readthedocs.io/en/latest/ 找到可用指标的完整列表。默认值：None。
likelihood (Optional[TorchLikelihood, None]) – Darts 的 Likelihood 模型之一，用于概率预测。默认值：None。
optimizer_cls (Optimizer) – 要使用的 PyTorch 优化器类。默认值：torch.optim.Adam。
optimizer_kwargs (Optional[dict, None]) – 可选地，PyTorch 优化器的一些关键字参数（例如，{'lr': 1e-3} 用于指定学习率）。否则将使用选定的 optimizer_cls 的默认值。默认值：None。
lr_scheduler_cls (Optional[_LRScheduler, None]) – 可选地，要使用的 PyTorch 学习率调度器类。指定 None 对应于使用恒定学习率。默认值：None。
lr_scheduler_kwargs (Optional[dict, None]) – 可选地，PyTorch 学习率调度器的一些关键字参数。默认值：None。
use_reversible_instance_norm (bool) – 是否使用可逆实例归一化 RINorm 来对抗分布偏移，如 [1] 中所示。它仅应用于目标序列的特征，而不应用于协变量。

参考

1: T. Kim et al. “Reversible Instance Normalization for Accurate Time-Series Forecasting against Distribution Shift”, https://openreview.net/forum?id=cGDAkQo1C0p

属性

`automatic_optimization`	如果设置为 `False`，则您负责调用 `.backward()`, `.step()`, `.zero_grad()`。
`current_epoch`	`Trainer` 中的当前 epoch，如果未附加则为 0。
`device_mesh`	`ModelParallelStrategy` 等策略将创建设备网格，可在 `configure_model()` 钩子中访问该网格以并行化 LightningModule。
`example_input_array`	示例输入数组指定了模块在 `forward()` 方法中可以接受的内容。
`global_rank`	当前进程在所有节点和设备中的索引。
`global_step`	所有 epoch 中看到的总训练批次。
`hparams`	使用 `save_hyperparameters()` 保存的超参数集合。
`hparams_initial`	使用 `save_hyperparameters()` 保存的超参数集合。
`local_rank`	当前进程在单个节点内的索引。
`logger`	指向 Trainer 中 logger 对象的引用。
`loggers`	指向 Trainer 中 loggers 列表的引用。
`on_gpu`	如果此模型当前位于 GPU 上，则返回 `True`。
`output_chunk_length`	模型一次预测的时间步长数量。
`strict_loading`	确定 Lightning 如何使用 .load_state_dict(..., strict=model.strict_loading) 加载此模型。

device
dtype
epochs_trained
fabric
supports_probabilistic_prediction
trainer

方法

`add_module`(name, module)	向当前模块添加子模块。
`all_gather`(data[, group, sync_grads])	从多个进程聚合张量或张量集合。
`apply`(fn)	将 `fn` 递归地应用于每个子模块（由 `.children()` 返回）以及自身。
`backward`(loss, args, *kwargs)	调用此方法以在 `training_step()` 中返回的损失上执行反向传播。
`bfloat16`()	将所有浮点参数和缓冲区转换为 `bfloat16` 数据类型。
`buffers`([recurse])	返回模块缓冲区的迭代器。
`children`()	返回直接子模块的迭代器。
`clip_gradients`(optimizer[, ...])	内部处理梯度裁剪。
`compile`(args, *kwargs)	使用 `torch.compile()` 编译此模块的前向传播。
`configure_callbacks`()	配置模型特定的回调。
`configure_gradient_clipping`(optimizer[, ...])	对优化器参数执行梯度裁剪。
`configure_model`()	在策略和精度感知上下文中创建模块的钩子。
`configure_optimizers`()	配置用于模型优化的优化器和学习率调度器。
`configure_sharded_model`()	已弃用。
`configure_torch_metrics`(torch_metrics)	处理 torch_metrics 参数。
`cpu`()	参见 `torch.nn.Module.cpu()`。
`cuda`([device])	将所有模型参数和缓冲区移动到 GPU。
`double`()	参见 `torch.nn.Module.double()`。
`eval`()	将模块设置为评估模式。
`extra_repr`()	返回模块的额外表示。
`float`()	参见 `torch.nn.Module.float()`。
`forward`(args, *kwargs)	与 `torch.nn.Module.forward()` 相同。
`freeze`()	冻结所有参数以进行推理。
`get_buffer`(target)	如果存在，则返回由 `target` 指定的缓冲区，否则抛出错误。
`get_extra_state`()	返回要包含在模块 state_dict 中的任何额外状态。
`get_parameter`(target)	如果存在，则返回由 `target` 指定的参数，否则抛出错误。
`get_submodule`(target)	如果存在，则返回由 `target` 指定的子模块，否则抛出错误。
`half`()	参见 `torch.nn.Module.half()`。
`ipu`([device])	将所有模型参数和缓冲区移动到 IPU。
`load_from_checkpoint`(checkpoint_path[, ...])	从检查点加载模型的主要方式。
`load_state_dict`(state_dict[, strict, assign])	将参数和缓冲区从 `state_dict` 复制到此模块及其后代中。
`log`(name, value[, prog_bar, logger, ...])	记录键值对。
`log_dict`(dictionary[, prog_bar, logger, ...])	一次记录字典中的值。
`lr_scheduler_step`(scheduler, metric)	覆盖此方法以调整 `Trainer` 调用每个调度器的默认方式。
`lr_schedulers`()	返回训练期间使用的学习率调度器。
`manual_backward`(loss, args, *kwargs)	手动进行优化时，直接从您的 `training_step()` 调用此方法。
`modules`()	返回网络中所有模块的迭代器。
`mtia`([device])	将所有模型参数和缓冲区移动到 MTIA。
`named_buffers`([prefix, recurse, ...])	返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。
`named_children`()	返回直接子模块的迭代器，同时产生模块名称和模块本身。
`named_modules`([memo, prefix, remove_duplicate])	返回网络中所有模块的迭代器，同时产生模块名称和模块本身。
`named_parameters`([prefix, recurse, ...])	返回模块参数的迭代器，同时产生参数名称和参数本身。
`on_after_backward`()	在 `loss.backward()` 之后且在优化器步进之前调用。
`on_after_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备后修改或应用批次增强。
`on_before_backward`(loss)	在 `loss.backward()` 之前调用。
`on_before_batch_transfer`(batch, dataloader_idx)	覆盖此方法以在批次转移到设备之前修改或应用批次增强。
`on_before_optimizer_step`(optimizer)	在 `optimizer.step()` 之前调用。
`on_before_zero_grad`(optimizer)	在 `training_step()` 之后且在 `optimizer.zero_grad()` 之前调用。
`on_fit_end`()	在 fit 的最后调用。
`on_fit_start`()	在 fit 的最开始调用。
`on_load_checkpoint`(checkpoint)	由 Lightning 调用以恢复您的模型。
`on_predict_batch_end`(outputs, batch, batch_idx)	在预测循环中批次之后调用。
`on_predict_batch_start`(batch, batch_idx[, ...])	在预测循环中该批次发生任何事情之前调用。
`on_predict_end`()	在预测结束时调用。
`on_predict_epoch_end`()	在预测结束时调用。
`on_predict_epoch_start`()	在预测开始时调用。
`on_predict_model_eval`()	预测循环开始时调用。
`on_predict_start`()	在预测开始时调用。
`on_save_checkpoint`(checkpoint)	Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。
`on_test_batch_end`(outputs, batch, batch_idx)	在测试循环中批次之后调用。
`on_test_batch_start`(batch, batch_idx[, ...])	在测试循环中该批次发生任何事情之前调用。
`on_test_end`()	在测试结束时调用。
`on_test_epoch_end`()	在测试循环中 epoch 的最后调用。
`on_test_epoch_start`()	在测试循环中 epoch 的最开始调用。
`on_test_model_eval`()	测试循环开始时调用。
`on_test_model_train`()	测试循环结束时调用。
`on_test_start`()	在测试开始时调用。
`on_train_batch_end`(outputs, batch, batch_idx)	在训练循环中批次之后调用。
`on_train_batch_start`(batch, batch_idx)	在训练循环中该批次发生任何事情之前调用。
`on_train_end`()	在训练结束、logger 实验关闭之前调用。
`on_train_epoch_end`()	在训练循环中 epoch 的最后调用。
`on_train_epoch_start`()	在训练循环中 epoch 的最开始调用。
`on_train_start`()	在健全性检查之后、训练开始时调用。
`on_validation_batch_end`(outputs, batch, ...)	在验证循环中批次之后调用。
`on_validation_batch_start`(batch, batch_idx)	在验证循环中该批次发生任何事情之前调用。
`on_validation_end`()	在验证结束时调用。
`on_validation_epoch_end`()	在验证循环中 epoch 的最后调用。
`on_validation_epoch_start`()	在验证循环中 epoch 的最开始调用。
`on_validation_model_eval`()	验证循环开始时调用。
`on_validation_model_train`()	验证循环结束时调用。
`on_validation_model_zero_grad`()	由训练循环调用，在进入验证循环之前释放梯度。
`on_validation_start`()	在验证开始时调用。
`optimizer_step`(epoch, batch_idx, optimizer)	覆盖此方法以调整 `Trainer` 调用优化器的默认方式。
`optimizer_zero_grad`(epoch, batch_idx, optimizer)	覆盖此方法以更改 `optimizer.zero_grad()` 的默认行为。
`optimizers`([use_pl_optimizer])	返回训练期间使用的优化器。
`parameters`([recurse])	返回模块参数的迭代器。
`predict_dataloader`()	指定预测样本的可迭代对象或可迭代对象集合。
`predict_step`(batch, batch_idx[, dataloader_idx])	执行预测步骤
`prepare_data`()	使用此方法下载和准备数据。
`print`(args, *kwargs)	仅从进程 0 打印。
`register_backward_hook`(hook)	在模块上注册后向钩子。
`register_buffer`(name, tensor[, persistent])	向模块添加缓冲区。
`register_forward_hook`(hook, *[, prepend, ...])	在模块上注册前向钩子。
`register_forward_pre_hook`(hook, *[, ...])	在模块上注册前向预钩子。
`register_full_backward_hook`(hook[, prepend])	在模块上注册后向钩子。
`register_full_backward_pre_hook`(hook[, prepend])	在模块上注册后向预钩子。
`register_load_state_dict_post_hook`(hook)	注册一个后钩子，该钩子在模块的 `load_state_dict()` 被调用后运行。
`register_load_state_dict_pre_hook`(hook)	注册一个预钩子，该钩子在模块的 `load_state_dict()` 被调用前运行。
`register_module`(name, module)	`add_module()` 的别名。
`register_parameter`(name, param)	向模块添加参数。
`register_state_dict_post_hook`(hook)	为 `state_dict()` 方法注册一个后钩子。
`register_state_dict_pre_hook`(hook)	为 `state_dict()` 方法注册一个预钩子。
重置使用 `toggle_optimizer()` 切换的所需梯度的状态。	更改此模块中是否应记录参数上的自动梯度操作。
`save_hyperparameters`(*args[, ignore, frame, ...])	将参数保存到 `hparams` 属性。
`set_extra_state`(state)	设置加载的 state_dict 中包含的额外状态。
`set_predict_parameters`(n, num_samples, ...)	在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置
`set_submodule`(target, module)	如果存在，则设置由 `target` 指定的子模块，否则抛出错误。
如果您需要存储额外状态，请为您的模块实现此方法以及对应的 `set_extra_state()` 方法。构建模块的 state_dict() 时会调用此函数。	在 fit（训练 + 验证）、验证、测试或预测开始时调用。
`share_memory`()	参见 `torch.Tensor.share_memory_()`。
`setup`(stage)	返回包含模块完整状态引用的字典。
`state_dict`(*args[, destination, prefix, ...])	在 fit（训练 + 验证）、验证、测试或预测结束时调用。
`test_dataloader`()	指定测试样本的可迭代对象或可迭代对象集合。
`teardown`(stage)	处理测试集中的单个批次数据。
`test_step`(args, *kwargs)	参见 `torch.nn.Module.to()`。
`to`(args, *kwargs)	将模块精度（默认为 float32）转换为其他精度。
`to_dtype`(dtype)	在不复制存储的情况下，将参数和缓冲区移动到指定设备。
`to_empty`(*, device[, recurse])	将模型保存为 ONNX 格式。
示例输入数组是模块在 `forward()` 方法中可以消耗的规范。返回类型解释如下：	默认情况下，将整个模型编译为 `ScriptModule`。
`to_onnx`(file_path[, input_sample])	确保在训练步骤中仅计算当前优化器参数的梯度，以防止多优化器设置中出现悬空梯度。
`to_torchscript`([file_path, method, ...])	将模块设置为训练模式。
`train_dataloader`()	指定训练样本的可迭代对象或可迭代对象集合。
`toggle_optimizer`(optimizer)	执行训练步骤
`train`([mode])	如果您的 `DataLoader` 返回包装在自定义数据结构中的张量，请覆盖此钩子。
`training_step`(train_batch, batch_idx)	参见 `torch.nn.Module.type()`。
`unfreeze`()	解冻所有参数以进行训练。
`transfer_batch_to_device`(batch, device, ...)	重置使用 `toggle_optimizer()` 切换的所需梯度的状态。
`val_dataloader`()	指定验证样本的可迭代对象或可迭代对象集合。
`type`(dst_type)	执行验证步骤
`untoggle_optimizer`(optimizer)	将所有模型参数和缓冲区移动到 XPU。
`validation_step`(val_batch, batch_idx)	重置所有模型参数的梯度。

__call__
set_mc_dropout

xpu([device])

zero_grad([set_to_none])

CHECKPOINT_HYPER_PARAMS_KEY = 'hyper_parameters'¶

CHECKPOINT_HYPER_PARAMS_NAME = 'hparams_name'¶: TypeVar(‘T_destination’, bound=Dict[str, Any]) 的别名

CHECKPOINT_HYPER_PARAMS_TYPE = 'hparams_type'¶

向当前模块添加子模块。

模块可以使用给定的名称作为属性访问。

参数

name (str) – 子模块的名称。可以使用此名称从当前模块访问子模块
module (Module) – 要添加到模块的子模块。

返回类型

None

T_destination¶

从多个进程聚合张量或张量集合。

此方法需要在所有进程上调用，并且张量需要在所有进程上具有相同的形状，否则您的程序将永远暂停。

参数

data (Union[Tensor, dict, list, tuple]) – int、float、形状为 (batch, …) 的张量，或其（可能嵌套的）集合。
group (Optional[Any, None]) – 要从中收集结果的进程组。默认为所有进程 (world)。
sync_grads (bool) – 允许用户同步 all_gather 操作的梯度的标志。

返回类型

Union[Tensor, dict, list, tuple]

返回值

形状为 (world_size, batch, …) 的张量，如果输入是集合，则输出也将是包含此形状张量的集合。对于 world_size 为 1 的特殊情况，不会向张量添加额外维度。

add_module(name, module)¶

all_gather(data, group=None, sync_grads=False)¶

将 fn 递归地应用于每个子模块（由 .children() 返回）以及自身。

典型用法包括初始化模型的参数（另见 nn-init-doc）。

参数: fn (Module -> None) – 要应用于每个子模块的函数
返回值: self
返回类型: Module

示例

>>> @torch.no_grad()
>>> def init_weights(m):
>>>     print(m)
>>>     if type(m) == nn.Linear:
>>>         m.weight.fill_(1.0)
>>>         print(m.weight)
>>> net = nn.Sequential(nn.Linear(2, 2), nn.Linear(2, 2))
>>> net.apply(init_weights)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)

allow_zero_length_dataloader_with_multiple_devices: bool¶

如果设置为 False，则您负责调用 .backward(), .step(), .zero_grad()。

返回类型: bool

apply(fn)¶

property automatic_optimization: bool¶

参数: backward(loss, *args, **kwargs)¶

示例

def backward(self, loss):
    loss.backward()

返回类型: None

调用此方法可在 training_step() 返回的损失上执行反向传播。如果需要，请用您自己的实现覆盖此钩子。

将所有浮点参数和缓冲区转换为 bfloat16 数据类型。

注意

此方法会修改模块本身。

返回值: self
返回类型: Module

loss (Tensor) – 由 training_step() 返回的损失张量。如果使用梯度累积，此处的损失保持归一化值（按 1 / 累积步数缩放）。

返回模块缓冲区的迭代器。

参数: recurse (bool) – 如果为 True，则产生此模块和所有子模块的缓冲区。否则，仅产生此模块的直接成员缓冲区。
Yields: torch.Tensor – 模块缓冲区

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for buf in model.buffers():
>>>     print(type(buf), buf.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Tensor]

bfloat16()¶

buffers(recurse=True)¶

返回直接子模块的迭代器。

Yields: Module – 子模块
返回类型: Iterator[Module]

call_super_init: bool = False¶

内部处理梯度裁剪。

注意

children()¶
对于手动优化 (self.automatic_optimization = False)，如果要使用梯度裁剪，请考虑在训练步骤中手动调用 self.clip_gradients(opt, gradient_clip_val=0.5, gradient_clip_algorithm="norm")。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
clip_gradients(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。传递 gradient_clip_algorithm="value" 按值裁剪，传递 gradient_clip_algorithm="norm" 按范数裁剪。

返回类型

None

不要覆盖此方法。如果您想自定义梯度裁剪，请考虑使用 configure_gradient_clipping() 方法。

使用 torch.compile() 编译此模块的前向传播。

此模块的 __call__ 方法将被编译，并且所有参数将原样传递给 torch.compile()。

有关此函数的参数详细信息，请参见 torch.compile()。

gradient_clip_val (Union[int, float, None]) – 裁剪梯度的值。

返回类型: Union[Sequence[Callback], Callback]
返回值: 一个或多个回调，它们将扩展 Trainer 中的回调列表。

示例

def configure_callbacks(self):
    early_stop = EarlyStopping(monitor="val_acc", mode="max")
    checkpoint = ModelCheckpoint(monitor="val_loss")
    return [early_stop, checkpoint]

compile(*args, **kwargs)¶

configure_callbacks()¶

参数

optimizer (Optimizer) – 正在使用的当前优化器。
configure_gradient_clipping(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。默认情况下，Trainer 中传入的值将在此处可用。

示例

def configure_gradient_clipping(self, optimizer, gradient_clip_val, gradient_clip_algorithm):
    # Implement your own custom logic to clip gradients
    # You can call `self.clip_gradients` with your settings:
    self.clip_gradients(
        optimizer,
        gradient_clip_val=gradient_clip_val,
        gradient_clip_algorithm=gradient_clip_algorithm
    )

返回类型: None

对优化器参数执行梯度裁剪。在调用 optimizer_step() 之前调用。

在策略和精度感知上下文中创建模块的钩子。

此钩子在同一进程的 fit/val/test/predict 各阶段都会被调用，因此请确保此钩子的实现是幂等的，即在第一次调用此钩子后，后续调用应该是空操作。

返回类型: None

gradient_clip_val (Union[int, float, None]) – 裁剪梯度的值。默认情况下，此处将提供在 Trainer 中传递的值。: 配置用于模型优化的优化器和学习率调度器。

configure_model()¶

已弃用。

请改用 configure_model()。

返回类型: None

configure_optimizers()¶

处理 torch_metrics 参数。

返回类型: MetricCollection

configure_sharded_model()¶

参见 torch.nn.Module.cpu()。

返回类型: Self

static configure_torch_metrics(torch_metrics)¶

参数: device (Union[int, device, None]) – 如果指定，所有参数将被复制到该设备。如果为 None，将使用当前的 CUDA 设备索引。
返回值: self
返回类型: Module

cpu()¶

Trainer 中的当前 epoch，如果未附加则为 0。

返回类型: int

cuda(device=None)¶

返回类型: device

property current_epoch: int¶

ModelParallelStrategy 等策略将创建设备网格，可在 configure_model() 钩子中访问该网格以并行化 LightningModule。

返回类型: Optional[ForwardRef, None]

property device: device¶

参见 torch.nn.Module.double()。

返回类型: Self

property device_mesh: Optional[DeviceMesh]¶

返回类型: Union[str, dtype]

double()¶

property dtype: Union[str, dtype]¶

dump_patches: bool = False¶

将模块设置为评估模式。

这仅对某些模块有效。有关特定模块在训练/评估模式下的行为详情，即它们是否受到影响，请参阅其文档，例如 Dropout、BatchNorm 等。

这等同于 self.train(False)。

有关 .eval() 与可能与其混淆的几个类似机制之间的比较，请参见 locally-disable-grad-doc。

返回值: self
返回类型: Module

property epochs_trained¶

eval()¶

单个张量：假定模型接受一个参数，即 model.forward(model.example_input_array)
元组：输入数组应被解释为位置参数序列，即 model.forward(*model.example_input_array)
字典：输入数组表示命名关键字参数，即 model.forward(**model.example_input_array)

返回类型: Union[Tensor, tuple, dict, None]

property example_input_array: Optional[Union[Tensor, tuple, dict]]¶

返回模块的额外表示。

要打印自定义的额外信息，您应该在自己的模块中重新实现此方法。单行和多行字符串都可接受。

返回类型: str

示例输入数组是模块在 forward() 方法中可以消耗的规范。返回类型解释如下：

返回类型: Optional[Fabric, None]

extra_repr()¶

参见 torch.nn.Module.float()。

返回类型: Self

property fabric: Optional[Fabric]¶

与 torch.nn.Module.forward() 相同。

参数

*args – 您决定传递给 forward 方法的任何内容。
**kwargs – 关键字参数也是可以的。

返回类型

Any

返回值

您的模型的输出

float()¶

冻结所有参数以进行推理。

示例

model = MyLightningModule(...)
model.freeze()

返回类型: None

abstract forward(*args, **kwargs)¶

如果存在，则返回由 target 指定的缓冲区，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的缓冲区的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的缓冲区
返回类型: torch.Tensor
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是缓冲区

freeze()¶

返回要包含在模块 state_dict 中的任何额外状态。

get_buffer(target)¶

返回值: 要存储在模块 state_dict 中的任何额外状态
返回类型: object

get_extra_state()¶

如果存在，则返回由 target 指定的参数，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的参数的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的参数
返回类型: torch.nn.Parameter
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Parameter

如果您需要存储额外状态，请为您的模块实现此方法以及对应的 set_extra_state() 方法。构建模块的 state_dict() 时会调用此函数。

如果存在，则返回由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

（图表显示了一个 nn.Module A。 A 有一个嵌套子模块 net_b，它本身有两个子模块 net_c 和 linear。 net_c 还有一个子模块 conv。）

要检查是否存在 linear 子模块，我们可以调用 get_submodule("net_b.linear")。要检查是否存在 conv 子模块，我们可以调用 get_submodule("net_b.net_c.conv")。

参数: target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
返回值: target 引用的子模块
返回类型: torch.nn.Module
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

get_parameter(target)¶

当前进程在所有节点和设备中的索引。

返回类型: int

get_submodule(target)¶

所有 epoch 中看到的总训练批次。

如果未附加 Trainer，此属性值为 0。

返回类型: int

property global_rank: int¶

参见 torch.nn.Module.half()。

返回类型: Self

property global_step: int¶

half()¶

返回类型: Union[AttributeDict, MutableMapping]
返回值: 可变的超参数字典

property hparams: Union[AttributeDict, MutableMapping]¶

使用 save_hyperparameters() 保存的超参数集合。用户可以修改它。对于初始超参数的冻结集，请使用 hparams_initial。

返回值: 不可变初始超参数
返回类型: AttributeDict

property hparams_initial: AttributeDict¶

将所有模型参数和缓冲区移动到 IPU。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 IPU 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

使用 save_hyperparameters() 保存的超参数集合。这些内容是只读的。对已保存超参数的手动更新可以通过 hparams 进行。

从检查点加载模型的主要方式。当 Lightning 保存检查点时，它会将传递给 __init__ 的参数存储在检查点中的 "hyper_parameters" 下。

通过 **kwargs 指定的任何参数将覆盖存储在 "hyper_parameters" 中的参数。

参数

checkpoint_path (Union[str, Path, IO]) – 检查点路径。这也可以是 URL 或文件类对象
map_location (Union[device, str, int, Callable[[UntypedStorage, str], Optional[UntypedStorage, None]], dict[Union[device, str, int], Union[device, str, int]], None]) – 如果您的检查点保存的是 GPU 模型，而您现在在 CPU 或不同数量的 GPU 上加载，请使用此参数映射到新的配置。其行为与 torch.load() 中相同。
hparams_file (Union[str, Path, None]) –
可选的 .yaml 或 .csv 文件路径，其结构如下例所示
```
drop_prob: 0.2
dataloader:
    batch_size: 32
```
您很可能不需要此参数，因为 Lightning 总是会将超参数保存到检查点中。但是，如果您的检查点权重没有保存超参数，请使用此方法传入一个包含您希望使用的超参数的 .yaml 文件。这些超参数将被转换为 dict 并传递给您的 LightningModule 使用。

如果您的模型的 hparams 参数是 Namespace 并且 .yaml 文件具有分层结构，您需要重构您的模型以将 hparams 视为 dict。
strict (Optional[bool, None]) – 是否严格强制 checkpoint_path 中的键与此模块的 state dict 返回的键完全匹配。默认为 True，除非设置了 LightningModule.strict_loading，在这种情况下，它将默认为 LightningModule.strict_loading 的值。
**kwargs – 初始化模型所需的任何额外关键字参数。也可以用于覆盖已保存的超参数值。

返回类型

Self

返回值

加载了权重和超参数（如果可用）的 LightningModule 实例。

注意

load_from_checkpoint 是一个类方法。您应该使用 LightningModule 类来调用它，而不是 LightningModule 实例，否则将引发 TypeError。

注意

示例

# load weights without mapping ...
model = MyLightningModule.load_from_checkpoint('path/to/checkpoint.ckpt')

# or load weights mapping all weights from GPU 1 to GPU 0 ...
map_location = {'cuda:1':'cuda:0'}
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    map_location=map_location
)

# or load weights and hyperparameters from separate files.
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    hparams_file='/path/to/hparams_file.yaml'
)

# override some of the params with new values
model = MyLightningModule.load_from_checkpoint(
    PATH,
    num_layers=128,
    pretrained_ckpt_path=NEW_PATH,
)

# predict
pretrained_model.eval()
pretrained_model.freeze()
y_hat = pretrained_model(x)

ipu(device=None)¶

将参数和缓冲区从 state_dict 复制到此模块及其后代中。

load_from_checkpoint(checkpoint_path, map_location=None, hparams_file=None, strict=None, **kwargs)¶

警告

load_state_dict(state_dict, strict=True, assign=False)¶

参数

state_dict (dict) – 包含参数和持久缓冲区的字典。
如果 strict 为 True，则 state_dict 的键必须与此模块的 state_dict() 函数返回的键完全匹配。
assign (bool, optional) – 设置为 False 时，保留当前模块中张量的属性，而设置为 True 时，保留 state dict 中张量的属性。唯一的例外是 Default: ``False` 的 requires_grad 字段

返回值

missing_keys 是一个字符串列表，包含此模块需要但
提供的 state_dict 中缺失的键。
unexpected_keys 是一个字符串列表，包含此模块
不预期但提供的 state_dict 中存在的键。

返回类型

包含 missing_keys 和 unexpected_keys 字段的 NamedTuple

注意

如果 assign 为 True，则优化器必须在调用 load_state_dict 之后创建，除非 get_swap_module_params_on_conversion() 为 True。

strict (bool, optional) – 是否严格要求 state_dict 中的键与此模块的 state_dict() 函数返回的键匹配。默认值：True

当前进程在单个节点内的索引。

返回类型: int

如果参数或缓冲区注册为 None 且其对应的键存在于 state_dict 中，load_state_dict() 将引发 RuntimeError。

记录键值对。

示例

self.log('train_loss', loss)

每个钩子的默认行为在此处有文档说明：extensions/logging:Automatic Logging。

参数

name (str) – 要记录的键。如果使用 DDP 或任何其他分布式策略，则必须在所有进程中保持一致。
property local_rank: int¶
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图。
sync_dist (bool) – 如果为 True，则在设备之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 DDP 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个 dataloader 时）。如果 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch_size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
metric_attribute (Optional[str, None]) – 为了恢复指标状态，Lightning 需要您的模型中 torchmetrics.Metric 的引用。如果它是一个模型属性，则会自动找到。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

一次记录字典中的值。

示例

values = {'loss': loss, 'acc': acc, ..., 'metric_n': metric_n}
self.log_dict(values)

参数

value (Union[Metric, Tensor, int, float]) – 要记录的值。可以是 float、Tensor 或 Metric。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。None 会自动记录 training_step，但不记录 validation/test_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。None 会自动记录 val/test step，但不记录 training_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图
sync_dist (bool) – 如果为 True，则在 GPU/TPU 之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 ddp 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个时）。如果为 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

指向 Trainer 中 logger 对象的引用。

返回类型: Union[Logger, Logger, None]

dictionary (Union[Mapping[str, Union[Metric, Tensor, int, float]], MetricCollection]) – 键值对。如果使用 DDP 或任何其他分布式策略，键必须在所有进程中相同。值可以是 float、Tensor、Metric 或 MetricCollection。

指向 Trainer 中 loggers 列表的引用。

返回类型: Union[list[Logger], list[Logger]]

property logger: Optional[Union[Logger, Logger]]¶

覆盖此方法以调整 Trainer 调用每个调度器的默认方式。默认情况下，Lightning 根据每个调度器的 interval 调用 step()，如示例所示。

参数

scheduler (Union[LRScheduler, ReduceLROnPlateau]) – 学习率调度器。
metric (Optional[Any, None]) – 用于像 ReduceLROnPlateau 这样的调度器的监视器值。

示例

# DEFAULT
def lr_scheduler_step(self, scheduler, metric):
    if metric is None:
        scheduler.step()
    else:
        scheduler.step(metric)

# Alternative way to update schedulers if it requires an epoch value
def lr_scheduler_step(self, scheduler, metric):
    scheduler.step(epoch=self.current_epoch)

返回类型: None

property loggers: Union[list[pytorch_lightning.loggers.logger.Logger], list[lightning_fabric.loggers.logger.Logger]]¶

返回训练期间使用的学习率调度器。对于手动优化很有用。

返回类型: Union[None, list[Union[LRScheduler, ReduceLROnPlateau]], LRScheduler, ReduceLROnPlateau]
返回值: 单个调度器，或者在存在多个调度器时返回一个列表，如果在 configure_optimizers() 中没有返回调度器，则返回 None。

lr_scheduler_step(scheduler, metric)¶

lr_schedulers()¶

更多示例请参见 manual optimization。

示例

def training_step(...):
    opt = self.optimizers()
    loss = ...
    opt.zero_grad()
    # automatically applies scaling, etc...
    self.manual_backward(loss)
    opt.step()

参数

loss (Tensor) – 用于计算梯度的张量。必须附加计算图。
*args – 要转发给 backward() 的额外位置参数
**kwargs – 要转发给 backward() 的额外关键字参数

返回类型

None

manual_backward(loss, *args, **kwargs)¶

返回网络中所有模块的迭代器。

Yields: Module – 网络中的一个模块

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.modules()):
...     print(idx, '->', m)

0 -> Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)
1 -> Linear(in_features=2, out_features=2, bias=True)

返回类型: Iterator[Module]

手动进行优化时，直接从您的 training_step() 调用此方法。通过使用此方法，Lightning 可以确保在使用混合精度时应用所有适当的缩放。

将所有模型参数和缓冲区移动到 MTIA。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 MTIA 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

modules()¶

返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。

参数

prefix (str) – 要添加到所有缓冲区名称前的字符串前缀。
recurse (bool, optional) – 如果为 True，则生成此模块及其所有子模块的缓冲区。否则，仅生成此模块的直接成员缓冲区。默认为 True。
remove_duplicate (bool, optional) – 是否移除结果中的重复缓冲区。默认为 True。

Yields

(str, torch.Tensor) – 包含名称和缓冲区的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, buf in self.named_buffers():
>>>     if name in ['running_var']:
>>>         print(buf.size())

返回类型: Iterator[Tuple[str, Tensor]]

mtia(device=None)¶

返回直接子模块的迭代器，同时产生模块名称和模块本身。

Yields: (str, Module) – 包含名称和子模块的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, module in model.named_children():
>>>     if name in ['conv4', 'conv5']:
>>>         print(module)

返回类型: Iterator[Tuple[str, Module]]

named_buffers(prefix='', recurse=True, remove_duplicate=True)¶

返回网络中所有模块的迭代器，同时产生模块名称和模块本身。

参数

memo (Optional[Set[Module], None]) – 用于存储已添加到结果中的模块集合的备忘录
prefix (str) – 将添加到模块名称前的字符串前缀
remove_duplicate (bool) – 是否移除结果中重复的模块实例

Yields

(str, Module) – 包含名称和模块的元组

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.named_modules()):
...     print(idx, '->', m)

0 -> ('', Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
))
1 -> ('0', Linear(in_features=2, out_features=2, bias=True))

named_children()¶

返回模块参数的迭代器，同时产生参数名称和参数本身。

参数

prefix (str) – 要添加到所有参数名称前的字符串前缀。
recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
remove_duplicate (bool, optional) – 是否移除结果中重复的参数。默认为 True。

Yields

(str, Parameter) – 包含名称和参数的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, param in self.named_parameters():
>>>     if name in ['bias']:
>>>         print(param.size())

返回类型: Iterator[Tuple[str, Parameter]]

named_modules(memo=None, prefix='', remove_duplicate=True)¶

在 loss.backward() 之后且在优化器步进之前调用。

注意

如果使用原生 AMP，此时梯度不会被取消缩放。如果您需要未缩放的梯度，请使用 on_before_optimizer_step。

返回类型: None

named_parameters(prefix='', recurse=True, remove_duplicate=True)¶

覆盖此方法以在批次转移到设备后修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_after_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = gpu_transforms(batch['x'])
    return batch

另请参阅

on_before_batch_transfer()
transfer_batch_to_device()

on_after_backward()¶

在 loss.backward() 之前调用。

参数: loss (Tensor) – 损失值，除以进行梯度累积的批次数，如果使用 AMP 则会进行缩放。
返回类型: None

on_after_batch_transfer(batch, dataloader_idx)¶

覆盖此方法以在批次转移到设备之前修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_before_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = transforms(batch['x'])
    return batch

另请参阅

on_after_batch_transfer()
transfer_batch_to_device()

on_before_backward(loss)¶

在 optimizer.step() 之前调用。

on_before_batch_transfer(batch, dataloader_idx)¶

如果使用 AMP，损失值在此钩子调用前会取消缩放。有关梯度缩放的更多信息，请参阅这些文档。

如果进行梯度裁剪，此时梯度尚未被裁剪。

参数: optimizer (Optimizer) – 正在使用的当前优化器。

示例

def on_before_optimizer_step(self, optimizer):
    # example to inspect gradient information in tensorboard
    if self.trainer.global_step % 25 == 0:  # don't make the tf file huge
        for k, v in self.named_parameters():
            self.logger.experiment.add_histogram(
                tag=k, values=v.grad, global_step=self.trainer.global_step
            )

返回类型: None

on_before_optimizer_step(optimizer)¶

在 training_step() 之后且在 optimizer.zero_grad() 之前调用。

在训练循环中，在优化器步长后和梯度清零前调用。是检查权重更新后权重信息的好地方。

这里是它被调用的地方

for optimizer in optimizers:
    out = training_step(...)

    model.on_before_zero_grad(optimizer) # < ---- called here
    optimizer.zero_grad()

    backward()

参数: optimizer (Optimizer) – 应清零其梯度的优化器。
返回类型: None

如果使用梯度累积，则在梯度累积后调用此钩子。参见：:paramref:`~pytorch_lightning.trainer.trainer.Trainer.accumulate_grad_batches`。

在 fit 的最后调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

on_before_zero_grad(optimizer)¶

在 fit 的最开始调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

on_fit_end()¶

如果此模型当前位于 GPU 上，则返回 True。

对于在 LightningModule 中设置标志以区分 CPU 和 GPU 的行为很有用。

返回类型: bool

on_fit_start()¶

property on_gpu: bool¶

参数: checkpoint (dict[str, Any]) – 已加载的检查点

示例

def on_load_checkpoint(self, checkpoint):
    # 99% of the time you don't need to implement this method
    self.something_cool_i_want_to_save = checkpoint['something_cool_i_want_to_save']

注意

Lightning 会自动恢复全局步长、epoch 和训练状态，包括 amp 缩放。您无需恢复任何与训练相关的内容。

返回类型: None

on_load_checkpoint(checkpoint)¶

在预测循环中批次之后调用。

参数

outputs (Optional[Any, None]) – predict_step(x) 的输出
batch (Any) – 预测 DataLoader 返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

由 Lightning 调用以恢复您的模型。如果您使用 on_save_checkpoint() 保存了内容，这是您恢复它的机会。

在预测循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在预测结束时调用。

返回类型: None

on_predict_batch_start(batch, batch_idx, dataloader_idx=0)¶

在预测结束时调用。

返回类型: None

on_predict_end()¶

在预测开始时调用。

返回类型: None

on_predict_epoch_end()¶

预测循环开始时调用。

预测循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。

返回类型: None

on_predict_epoch_start()¶

在预测开始时调用。

返回类型: None

on_predict_model_eval()¶

Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。

参数: checkpoint (dict[str, Any]) – 在检查点字典被写入文件之前的完整字典。此钩子函数的实现可以将额外数据插入此字典。

示例

def on_save_checkpoint(self, checkpoint):
    # 99% of use cases you don't need to implement this method
    checkpoint['something_cool_i_want_to_save'] = my_cool_pickable_object

注意

Lightning 会保存训练的所有方面（周期、全局步数等），包括 amp scaling。您无需存储任何关于训练的内容。

返回类型: None

on_predict_start()¶

在测试循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – test_step(x) 的输出。
batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_save_checkpoint(checkpoint)¶

在测试循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在测试结束时调用。

返回类型: None

on_test_batch_start(batch, batch_idx, dataloader_idx=0)¶

在测试循环中 epoch 的最后调用。

返回类型: None

on_test_end()¶

在测试循环中 epoch 的最开始调用。

返回类型: None

on_test_epoch_end()¶

测试循环开始时调用。

测试循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_test_model_train()。

返回类型: None

on_test_epoch_start()¶

测试循环结束时调用。

测试循环默认将 LightningModule 的 training 模式恢复到开始测试之前的状态。重写此钩子函数以改变此行为。另请参见 on_test_model_eval()。

返回类型: None

on_test_model_eval()¶

在测试开始时调用。

返回类型: None

on_test_model_train()¶

在训练循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – training_step(x) 的输出。
batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

注意

此处 outputs["loss"] 的值将是根据 accumulate_grad_batches 对 training_step 返回的损失值进行归一化后的值。

返回类型: None

on_test_start()¶

在训练循环中该批次发生任何事情之前调用。

如果此处返回 -1，将跳过当前周期的剩余训练。

参数

batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

返回类型

Optional[int, None]

on_train_batch_end(outputs, batch, batch_idx)¶

在训练结束、logger 实验关闭之前调用。

返回类型: None

on_train_batch_start(batch, batch_idx)¶

在训练循环中 epoch 的最后调用。

要在周期结束时访问所有批次输出，您可以将步输出缓存为 LightningModule 的属性，并在此钩子函数中访问它们

class MyLightningModule(L.LightningModule):
    def __init__(self):
        super().__init__()
        self.training_step_outputs = []

    def training_step(self):
        loss = ...
        self.training_step_outputs.append(loss)
        return loss

    def on_train_epoch_end(self):
        # do something with all training_step outputs, for example:
        epoch_mean = torch.stack(self.training_step_outputs).mean()
        self.log("training_epoch_mean", epoch_mean)
        # free up the memory
        self.training_step_outputs.clear()

on_train_end()¶

在训练循环中 epoch 的最开始调用。

返回类型: None

on_train_epoch_end()¶

在健全性检查之后、训练开始时调用。

返回类型: None

on_train_epoch_start()¶

在验证循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – validation_step(x) 的输出。
batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_batch_start(batch, batch_idx, dataloader_idx=0)¶

在验证循环中该批次发生任何事情之前调用。

参数

batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_end()¶

在验证结束时调用。

返回类型: None

on_validation_epoch_end()¶: 在验证循环中 epoch 的最后调用。

on_validation_epoch_start()¶

在验证循环中 epoch 的最开始调用。

返回类型: None

on_validation_model_eval()¶

验证循环开始时调用。

验证循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_validation_model_train()。

返回类型: None

on_validation_model_train()¶

验证循环结束时调用。

验证循环默认将 LightningModule 的 training 模式恢复到开始验证之前的状态。重写此钩子函数以改变此行为。另请参见 on_validation_model_eval()。

返回类型: None

on_validation_model_zero_grad()¶

由训练循环调用，在进入验证循环之前释放梯度。

返回类型: None

on_validation_start()¶

在验证开始时调用。

返回类型: None

optimizer_step(epoch, batch_idx, optimizer, optimizer_closure=None)¶

覆盖此方法以调整 Trainer 调用优化器的默认方式。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Union[Optimizer, LightningOptimizer]) – PyTorch 优化器
optimizer_closure (Optional[Callable[[], Any], None]) – 优化器闭包。必须执行此闭包，因为它包含对 training_step()、optimizer.zero_grad() 和 backward() 的调用。

示例

def optimizer_step(self, epoch, batch_idx, optimizer, optimizer_closure):
    # Add your custom logic to run directly before `optimizer.step()`

    optimizer.step(closure=optimizer_closure)

    # Add your custom logic to run directly after `optimizer.step()`

返回类型: None

optimizer_zero_grad(epoch, batch_idx, optimizer)¶

覆盖此方法以更改 optimizer.zero_grad() 的默认行为。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Optimizer) – PyTorch 优化器

示例

# DEFAULT
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad()

# Set gradients to `None` instead of zero to improve performance (not required on `torch>=2.0.0`).
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad(set_to_none=True)

有关上述示例的解释，请参见 torch.optim.Optimizer.zero_grad()。

返回类型: None

optimizers(use_pl_optimizer=True)¶

返回训练期间使用的优化器。对于手动优化很有用。

参数: use_pl_optimizer (bool) – 如果为 True，则会将优化器封装在 LightningOptimizer 中，以自动处理精度、分析以及步调用计数，从而实现正确的日志记录和检查点。它专门封装 step 方法，不支持没有此方法的自定义优化器。
返回类型: Union[Optimizer, LightningOptimizer, _FabricOptimizer, list[Optimizer], list[LightningOptimizer], list[_FabricOptimizer]]
返回值: 单个优化器，或者在存在多个优化器时返回一个列表。

property output_chunk_length: Optional[int]¶

模型一次预测的时间步长数量。

返回类型: Optional[int, None]

parameters(recurse=True)¶

返回模块参数的迭代器。

这通常传递给优化器。

参数: recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
Yields: Parameter – 模块参数

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for param in model.parameters():
>>>     print(type(param), param.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Parameter]

pred_batch_size: Optional[int]¶

pred_mc_dropout: Optional[bool]¶

pred_n: Optional[int]¶

pred_n_jobs: Optional[int]¶

pred_num_samples: Optional[int]¶

pred_roll_size: Optional[int]¶

predict_dataloader()¶

指定预测样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

建议所有数据下载和准备都在 prepare_data() 中进行。

predict()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any
返回值: 一个 torch.utils.data.DataLoader 或其序列，指定预测样本。

predict_likelihood_parameters: Optional[bool]¶

predict_step(batch, batch_idx, dataloader_idx=None)¶

执行预测步骤

batch: Darts 的 InferenceDataset 的输出 - 包含 (past_target, past_covariates, historic_future_covariates, future_covariates, future_past_covariates, input time series, prediction start time step) 的元组
batch_idx: 当前批次的批次索引
dataloader_idx: 数据加载器索引

返回类型: Sequence[TimeSeries]

prepare_data()¶

警告

不要在此方法中为模型设置状态（请改用 setup 方法），因为此方法不会在每个设备上调用

示例

def prepare_data(self):
    # good
    download_data()
    tokenize()
    etc()

    # bad
    self.split = data_split
    self.some_state = some_other_state()

在分布式环境中，prepare_data 可以通过两种方式调用（使用 prepare_data_per_node）

每个节点一次。这是默认设置，仅在 LOCAL_RANK=0 上调用。
总共一次。仅在 GLOBAL_RANK=0 上调用。

示例

# DEFAULT
# called once per node on LOCAL_RANK=0 of that node
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = True

# call on GLOBAL_RANK=0 (great for shared file systems)
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = False

此方法在请求数据加载器之前调用

model.prepare_data()
initialize_distributed()
model.setup(stage)
model.train_dataloader()
model.val_dataloader()
model.test_dataloader()
model.predict_dataloader()

返回类型: None

prepare_data_per_node: bool¶

print(*args, **kwargs)¶

仅从进程 0 打印。在任何分布式模式下使用此方法以仅记录一次。

参数

*args – 要打印的内容。与 Python 内置的 print 函数相同。
**kwargs – 与 Python 内置的 print 函数相同。

示例

def forward(self, x):
    self.print(x, 'in forward')

返回类型: None

register_backward_hook(hook)¶

在模块上注册后向钩子。

此函数已被弃用，推荐使用 register_full_backward_hook()，此函数的行为将在未来版本中改变。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_buffer(name, tensor, persistent=True)¶

向模块添加缓冲区。

这通常用于注册不应被视为模型参数的缓冲区。例如，BatchNorm 的 running_mean 不是参数，但它是模块状态的一部分。默认情况下，缓冲区是持久的，并将与参数一起保存。通过将 persistent 设置为 False 可以更改此行为。持久缓冲区和非持久缓冲区的唯一区别在于，后者不会包含在此模块的 state_dict 中。

缓冲区可以使用给定的名称作为属性访问。

参数

name (str) – 缓冲区的名称。可以使用给定的名称从此模块访问缓冲区
tensor (Tensor 或 None) – 要注册的缓冲区。如果为 None，则对缓冲区进行的操作（例如 cuda）将被忽略。如果为 None，则缓冲区**不**包含在模块的 state_dict 中。
persistent (bool) – 缓冲区是否是此模块的 state_dict 的一部分。

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> self.register_buffer('running_mean', torch.zeros(num_features))

返回类型: None

register_forward_hook(hook, *, prepend=False, with_kwargs=False, always_call=False)¶

在模块上注册前向钩子。

每次在 forward() 计算出输出后都会调用此钩子。

如果 with_kwargs 为 False 或未指定，则输入仅包含传递给模块的位置参数。关键字参数不会传递给钩子，只会传递给 forward。钩子可以修改输出。它可以就地修改输入，但由于此钩子是在 forward() 调用后才调用，所以修改不会影响 forward。此钩子应具有以下签名

hook(module, args, output) -> None or modified output

如果 with_kwargs 为 True，则前向钩子函数将接收传递给 forward 函数的 kwargs，并预期返回可能修改过的输出。此钩子函数应具有以下签名：

hook(module, args, kwargs, output) -> None or modified output

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 True，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之后触发。请注意，使用 register_module_forward_hook() 注册的全局 forward 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 True，hook 将接收传递给 forward 函数的 kwargs。默认值：False
always_call (bool) – 如果为 True，无论在调用模块时是否引发异常，hook 都将被运行。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_forward_pre_hook(hook, *, prepend=False, with_kwargs=False)¶

在模块上注册前向预钩子。

每次调用 forward() 之前都会调用此钩子。

hook(module, args) -> None or modified input

hook(module, args, kwargs) -> None or a tuple of modified input and kwargs

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之后触发。请注意，使用 register_module_forward_pre_hook() 注册的全局 forward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 true，hook 将接收传递给 forward 函数的 kwargs。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_hook(hook, prepend=False)¶

在模块上注册后向钩子。

每当计算相对于模块的梯度时，此钩子函数都将被调用，即只有当计算相对于模块输出的梯度时，此钩子函数才会执行。此钩子函数应具有以下签名：

hook(module, grad_input, grad_output) -> tuple(Tensor) or None

警告

使用后向钩子时，不允许原地修改输入或输出，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之后触发。请注意，使用 register_module_full_backward_hook() 注册的全局 backward 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_pre_hook(hook, prepend=False)¶

在模块上注册后向预钩子。

每当计算模块的梯度时，此钩子函数都将被调用。此钩子函数应具有以下签名：

hook(module, grad_output) -> tuple[Tensor] or None

警告

使用后向钩子时，不允许原地修改输入，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之后触发。请注意，使用 register_module_full_backward_pre_hook() 注册的全局 backward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_load_state_dict_post_hook(hook)¶

注册一个后钩子函数，在调用模块的 load_state_dict() 后运行。

它应该具有以下签名：: hook(module, incompatible_keys) -> None

如有需要，可以原地修改给定的 incompatible_keys。

注意，当调用 load_state_dict() 并设置 strict=True 时执行的检查会受到钩子对 missing_keys 或 unexpected_keys 所做修改的影响，这是预期的行为。向任何一组键添加内容都会在 strict=True 时引发错误，而清除缺失和意外的键则会避免错误。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_load_state_dict_pre_hook(hook)¶

注册一个预钩子函数，在调用模块的 load_state_dict() 之前运行。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata, strict, missing_keys, unexpected_keys, error_msgs) -> None # noqa: B950

参数: hook (Callable) – 可调用钩子函数，将在加载状态字典之前被调用。

register_module(name, module)¶

add_module() 的别名。

返回类型: None

register_parameter(name, param)¶

向模块添加参数。

参数可以使用给定的名称作为属性访问。

参数

name (str) – 参数的名称。可以使用给定的名称从此模块访问参数
param (Parameter 或 None) – 要添加到模块的参数。如果为 None，则对参数进行的操作（例如 cuda）将被忽略。如果为 None，则参数**不**包含在模块的 state_dict 中。

返回类型

None

register_state_dict_post_hook(hook)¶

为 state_dict() 方法注册一个后钩子。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata) -> None

注册的钩子函数可以原地修改 state_dict。

register_state_dict_pre_hook(hook)¶

为 state_dict() 方法注册一个预钩子。

它应该具有以下签名：: hook(module, prefix, keep_vars) -> None

注册的钩子函数可用于在进行 state_dict 调用之前执行预处理。

requires_grad_(requires_grad=True)¶

更改此模块中是否应记录参数上的自动梯度操作。

此方法原地设置参数的 requires_grad 属性。

此方法有助于冻结模块的一部分用于微调，或单独训练模型的各个部分（例如，GAN 训练）。

有关 .requires_grad_() 和几个可能与其混淆的类似机制的比较，请参见 locally-disable-grad-doc。

参数: requires_grad (bool) – 是否应由 autograd 记录此模块中参数的操作。默认值：True。
返回值: self
返回类型: Module

save_hyperparameters(*args, ignore=None, frame=None, logger=True)¶

将参数保存到 hparams 属性。

参数

args (Any) – 可以是 dict、NameSpace 或 OmegaConf 的单个对象，或来自类 __init__ 的字符串名称或参数
ignore (Union[str, Sequence[str], None]) – 要忽略的来自类 __init__ 的参数名称或参数名称列表
frame (Optional[frame, None]) – 一个 frame 对象。默认值为 None
logger (bool) – 是否将超参数发送到日志记录器。默认值：True

示例：

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # manually assign arguments
...         self.save_hyperparameters('arg1', 'arg3')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class AutomaticArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # equivalent automatic
...         self.save_hyperparameters()
...     def forward(self, *args, **kwargs):
...         ...
>>> model = AutomaticArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg2": abc
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class SingleArgModel(HyperparametersMixin):
...     def __init__(self, params):
...         super().__init__()
...         # manually assign single argument
...         self.save_hyperparameters(params)
...     def forward(self, *args, **kwargs):
...         ...
>>> model = SingleArgModel(Namespace(p1=1, p2='abc', p3=3.14))
>>> model.hparams
"p1": 1
"p2": abc
"p3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # pass argument(s) to ignore as a string or in a list
...         self.save_hyperparameters(ignore='arg2')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

返回类型: None

set_extra_state(state)¶

设置加载的 state_dict 中包含的额外状态。

此函数由 load_state_dict() 调用，用于处理 state_dict 中找到的任何额外状态。如果您需要在模块的 state_dict 中存储额外状态，请实现此函数和相应的 get_extra_state()。

参数: state (dict) – 来自 state_dict 的额外状态
返回类型: None

set_mc_dropout(active)¶

set_predict_parameters(n, num_samples, roll_size, batch_size, n_jobs, predict_likelihood_parameters, mc_dropout)¶

在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置

返回类型: None

set_submodule(target, module)¶

如果存在，则设置由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

(图示为一个 nn.Module A。A 有一个嵌套子模块 net_b，其本身又有两个子模块 net_c 和 linear。net_c 然后有一个子模块 conv。)

要用一个新的子模块 Linear 覆盖 Conv2d，您可以调用 set_submodule("net_b.net_c.conv", nn.Linear(33, 16))。

参数

target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
module (Module) – 用于设置子模块的模块。

Raises

ValueError – 如果目标字符串为空
AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

返回类型

None

setup(stage)¶

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'

示例

class LitModel(...):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        download_data()
        tokenize()

        # don't do this
        self.something = else

    def setup(self, stage):
        data = load_data(...)
        self.l1 = nn.Linear(28, data.num_classes)

返回类型: None

share_memory()¶

参见 torch.Tensor.share_memory_()。

返回类型: ~T

state_dict(*args, destination=None, prefix='', keep_vars=False)¶

返回包含模块完整状态引用的字典。

参数和持久缓冲区（例如，运行平均值）都包含在内。键是相应的参数和缓冲区名称。设置为 None 的参数和缓冲区不包含在内。

注意

返回的对象是浅拷贝。它包含对模块参数和缓冲区的引用。

警告

目前 state_dict() 也按顺序接受 destination、prefix 和 keep_vars 的位置参数。但是，此用法已被弃用，未来版本将强制使用关键字参数。

警告

请避免使用参数 destination，因为它并非为终端用户设计。

参数

destination (dict, optional) – 如果提供，模块的状态将更新到此字典中，并返回相同的对象。否则，将创建一个 OrderedDict 并返回。默认值：None。
prefix (str, optional) – 添加到参数和缓冲区名称的前缀，用于在 state_dict 中构成键。默认值：''。
keep_vars (bool, optional) – 默认情况下，state dict 中返回的 Tensor s 与 autograd 分离。如果设置为 True，将不会进行分离。默认值：False。

返回值

包含模块完整状态的字典

返回类型

dict

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> module.state_dict().keys()
['bias', 'weight']

property strict_loading: bool¶

确定 Lightning 如何使用 .load_state_dict(…, strict=model.strict_loading) 加载此模型。

返回类型: bool

property supports_probabilistic_prediction: bool¶

返回类型: bool

teardown(stage)¶

在 fit（训练 + 验证）、验证、测试或预测结束时调用。

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'
返回类型: None

test_dataloader()¶

指定测试样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

test()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果您不需要测试数据集和 test_step()，则无需实现此方法。

返回类型: Any

test_step(*args, **kwargs)¶

对测试集中的单个批次数据进行操作。在此步骤中，您通常会生成示例或计算任何感兴趣的内容，例如准确率。

参数

batch – 您的数据可迭代对象（通常是 DataLoader）的输出。
batch_idx – 此批次的索引。
dataloader_idx – 生成此批次的数据加载器索引。（仅在使用多个数据加载器时）

返回类型

Union[Tensor, Mapping[str, Any], None]

返回值

Tensor - 损失张量
dict - 字典。可以包含任意键，但必须包含键 'loss'。
None - 跳到下一个批次。

# if you have one test dataloader:
def test_step(self, batch, batch_idx): ...

# if you have multiple test dataloaders:
def test_step(self, batch, batch_idx, dataloader_idx=0): ...

示例

# CASE 1: A single test dataset
def test_step(self, batch, batch_idx):
    x, y = batch

    # implement your own
    out = self(x)
    loss = self.loss(out, y)

    # log 6 example images
    # or generated text... or whatever
    sample_imgs = x[:6]
    grid = torchvision.utils.make_grid(sample_imgs)
    self.logger.experiment.add_image('example_images', grid, 0)

    # calculate acc
    labels_hat = torch.argmax(out, dim=1)
    test_acc = torch.sum(y == labels_hat).item() / (len(y) * 1.0)

    # log the outputs!
    self.log_dict({'test_loss': loss, 'test_acc': test_acc})

如果您传入多个测试数据加载器，test_step() 将有一个额外的参数。我们建议将默认值设置为 0，以便您可以在单个和多个数据加载器之间快速切换。

# CASE 2: multiple test dataloaders
def test_step(self, batch, batch_idx, dataloader_idx=0):
    # dataloader_idx tells you which dataset this is.
    ...

注意

如果您不需要测试，则无需实现此方法。

注意

调用 test_step() 时，模型已设置为评估模式，并且 PyTorch 梯度已禁用。在测试周期结束时，模型会返回训练模式并启用梯度。

to(*args, **kwargs)¶

参见 torch.nn.Module.to()。

返回类型: Self

to_dtype(dtype)¶: 将模块精度（默认为 float32）转换为其他精度。

to_empty(*, device, recurse=True)¶

在不复制存储的情况下，将参数和缓冲区移动到指定设备。

参数

device (torch.device) – 此模块中参数和缓冲区的目标设备。
recurse (bool) – 是否应将子模块的参数和缓冲区递归地移动到指定设备。

返回值

self

返回类型

Module

to_onnx(file_path, input_sample=None, **kwargs)¶

将模型保存为 ONNX 格式。

参数

file_path (Union[str, Path, BytesIO]) – 应保存 onnx 模型的文件路径。
input_sample (Optional[Any, None]) – 用于跟踪的输入。默认值：None（使用 self.example_input_array）
**kwargs – 将传递给 torch.onnx.export 函数。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)

model = SimpleModel()
input_sample = torch.randn(1, 64)
model.to_onnx("export.onnx", input_sample, export_params=True)

返回类型: None

to_torchscript(file_path=None, method='script', example_inputs=None, **kwargs)¶

默认情况下，将整个模型编译为 ScriptModule。如果您想使用追踪，请提供参数 method='trace'，并确保提供了 example_inputs 参数，或者设置了模型的 example_input_array。如果您想自定义脚本化的模块，应覆盖此方法。如果您想返回多个模块，建议使用字典。

参数

file_path (Union[str, Path, None]) – 保存 torchscript 的路径。默认值：None（不保存文件）。
method (Optional[str, None]) – 是使用 TorchScript 的 script 方法还是 trace 方法。默认值：‘script’
example_inputs (Optional[Any, None]) – 当方法设置为“trace”时用于追踪的输入。默认值：None（使用 example_input_array）
**kwargs – 将传递给 torch.jit.script() 或 torch.jit.trace() 函数的附加参数。

注意

需要实现 forward() 方法。
导出的脚本将被设置为评估模式。
建议您安装最新支持版本的 PyTorch 以无限制地使用此功能。另请参见 torch.jit 文档以了解支持的功能。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)))

model = SimpleModel()
model.to_torchscript(file_path="model.pt")

torch.jit.save(model.to_torchscript(
    file_path="model_trace.pt", method='trace', example_inputs=torch.randn(1, 64))
)

返回类型: Union[ScriptModule, dict[str, ScriptModule]]
返回值: 此 LightningModule 作为 torchscript，无论是否定义了 file_path。

toggle_optimizer(optimizer)¶

确保在训练步骤中仅计算当前优化器参数的梯度，以防止在多优化器设置中出现悬空梯度。

它与 untoggle_optimizer() 一起使用，以确保 param_requires_grad_state 正确重置。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要切换的优化器。
返回类型: None

train(mode=True)¶

将模块设置为训练模式。

这仅对某些模块有影响。有关它们在训练/评估模式下的行为详情，例如它们是否受影响（例如 Dropout、BatchNorm 等），请参阅特定模块的文档。

参数: mode (bool) – 是否设置训练模式 (True) 或评估模式 (False)。默认值: True。
返回值: self
返回类型: Module

train_criterion_reduction: Optional[str]¶

train_dataloader()¶

指定训练样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

除非您将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数，否则您返回的数据加载器不会重新加载。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

fit()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any

property trainer: Trainer¶

返回类型: Trainer

training: bool¶

training_step(train_batch, batch_idx)¶

执行训练步骤

返回类型: Tensor

transfer_batch_to_device(batch, device, dataloader_idx)¶

如果您的 DataLoader 返回包装在自定义数据结构中的张量，请覆盖此钩子。

下面列出的数据类型（以及它们的任意嵌套）是开箱即用的支持

torch.Tensor 或任何实现了 .to(…) 的东西
list
dict
tuple

对于其他任何东西，你需要定义数据如何移动到目标设备 (CPU, GPU, TPU, …)。

注意

参数

batch (Any) – 需要转移到新设备的数据批次。
device (device) – PyTorch 中定义的目标设备。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据在新设备上的引用。

示例

def transfer_batch_to_device(self, batch, device, dataloader_idx):
    if isinstance(batch, CustomBatch):
        # move all tensors in your custom data structure to the device
        batch.samples = batch.samples.to(device)
        batch.targets = batch.targets.to(device)
    elif dataloader_idx == 0:
        # skip device transfer for the first dataloader or anything you wish
        pass
    else:
        batch = super().transfer_batch_to_device(batch, device, dataloader_idx)
    return batch

另请参阅

move_data_to_device()
apply_to_collection()

type(dst_type)¶

参见 torch.nn.Module.type()。

返回类型: Self

unfreeze()¶

解冻所有参数以进行训练。

model = MyLightningModule(...)
model.unfreeze()

返回类型: None

untoggle_optimizer(optimizer)¶

重置使用 toggle_optimizer() 切换的所需梯度的状态。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要取消切换的优化器。
返回类型: None

val_criterion_reduction: Optional[str]¶

val_dataloader()¶

指定验证样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

除非您将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数，否则您返回的数据加载器不会重新加载。

建议所有数据下载和准备都在 prepare_data() 中进行。

fit()
validate()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果您不需要验证数据集和 validation_step()，则无需实现此方法。

返回类型: Any

validation_step(val_batch, batch_idx)¶

执行验证步骤

返回类型: Tensor

xpu(device=None)¶

将所有模型参数和缓冲区移动到 XPU。

这也会使得相关的参数和缓冲区成为不同的对象。因此，如果模块将在 XPU 上运行并进行优化，则应该在构建优化器之前调用它。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

zero_grad(set_to_none=True)¶

重置所有模型参数的梯度。

请参阅 torch.optim.Optimizer 下的类似函数，了解更多背景信息。

参数: set_to_none (bool) – 不设置为零，而是将梯度设置为 None。请参阅 torch.optim.Optimizer.zero_grad() 了解详情。
返回类型: None

class darts.models.forecasting.pl_forecasting_module.PLSplitCovariatesModule(input_chunk_length, output_chunk_length, output_chunk_shift=0, train_sample_shape=None, loss_fn=MSELoss(), torch_metrics=None, likelihood=None, optimizer_cls=<class 'torch.optim.adam.Adam'>, optimizer_kwargs=None, lr_scheduler_cls=None, lr_scheduler_kwargs=None, use_reversible_instance_norm=False)[source]¶

基类：PLForecastingModule, ABC

基于 PyTorch Lightning 的预测模块。

此类旨在被继承以创建新的基于 PyTorch Lightning 的预测模块。子类化此类时，请确保添加具有以下签名的方

PLForecastingModule.__init__()

PLForecastingModule.forward()

PLForecastingModule._process_input_batch()

PLForecastingModule._produce_train_output()

PLForecastingModule._get_batch_prediction()

在子类 MyModel 的 __init__() 函数中调用 super(MyModel, self).__init__(**kwargs)，其中 kwargs 是 PLForecastingModule 的参数。

参数

input_chunk_length (int) – 模型输入的时间步长数量（每块）。适用于目标序列以及过去和/或未来协变量（如果模型支持）。
output_chunk_length (int) – 内部模型一次预测（每块）的时间步长数量。此外，未来协变量的未来值用作模型输入的数量（如果模型支持未来协变量）。它与 predict() 中使用的预测视野 n 不同，后者是使用一次性预测或自回归预测生成的所需预测点数。设置 n <= output_chunk_length 可防止自回归。当协变量未能充分延伸到未来时，这非常有用，或者为了禁止模型使用过去和/或未来协变量的未来值进行预测（取决于模型的协变量支持）。
train_sample_shape (Optional[tuple, None]) – 模型的输入形状，用于在不调用 fit_from_dataset 的情况下实例化模型，并对用于重新训练或预测的新训练/推理数据集执行健全性检查。
loss_fn (_Loss) – 用于训练的 PyTorch 损失函数。如果指定了 likelihood 参数，则此参数对于概率模型将被忽略。默认值：torch.nn.MSELoss()。
torch_metrics (Union[Metric, MetricCollection, None]) – 用于评估的 torch 指标或 MetricCollection。可在 https://torchmetrics.readthedocs.io/en/latest/ 找到可用指标的完整列表。默认值：None。
likelihood (Optional[TorchLikelihood, None]) – Darts 的 Likelihood 模型之一，用于概率预测。默认值：None。
optimizer_cls (Optimizer) – 要使用的 PyTorch 优化器类。默认值：torch.optim.Adam。
optimizer_kwargs (Optional[dict, None]) – 可选地，PyTorch 优化器的一些关键字参数（例如，{'lr': 1e-3} 用于指定学习率）。否则将使用选定的 optimizer_cls 的默认值。默认值：None。
lr_scheduler_cls (Optional[_LRScheduler, None]) – 可选地，要使用的 PyTorch 学习率调度器类。指定 None 对应于使用恒定学习率。默认值：None。
lr_scheduler_kwargs (Optional[dict, None]) – 可选地，PyTorch 学习率调度器的一些关键字参数。默认值：None。
use_reversible_instance_norm (bool) – 是否使用可逆实例归一化 RINorm 来对抗分布偏移，如 [1] 所示。它仅应用于目标序列的特征，而不应用于协变量。

参考

1: T. Kim et al. “Reversible Instance Normalization for Accurate Time-Series Forecasting against Distribution Shift”, https://openreview.net/forum?id=cGDAkQo1C0p

属性

`automatic_optimization`	如果设置为 `False`，则您负责调用 `.backward()`, `.step()`, `.zero_grad()`。
`current_epoch`	`Trainer` 中的当前 epoch，如果未附加则为 0。
`device_mesh`	`ModelParallelStrategy` 等策略将创建设备网格，可在 `configure_model()` 钩子中访问该网格以并行化 LightningModule。
`example_input_array`	示例输入数组指定了模块在 `forward()` 方法中可以接收的内容。
`global_rank`	当前进程在所有节点和设备中的索引。
`global_step`	所有 epoch 中看到的总训练批次。
`hparams`	使用 `save_hyperparameters()` 保存的超参数集合。
`hparams_initial`	使用 `save_hyperparameters()` 保存的超参数集合。
`local_rank`	当前进程在单个节点内的索引。
`logger`	指向 Trainer 中 logger 对象的引用。
`loggers`	指向 Trainer 中 loggers 列表的引用。
`on_gpu`	如果此模型当前位于 GPU 上，则返回 `True`。
`output_chunk_length`	模型一次预测的时间步长数量。
`strict_loading`	确定 Lightning 如何使用 .load_state_dict(..., strict=model.strict_loading) 加载此模型。

device
dtype
epochs_trained
fabric
supports_probabilistic_prediction
trainer

方法

`add_module`(名称, 模块)	向当前模块添加子模块。
`all_gather`(数据[, 组, 同步梯度])	从多个进程聚合张量或张量集合。
`apply`(函数)	将 `fn` 递归地应用于每个子模块（由 `.children()` 返回）以及自身。
`backward`(损失, 参数, *关键字参数)	调用此方法对 `training_step()` 中返回的损失执行反向传播。
`bfloat16`()	将所有浮点参数和缓冲区转换为 `bfloat16` 数据类型。
`buffers`([递归])	返回模块缓冲区的迭代器。
`children`()	返回直接子模块的迭代器。
`clip_gradients`(优化器[, ...])	内部处理梯度裁剪。
`compile`(参数, *关键字参数)	使用 `torch.compile()` 编译此模块的前向传播。
`configure_callbacks`()	配置模型特定的回调。
`configure_gradient_clipping`(优化器[, ...])	对优化器参数执行梯度裁剪。
`configure_model`()	在策略和精度感知上下文中创建模块的钩子。
`configure_optimizers`()	配置用于模型优化的优化器和学习率调度器。
`configure_sharded_model`()	已弃用。
`configure_torch_metrics`(torch_metrics)	处理 torch_metrics 参数。
`cpu`()	参见 `torch.nn.Module.cpu()`。
`cuda`([设备])	将所有模型参数和缓冲区移动到 GPU。
`double`()	参见 `torch.nn.Module.double()`。
`eval`()	将模块设置为评估模式。
`extra_repr`()	返回模块的额外表示。
`float`()	参见 `torch.nn.Module.float()`。
`forward`(参数, *关键字参数)	与 `torch.nn.Module.forward()` 相同。
`freeze`()	冻结所有参数以进行推理。
`get_buffer`(目标)	如果存在，则返回由 `target` 指定的缓冲区，否则抛出错误。
`get_extra_state`()	返回要包含在模块 state_dict 中的任何额外状态。
`get_parameter`(目标)	如果存在，则返回由 `target` 指定的参数，否则抛出错误。
`get_submodule`(目标)	如果存在，则返回由 `target` 指定的子模块，否则抛出错误。
`half`()	参见 `torch.nn.Module.half()`。
`ipu`([设备])	将所有模型参数和缓冲区移动到 IPU。
`load_from_checkpoint`(检查点路径[, ...])	从检查点加载模型的主要方式。
`load_state_dict`(状态字典[, 严格, 分配])	将参数和缓冲区从 `state_dict` 复制到此模块及其后代。
`log`(名称, 值[, 进度条, 日志记录器, ...])	记录键值对。
`log_dict`(字典[, 进度条, 日志记录器, ...])	一次记录字典中的值。
`lr_scheduler_step`(调度器, 指标)	覆盖此方法以调整 `Trainer` 调用每个调度器的默认方式。
`lr_schedulers`()	返回训练期间使用的学习率调度器。
`manual_backward`(损失, 参数, *关键字参数)	手动执行优化时，可直接从您的 `training_step()` 中调用此方法。
`modules`()	返回网络中所有模块的迭代器。
`mtia`([设备])	将所有模型参数和缓冲区移动到 MTIA。
`named_buffers`([前缀, 递归, ...])	返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。
`named_children`()	返回直接子模块的迭代器，同时产生模块名称和模块本身。
`named_modules`([备忘录, 前缀, 移除重复])	返回网络中所有模块的迭代器，同时产生模块名称和模块本身。
`named_parameters`([前缀, 递归, ...])	返回模块参数的迭代器，同时产生参数名称和参数本身。
`on_after_backward`()	在 `loss.backward()` 之后且在优化器步进之前调用。
`on_after_batch_transfer`(批次, 数据加载器索引)	覆盖此方法以在批次转移到设备后修改或应用批次增强。
`on_before_backward`(损失)	在 `loss.backward()` 之前调用。
`on_before_batch_transfer`(批次, 数据加载器索引)	覆盖此方法以在批次转移到设备之前修改或应用批次增强。
`on_before_optimizer_step`(优化器)	在 `optimizer.step()` 之前调用。
`on_before_zero_grad`(优化器)	在 `training_step()` 之后且在 `optimizer.zero_grad()` 之前调用。
`on_fit_end`()	在 fit 的最后调用。
`on_fit_start`()	在 fit 的最开始调用。
`on_load_checkpoint`(检查点)	由 Lightning 调用以恢复您的模型。
`on_predict_batch_end`(输出, 批次, 批次索引)	在预测循环中批次之后调用。
`on_predict_batch_start`(批次, 批次索引[, ...])	在预测循环中该批次发生任何事情之前调用。
`on_predict_end`()	在预测结束时调用。
`on_predict_epoch_end`()	在预测结束时调用。
`on_predict_epoch_start`()	在预测开始时调用。
`on_predict_model_eval`()	预测循环开始时调用。
`on_predict_start`()	在预测开始时调用。
`on_save_checkpoint`(检查点)	Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。
`on_test_batch_end`(输出, 批次, 批次索引)	在测试循环中批次之后调用。
`on_test_batch_start`(批次, 批次索引[, ...])	在测试循环中该批次发生任何事情之前调用。
`on_test_end`()	在测试结束时调用。
`on_test_epoch_end`()	在测试循环中 epoch 的最后调用。
`on_test_epoch_start`()	在测试循环中 epoch 的最开始调用。
`on_test_model_eval`()	测试循环开始时调用。
`on_test_model_train`()	测试循环结束时调用。
`on_test_start`()	在测试开始时调用。
`on_train_batch_end`(输出, 批次, 批次索引)	在训练循环中批次之后调用。
`on_train_batch_start`(批次, 批次索引)	在训练循环中该批次发生任何事情之前调用。
`on_train_end`()	在训练结束、logger 实验关闭之前调用。
`on_train_epoch_end`()	在训练循环中 epoch 的最后调用。
`on_train_epoch_start`()	在训练循环中 epoch 的最开始调用。
`on_train_start`()	在健全性检查之后、训练开始时调用。
`on_validation_batch_end`(输出, 批次, ...)	在验证循环中批次之后调用。
`on_validation_batch_start`(批次, 批次索引)	在验证循环中该批次发生任何事情之前调用。
`on_validation_end`()	在验证结束时调用。
`on_validation_epoch_end`()	在验证循环中 epoch 的最后调用。
`on_validation_epoch_start`()	在验证循环中 epoch 的最开始调用。
`on_validation_model_eval`()	验证循环开始时调用。
`on_validation_model_train`()	验证循环结束时调用。
`on_validation_model_zero_grad`()	由训练循环调用，在进入验证循环之前释放梯度。
`on_validation_start`()	在验证开始时调用。
`optimizer_step`(周期, 批次索引, 优化器)	覆盖此方法以调整 `Trainer` 调用优化器的默认方式。
`optimizer_zero_grad`(周期, 批次索引, 优化器)	覆盖此方法以更改 `optimizer.zero_grad()` 的默认行为。
`optimizers`([使用pl优化器])	返回训练期间使用的优化器。
`parameters`([递归])	返回模块参数的迭代器。
`predict_dataloader`()	指定预测样本的可迭代对象或可迭代对象集合。
`predict_step`(批次, 批次索引[, 数据加载器索引])	执行预测步骤
`prepare_data`()	使用此方法下载和准备数据。
`print`(参数, *关键字参数)	仅从进程 0 打印。
`register_backward_hook`(钩子)	在模块上注册后向钩子。
`register_buffer`(名称, 张量[, 持久])	向模块添加缓冲区。
`register_forward_hook`(钩子, *[, 前置, ...])	在模块上注册前向钩子。
`register_forward_pre_hook`(钩子, *[, ...])	在模块上注册前向预钩子。
`register_full_backward_hook`(钩子[, 前置])	在模块上注册后向钩子。
`register_full_backward_pre_hook`(钩子[, 前置])	在模块上注册后向预钩子。
`register_load_state_dict_post_hook`(钩子)	注册一个后钩子，该钩子在模块的 `load_state_dict()` 被调用后运行。
`register_load_state_dict_pre_hook`(钩子)	注册一个预钩子，该钩子在模块的 `load_state_dict()` 被调用前运行。
`register_module`(名称, 模块)	`add_module()` 的别名。
`register_parameter`(名称, 参数)	向模块添加参数。
`register_state_dict_post_hook`(钩子)	为 `state_dict()` 方法注册一个后钩子。
`register_state_dict_pre_hook`(钩子)	为 `state_dict()` 方法注册一个预钩子。
`requires_grad_`([需要梯度])	更改此模块中是否应记录参数上的自动梯度操作。
`save_hyperparameters`(*参数[, 忽略, 框架, ...])	将参数保存到 `hparams` 属性。
`set_extra_state`(状态)	设置加载的 state_dict 中包含的额外状态。
`set_predict_parameters`(n, 样本数, ...)	在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置
`set_submodule`(目标, 模块)	如果存在，则设置由 `target` 指定的子模块，否则抛出错误。
`setup`(阶段)	在 fit（训练 + 验证）、验证、测试或预测开始时调用。
`share_memory`()	参见 `torch.Tensor.share_memory_()`。
`state_dict`(*参数[, 目标, 前缀, ...])	返回包含模块完整状态引用的字典。
`teardown`(阶段)	在 fit（训练 + 验证）、验证、测试或预测结束时调用。
`test_dataloader`()	指定测试样本的可迭代对象或可迭代对象集合。
`test_step`(参数, *关键字参数)	处理测试集中的单个批次数据。
`to`(参数, *关键字参数)	参见 `torch.nn.Module.to()`。
`to_dtype`(数据类型)	将模块精度（默认为 float32）转换为其他精度。
`to_empty`(*, 设备[, 递归])	在不复制存储的情况下，将参数和缓冲区移动到指定设备。
`to_onnx`(文件路径[, 输入样本])	将模型保存为 ONNX 格式。
`to_torchscript`([文件路径, 方法, ...])	默认情况下，将整个模型编译为 `ScriptModule`。
`toggle_optimizer`(优化器)	确保在训练步骤中仅计算当前优化器参数的梯度，以防止多优化器设置中出现悬空梯度。
`train`([模式])	将模块设置为训练模式。
`train_dataloader`()	指定训练样本的可迭代对象或可迭代对象集合。
`training_step`(训练批次, 批次索引)	执行训练步骤
`transfer_batch_to_device`(批次, 设备, ...)	如果您的 `DataLoader` 返回包装在自定义数据结构中的张量，请覆盖此钩子。
`type`(目标类型)	参见 `torch.nn.Module.type()`。
`unfreeze`()	解冻所有参数以进行训练。
`untoggle_optimizer`(优化器)	重置通过 `toggle_optimizer()` 切换的所需梯度状态。
`val_dataloader`()	指定验证样本的可迭代对象或可迭代对象集合。
`validation_step`(验证批次, 批次索引)	执行验证步骤
`xpu`([设备])	将所有模型参数和缓冲区移动到 XPU。
`zero_grad`([设置为无])	重置所有模型参数的梯度。

__call__
set_mc_dropout

CHECKPOINT_HYPER_PARAMS_KEY = 'hyper_parameters'¶

CHECKPOINT_HYPER_PARAMS_NAME = 'hparams_name'¶

CHECKPOINT_HYPER_PARAMS_TYPE = 'hparams_type'¶

T_destination¶: TypeVar(‘T_destination’, bound=Dict[str, Any]) 的别名

add_module(name, module)¶

向当前模块添加子模块。

模块可以使用给定的名称作为属性访问。

参数

name (str) – 子模块的名称。可以使用此名称从当前模块访问子模块
module (Module) – 要添加到模块的子模块。

返回类型

None

all_gather(data, group=None, sync_grads=False)¶

从多个进程聚合张量或张量集合。

此方法需要在所有进程上调用，并且张量需要在所有进程上具有相同的形状，否则您的程序将永远暂停。

参数

data (Union[Tensor, dict, list, tuple]) – int、float、形状为 (batch, …) 的张量，或其（可能嵌套的）集合。
group (Optional[Any, None]) – 要从中收集结果的进程组。默认为所有进程 (world)。
sync_grads (bool) – 允许用户同步 all_gather 操作的梯度的标志。

返回类型

Union[Tensor, dict, list, tuple]

返回值

形状为 (world_size, batch, …) 的张量，如果输入是集合，则输出也将是包含此形状张量的集合。对于 world_size 为 1 的特殊情况，不会向张量添加额外维度。

allow_zero_length_dataloader_with_multiple_devices: bool¶

apply(fn)¶

将 fn 递归地应用于每个子模块（由 .children() 返回）以及自身。

典型用法包括初始化模型的参数（另见 nn-init-doc）。

参数: fn (Module -> None) – 要应用于每个子模块的函数
返回值: self
返回类型: Module

示例

>>> @torch.no_grad()
>>> def init_weights(m):
>>>     print(m)
>>>     if type(m) == nn.Linear:
>>>         m.weight.fill_(1.0)
>>>         print(m.weight)
>>> net = nn.Sequential(nn.Linear(2, 2), nn.Linear(2, 2))
>>> net.apply(init_weights)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Linear(in_features=2, out_features=2, bias=True)
Parameter containing:
tensor([[1., 1.],
        [1., 1.]], requires_grad=True)
Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)

property automatic_optimization: bool¶

如果设置为 False，则您负责调用 .backward(), .step(), .zero_grad()。

返回类型: bool

backward(loss, *args, **kwargs)¶

调用此钩子对 training_step() 中返回的损失执行反向传播。如果您需要自己的实现，请覆盖此钩子。

参数: loss (Tensor) – training_step() 返回的损失张量。如果使用梯度累积，这里的损失是归一化后的值（按 1 / 累积步数缩放）。

示例

def backward(self, loss):
    loss.backward()

返回类型: None

bfloat16()¶

将所有浮点参数和缓冲区转换为 bfloat16 数据类型。

注意

此方法会修改模块本身。

返回值: self
返回类型: Module

buffers(recurse=True)¶

返回模块缓冲区的迭代器。

参数: recurse (bool) – 如果为 True，则产生此模块和所有子模块的缓冲区。否则，仅产生此模块的直接成员缓冲区。
Yields: torch.Tensor – 模块缓冲区

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for buf in model.buffers():
>>>     print(type(buf), buf.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Tensor]

call_super_init: bool = False¶

children()¶

返回直接子模块的迭代器。

Yields: Module – 子模块
返回类型: Iterator[Module]

clip_gradients(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

内部处理梯度裁剪。

注意

不要覆盖此方法。如果要自定义梯度裁剪，请考虑使用 configure_gradient_clipping() 方法。
对于手动优化 (self.automatic_optimization = False)，如果要使用梯度裁剪，请考虑在训练步骤中手动调用 self.clip_gradients(opt, gradient_clip_val=0.5, gradient_clip_algorithm="norm")。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 用于裁剪梯度的值。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。传递 gradient_clip_algorithm="value" 按值裁剪，传递 gradient_clip_algorithm="norm" 按范数裁剪。

返回类型

None

compile(*args, **kwargs)¶

使用 torch.compile() 编译此模块的前向传播。

此模块的 __call__ 方法将被编译，并且所有参数将原样传递给 torch.compile()。

有关此函数的参数详细信息，请参见 torch.compile()。

configure_callbacks()¶

返回类型: Union[Sequence[Callback], Callback]
返回值: 一个或多个回调，它们将扩展 Trainer 中的回调列表。

示例

def configure_callbacks(self):
    early_stop = EarlyStopping(monitor="val_acc", mode="max")
    checkpoint = ModelCheckpoint(monitor="val_loss")
    return [early_stop, checkpoint]

configure_gradient_clipping(optimizer, gradient_clip_val=None, gradient_clip_algorithm=None)¶

对优化器参数执行梯度裁剪。在 optimizer_step() 之前调用。

参数

optimizer (Optimizer) – 正在使用的当前优化器。
gradient_clip_val (Union[int, float, None]) – 用于裁剪梯度的值。默认情况下，Trainer 中传递的值将在此处可用。
gradient_clip_algorithm (Optional[str, None]) – 要使用的梯度裁剪算法。默认情况下，Trainer 中传入的值将在此处可用。

示例

def configure_gradient_clipping(self, optimizer, gradient_clip_val, gradient_clip_algorithm):
    # Implement your own custom logic to clip gradients
    # You can call `self.clip_gradients` with your settings:
    self.clip_gradients(
        optimizer,
        gradient_clip_val=gradient_clip_val,
        gradient_clip_algorithm=gradient_clip_algorithm
    )

返回类型: None

configure_model()¶

在策略和精度感知上下文中创建模块的钩子。

此钩子在同一进程的 fit/val/test/predict 各阶段都会被调用，因此请确保此钩子的实现是幂等的，即在第一次调用此钩子后，后续调用应该是空操作。

返回类型: None

configure_optimizers()¶: 配置用于模型优化的优化器和学习率调度器。

configure_sharded_model()¶

已弃用。

请改用 configure_model()。

返回类型: None

static configure_torch_metrics(torch_metrics)¶

处理 torch_metrics 参数。

返回类型: MetricCollection

cpu()¶

参见 torch.nn.Module.cpu()。

返回类型: Self

cuda(device=None)¶

参数: device (Union[int, device, None]) – 如果指定，所有参数将被复制到该设备。如果为 None，将使用当前的 CUDA 设备索引。
返回值: self
返回类型: Module

property current_epoch: int¶

Trainer 中的当前 epoch，如果未附加则为 0。

返回类型: int

property device: device¶

返回类型: device

property device_mesh: Optional[DeviceMesh]¶

ModelParallelStrategy 等策略将创建设备网格，可在 configure_model() 钩子中访问该网格以并行化 LightningModule。

返回类型: Optional[ForwardRef, None]

double()¶

参见 torch.nn.Module.double()。

返回类型: Self

property dtype: Union[str, dtype]¶

返回类型: Union[str, dtype]

dump_patches: bool = False¶

property epochs_trained¶

eval()¶

将模块设置为评估模式。

这仅对某些模块有效。有关特定模块在训练/评估模式下的行为详情，即它们是否受到影响，请参阅其文档，例如 Dropout、BatchNorm 等。

这等同于 self.train(False)。

有关 .eval() 与可能与其混淆的几个类似机制之间的比较，请参见 locally-disable-grad-doc。

返回值: self
返回类型: Module

property example_input_array: Optional[Union[Tensor, tuple, dict]]¶

示例输入数组指定了模块在 forward() 方法中可以接受的内容。返回类型解释如下：

单个张量：假定模型接受一个参数，即 model.forward(model.example_input_array)
元组：输入数组应被解释为位置参数序列，即 model.forward(*model.example_input_array)
字典：输入数组表示命名关键字参数，即 model.forward(**model.example_input_array)

返回类型: Union[Tensor, tuple, dict, None]

extra_repr()¶

返回模块的额外表示。

要打印自定义的额外信息，您应该在自己的模块中重新实现此方法。单行和多行字符串都可接受。

返回类型: str

property fabric: Optional[Fabric]¶

返回类型: Optional[Fabric, None]

float()¶

参见 torch.nn.Module.float()。

返回类型: Self

abstract forward(*args, **kwargs)¶

与 torch.nn.Module.forward() 相同。

参数

*args – 您决定传递给 forward 方法的任何内容。
**kwargs – 关键字参数也是可以的。

返回类型

Any

返回值

您的模型的输出

freeze()¶

冻结所有参数以进行推理。

示例

model = MyLightningModule(...)
model.freeze()

返回类型: None

get_buffer(target)¶

如果存在，则返回由 target 指定的缓冲区，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的缓冲区的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的缓冲区
返回类型: torch.Tensor
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是缓冲区

get_extra_state()¶

返回要包含在模块 state_dict 中的任何额外状态。

如果您需要存储额外状态，请为您的模块实现此函数以及相应的 set_extra_state() 函数。此函数在构建模块的 state_dict() 时调用。

返回值: 要存储在模块 state_dict 中的任何额外状态
返回类型: object

get_parameter(target)¶

如果存在，则返回由 target 指定的参数，否则抛出错误。

有关此方法功能的更详细解释以及如何正确指定 target，请参见 get_submodule 的文档字符串。

参数: target (str) – 要查找的参数的完全限定字符串名称。（有关如何指定完全限定字符串，请参见 get_submodule。）
返回值: target 引用的参数
返回类型: torch.nn.Parameter
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Parameter

get_submodule(target)¶

如果存在，则返回由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

（图表显示了一个 nn.Module A。 A 有一个嵌套子模块 net_b，它本身有两个子模块 net_c 和 linear。 net_c 还有一个子模块 conv。）

要检查是否存在 linear 子模块，我们可以调用 get_submodule("net_b.linear")。要检查是否存在 conv 子模块，我们可以调用 get_submodule("net_b.net_c.conv")。

参数: target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
返回值: target 引用的子模块
返回类型: torch.nn.Module
Raises: AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

property global_rank: int¶

当前进程在所有节点和设备中的索引。

返回类型: int

property global_step: int¶

所有 epoch 中看到的总训练批次。

如果未附加 Trainer，此属性值为 0。

返回类型: int

half()¶

参见 torch.nn.Module.half()。

返回类型: Self

property hparams: Union[AttributeDict, MutableMapping]¶

使用 save_hyperparameters() 保存的超参数集合。用户可以修改。对于初始超参数的冻结集合，请使用 hparams_initial。

返回类型: Union[AttributeDict, MutableMapping]
返回值: 可变的超参数字典

property hparams_initial: AttributeDict¶

使用 save_hyperparameters() 保存的超参数集合。这些内容是只读的。可以通过 hparams 进行手动更新保存的超参数。

返回值: 不可变初始超参数
返回类型: AttributeDict

ipu(device=None)¶

将所有模型参数和缓冲区移动到 IPU。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 IPU 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

load_from_checkpoint(checkpoint_path, map_location=None, hparams_file=None, strict=None, **kwargs)¶

从检查点加载模型的主要方式。当 Lightning 保存检查点时，它会将传递给 __init__ 的参数存储在检查点中的 "hyper_parameters" 下。

通过 **kwargs 指定的任何参数将覆盖存储在 "hyper_parameters" 中的参数。

参数

checkpoint_path (Union[str, Path, IO]) – 检查点路径。这也可以是 URL 或文件类对象
map_location (Union[device, str, int, Callable[[UntypedStorage, str], Optional[UntypedStorage, None]], dict[Union[device, str, int], Union[device, str, int]], None]) – 如果您的检查点保存的是 GPU 模型，而您现在在 CPU 或不同数量的 GPU 上加载，请使用此参数映射到新的配置。其行为与 torch.load() 中相同。
hparams_file (Union[str, Path, None]) –
可选的 .yaml 或 .csv 文件路径，其结构如下例所示
```
drop_prob: 0.2
dataloader:
    batch_size: 32
```
您很可能不需要此参数，因为 Lightning 总是会将超参数保存到检查点中。但是，如果您的检查点权重没有保存超参数，请使用此方法传入一个包含您希望使用的超参数的 .yaml 文件。这些超参数将被转换为 dict 并传递给您的 LightningModule 使用。

如果您的模型的 hparams 参数是 Namespace 并且 .yaml 文件具有分层结构，您需要重构您的模型以将 hparams 视为 dict。
strict (Optional[bool, None]) – 是否严格强制 checkpoint_path 中的键与此模块的 state dict 返回的键完全匹配。默认为 True，除非设置了 LightningModule.strict_loading，在这种情况下，它将默认为 LightningModule.strict_loading 的值。
**kwargs – 初始化模型所需的任何额外关键字参数。也可以用于覆盖已保存的超参数值。

返回类型

Self

返回值

加载了权重和超参数（如果可用）的 LightningModule 实例。

注意

load_from_checkpoint 是一个类方法。您应该使用 LightningModule 类来调用它，而不是 LightningModule 实例，否则将引发 TypeError。

注意

示例

# load weights without mapping ...
model = MyLightningModule.load_from_checkpoint('path/to/checkpoint.ckpt')

# or load weights mapping all weights from GPU 1 to GPU 0 ...
map_location = {'cuda:1':'cuda:0'}
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    map_location=map_location
)

# or load weights and hyperparameters from separate files.
model = MyLightningModule.load_from_checkpoint(
    'path/to/checkpoint.ckpt',
    hparams_file='/path/to/hparams_file.yaml'
)

# override some of the params with new values
model = MyLightningModule.load_from_checkpoint(
    PATH,
    num_layers=128,
    pretrained_ckpt_path=NEW_PATH,
)

# predict
pretrained_model.eval()
pretrained_model.freeze()
y_hat = pretrained_model(x)

load_state_dict(state_dict, strict=True, assign=False)¶

将参数和缓冲区从 state_dict 复制到此模块及其后代。

如果 strict 为 True，则 state_dict 的键必须与此模块的 state_dict() 函数返回的键完全匹配。

警告

如果 assign 为 True，则优化器必须在调用 load_state_dict 之后创建，除非 get_swap_module_params_on_conversion() 为 True。

参数

state_dict (dict) – 包含参数和持久缓冲区的字典。
strict (bool, optional) – 是否严格强制要求 state_dict 中的键与此模块的 state_dict() 函数返回的键匹配。默认值：True
assign (bool, optional) – 设置为 False 时，保留当前模块中张量的属性，而设置为 True 时，保留 state dict 中张量的属性。唯一的例外是 Default: ``False` 的 requires_grad 字段

返回值

missing_keys 是一个字符串列表，包含此模块需要但
提供的 state_dict 中缺失的键。
unexpected_keys 是一个字符串列表，包含此模块
不预期但提供的 state_dict 中存在的键。

返回类型

包含 missing_keys 和 unexpected_keys 字段的 NamedTuple

注意

如果参数或缓冲区被注册为 None，并且其对应的键存在于 state_dict 中，load_state_dict() 将引发 RuntimeError。

property local_rank: int¶

当前进程在单个节点内的索引。

返回类型: int

记录键值对。

示例

self.log('train_loss', loss)

每个钩子的默认行为在此处有文档说明：extensions/logging:Automatic Logging。

参数

name (str) – 要记录的键。如果使用 DDP 或任何其他分布式策略，则必须在所有进程中保持一致。
value (Union[Metric, Tensor, int, float]) – 要记录的值。可以是 float、Tensor 或 Metric。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图。
sync_dist (bool) – 如果为 True，则在设备之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 DDP 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个 dataloader 时）。如果 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch_size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
metric_attribute (Optional[str, None]) – 为了恢复指标状态，Lightning 需要您的模型中 torchmetrics.Metric 的引用。如果它是一个模型属性，则会自动找到。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

一次记录字典中的值。

示例

values = {'loss': loss, 'acc': acc, ..., 'metric_n': metric_n}
self.log_dict(values)

参数

dictionary (Union[Mapping[str, Union[Metric, Tensor, int, float]], MetricCollection]) – 键值对。如果使用 DDP 或任何其他分布式策略，所有进程中的键必须相同。值可以是 float、Tensor、Metric 或 MetricCollection。
prog_bar (bool) – 如果为 True，则记录到进度条。
logger (Optional[bool, None]) – 如果为 True，则记录到 logger。
on_step (Optional[bool, None]) – 如果为 True，则在此步记录。None 会自动记录 training_step，但不记录 validation/test_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
on_epoch (Optional[bool, None]) – 如果为 True，则记录 epoch 累积指标。None 会自动记录 val/test step，但不记录 training_step。默认值由钩子确定。详情请参见 extensions/logging:Automatic Logging。
reduce_fx (Union[str, Callable]) – 用于 epoch 结束时对步长值进行归约的函数。默认为 torch.mean()。
enable_graph (bool) – 如果为 True，则不会自动分离计算图
sync_dist (bool) – 如果为 True，则在 GPU/TPU 之间归约指标。请谨慎使用，因为这可能会导致显著的通信开销。
sync_dist_group (Optional[Any, None]) – 用于跨设备同步的 ddp 组。
add_dataloader_idx (bool) – 如果为 True，则将当前 dataloader 的索引附加到名称中（当使用多个时）。如果为 False，用户需要为每个 dataloader 提供唯一的名称，以避免混淆值。
batch_size (Optional[int, None]) – 当前 batch size。此参数将直接从加载的 batch 中推断，但对于某些数据结构，您可能需要显式提供它。
rank_zero_only (bool) – 告诉 Lightning 您是从每个进程调用 self.log（默认）还是仅从 rank 0 调用。如果为 True，您将无法在回调函数（例如，早停）中使用此指标作为监视器。警告：不当使用可能导致死锁！更多详情请参见 Advanced Logging。

返回类型

None

property logger: Optional[Union[Logger, Logger]]¶

指向 Trainer 中 logger 对象的引用。

返回类型: Union[Logger, Logger, None]

property loggers: Union[list[pytorch_lightning.loggers.logger.Logger], list[lightning_fabric.loggers.logger.Logger]]¶

指向 Trainer 中 loggers 列表的引用。

返回类型: Union[list[Logger], list[Logger]]

lr_scheduler_step(scheduler, metric)¶

覆盖此方法以调整 Trainer 调用每个调度器的默认方式。默认情况下，Lightning 根据每个调度器的 interval 调用 step()，如示例所示。

参数

scheduler (Union[LRScheduler, ReduceLROnPlateau]) – 学习率调度器。
metric (Optional[Any, None]) – 用于像 ReduceLROnPlateau 这样的调度器的监视器值。

示例

# DEFAULT
def lr_scheduler_step(self, scheduler, metric):
    if metric is None:
        scheduler.step()
    else:
        scheduler.step(metric)

# Alternative way to update schedulers if it requires an epoch value
def lr_scheduler_step(self, scheduler, metric):
    scheduler.step(epoch=self.current_epoch)

返回类型: None

lr_schedulers()¶

返回训练期间使用的学习率调度器。对于手动优化很有用。

返回类型: Union[None, list[Union[LRScheduler, ReduceLROnPlateau]], LRScheduler, ReduceLROnPlateau]
返回值: 单个调度器，或者在存在多个调度器时返回一个列表，如果在 configure_optimizers() 中没有返回调度器，则返回 None。

manual_backward(loss, *args, **kwargs)¶

手动执行优化时，直接在您的 training_step() 中调用此函数。通过使用此函数，Lightning 可以确保在使用混合精度时应用所有正确的缩放。

更多示例请参见 manual optimization。

示例

def training_step(...):
    opt = self.optimizers()
    loss = ...
    opt.zero_grad()
    # automatically applies scaling, etc...
    self.manual_backward(loss)
    opt.step()

参数

loss (Tensor) – 用于计算梯度的张量。必须附加计算图。
*args – 要转发给 backward() 的额外位置参数
**kwargs – 要转发给 backward() 的额外关键字参数

返回类型

None

modules()¶

返回网络中所有模块的迭代器。

Yields: Module – 网络中的一个模块

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.modules()):
...     print(idx, '->', m)

0 -> Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
)
1 -> Linear(in_features=2, out_features=2, bias=True)

返回类型: Iterator[Module]

mtia(device=None)¶

将所有模型参数和缓冲区移动到 MTIA。

这也会使相关的参数和缓冲区成为不同的对象。因此，如果模块将在 MTIA 上进行优化，则应在构建优化器之前调用此方法。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

named_buffers(prefix='', recurse=True, remove_duplicate=True)¶

返回模块缓冲区的迭代器，同时产生缓冲区名称和缓冲区本身。

参数

prefix (str) – 要添加到所有缓冲区名称前的字符串前缀。
recurse (bool, optional) – 如果为 True，则生成此模块及其所有子模块的缓冲区。否则，仅生成此模块的直接成员缓冲区。默认为 True。
remove_duplicate (bool, optional) – 是否移除结果中的重复缓冲区。默认为 True。

Yields

(str, torch.Tensor) – 包含名称和缓冲区的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, buf in self.named_buffers():
>>>     if name in ['running_var']:
>>>         print(buf.size())

返回类型: Iterator[Tuple[str, Tensor]]

named_children()¶

返回直接子模块的迭代器，同时产生模块名称和模块本身。

Yields: (str, Module) – 包含名称和子模块的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, module in model.named_children():
>>>     if name in ['conv4', 'conv5']:
>>>         print(module)

返回类型: Iterator[Tuple[str, Module]]

named_modules(memo=None, prefix='', remove_duplicate=True)¶

返回网络中所有模块的迭代器，同时产生模块名称和模块本身。

参数

memo (Optional[Set[Module], None]) – 用于存储已添加到结果中的模块集合的备忘录
prefix (str) – 将添加到模块名称前的字符串前缀
remove_duplicate (bool) – 是否移除结果中重复的模块实例

Yields

(str, Module) – 包含名称和模块的元组

注意

重复的模块只返回一次。在以下示例中，l 只返回一次。

示例

>>> l = nn.Linear(2, 2)
>>> net = nn.Sequential(l, l)
>>> for idx, m in enumerate(net.named_modules()):
...     print(idx, '->', m)

0 -> ('', Sequential(
  (0): Linear(in_features=2, out_features=2, bias=True)
  (1): Linear(in_features=2, out_features=2, bias=True)
))
1 -> ('0', Linear(in_features=2, out_features=2, bias=True))

named_parameters(prefix='', recurse=True, remove_duplicate=True)¶

返回模块参数的迭代器，同时产生参数名称和参数本身。

参数

prefix (str) – 要添加到所有参数名称前的字符串前缀。
recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
remove_duplicate (bool, optional) – 是否移除结果中重复的参数。默认为 True。

Yields

(str, Parameter) – 包含名称和参数的元组

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for name, param in self.named_parameters():
>>>     if name in ['bias']:
>>>         print(param.size())

返回类型: Iterator[Tuple[str, Parameter]]

on_after_backward()¶

在 loss.backward() 之后且在优化器步进之前调用。

注意

如果使用原生 AMP，此时梯度不会被取消缩放。如果您需要未缩放的梯度，请使用 on_before_optimizer_step。

返回类型: None

on_after_batch_transfer(batch, dataloader_idx)¶

覆盖此方法以在批次转移到设备后修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_after_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = gpu_transforms(batch['x'])
    return batch

另请参阅

on_before_batch_transfer()
transfer_batch_to_device()

on_before_backward(loss)¶

在 loss.backward() 之前调用。

参数: loss (Tensor) – 损失值，除以进行梯度累积的批次数，如果使用 AMP 则会进行缩放。
返回类型: None

on_before_batch_transfer(batch, batch_idx, dataloader_idx=0)¶

覆盖此方法以在批次转移到设备之前修改或应用批次增强。

注意

要检查此钩子的当前执行状态，您可以使用 self.trainer.training/testing/validating/predicting，以便根据您的需求添加不同的逻辑。

参数

batch (Any) – 需要修改或增强的数据批次。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据批次

示例

def on_before_batch_transfer(self, batch, dataloader_idx):
    batch['x'] = transforms(batch['x'])
    return batch

另请参阅

on_after_batch_transfer()
transfer_batch_to_device()

on_before_optimizer_step(optimizer)¶

在 optimizer.step() 之前调用。

如果使用梯度累积，则在梯度累积完成后调用此钩子。参见： :paramref:`~pytorch_lightning.trainer.trainer.Trainer.accumulate_grad_batches`。

如果使用 AMP，损失值在此钩子调用前会取消缩放。有关梯度缩放的更多信息，请参阅这些文档。

如果进行梯度裁剪，此时梯度尚未被裁剪。

参数: optimizer (Optimizer) – 正在使用的当前优化器。

示例

def on_before_optimizer_step(self, optimizer):
    # example to inspect gradient information in tensorboard
    if self.trainer.global_step % 25 == 0:  # don't make the tf file huge
        for k, v in self.named_parameters():
            self.logger.experiment.add_histogram(
                tag=k, values=v.grad, global_step=self.trainer.global_step
            )

返回类型: None

on_before_zero_grad(optimizer)¶

在 training_step() 之后且在 optimizer.zero_grad() 之前调用。

在训练循环中，在优化器步长后和梯度清零前调用。是检查权重更新后权重信息的好地方。

这里是它被调用的地方

for optimizer in optimizers:
    out = training_step(...)

    model.on_before_zero_grad(optimizer) # < ---- called here
    optimizer.zero_grad()

    backward()

参数: optimizer (Optimizer) – 应清零其梯度的优化器。
返回类型: None

on_fit_end()¶

在 fit 的最后调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

on_fit_start()¶

在 fit 的最开始调用。

如果在 DDP 上，它会在每个进程上调用

返回类型: None

property on_gpu: bool¶

如果此模型当前位于 GPU 上，则返回 True。

对于在 LightningModule 中设置标志以区分 CPU 和 GPU 的行为很有用。

返回类型: bool

on_load_checkpoint(checkpoint)¶

Lightning 调用此函数以恢复您的模型。如果您使用 on_save_checkpoint() 保存了某些内容，这是您恢复它们的机会。

参数: checkpoint (dict[str, Any]) – 已加载的检查点

示例

def on_load_checkpoint(self, checkpoint):
    # 99% of the time you don't need to implement this method
    self.something_cool_i_want_to_save = checkpoint['something_cool_i_want_to_save']

注意

Lightning 会自动恢复全局步长、epoch 和训练状态，包括 amp 缩放。您无需恢复任何与训练相关的内容。

返回类型: None

on_predict_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在预测循环中批次之后调用。

参数

outputs (Optional[Any, None]) – predict_step(x) 的输出
batch (Any) – 预测 DataLoader 返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_batch_start(batch, batch_idx, dataloader_idx=0)¶

在预测循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_predict_end()¶

在预测结束时调用。

返回类型: None

on_predict_epoch_end()¶

在预测结束时调用。

返回类型: None

on_predict_epoch_start()¶

在预测开始时调用。

返回类型: None

on_predict_model_eval()¶

预测循环开始时调用。

预测循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。

返回类型: None

on_predict_start()¶

在预测开始时调用。

返回类型: None

on_save_checkpoint(checkpoint)¶

Lightning 在保存检查点时调用此方法，以便您有机会保存任何其他您可能想要保存的内容。

参数: checkpoint (dict[str, Any]) – 在检查点字典被写入文件之前的完整字典。此钩子函数的实现可以将额外数据插入此字典。

示例

def on_save_checkpoint(self, checkpoint):
    # 99% of use cases you don't need to implement this method
    checkpoint['something_cool_i_want_to_save'] = my_cool_pickable_object

注意

Lightning 会保存训练的所有方面（周期、全局步数等），包括 amp scaling。您无需存储任何关于训练的内容。

返回类型: None

on_test_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在测试循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – test_step(x) 的输出。
batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_batch_start(batch, batch_idx, dataloader_idx=0)¶

在测试循环中该批次发生任何事情之前调用。

参数

batch (Any) – 测试数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_test_end()¶

在测试结束时调用。

返回类型: None

on_test_epoch_end()¶

在测试循环中 epoch 的最后调用。

返回类型: None

on_test_epoch_start()¶

在测试循环中 epoch 的最开始调用。

返回类型: None

on_test_model_eval()¶

测试循环开始时调用。

测试循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_test_model_train()。

返回类型: None

on_test_model_train()¶

测试循环结束时调用。

测试循环默认将 LightningModule 的 training 模式恢复到开始测试之前的状态。重写此钩子函数以改变此行为。另请参见 on_test_model_eval()。

返回类型: None

on_test_start()¶

在测试开始时调用。

返回类型: None

on_train_batch_end(outputs, batch, batch_idx)¶

在训练循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – training_step(x) 的输出。
batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

注意

此处 outputs["loss"] 的值将是根据 accumulate_grad_batches 对 training_step 返回的损失值进行归一化后的值。

返回类型: None

on_train_batch_start(batch, batch_idx)¶

在训练循环中该批次发生任何事情之前调用。

如果此处返回 -1，将跳过当前周期的剩余训练。

参数

batch (Any) – 训练数据加载器返回的批次数据。
batch_idx (int) – 批次的索引

返回类型

Optional[int, None]

on_train_end()¶

在训练结束、logger 实验关闭之前调用。

返回类型: None

on_train_epoch_end()¶

在训练循环中 epoch 的最后调用。

要在周期结束时访问所有批次输出，您可以将步输出缓存为 LightningModule 的属性，并在此钩子函数中访问它们

class MyLightningModule(L.LightningModule):
    def __init__(self):
        super().__init__()
        self.training_step_outputs = []

    def training_step(self):
        loss = ...
        self.training_step_outputs.append(loss)
        return loss

    def on_train_epoch_end(self):
        # do something with all training_step outputs, for example:
        epoch_mean = torch.stack(self.training_step_outputs).mean()
        self.log("training_epoch_mean", epoch_mean)
        # free up the memory
        self.training_step_outputs.clear()

on_train_epoch_start()¶

在训练循环中 epoch 的最开始调用。

返回类型: None

on_train_start()¶

在健全性检查之后、训练开始时调用。

返回类型: None

on_validation_batch_end(outputs, batch, batch_idx, dataloader_idx=0)¶

在验证循环中批次之后调用。

参数

outputs (Union[Tensor, Mapping[str, Any], None]) – validation_step(x) 的输出。
batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_batch_start(batch, batch_idx, dataloader_idx=0)¶

在验证循环中该批次发生任何事情之前调用。

参数

batch (Any) – 验证数据加载器返回的批次数据。
batch_idx (int) – 批次的索引
dataloader_idx (int) – dataloader 的索引

返回类型

None

on_validation_end()¶

在验证结束时调用。

返回类型: None

on_validation_epoch_end()¶: 在验证循环中 epoch 的最后调用。

on_validation_epoch_start()¶

在验证循环中 epoch 的最开始调用。

返回类型: None

on_validation_model_eval()¶

验证循环开始时调用。

验证循环默认在开始前对 LightningModule 调用 .eval()。重写此钩子函数以改变此行为。另请参见 on_validation_model_train()。

返回类型: None

on_validation_model_train()¶

验证循环结束时调用。

验证循环默认将 LightningModule 的 training 模式恢复到开始验证之前的状态。重写此钩子函数以改变此行为。另请参见 on_validation_model_eval()。

返回类型: None

on_validation_model_zero_grad()¶

由训练循环调用，在进入验证循环之前释放梯度。

返回类型: None

on_validation_start()¶

在验证开始时调用。

返回类型: None

optimizer_step(epoch, batch_idx, optimizer, optimizer_closure=None)¶

覆盖此方法以调整 Trainer 调用优化器的默认方式。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Union[Optimizer, LightningOptimizer]) – PyTorch 优化器
optimizer_closure (Optional[Callable[[], Any], None]) – 优化器闭包。必须执行此闭包，因为它包含对 training_step()、optimizer.zero_grad() 和 backward() 的调用。

示例

def optimizer_step(self, epoch, batch_idx, optimizer, optimizer_closure):
    # Add your custom logic to run directly before `optimizer.step()`

    optimizer.step(closure=optimizer_closure)

    # Add your custom logic to run directly after `optimizer.step()`

返回类型: None

optimizer_zero_grad(epoch, batch_idx, optimizer)¶

覆盖此方法以更改 optimizer.zero_grad() 的默认行为。

参数

epoch (int) – 当前周期
batch_idx (int) – 当前批次的索引
optimizer (Optimizer) – PyTorch 优化器

示例

# DEFAULT
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad()

# Set gradients to `None` instead of zero to improve performance (not required on `torch>=2.0.0`).
def optimizer_zero_grad(self, epoch, batch_idx, optimizer):
    optimizer.zero_grad(set_to_none=True)

有关上述示例的解释，请参见 torch.optim.Optimizer.zero_grad()。

返回类型: None

optimizers(use_pl_optimizer=True)¶

返回训练期间使用的优化器。对于手动优化很有用。

参数: use_pl_optimizer (bool) – 如果为 True，则会将优化器封装在 LightningOptimizer 中，以自动处理精度、分析以及步调用计数，从而实现正确的日志记录和检查点。它专门封装 step 方法，不支持没有此方法的自定义优化器。
返回类型: Union[Optimizer, LightningOptimizer, _FabricOptimizer, list[Optimizer], list[LightningOptimizer], list[_FabricOptimizer]]
返回值: 单个优化器，或者在存在多个优化器时返回一个列表。

property output_chunk_length: Optional[int]¶

模型一次预测的时间步长数量。

返回类型: Optional[int, None]

parameters(recurse=True)¶

返回模块参数的迭代器。

这通常传递给优化器。

参数: recurse (bool) – 如果为 True，则生成此模块及其所有子模块的参数。否则，仅生成此模块的直接成员参数。
Yields: Parameter – 模块参数

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> for param in model.parameters():
>>>     print(type(param), param.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)

返回类型: Iterator[Parameter]

pred_batch_size: Optional[int]¶

pred_mc_dropout: Optional[bool]¶

pred_n: Optional[int]¶

pred_n_jobs: Optional[int]¶

pred_num_samples: Optional[int]¶

pred_roll_size: Optional[int]¶

predict_dataloader()¶

指定预测样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

建议所有数据下载和准备工作都在 prepare_data() 中进行。

predict()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any
返回值: 一个 torch.utils.data.DataLoader 或其序列，指定预测样本。

predict_likelihood_parameters: Optional[bool]¶

predict_step(batch, batch_idx, dataloader_idx=None)¶

执行预测步骤

batch: Darts 的 InferenceDataset 的输出 - 包含 (past_target, past_covariates, historic_future_covariates, future_covariates, future_past_covariates, input time series, prediction start time step) 的元组
batch_idx: 当前批次的批次索引
dataloader_idx: 数据加载器索引

返回类型: Sequence[TimeSeries]

prepare_data()¶

警告

不要在此方法中为模型设置状态（请改用 setup 方法），因为此方法不会在每个设备上调用

示例

def prepare_data(self):
    # good
    download_data()
    tokenize()
    etc()

    # bad
    self.split = data_split
    self.some_state = some_other_state()

在分布式环境中，prepare_data 可以通过两种方式调用（使用 prepare_data_per_node）

每个节点一次。这是默认设置，仅在 LOCAL_RANK=0 上调用。
总共一次。仅在 GLOBAL_RANK=0 上调用。

示例

# DEFAULT
# called once per node on LOCAL_RANK=0 of that node
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = True

# call on GLOBAL_RANK=0 (great for shared file systems)
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = False

此方法在请求数据加载器之前调用

model.prepare_data()
initialize_distributed()
model.setup(stage)
model.train_dataloader()
model.val_dataloader()
model.test_dataloader()
model.predict_dataloader()

返回类型: None

prepare_data_per_node: bool¶

print(*args, **kwargs)¶

仅从进程 0 打印。在任何分布式模式下使用此方法以仅记录一次。

参数

*args – 要打印的内容。与 Python 内置的 print 函数相同。
**kwargs – 与 Python 内置的 print 函数相同。

示例

def forward(self, x):
    self.print(x, 'in forward')

返回类型: None

register_backward_hook(hook)¶

在模块上注册后向钩子。

此函数已被弃用，推荐使用 register_full_backward_hook()，此函数的行为将在未来版本中改变。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_buffer(name, tensor, persistent=True)¶

向模块添加缓冲区。

这通常用于注册不应被视为模型参数的缓冲区。例如，BatchNorm 的 running_mean 不是参数，而是模块状态的一部分。默认情况下，缓冲区是持久的，会与参数一起保存。可以通过将 persistent 设置为 False 来更改此行为。持久缓冲区和非持久缓冲区之间的唯一区别在于后者不会成为此模块的 state_dict 的一部分。

缓冲区可以使用给定的名称作为属性访问。

参数

name (str) – 缓冲区的名称。可以使用给定的名称从此模块访问缓冲区
tensor (Tensor or None) – 要注册的缓冲区。如果为 None，则在缓冲区上运行的操作（例如 cuda）将被忽略。如果为 None，则缓冲区**不会**包含在模块的 state_dict 中。
persistent (bool) – 缓冲区是否为此模块的 state_dict 的一部分。

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> self.register_buffer('running_mean', torch.zeros(num_features))

返回类型: None

register_forward_hook(hook, *, prepend=False, with_kwargs=False, always_call=False)¶

在模块上注册前向钩子。

每次在 forward() 计算出输出后都会调用此钩子。

hook(module, args, output) -> None or modified output

如果 with_kwargs 为 True，则前向钩子函数将接收传递给 forward 函数的 kwargs，并预期返回可能修改过的输出。此钩子函数应具有以下签名：

hook(module, args, kwargs, output) -> None or modified output

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 True，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward 钩子函数之后触发。请注意，使用 register_module_forward_hook() 注册的全局 forward 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 True，hook 将接收传递给 forward 函数的 kwargs。默认值：False
always_call (bool) – 如果为 True，无论在调用模块时是否引发异常，hook 都将被运行。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_forward_pre_hook(hook, *, prepend=False, with_kwargs=False)¶

在模块上注册前向预钩子。

每次调用 forward() 之前都会调用此钩子。

hook(module, args) -> None or modified input

hook(module, args, kwargs) -> None or a tuple of modified input and kwargs

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 forward_pre 钩子函数之后触发。请注意，使用 register_module_forward_pre_hook() 注册的全局 forward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。默认值：False
with_kwargs (bool) – 如果为 true，hook 将接收传递给 forward 函数的 kwargs。默认值：False

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_hook(hook, prepend=False)¶

在模块上注册后向钩子。

每当计算相对于模块的梯度时，此钩子函数都将被调用，即只有当计算相对于模块输出的梯度时，此钩子函数才会执行。此钩子函数应具有以下签名：

hook(module, grad_input, grad_output) -> tuple(Tensor) or None

警告

使用后向钩子时，不允许原地修改输入或输出，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward 钩子函数之后触发。请注意，使用 register_module_full_backward_hook() 注册的全局 backward 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_full_backward_pre_hook(hook, prepend=False)¶

在模块上注册后向预钩子。

每当计算模块的梯度时，此钩子函数都将被调用。此钩子函数应具有以下签名：

hook(module, grad_output) -> tuple[Tensor] or None

警告

使用后向钩子时，不允许原地修改输入，否则将引发错误。

参数

hook (Callable) – 要注册的用户定义钩子函数。
prepend (bool) – 如果为 true，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之前触发。否则，提供的 hook 将在此 torch.nn.modules.Module 上所有现有的 backward_pre 钩子函数之后触发。请注意，使用 register_module_full_backward_pre_hook() 注册的全局 backward_pre 钩子函数将在此方法注册的所有钩子函数之前触发。

返回值

一个可用于通过调用 handle.remove() 移除已添加钩子的句柄

返回类型

torch.utils.hooks.RemovableHandle

register_load_state_dict_post_hook(hook)¶

注册一个后钩子函数，在调用模块的 load_state_dict() 后运行。

它应该具有以下签名：: hook(module, incompatible_keys) -> None

如有需要，可以原地修改给定的 incompatible_keys。

请注意，当使用 strict=True 调用 load_state_dict() 时执行的检查会受到钩子对 missing_keys 或 unexpected_keys 所做修改的影响，这是预期行为。向任何一个键集添加内容都会在使用 strict=True 时引发错误，而清除缺失和意外键将避免错误。

返回值: 一个可用于通过调用 handle.remove() 移除已添加钩子的句柄
返回类型: torch.utils.hooks.RemovableHandle

register_load_state_dict_pre_hook(hook)¶

注册一个预钩子函数，在调用模块的 load_state_dict() 之前运行。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata, strict, missing_keys, unexpected_keys, error_msgs) -> None # noqa: B950

参数: hook (Callable) – 可调用钩子函数，将在加载状态字典之前被调用。

register_module(name, module)¶

add_module() 的别名。

返回类型: None

register_parameter(name, param)¶

向模块添加参数。

参数可以使用给定的名称作为属性访问。

参数

name (str) – 参数的名称。可以使用给定的名称从此模块访问参数
param (Parameter or None) – 要添加到模块的参数。如果为 None，则在参数上运行的操作（例如 cuda）将被忽略。如果为 None，则参数**不会**包含在模块的 state_dict 中。

返回类型

None

register_state_dict_post_hook(hook)¶

为 state_dict() 方法注册一个后钩子。

它应该具有以下签名：: hook(module, state_dict, prefix, local_metadata) -> None

注册的钩子函数可以原地修改 state_dict。

register_state_dict_pre_hook(hook)¶

为 state_dict() 方法注册一个预钩子。

它应该具有以下签名：: hook(module, prefix, keep_vars) -> None

注册的钩子函数可用于在进行 state_dict 调用之前执行预处理。

requires_grad_(requires_grad=True)¶

更改此模块中是否应记录参数上的自动梯度操作。

此方法原地设置参数的 requires_grad 属性。

此方法有助于冻结模块的一部分用于微调，或单独训练模型的各个部分（例如，GAN 训练）。

有关 .requires_grad_() 和几个可能与其混淆的类似机制的比较，请参见 locally-disable-grad-doc。

参数: requires_grad (bool) – 是否应由 autograd 记录此模块中参数的操作。默认值：True。
返回值: self
返回类型: Module

save_hyperparameters(*args, ignore=None, frame=None, logger=True)¶

将参数保存到 hparams 属性。

参数

args (Any) – 可以是 dict、NameSpace 或 OmegaConf 的单个对象，或来自类 __init__ 的字符串名称或参数
ignore (Union[str, Sequence[str], None]) – 要忽略的来自类 __init__ 的参数名称或参数名称列表
frame (Optional[frame, None]) – 一个 frame 对象。默认值为 None
logger (bool) – 是否将超参数发送到日志记录器。默认值：True

示例：

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # manually assign arguments
...         self.save_hyperparameters('arg1', 'arg3')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class AutomaticArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # equivalent automatic
...         self.save_hyperparameters()
...     def forward(self, *args, **kwargs):
...         ...
>>> model = AutomaticArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg2": abc
"arg3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class SingleArgModel(HyperparametersMixin):
...     def __init__(self, params):
...         super().__init__()
...         # manually assign single argument
...         self.save_hyperparameters(params)
...     def forward(self, *args, **kwargs):
...         ...
>>> model = SingleArgModel(Namespace(p1=1, p2='abc', p3=3.14))
>>> model.hparams
"p1": 1
"p2": abc
"p3": 3.14

>>> from pytorch_lightning.core.mixins import HyperparametersMixin
>>> class ManuallyArgsModel(HyperparametersMixin):
...     def __init__(self, arg1, arg2, arg3):
...         super().__init__()
...         # pass argument(s) to ignore as a string or in a list
...         self.save_hyperparameters(ignore='arg2')
...     def forward(self, *args, **kwargs):
...         ...
>>> model = ManuallyArgsModel(1, 'abc', 3.14)
>>> model.hparams
"arg1": 1
"arg3": 3.14

返回类型: None

set_extra_state(state)¶

设置加载的 state_dict 中包含的额外状态。

此函数由 load_state_dict() 调用，用于处理在 state_dict 中找到的任何额外状态。如果需要将额外状态存储在其 state_dict 中，请为您的模块实现此函数以及相应的 get_extra_state() 函数。

参数: state (dict) – 来自 state_dict 的额外状态
返回类型: None

set_mc_dropout(active)¶

set_predict_parameters(n, num_samples, roll_size, batch_size, n_jobs, predict_likelihood_parameters, mc_dropout)¶

在调用 trainer.predict() 之前从 TorchForecastingModel 设置并在 self.on_predict_end() 重置

返回类型: None

set_submodule(target, module)¶

如果存在，则设置由 target 指定的子模块，否则抛出错误。

例如，假设您有一个 nn.Module A，它看起来像这样

A(
    (net_b): Module(
        (net_c): Module(
            (conv): Conv2d(16, 33, kernel_size=(3, 3), stride=(2, 2))
        )
        (linear): Linear(in_features=100, out_features=200, bias=True)
    )
)

(图示为一个 nn.Module A。A 有一个嵌套子模块 net_b，其本身又有两个子模块 net_c 和 linear。net_c 然后有一个子模块 conv。)

要用一个新的子模块 Linear 覆盖 Conv2d，您可以调用 set_submodule("net_b.net_c.conv", nn.Linear(33, 16))。

参数

target (str) – 要查找的子模块的完全限定字符串名称。（有关如何指定完全限定字符串，请参见上面的示例。）
module (Module) – 用于设置子模块的模块。

Raises

ValueError – 如果目标字符串为空
AttributeError – 如果目标字符串引用了无效路径或解析到的内容不是 nn.Module

返回类型

None

setup(stage)¶

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'

示例

class LitModel(...):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        download_data()
        tokenize()

        # don't do this
        self.something = else

    def setup(self, stage):
        data = load_data(...)
        self.l1 = nn.Linear(28, data.num_classes)

返回类型: None

share_memory()¶

参见 torch.Tensor.share_memory_()。

返回类型: ~T

state_dict(*args, destination=None, prefix='', keep_vars=False)¶

返回包含模块完整状态引用的字典。

参数和持久缓冲区（例如，运行平均值）都包含在内。键是相应的参数和缓冲区名称。设置为 None 的参数和缓冲区不包含在内。

注意

返回的对象是浅拷贝。它包含对模块参数和缓冲区的引用。

警告

目前 state_dict() 也按顺序接受 destination、prefix 和 keep_vars 的位置参数。但是，此用法已被弃用，未来版本将强制使用关键字参数。

警告

请避免使用参数 destination，因为它并非为终端用户设计。

参数

destination (dict, optional) – 如果提供，模块的状态将更新到此字典中，并返回相同的对象。否则，将创建一个 OrderedDict 并返回。默认值：None。
prefix (str, optional) – 添加到参数和缓冲区名称的前缀，用于在 state_dict 中构成键。默认值：''。
keep_vars (bool, optional) – 默认情况下，state dict 中返回的 Tensor s 与 autograd 分离。如果设置为 True，将不会进行分离。默认值：False。

返回值

包含模块完整状态的字典

返回类型

dict

示例

>>> # xdoctest: +SKIP("undefined vars")
>>> module.state_dict().keys()
['bias', 'weight']

property strict_loading: bool¶

确定 Lightning 如何使用 .load_state_dict(…, strict=model.strict_loading) 加载此模型。

返回类型: bool

property supports_probabilistic_prediction: bool¶

返回类型: bool

teardown(stage)¶

在 fit（训练 + 验证）、验证、测试或预测结束时调用。

参数: stage (str) – 可以是 'fit'、'validate'、'test' 或 'predict'
返回类型: None

test_dataloader()¶

指定测试样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

test()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果您不需要测试数据集和 test_step()，则无需实现此方法。

返回类型: Any

test_step(*args, **kwargs)¶

对测试集中的单个批次数据进行操作。在此步骤中，您通常会生成示例或计算任何感兴趣的内容，例如准确率。

参数

batch – 您的数据可迭代对象（通常是 DataLoader）的输出。
batch_idx – 此批次的索引。
dataloader_idx – 生成此批次的数据加载器索引。（仅在使用多个数据加载器时）

返回类型

Union[Tensor, Mapping[str, Any], None]

返回值

Tensor - 损失张量
dict - 字典。可以包含任意键，但必须包含键 'loss'。
None - 跳到下一个批次。

# if you have one test dataloader:
def test_step(self, batch, batch_idx): ...

# if you have multiple test dataloaders:
def test_step(self, batch, batch_idx, dataloader_idx=0): ...

示例

# CASE 1: A single test dataset
def test_step(self, batch, batch_idx):
    x, y = batch

    # implement your own
    out = self(x)
    loss = self.loss(out, y)

    # log 6 example images
    # or generated text... or whatever
    sample_imgs = x[:6]
    grid = torchvision.utils.make_grid(sample_imgs)
    self.logger.experiment.add_image('example_images', grid, 0)

    # calculate acc
    labels_hat = torch.argmax(out, dim=1)
    test_acc = torch.sum(y == labels_hat).item() / (len(y) * 1.0)

    # log the outputs!
    self.log_dict({'test_loss': loss, 'test_acc': test_acc})

如果传入多个测试 dataloader，test_step() 将有一个额外的参数。我们建议将默认值设置为 0，以便您可以在单个和多个 dataloader 之间快速切换。

# CASE 2: multiple test dataloaders
def test_step(self, batch, batch_idx, dataloader_idx=0):
    # dataloader_idx tells you which dataset this is.
    ...

注意

如果您不需要测试，则无需实现此方法。

注意

调用 test_step() 时，模型已设置为评估模式，并已禁用 PyTorch 梯度。在测试 epoch 结束时，模型会回到训练模式并启用梯度。

to(*args, **kwargs)¶

参见 torch.nn.Module.to()。

返回类型: Self

to_dtype(dtype)¶: 将模块精度（默认为 float32）转换为其他精度。

to_empty(*, device, recurse=True)¶

在不复制存储的情况下，将参数和缓冲区移动到指定设备。

参数

device (torch.device) – 此模块中参数和缓冲区的目标设备。
recurse (bool) – 是否应将子模块的参数和缓冲区递归地移动到指定设备。

返回值

self

返回类型

Module

to_onnx(file_path, input_sample=None, **kwargs)¶

将模型保存为 ONNX 格式。

参数

file_path (Union[str, Path, BytesIO]) – 应保存 onnx 模型的文件路径。
input_sample (Optional[Any, None]) – 用于跟踪的输入。默认值：None（使用 self.example_input_array）
**kwargs – 将传递给 torch.onnx.export 函数。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)

model = SimpleModel()
input_sample = torch.randn(1, 64)
model.to_onnx("export.onnx", input_sample, export_params=True)

返回类型: None

to_torchscript(file_path=None, method='script', example_inputs=None, **kwargs)¶

默认情况下，将整个模型编译为 ScriptModule。如果要使用 tracing，请提供参数 method='trace' 并确保提供了 example_inputs 参数，或者模型设置了 example_input_array。如果您想自定义要脚本化的模块，应覆盖此方法。如果您想返回多个模块，我们建议使用字典。

参数

file_path (Union[str, Path, None]) – 保存 torchscript 的路径。默认值：None（不保存文件）。
method (Optional[str, None]) – 是使用 TorchScript 的 script 方法还是 trace 方法。默认值：‘script’
example_inputs (Optional[Any, None]) – 在将 method 设置为 'trace' 时用于执行 tracing 的输入。默认值：None (使用 example_input_array)
**kwargs – 将传递给 torch.jit.script() 或 torch.jit.trace() 函数的附加参数。

注意

需要实现 forward() 方法。
导出的脚本将被设置为评估模式。
建议您安装最新支持版本的 PyTorch 以无限制地使用此功能。另请参见 torch.jit 文档以了解支持的功能。

示例

class SimpleModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(in_features=64, out_features=4)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)))

model = SimpleModel()
model.to_torchscript(file_path="model.pt")

torch.jit.save(model.to_torchscript(
    file_path="model_trace.pt", method='trace', example_inputs=torch.randn(1, 64))
)

返回类型: Union[ScriptModule, dict[str, ScriptModule]]
返回值: 此 LightningModule 作为 torchscript，无论是否定义了 file_path。

toggle_optimizer(optimizer)¶

确保在训练步骤中仅计算当前优化器参数的梯度，以防止在多优化器设置中出现悬空梯度。

它与 untoggle_optimizer() 协同工作，以确保 param_requires_grad_state 正确重置。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要切换的优化器。
返回类型: None

train(mode=True)¶

将模块设置为训练模式。

这仅对某些模块有影响。有关它们在训练/评估模式下的行为详情，例如它们是否受影响（例如 Dropout、BatchNorm 等），请参阅特定模块的文档。

参数: mode (bool) – 是否设置训练模式 (True) 或评估模式 (False)。默认值: True。
返回值: self
返回类型: Module

train_criterion_reduction: Optional[str]¶

train_dataloader()¶

指定训练样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

您返回的数据加载器不会被重新加载，除非您将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数。

对于数据处理，请使用以下模式

在 prepare_data() 中下载

在 setup() 中处理和分割

但是，上述模式仅在分布式处理中是必需的。

警告

不要在 prepare_data 中分配状态

fit()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

返回类型: Any

property trainer: Trainer¶

返回类型: Trainer

training: bool¶

training_step(train_batch, batch_idx)¶

执行训练步骤

返回类型: Tensor

transfer_batch_to_device(batch, device, dataloader_idx)¶

如果您的 DataLoader 返回包装在自定义数据结构中的张量，请覆盖此钩子。

下面列出的数据类型（以及它们的任意嵌套）是开箱即用的支持

torch.Tensor 或任何实现了 .to(…) 的东西
list
dict
tuple

对于其他任何东西，你需要定义数据如何移动到目标设备 (CPU, GPU, TPU, …)。

注意

参数

batch (Any) – 需要转移到新设备的数据批次。
device (device) – PyTorch 中定义的目标设备。
dataloader_idx (int) – 该批次所属的 dataloader 索引。

返回类型

Any

返回值

数据在新设备上的引用。

示例

def transfer_batch_to_device(self, batch, device, dataloader_idx):
    if isinstance(batch, CustomBatch):
        # move all tensors in your custom data structure to the device
        batch.samples = batch.samples.to(device)
        batch.targets = batch.targets.to(device)
    elif dataloader_idx == 0:
        # skip device transfer for the first dataloader or anything you wish
        pass
    else:
        batch = super().transfer_batch_to_device(batch, device, dataloader_idx)
    return batch

另请参阅

move_data_to_device()
apply_to_collection()

type(dst_type)¶

参见 torch.nn.Module.type()。

返回类型: Self

unfreeze()¶

解冻所有参数以进行训练。

model = MyLightningModule(...)
model.unfreeze()

返回类型: None

untoggle_optimizer(optimizer)¶

重置通过 toggle_optimizer() 切换的所需梯度状态。

参数: optimizer (Union[Optimizer, LightningOptimizer]) – 要取消切换的优化器。
返回类型: None

val_criterion_reduction: Optional[str]¶

val_dataloader()¶

指定验证样本的可迭代对象或可迭代对象集合。

有关多个数据加载器的更多信息，请参见此章节。

您返回的数据加载器不会被重新加载，除非您将 :paramref:`~pytorch_lightning.trainer.trainer.Trainer.reload_dataloaders_every_n_epochs` 设置为正整数。

建议所有数据下载和准备工作都在 prepare_data() 中进行。

fit()
validate()
prepare_data()
setup()

注意

Lightning 尝试为分布式和任意硬件添加正确的采样器。无需自行设置。

注意

如果您不需要验证数据集和 validation_step()，则无需实现此方法。

返回类型: Any

validation_step(val_batch, batch_idx)¶

执行验证步骤

返回类型: Tensor

xpu(device=None)¶

将所有模型参数和缓冲区移动到 XPU。

这也会使得相关的参数和缓冲区成为不同的对象。因此，如果模块将在 XPU 上运行并进行优化，则应该在构建优化器之前调用它。

注意

此方法会修改模块本身。

参数: device (int, optional) – 如果指定，所有参数将被复制到该设备
返回值: self
返回类型: Module

zero_grad(set_to_none=True)¶

重置所有模型参数的梯度。

请参阅 torch.optim.Optimizer 下的类似函数，了解更多背景信息。

参数: set_to_none (bool) – 不设置为零，而是将梯度设置为 None。请参阅 torch.optim.Optimizer.zero_grad() 了解详情。
返回类型: None

darts.models.forecasting.pl_forecasting_module.io_processor(forward)[source]¶

对 PLForecastingModule.forward 应用一些输入/输出处理。请注意，此包装器必须添加到 PLForecastinModule 的每个子类的 forward 方法中。这是一个如何添加装饰器的示例：

```python: @io_processor def forward(self, *args, **kwargs)

pass

```

N-Linear

Facebook Prophet