DockerモデルランナーにNVIDIA GPUサポートを追加する

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

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

LLMホスティングソリューションでGPU設定が簡単な代替案を探している場合は、Ollama を検討してください。これは、組み込みのGPUサポートと簡単なセットアップを提供しています。ただし、Docker Model RunnerはDockerエコシステムおよびOCIアーティファクト配布との統合がより良いです。

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

事前準備

GPUサポートを構成する前に、以下のものを確認してください：

• NVIDIA GPU に互換性のあるドライバがインストールされている。AIワークロードに適したGPUの選択方法については、NVIDIA GPU仕様のAIへの適応性比較 をご参照ください。
• NVIDIA Container Toolkit がインストールされている（[NVIDIA RTXサポートセクション](https://www.glukhov.org/ja/post/2025/10/docker-model-runner-cheatsheet/#nvidia-rtx-support-for-docker “Docker向け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

以下のようなメッセージが表示されるはずです：

• 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 auto ではなく --gpu cuda を使用して、正しい構成を保証してください。

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

3. GPU使用を監視してください: モデル推論中に nvidia-smi を使用して、GPUメモリと利用率を監視してください。より高度な監視ツールについては、Linux / UbuntuでのGPU監視アプリケーション をご参照ください。

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

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

有用なリンク

• Docker Model Runner Cheatsheet
• Docker Model Runner公式ドキュメント
• NVIDIA Container Toolkitインストールガイド
• Docker Model Runner vs Ollama比較
• Ollama Cheatsheet - 内蔵GPUサポート付きのLLMホスティングソリューションの代替案
• Docker Cheatsheet - Dockerコマンドと構成の完全なリファレンス
• Linux / UbuntuでのGPU監視アプリケーション - NVIDIA GPU監視ツールの一覧と比較
• NVIDIA GPU仕様のAIへの適応性比較 - AIワークロードに適したGPUの選択ガイド