Docker Model Runner で Gemma 4 を動かす手順とバリアント選定のポイント

はじめに

AI 開発においてローカル環境でのモデル実行が広がる中、2026 年 4 月に Google の軽量モデル Gemma 4 が Docker Hub に公式対応しました。リリース当初は Docker Model Runner（DMR）側のアーキテクチャ対応が間に合っておらず、unknown model architecture 等のエラーが発生していましたが、現時点では DMR で Gemma 4 を直接実行できるようになっています。

参考: Docker Blog – Gemma 4 Is Now Available on Docker Hub
“By packaging models as OCI artifacts, models behave just like containers. They become versioned, shareable, and instantly deployable, with no custom toolchains required.”
（モデルを OCI アーティファクトとしてパッケージ化することで、モデルがコンテナと同じように振る舞います。バージョン管理・共有・即時デプロイが可能になり、独自のツールチェーンは不要です）
https://www.docker.com/blog/gemma4-dockerhub/

本記事では、Docker Model Runner を使って Gemma 4 をローカル PC で実行する手順を、バリアントの選定基準、TCP API の有効化、Python からの呼び出し例、ハマりやすいポイントまで含めて整理します。

なお、Docker Desktop 自体のインストールがまだの方は、関連記事「Docker Desktop の Windows 11 導入手順と Docker Hub 連携のポイント」も参照してください。

Docker Hub の Gemma 4 を活用するメリット

従来、ローカル環境で大規模言語モデル（LLM）を動かすには、Python 環境の整備、推論エンジン（llama.cpp など）のコンパイル、Hugging Face からの手動ダウンロードといった複数のステップが必要でした。依存関係の競合やツールチェーンの管理が複雑になるケースも少なくありませんでした。

Docker Hub の ai/ ネームスペースで配布される Gemma 4 は、OCI アーティファクトとしてパッケージ化されているため、コンテナイメージと同じ感覚でモデルを扱えます。専用のダウンローダーや認証手順を別途用意することなく、docker model pull の 1 行で取得できる点が大きなメリットです。

参考: Docker Blog – Why Docker Chose OCI Artifacts for AI Model Packaging
“Docker Model Runner introduces a new specification for packaging large language models (LLMs) as OCI artifacts — a format developers already know and trust.”
（Docker Model Runner は、大規模言語モデル（LLM）を OCI アーティファクトとしてパッケージ化する新しい仕様を導入します。これは開発者が既に知っており、信頼している形式です）
https://www.docker.com/blog/oci-artifacts-for-ai-model-packaging/

コンテナと同じワークフローで管理できる

docker model pull でモデルをダウンロードし、docker model run で対話を開始する、というシンプルなコマンド体系で完結します。チーム開発や別環境への移行時もコンテナイメージと同様に共有・バージョン管理が可能なため、環境差異による動作不良の防止につながります。CI/CD パイプラインへの組み込みやエッジデバイスへの展開を視野に入れる場合、Docker 経由での導入を推奨します。

OpenAI 互換 API を標準提供

Docker Model Runner は OpenAI 互換の REST API を標準で提供します。既存の OpenAI SDK（Python・Node.js 等）のエンドポイントを http://localhost:12434/engines/v1 に差し替えるだけで、コードの変更を最小限に抑えつつローカル推論に移行できます。これにより、開発時のレイテンシー削減、API コストの削減、機密データを外部に送信せずに処理できるプライバシー上のメリットが得られます。

Gemma 4 のバリアントと選定の目安

Gemma 4 は Google が公開しているモデルファミリーで、用途やハードウェアに応じて複数のサイズが存在します。Docker Hub の ai/gemma4 リポジトリでは、エッジ向けの軽量バリアントを中心に複数のタグが提供されています。

参考: Google AI – Gemma 4 model overview
“The ‘E’ stands for ‘effective’ parameters. The smaller models incorporate Per-Layer Embeddings (PLE) to maximize parameter efficiency in on-device deployments.”
（「E」は「Effective（有効）」パラメータを意味します。小型モデルは Per-Layer Embeddings（PLE）を採用し、オンデバイス展開でのパラメータ効率を最大化しています）
https://ai.google.dev/gemma/docs/core

Docker Hub で配布されている Gemma 4 のタグ

docker model pull ai/gemma4:<タグ> の形式でバリアントを指定します。Docker Hub ai/gemma4 リポジトリで提供されている主要なタグは以下のとおりです。

E4B の「E」は Effective（有効）パラメータ の略で、Per-Layer Embeddings（PLE）という技術により、見かけの 4B 規模でありながらより大きなモデルに近い表現力を実現しています。エッジ・ラップトップ環境を主なターゲットに最適化されています。

Docker Hub 以外で配布されている大規模バリアント

