Dockerモデルランナー: コンテキストサイズ設定ガイド

Docker Model Runnerでコンテキストサイズを設定する際の回避策

目次

Docker Model Runnerにおけるコンテキストサイズの設定は、本来よりも複雑です。

docker-composeの設定においてcontext_sizeというパラメータが存在しますが、docker/model-runner:latest-cudaというイメージではこのパラメータが無視され、4096トークンのコンテキストサイズがハードコーディングされています。本ガイドではこの制限について説明し、実用的な回避策を提供します。Docker Model RunnerとOllama、vLLM、LocalAI、クラウドプロバイダとの比較を含む、より広範な比較については、LLMホスティング：ローカル、セルフホスト、クラウドインフラの比較を参照してください。

configuring car この画像はFlux 1 devによって生成されました。

問題の理解

Docker Model Runnerを使用してdocker-composeでコンテキストサイズを設定する場合、以下のように設定することがあります：

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

しかし、ログを確認すると実際に使用されているコンテキストサイズは以下のようになります：

docker compose logs 2>&1 | grep -i "n_ctx"

出力は以下のように表示されます：

llamaCppArgs: [... --ctx-size 4096 ...]
llama_context: n_ctx = 4096

docker/model-runner:latest-cudaというイメージは、llama.cppを呼び出す際、**--ctx-size 4096**をハードコーディングしており、あなたのcontext_size: 10240という設定を完全に無視しています。

この問題が発生する理由

コンテキストサイズ（n_ctx）は、Docker Model Runnerが使用している下層の推論エンジンであるllama.cppにおいて、モデルの初期化時に設定されます。これは、APIリクエストが処理される前のモデルのコンテキスト構築フェーズで行われます。Docker Model Runnerのdocker-composeとの統合には、modelsセクションからcontext_sizeパラメータをllama.cppプロセスに適切に渡していないというバグがあります。その代わりに、設定に関係なく4096トークンにデフォルトで設定されています。

この制限により、Docker ComposeがYAML設定でcontext_sizeパラメータを認識しているにもかかわらず、docker/model-runner:latest-cudaイメージはllama.cppのコマンドライン引数にこの設定を反映しません。ハードコーディングされた--ctx-size 4096フラグが、あなたが指定した設定を上書きします。

対処法と解決策

どうすればよいでしょうか？方法1～3は動作しますが、それぞれ制限があります。

方法1：docker model configureを使用（制限あり）

Docker Model CLIを使用してコンテキストサイズを設定できます。この設定はDockerのモデルメタデータに保存されます：

docker model configure --context-size=10000 ai/gemma3-qat:4B

このコマンドはモデルの設定を更新しますが、実装には重大な制限があります。設定は保存されるものの、常に正しく適用されるわけではありません。

制限：

  • docker model runを直接使用する場合、APIエンドポイントにcurlでアクセスする場合のみ動作します
  • 設定後にdocker model runを使用すると、設定が無視されます
  • docker/model-runner:latest-cudaイメージとdocker-composeを使用する場合、設定が無視されます
  • モデルが更新または再取得された場合、設定が失われる可能性があります

この方法は直接のAPI呼び出しでのテストに最適ですが、docker-composeを使用したプロダクションデプロイには適していません。

方法2：独自のモデルをパッケージ化

カスタムコンテキストサイズを設定する最も信頼性が高い方法は、docker model packageを使用して独自のモデルをパッケージ化することです。これにより、パッケージ化の時点ですでにコンテキストサイズがモデルのメタデータに焼き込まれます：

docker model package \
  --gguf /path/to/model.gguf \
  --context-size 10240 \
  --name my-model:custom-context

このコマンドは、コンテキストサイズが永久に設定された新しいOCIアーティファクト（Dockerイメージに類似）を作成します。このパッケージ化されたモデルは、Docker Hubまたは任意のOCI準拠レジストリにプッシュされ、他のDocker Model Runnerモデルのようにプルできます。

ただし、この方法には以下が必要です：

  • 元のGGUFモデルファイルへのアクセス（llama.cppが使用する量子化されたフォーマット）
  • コンテキストサイズを変更するたびに再パッケージ化が必要で、時間がかかる可能性があります
  • 自分のモデルレジストリまたはDocker Hubアカウントの管理
  • Docker Model Runnerパッケージングワークフローの理解

この方法は、デプロイにわたって一貫した、再現可能なコンテキストサイズが必要なプロダクション環境に最適です。

方法3：Docker Compose（現状では動作しない）

現状ではdocker/model-runner:latest-cudaでは動作しない

ただし、独自のアプリをイメージに含める方法であれば、動作する可能性があります。

