llamacpp-server の --parallel 引数の設定を怠ったせいで、俺のコンテキストサイズが意図せず奪われていた話

こんにちは、色違いモノです。
タイトルの通りです。😭

忙しい人のために要約

llamacpp-serverの引数 --parallel は同時リクエスト数を指定する
llamacpp-serverのコンテキストサイズは --ctx-size を --parallel で割ったが内部的に扱われるため、デフォルト 8 だとコンテキストが 1/8 に縮小される
解決策は --parallel と --ctx-size を調整すること

コンテキストサイズ超過で処理に失敗する

ここ数日、llama.cpp-serverでgpt-oss:120bを動作させ、Codex IDE extensionを完全ローカルで遊んでいるのですが、
LLMがweb検索MCPを使用した際に高確率でコンテキストサイズオーバーとなってしまう現象が発生していました。

unexpected status 400 Bad Request: {
"error":{
"code":400,
"message":"the request exceeds the available context size, try increasing it",
"type":"exceed_context_size_error",
"n_prompt_tokens":23449,"n_ctx":16384
}}

このエラーをよく見ると "n_ctx":16384 となっており、コンテキストサイズが16kで、それを超えてしまったことがわかります。
しかしgpt-oss:120bの最大コンテキストサイズは128kのはずです。

原因調査

gpt-oss:120bは docker composeのllamacpp-serverコンテナで動かしており、
コンテキストサイズの設定を確認するために compose.yaml を確認しました。
しかし、しっかり以下の用に指定されていました。

compose.yaml

services:
  llama-cpp-vulkan:
    image: ghcr.io/ggml-org/llama.cpp:server-vulkan
    ports:
      - "10000:10000"
      〜省略〜
    command: >
      --model ${LLAMA_MODEL}
      --host 0.0.0.0
      --port 10000
      --ctx-size ${LLAMA_CTX_SIZE:-131072}
      --parallel ${LLAMA_N_PARALLEL:-8}
      〜省略〜

.env

〜省略〜
LLAMA_CTX_SIZE=131072

--ctx-size ${LLAMA_CTX_SIZE:-131072}にはしっかり
環境変数LLAMA_CTX_SIZEを指定しており、さらにデフォルト値も131072なので環境変数の指定漏れもカバーできています。

落とし穴

設定したコンテキストサイズと実際のコンテキストサイズを比べて見てみると、

設定したサイズ＝131072
実際のサイズ＝16384

となっており、ちょうど8分の1となっています。
※試しに設定変更してみても、きっちり8分の1になっていました。

そこでChatGPTに聞いてみました。その時のやり取りを一部抜粋します。

入力プロンプト：
llama.cpp-server の引数、環境変数でどちらもctx-sizeに128k(131072)を指定しています。
しかし、エラーに記載されているように、n_ctx":16128となっています。
どうやら、n_ctxは、ctx-sizeの8分の1のサイズになっているようです。
この理由を調査してください。

ChatGPTの回答：
良い観察です。
結論から言うと、llama.cpp／llama‑server において
「--ctx-size で指定した値が実質的な n_ctx にそのまま反映されず、
（あなたの例では）8分の1に近い値で報告されている」現象は、少なくとも
「--parallel オプションとの関係」 によるものとして Issue に記録があります。

--parallel ${LLAMA_N_PARALLEL:-8} にデフォルトで 8 にしてますが、
どうやら、この parallel オプションはになにかカラクリがあるようです。
parallelオプションは、「同時に処理できるリクエスト数」を表しており、
更にコンテキストサイズは、このparallel で割った分しか使用できないようです。

私の場合は一人で利用するので、同時には 1 本のリクエストしか走らせないので利点がないようです。

背景知識

parallel オプションとは？

llama.cpp のサーバー実装 (llama-server) はマルチスレッドで複数リクエストを同時処理できるように --parallel N を提供しています。N が大きいほど同時処理数が増えるものの、内部では コンテキスト領域を N 等分 して各スロットに割り当てます。

コンテキストサイズが分割される

--ctx-size はサーバー全体で確保する総トークン数です
実行時に n_ctx_per_seq = ctx_size / parallel が計算され、各リクエストはこのサイズしか使えません
デフォルト 8 → 例えば --ctx-size 16384 を指定しても実際の有効コンテキストは 2048 トークンになる

まとめ: llama.cpp の --parallel は同時リクエスト数だけを制御するフラグで、デフォルト 8 が原因でコンテキストが 1/8 に削られる挙動をしていました。
個人利用なら --parallel 1 に設定し、必要に応じて --ctx-size を調整する必要があります。次回からはこの落とし穴を避けて、思い通りのコーディングエージェント生活
を楽しみましょう。