blender-mask-peoples/docs/ultralytics-yolo-rocm-guide.md

# Ultralytics YOLO with AMD GPU (ROCm) - 完全ガイド

**取得日**: 2026-02-07
**対象**: Ultralytics YOLO (YOLOv5/YOLOv8/YOLO11)
**プラットフォーム**: AMD GPU + ROCm

---

## 目次

1. [公式サポート状況](#公式サポート状況)
2. [ROCm環境のセットアップ](#rocm環境のセットアップ)
3. [デバイス指定の正しい方法](#デバイス指定の正しい方法)
4. [Ultralytics YOLOでの使用方法](#ultralytics-yoloでの使用方法)
5. [トラブルシューティング](#トラブルシューティング)
6. [コミュニティ実装例](#コミュニティ実装例)
7. [参考資料](#参考資料)

---

## 公式サポート状況

### Ultralyticsの公式見解

**重要**: Ultralytics YOLOは現在、AMD ROCmのネイティブサポートを提供していません。

- **Issue #10323** (2024年4月25日開設、2024年6月8日に"not planned"としてクローズ)
  - Glenn Jocher氏（Ultralyticsチームメンバー）の回答:
    > "YOLOv8 primarily supports Nvidia CUDA for GPU acceleration"
  - ネイティブROCmサポートの即時計画はない
  - コミュニティによるPull Requestは歓迎

- **推奨される回避策**: PyTorchのROCm互換性レイヤーを使用

### 使用可能な選択肢

1. **PyTorch ROCmバックエンド経由** (非公式だが実用可能)
2. **Dockerコンテナを使用した環境分離**
3. **クラウドGPUレンタル** (NVIDIA GPU使用)
4. **ONNXエクスポート + AMD推論エンジン**

---

## ROCm環境のセットアップ

### 1. ROCmサポート確認

#### 対応GPU

- **Instinctシリーズ**: MI100 (gfx908), MI210/MI250/MI250x (gfx90a), MI300A/MI300X/MI325 (gfx942), MI350/MI355 (gfx950)
- **Radeon RXシリーズ**: RX 7900 GRE以上、一部のRX 6000シリーズ (gfx1030, gfx1100/1101, gfx1200/1201)
- **統合GPU**: 一部のRyzen APU (環境変数による回避策が必要)

#### GPU情報の確認

```bash
rocminfo | grep gfx
```

### 2. PyTorch ROCmのインストール

#### 方法A: Dockerイメージ（推奨）

AMDが検証済みのDockerイメージを使用:

```bash
# 最新イメージの取得
docker pull rocm/pytorch:latest

# コンテナの起動
docker run -it \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --device=/dev/kfd \
    --device=/dev/dri \
    --group-add video \
    --ipc=host \
    --shm-size 8G \
    rocm/pytorch:latest
```

**利用可能なタグ（ROCm 7.2.0時点）**:
- PyTorch 2.9.1 + Python 3.12/3.10
- PyTorch 2.8.0 + Python 3.12/3.10
- PyTorch 2.7.1 + Python 3.12/3.10

#### 方法B: Wheelパッケージ（ベアメタル）

```bash
# 依存関係のインストール
sudo apt install libjpeg-dev python3-dev python3-pip

# PyTorch ROCmのインストール
pip3 install --pre torch torchvision torchaudio \
    --index-url https://download.pytorch.org/whl/nightly/rocm7.0
```

**注意**: AMDは`repo.radeon.com`で提供されるWHLの使用を推奨（PyTorch.orgのnightly buildsは頻繁に変更されテストが不十分）

#### 方法C: ソースからビルド

```bash
git clone https://github.com/pytorch/pytorch.git
cd pytorch
git submodule update --init --recursive

# GPUアーキテクチャを指定
export PYTORCH_ROCM_ARCH=gfx90a  # 例: MI210/MI250の場合

# ビルド手順に従う
# (pytorch/pytorch リポジトリのREADME参照)
```

### 3. インストールの確認

```bash
python3 -c 'import torch; print(torch.cuda.is_available())'
# 出力: True (GPUが利用可能な場合)

python3 -c 'import torch; print(torch.version.hip)'
# 出力: ROCmバージョン（例: '5.7.31921'）
```

---

## デバイス指定の正しい方法

### 重要な概念

**PyTorch ROCmは意図的にCUDAインターフェースを再利用**します。これにより、コード変更を最小限に抑えています。

### 基本的なデバイス指定

```python
import torch

# デフォルトのGPUデバイス
cuda = torch.device('cuda')

# 特定のGPUデバイス
cuda0 = torch.device('cuda:0')  # GPU 0
cuda1 = torch.device('cuda:1')  # GPU 1
cuda2 = torch.device('cuda:2')  # GPU 2
```

**注意**: `"rocm"`や`"hip"`は無効なデバイス文字列です。必ず`"cuda"`を使用してください。

### HIP vs CUDAの検出

```python
import torch

if torch.cuda.is_available():
    if torch.version.hip:
        print("Running on AMD GPU with ROCm/HIP")
        print(f"ROCm version: {torch.version.hip}")
    elif torch.version.cuda:
        print("Running on NVIDIA GPU with CUDA")
        print(f"CUDA version: {torch.version.cuda}")
else:
    print("No GPU available")
```

### Ultralytics YOLOでのデバイス指定

Ultralytics APIを使用する場合:

```python
from ultralytics import YOLO

# モデルの読み込み
model = YOLO('yolov8n.pt')

# 推論時のデバイス指定
# 方法1: 文字列で指定
results = model.predict('image.jpg', device='cuda:0')

# 方法2: 整数で指定（GPU番号）
results = model.predict('image.jpg', device=0)

# 方法3: CPUを使用
results = model.predict('image.jpg', device='cpu')

# トレーニング時のデバイス指定
model.train(data='coco.yaml', epochs=100, device=0)
```

---

## Ultralytics YOLOでの使用方法

### 基本的な推論

```python
from ultralytics import YOLO
import torch

# GPU確認
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"ROCm version: {torch.version.hip if torch.version.hip else 'N/A'}")

# モデルのロード
model = YOLO('yolov8n.pt')

# 推論の実行
results = model('path/to/image.jpg', device=0)

# 結果の処理
for result in results:
    boxes = result.boxes  # Boxes object
    masks = result.masks  # Masks object (セグメンテーションの場合)
    probs = result.probs  # 分類の場合
```

### バッチ処理

```python
from ultralytics import YOLO
from pathlib import Path

model = YOLO('yolov8n.pt')

# 画像リストで推論
image_folder = Path('path/to/images')
image_paths = list(image_folder.glob('*.jpg'))

# バッチサイズを指定して推論
results = model.predict(image_paths, device=0, batch=16)

for i, result in enumerate(results):
    result.save(filename=f'result_{i}.jpg')
```

### トレーニング

```python
from ultralytics import YOLO

# モデルの作成
model = YOLO('yolov8n.yaml')

# トレーニングの実行
results = model.train(
    data='coco.yaml',
    epochs=100,
    imgsz=640,
    device=0,  # AMD GPUを使用
    batch=16,
    workers=8
)
```

### モデルのエクスポート（ONNX）

AMD環境での推論最適化のため、ONNXにエクスポート:

```python
from ultralytics import YOLO

model = YOLO('yolov8n.pt')

# ONNXフォーマットにエクスポート
model.export(format='onnx', dynamic=True)
```

エクスポート後、AMD MIGraphXで最適化:

```bash
migraphx-driver compile ./yolov8n.onnx \
    --optimize \
    --gpu \
    --enable-offload-copy \
    --binary \
    -o yolov8n.mxr
```

---

## トラブルシューティング

### 1. GPU認識されない

#### 症状
```python
torch.cuda.is_available()  # False
```

#### 解決策

**ユーザー権限の確認**:
```bash
# ユーザーを適切なグループに追加
sudo usermod -a -G video $USER
sudo usermod -a -G render $USER

# 再ログインして反映
```

**デバイスアクセスの確認**:
```bash
ls -la /dev/kfd /dev/dri/
```

**ROCmインストールの確認**:
```bash
rocm-smi
# GPUリストが表示されるはず
```

### 2. hipErrorNoBinaryForGpu

#### 症状
```
RuntimeError: HIP error: hipErrorNoBinaryForGpu
```

#### 原因
PyTorchが対象GPUアーキテクチャ用にコンパイルされていない

#### 解決策

**GPUアーキテクチャの確認**:
```bash
rocminfo | grep gfx
```

**環境変数による回避** (統合GPUやサポート外GPU):
```bash
# gfx90cの場合、gfx900として認識させる
export HSA_OVERRIDE_GFX_VERSION=9.0.0

# 再度Pythonを実行
python3 your_script.py
```

**ソースからビルドする場合**:
```bash
export PYTORCH_ROCM_ARCH=gfx1030  # 自分のGPUアーキテクチャを指定
# PyTorchをビルド
```

### 3. GPU転送のハング/失敗

#### 症状
- スクリプトが無言でハング
- GPU-CPU間のデータ転送が失敗

#### 解決策

**PCIe Atomicsサポートの問題** (コンシューマー向けマザーボード):

```bash
# SDMA（ダイレクトメモリアクセス）を無効化
export HSA_ENABLE_SDMA=0

python3 your_script.py
```

この設定なしでは「GPU memory transfers will silently hang/fail」する可能性があります。

### 4. ROCmバージョンの非互換性

#### 症状
```
ImportError: libMIOpen.so.1: cannot open shared object file
```

#### 解決策

**特定バージョンのROCmを使用**:
- ROCm 5.7が推奨される場合が多い
- ROCm 6.0.0は一部環境で動作しない報告あり

**Dockerイメージを使用**してバージョンを固定:
```bash
docker pull rocm/pytorch:rocm5.7_ubuntu22.04_py3.10_pytorch_2.0.1
```

### 5. メモリ不足エラー

#### 症状
```
RuntimeError: HIP out of memory
```

#### 解決策

**メモリ使用状況の確認**:
```python
import torch

print(f"Allocated: {torch.cuda.memory_allocated() / 1024**3:.2f} GB")
print(f"Reserved: {torch.cuda.memory_reserved() / 1024**3:.2f} GB")
```

**キャッシュのクリア**:
```python
torch.cuda.empty_cache()
```

**バッチサイズの削減**:
```python
model.train(data='coco.yaml', batch=8)  # デフォルトより小さく
```

**キャッシュアロケータの無効化** (デバッグ用):
```bash
export PYTORCH_NO_HIP_MEMORY_CACHING=1
```

### 6. パフォーマンスが遅い

#### 最適化のヒント

**hipBLASワークスペースの調整**:
```bash
# デフォルトは32 MiB、MI300+は128 MiB
export HIPBLAS_WORKSPACE_CONFIG=128M
```

**Composable Kernelの有効化** (対応GPU):
```python
import torch
torch.backends.cuda.matmul.allow_tf32 = True  # TF32はROCmで非対応
```

**混合精度トレーニング**:
```python
from ultralytics import YOLO

model = YOLO('yolov8n.pt')
model.train(
    data='coco.yaml',
    epochs=100,
    amp=True,  # Automatic Mixed Precision
    device=0
)
```

---

## コミュニティ実装例

### AMD統合GPU向けYOLOv8実装

GitHub: [harakas/amd_igpu_yolo_v8](https://github.com/harakas/amd_igpu_yolo_v8)

#### 主な特徴

- DockerベースのROCm + PyTorch環境
- 統合GPUに特化した環境変数設定
- YOLOv5/YOLOv8の推論例
- MIGraphXを使った本番デプロイ

#### セットアップ例

```bash
# Dockerイメージのビルド
docker build -t rocm-pytorch .

# ラッパースクリプトでPythonを実行
./rocm_python yolo8.py
```

#### 必須環境変数

```bash
# PCIe Atomics非サポート対策
export HSA_ENABLE_SDMA=0

# GPUアーキテクチャのオーバーライド
export HSA_OVERRIDE_GFX_VERSION=9.0.0  # gfx90cの場合
```

#### パフォーマンス実測値

**テスト環境**: AMD Ryzen 3 5400U (統合GPU)

- YOLOv8n (640x640): 約50 FPS (0.02秒/画像)
- YOLOv8n (320x320): 約140 FPS

#### MIGraphXデプロイ

```bash
# 1. ONNXエクスポート
python3 -c "from ultralytics import YOLO; YOLO('yolov8n.pt').export(format='onnx')"

# 2. MIGraphXバイナリにコンパイル
migraphx-driver compile ./yolov8n.onnx \
    --optimize \
    --gpu \
    --enable-offload-copy \
    --binary \
    -o yolov8n.mxr

# 3. MIGraphX Python APIで推論
# (PyTorch依存なし、高速化)
```

---

## 制限事項と注意点

### PyTorch ROCmの制限

1. **TensorFloat-32 (TF32)**: ROCmでは非対応
2. **分散トレーニング**: NCCLとGlooバックエンドのみサポート
3. **hipFFT/rocFFT**: プランキャッシュサイズの設定は非サポート

### Ultralytics YOLO固有の問題

1. **公式サポートなし**: AMDからの技術サポートは期待できない
2. **パフォーマンス**: NVIDIA CUDAと比較して遅い場合がある
3. **互換性**: 全機能が動作する保証はない（特に新機能）

### 推奨される使用ケース

**ROCmが適している場合**:
- 既にAMD GPUを所有している
- 開発/テスト環境
- 小～中規模のデータセット

**クラウドGPUを検討すべき場合**:
- 本番環境での大規模トレーニング
- 最高のパフォーマンスが必要
- 公式サポートが必要

---

## 完全な動作例

### 統合GPU環境での推論スクリプト

```python
#!/usr/bin/env python3
"""
AMD GPU (ROCm) 向け Ultralytics YOLO 推論スクリプト
"""
import os
import torch
from ultralytics import YOLO

# 必須環境変数の設定（統合GPUの場合）
os.environ['HSA_ENABLE_SDMA'] = '0'
os.environ['HSA_OVERRIDE_GFX_VERSION'] = '9.0.0'  # 自分のGPUに合わせて調整

def check_gpu():
    """GPU利用可能性の確認"""
    print("=" * 50)
    print("GPU情報")
    print("=" * 50)
    print(f"CUDA available: {torch.cuda.is_available()}")
    if torch.cuda.is_available():
        print(f"GPU count: {torch.cuda.device_count()}")
        print(f"Current device: {torch.cuda.current_device()}")
        print(f"Device name: {torch.cuda.get_device_name(0)}")
        print(f"ROCm version: {torch.version.hip}")
        print(f"Memory allocated: {torch.cuda.memory_allocated() / 1024**3:.2f} GB")
        print(f"Memory reserved: {torch.cuda.memory_reserved() / 1024**3:.2f} GB")
    print("=" * 50)

def main():
    # GPU確認
    check_gpu()

    if not torch.cuda.is_available():
        print("警告: GPUが利用できません。CPUで実行します。")
        device = 'cpu'
    else:
        device = 0  # GPU 0を使用

    # モデルのロード
    print(f"\nモデルをロード中... (device={device})")
    model = YOLO('yolov8n.pt')

    # 推論の実行
    print("\n推論を実行中...")
    results = model.predict(
        source='path/to/image.jpg',
        device=device,
        conf=0.25,
        iou=0.7,
        imgsz=640,
        save=True,
        save_txt=True
    )

    # 結果の表示
    for i, result in enumerate(results):
        print(f"\n結果 {i+1}:")
        print(f"  検出数: {len(result.boxes)}")
        print(f"  処理時間: {result.speed['inference']:.2f}ms")

        # ボックス情報
        for box in result.boxes:
            cls = int(box.cls[0])
            conf = float(box.conf[0])
            print(f"    クラス: {model.names[cls]}, 信頼度: {conf:.2f}")

    # メモリ解放
    torch.cuda.empty_cache()
    print("\n完了!")

if __name__ == '__main__':
    main()
```

### Dockerを使った実行例

```dockerfile
# Dockerfile
FROM rocm/pytorch:rocm5.7_ubuntu22.04_py3.10_pytorch_2.0.1

# Ultralyticsのインストール
RUN pip install ultralytics opencv-python

# 作業ディレクトリ
WORKDIR /workspace

# 環境変数の設定
ENV HSA_ENABLE_SDMA=0
ENV HSA_OVERRIDE_GFX_VERSION=9.0.0

CMD ["/bin/bash"]
```

```bash
# ビルドと実行
docker build -t yolo-rocm .

docker run -it --rm \
    --device=/dev/kfd \
    --device=/dev/dri \
    --group-add video \
    --ipc=host \
    --shm-size 8G \
    -v $(pwd):/workspace \
    yolo-rocm \
    python3 inference.py
```

---

## 参考資料

### 公式ドキュメント

- [PyTorch HIP (ROCm) Semantics](https://docs.pytorch.org/docs/stable/notes/hip.html)
- [PyTorch on ROCm Installation](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/3rd-party/pytorch-install.html)
- [ROCm PyTorch Compatibility](https://rocm.docs.amd.com/en/latest/compatibility/ml-compatibility/pytorch-compatibility.html)
- [Ultralytics YOLO Documentation](https://docs.ultralytics.com/)

### GitHub Issues & Discussions

- [AMD GPU support and optimisation - YOLOv5 #2995](https://github.com/ultralytics/yolov5/issues/2995)
- [Direct support for AMD GPUs/ROCm - Ultralytics #10323](https://github.com/ultralytics/ultralytics/issues/10323)
- [Running YOLOV8 on non CUDA GPU - Discussion #10066](https://github.com/orgs/ultralytics/discussions/10066)

### コミュニティリソース

- [harakas/amd_igpu_yolo_v8](https://github.com/harakas/amd_igpu_yolo_v8) - AMD統合GPU向け実装例
- [ROCm Docker Hub](https://hub.docker.com/r/rocm/pytorch) - 公式Dockerイメージ
- [PyTorch for AMD ROCm Platform Blog](https://pytorch.org/blog/pytorch-for-amd-rocm-platform-now-available-as-python-package/)

### トラブルシューティングリソース

- [How to run torch with AMD gpu? - PyTorch Forums](https://discuss.pytorch.org/t/how-to-run-torch-with-amd-gpu/157069)
- [Install AMD GPU ROCm and PyTorch on Ubuntu - GitHub Gist](https://gist.github.com/jurgonaut/462a6bd9b87ed085fa0fe6c893536993)

---

## まとめ

### 重要なポイント

1. **公式サポートなし**: Ultralytics YOLOはROCmをネイティブサポートしていないが、PyTorchのROCmバックエンド経由で動作可能

2. **デバイス指定**: `device='cuda'` または `device=0` を使用（`'rocm'`や`'hip'`は無効）

3. **環境変数が重要**: 統合GPUや一部のコンシューマーGPUでは `HSA_ENABLE_SDMA=0` と `HSA_OVERRIDE_GFX_VERSION` が必須

4. **Dockerが推奨**: 環境の一貫性とトラブル回避のため、公式ROCm PyTorchイメージの使用を推奨

5. **パフォーマンス**: NVIDIA CUDAより遅い場合があるが、小～中規模の用途では実用的

### 次のステップ

- 自分のGPUアーキテクチャを確認 (`rocminfo | grep gfx`)
- Docker環境でテスト推論を実行
- パフォーマンスが不十分な場合はONNX + MIGraphXを検討
- 本番環境ではクラウドGPUの使用を検討

---

**ドキュメント作成**: Claude Code (Sonnet 4.5)
**最終更新**: 2026-02-07