Docker Model Runner チートシート: コマンドと例

Docker Model Runner コマンドのクイックリファレンス

Docker Model Runner (DMR) は、2025年4月に導入された Docker の公式ソリューションで、AIモデルをローカルで実行するためのものです。このチートシートでは、すべての必須コマンド、構成、およびベストプラクティスのクイックリファレンスを提供しています。

Docker Model Runner と Ollama、vLLM、LocalAI、クラウドプロバイダーとの比較（コストとインフラのトレードオフを含む）については、LLM ホスティング: ローカル、セルフホスト、クラウドインフラの比較 をご覧ください。

docker model runner に利用可能な gemma モデルのリスト

インストール

Docker Desktop

GUI経由で Docker Model Runner を有効にします:

  1. Docker Desktop を開きます
  2. 設定 → AI タブに移動します
  3. Docker Model Runner を有効にする をクリックします
  4. Docker Desktop を再起動します

/home/rg/prj/hugo-pers/content/post/2025/10/docker-model-runner-cheatsheet/docker-model-runner_w678.jpg docker model runner ウィンドウ

Docker Engine (Linux)

プラグインパッケージをインストールします:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-model-plugin

# Fedora/RHEL
sudo dnf install docker-model-plugin

# Arch Linux
sudo pacman -S docker-model-plugin

インストールを確認します:

docker model --help

Docker 用の NVIDIA RTX サポート

LLM を GPU で実行するようにするには、nvidia-container-toolkit をインストールします:

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

その後、--gpus all を使用してコンテナを実行できます:

docker run --rm --gpus all <image> <command>

コンテナが GPU を認識しているかを確認します:

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

Docker Model Runner 用の NVIDIA サポートを追加

Docker Model Runner では、GPU の構成を明示的に設定する必要があります。標準の docker run コマンドとは異なり、docker model run は --gpus や -e フラグをサポートしていません。代わりに、以下の手順が必要です:

  1. Docker デーモンをデフォルトで NVIDIA ランタイムを使用するように設定する

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

which nvidia-container-runtime

これは通常 /usr/bin/nvidia-container-runtime を出力します。このパスを以下の構成に使用します。

/etc/docker/daemon.json を作成または更新します:

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 を再起動します:

sudo systemctl restart docker

構成を確認します:

docker info | grep -i runtime

出力には Default Runtime: nvidia が表示されるはずです。

  1. GPU サポート付きで Docker Model Runner を再インストール

Docker Model Runner は、明示的な GPU サポート付きでインストールまたは再インストールする必要があります:

# 現在のランナーを停止
docker model stop-runner

# CUDA GPU サポート付きで再インストール
docker model reinstall-runner --gpu cuda

これにより、CPU専用バージョンではなく、CUDA エンバビルドバージョン (docker/model-runner:latest-cuda) が引き込まれます。

  1. GPU アクセスの確認

Docker Model Runner コンテナが GPU にアクセスできているかを確認します:

docker exec docker-model-runner nvidia-smi
  1. GPU でのモデルのテスト

モデルを実行し、ログを確認して GPU 使用状況を確認します:

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

ログで GPU の確認を行います:

docker model logs | grep -i cuda

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

  • using device CUDA0 (NVIDIA GeForce RTX 4080)
  • offloaded 41/41 layers to GPU
  • CUDA0 model buffer size = 10946.13 MiB

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

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

  • cuda - NVIDIA CUDA（最も一般的）
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - 自動検出（デフォルト）
  • none - CPU 限定

コアコマンド

モデルのプル

Docker Hub からパッケージ化されたモデルをプルします:

# 基本的なプル
docker model pull ai/llama2

# 特定バージョンのプル
docker model pull ai/llama2:7b-q4

# カスタムレジストリからのプル
docker model pull myregistry.com/models/mistral:latest

# ネームスペース内の利用可能なモデルを一覧表示
docker search ai/

モデルの実行

自動APIサービング付きでモデルを開始します:

# 基本的な実行（対話型）
docker model run ai/llama2 "What is Docker?"

# サービスとして実行（バックグラウンド）
docker model run -d

CLI経由でモデルを実行する際には、多くのオプションがありません:

docker model run --help
Usage:  docker model run MODEL [PROMPT]

モデルを実行し、提示されたプロンプトまたはチャットモードを使用してモデルと対話します

オプション:
      --color string                  色付き出力を使用 (auto|yes|no) (デフォルト "auto")
      --debug                         デバッグログを有効にする
  -d, --detach                        モデルをバックグラウンドでロードし、対話なし
      --ignore-runtime-memory-check   推定実行時のメモリがシステムリソースを超過してもプルをブロックしない

モデルの一覧表示

ダウンロードおよび実行中のモデルを表示します:

# すべてのダウンロードされたモデルを一覧表示
docker model ls

# 実行中のモデルを一覧表示
docker model ps

# 詳細情報を含めて一覧表示
docker model ls --json

# 詳細情報を含めて一覧表示
docker model ls --openai

# シャストハッシュコードのみを返す
docker model ls -q

