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:

  1. Verify Docker Model Runner status:

    $ docker model status

  2. Check available models:

    $ docker model list

  3. Check model logs for errors:

    $ docker model logs

  4. 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