Docker Model Runner

Docker Model Runner は、Docker を使って AI モデルを簡単に管理・実行・デプロイできるようにする機能です。開発者向けに設計されており、大規模言語モデル（LLM）やその他の AI モデルを Docker Hub や OCI 準拠のレジストリから直接 Pull・実行・提供するプロセスを効率化します。

Docker Desktop や Docker Engine とシームレスに統合されており、OpenAI 互換 API を通じてモデルを提供したり、GGUF ファイルを OCI アーティファクトとしてパッケージ化して公開したり、CLI や GUI からモデルを操作できます。

生成 AI アプリの開発、機械学習ワークフローの実験、開発ライフサイクルへの AI 統合など、Docker Model Runner を使えば、AI モデルをローカルで一貫性・安全性・効率性をもって利用できます。

主な特徴

• Docker Hub からモデルを Pull・Push 
• OpenAI 互換 API でモデルを提供し、既存アプリに統合可能
• GGUF ファイルを OCI アーティファクトとしてパッケージ・あらゆるコンテナレジストリに公開
• CLI や Docker Desktop GUI からモデルを実行・対話
• ローカルモデルの管理とログ表示

対応環境

Docker Model Runner は以下のプラットフォームに対応しています:

動作の仕組み

モデルは初回使用時に Docker Hub から Pull され、ローカルに保存されます。リクエストがあったときにのみメモリへ読み込まれ、使用されていないときはリソースを最適化するためにアンロードされます。モデルは大容量になることがあるため、初回の Pull には時間がかかる場合がありますが、一度キャッシュされれば以降は高速にアクセスできます。OpenAI 互換 API を使ってモデルと対話できます。

Docker Model Runner を有効にする

Docker Desktop で DMR を有効にする

1. Docker Desktop の設定画面を開き、Beta features タブに移動します。

2. Enable Docker Model Runner の設定にチェックを入れます。

3. 対応する NVIDIA GPU を搭載した Windows 環境では、Enable GPU-backed inference のオプションも表示され、チェックできるようになります。

4. （任意）TCP サポートを有効にしたい場合は、Enable host-side TCP support を選択します。

   1. Port フィールドに任意のポート番号を入力します。
   2. Model Runner をローカルのフロントエンド Web アプリから利用する場合は、CORS Allows Origins にそのアプリの URL（例：http://localhost:3131）を指定します。

これで docker model コマンドを CLI で使用できるようになり、Docker Desktop の Models タブからローカルモデルを表示・操作できます。

Docker Engine で DMR を有効にする

1. Docker Engine  がインストールされていることを確認してください。

2. DMR はパッケージとして提供されています。以下のコマンドでインストールできます：

$ sudo apt-get update
$ sudo apt-get install docker-model-plugin

$ sudo dnf update
$ sudo dnf install docker-model-plugin

3. インストールをテストします:

   $ docker model version
   $ docker model run ai/smollm2

4. （任意）TCP サポートを有効にするには、DMR_RUNNER_PORT 環境変数で使用するポート番号を指定します。

5. （任意）TCP サポートを有効にした場合は、DMR_ORIGINS 環境変数で CORS の許可オリジンを設定できます。指定可能な値は以下のとおりです：

   • *: すべてのオリジンを許可

   • カンマ区切りで複数のオリジンを指定

   • 未設定の場合は、すべてのオリジンが拒否されます。

モデルの Pull

モデルはローカルにキャッシュされます。

# Docker Hub から Pull
docker model pull ai/smollm2:360M-Q4_K_M

# Hugging Face から Pull
docker model pull hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF

モデルの実行（Run）

トラブルシューティング

問題が発生した場合は、ログを表示して原因を確認できます：

モデルの公開（Publish）

既存のモデルに新しい名前を付けて、別の namespace やリポジトリで公開できます：

# Pull 済みのモデルに新しい名前をタグ付け
$ docker model tag ai/smollm2 myorg/smollm2
 
# Docker Hub に Push
$ docker model push myorg/smollm2

詳細は docker model tag および docker model push のコマンドリファレンスを参照してください。

GGUF 形式のモデルファイルを直接 OCI アーティファクトとしてパッケージ化し、Docker Hub に公開することもできます：

# 例：HuggingFace から GGUF 形式のモデルファイルをダウンロード
$ curl -L -o model.gguf https://huggingface.co/TheBloke/Mistral-7B-v0.1-GGUF/resolve/main/mistral-7b-v0.1.Q4_K_M.gguf
 
# OCI アーティファクトとしてパッケージ化し、Docker Hub に Push
$ docker model package --gguf "$(pwd)/model.gguf" --push myorg/mistral-7b-v0.1:Q4_K_M

詳細は docker model package のコマンドリファレンスをご覧ください。

例：Docker Model Runner をソフトウェア開発ライフサイクルに統合する

Docker Model Runner を活用して、生成 AI アプリケーションの開発をすぐに始められます。

すでに用意された GenAI アプリケーションを試したい場合は、以下の手順に従ってください。