モデルの削除

ローカルストレージからモデルを削除します:

# 特定のモデルを削除
docker model rm ai/llama2

# 強制削除（実行中でも）
docker model rm -f ai/llama2

# 未使用モデルを削除
docker model prune

# すべてのモデルを削除
docker model rm $(docker model ls -q)

モデルのコンテキストサイズの設定

CLIでは、特定のリクエストにコンテキストサイズを指定することはできません。

基本的に、モデルのコンテキストサイズを制御するには、以下の3つの方法があります:

  1. 自分でパッケージ化し、望むハードコードされたコンテキストサイズを指定します（次のセクションで詳しく説明します。）

  2. docker model runner の設定コマンドで --context-size パラメータを使用します:

docker model configure --context-size=10000 ai/gemma3-qat:4B

その後、curl でアクセスできますが、docker model run... は設定を無視します。

  1. docker-compose.yaml ファイルで設定できますが、docker-model-runner イメージを使用することはできません、なぜなら、ハードコードされたコンテキストサイズ4096がモデルに渡されるからです。
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

詳しくは以下の投稿をご覧ください: DMR でのコンテキストサイズの指定

カスタムモデルのパッケージ化

GGUF から OCI アーティファクトの作成

独自の GGUF モデルをパッケージ化します:

# 基本的なパッケージ化
docker model package --gguf /path/to/model.gguf myorg/mymodel:latest

# メタデータ付きでパッケージ化
docker model package \
  --gguf /path/to/model.gguf \
  --label "description=Custom Llama model" \
  --label "version=1.0" \
  myorg/mymodel:v1.0

# パッケージ化とプッシュを1つのコマンドで
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

# カスタムコンテキストサイズでパッケージ化
docker model package \
  --gguf /path/to/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

モデルの公開

レジストリにモデルをプッシュします:

# Docker Hub にログイン
docker login

# Docker Hub にプッシュ
docker model push myorg/mymodel:latest

# プライベートレジストリにプッシュ
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# タグを付けてプッシュ
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

API の使用

OpenAI 互換エンドポイント

Docker Model Runner は自動的に OpenAI 互換の API を公開します:

# API 付きでモデルを開始
docker model run -d -p 8080:8080 --name llm ai/llama2

# チャット補完
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# テキスト生成
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Once upon a time",
    "max_tokens": 100
  }'

# ストリーミング応答
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

# 利用可能なモデルをAPIで一覧表示
curl http://localhost:8080/v1/models

# モデル情報
curl http://localhost:8080/v1/models/llama2

Docker Compose 設定

基本的な Compose ファイル

version: '3.8'

services:
  llm:
    image: docker-model-runner
    model: ai/llama2:7b-q4
    ports:
      - "8080:8080"
    environment:
      - MODEL_TEMPERATURE=0.7
    volumes:
      - docker-model-runner-models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  docker-model-runner-models:
    external: true

マルチモデル設定

version: '3.8'

services:
  llama:
    image: docker-model-runner
    model: ai/llama2
    ports:
      - "8080:8080"
    
  mistral:
    image: docker-model-runner
    model: ai/mistral
    ports:
      - "8081:8080"
    
  embedding:
    image: docker-model-runner
    model: ai/nomic-embed-text
    ports:
      - "8082:8080"

より高度な Docker Compose の設定やコマンドについては、ネットワーク、ボリューム、オーケストレーションパターンをカバーした Docker Compose チートシート をご覧ください。

環境変数

モデルの動作を環境変数で設定します:

# 温度 (0.0-1.0)
MODEL_TEMPERATURE=0.7

# Top-p サンプリング
MODEL_TOP_P=0.9

# Top-k サンプリング
MODEL_TOP_K=40

# 最大トークン数
MODEL_MAX_TOKENS=2048

# GPU レイヤー数
MODEL_GPU_LAYERS=35

# バッチサイズ
MODEL_BATCH_SIZE=512

# スレッド数 (CPU)
MODEL_THREADS=8

# 詳細なログ出力を有効にする
MODEL_VERBOSE=true

# 認証用のAPIキー
MODEL_API_KEY=your-secret-key

環境変数付きで実行します:

docker model run \
  -e MODEL_TEMPERATURE=0.8 \
  -e MODEL_API_KEY=secret123 \
  ai/llama2

GPU 設定

自動GPU検出

DMR は自動的に利用可能な GPU を検出および使用します:

# すべての GPU を使用
docker model run --gpus all ai/llama2

# 特定の GPU を使用
docker model run --gpus 0 ai/llama2

# 複数の特定の GPU を使用
docker model run --gpus 0,1,2 ai/llama2

# メモリ制限付きで GPU を使用
docker model run --gpus all --memory 16g ai/llama2

CPU専用モード

GPUが利用可能でもCPUでの推論を強制します:

docker model run --no-gpu ai/llama2

多GPUテンソル並列

大規模モデルを複数のGPUに分散して実行します:

docker model run \
  --gpus all \
  --tensor-parallel 2 \
  ai/llama2-70b

見てみる・デバッグ