Gemma 4 ファミリー全体としては 26B A4B（MoE モデル） や 31B といった大規模バリアントも存在しますが、これらは現時点では ai/gemma4 リポジトリには含まれていません。大規模バリアントを試したい場合は、Hugging Face から GGUF 形式で取得して Ollama や llama.cpp で実行するアプローチを検討します。Docker Model Runner で動かす範囲では、E4B または 4B 系を選ぶのが基本となります。

バリアント選定の目安

Apple Silicon Mac の場合はユニファイドメモリとして CPU/GPU 共用のため、システム全体のメモリで判断します。16 GB の Apple Silicon Mac であれば E4B Q4 系が快適に動作します。

Gemma 4 の取得とローカル実行の手順

Gemma 4 を動かす前提として、Docker Desktop 4.40 以降が必要です（Docker Model Runner が同梱されているバージョン）。最新の Docker Desktop をインストールしている前提で、以下の手順を進めます。

Docker Model Runner の有効化

まずは Docker Model Runner を有効化します。Docker Desktop の GUI（Settings > AI もしくは Beta features 配下）から有効にするか、PowerShell やターミナルから以下のコマンドで有効化します。

docker desktop enable model-runner

ホスト側のアプリケーションから TCP 経由でモデルにアクセスする場合は、TCP サポートも併せて有効化します。既定ポートは 12434 です。

docker desktop enable model-runner --tcp 12434

参考: Docker Docs – DMR REST API
“Enable the host-side TCP support from the Docker Desktop GUI, or via the Docker Desktop CLI. For example: docker desktop enable model-runner –tcp.”
（ホスト側の TCP サポートは Docker Desktop GUI または Docker Desktop CLI から有効化します。例: docker desktop enable model-runner –tcp）
https://docs.docker.com/ai/model-runner/api-reference/

有効化が完了したら、以下のコマンドで Model Runner のステータスを確認します。

docker model status

Docker Model Runner is running と表示されれば、モデルを取得・実行する準備が完了しています。

Gemma 4 のプル（ダウンロード）

Docker Hub から Gemma 4 を取得します。ai/ ネームスペースを必ず含める点に注意します。

docker model pull ai/gemma4:E4B

ダウンロードが完了したら、ローカルに保存されたモデルの一覧を確認します。

docker model ls

ai/gemma4 がリストに表示されれば、ダウンロードは成功です。

Gemma 4 でプロンプトを送信

取得した Gemma 4 にプロンプトを送信して動作確認を行います。

docker model run ai/gemma4:E4B "こんにちは。Gemma 4 の動作確認です。一言で挨拶をお願いします。"

初回実行時はモデルがメモリにロードされるため、回答までに数秒〜十数秒かかる場合があります。2 回目以降はモデルがキャッシュされているため、より高速に応答します。対話モードで継続的にやり取りしたい場合は、-it オプションを付与します。

docker model run -it ai/gemma4:E4B

Gemma 4 を Python から呼び出す手順

Docker Model Runner は OpenAI 互換 API を提供しているため、既存の OpenAI SDK をそのまま使えます。ここでは Python の公式 OpenAI ライブラリでローカルの Gemma 4 にリクエストを送る例を紹介します。

TCP API が有効化されているか確認

前述の手順で docker desktop enable model-runner --tcp 12434 を実行済みであれば、ホストの localhost:12434 で API が待ち受けています。curl で疎通を確認します。

curl http://localhost:12434/engines/v1/models

JSON 形式で利用可能なモデル一覧が返れば、API は正常に動作しています。

Python の OpenAI SDK をインストール

pip install openai

Python からのリクエスト例

公式の OpenAI SDK 向け Base URL は http://localhost:12434/engines/v1 です。api_key はローカル実行で認証不要なため、任意の文字列で問題ありません（DMR は Authorization ヘッダーを無視します）。

from openai import OpenAI

# ローカルで稼働している Docker Model Runner のエンドポイントを指定
client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="not-needed"  # DMR は API キーを要求しないため任意の文字列で可
)

# Gemma 4 に対してプロンプトを送信
response = client.chat.completions.create(
    model="ai/gemma4:E4B",
    messages=[
        {"role": "user", "content": "Gemma 4 をアプリケーションから呼び出すテストです。一言で挨拶をお願いします。"}
    ]
)

# 応答を出力
print(response.choices[0].message.content)

