# gpu_stats_monitor

Python API: `luxonis_train.callbacks.gpu_stats_monitor`

在模型训练期间记录 `nvidia-smi` 的 GPU 统计信息。

版权所有 The PyTorch Lightning 团队。

根据 Apache 许可证 2.0 版（“许可证”）获得许可；除非符合许可证，否则您不得使用此文件。您可以在
[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) 获取许可证副本。

除非适用法律要求或书面同意，否则根据许可证分发的软件按“原样”分发，不附带任何明示或暗示的保证或条件。请参阅许可证以了解管理权限和限制的特定语言。

## 类

### GPUStatsMonitor

记录 `nvidia-smi` 的 GPU 统计信息的回调。

回调在训练批次开始和结束时，为训练器的每个 GPU 查询 `nvidia-smi --query-gpu`。它使用训练器的记录器在 `trainer.global_step` 记录值。它仅在训练器更新其日志的步骤上进行记录。Lightning 使用训练器的
`log_every_n_steps` 选择这些步骤。批次钩子仅在 rank 0 上运行。

[GPUStatsMonitor.init](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gpu_stats_monitor.md)
的每个标志都会开启一组查询：

 * `gpu_utilization`: `utilization.gpu`，以百分比表示。它是上一个采样周期中一个或多个内核在 GPU 上运行的部分。回调在批次开始和结束时记录它。
 * `memory_utilization`: `memory.used` 和 `memory.free`，以 MiB 为单位，以及 `utilization.memory`，以百分比表示。最后一个值是上一个采样周期中 GPU
   读取或写入其内存的部分。回调在批次开始和结束时记录它们。
 * `fan_speed`: `fan.speed`，以最大速度的百分比表示。它是预期速度，而不是测量速度。回调仅在批次结束时记录它。
 * `temperature`: `temperature.gpu` 和 `temperature.memory`，以摄氏度表示。回调仅在批次结束时记录它们。

指标名称的形式为 `GPU_<device>/<query> - <unit>`，例如 `GPU_0/utilization.gpu - percent` 或 `GPU_0/memory.used - MB`。`<device>`
是训练器的逻辑设备索引。`<unit>` 是 `percent`、`MB` 或 `°C`。`MB` 标签表示 MiB 中的值。回调将非数字值（例如 `[N/A]`）记录为 `0.0`。

另外两个标志记录批次时间，以毫秒为单位：

 * `intra_step_time`: `batch_time/intra_step (ms)`，从批次开始到结束的时间。回调在批次结束时记录它。
 * `inter_step_time`: `batch_time/inter_step (ms)`，从上一个批次结束到此批次开始的时间。回调在批次开始时记录它。一个 epoch 的第一个批次没有值。

每个时间都包括在其间隔内运行的 `nvidia-smi` 查询。

回调在 `CALLBACKS` 注册表中，因此配置可以添加它：

```yaml
trainer:
  callbacks:
    - name: GPUStatsMonitor
      params:
        temperature: true
        intra_step_time: true
```

#### 方法

##### init

```python
def __init__(memory_utilization: bool = True, gpu_utilization: bool = True, intra_step_time: bool = False, inter_step_time: bool = False, fan_speed: bool = False, temperature: bool = False):
```

使用要记录的统计信息初始化回调。

类文档字符串描述了每个统计信息。构造函数仅检查
`nvidia-smi`。[GPUStatsMonitor.setup](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gpu_stats_monitor.md)
检查记录器和 CUDA。

参数

 * `memory_utilization` (`bool`): 在批次开始和结束时记录 `memory.used`、`memory.free` 和 `utilization.memory`。
 * `gpu_utilization` (`bool`): 在批次开始和结束时记录 `utilization.gpu`。
 * `intra_step_time` (`bool`): 将从批次开始到结束的时间记录为 `batch_time/intra_step (ms)`。
 * `inter_step_time` (`bool`): 将从批次结束到下一个批次开始的时间记录为 `batch_time/inter_step (ms)`。
 * `fan_speed` (`bool`): 在批次结束时记录 `fan.speed`。
 * `temperature` (`bool`): 在批次结束时记录 `temperature.gpu` 和 `temperature.memory`。