モデル詳細の表示

# モデル構成を確認
docker model inspect ai/llama2

# モデルレイヤーを確認
docker model history ai/llama2

# モデルサイズとメタデータを確認
docker model inspect --format='{{.Size}}' ai/llama2

ログと監視

# モデルログを表示
docker model logs llm

# 実時間でログを追跡
docker model logs -f llm

# 最後の100行を表示
docker model logs --tail 100 llm

# タイムスタンプ付きでログを表示
docker model logs -t llm

パフォーマンス統計

# リソース使用状況
docker model stats

# 特定モデルの統計
docker model stats llm

# JSON形式で統計を表示
docker model stats --format json

ネットワーキング

APIの公開

# デフォルトポート (8080)
docker model run -p 8080:8080 ai/llama2

# カスタムポート
docker model run -p 3000:8080 ai/llama2

# 特定のインターフェースにバインド
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# 複数ポート
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

ネットワーク設定

# カスタムネットワークを作成
docker network create llm-network

# カスタムネットワークでモデルを実行
docker model run --network llm-network --name llm ai/llama2

# 既存ネットワークに接続
docker model run --network host ai/llama2

セキュリティ

アクセス制御

# APIキー認証付きで実行
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

# 認証付きで使用
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama2", "messages": [...]}'

レジストリ認証

# プライベートレジストリにログイン
docker login myregistry.com -u username -p password

# プライベートレジストリからプル
docker model pull myregistry.com/private/model:latest

# 認証ヘルパーを使用
docker login --password-stdin < token.txt

ベストプラクティス

モデル選択

# より高速な推論のためにクアンティズドモデルを使用
docker model pull ai/llama2:7b-q4     # 4-bit クアンティズド
docker model pull ai/llama2:7b-q5     # 5-bit クアンティズド
docker model pull ai/llama2:7b-q8     # 8-bit クアンティズド

# モデルバリアントを確認
docker search ai/llama2

リソース管理

# メモリ制限を設定
docker model run --memory 8g --memory-swap 16g ai/llama2

# CPU 制限を設定
docker model run --cpus 4 ai/llama2

# GPU メモリを制限
docker model run --gpus all --gpu-memory 8g ai/llama2

ヘルスチェック

# ヘルスチェック付きで実行
docker model run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  ai/llama2

本番環境のオーケストレーション

Kubernetes での本番環境デプロイでは、Docker Model Runner コンテナを標準の Kubernetes マニフェストでオーケストレーションできます。リソース制限、オートスケーリング、ロードバランシングを含むデプロイメントを定義してください。包括的な Kubernetes コマンドリファレンスとデプロイメントパターンについては、Kubernetes チートシート をご覧ください。

# 例: Kubernetes クラスターにデプロイ
kubectl apply -f llm-deployment.yaml

# デプロイをスケール
kubectl scale deployment llm --replicas=3

# サービスとして公開
kubectl expose deployment llm --type=LoadBalancer --port=8080

トラブルシューティング

一般的な問題

モデルが起動しない:

# 利用可能なディスク容量を確認
df -h

# 詳細なエラーログを確認
docker model logs --tail 50 llm

# GPU の利用可能性を確認
nvidia-smi  # NVIDIA GPU の場合

メモリ不足エラー:

# より小さいクアンティズドモデルを使用
docker model pull ai/llama2:7b-q4

# コンテキストサイズを減らす
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# バッチサイズを減らす
docker model run -e MODEL_BATCH_SIZE=256 ai/llama年

推論が遅い:

# GPU 使用状況を確認
docker model stats llm

# GPU が使用されているか確認
docker model logs llm | grep -i gpu

# GPU レイヤー数を増やす
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

ディアグノスティックコマンド

# システム情報
docker model system info

# ディスク使用状況
docker model system df

# 未使用リソースをクリーンアップ
docker model system prune

# フルクリーンアップ（すべてのモデルを削除）
docker model system prune -a

インテグレーション例

Python インテグレーション

import openai

# Docker Model Runner 用のクライアントを構成
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # DMR はデフォルトでキー不要
)

# チャット補完
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

# ストリーミング
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Bash スクリプト

#!/bin/bash

# 実行中でない場合、モデルを起動
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "モデルが起動するのを待っています..."
    sleep 10
fi

# APIコール
curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "'"$1"'"}]
  }' | jq -r '.choices[0].message.content'

Node.js インテグレーション

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'http://localhost:8080/v1',
    apiKey: 'not-needed'
});

async function chat(message) {
    const completion = await client.chat.completions.create({
        model: 'llama2',
        messages: [{ role: 'user', content: message }]
    });
    
    return completion.choices[0].message.content;
}

// 使い方
const response = await chat('Docker Model Runner とは何ですか？');
console.log(response);

Docker Model Runner が Ollama、vLLM、LocalAI、クラウドプロバイダーとどのように連携するかについては、LLM ホスティング: ローカル、セルフホスト、クラウドインフラの比較 ガイドをご覧ください。

有用なリンク

公式ドキュメント

関連記事