参考: Docker Docs – DMR REST API（Using with OpenAI SDKs）
“client = OpenAI(base_url=’http://localhost:12434/engines/v1′, api_key=’not-needed’)”
（OpenAI クライアントの初期化例。Base URL は /engines/v1、API キーは不要）
https://docs.docker.com/ai/model-runner/api-reference/

このスクリプトを実行すると、インターネットに出ることなく、ローカル PC の CPU または GPU のみを使って Gemma 4 が応答を生成します。クラウド API と異なり、レイテンシーが安定し、API コストも発生しません。

コンテナから DMR を呼び出す場合の Base URL

別のコンテナ内から DMR API を呼び出す場合は、localhost ではなく http://model-runner.docker.internal/engines/v1 を使用します。Docker Compose 環境では、サービスの YAML に以下を追記することで解決します。

extra_hosts:
  - "model-runner.docker.internal:host-gateway"

導入時に起こりがちなエラーと対処

Docker Model Runner で Gemma 4 を動かす際、環境やコマンドの指定ミスに起因するエラーがいくつか発生します。代表的なものを整理します。

model not found エラー（ネームスペースの指定漏れ）

docker model pull gemma4 のように ネームスペース ai/ を省略すると、model not found エラーになります。Docker Hub の公式 Gemma 4 イメージは ai/gemma4 というパスで配布されているため、必ずプレフィックスを付与します。

# 誤り
docker model pull gemma4

# 正しい
docker model pull ai/gemma4:E4B

connection refused エラー（TCP API の未有効化）

Python スクリプトや curl で http://localhost:12434/engines/v1/... にアクセスしたとき connection refused が返るケースがあります。これは Docker Model Runner の TCP サポートが未有効な状態が原因です。前述の手順で TCP サポートを有効化したうえで再度アクセスします。

docker desktop enable model-runner --tcp 12434

有効化後は docker model status でステータスを確認します。

メモリ不足によるクラッシュ

Gemma 4 E4B でも、推論時には 4〜5 GB 程度のメモリを消費します。ホスト全体のメモリが 8 GB 程度の環境では、ブラウザや IDE などの他のプロセスとの兼ね合いでメモリが枯渇し、モデルの実行が強制終了するケースがあります。以下の対処を検討します。

• 他のメモリ使用量の大きいプロセスを終了する
• より軽量な量子化版 ai/gemma4:4B-Q4_K_XL に切り替える
• WSL 2 のメモリ割り当てを .wslconfig で調整する（詳細は関連記事「Docker Desktop の Windows 11 導入手順と Docker Hub 連携のポイント」を参照）

Windows 環境で GPU が認識されない

Windows + NVIDIA GPU 環境で GPU が利用されず、CPU 推論にフォールバックして遅くなるケースがあります。Docker Model Runner で Windows の GPU バックエンドを有効にするには、Docker Desktop の Settings で GPU-backed inference を有効化する必要があります。NVIDIA GPU のドライバが最新であることもあわせて確認します。

初回実行後の応答が遅い

初回の docker model run 実行時はモデルがメモリにロードされるため、応答までに数秒〜十数秒かかります。2 回目以降はキャッシュされたモデルが使われるため高速化されます。ベンチマークを取る場合は、ウォームアップ実行を 1 回挟んだうえで計測することを推奨します。

Gemma 4 と Docker Model Runner の最新動向

Gemma 4 と Docker Model Runner はいずれも活発に更新が続いている領域で、新しいバリアントの追加や API 仕様の改善が随時行われています。以下の情報源を定期的にチェックすることを推奨します。

• Docker Hub の ai/gemma4 ページ: 新しいタグ（バリアント・量子化）の追加状況を確認できます
• Docker 公式ブログ: Docker Model Runner や AI 関連機能の大型アップデートが発表されます
• Docker Model Runner の公式ドキュメント: API 仕様の変更や新機能の追加が随時反映されます
• Google AI for Developers の Gemma ページ: Gemma 4 のアーキテクチャ仕様や新バリアントが公開されます

参考: Docker Docs – DMR REST API
“Docker Model Runner supports multiple API formats: OpenAI-compatible, Anthropic-compatible, Ollama-compatible, and Image Generation (Diffusers).”
（Docker Model Runner は OpenAI 互換、Anthropic 互換、Ollama 互換、画像生成（Diffusers）の複数の API 形式をサポートします）
https://docs.docker.com/ai/model-runner/api-reference/

Anthropic 互換 API や画像生成（Diffusers）API は本記事執筆時点での比較的新しい機能で、用途によっては開発体験を大きく変える可能性があります。

まとめ

本記事では、Docker Model Runner を使った Gemma 4 のローカル実行手順について、バリアント選定からアプリケーション連携まで解説しました。

• Gemma 4 は Docker Hub の ai/gemma4 リポジトリで OCI アーティファクトとして配布されている
• Docker Hub では E4B・4B・量子化版が利用可能で、26B/31B の大規模バリアントは別経路で取得する
• Docker Model Runner の TCP サポートは docker desktop enable model-runner --tcp 12434 で有効化する
• モデルの取得と実行は docker model pull と docker model run の 2 コマンドで完結する
• Python の OpenAI SDK からは http://localhost:12434/engines/v1 をエンドポイントとして指定する
• ネームスペース ai/ の指定漏れやメモリ不足が、よくあるトラブルの原因となる

以上、最後までお読みいただきありがとうございました。