> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokios.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel. > Use 'connector' for the local tokios-connector process. > Use 'deployment' for the public model name in the API model field. > Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend. > API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-. # vLLM をスループットとレイテンシの観点で最適化する > vLLM をスループットの最大化またはレイテンシの最小化に向けてチューニングします。KV キャッシュの調整、プレフィックスキャッシュ、チャンク化プリフィル、LoRA の提供、量子化オプション、V1 アーキテクチャの変更点を解説します。 vLLMはGPUで大規模言語モデルをサービングするための最も機能豊富なオープンソースランタイムだ。スループット、レイテンシ、メモリ使用量に直接影響する幅広い設定オプションを備えている。このガイドでは最も重要な設定項目と、ワークロードに応じた設定方法を解説する。 > [!NOTE] > > Last verified: 2026-10-14 — vLLM v0.31.0. > [!NOTE] > > **V1がデフォルト。** V1アーキテクチャはvLLM v0.31.0でデフォルトとなった。新しいスケジューラー、デフォルトで有効化されたチャンクドプリフィル、改善されたGPUメモリ管理をもたらす。古いガイドとの動作差異がある場合、V1がその原因である可能性が高い。 ## KVキャッシュのチューニング KVキャッシュはすべてのアクティブなシーケンスの各トークンのキーバリューテンソルを格納する。モデルウェイト自体に次ぐGPUメモリの最大の消費源であり、これをチューニングすることで同時リクエスト数を最大限に変更できる。 ### サイジング計算式 vLLMはKVキャッシュサイズを自動計算するが、計算式を理解しておくと上限設定に役立つ。 ``` KV memory per token = 2 × num_layers × num_kv_heads × head_dim × dtype_bytes ``` 係数の2はキーとバリューの両方を考慮したものだ。7Bモデル（32レイヤー、32 KVヘッド、128ヘッドディメンション、`float16`）の場合： ``` 2 × 32 × 32 × 128 × 2 = 524,288 bytes ≈ 0.5 MB per token ``` 24 GBのKVキャッシュスペースがある場合、全シーケンス合わせて約48,000トークンを格納できる。 ### fp8 KVキャッシュの使用 `--kv-cache-dtype fp8`はデフォルトの`float16`と比較してKVキャッシュメモリを約50%削減する。キャッシュ可能なトークン数が直接倍増し、より多くの同時シーケンスまたはより長いコンテキストに対応できる。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --kv-cache-dtype fp8 ``` > [!WARNING] > > FP8 KVキャッシュはわずかな精度の低下を伴う。ほとんどのチャットやコード生成ワークロードでは影響は無視できるが、特定のタスクで評価を実行する場合は、本番環境で有効化する前に出力品質が閾値を満たすことを確認してほしい。 ### `--max-num-seqs`と`--max-model-len` これら2つのフラグは同じKVキャッシュプールを競合する。 * `--max-model-len`は単一シーケンスのコンテキスト長に上限を設定する。これを下げるとKVキャッシュが解放され、より多くの同時シーケンスに対応できる。 * `--max-num-seqs`は単一のバッチで処理されるシーケンス数に上限を設定する。これを上げるとスループットが向上するが、シーケンスごとのメモリコストが増加する。 ワークロードが短いプロンプト（2Kトークン未満）を送信する場合、`--max-model-len`を下げ、`--max-num-seqs`を上げて並行性を最大化する。ロングコンテキストリクエストを扱う場合はその逆を行う。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Short prompts, high concurrency vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-model-len 4096 \ --max-num-seqs 256 # Long context, fewer concurrent sequences vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-model-len 32768 \ --max-num-seqs 32 ``` ## プレフィックスキャッシング 多くの実ワークロードでは、共通のプレフィックスを共有するリクエストが送信される。システムプロンプト、RAGの検索ブロック、マルチターン会話の過去のターンなどだ。プレフィックスキャッシングがない場合、vLLMは共有プレフィックスのKVキャッシュをリクエストごとに再計算する。 `--enable-prefix-caching`は計算済みのKVブロックをハッシュインデックス付きテーブルに格納する。キャッシュ済みブロックと一致するプレフィックスを持つ新しいリクエストが到着すると、vLLMはKVテンソルを再計算せずにキャッシュを再利用する。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --enable-prefix-caching ``` > [!TIP] > > プレフィックスキャッシングが特に効果を発揮するのは以下の場合だ： > > * すべてのリクエストに同じシステムプロンプトが含まれる場合（チャットアプリやコーディングエージェントで一般的）。 > * 固定の検索ブロックを各クエリの先頭に付加するRAGを使用している場合。 > * マルチターン会話で過去のターンをコンテキストとして再利用する場合。 > > すべてのリクエストが固有のプレフィックスを持つ場合は、効果はない。 V1ではプレフィックスキャッシングはデフォルトで有効だ。`V0`スケジューラーモードで実行している場合にのみ明示的にフラグが必要になる。 ## チャンクドプリフィル プリフィル（入力プロンプトの処理）は計算負荷が高い。長いプロンプト（8K+トークン）はGPUを数百ミリ秒にわたって占有し、他のシーケンスのデコードステップをブロックしてレイテンシスパイクを引き起こす可能性がある。 チャンクドプリフィルはプリフィルをデコードステップと交互に挿入される小さなチャンクに分割する。GPUはプロンプトのチャンクを処理し、次に他のアクティブなシーケンスのデコードステップを実行し、その後次のプリフィルチャンクを処理する。これによりデコードレイテンシが予測可能に保たれる。 V1ではチャンクドプリフィルは**デフォルトで有効**だ。チャンクサイズは制御できる。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-num-batched-tokens 8192 ``` `--max-num-batched-tokens`は単一のスケジューラステップで処理されるトークンの最大数を設定する。低い値はデコードレイテンシへのプリフィル影響を軽減するが、TTFT（Time-to-First-Token）の総時間が増加する。高い値は時折のデコードジッターと引き換えにプリフィックススループットを向上させる。 > [!NOTE] > > 古いvLLMバージョンでチャンクドプリフィルを無効にしていてV1にアップグレードする場合、`--enable-chunked-prefill`フラグを削除してほしい。V1では常にオンであり、フラグは無視される。 ## LoRAサービング vLLMは複数のLoRAアダプターをベースモデルにマージすることなく単一のプロセスからサービングできる。単一のベースモデルを実行し、異なるファインチューニング済みバリアントにリクエストをルーティングできる。例えば、コーディングアダプター、要約アダプター、汎用チャットアダプターを、すべて同じベースウェイトをGPUメモリで共有しながら実行できる。 ### LoRAサービングの有効化 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B \ --enable-lora \ --lora-modules \ coder=./lora-adapter-coder \ summarizer=./lora-adapter-summarizer ``` 設定の`--lora-modules`の各エントリは、リクエスト-facingの名前をローカルパスにマッピングする。クライアントは`model`フィールドでアダプターを選択する。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "coder", "messages": [ { "role": "user", "content": "Write a Python function that sorts a list." } ] }' ``` ### 動的ローディング vLLMは動的なLoRAローディングをサポートする。サーバーを再起動せずにAPIを通じて実行時にアダプターを追加または削除できる。多数のアダプターを持ち、そのうち少数のみが常にアクティブな場合に有用だ。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Load a new adapter at runtime curl http://localhost:8000/v1/load_lora_adapter \ -H "Content-Type: application/json" \ -d '{ "lora_name": "translator", "lora_path": "./lora-adapter-translator" }' ``` > [!TIP] > > 設定 `--max-lora-rank` でランクを制限する。低ランクのアダプターはより少ないメモリを使用する。すべてのアダプターが同じランクを共有する場合は、未使用の容量にメモリを過剰割り当てしないよう、そのランクに設定する。 ## 量子化オプション 量子化はモデルウェイトの精度を16ビット未満に下げ、わずかな精度と引き換えに大きなメモリとスピードの向上を得る。vLLMは複数の量子化フォーマットをサポートする。 | Format | Precision | Hardware | Best for | | - | - | - | - | | **AWQ** | 4-bit integer | Any GPU | General-purpose 4-bit quantization. Good accuracy retention. Pre-quantized models widely available on Hugging Face. | | **GPTQ** | 4-bit integer | Any GPU | Older format, similar to AWQ. Prefer AWQ for new quantizations — GPTQ remains for compatibility with existing models. | | **FP8** | 8-bit float | Ampere+ (A100, H100, L40, RTX 4090) | Near-FP16 accuracy with half the memory. Good default when your GPU supports it. | | **NVFP4** | 4-bit float | Blackwell (B200, GB200, RTX 5090) | Newest format. Maximum memory savings on Blackwell hardware. | ### 量子化モデルの使用 事前量子化モデルの場合、vLLMはモデルの`config.json`からフォーマットを自動検出する。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # AWQ model — auto-detected vllm serve TheBloke/Llama-2-7B-Chat-AWQ # FP8 model — auto-detected on Ampere+ GPUs vllm serve neuralmagic/Meta-Llama-3.1-8B-Instruct-FP8 ``` > [!WARNING] > > **FP8ショートハンドはv0.31で変更された。** FP8量子化識別子は現在`fp8_per_tensor`だ。スクリプトやCIパイプラインで`--quantization fp8`を明示的に渡している場合は、新しい識別子に更新してほしい。`config.json`にFP8を持つモデルは影響を受けない。自動検出は引き続き機能する。 ### オンライン量子化 ロード中にモデルをオンザフライで量子化することも可能だが、本番環境では事前量子化モデルが推奨される。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-70B \ --quantization awq ``` ## スループットとレイテンシ 最適化戦略は**スループット**（全リクエスト合計の毎秒トークン数）と**レイテンシ**（個別リクエストのTTFTとトークン間レイテンシ）のどちらを優先するかによって異なる。 ### スループットの最大化 バッチサイズを増やしてGPUステップあたりの作業量を高める。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-num-seqs 256 \ --max-num-batched-tokens 16384 \ --enable-prefix-caching \ --kv-cache-dtype fp8 ``` * `--max-num-seqs 256`はバッチ内の同時シーケンスを最大256まで許可する。 * `--max-num-batched-tokens 16384`はスケジューラステップあたりのトークン数を増やす。 * `--kv-cache-dtype fp8`はより多くのシーケンス用にメモリを解放する。 ### レイテンシの最小化 バッチサイズを減らし、レイテンシをスループットに置き換える最適化を無効にする。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-num-seqs 16 \ --max-num-batched-tokens 4096 \ --enforce-eager ``` * `--max-num-seqs 16`はバッチを小さく保ち、各リクエストがより早くGPU時間を得られるようにする。 * `--enforce-eager`はCUDAグラフを無効にする。CUDAグラフは固定計算グラフをキャプチャしてリプレイし、スループットを向上させるが、新しいバッチシェイプの初回実行時にレイテンシを追加する。デバッグ時またはTTFTの毎ミリ秒が重要な場合に`--enforce-eager`を使用する。 > [!TIP] > > ユーザーがレスポンスを待つインタラクティブアプリケーションでは、TTFTを500ms未満に抑えることを目標とすべきだ。`--max-num-seqs 32`と`--max-num-batched-tokens 4096`から始め、負荷下で測定したTTFTに基づいて調整する。 ## V1アーキテクチャの変更 V1はvLLM v0.31.0のデフォルトスケジューラーだ。以前vLLMを使用していた場合、以下が変更点だ。 **新しいスケジューラー。** V1スケジューラーはV0ブロックマネージャーを統一メモリマネージャーに置き換え、KVキャッシュ、プレフィックスキャッシング、チャンクドプリフィルを単一のパスで処理する。これによりスケジューリングオーバーヘッドが削減され、V0がGPUメモリを断片化する可能性があったいくつかのエッジケースが解消される。 **チャンクドプリフィルがデフォルト。** プリフィルとデコードは自動的にインターリーブされる。`--enable-chunked-prefill`は不要で、常にオンになっている。 **より良いメモリ管理。** V1はGPUメモリをより細かい粒度で追跡し、パディングとアライメントからの無駄なスペースを削減する。5-15%のより多くの利用可能なKVキャッシュを、同じハードウェアでV0と比較して期待できる。 **CUDAグラフの改善。** V1はより幅広いバッチシェイプで積極的にCUDAグラフをキャプチャし、手動チューニングなしにスループットを向上させる。 > [!NOTE] > > V1でリグレッションが発生した場合は、サーバー起動前に環境変数`VLLM_USE_V1=0`を設定してV0にフォールバックできる。問題をvLLMチームに報告してほしい。V0は新機能を受け取らない。 ### v0.31の新機能：永続ウェイトキャッシュとスナップショット vLLM v0.31は2つの新しいCLIコマンドを導入する。 * **`vllm preload`** は永続ウェイトキャッシュデーモンを起動し、サーバー再起動間でもモデルウェイトをGPUメモリに保持する。再起動ごとに数ギガバイトのモデルをディスクから再ロードする代わりに、サーバーがデーモンに接続してキャッシュされたウェイトを再利用する。これによりコールドスタート時間が数分から数秒に短縮される。 * **`vllm snapshot create`** は現在のサーバー状態（ロード済みモデル、アダプター、設定）をキャプチャし、**`vllm snapshot restore`** が即座に復元する。悪い設定変更後のロールバックや、既知の良好な設定をマシン間で複製するのに有用だ。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Start the weight-cache daemon vllm preload meta-llama/Llama-3.1-8B-Instruct # Create a snapshot of the current state vllm snapshot create my-production-config # Restore it on another machine vllm snapshot restore my-production-config ``` ### v0.31の破壊的変更 * **`--trust-request-mm-kwargs`** はクライアントがリクエストボディを通じてマルチモーダル入力（画像、オーディオ）を送信する際に現在必須だ。このフラグがない場合、vLLMはセキュリティ上の理由からマルチモーダルkwargsを拒否する。アプリケーションがAPIリクエストで画像やその他のメディアを送信する場合は追加する。 * **`--grpc`** はHTTPサーバーと並行してgRPCサービングを有効にする。gRPCクライアントを使用する場合は、このフラグを付けてvLLMを起動し、gRPCエンドポイントを公開する。 ## 設定例 ### 高スループットバッチ処理 個別リクエストのレイテンシよりも毎秒合計トークン数が重要なオフラインバッチワークロードの場合。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-70B-Instruct \ --tensor-parallel-size 4 \ --kv-cache-dtype fp8 \ --enable-prefix-caching \ --max-num-seqs 512 \ --max-num-batched-tokens 32768 \ --max-model-len 8192 ``` この設定は4-GPUセットアップで並行性を最大化する。4ビット相当のKVキャッシュと高いバッチ制限は、リクエストごとのレイテンシが長くなるのと引き換えにスループットを押し上げる。 ### 低レイテンシインタラクティブサービング ユーザーがレスポンスを待つチャットアプリケーションで、TTFTを500ms未満に抑える場合。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --kv-cache-dtype fp8 \ --enable-prefix-caching \ --max-num-seqs 32 \ --max-num-batched-tokens 4096 \ --max-model-len 8192 ``` 小さなバッチサイズと中程度のトークン制限によりGPUの応答性が保たれる。プレフィックスキャッシングはレイテンシを追加せずに繰り返しのシステムプロンプトを高速化する。 ### マルチアダプターLoRAサービング 単一のベースモデルから複数のファインチューニング済みバリアントをサービングする場合。 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B \ --enable-lora \ --lora-modules \ coder=./adapters/coder \ reviewer=./adapters/reviewer \ summarizer=./adapters/summarizer \ --max-lora-rank 64 \ --kv-cache-dtype fp8 \ --enable-prefix-caching \ --max-num-seqs 128 ``` クライアントは`model`フィールドでアダプターを名前で選択する。全3アダプターが同じベースモデルウェイトを共有するため、GPUメモリ使用量はベースモデル単体のサービングとほぼ同等で、各LoRAアダプターは数メガバイトしか追加しない。 > [!NOTE] > > vLLMの設定を変更した後、Tokiosデプロイメントを再登録して、コネクターが新しいアップストリームエンドポイントを取得できるようにする。[Register Model](/ja/setup/register-model.md)を参照。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.