Docker Model Runner でのローカルモデル利用

Docker Model Runner では、ローカルマシン上における AI モデルを実行することができます。 API キーや定期的コストは不要であり、データをプライベートに保つことができます。

ローカルモデルをなぜ使うのか

Docker Model Runner を利用すると、API キーや定期的コストがなくても、ローカル環境においてモデルを実行できます。データはローカルマシン内に保持します。モデルをダウンロードしていれば、オフラインにより作動させることができます。これはクラウドモデルプロバイダーに代わるものです。

前提条件

Docker Model Runner をインストールしており、さらに以下を起動しておくことが必要です。

Docker Desktop (macOS/Windows) - Settings > AI > Enable Docker Model Runner により Docker Model Runner を有効にします。具体的な手順については DMR をはじめようを参照してください。
Docker Engine (Linux) - sudo apt-get install docker-model-plugin または sudo dnf install docker-model-plugin によりインストールします。詳しくは DMR をはじめようを参照してください。

Docker Model Runner が利用可能かどうかを確認します。

$ docker model version

上のコマンドによりバージョン情報が返ってくれば、ローカルモデルを利用することができます。

DMR によるモデルの利用

Docker Model Runner は互換性のあるモデルであれば何であっても動作します。モデルは以下から入手可能です。

Docker Hub リポジトリ (docker.io/namespace/model-name)
独自のレジストリにプッシュしパッケージ化した OCI 成果物
HuggingFace モデルへの直接アクセス (hf.co/org/model-name)
Docker Desktop 内の Docker Model カタログ

ローカルの Docker カタログにおいてモデルが利用可能かどうかを確認するには、以下を実行します。

$ docker model list --openai

モデルを利用する場合は、それを参照するように設定します。ローカルにまだモデルがプルされていない場合は、DMR がその利用の初回に自動的にプルを行います。

設定

agent においては Docker Model Runner の利用にあたって dmr プロバイダーを指定します。

agents:
  root:
    model: dmr/ai/qwen3
    instruction: You are a helpful assistant
    toolsets:
      - type: filesystem

agent を初めて実行する際に、ローカル環境にモデルがプルされていない場合には、cagent がモデルのプルをプロンプトにより促してきます。

$ cagent run agent.yaml
Model not found locally. Do you want to pull it now? ([y]es/[n]o)

どうやって動作するのか

DMR の利用にあたってモデルを指定した場合、cagent は自動的にローカル環境にある Docker Model Runner への接続を行い、指示を行うためのインターフェースを確立します。ローカル環境にモデルがまだ存在せず、それが初めての利用であるとき、cagent がモデルのプルをプロンプトにより促します。この場合に API キーや認証は不要です。

さらなる設定

モデルの動作をさらに細かく指定する場合は、モデル設定を定義します。

models:
  local-qwen:
    provider: dmr
    model: ai/qwen3:14B
    temperature: 0.7
    max_tokens: 8192

agents:
  root:
    model: local-qwen
    instruction: You are a helpful coding assistant

Faster inference with speculative decoding

Speed up model responses using speculative decoding with a smaller draft model:

models:
  fast-qwen:
    provider: dmr
    model: ai/qwen3:14B
    provider_opts:
      speculative_draft_model: ai/qwen3:0.6B-Q4_K_M
      speculative_num_tokens: 16
      speculative_acceptance_rate: 0.8

The draft model generates token candidates, and the main model validates them. This can significantly improve throughput for longer responses.

Runtime flags

Pass engine-specific flags to optimize performance:

models:
  optimized-qwen:
    provider: dmr
    model: ai/qwen3
    provider_opts:
      runtime_flags: ["--ngl=33", "--threads=8"]

Common flags:

--ngl - Number of GPU layers
--threads - CPU thread count
--repeat-penalty - Repetition penalty

Using DMR for RAG

Docker Model Runner supports both embeddings and reranking for RAG workflows.

Embedding with DMR

Use local embeddings for indexing your knowledge base:

rag:
  codebase:
    docs: [./src]
    strategies:
      - type: chunked-embeddings
        embedding_model: dmr/ai/embeddinggemma
        database: ./code.db

Reranking with DMR

DMR provides native reranking for improved RAG results:

models:
  reranker:
    provider: dmr
    model: hf.co/ggml-org/qwen3-reranker-0.6b-q8_0-gguf

rag:
  docs:
    docs: [./documentation]
    strategies:
      - type: chunked-embeddings
        embedding_model: dmr/ai/embeddinggemma
        limit: 20
    results:
      reranking:
        model: reranker
        threshold: 0.5
      limit: 5

Native DMR reranking is the fastest option for reranking RAG results.

Troubleshooting

If cagent can't find Docker Model Runner:

Verify Docker Model Runner status:
$ docker model status
Check available models:
$ docker model list
Check model logs for errors:
$ docker model logs
Ensure Docker Desktop has Model Runner enabled in settings (macOS/Windows)

What's next

Follow the tutorial to build your first agent with local models
Learn about RAG to give your agents access to codebases and documentation
See the configuration reference for all DMR options

Ask me about Docker

Docker Model Runner でのローカルモデル利用