著者 Ollamaのコンテキスト長をnum_ctxで設定する方法
Ollamaで長いプロンプトが途中で切れる原因と、num_ctxをリクエスト単位またはサーバー全体で設定する方法を解説します。KVキャッシュ用RAMの見積もりも確認できます。
num_ctx の役割と、長いプロンプトが途中で切れた理由
Ollama のコンテキスト長は、読み込んだモデルが一度にメモリへ保持できるトークン数です。num_ctx は、その値を設定するオプションです。Ollama は、モデルが公称する最大値を大幅に下回るデフォルト値を選択します。そのため、長いプロンプトはモデルが読む前に切り詰められます。発生しても、応答からは分かりません。
Ollama のモデルライブラリでは、Llama 3.1 8B のコンテキストウィンドウは 128k と記載されています。ただし、標準状態のサーバーでは、その値は使用されません。Ollama の公式ドキュメントでも、ページによってデフォルト値が異なります。FAQ では 4096 トークン、Modelfile リファレンスでは num_ctx のデフォルト値が 2048、コンテキスト長のページでは、利用可能な VRAM（ビデオメモリ）からデフォルト値を選ぶと説明されています。24 GiB 未満では 4k、24 GiB 以上 48 GiB 未満では 32k、それを超えると 256k です。これらは、いずれかのビルドでは正しい値でした。ここから得られる教訓は明確です。このページを含め、どのページの記載もそのまま信頼せず、実行中の自分のサーバーから値を確認してください。
切り詰めは、モデルが応答を返し、その内容も自然に読めるため、気付きにくい状態で発生します。応答は入力の末尾を基に生成されます。文書の前半を欠いた要約は、性能の低いモデルによるものに見えます。しかし、実際の原因は小さすぎるコンテキストウィンドウであることが一般的です。
Ollama サーバーが実際に適用したコンテキスト長を確認する
どのビルドでも使用できる確認方法は prompt_eval_count です。これは、サーバーが処理したと報告するプロンプトトークン数です。コンテキストに収まる量を超える入力を送ると、この数値は上限で止まります。
sudo apt update && sudo apt install -y jq
LONG=$(python3 -c "print('the quick brown fox jumps over the lazy dog. ' * 2000)")
jq -n --arg p "$LONG" '{model:"llama3.1:8b", prompt:$p, stream:false, options:{num_ctx:4096}}' |
curl -s http://localhost:11434/api/generate -d @- |
jq '{prompt_eval_count, prompt_eval_duration}'このプロンプトは約 18,000 語あり、4096 トークンを大幅に超えています。そのため、サーバーが残りを破棄し、prompt_eval_count は実際のトークン数に近い値ではなく、4096 前後になります。"num_ctx":16384 を指定して再実行すると、カウントが増えます。ビルドによって切り捨てではなくエラーを返す場合もありますが、より明確に示されるだけで、確認できる内容は同じです。
ollama psCONTEXT 列は、表示されるビルドでは、現在読み込まれているモデルが使用しているコンテキスト長を示します。その隣の PROCESSOR 列には、モデルの配置先が表示されます。GPU のない VPS では 100% CPU が通常の状態です。GPU サーバーで 30%/70% CPU/GPU のように分割されている場合、重みとキャッシュが VRAM に収まらなくなっています。通常の原因は、num_ctx が引き上げられていることです。
journalctl -u ollama --no-pager | grep -i n_ctx | tail -n 5推論ランナーは、n_ctx を含む行にコンテキストサイズを表示します。正確な文言はリリースによって変わるため、その行がない場合は、何かを証明するものではなく、名称が変更されたものとして扱ってください。
num_ctx を設定する4つの場所
リクエスト内。 "options": {"num_ctx": 16384} を /api/generate または /api/chat に送信します。これは他のすべての設定より優先され、その1回の呼び出しにだけ適用されます。値がロード済みモデルの実行時の値と異なる場合、サーバーは最初にモデルを再ロードします。この処理はレスポンスの load_duration で確認できます。値がほぼ0から数秒単位に変化します。モデルが十分な時間アイドル状態になってアンロードされた場合も同じ待ち時間が発生します。そのため、コンテキストサイズを決めた後は、keep_alive でモデルを常駐させるとよいでしょう。
対話セッション内。 ollama run 内で /set parameter num_ctx 16384 と入力します。この設定はそのセッション中だけ有効です。
Modelfile 内。 この値を名前付きモデルに組み込むため、クライアント側を変更しなくても、すべてのクライアントに適用されます。
FROM llama3.1:8b
PARAMETER num_ctx 16384ollama create llama3.1-16k -f ./Modelfile
ollama run llama3.1-16kサーバー上。 OLLAMA_CONTEXT_LENGTH は、独自の num_ctx を含まないすべてのリクエストのデフォルト値を設定します。systemd では、unit ファイルを編集せず、drop-in を追加します。
sudo systemctl edit ollama.service[Service]
Environment="OLLAMA_CONTEXT_LENGTH=16384"sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama psトラブルシューティングでは、この優先順位が特に重要です。他者のクライアントを調査する場合も同様です。num_ctx を含むリクエストはサーバーのデフォルトより優先されます。そのため、chat フロントエンドや agent が独自に小さい値を送信すると、systemd で行った変更が気付かないうちに上書きされます。coding agent を Ollama server に接続する場合は、サーバーを疑う前にクライアントが送信する値を確認してください。
モデルの最大値に num_ctx を設定するだけでは不十分な理由
Attention では、各トークンがそれ以前のすべてのトークンを参照します。先行トークンから計算したキーと値は、新しいトークンのたびに再計算しないよう保持されます。この保存領域が KV cache（key/value cache）です。モデルの読み込み時に num_ctx 全体分が確保され、会話の進行に応じて増えるわけではありません。そのため、1 行のプロンプトでも大きなコンテキスト用のメモリが必要になります。
DigitalOcean の推論コストに関するチュートリアルでは、計算式を次の 1 行で示しています。
kv_bytes_per_token = 2 * layers * kv_heads * head_dim * bytes_per_valueこの 2 は、キーと値を個別に数えることを表します。その他の数値は使用するモデルから確認してください。
curl -s http://localhost:11434/api/show -d '{"model":"llama3.1:8b"}' |
jq '.model_info | {ctx: ."llama.context_length", layers: ."llama.block_count", heads: ."llama.attention.head_count", kv_heads: ."llama.attention.head_count_kv", embed: ."llama.embedding_length"}'Llama 3.1 8B は、32 層と 8 個の key/value head を使用します。head dimension は embed を heads で割って求めます。ここでは 4096 / 32 = 128 です。モデルによっては、この値を llama.attention.key_length として直接公開しています。デフォルトの cache は f16 の値を保持するため、bytes_per_value は 2 です。したがって、2 32 8 128 2 は 131,072 bytes になります。これは、コンテキスト 1 トークンごとに 128 KiB の cache が必要ということです。コンテキスト長を掛けると、必要なメモリが具体的に見えてきます。
The data behind this chart
[
{
"label": "4k",
"kv_cache_gib": 0.5,
"total_ram_gib": 5.1
},
{
"label": "8k",
"kv_cache_gib": 1,
"total_ram_gib": 5.6
},
{
"label": "16k",
"kv_cache_gib": 2,
"total_ram_gib": 6.6
},
{
"label": "32k",
"kv_cache_gib": 4,
"total_ram_gib": 8.6
},
{
"label": "64k",
"kv_cache_gib": 8,
"total_ram_gib": 12.6
},
{
"label": "128k",
"kv_cache_gib": 16,
"total_ram_gib": 20.6
}
]この 6 行は、上記の式から算出した値であり、実測値ではありません。合計列には、2026 年 8 月に Ollama library が llama3.1:8b 用として掲載していた 4.9 GB のダウンロードサイズを加えています。これは 4.6 GiB に相当します。compute buffer と server process 自体は含めていません。したがって、これは必要メモリの下限として扱ってください。
重要なのは全体の傾向です。8k では cache は 1 GiB で、weights と比べれば無視できる大きさです。モデルの最大値である 128k では 16 GiB になり、weights の 3 倍を超えます。合計は約 20.6 GiB です。そのため、4 GB VPS では、このモデルを実用的なコンテキスト長で読み込めません。8 GB VPS なら 8k で余裕があります。16 GB VPS なら、他の処理にメモリを残した状態で 32k まで使用できます。weights が大きくなるほど、これらの境界値も上がります。そのため、この 8B とより大きなモデルを比較する場合は、CPU 専用 VPS での Qwen の 27B tagについて同じ計算を行うと、8 GB から 64 GB の環境で context に残るメモリがどれだけ少ないかが分かります。
KV キャッシュが収まらない場合の動作
CPU のみの VPS では、プロセスのメモリ使用量がそのまま増加します。モデルの読み込み中と、長いリクエストの実行中に監視してください。
free -m
ps -eo rss,comm --sort=-rss | head -n 5RSS（resident set size）はキロバイト単位で表示されます。free -m の使用済み swap が増え始めたら、コンテキストサイズを下げてください。swap 上にある KV キャッシュは、生成を 1 トークンあたり数秒停止させます。新しいトークンを生成するたびに、キャッシュ全体を読み取る必要があるためです。
サーバーのメモリが完全に枯渇すると、kernel は最大のプロセスを選んで強制終了します。
sudo dmesg | grep -i "killed process"Out of memory: Killed process 1234 (ollama) と表示された行は、指定したコンテキストサイズが収まらなかったことを示します。Ollama はそこまで進む前に拒否することが多く、その場合、必要だったメモリと空いていたメモリを示すメッセージとともにリクエストが失敗します。
GPU サーバーでは、失敗が分かりにくくなります。レイヤーが system RAM にあふれ出し、ollama ps に CPU と GPU の分担が表示され、スループットが大幅に低下します。低下幅はハードウェアによって異なります。そのため、他のマシンの数値をそのまま信用せず、各コンテキスト設定で 自分のサーバーで 1 秒あたりのトークン数を測定してください。
プロンプトよりもPrefill時間の増加が速い
Prefillは、最初の出力トークンが現れる前に入力に対して行う処理です。各プロンプトトークンは、それより前にあるすべてのトークンにAttentionを行うため、処理量は入力長の2乗に比例して増加します。プロンプトを2倍にすると、最初のトークンが返るまでの待ち時間は2倍を超えて長くなります。
応答には測定値が含まれるため、その値を無条件に信頼する必要はありません。
jq -n --arg p "$LONG" '{model:"llama3.1:8b", prompt:$p, stream:false, options:{num_ctx:16384}}' |
curl -s http://localhost:11434/api/generate -d @- |
jq '{tokens: .prompt_eval_count, prefill_seconds: (.prompt_eval_duration/1000000000)}'短いプロンプトと長いプロンプトでそれぞれ実行し、各ケースでトークン数を秒数で割ります。CPU のみの VPS では、長いコンテキストのリクエストにおいて、通常は prefill が最も時間のかかる処理です。短いプロンプトで測定した tokens per second の値から、長いコンテキストの処理時間を予測することはできません。prefill が、前段に設定されたどのタイムアウトよりも長くかかると、長いプロンプトに対して回答ではなく コンテキストの期限超過 が返されるのが一般的です。そのため、コンテキストを短くする前に、どの層が先に処理を中断したのかを確認してください。
この影響が最も大きくなるのは、同時実行時です。処理中の各リクエストには専用のキャッシュが必要です。そのため、上の図に示したメモリ量はサーバー単位ではなく、リクエスト単位です。長いリクエストがサーバーを占有すると、短いリクエストは後ろで待機することがあります。OLLAMA_NUM_PARALLELは意図的に設定し、両方の数値を同時に増やす前に、セルフホスト型LLMが同時に処理できるユーザー数を確認してください。
小さなキャッシュでコンテキスト用のメモリを確保する
bytes_per_valueは、ユーザーが変更できる設定です。Ollama の FAQ には OLLAMA_KV_CACHE_TYPE が記載されており、デフォルトは 2 bytes の f16 です。さらに、1 byte の q8_0 と、それより小さい q4_0 もあります。q8_0 に変更するとキャッシュが半分になるため、32k の行に必要な容量は 4 GiB ではなく 2 GiB になります。重みを量子化すると、同じメモリ予算の別の部分からメモリを確保できます。このトレードオフを選ぶ場合は、VPS に実際に収まる GLM タグを量子化方式ごとに検討します。Ollama の同じ FAQ には OLLAMA_FLASH_ATTENTION=1 も記載されています。量子化キャッシュを有効にする前に、この設定を必要とするビルドがあります。
[Service]
Environment="OLLAMA_FLASH_ATTENTION=1"
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"推測で判断せず、サービスを再起動し、以前と同じ num_ctx でモデルを読み込み、RSS を比較します。対応状況はモデルとバックエンドによって異なるため、設定を変更しても何も変わらない場合、その組み合わせは対応対象外です。ドキュメントにはこれらのオプションが記載されていますが、品質が向上するとは保証されていません。依存する前に、q4_0を自分のプロンプトでテストしてください。ここで扱った設定が必要な理由であれば、Ollama と llama.cpp では設定の公開方法が異なります。
num_ctx の決め方
/api/showから、モデルの最大コンテキスト、レイヤー数、key/value ヘッド数を確認します。- 式でトークンあたりのバイト数を求め、必要なコンテキスト長を掛けます。
- 重みのサイズを加算して空き RAM と比較し、サーバーの他の処理用に少なくとも 1 GiB を残します。
- 値を設定してモデルを読み込み、
ollama psとprompt_eval_countで適用された値を確認します。 free -mを監視しながら実際のワークロードを実行し、swap の使用が始まったらコンテキスト長を半分にします。
多くの処理では、設定されているコンテキスト長ほどの長さは必要ありません。長いレポートの要約なら 16k で十分です。5 つの文書チャンクを貼り付ける検索フロントエンドでも、通常は 8k を超えません。ファイル全体を読み込むコーディングエージェントは、64k 以上が実際に必要になるケースです。この場合は、コンテキスト長に合わせてマシンのサイズを決めるべきです。逆に、マシンに合わせてコンテキスト長を決めるのではありません。サーバーを構築したばかりなら、まず VPS で動作する Ollama のインストール から始め、モデルが正常に読み込めることを確認してからコンテキスト長を調整します。
FAQ
Ollama のデフォルトのコンテキスト長はいくつですか？
ビルドとハードウェアによって異なるため、想定せずに確認してください。Ollama の FAQ には 4096 トークン、Modelfile リファレンスには num_ctx のデフォルト値として 2048、コンテキスト長のページには利用可能な VRAM に基づくデフォルト値として、24 GiB 未満では 4k、24 以上 48 GiB 以下では 32k、48 GiB 超では 256k と記載されています。CPU のみの VPS では、小さい値になります。ollama ps は、この列を持つビルドで適用されたコンテキストを表示し、API 応答内の prompt_eval_count はすべてのビルドでその値を確認できます。
Ollama が長いプロンプトの先頭を無視するのはなぜですか？
プロンプトがコンテキストウィンドウより長かったためです。サーバーがモデルに渡す前にプロンプトを切り詰めたため、エラーは返りません。同じプロンプトを、より大きい num_ctx を指定して再送し、応答内の prompt_eval_count が増えるか確認してください。その値が変わらない場合は、クライアントとサーバーの間にある何かが num_ctx 自体を設定しています。これはチャットフロントエンドやエージェントフレームワークでよくあります。
大きい num_ctx には、どの程度の追加 RAM が必要ですか？
コンテキスト長に、トークンごとのキャッシュコストである 2 * layers * kv_heads * head_dim * bytes_per_value を掛けて計算します。f16 の Llama 3.1 8B では、1 トークンあたり 128 KiB です。そのため、32k トークンでは重みとは別に 4 GiB、完全な 128k では 16 GiB が必要です。キャッシュはモデルの読み込み時に割り当てられるため、プロンプトが短いままでも大きな num_ctx にはその分のメモリが必要です。
コンテキストウィンドウを大きくすると Ollama は遅くなりますか？
はい。2 つの理由があります。プリフィル処理量はプロンプト長の 2 乗に比例して増えるため、長い入力では、長さから想定される以上に最初のトークンの出力が遅れます。大きなキャッシュはメモリも圧迫します。GPU マシンでは一部のレイヤーがシステム RAM に移され、CPU マシンでは swap が発生しやすくなります。使い切らない大きな num_ctx でもメモリは消費しますが、プリフィル処理時間は増加しません。
1 つのモデルに対して num_ctx を永続的に設定できますか？
はい。FROM llama3.1:8b と PARAMETER num_ctx 16384 を含む Modelfile を作成し、ollama create llama3.1-16k -f ./Modelfile を実行します。llama3.1-16k を要求するすべてのクライアントが、オプションを送信せずにこのコンテキストを使用できます。独自の num_ctx を含むリクエストがあれば、そちらが優先されます。そのため、これは上限ではなくデフォルト値の設定です。