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

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

目次

ドッカー・モデル・ランナーでのコンテキストサイズの設定は、本来よりも複雑です。

context_sizeパラメータはdocker-compose構成に存在しますが、docker/model-runner:latest-cudaイメージではこのパラメータがしばしば無視され、4096トークンのコンテキストサイズがハードコーディングされています。このガイドでは、この制限について説明し、実用的な回避策を提供します。

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. 一時的なもので動作します。 方法2. モデルにハードコーディングします。 方法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

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

Dockerとインフラ

代替のLLMソリューション

公式ドキュメント

結論

docker-composeを使用してDocker Model Runnerでコンテキストサイズを設定することは現在、問題があります。context_sizeパラメータはDocker Compose仕様に存在しますが、docker/model-runner:latest-cudaイメージでは適切に実装されておらず、設定に関係なく4096トークンのコンテキストサイズがハードコーディングされています。

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

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

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

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