# aimet_utils

Python API: `luxonis_train.core.utils.aimet_utils`

AIMET 训练后量化和量化感知训练。

[LuxonisModel.quantize](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
调用这些辅助函数。AIMET 是一个可选依赖项，通过 `luxonis-train` 的 `aimet` 额外安装。该模块仅在函数内部导入 `aimet_torch`，因此模块本身在没有 AIMET 的情况下也可以导入。

## 函数

### check_aimet_available

```python
def check_aimet_available():
```

当未安装 `aimet_torch` 包时引发错误。

该函数使用 `importlib.util.find_spec` 查找包。它不导入包。

引发

 * `ImportError`: 当未安装 `aimet_torch` 时。消息会提示用户安装 `luxonis-train[aimet]`。

### get_ptq_calibration_loader

```python
def get_ptq_calibration_loader(val_dataset: torch_data.Dataset[LuxonisLoaderTorchOutput], collate_fn: Callable[[list[LuxonisLoaderTorchOutput]], Any], batch_size: int, num_workers: int, pin_memory: bool, max_calibration_images: int | None) -> DataLoader:
```

构建校准训练后量化的加载器。

[LuxonisModel.quantize](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
传递的是验证数据集本身，而不是
[LuxonisModel.val_loader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)。因此
`trainer.n_validation_batches` 不会限制校准。

使用 `max_calibration_images` 时，加载器只读取 `val_dataset` 的前 `max_calibration_images` 个样本。当这会遗漏样本时，函数会记录一条信息消息。当 `val_dataset`
的样本少于请求的数量时，函数会记录一条警告并使用所有样本。加载器保持数据集的顺序并保留最后一个不完整的批次。

> **示例**
> 此示例关闭了日志记录器，因此不会显示信息消息：

```pycon
>>> import torch
>>> from loguru import logger
>>> from torch.utils.data import TensorDataset, default_collate
>>> logger.disable("luxonis_train")
>>> loader = get_ptq_calibration_loader(
...     TensorDataset(torch.arange(10)),
...     collate_fn=default_collate,
...     batch_size=4,
...     num_workers=0,
...     pin_memory=False,
...     max_calibration_images=6,
... )
>>> logger.enable("luxonis_train")
>>> [batch.tolist() for (batch,) in loader]
[[0, 1, 2, 3], [4, 5]]
```

参数

 * `val_dataset` (`torch_data.Dataset[LuxonisLoaderTorchOutput]`): 验证视图的数据集。当 `max_calibration_images` 不为 `None` 时，它必须支持 `len`。
 * `collate_fn` (`Callable[[list[LuxonisLoaderTorchOutput]], Any]`): 将样本列表合并为批次的函数，例如
   [BaseLoaderTorch.collate_fn](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)。
 * `batch_size` (`int`): 批次中的样本数量。
 * `num_workers` (`int`): 加载器的工作进程数量。`0` 在主进程中加载样本。
 * `pin_memory` (`bool`): 在加载器返回之前，将每个批次的张量复制到固定内存中。
 * `max_calibration_images` (`int | None`): 要读取的最大样本数量。`None` 读取所有样本。

返回

 * `DataLoader`: 校准加载器。

### post_training_quantization

```python
def post_training_quantization(model: LuxonisLightningModule, dummy_inputs: Tensor, val_loader: DataLoader, save_dir: Path, quant_scheme: QuantScheme | None = None, default_output_bw: int = 8, default_param_bw: int = 8, default_data_type: QuantizationDataType | None = None, config_file: str | None = None, adaround: bool = False, adaround_iterations: int | None = None, adaround_reg_param: float = 0.01, adaround_beta_range: tuple[int, int] = (20, 2), adaround_warm_start: float = 0.2, fold_batch_norms: bool = False, cross_layer_equalization: bool = False, batch_norm_reestimation: bool = False, sequential_mse: bool = False) -> QuantizationSimModel:
```

在训练后使用 AIMET 量化模块。

该函数运行以下步骤：

 * 当 CUDA 可用时，它将 `model` 和 `dummy_inputs` 移动到 GPU，并将 `model` 置于评估模式。
 * 使用 `fold_batch_norms` 且不使用 `batch_norm_reestimation` 时，它将 `model` 的批归一化层折叠到前一层。
 * 使用 `cross_layer_equalization` 时，它均衡 `model` 连续层的权重范围。
 * 使用 `adaround` 时，它在 `val_loader` 的最多 ⌈2000 ⁄ B⌉ 个批次上学习权重的舍入，其中 B 是批次大小。AdaRound 将其文件以 `adaround` 为前缀写入 `save_dir`。接下来的步骤使用
   AdaRound 返回的模块而不是 `model`。
 * 它使用 `in_place=True` 在模块周围构建一个 `QuantizationSimModel`。
 * 使用 `sequential_mse` 时，它在 `val_loader` 上应用顺序 MSE，并使用 20 个候选。
 * 使用 `adaround` 时，它从 `save_dir` 加载 `adaround.encodings` 并冻结这些参数编码。
 * 它通过 `val_loader` 的每个批次的输入的前向传播计算编码，并显示进度条。

这些步骤会记录批归一化折叠、跨层均衡和顺序 MSE 的信息消息。

参数

 * `model` (`LuxonisLightningModule`): 要量化的模块。
 * `dummy_inputs` (`Tensor`): 用于图跟踪的输入批次，例如形状为 `[1, C, H, W]` 的随机张量。
 * `val_loader` (`DataLoader`): 校准加载器，例如
   [get_ptq_calibration_loader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/aimet_utils.md)
   的结果。每个批次都是输入和标签的对。
 * `save_dir` (`Path`): AdaRound 文件的目录。
 * `quant_scheme` (`QuantScheme | None`): AIMET 量化方案。`None` 选择 `QuantScheme.min_max`。
 * `default_output_bw` (`int`): 激活的位宽。
 * `default_param_bw` (`int`): 参数的位宽。
 * `default_data_type` (`QuantizationDataType | None`): 量化值的数据类型。`None` 选择 `QuantizationDataType.int`。
 * `config_file` (`str | None`): AIMET 配置 JSON 文件的路径。`batch_norm_reestimation` 为 `None` 时选择 AIMET 的每通道配置。
 * `adaround` (`bool`): 应用 AdaRound。
 * `adaround_iterations` (`int | None`): AdaRound 迭代次数，传递给 `AdaroundParameters`。
 * `adaround_reg_param` (`float`): AdaRound 正则化参数。
 * `adaround_beta_range` (`tuple[int, int]`): AdaRound beta 退火的开始和结束。
 * `adaround_warm_start` (`float`): AdaRound 迭代中舍入损失不起作用的份额。
 * `fold_batch_norms` (`bool`): 在量化之前折叠批归一化。它对 `batch_norm_reestimation` 没有影响，因为
   [quantization_aware_training](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/aimet_utils.md)
   会折叠它们。
 * `cross_layer_equalization` (`bool`): 应用跨层均衡。
 * `batch_norm_reestimation` (`bool`):
   [quantization_aware_training](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/aimet_utils.md)
   是否重新估计批归一化。为 `True` 时，函数会跳过批归一化折叠。当 `config_file` 为 `None` 时，它还会选择 AIMET 的每通道配置。
 * `sequential_mse` (`bool`): 应用顺序 MSE。

返回

 * `QuantizationSimModel`: 模拟，带有计算出的编码。其 `model` 是量化模块。

引发

 * `ImportError`: 当未安装 `aimet_torch` 时。
 * `AssertionError`: 当 `val_loader` 没有批次时。
 * `ValueError`: 当参数在量化之前，或在批归一化折叠、跨层均衡或 AdaRound 之后不是有限的。

### quantization_aware_training

```python
def quantization_aware_training(sim: QuantizationSimModel, dummy_inputs: Tensor, train_loader: DataLoader, optimizer: Optimizer, scheduler: LRScheduler, epochs: int, fold_batch_norms: bool = False, batch_norm_reestimation: bool = False) -> LuxonisLightningModule:
```

训练 AIMET 模拟的量化模块。

该函数就地训练 `sim.model`，并在前向传播中使用量化器。它将模块置于训练模式，并在 CUDA 可用时将其移动到 GPU。它关闭模块的自动优化以进行循环，并在结束时（包括发生错误后）恢复先前的值。

对于每个 epoch，函数会使用进度条运行 `train_loader` 的每个批次。对于每个批次，它使用
[LuxonisLightningModule.compute_training_loss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
计算损失，运行反向传播，并步进 `optimizer`。它在每个 epoch 结束时步进 `scheduler` 一次。

使用 `batch_norm_reestimation` 时，函数会重新估计 `train_loader` 上的批归一化统计信息。如果也使用 `fold_batch_norms`，它会将批归一化折叠到前一层。当 AIMET
无法跟踪量化模块的图时，函数会记录警告并跳过折叠。

参数

 * `sim` (`QuantizationSimModel`): 来自
   [post_training_quantization](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/aimet_utils.md)
   的模拟。
 * `dummy_inputs` (`Tensor`): 用于批归一化折叠的图跟踪的输入批次。
 * `train_loader` (`DataLoader`): 训练加载器。每个批次都是输入和标签的对。
 * `optimizer` (`Optimizer`): `sim.model` 参数的优化器。
 * `scheduler` (`LRScheduler`): `optimizer` 的学习率调度器。
 * `epochs` (`int`): `train_loader` 的遍历次数。
 * `fold_batch_norms` (`bool`): 在重新估计后折叠批归一化。它对不使用 `batch_norm_reestimation` 没有影响。
 * `batch_norm_reestimation` (`bool`): 在训练后重新估计批归一化统计信息。

返回

 * `LuxonisLightningModule`: 训练后的 `sim.model`。函数不会将其恢复为评估模式。

引发

 * `ImportError`: 当未安装 `aimet_torch` 时。
 * `AssertionError`: 当 `train_loader` 没有批次时。
