vLLMのtoken上限とreasoningを別の軸で調べる

vLLMの「token上限」は1つの値ではありません。

モデルのcontext長、1 requestのinputとoutput、同時実行、KV cache、GPU memoryを分けて確認する必要があります。

reasoning設定も、vLLMがどのmodelへも推論能力を追加するswitchではありません。

model、chat template、reasoning parserの対応が揃って初めて意味を持ちます。

設定と実行時の役割を分ける

設定	制御するもの	誤解しやすい点
--max-model-len	1系列のinputと生成を含む最大context	outputだけの上限ではない
max_tokens	1 requestで許す最大output	必ずその量を生成するわけではない
--max-num-batched-tokens	1回のscheduleで扱うtoken量	context長そのものではない
--max-num-seqs	同時に処理するsequence数	増やせば必ず速くなるわけではない
--gpu-memory-utilization	vLLMへ割り当てるGPU memory割合	weightsだけを対象にする値ではない

現行のvLLM engine argsでは、max-model-lenを省略するとmodel設定から導出します。

modelが長いcontextを宣言しても、その長さを同時実行できるとは限りません。

GPU memoryとKV cacheの余裕を別に確認します。

inputとoutputの条件を式にする

1 requestでは、概ね次の関係が必要です。

input tokens + maximum generated tokens <= max-model-len

max_tokens=8192は、常に8192 tokenを生成する指定ではありません。

EOS、stop、tool callなどで早く終了することがあります。

一方、上限を大きく設定すると、schedulerが同時実行へ割り当てる余地を圧迫します。

日常設定はmodelの公称最大値から決めません。

実運用に近いinputとoutputの分布を集め、95〜99 percentileへ余裕を足して決めます。

GPU memoryの内訳を確認する

GPU memoryには、model weights、実行時のtemporary領域、KV cacheが入ります。

KV cacheはcontext長と同時sequence数に応じて増えます。

そのため、次の変更は互いに影響します。

• max-model-lenを増やす
• max-num-seqsを増やす
• KV cacheのdtypeを変える
• より大きなmodelや高精度weightsを使う

OOMが出たときは、context長だけを下げないようにします。

並列数、batch token数、quantization、同じGPUを使う他processを分けて確認します。

gpu-memory-utilizationを限界まで上げるのは最後にします。

driverや他processの余地も残します。

reasoning parserの役割を確認する

Reasoning modelは、内部推論と最終回答を特定の形式で返す場合があります。

vLLMのReasoning Outputsは、modelに対応するparserで2つを分離する仕組みです。

parserが合わないと、推論が通常本文へ混ざります。

reasoning fieldが空になったり、chat templateと出力形式がずれたりします。

reasoning_effortの受け付け方もmodelとtemplateに依存します。

設定値を受け付けても、すべてのmodelが同じ意味で処理するとは限りません。

公式の対応情報とmodel cardを確認し、レスポンスのreasoning fieldとusage tokenを実測します。

設定を1段ずつ増やす

切り分けでは、次の順番で設定を変えます。

1. model cardのcontext長と推奨templateを確認する
2. 短いinputを1 requestだけ送る
3. reasoning parserなしでraw outputの形式を確認する
4. 対応parserを設定し、推論と回答の分離を確認する
5. 実運用に近いinput長へ増やす
6. max-num-seqsを少しずつ増やす
7. throughput、初回token時間、OOM、KV cache使用量を記録する

設定を一度に変えると、model不一致、template不一致、memory不足の原因が混ざります。

設定例は測定の開始点にする

vllm serve MODEL_ID \
  --max-model-len 32768 \
  --max-num-seqs 4 \
  --gpu-memory-utilization 0.90 \
  --reasoning-parser MODEL_SUPPORTED_PARSER

この値は推奨値ではありません。

GPU、quantization、model、input分布によって変更する測定用の例です。

max-model-lenはcontextの上限、batch設定は処理量、GPU設定は実行可能性、reasoning parserは出力解釈を担当します。

この4つを分けて調べると、設定変更の影響を説明しやすくなります。

参考資料

• vLLM Engine Arguments
• Reasoning Outputs | vLLM
• Structured Outputs | vLLM