1. サンプルアプリをセットアップします。以下のリポジトリをクローンして実行します：

   $ git clone https://github.com/docker/hello-genai.git

2. ターミナルで hello-genai ディレクトリに移動します。

3. run.sh を実行すると、選択されたモデルが Pull され、アプリケーションが起動します：

4. ブラウザでアプリを開き、リポジトリの README  に記載されたアドレスにアクセスします。

ブラウザには GenAI アプリのインターフェースが表示され、プロンプトを入力して試すことができます。

ローカルモデルを使って動作する、自分だけの GenAI アプリと対話してみましょう。高速なレスポンスに注目してください — すべてが Docker 上でローカルに実行されています。

よくある質問（FAQs）

利用可能なモデルは？

すべての利用可能なモデルは、Docker Hub の ai public namespace にホストされています。

使用できる CLI コマンドは？

CLI リファレンスドキュメント をご覧ください。

利用できる API エンドポイントは？

機能を有効にすると、以下のベース URL に新しい API エンドポイントが提供されます。

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

Docker Model 管理用エンドポイント:

POST /models/create
GET /models
GET /models/{namespace}/{name}
DELETE /models/{namespace}/{name}

OpenAI 互換エンドポイント:

GET /engines/llama.cpp/v1/models
GET /engines/llama.cpp/v1/models/{namespace}/{name}
POST /engines/llama.cpp/v1/chat/completions
POST /engines/llama.cpp/v1/completions
POST /engines/llama.cpp/v1/embeddings

これらのエンドポイントを Unix ソケット（/var/run/docker.sock）経由で呼び出す場合は、パスの前に /exp/vDD4.40 を付けてください。

OpenAI API を通じた対話方法

コンテナ内からのアクセス

別のコンテナ内から chat/completions の OpenAI エンドポイントを curl を使って呼び出すには、以下のようにします：

#!/bin/sh
 
curl http://model-runner.docker.internal/engines/llama.cpp/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "ai/smollm2",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Please write 500 words about the fall of Rome."
            }
        ]
    }'

このリクエストでは、ai/smollm2 モデルを指定し、プロンプトとして「ローマ帝国の滅亡について 500 語で説明してください」と尋ねています。model-runner.docker.internal は Docker Desktop 環境でコンテナからホストにリクエストを送るための内部 DNS 名です。

ホスト（TCP）からのアクセス

ホストマシンから TCP を使って chat/completions の OpenAI エンドポイントを呼び出すには：

1. Docker Desktop の GUI または Docker Desktop CLI  を使って、ホスト側の TCP サポートを有効にします。

   例：

   $ docker desktop enable model-runner --tcp <port>

   Windows で使用している場合は、GPU-backed inference も有効にしてください。手順についてはこちらを参照。

2. 正しいポート番号と localhost を使用して、以下のようにリクエストを送信します。

#!/bin/sh
 
curl http://localhost:12434/engines/llama.cpp/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "ai/smollm2",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Please write 500 words about the fall of Rome."
            }
        ]
    }'

ホスト（Unix ソケット）からのアクセス

Docker ソケットを経由して chat/completions エンドポイントにアクセスするには、以下のように curl を使用します：

#!/bin/sh
 
curl --unix-socket $HOME/.docker/run/docker.sock \
    localhost/exp/vDD4.40/engines/llama.cpp/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "ai/smollm2",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Please write 500 words about the fall of Rome."
            }
        ]
    }'

この方法では TCP ポートを使用せず、Docker の Unix ソケットを通じて直接リクエストが送られます。/exp/vDD4.40 は Unix ソケット向けにエンドポイントを拡張するパスプレフィックスです。

既知の問題

docker model が認識されない

Docker Model Runner のコマンドを実行した際に、以下のようなエラーが表示される場合：

docker: 'model' is not a docker command

これは、Docker がプラグインを検出できないことを意味します。CLI プラグインの所定のディレクトリに存在しないことが原因です。

対処方法： シンボリックリンクを作成して、Docker がプラグインを認識できるようにします：

$ ln -s /Applications/Docker.app/Contents/Resources/cli-plugins/docker-model ~/.docker/cli-plugins/docker-model

リンクを作成したら、再度コマンドを実行してください。

過剰なサイズのモデル実行に対する保護機能がない

現時点では、Docker Model Runner において、ホストマシンのリソース（メモリや GPU メモリなど）を超えるモデルの実行を防ぐ保護機能はありません。 そのため、過剰なサイズのモデルを起動しようとすると、システムの著しい遅延や一時的なフリーズが発生する可能性があります。

この問題は、十分な GPU メモリや RAM を持たない環境で LLM を実行しようとする際に特に発生しやすいです。

Model CLI での digest 指定の一貫性がない

現在、Docker Model CLI ではイメージの digest を使用してモデルを指定するための一貫したサポートが提供されていません。

一時的な回避策として、digest ではなくモデル名で参照してください。

フィードバックの共有

Docker Model Runner をお試しいただきありがとうございます。

ご意見や不具合の報告は、Enable Docker Model Runner 設定の横にある Give feedback リンクからお送りください。