引发

 * `MisconfigurationException`: 当 `nvidia-smi` 可执行文件不在 `PATH` 上时。消息表示 NVIDIA 驱动程序未安装。

##### is_available

```python
def is_available() -> bool:
```

返回此机器是否可以运行回调。

构造函数和
[GPUStatsMonitor.setup](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gpu_stats_monitor.md)
不会调用此方法。它们会进行自己的检查并引发错误。

返回

 * `bool`: 当 `nvidia-smi` 可执行文件在 `PATH` 上且 Lightning `CUDAAccelerator` 报告 CUDA 可用时为 `True`。

##### 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):
```

在批次结束后记录所有启用的 GPU 统计信息。

Lightning 在每个训练批次后调用此钩子。钩子仅在 rank 0 上运行。当 `inter_step_time` 开启时，钩子首先记录批次的结束时间。当训练器在此步骤上不更新其日志时，它会停止。

否则，钩子会查询 `nvidia-smi` 以获取 `gpu_utilization`、`memory_utilization`、`fan_speed` 和 `temperature` 中启用标志的统计信息。当 `intra_step_time`
开启时，钩子会添加 `batch_time/intra_step (ms)`。它使用 `trainer.logger.log_metrics` 在 `trainer.global_step` 记录值。

参数

 * `trainer` (`pl.Trainer`): 训练器。其记录器接收值。
 * `pl_module` (`pl.LightningModule`): 模型。未使用。
 * `outputs` (`STEP_OUTPUT`): 训练步骤的输出。未使用。
 * `batch` (`Any`): 批次。未使用。
 * `batch_idx` (`int`): 批次的索引。未使用。

##### on_train_batch_start

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

在批次之前记录 GPU 利用率和内存。

Lightning 在每个训练批次之前调用此钩子。钩子仅在 rank 0 上运行。当 `intra_step_time` 开启时，钩子首先记录批次的开始时间。当训练器在此步骤上不更新其日志时，它会停止。

否则，钩子会查询 `nvidia-smi` 以获取 `gpu_utilization` 和 `memory_utilization` 中启用标志的统计信息。当 `inter_step_time` 开启且上一个批次记录了其结束时间时，钩子会添加
`batch_time/inter_step (ms)`。它使用 `trainer.logger.log_metrics` 在 `trainer.global_step` 记录值。

参数

 * `trainer` (`pl.Trainer`): 训练器。其记录器接收值。
 * `pl_module` (`pl.LightningModule`): 模型。未使用。
 * `batch` (`Any`): 批次。未使用。
 * `batch_idx` (`int`): 批次的索引。未使用。

##### on_train_epoch_start

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

清除记录的批次时间。

Lightning 在每个训练 epoch 开始时，在每个 rank 上调用此钩子。由于重置，一个 epoch 的第一个批次不记录 `batch_time/inter_step (ms)` 值。

参数

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

##### setup

```python
def setup(trainer: pl.Trainer, pl_module: pl.LightningModule, stage: str | None = None):
```

检查训练器并找到要查询的 GPU。

Lightning 在每个阶段开始时调用此钩子。钩子存储训练器的排序的唯一设备索引。它通过 `CUDA_VISIBLE_DEVICES` 环境变量将每个索引映射到物理 GPU ID。当未设置该变量时，每个 GPU ID 等于其索引。

参数

 * `trainer` (`pl.Trainer`): 训练器。它必须有一个记录器。
 * `pl_module` (`pl.LightningModule`): 模型。未使用。
 * `stage` (`str | None`): 开始的阶段。未使用。

引发

 * `MisconfigurationException`: 当 `trainer` 没有记录器，或者当 CUDA 不可用时。
