DockerモデルランナーへのNVIDIA GPUサポートの追加

Docker Model Runner は、Dockerが公式に提供するローカルでAIモデルを実行するためのツールですが、
Docker Model RunnerにおけるNVidia GPUの加速の有効化 には特定の設定が必要です。

標準の docker run コマンドとは異なり、docker model run は --gpus や -e のフラグをサポートしていません。そのため、GPUのサポートはDockerデーモンレベルおよびランナーのインストール時に設定する必要があります。

もし、GPUの設定がより簡単なLLMホスティングソリューションを探している場合は、Ollama をご検討ください。Ollamaは、組み込みのGPUサポートとシンプルなセットアップを提供しています。ただし、Docker Model RunnerはDockerエコシステムおよびOCIアーティファクト配布との統合性が優れています。Docker Model RunnerとOllama、vLLM、LocalAI、クラウドプロバイダーとの比較（コストやインフラのトレードオフを含む）については、LLMホスティング：ローカル、セルフホスト、クラウドインフラの比較 をご参照ください。

この美しい画像は、AIモデルFlux 1 dev によって生成されました。

事前条件

GPUサポートの設定を行う前に、以下のものをご確認ください：

• NVIDIA GPU および、AIワークロードに適したドライバーがインストールされている必要があります。AIワークロードに適したNVIDIA GPUの選定方法については、NVIDIA GPUの仕様とAIへの適応性の比較 をご参照ください。
• NVIDIA Container Toolkit がインストールされている必要があります（NVIDIA RTXサポートセクション をご参照ください）。
• Docker Model Runner がインストールされている必要があります（GPUサポート付きで再インストール可能です）。

GPUがアクセス可能かを確認してください：

nvidia-smi

DockerのGPUアクセスをテストしてください：

docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi

Dockerコマンドや設定オプションについてさらに詳しく知りたい場合は、Docker Cheatsheet をご参照ください。

手順1：NVIDIAランタイムをデフォルトに設定するDockerデーモンの構成

Docker Model Runnerは、Dockerデーモン設定でNVIDIAランタイムをデフォルトとして設定する必要があります。

NVIDIA Container Runtimeのパスの確認

まず、nvidia-container-runtime がインストールされている場所を確認してください：

which nvidia-container-runtime

このコマンドは通常 /usr/bin/nvidia-container-runtime を出力します。このパスを次の手順で使用してください。

Dockerデーモンの構成

/etc/docker/daemon.json を作成または更新し、NVIDIAをデフォルトのランタイムに設定してください：

sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
EOF

重要: which nvidia-container-runtime が別のパスを返した場合は、JSON構成ファイルの "path" 値をそれに合わせて更新してください。

Dockerサービスの再起動

設定を反映するためにDockerを再起動してください：

sudo systemctl restart docker

設定の確認

NVIDIAランタイムが設定されているかを確認してください：

docker info | grep -i runtime

出力には Default Runtime: nvidia が表示される必要があります。

手順2：GPUサポート付きDocker Model Runnerのインストール

Docker Model Runnerは、明示的なGPUサポート付きでインストールまたは再インストールする必要があります。ランナーコンテナ自体はCUDA対応のバージョンである必要があります。

現在のランナーを停止（実行中であれば）

Docker Model Runnerが既にインストールされている場合は、まず停止してください：

docker model stop-runner

CUDAサポート付きでインストール/再インストール

CUDA GPUサポート付きでDocker Model Runnerをインストールまたは再インストールしてください：

docker model reinstall-runner --gpu cuda

このコマンドは以下の処理を行います：

• CPU専用バージョンではなく、CUDA対応バージョン（docker/model-runner:latest-cuda）をプルします。
• ランナーコンテナをNVIDIAランタイムで構成します。
• すべてのモデルにGPU加速を有効にします。

注意: すでにGPUサポートなしでDocker Model Runnerをインストールした場合、--gpu cuda フラグで再インストールする必要があります。Dockerデーモンの設定だけでは十分ではなく、ランナーコンテナ自体がCUDA対応バージョンである必要があります。

利用可能なGPUバックエンド

Docker Model Runnerは複数のGPUバックエンドをサポートしています：

• cuda - NVIDIA CUDA（NVIDIA GPUで最も一般的）
• rocm - AMD ROCm（AMD GPU用）
• musa - Moore Threads MUSA
• cann - Huawei CANN
• auto - 自動検出（デフォルト、正しく動作しない可能性あり）
• none - CPU専用

NVIDIA GPUでは常に --gpu cuda を明示的に指定してください。

手順3：GPUアクセスの確認

インストール後、Docker Model RunnerがGPUにアクセスできるかを確認してください。

ランナーコンテナのGPUアクセスの確認

Docker Model Runnerコンテナ内からGPUアクセスをテストしてください：

docker exec docker-model-runner nvidia-smi