docker-compose.ymlに以下の構文が存在します：

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

これは動作しない - context_sizeパラメータはdocker-composeによって認識されるが、適用されません。モデルは依然として4096トークンを使用します。

方法4：環境変数（動作しない）

MODEL_CONTEXT環境変数を使用して試みる：

services:
  llm:
    image: docker/model-runner:latest-cuda
    environment:
      - MODEL_CONTEXT=10240

これは動作しない - docker-composeを使用する際に環境変数が無視されます。

コンテキストサイズの確認

実際に使用されているコンテキストサイズを確認するには、ログを確認してください：

# llama.cppの引数を確認
docker compose logs 2>&1 | grep "llamaCppArgs"

# 実際のコンテキストサイズを確認
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

出力は以下のように表示されます：

llamaCppArgs: [-ngl 999 --metrics --model /models/... --ctx-size 4096 ...]
llama_context: n_ctx = 4096
llama_context: n_ctx_per_seq = 4096

n_ctx = 4096が表示され、別の値を設定したにもかかわらず、設定が無視されていることを示します。

コンテキストサイズのテスト

設定が実際に適用されているかを確認するには、デフォルトの4096トークンの制限を超えるプロンプトを使用してテストする必要があります。以下は、Pythonを使用して、コンテキストサイズ設定が動作しているかをテストする実用的なスクリプトです：

#!/bin/bash
MODEL="ai/gemma3-qat:4B"
PORT=8085

# 大きなプロンプトでテスト
python3 -c "print('test ' * 5000)" > large_prompt.txt

python3 << 'PYTHON' > request.json
import json
import os

with open('large_prompt.txt', 'r') as f:
    large_prompt = f.read().strip()

request = {
    "model": os.environ.get("MODEL", "ai/gemma3-qat:4B"),
    "messages": [{
        "role": "user",
        "content": large_prompt
    }]
}
print(json.dumps(request))
PYTHON

curl -s http://localhost:${PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @request.json > response.json

# トークン使用量を確認
python3 << 'PYTHON'
import json
with open('response.json') as f:
    r = json.load(f)
    if 'usage' in r:
        print(f"Prompt tokens: {r['usage']['prompt_tokens']}")
        if r['usage']['prompt_tokens'] > 4096:
            print("✅ コンテキストウィンドウは4096より大きい!")
        else:
            print("⚠️ コンテキストウィンドウは4096に制限されているようです")
PYTHON

代替の解決策

より柔軟なコンテキストサイズ設定が必要な場合は、以下の代替案をご検討ください：

  • Ollama - コンテキストサイズや設定をよりよく制御できる代替のLLMホスティングソリューション。Ollamaではモデルごとにコンテキストサイズを指定でき、docker-composeの制限がありません。

  • Docker Model Runner vs Ollamaの比較 - 両方のソリューションの詳細な比較、コンテキストサイズ設定機能、パフォーマンス、プラットフォーム選択のタイミングを含みます。

Docker Model Runnerが他のローカルおよびクラウドオプションとどのように適合するかについては、LLMホスティング：ローカル、セルフホスト、クラウドインフラの比較ガイドをご覧ください。

関連リソース

Docker Model Runner

Dockerとインフラストラクチャ

代替LLMソリューション

公式ドキュメント

結論

docker-composeを使用してDocker Model Runnerでコンテキストサイズを設定することは現在のところ問題があります。docker/model-runner:latest-cudaイメージでは、設定構文がDocker Compose仕様に存在しているにもかかわらず、4096トークンのコンテキストサイズがハードコーディングされており、あなたの設定を無視します。

最も信頼性が高い回避策は、docker model packageを使用して必要なコンテキストサイズを持つ独自モデルをパッケージ化することですが、これはワークフローに複雑さを加え、元のGGUFモデルファイルへのアクセスが必要です。代替として、docker model configureを使用して直接APIにアクセスできますが、docker-composeデプロイでは動作しません。

ほとんどのユースケースでは、デフォルトの4096トークンのコンテキストサイズは典型的な会話型AIアプリケーションには十分です。より大きなコンテキストウィンドウやより柔軟な設定が必要な場合は、docker-composeの制限がないOllamaを使用することを検討してください。

VRAM使用量を最適化するには、モデル量子化（Q4、Q6、Q8）やGPUレイヤー設定（MODEL_GPU_LAYERS）などの他の手段を使用するのが効果的です。これらはコンテキストサイズの調整よりもメモリ消費を減らすためにより効果的です。

GPU最適化とVRAM管理に関する詳細については、NVIDIA GPUサポートの設定ガイドをご覧ください。