# ema

Python API: `luxonis_train.callbacks.ema`

保持权重的指数移动平均值。

拟合期间的验证使用平均权重运行，因此其可视化也来自这些权重。拟合后，模型保持平均权重。非仅权重检查点将平均权重作为模型权重。从此类检查点导出的模型也使用它们。

## 类

### EMACallback

保持权重指数移动平均值的回调。

回调将平均值保存在
[ModelEma](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
中。它在运行的这些点更改模型：

 * [on_fit_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
   从当前权重创建平均值。
 * [on_train_batch_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
   在每个梯度累积窗口中将平均值向训练权重移动一次。
 * 验证和测试在平均值存在时使用平均权重运行。回调在循环开始时保留模型权重的副本，并在循环结束时加载副本。
 * 训练结束时，模型保持平均权重。
 * 每个非仅权重检查点都将平均权重作为模型权重。检查点中回调的状态也包含平均值和更新计数，因此恢复的拟合会继续平均值。

虽然
[replace_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/export_utils.md)
在模型中保留显式权重，但回调不交换任何权重。

[LuxonisLightningModule.configure_callbacks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
为训练器的每次调用（例如 `trainer.fit` 或 `trainer.test`）构建此回调的新实例。因此，拟合后的 `trainer.test` 调用没有平均值，并且测试使用模型的当前权重运行。

配置将此回调移动到 `trainer.callbacks` 的前面，以便它在配置的其他回调之前运行。

#### 方法

##### init

```python
def __init__(decay: float = 0.5, use_dynamic_decay: bool = True, decay_tau: float = 2000):
```

使用平均值的选项初始化回调。

回调在
[on_fit_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
中创建平均值，而不是在此处。

参数

 * `decay` (`float`): 平均值的最大衰减。接近 `1` 的值会缓慢移动平均值。默认值 `0.5` 远低于
   [ModelEma](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
   的默认值 `0.9999`。
 * `use_dynamic_decay` (`bool`): 当为 `True` 时，衰减会随着更新的累积从 `0` 增长到 `decay`。请参阅
   [ModelEma.update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)。
 * `decay_tau` (`float`): 动态衰减的时间常数，以更新为单位。

##### load_state_dict

```python
def load_state_dict(state_dict: dict[str, Any]):
```

为下一个
[on_fit_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
存储检查点平均值。

Lightning 在恢复检查点时调用此方法，并使用
[state_dict](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
返回的字典。该方法读取 `"ema_state_dict"` 下的值，或者在缺少该键时读取 `"state_dict"` 下的值。当该值为映射时，它会保留该值。当 `"updates"` 下的值为 `int` 时，它也会保留该值。它忽略其他类型的值和空的
`state_dict`。当前平均值不变。

> **示例**
> 在拟合之前，回调没有平均值，因此其状态保持为空：

```pycon
>>> import torch
>>> callback = EMACallback()
>>> callback.load_state_dict(
...     {"ema_state_dict": {"weight": torch.ones(1)}, "updates": 7}
... )
>>> callback.state_dict()
{}
```

参数

 * `state_dict` (`dict[str, Any]`): 回调的状态。

##### on_fit_start

```python
def on_fit_start(trainer: pl.Trainer, pl_module: pl.LightningModule):
```

从模型的当前权重创建平均值。

Lightning 在 `trainer.fit` 开始时调用此钩子。该钩子使用回调的选项从 `pl_module` 构建一个新的
[ModelEma](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)。当
[load_state_dict](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
或
[on_load_checkpoint](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
之前存储了平均值时，该钩子将其复制到新的平均值中：

 * 它忽略损失、指标和可视化工具为其节点保留的条目，在两个平均值中都是如此。
 * 它会记录存储的平均值缺少、多余或形状不同的键的警告。
 * 它保留缺失键和形状不同键的新值。
 * 它将存储的张量移动到新平均值的设备。
 * 当存储了计数时，它会设置更新计数。

然后它清除存储的平均值和计数。

参数

 * `trainer` (`pl.Trainer`): 训练器。未使用。
 * `pl_module` (`pl.LightningModule`):
   要平均的模型。[ModelEma](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
   将其保留在训练模式。

##### on_load_checkpoint

```python
def on_load_checkpoint(trainer: pl.Trainer, pl_module: pl.LightningModule, callback_state: dict):
```

为下一个
[on_fit_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
存储检查点权重。

Lightning 在恢复具有 `callbacks` 键的检查点时调用此钩子，在调用
[load_state_dict](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
之前。Lightning 传递整个检查点，而不是回调的状态。该钩子像
[load_state_dict](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
一样读取它。检查点在顶层没有 `"ema_state_dict"` 键，因此该钩子存储其 `"state_dict"`：当此回调保存检查点时，即平均权重。然后，当检查点具有回调状态的 `"ema_state_dict"`
时，[load_state_dict](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
将该值替换为回调状态的 `"ema_state_dict"`。

参数

 * `trainer` (`pl.Trainer`): 训练器。未使用。
 * `pl_module` (`pl.LightningModule`): 模型。未使用。
 * `callback_state` (`dict`): 整个检查点，尽管名称如此。

##### on_save_checkpoint

```python
def on_save_checkpoint(trainer: pl.Trainer, pl_module: pl.LightningModule, checkpoint: dict):
```

将平均值存储为检查点的模型权重。

Lightning 在保存非仅权重检查点时调用此钩子，在收集
[state_dict](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
的输出之后。当平均值存在时，该钩子将 `checkpoint["state_dict"]` 替换为平均值。因此，加载检查点的模型会获得平均权重。

参数

 * `trainer` (`pl.Trainer`): 训练器。未使用。
 * `pl_module` (`pl.LightningModule`): 模型。未使用。
 * `checkpoint` (`dict`): Lightning 保存的检查点。钩子会就地更改它。

##### on_test_end

```python
def on_test_end(trainer: pl.Trainer, pl_module: pl.LightningModule):
```

测试结束后将保留的权重加载回模型。

Lightning 在测试循环结束时调用此钩子。该钩子将保留的权重加载到 `pl_module` 中，就像
[on_validation_end](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
一样。当没有副本存在时，或者当
[replace_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/export_utils.md)
在模型中保留显式权重时，它不执行任何操作。

参数

 * `trainer` (`pl.Trainer`): 训练器。未使用。
 * `pl_module` (`pl.LightningModule`): 被测试的模型。

##### on_test_epoch_start

```python
def on_test_epoch_start(trainer: pl.Trainer, pl_module: pl.LightningModule):
```

将平均权重加载到模型中进行测试。

Lightning 在每个测试 epoch 开始时调用此钩子。该钩子像
[on_validation_epoch_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
一样交换权重：它保留 `pl_module` 权重的深层副本，然后在平均值存在时加载平均值。当
[replace_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/export_utils.md)
在模型中保留显式权重时，该钩子不执行任何操作。

参数

 * `trainer` (`pl.Trainer`): 训练器。未使用。
 * `pl_module` (`pl.LightningModule`): 要测试的模型。

##### on_train_batch_end

```python
def on_train_batch_end(trainer: pl.Trainer, pl_module: pl.LightningModule, outputs: STEP_OUTPUT, batch: Any, batch_idx: int):
```

将平均值向训练权重移动一步。

Lightning 在每个训练批次之后调用此钩子。当平均值存在且 `batch_idx` 是 `trainer.accumulate_grad_batches` 的倍数时，该钩子调用
[ModelEma.update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)。因此，平均值在每个梯度累积窗口中移动一次，在窗口的第一个批次上。

参数

 * `trainer` (`pl.Trainer`): 训练器。钩子读取其 `accumulate_grad_batches`。
 * `pl_module` (`pl.LightningModule`): 平均值向其移动权重的模型。
 * `outputs` (`STEP_OUTPUT`): 训练步骤的输出。未使用。
 * `batch` (`Any`): 批次。未使用。
 * `batch_idx` (`int`): 批次在 epoch 中的索引。

##### on_train_end

```python
def on_train_end(trainer: pl.Trainer, pl_module: pl.LightningModule):
```

训练结束时将平均权重加载到模型中。

Lightning 在 `trainer.fit` 结束时调用此钩子一次。该钩子像
[on_validation_epoch_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
一样交换权重，但它不加载训练权重。因此，模型在拟合后保持平均权重。当
[replace_weights](article://v3.ai-inference.model-source.training.luxonis-train.luxonis-train-api-reference.core.utils.export_utils)
在模型中保留显式权重时，该钩子不执行任何操作。

参数

 * `trainer` (`pl.Trainer`): 训练器。未使用。
 * `pl_module` (`pl.LightningModule`): 训练好的模型。

##### on_validation_end

```python
def on_validation_end(trainer: pl.Trainer, pl_module: pl.LightningModule):
```

验证后将保留的权重加载回模型。

Lightning 在验证循环结束时调用此钩子。该钩子将保留的权重加载到 `pl_module` 中。在拟合期间，这些是训练好的权重。当没有副本存在时，或者当
[replace_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/export_utils.md)
在模型中保留显式权重时，该钩子不执行任何操作。副本保留在回调中。

参数

 * `trainer` (`pl.Trainer`): 训练器。未使用。
 * `pl_module` (`pl.LightningModule`): 经过验证的模型。

##### on_validation_epoch_start

```python
def on_validation_epoch_start(trainer: pl.Trainer, pl_module: pl.LightningModule):
```

将平均权重加载到模型中进行验证。

Lightning 在每个验证 epoch 开始时调用此钩子。该钩子保留 `pl_module` 状态字典的深层副本。然后，当平均值存在时，它将平均值加载到 `pl_module` 中。当
[replace_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/export_utils.md)
在模型中保留显式权重时，该钩子不执行任何操作。

参数

 * `trainer` (`pl.Trainer`): 训练器。未使用。
 * `pl_module` (`pl.LightningModule`): 要验证的模型。

##### state_dict

```python
def state_dict(self) -> dict[str, Any]:
```

返回回调的状态以用于检查点。

Lightning 在保存非仅权重检查点时调用此方法。它将非空结果存储在检查点的 `callbacks` 条目中，位于回调的状态键下。它不存储空结果。

返回

 * `dict[str, Any]`: 当平均值尚不存在时，返回一个空字典。否则，返回一个包含两个键的字典。 * `"ema_state_dict"` 包含平均值，不包括损失、指标和可视化工具为其节点保留的条目。
    * `"updates"` 包含平均值的更新次数。

#### 属性

##### ema

包含平均值的
[ModelEma](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)。

引发

 * `ValueError`: 当
   [on_fit_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
   尚未创建平均值时。

### ModelEma

模型状态字典的指数移动平均值。

平均值涵盖 `model.state_dict()` 的每个条目：参数和持久缓冲区。它存在于一个普通字典中，而不是注册的缓冲区中，因此 `ModelEma.state_dict()`
不会返回它。[EMACallback](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
创建并更新它。

#### 方法

##### init

```python
def __init__(model: pl.LightningModule, decay: float = 0.9999, use_dynamic_decay: bool = True, decay_tau: float = 2000):
```

将 `model` 的状态字典复制为第一个平均值。

该方法调用 `model.eval()`，对 `model.state_dict()` 进行深层复制，然后调用 `model.train()`。因此，`model` 之后处于训练模式，无论其之前的模式如何。复制不需要梯度。

参数

 * `model` (`pl.LightningModule`): 要平均的模型。
 * `decay` (`float`): 最大衰减 d。接近 `1` 的值会缓慢移动平均值。
 * `use_dynamic_decay` (`bool`): 当为 `True` 时，衰减会随着更新的累积从 `0` 增长到 `decay`。请参阅
   [update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)。
 * `decay_tau` (`float`): 动态衰减的时间常数 τ，以更新为单位。值越大，衰减增长越慢。

##### update

```python
def update(model: pl.LightningModule):
```

将平均值向 `model` 的状态移动一步。

该方法将 `1` 添加到 `updates` 并计算此步骤的衰减 dt。使用 `use_dynamic_decay` 时，衰减会随着更新的累积从 `0` 增长到 `decay`，因此第一个平均值会紧密跟随模型：

dt = d(1 − e − t ⁄ τ)

其中 t 是 `updates`，d 是 `decay`，τ 是 `decay_tau`。如果没有 `use_dynamic_decay`，dt = d。然后，该方法就地更改平均值的每个浮点条目 θema：

θema ← dt θema + (1 − dt) θ

其中 θ 是 `model.state_dict()` 中具有相同键的条目。该方法复制其他类型的每个条目，例如批归一化的 `num_batches_tracked` 计数器。它跳过 `model` 没有的键。更新不通过梯度流动。

> **参考**
> * 来源：改编自 [timm model_ema.py](https://github.com/huggingface/pytorch-image-models/blob/main/timm/utils/model_ema.py) ([Apache License 2.0](https://github.com/huggingface/pytorch-image-models/tree/main?tab=Apache-2.0-1-ov-file#readme))。

> **示例**
> 固定衰减 `0.5` 将平均值移动一半：

```pycon
>>> import lightning.pytorch as pl
>>> import torch
>>> model = pl.LightningModule()
>>> model.weight = torch.nn.Parameter(torch.zeros(2))
>>> ema = ModelEma(model, decay=0.5, use_dynamic_decay=False)
>>> _ = model.weight.data.fill_(1.0)
>>> ema.update(model)
>>> ema.state_dict_ema["weight"].tolist()
[0.5, 0.5]
```

动态衰减在第一次更新时较小，因此平均值向模型移动得更远：

```pycon
>>> _ = model.weight.data.zero_()
>>> ema = ModelEma(model, decay=0.5, decay_tau=1.0)
>>> _ = model.weight.data.fill_(1.0)
>>> ema.update(model)
>>> round(ema.state_dict_ema["weight"][0].item(), 3)
0.684
>>> ema.updates
1
```

参数

 * `model` (`pl.LightningModule`): 平均值向其当前状态移动的模型。

#### 属性

##### state_dict_ema

平均值，带有 `model.state_dict()` 的键。

##### updates

平均值的更新次数。每次
[update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
调用都会添加
`1`。[EMACallback.on_fit_start](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md)
从包含计数的检查点设置它。