このコマンドは、GPU情報が表示され、コンテナがGPUにアクセスできていることを確認できます。

ランナーのステータスの確認

Docker Model Runnerが実行されているかを確認してください：

docker model status

ランナーがアクティブで、llama.cppサポートがあることを確認してください。

手順4：GPUを使用したモデルのテスト

モデルを実行し、GPUを使用していることを確認してください。

モデルの実行

モデルの推論を開始してください：

docker model run ai/qwen3:14B-Q6_K "who are you?"

ログでのGPU使用の確認

Docker Model RunnerのログでGPU使用を確認してください：

docker model logs | grep -i cuda

GPU使用に関するメッセージが表示される必要があります：

• using device CUDA0 (NVIDIA GeForce RTX 4080) - GPUデバイスが検出された
• offloaded 41/41 layers to GPU - モデルのレイヤーがGPUにロードされた
• CUDA0 model buffer size = 10946.13 MiB - GPUメモリの割り当て
• CUDA0 KV buffer size = 640.00 MiB - GPU上のキーバリューキャッシュ
• CUDA0 compute buffer size = 306.75 MiB - GPU上のコンピュートバッファ

GPU使用のモニタリング

別のターミナルで、リアルタイムでGPU使用状況をモニタリングしてください：

nvidia-smi -l 1

モデルが実行されている間、GPUメモリ使用量と利用率が増加する必要があります。

より高度なGPUモニタリングオプションやツールについては、Linux / UbuntuにおけるGPUモニタリングアプリケーション のガイドをご参照ください。

トラブルシューティング

モデルがCPUを使用している

モデルがまだCPUを使用している場合：

1. Dockerデーモン構成を確認:

   docker info | grep -i runtime
   

   Default Runtime: nvidia が表示される必要があります。

2. ランナーコンテナのランタイムを確認:

   docker inspect docker-model-runner | grep -A 2 '"Runtime"'
   

   "Runtime": "nvidia" が表示される必要があります。

3. GPUサポート付きでランナーを再インストール:

   docker model reinstall-runner --gpu cuda
   

4. エラーの確認:

   docker model logs | tail -50
   

GPUが検出されない

GPUが検出されない場合：

1. NVIDIA Container Toolkitがインストールされているかを確認:

   dpkg -l | grep nvidia-container-toolkit
   

2. 標準DockerでGPUアクセスをテスト:

   docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi
   

   Dockerのトラブルシューティングについては、Docker Cheatsheet をご参照ください。

3. NVIDIAドライバーを確認:

   nvidia-smi
   

パフォーマンス問題

GPUパフォーマンスが悪い場合：

1. GPU利用率を確認:

   nvidia-smi
   

   高いGPU利用率のパーセンテージを確認してください。

2. モデルのレイヤーがGPUにあるかを確認:

   docker model logs | grep "offloaded.*layers to GPU"
   

   すべてのレイヤーがGPUにロードされている必要があります。

3. メモリ問題を確認:

   nvidia-smi
   

   GPUメモリが枯渇していないか確認してください。

ベストプラクティス

1. GPUバックエンドを明示的に指定: NVIDIA GPUでは --gpu cuda を --gpu auto ではなく使用し、正しい構成を保証してください。

2. 変更後は構成を確認: Dockerデーモン設定を変更した後は常に docker info | grep -i runtime を確認してください。

3. GPU使用状況をモニタリング: モデル推論中に nvidia-smi を使用してGPUメモリおよび利用率をモニタリングしてください。より高度なモニタリングツールについては、Linux / UbuntuにおけるGPUモニタリングアプリケーション のガイドをご参照ください。

4. ログを定期的に確認: docker model logs を確認し、モデルがGPU加速を使用していることを確認してください。

5. 適切なモデルサイズを使用: GPUに十分なメモリがあることを確認し、Q4、Q5、Q6、Q8のクアンタイズモデルを使用してGPUメモリ効率を向上させましょう。AIワークロードに適したNVIDIA GPUの選定方法については、NVIDIA GPUの仕様とAIへの適応性の比較 をご参照ください。

GPUサポートが有効になった後、Docker Model RunnerはLLMをローカルで実行する方法の一つです。Ollama、vLLM、クラウドAPI、その他のオプションとの関係について確認するには、LLMホスティング：ローカル、セルフホスト、クラウドインフラの比較 のガイドをご参照ください。

有用なリンク

• Docker Model Runner Cheatsheet
• Docker Model Runner公式ドキュメント
• NVIDIA Container Toolkitインストールガイド
• Docker Model RunnerとOllamaの比較
• Docker Cheatsheet - Dockerコマンドと設定の完全なリファレンス
• Linux / UbuntuにおけるGPUモニタリングアプリケーション - NVIDIA GPUモニタリングツールのリストおよび比較
• NVIDIA GPUの仕様とAIへの適応性の比較 - AIワークロードに適したGPUの選定ガイド