# PyTorch アクセラレータ

LeRobotは、学習と推論の両方で複数のハードウェアアクセラレーションオプションをサポートしています。

これらのオプションには、以下が含まれます。

- **CPU**: CPU がすべての計算を実行し、専用のアクセラレーターは使用されません
- **CUDA**: NVIDIA GPU による高速化、および ROCm 経由での AMD GPU による高速化（[AMD GPU](#amd-gpus-rocm)を参照）
- **MPS**: Apple Silicon GPUによる高速化
- **XPU**: Intel統合GPUおよびディスクリートGPUによるアクセラレーション

## はじめる

特定のアクセラレータを使用するには、適切なバージョンのPyTorchをインストールする必要があります。

CPU、CUDA、MPSバックエンドについては、[PyTorchのインストールページ](https://pytorch.org/get-started/locally)の指示に従ってください。XPUバックエンドについては、[PyTorchのドキュメント](https://docs.pytorch.org/docs/stable/notes/get_start_xpu.html)の指示に従ってください。

### AMD GPU (ROCm)

PyTorch の ROCm ビルドは HIP ランタイムを `torch.cuda` 名前空間経由で公開するため、`--policy.device=cuda` を指定すると AMD GPU が選択され、LeRobot 側の修正は不要です。特定のカードを選択する場合は、`CUDA_VISIBLE_DEVICES` よりも `HIP_VISIBLE_DEVICES` を優先してください。

既存のROCm PyTorch環境の上にLeRobotをインストールする際は注意が必要です。LeRobotの`torch`、`torchvision`、`numpy`のバージョン制約は、ROCmイメージに同梱されているものとは異なる場合があります。また、通常のインストールではPyPIからtorchを取得しますが、PyPIのLinux向けホイールはCUDAビルドであるため、制約なしでインストールするとROCmビルドが上書きされ、GPUが使用できなくなります。そのため、`uv pip install --override`でこれらのパッケージを固定し、ツリーの残りの依存関係が正常に解決されるようにしてください。[`docker/Dockerfile.rocm`](https://github.com/huggingface/lerobot/blob/main/docker/Dockerfile.rocm)はこの処理を行っており、動作する環境を構築する最速の方法です。ROCmに必要な実行フラグについては、[docker/README.md](https://github.com/huggingface/lerobot/blob/main/docker/README.md)を参照してください。

### インストールの検証

インストール後、accelerateの可用性を確認するには、以下を実行します。

```python
import torch
print(torch.<backend_name>.is_available())  # <backend_name> is cuda, mps, or xpu
```

## トレーニングまたは評価の実行方法

希望するアクセラレーターを選択するには、`lerobot-train`または`lerobot-eval`を実行する際に`--policy.device`フラグを使用します。例えば、Apple SiliconでMPSを使用するには、以下を実行します:

```bash
lerobot-train \
    --policy.device=mps ...
```

```bash
lerobot-eval \
    --policy.device=mps ...
```

ただし、ほとんどの場合、アクセラレーターの存在は自動的に検出されるため、CLIコマンドから`policy.device`パラメータを省略できます。

## 混合精度

トレーニングの精度は`--accelerator.mixed_precision`によって管理され、`no`(デフォルト)、`bf16`、`fp16`を受け入れます:

```bash
lerobot-train \
    --policy.type=act \
    --accelerator.mixed_precision=bf16 ...
```

`fp16` はアクセラレータが必要です。`--policy.device=cpu` では拒否されます。この場合、accelerate はロススケーラーを構築せず、実行がサイレントにフル精度にフォールバックしてしまうためです。`bf16` は CPU でもオートキャストされるため、制限はありません。

`bf16`にはハードウェアのサポート（NVIDIA GPUではAmpere以降）が必要です。V100やT4などの古いアクセラレーターでは、`fp16`を使用してください。

### fp16とロススケーラー

`fp16`は`bf16`よりも指数部の範囲がはるかに狭いため、バックワードパスの前に勾配をスケールアップし、オプティマイザーステップの前にスケールダウンします。LeRobotはこの処理をaccelerateの`GradScaler`に委譲しており、これにより勾配のオーバーフローを検出し、該当するオプティマイザの更新をスキップします。シャード化された学習では勾配は`DTensor`となり、PyTorchがデバイスメッシュ全体でオーバーフローフラグをリダクションするため、あるランクでオーバーフローが発生すると、すべてのランクで更新がスキップされます。

更新がスキップされるのは正常な動作であり、特に初期値からスケールが調整される最初の数ステップではよく見られます。ログでは、`scale`メトリックの低下として確認できます。スケールはすべてのチェックポイント（`training_state/scaler_state.json`）に保存され、再開時に復元されるため、再開した実行では再調整を行う必要はありません。

デフォルトがポリシーに合わない場合は、スケーラーを調整できます:

```bash
lerobot-train \
    --policy.type=act \
    --accelerator.mixed_precision=fp16 \
    --accelerator.grad_scaler.init_scale=1024 \
    --accelerator.grad_scaler.growth_interval=2000 ...
```

### TF32

Ampere 以降の NVIDIA GPU では、LeRobot はデフォルトで float32 の行列積および cuDNN の畳み込みに TF32 を使用します（`--tf32=true`）。`--tf32=false` を使用すると、これらは完全な float32 精度で保持されます。また、`--tf32=null` を使用すると、PyTorch のデフォルト設定が維持されます。

