docker-ai-ml

Docker AI/ML — AI ワークロード

Docker で AI モデルとエージェントを実行するためのガイダンスです。

使用するタイミング

ユーザーが次の内容に言及した場合は、必ずこのスキルを使用してください：

• 「docker ai」、「docker model」、「model runner」
• 「ローカル LLM」、「local model」、「offline model」
• 「docker agent」、「AI agent」
• 「GPU docker」、「nvidia docker」
• 「sandbox」、「サンドボックス」
• 「LLM のデプロイ」、「モデルのデプロイ」

Docker Model Runner

# List available models
docker model ls

# Pull a model
docker model pull ai/gemma3
docker model pull ai/qwen2.5

# Run inference
docker model run ai/gemma3 "Explain Docker in one sentence"

# Interactive chat
docker model run -i ai/gemma3

# API server mode
docker model serve ai/gemma3 --port 11434
# → access at http://localhost:11434/v1

AI コーディングアシスタント向けのスキルをインストールする

# Install skills for Claude Code
docker model skills --claude

# For Codex CLI
docker model skills --codex

GPU の設定

# Install NVIDIA Container Toolkit (once)
# Ubuntu/Debian:
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

# Run with GPU access
docker run --gpus all -it nvidia/cuda:12.6-base nvidia-smi

# Specific GPU
docker run --gpus device=0 -it nvidia/cuda:12.6-base

# GPU + Model Runner
docker model run --gpus all ai/llama3.2

Docker Agent

# agent.yaml — Define a multi-agent system
name: my-coding-agent
model:
  provider: openai
  model: gpt-4o
tools:
  - write_file
  - execute_command
  - web_search
sandbox:
  image: node:22-alpine
  workdir: /workspace

# Run agent with Docker
docker agent run -f agent.yaml "Fix the bug in src/app.js"

Docker Sandbox

# Isolated execution environment for AI agents
sandbox:
  image: python:3.12-slim
  network: none          # No network access
  read_only: true        # Read-only filesystem
  memory: 512m
  cpus: 1

ローカル LLM スタック

# Ollama (open-source) as alternative
docker run -d --name ollama \
  -p 11434:11434 \
  -v ollama_data:/root/.ollama \
  --gpus all \
  ollama/ollama

# Download and run model
docker exec ollama ollama pull llama3.2
docker exec ollama ollama run llama3.2 "Hello"

ワークフロー — 推奨ワークフロー

ステップ 1：推論方法を選択する：Docker Model Runner（docker model）を優先し、Ollama は代替として使用します ステップ 2：ハードウェアを確認する：GPU の使用には Linux + nvidia-container-toolkit が必要です。CPU 推論には 8-32GB の RAM が必要です ステップ 3：モデルをプルする：docker model pull <model> または ollama pull <model> ステップ 4：サービスを起動する：docker model run または ollama serve + クライアント ステップ 5：検証する：テスト用プロンプトを送信し、モデルが正常に応答することを確認します

注意点 — よくある落とし穴

• GPU が利用できない：Docker Desktop の Mac/Windows では、GPU のパススルーに制限があります。→ 対処方法：GPU を完全にサポートするには、Linux ホスト + nvidia-container-toolkit が必要です。Mac の場合は、推論をオフロードできる docker model を使用してください。
• モデルのダウンロードサイズ：LLM は大容量です（2-70 GB）。→ 対処方法：docker model pull はモデルを ~/.docker/models にキャッシュします。プルする前に df -h で空き容量を確認してください。容量を抑えるには、量子化モデル（Q4/Q8）を使用してください。
• メモリ制限：LLM の推論には多くの RAM が必要です（通常 8-32 GB）。→ 対処方法：docker run --memory=16g model-runner を実行します。RAM は free -h で確認してください。メモリが不足する場合は、小さいモデル（70B ではなく 7B）を使用してください。
• Model Runner と Ollama の違い：Docker Model Runner は Docker ネイティブです。Ollama はより大きなエコシステムを備えています。→ 対処方法：Docker との統合には docker model を使用し、幅広いモデルを選択する場合は Ollama を使用してください。両方を併用することもできます。

適用範囲 — できること・できないこと

分類	シナリオ	説明
✅ 可能	ローカルモデルの推論（Docker Model Runner / Ollama）	オープンソース LLM をプルして実行でき、API key は不要です
✅ 可能	GPU アクセラレーションによる推論	Linux ホスト + nvidia-container-toolkit
✅ 可能	AI エージェントの構築（Docker Agent / Sandboxes）	複数エージェントの連携、サンドボックスによる分離
⚠️ 条件付き	macOS での GPU 推論	Docker Desktop のサポートには制限があります。docker model を優先してください
⚠️ 条件付き	大規模モデル（70B+）の推論	32GB+ の RAM が必要です。量子化モデルの使用を検討してください
❌ 対象外	モデルのトレーニング／ファインチューニング	専用フレームワーク（PyTorch/TensorFlow）が必要です。このスキルの対象外です
❌ 対象外	クラウド API の呼び出し（OpenAI/Claude）	ローカル推論ではありません。該当する SDK を使用してください
❌ 対象外	本番環境でのモデルサービング（K8s）	docker-production + K8s を使用してデプロイしてください

このスキルを使用しない場合

❌ スキップ	✅ 代わりに使用
Docker の基本	docker-basics
カスタムモデルイメージのビルド	docker-build
本番環境でのモデルサービング（K8s）	docker-production
クラウド AI API（Docker 不要）	API に直接アクセス

セキュリティと安定性

• 可能な場合は、モデルのコンテナを --read-only で実行してください。モデルは読み取り専用の重みです。
• モデルのコンテナのネットワークアクセスを制限してください。ローカル推論にインターネット接続は不要です。
• GPU パススルーを使用すると、コンテナはハードウェアに直接アクセスできます。分離のために --security-opt と組み合わせてください。
• GPU メモリの使用状況を監視してください。使用率の確認には nvidia-smi を使用します。

📚 公式ドキュメント

ドキュメント	URL
Docker AI の概要	https://docs.docker.com/ai-overview/
Docker Model Runner	https://docs.docker.com/ai/model-runner/
Docker Model Runner 入門	https://docs.docker.com/ai/model-runner/get-started/
Docker Agent	https://docs.docker.com/ai/docker-agent/
Docker Sandboxes	https://docs.docker.com/ai/sandboxes/
AI/ML の例	https://docs.docker.com/reference/samples/ai-ml/

🧭 Docker Skills Journey

📍 現在の位置：docker-ai-ml — AI/ML ワークロード

← 前へ：docker-testcontainers — 統合テスト

FAQ

Q1：このスキルを手早く使い始めるには？ A：上記のクイックスタートの章を参考に、手順に沿って操作してください。

Q2：バージョンの互換性に関する問題が発生した場合は？ A：依存関係のバージョンを確認し、lock ファイルで固定して、よくある落とし穴の章を参照してください。

Q3：本番環境で使用するには？ A：ベストプラクティスの章を参考に、設定が正しいことを確認し、監視とログ記録を行ってください。

Q4：パフォーマンスを最適化するには？ A：パフォーマンス最適化に関するドキュメントを参考に、キャッシュやインデックスなどを活用してください。

Q5：問題を報告したり、プロジェクトに貢献したりするには？ A：GitHub リポジトリで Issue または Pull Request を提出してください。

Q6：中国語に対応していますか？ A：中国語のドキュメントとコメントに対応しています。国内向けの適応に関する章を参照してください。