コードリーディング: vLLM & LMCache

LLM推論サービングに関連するOSSのコードリーディング結果を構造化して蓄積するプロジェクト。

対象OSS

プロジェクト横断

• 横断調査 — 複数OSSにまたがる調査報告

vLLM

LLM推論サービングエンジン vLLM のコードリーディング。

• ソースコード: target/vllm/
• 現在のPhase: Phase 2（コンポーネント別深堀り）

テキスト推論データフロー

深度: [MEDIUM] 確信度: [VERIFIED] 最終更新: 2026-02-11 (Phase 2bでマルチモーダル差分追加)

概要

テキスト推論リクエストは、APIエントリポイントからエンジン層を経てGPUで実行され、生成されたトークンがデトークナイズされてユーザーに返却される。フロー全体は5つの境界データ構造（EngineCoreRequest → SchedulerOutput → ModelRunnerOutput → EngineCoreOutput → RequestOutput）で区切られ、ZMQ IPCによるプロセス分離とasyncioによる非同期パイプラインで高スループットを実現する。

フロー全体図

graph TD
    subgraph フロントエンドプロセス
        API["API Server / LLM"]
        AsyncLLM["AsyncLLM<br>generate() / add_request()"]
        IP["InputProcessor<br>process_inputs()"]
        OP["OutputProcessor<br>process_outputs()"]
        Client["EngineCoreClient<br>AsyncMPClient"]
    end

    subgraph バックエンドプロセス ["EngineCore プロセス"]
        EC["EngineCore<br>step()"]
        Sched["Scheduler<br>schedule()"]
        KV["KVCacheManager<br>allocate_slots()"]
        Exec["Executor<br>execute_model()"]
        Worker["Worker"]
        MR["GPUModelRunner<br>execute_model()"]
    end

    API -->|"prompt, params"| AsyncLLM
    AsyncLLM -->|"prompt, params"| IP
    IP -->|"EngineCoreRequest"| AsyncLLM
    AsyncLLM -->|"EngineCoreRequest"| Client

    Client -->|"ZMQ ROUTER\nmsgpack"| EC
    EC --> Sched
    Sched -->|"allocate_slots()"| KV
    Sched -->|"SchedulerOutput"| EC
    EC -->|"SchedulerOutput"| Exec
    Exec -->|"MessageQueue\n共有メモリ"| Worker
    Worker --> MR
    MR -->|"ModelRunnerOutput"| Worker
    Worker -->|"ModelRunnerOutput"| Exec
    Exec -->|"ModelRunnerOutput"| EC
    EC -->|"update_from_output()"| Sched
    Sched -->|"EngineCoreOutputs"| EC

    EC -->|"ZMQ PUSH\nmsgpack"| Client
    Client -->|"EngineCoreOutputs"| OP
    OP -->|"RequestOutput"| AsyncLLM
    AsyncLLM -->|"RequestOutput"| API

境界データ構造

フローは以下の5つのデータ構造で区切られる。各構造はプロセス間またはコンポーネント間の境界を定義する。

EngineCoreRequest

フロントエンド → バックエンドの境界。ユーザー入力を正規化した内部表現。

参照: target/vllm/vllm/v1/engine/__init__.py:55 (EngineCoreRequest)

msgspec.Struct を継承し、array_like=True + omit_defaults=True で効率的にmsgpackシリアライズされる。

SchedulerOutput

Scheduler → Executor の境界。各ステップのスケジュール結果を含む。

参照: target/vllm/vllm/v1/core/sched/output.py:184 (SchedulerOutput)

NewRequestData は初回スケジュール時のフルデータ（プロンプトトークン、サンプリングパラメータ、ブロックID等）を含む。CachedRequestData は既スケジュール済みリクエストの差分（新規ブロックID、新トークンID、計算済みトークン数の更新）のみを含み、プロセス間通信コストを最小化する。

ModelRunnerOutput

GPUModelRunner → EngineCore の境界。モデル推論結果を含む。

参照: target/vllm/vllm/v1/outputs.py:160 (ModelRunnerOutput)

Worker→Executorへの転送ではPythonリスト形式を使用し、torch.Tensorの高コストなシリアライゼーションを回避する。

EngineCoreOutput

バックエンド → フロントエンドの境界。リクエスト単位の推論結果。

参照: target/vllm/vllm/v1/engine/__init__.py:130 (EngineCoreOutput)

EngineCoreOutputs（複数形）がこれをlist[EngineCoreOutput]としてバッチ化し、scheduler_statsやタイムスタンプと共にZMQ経由で送信される。

参照: target/vllm/vllm/v1/engine/__init__.py:176 (EngineCoreOutputs)

RequestOutput

OutputProcessor → API の境界。ユーザーに返却される最終出力。

参照: target/vllm/vllm/outputs.py:86 (RequestOutput)

CompletionOutput (target/vllm/vllm/outputs.py:23) は各サンプルの出力を表す:

出力モード（RequestOutputKind、target/vllm/vllm/sampling_params.py:108）:

• CUMULATIVE: 毎回全出力を返す（デフォルト）
• DELTA: 差分のみ返す（ストリーミング向け）
• FINAL_ONLY: 完了時のみ返す

上流パス: リクエスト受信 → EngineCore

エントリポイント (LLM / AsyncLLM)

vLLMには同期パス（LLM）と非同期パス（AsyncLLM）の2つのエントリポイントがある。内部的にはどちらもInputProcessorとEngineCoreClientを使用する。

非同期パス（主パス）: AsyncLLM

APIサーバー（OpenAI互換API等）が使用する主要パス。

参照: target/vllm/vllm/v1/engine/async_llm.py:71 (AsyncLLM)

AsyncLLM.generate(prompt, sampling_params, request_id)    # L537
  │
  ├─ add_request(request_id, prompt, params)               # L286
  │   ├─ input_processor.process_inputs(prompt, params)    # L364
  │   │   → EngineCoreRequest を生成
  │   ├─ input_processor.assign_request_id(request)        # L378
  │   │   → 内部IDを付与（外部ID + 8文字ランダムサフィックス）
  │   ├─ output_processor.add_request(request, ...)        # L423
  │   │   → フロントエンド側でリクエストを登録
  │   └─ engine_core.add_request_async(request)            # L426
  │       → ZMQ経由でバックエンドへ送信
  │
  └─ while not finished:                                    # L586
      out = q.get_nowait() or await q.get()                # L589
      yield out                                             # L596

generate()はAsyncGeneratorで、バックグラウンドのoutput_handlerタスクがEngineCoreからの出力をRequestOutputCollectorキューにpushし、generate()がそれをyieldする。

output_handler（バックグラウンドタスク）:

参照: target/vllm/vllm/v1/engine/async_llm.py:647 (_run_output_handler)

output_handler():                                           # L662
  while True:
    outputs = await engine_core.get_output_async()          # L666
    for chunk in outputs.outputs:                           # L677
      output_processor.process_outputs(chunk, ...)          # L681
      → RequestOutputをキューにpush
    if reqs_to_abort:
      await engine_core.abort_requests_async(...)           # L693

同期パス: LLM

オフライン推論（バッチ処理）で使用される。

参照: target/vllm/vllm/entrypoints/llm.py:396 (generate)

LLM.generate(prompts, sampling_params)                      # L396
  → _run_completion(prompts, params)                        # L449
    → _add_request(prompt, params) × N                      # L1850
    │  ├─ input_processor.process_inputs(prompt, params)    # L1879
    │  └─ llm_engine.add_request(request_id, request, ...)  # L1889
    → _run_engine()                                         # L1900
       while has_unfinished_requests():                     # L1918
         step_outputs = llm_engine.step()                   # L1919

同期パスとの主な違い:

• LLMは_run_engine()でポーリングループを回す（AsyncGeneratorではない）
• llm_engine（=AsyncLLMのラッパー）のstep()を直接呼ぶ
• プログレスバー（tqdm）でバッチ処理の進捗を表示

入力処理 (InputProcessor)

InputProcessorはユーザー入力（テキストプロンプト、パラメータ）をEngineCoreRequestに変換する。

参照: target/vllm/vllm/v1/engine/input_processor.py:56 (InputProcessor)

InputProcessor.process_inputs(request_id, prompt, params)   # L521
  ├─ _validate_lora(lora_request)                           # L535
  ├─ _validate_params(params)                               # L536
  ├─ data_parallel_rank の範囲チェック                       # L542
  ├─ arrival_time 設定（未指定なら time.time()）             # L548
  │
  ├─ input_preprocessor.preprocess(prompt, ...)             # L581
  │   → テキストをトークナイズ（tokenizer.encode()）
  │   → ProcessorInputs を返す
  │
  ├─ split_enc_dec_inputs(processed_inputs)                 # L597
  │   → エンコーダ/デコーダ入力を分離
  │
  ├─ SamplingParams の正規化                                # L608-623
  │   ├─ params.clone()                                     # L612
  │   ├─ max_tokens 未設定時: max_model_len - seq_len       # L614-618
  │   ├─ update_from_generation_config()                    # L619
  │   └─ update_from_tokenizer()                            # L623
  │
  └─ EngineCoreRequest を構築して返す                        # L656-671

テキスト推論の場合、マルチモーダル関連処理（L630-654）はスキップされる（mm_featuresはNone）。

プロセス間通信 (EngineCoreClient / ZMQ IPC)

EngineCoreClientはフロントエンドプロセスとバックエンドプロセス（EngineCore）間のZMQ IPC通信を担当する。

参照: target/vllm/vllm/v1/engine/core_client.py:63 (EngineCoreClient)

クライアント階層

参照: target/vllm/vllm/v1/engine/core_client.py:442 (MPClient)

ZMQソケット構成

フロントエンド                 バックエンド
┌──────────────┐              ┌──────────────┐
│ AsyncMPClient│              │ EngineCore   │
│              │              │              │
│ input_socket ├─── ROUTER ──→│ (受信)       │
│ (zmq.ROUTER) │    msgpack   │              │
│              │              │              │
│ output_socket│←── PULL ─────┤ (送信)       │
│ (zmq.PULL)   │    msgpack   │              │
└──────────────┘              └──────────────┘

• シリアライゼーション: MsgpackEncoder / MsgpackDecoder（msgspecライブラリ）
  • EngineCoreRequestのシリアライズ → 入力ソケット経由で送信
  • EngineCoreOutputsのデシリアライズ ← 出力ソケット経由で受信
• 非同期出力受信: process_outputs_socket()タスクがZMQソケットをポーリングし、受信したOutputsをasyncio.Queueにpush

参照: target/vllm/vllm/v1/engine/core_client.py:822 (AsyncMPClient)

EngineCore側のリクエスト受信

EngineCore.add_request()はリクエストをバリデーションしてSchedulerに登録する。

参照: target/vllm/vllm/v1/engine/core.py:288 (add_request)

EngineCore.add_request(request)                             # L288
  ├─ request_id の型チェック                                 # L295
  ├─ pooling_params のバリデーション                          # L300
  ├─ kv_transfer_params の互換性チェック                      # L311
  └─ scheduler.add_request(request)                          # L319

EngineCore.step() （コアループ概要）

参照: target/vllm/vllm/v1/engine/core.py:389 (step)

EngineCore.step()                                            # L389
  ├─ scheduler.schedule()        → SchedulerOutput           # L404
  ├─ executor.execute_model()    → Future[ModelRunnerOutput]  # L405
  ├─ grammar_output 取得                                      # L406
  ├─ future.result()             → ModelRunnerOutput          # L411
  ├─ sample_tokens()（非同期スケジューリング時）              # L413
  └─ scheduler.update_from_output() → EngineCoreOutputs      # L418

コアループ: EngineCore.step()

EngineCoreのstep()メソッドは、各ステップで schedule → execute → update のサイクルを実行し、待機中のリクエストから生成トークンを生産する。

step() 実行フロー

参照: target/vllm/vllm/v1/engine/core.py:389 (step)

EngineCore.step()                                            # L389
  │
  ├─ if _scheduler_paused: return {}, False                  # L397
  ├─ if not scheduler.has_requests(): return {}, False       # L402
  │
  ├─ 1. scheduler_output = scheduler.schedule()              # L404
  │      → SchedulerOutput
  │      （RUNNINGリクエストの予算割当 → WAITINGリクエストの受け入れ
  │        → KVキャッシュブロック確保 → SchedulerOutput構築）
  │
  ├─ 2. future = executor.execute_model(                     # L405
  │         scheduler_output, non_block=True)
  │      → Future[ModelRunnerOutput | None]
  │      （非ブロッキング。ワーカープロセスで並行実行）
  │
  ├─ 3. grammar_output = scheduler.get_grammar_bitmask(      # L406
  │         scheduler_output)
  │      （構造化出力有効時のみ使用）
  │
  ├─ 4. model_output = future.result()                       # L411
  │      → ModelRunnerOutput（ブロッキング待機）
  │
  ├─ 5. if model_output is None:                             # L413
  │        model_output = executor.sample_tokens(grammar_output)
  │      （非同期スケジューリング時: execute_modelとsamplingが分離）
  │
  ├─ 6. _process_aborts_queue()                              # L417
  │
  └─ 7. engine_core_outputs = scheduler.update_from_output(  # L418
  │         scheduler_output, model_output)
  │      → dict[int, EngineCoreOutputs]
  │      （生成トークンの追加、完了判定、出力構築）
  │
  └─ return (engine_core_outputs,                            # L422
             total_num_scheduled_tokens > 0)

Scheduler と KVCacheManager の相互作用

sequenceDiagram
    participant EC as EngineCore
    participant S as Scheduler
    participant KV as KVCacheManager
    participant Ex as Executor

    EC->>S: schedule()

    Note over S: Phase 1: RUNNINGリクエスト処理
    loop 各RUNNINGリクエスト
        S->>KV: allocate_slots(request, num_new_tokens)
        KV-->>S: KVCacheBlocks or None
        alt 割り当て失敗 (None)
            S->>KV: free(低優先度request)
            Note over S: プリエンプション → 再試行
        end
    end

    Note over S: Phase 2: WAITINGリクエスト受け入れ
    loop 各WAITINGリクエスト
        S->>KV: get_computed_blocks(request)
        KV-->>S: (cached_blocks, num_hits)
        S->>KV: allocate_slots(request, num_new_tokens, ...)
        KV-->>S: KVCacheBlocks or None
        alt 割り当て失敗 (None)
            Note over S: break（ループ終了）
        end
    end

    Note over S: Phase 3: SchedulerOutput構築
    S-->>EC: SchedulerOutput

    EC->>Ex: execute_model(scheduler_output)
    Ex-->>EC: Future[ModelRunnerOutput]
    EC->>EC: future.result()（待機）

    EC->>S: update_from_output(scheduler_output, model_output)
    Note over S: トークン追加、完了判定
    S-->>EC: dict[int, EngineCoreOutputs]

Scheduler.schedule() の3フェーズ

参照: target/vllm/vllm/v1/core/sched/scheduler.py:321 (schedule)

schedule() は Unified Compute Model を採用し、Prefill/Decodeを区別せず num_computed_tokens の進捗で統一的にトークンを割り当てる。

トークン予算: token_budget = max_num_scheduled_tokens（ステップあたり上限）で、各リクエストのスケジュール時に消費される。

詳細は Scheduler サマリー を参照。

KVCacheManager のブロック割り当て

参照: target/vllm/vllm/v1/core/kv_cache_manager.py:206 (allocate_slots)

allocate_slots() は以下のブロック配置に基づいてGPUメモリブロックを確保する:

|  comp  | new_comp | ext_comp |   new   | lookahead |
|<------ 既計算トークン ------>|<-- 新規計算対象 -->|
                               |<- 割り当て対象 ->|

• 成功時: KVCacheBlocks（割り当てたブロック情報）を返す
• 失敗時: None を返す → Schedulerがプリエンプション（RUNNING）またはスキップ（WAITING）

プレフィックスキャッシュ検索は get_computed_blocks() で行い、過去に計算済みのブロックを再利用する。

詳細は KVCacheManager サマリー を参照。

update_from_output() → EngineCoreOutputs

参照: target/vllm/vllm/v1/core/sched/scheduler.py:1241 (update_from_output)

ModelRunnerOutputを受けてSchedulerの状態を更新し、クライアントに返すEngineCoreOutputsを構築する。

update_from_output(scheduler_output, model_runner_output)
  for each scheduled request:
    ├─ Speculative Decodingリジェクション処理
    │   → 不採用分の num_computed_tokens 巻き戻し
    ├─ 生成トークンをリクエストに追加
    ├─ 完了判定（EOS、max_tokens、stop_token）
    │   → 完了時: kv_cache_manager.free(request) でブロック解放
    └─ EngineCoreOutput 構築（request_id, new_token_ids, finish_reason, ...）
  → dict[int, EngineCoreOutputs]（クライアントインデックス別）

下流パス: 実行 → ユーザー応答

実行層: Executor → Worker → GPUModelRunner

EngineCore.step()はexecutor.execute_model()を非ブロッキングで呼び出し、GPUでの推論実行を開始する。

参照: target/vllm/vllm/v1/executor/abstract.py:202 (execute_model)

collective_rpc パターン

Executorはcollective_rpc()パターンで全Workerに同一メソッドを実行させ、出力ランクのWorkerの結果のみを返す。

EngineCore.step()
  │
  ├─ executor.execute_model(scheduler_output, non_block=True)
  │   └─ collective_rpc("execute_model", args=(scheduler_output,))
  │       └─ Worker.execute_model(scheduler_output)                # L604
  │           └─ model_runner.execute_model(scheduler_output)      # L652
  │               → ExecuteModelState を内部保存、None を返す
  │
  ├─ grammar_output = scheduler.get_grammar_bitmask(...)           # 並行処理
  │
  ├─ future.result()  → None                                       # 待機
  │
  └─ executor.sample_tokens(grammar_output)                         # L222
      └─ collective_rpc("sample_tokens", args=(grammar_output,))
          └─ Worker.sample_tokens(grammar_output)                  # L598
              └─ model_runner.sample_tokens(grammar_output)        # L3621
                  → ModelRunnerOutput を返す

参照: target/vllm/vllm/v1/worker/gpu_worker.py:604 (Worker.execute_model)

GPUModelRunner の2フェーズ実行

GPUModelRunnerは execute_model() と sample_tokens() を分離する2フェーズ実行パターンを採用する。これにより、モデルフォワード中にgrammar bitmask計算を並行実行できる。

Phase 1: execute_model() (target/vllm/vllm/v1/worker/gpu_model_runner.py:3312)

execute_model(scheduler_output)
  ├─ _update_states(scheduler_output)          # バッチ状態更新
  ├─ _prepare_inputs(scheduler_output)         # 入力ID・位置計算
  ├─ _build_attention_metadata(...)            # Attention メタデータ構築
  ├─ _model_forward(...)                       # model.forward() 実行
  │   → hidden_states
  ├─ compute_logits(hidden_states)             # logits 計算
  │   → logits
  └─ ExecuteModelState に保存 → None を返す

Phase 2: sample_tokens() (target/vllm/vllm/v1/worker/gpu_model_runner.py:3621)

sample_tokens(grammar_output)
  ├─ ExecuteModelState を復元
  ├─ grammar bitmask 適用（構造化出力時）
  ├─ _sample(logits) → SamplerOutput
  ├─ バッチ状態更新（生成トークン反映）
  └─ ModelRunnerOutput を構築して返す

ExecuteModelState (target/vllm/vllm/v1/worker/gpu_model_runner.py:313) はGPUテンソル（logits, hidden_states等）を保持するNamedTupleで、2フェーズ間の一時状態転送に使用される。

出力処理: EngineCoreOutput → RequestOutput

ModelRunnerOutputはバックエンドプロセス（EngineCore）でEngineCoreOutputに変換され、ZMQ経由でフロントエンドプロセスのOutputProcessorに送られてデトークナイズされる。

sequenceDiagram
    participant MR as GPUModelRunner
    participant S as Scheduler
    participant EC as EngineCore
    participant ZMQ as ZMQ IPC
    participant OP as OutputProcessor
    participant Client as API Client

    MR->>EC: ModelRunnerOutput
    EC->>S: update_from_output()
    Note over S: トークン追加、完了判定<br>KVキャッシュ解放
    S->>EC: dict[int, EngineCoreOutputs]

    EC->>ZMQ: msgpack シリアライズ
    ZMQ->>OP: EngineCoreOutputs

    Note over OP: デトークナイズ<br>停止文字列判定<br>logprobs処理
    OP->>Client: RequestOutput (yield)

OutputProcessor.process_outputs()

参照: target/vllm/vllm/v1/engine/output_processor.py:582 (process_outputs)

OutputProcessorはフロントエンドプロセスで動作し、EngineCoreOutputをユーザー向けRequestOutputに変換する。

OutputProcessor.process_outputs(engine_core_outputs)       # L582
  for each engine_core_output:
    ├─ req_state = request_states[req_id]                  # RequestState取得
    │
    ├─ detokenizer.update(new_token_ids, stop_terminated)  # L637
    │   ├─ トークン→テキスト変換（インクリメンタル）
    │   └─ 停止文字列チェック → stop_string or None
    │
    ├─ logprobs_processor.update_from_output(output)       # L646
    │
    ├─ req_state.make_request_output(...)                   # L649
    │   ├─ _new_completion_output(token_ids, finish_reason, ...)
    │   │   ├─ detokenizer.get_next_output_text(finished, delta)
    │   │   └─ CompletionOutput(text, token_ids, logprobs, ...)
    │   └─ RequestOutput(request_id, outputs, finished, ...)
    │
    └─ req_state.queue.put(request_output)                 # L661
        → AsyncLLM.generate() が yield

Detokenizer（インクリメンタルデトークナイズ）

参照: target/vllm/vllm/v1/engine/detokenizer.py:30 (IncrementalDetokenizer)

トークンからテキストへの変換はインクリメンタルに行われ、ストリーミング出力を実現する。

update()メソッドで各トークンをインクリメンタルにデコードし、同時にcheck_stop_strings()で停止文字列を検出する（target/vllm/vllm/v1/engine/detokenizer.py:316）。

Prefill vs Decode

vLLM v1はUnified Compute Modelを採用し、PrefillとDecodeを明示的に区別しない。両者はnum_computed_tokensの進捗によって暗黙的に区分される。

統一管理の仕組み

各リクエストはnum_computed_tokensフィールドで計算済みトークン数を追跡する:

プロンプト: [A, B, C, D, E]    (len=5)
num_computed_tokens: 0 → 5 → 6 → 7 → ...

Prefillフェーズ: num_computed_tokens < len(prompt_token_ids)
  → 複数トークンを一度に計算（チャンクプリフィル可能）

Decodeフェーズ: num_computed_tokens >= len(prompt_token_ids)
  → 1トークンずつ生成

Schedulerでの扱い

Scheduler.schedule()はPrefill/Decodeを区別せず、トークン予算の範囲内で各リクエストに計算トークン数を割り当てる:

• 新規リクエスト（WAITING→RUNNING）: num_tokens = len(prompt_token_ids) - num_computed_tokens（プレフィックスキャッシュヒット分を差し引き）
• 継続リクエスト（RUNNING）: num_tokens = 1（Decode 1トークン）
• 予算不足時は部分的なPrefill（チャンクプリフィル）も可能

GPUModelRunner内での違い

GPUModelRunner.execute_model()は入力準備の段階で暗黙的にPrefill/Decodeを処理する:

• _prepare_inputs(): num_scheduled_tokensに基づいて入力トークンと位置を計算。Prefillなら複数トークン、Decodeなら1トークン
• _build_attention_metadata(): Prefillはフルattention、Decodeはキャッシュ済みKVに対するattentionのメタデータを構築
• モデルフォワード: 入力テンソルのサイズが異なるだけで、同一のforward()を実行

この統一モデルにより、同一バッチ内にPrefillリクエストとDecodeリクエストを混在させるContinuous Batchingが自然に実現される。

コンポーネント優先度（確定）

Phase 2での深堀り順序。ユーザー関心領域とフロー上の重要度に基づく。

参照ファイル一覧

マルチモーダル推論パスの差分

テキスト推論フローに対し、画像等のマルチモーダル入力がある場合の主要な差分を以下に示す。詳細は マルチモーダル処理パイプライン を参照。

フロントエンド（P0）の差分

1. チャットテンプレート: プレースホルダー（<start_of_image> 等）がプロンプトに挿入される
2. HF Processor実行: 画像を pixel_values テンソルに変換（リサイズ、正規化、パッチ分割）
3. MMハッシュ計算: MultiModalHasher でコンテンツベースのblake3ハッシュを生成
4. ProcessorCache: HF処理結果をキャッシュ（4種類の実装: processor_only/lru/shm/none）
5. EngineCoreRequest: mm_features: list[MultiModalFeatureSpec] にテンソルデータ・位置情報・ハッシュを格納

バックエンド（P1）の差分

1. EncoderCacheManager: エンコーダ出力をリファレンスカウント方式で管理。キャッシュヒットでエンコーダ計算スキップ
2. Scheduler: encoder_compute_budget でステップあたりのエンコーダ計算量を制御
3. GPUModelRunner:
   • _execute_mm_encoder(): ビジョンエンコーダ実行（model.embed_multimodal()）
   • _gather_mm_embeddings(): キャッシュからプレースホルダー位置に対応する埋め込みを取得
   • embed_input_ids(): masked_scatter_ でテキスト埋め込みとビジョン埋め込みをマージ
4. モデルforward: input_ids ではなく inputs_embeds（マージ済み）が渡される

アーキテクチャ概要

深度: [SHALLOW] 確信度: [VERIFIED] 最終更新: 2026-02-09

概要

vLLMはUC Berkeley Sky Computing Lab発のLLM推論・サービングライブラリである。PagedAttentionによるKVキャッシュの効率的メモリ管理、Continuous Batchingによる動的バッチスケジューリングを中核技術とし、高スループット・低レイテンシのLLM推論を実現する。OpenAI互換APIサーバー、マルチモーダル対応、分散推論（Tensor/Pipeline/Data/Expert並列）を備える。

全体構造

graph TD
    subgraph エントリポイント層
        CLI["CLI<br>vllm.entrypoints.cli"]
        LLM["LLM<br>vllm.entrypoints.llm:101"]
        OpenAI["OpenAI互換API<br>vllm.entrypoints.openai"]
    end

    subgraph エンジン層
        AsyncLLM["AsyncLLM<br>vllm.v1.engine.async_llm:71"]
        LLMEngine["LLMEngine<br>vllm.v1.engine.llm_engine"]
        EngineCore["EngineCore<br>vllm.v1.engine.core:79"]
        InputProc["InputProcessor"]
        OutputProc["OutputProcessor"]
    end

    subgraph コア層
        Scheduler["Scheduler<br>vllm.v1.core.sched.scheduler:63"]
        KVCacheMgr["KVCacheManager<br>vllm.v1.core.kv_cache_manager:94"]
        BlockPool["BlockPool<br>vllm.v1.core.block_pool"]
    end

    subgraph 実行層
        Executor["Executor<br>vllm.v1.executor"]
        Worker["Worker<br>vllm.v1.worker.gpu_worker:70"]
        ModelRunner["GPUModelRunner<br>vllm.v1.worker.gpu_model_runner:329"]
    end

    subgraph モデル層
        Models["Models<br>vllm.model_executor.models<br>241ファイル"]
        Attention["Attention<br>2層構造"]
        Layers["Layers<br>vllm.model_executor.layers"]
    end

    CLI --> AsyncLLM
    LLM --> LLMEngine
    OpenAI --> AsyncLLM

    AsyncLLM -->|"ZMQ IPC"| EngineCore
    LLMEngine --> EngineCore
    EngineCore --> InputProc
    EngineCore --> OutputProc

    EngineCore --> Scheduler
    EngineCore --> KVCacheMgr
    KVCacheMgr --> BlockPool

    EngineCore --> Executor
    Executor --> Worker
    Worker --> ModelRunner

    ModelRunner --> Models
    ModelRunner --> Attention
    Models --> Layers

アーキテクチャの世代

vllm/engine/ は vllm/v1/ への薄いラッパーである。

参照: target/vllm/vllm/engine/llm_engine.py:4 — LLMEngine = V1LLMEngine の1行エイリアス

v1が現行アーキテクチャの本体であり、コードリーディングでは vllm/v1/ を中心に読む。ただし vllm/model_executor/、vllm/distributed/、vllm/multimodal/ 等はv1からも直接利用されるため調査対象に含む。

主要コンポーネント

設計原則

PagedAttention

KVキャッシュをOSの仮想メモリページングに着想を得てブロック単位で管理する。連続したGPUメモリ確保が不要になり、メモリ断片化を大幅に抑制する。

Continuous Batching

リクエストの到着・完了に応じてバッチを動的に更新する。固定バッチサイズと異なり、GPU稼働率を最大化できる。

ZMQ IPC によるプロセス分離

EngineCoreは別プロセス（EngineCoreProc）として動作し、ZeroMQソケットで上位エンジン層と通信する。これによりスケジューリングと推論処理を並行実行できる。

プラグインシステム

vllm/plugins/ によるプラグイン機構を備え、起動時に load_general_plugins() で拡張を読み込む。

C++/CUDA 拡張

target/vllm/csrc/ にパフォーマンスクリティカルなネイティブコードが配置されている。PagedAttentionカーネル、LayerNorm、量子化カーネル、カスタムAllReduce等が含まれる。Pythonからは vllm._custom_ops 等のバインディング経由で呼び出される。

参照ファイル

ECConnector（Encoder Cache Connector）

深度: [MEDIUM] | 確信度: [VERIFIED] | 最終更新: 2026-02-14

概要

ECConnectorは、マルチモーダルモデルのエンコーダ出力をvLLMインスタンス間または外部ストレージと転送するためのプラグインフレームワークである。KV Transfer（デコーダKVキャッシュ用）とは完全に独立した系統で、エンコーダキャッシュに特化している。

主なユースケースは**Encoder-Prefill-Decode分離（EPD）**で、エンコーダ専用インスタンスが画像処理を行い、その結果をデコーダインスタンスに転送する。

参照: target/vllm/vllm/distributed/ec_transfer/ (パッケージ全体)

アーキテクチャ

ファイル構成

vllm/distributed/ec_transfer/
├── __init__.py                          # get_ec_transfer(), has_ec_transfer() 公開API
├── ec_transfer_state.py                 # グローバルシングルトン管理
└── ec_connector/
    ├── __init__.py
    ├── base.py                          # ECConnectorBase 抽象基底クラス
    ├── factory.py                       # ECConnectorFactory レジストリ + 動的ロード
    └── example_connector.py             # ECExampleConnector 参照実装（safetensors）

vllm/v1/worker/
└── ec_connector_model_runner_mixin.py   # GPUModelRunner統合Mixin

vllm/config/
└── ec_transfer.py                       # ECTransferConfig 設定クラス

2ロール分離アーキテクチャ

ECConnectorはScheduler側とWorker側に分離され、同じクラスが両方のロールを担う：

graph TB
    subgraph "Scheduler Process (ECConnectorRole.SCHEDULER)"
        SC[ECConnector Scheduler側]
        SCH[Scheduler]
        SCH -->|has_cache_item| SC
        SCH -->|update_state_after_alloc| SC
        SCH -->|build_connector_meta| SC
    end

    subgraph "Worker Process (ECConnectorRole.WORKER)"
        WC[ECConnector Worker側]
        GMR[GPUModelRunner]
        GMR -->|bind_connector_metadata| WC
        GMR -->|start_load_caches| WC
        GMR -->|save_caches| WC
        GMR -->|get_finished| WC
    end

    SC -->|ECConnectorMetadata<br/>SchedulerOutput経由| WC

参照: target/vllm/vllm/v1/core/sched/scheduler.py:135-138 (Scheduler側生成) 参照: target/vllm/vllm/distributed/ec_transfer/ec_transfer_state.py:26-43 (Worker側生成)

ECConnectorBase 抽象基底クラス

参照: target/vllm/vllm/distributed/ec_transfer/ec_connector/base.py:59-253

プロパティ

抽象メソッド（実装必須）

Worker側（3メソッド）

Scheduler側（3メソッド）

具象メソッド（オーバーライド任意）

ECTransferConfig 設定

参照: target/vllm/vllm/config/ec_transfer.py:16-108

ECロール

ECRole = Literal["ec_producer", "ec_consumer", "ec_both"]

主要設定パラメータ

ECConnectorFactory

参照: target/vllm/vllm/distributed/ec_transfer/ec_connector/factory.py:20-85

コネクタ登録方式

2つの登録方法がある：

1. 静的登録: ECConnectorFactory.register_connector() でモジュール遅延ロード登録
2. 動的ロード: ec_connector_module_path で任意のPythonモジュールからロード

# 静的登録（factory.py末尾）
ECConnectorFactory.register_connector(
    "ECExampleConnector",
    "vllm.distributed.ec_transfer.ec_connector.example_connector",
    "ECExampleConnector",
)

# 動的ロード（ec_connector_module_pathが設定されている場合）
connector_module = importlib.import_module(connector_module_path)
connector_cls = getattr(connector_module, connector_name)

現在登録済みコネクタ

ECExampleConnector 参照実装

参照: target/vllm/vllm/distributed/ec_transfer/ec_connector/example_connector.py:45-199

safetensorsフォーマットでディスクにエンコーダキャッシュを保存/読み込みする参照実装。

メタデータ

@dataclass
class MMMeta:
    mm_hash: str      # マルチモーダルデータのハッシュ
    num_token: int     # エンコーダトークン数

@dataclass
class ECExampleConnectorMetadata(ECConnectorMetadata):
    mm_datas: list[MMMeta]  # ロードすべきエントリ一覧

ストレージ構造

{shared_storage_path}/
└── {mm_hash}/
    └── encoder_cache.safetensors    # {"ec_cache": Tensor} 形式

動作フロー

保存（Producer側）

参照: target/vllm/vllm/distributed/ec_transfer/ec_connector/example_connector.py:98-118

1. GPUModelRunnerが _execute_mm_encoder() 完了後に maybe_save_ec_to_connector() を呼ぶ
2. save_caches(): テンソルを .detach().cpu() してsafetensorsで保存

読み込み（Consumer側）

参照: target/vllm/vllm/distributed/ec_transfer/ec_connector/example_connector.py:63-96

1. Scheduler側: has_cache_item() でファイル存在確認 (os.path.exists)
2. Scheduler側: build_connector_meta() でロード対象リストを構築
3. Worker側: start_load_caches() でsafetensorsからGPUにロード

存在確認

has_cache_item() は os.path.exists() でsafetensorsファイルの存在をチェック。

Schedulerとの統合

_schedule_encoder_inputs() 内の分岐

参照: target/vllm/vllm/v1/core/sched/scheduler.py:1212-1218

if self.ec_connector is not None and self.ec_connector.has_cache_item(identifier):
    # 外部キャッシュにヒット → エンコーダ計算不要、compute_budget消費なし
    mm_hashes_to_schedule.add(item_identifier)
    external_load_encoder_input.append(i)
    num_embeds_to_schedule += num_encoder_embeds
    continue

ECConnectorにキャッシュがある場合：

• encoder_compute_budget は消費しない（エンコーダ計算不要のため）
• external_load_encoder_input リストに追加
• encoder_cache_manager.allocate() は実行される（GPU側に空きが必要）

割当後の状態更新

参照: target/vllm/vllm/v1/core/sched/scheduler.py:523-527

if external_load_encoder_input:
    for i in external_load_encoder_input:
        self.encoder_cache_manager.allocate(request, i)
        if self.ec_connector is not None:
            self.ec_connector.update_state_after_alloc(request, i)

メタデータ構築

参照: target/vllm/vllm/v1/core/sched/scheduler.py:899-904

build_connector_meta() がSchedulerOutputに ec_connector_metadata を設定。Worker側はこのメタデータを使ってロード対象を特定する。

GPUModelRunnerとの統合

ECConnectorModelRunnerMixin

参照: target/vllm/vllm/v1/worker/ec_connector_model_runner_mixin.py:25-87

GPUModelRunnerに3つのstatic methodを提供：

コンテキストマネージャのライフサイクル

with self.maybe_get_ec_connector_output(scheduler_output, encoder_cache) as output:
    # 1. bind_connector_metadata() → メタデータ設定
    # 2. Consumer時: start_load_caches() → 外部からロード
    # 3. yield → エンコーダ実行、gather処理
    # 4. get_finished() → 非同期完了確認
    # 5. clear_connector_metadata() → クリーンアップ

Producer専用モード

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:3343-3349

Producer専用インスタンスは、エンコーダ実行後にデコーダ実行をスキップし、空のModelRunnerOutputを返す：

if has_ec_transfer() and get_ec_transfer().is_producer:
    with self.maybe_get_ec_connector_output(...) as ec_connector_output:
        self._execute_mm_encoder(scheduler_output)
        return make_empty_encoder_model_runner_output(scheduler_output)

また、Producer専用インスタンスはKVキャッシュを確保しない：

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:6160-6161

if has_ec_transfer() and get_ec_transfer().is_producer:
    return {}  # KVCacheSpec空 → KVキャッシュ確保なし

ECConnectorOutput

参照: target/vllm/vllm/v1/outputs.py:151-154

@dataclass
class ECConnectorOutput:
    finished_sending: set[str] | None = None
    finished_recving: set[str] | None = None

ModelRunnerOutputに含まれてScheduler側に返されるが、現時点ではScheduler側で未消費（ec_connector_outputを読み取るコードがSchedulerにない）。非同期転送完了フィードバックは将来実装予定。

グローバルシングルトン管理

参照: target/vllm/vllm/distributed/ec_transfer/ec_transfer_state.py:14-43

_EC_CONNECTOR_AGENT: ECConnectorBase | None = None

Worker側のシングルトン初期化は gpu_worker.py で ensure_ec_transfer_initialized() を呼ぶことで行われる。Scheduler側は ECConnectorFactory.create_connector() で直接生成し、self.ec_connector に保持する（シングルトンではない）。

カスタムECConnector実装ガイド

最小実装

1. ECConnectorBase を継承
2. 5つの抽象メソッドを実装
3. ECTransferConfigのec_connectorにクラス名、ec_connector_module_pathにモジュールパスを指定

実装の要点

• has_cache_item() はSchedulerのホットパスで呼ばれるため高速であるべき
• start_load_caches() は encoder_cache dict に直接テンソルを追加する
• save_caches() は encoder_cache[mm_hash] からGPUテンソルを取得して保存する
• build_connector_meta() は内部状態をリセットすること

起動コマンド例

# Producer（エンコーダ専用インスタンス）
vllm serve model_name \
    --ec-connector ECExampleConnector \
    --ec-role ec_producer \
    --ec-connector-extra-config '{"shared_storage_path": "/shared/cache"}'

# Consumer（デコーダインスタンス）
vllm serve model_name \
    --ec-connector ECExampleConnector \
    --ec-role ec_consumer \
    --ec-connector-extra-config '{"shared_storage_path": "/shared/cache"}'

上流・下流依存関係

上流

• ECTransferConfig: ec_connector, ec_role 等の設定
• Scheduler: キャッシュ存在確認、状態更新、メタデータ構築の呼び出し
• GPUModelRunner: エンコーダ実行結果の保存、ロード済みキャッシュの利用

下流

• 外部ストレージ: safetensors（例）、共有メモリ、ネットワーク等（実装依存）

開発状況・未実装機能

1. ECConnectorOutput未消費: Worker→Scheduler方向の非同期転送完了フィードバックが未実装
2. request_finished未統合: Schedulerからec_connector.request_finished()が呼ばれていない
3. register_caches未実装: P2P直接転送のためのキャッシュ登録（TODO）
4. エンコーダキャッシュ事前割り当て未対応: encoder_cache が dict のため、固定バッファへの移行が必要
5. 登録済みコネクタが1つのみ: ECExampleConnector（デバッグ用）のみ。SHMConnector等は外部PR待ち

EncoderCache（エンコーダキャッシュ）

深度: [MEDIUM] | 確信度: [VERIFIED] | 最終更新: 2026-02-14

概要

EncoderCacheは、マルチモーダルモデルにおけるエンコーダ出力（例: ビジョンエンコーダの画像埋め込み）のGPUメモリ上キャッシュを管理するコンポーネントである。2層構造で、Scheduler側の論理管理（EncoderCacheManager）とWorker側の物理ストレージ（GPUModelRunner.encoder_cache）に分離されている。

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py (EncoderCacheManager)

アーキテクチャ

2層構造

graph TB
    subgraph Scheduler Process
        ECM[EncoderCacheManager<br/>論理管理]
    end
    subgraph Worker Process
        EC["encoder_cache: dict[str, Tensor]<br/>GPU物理ストレージ"]
    end
    ECM -->|"free_encoder_mm_hashes<br/>(SchedulerOutput経由)"| EC
    ECM -->|"scheduled_encoder_inputs<br/>(何を計算すべきか)"| EC

EncoderCacheManager 詳細

主要フィールド

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:67-77

Eviction方式: FIFO（参照ゼロエントリの遅延解放）

EncoderCacheManagerは遅延解放FIFO方式を採用する：

1. リクエスト完了時、参照カウントが0になったエントリは即座には解放されず freeable OrderedDictに追加
2. 新しいエンコーダ出力のキャッシュ確保（can_allocate()）時に空きが不足した場合のみ、古い順にEviction
3. Evictionされたmm_hashは freed リストに追加され、次の get_freed_mm_hashes() でWorkerに通知
4. Worker側で encoder_cache.pop(mm_hash) により物理メモリ解放

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:119-178 (can_allocate)

stateDiagram-v2
    [*] --> Active: allocate()
    Active --> Active: check_and_update_cache()で新リクエスト参照追加
    Active --> Freeable: free_encoder_input()で参照カウント=0
    Freeable --> Active: check_and_update_cache()で再参照
    Freeable --> Evicted: can_allocate()で空き不足時
    Evicted --> [*]: Worker側でpop()

共有キャッシュ

同じ画像を含む複数リクエストが同時に処理される場合、同一のmm_hashを持つエンコーダ出力は共有される。cached dictのvalue（set[str]）が複数リクエストIDを保持し、全リクエストの完了後にのみfreeableに移行する。

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:91-117 (check_and_update_cache)

主要メソッド

キャッシュ容量の決定

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:269-316 (compute_mm_encoder_budget)

encoder_compute_budget = max(max_num_encoder_input_tokens, max_tokens_per_mm_item)
encoder_cache_size = max(encoder_cache_size_config, max_tokens_per_mm_item)

• max_tokens_per_mm_item: モデルがサポートする全モダリティの最大トークン数
• max_num_encoder_input_tokens: SchedulerConfig設定値
• 1アイテムは必ずキャッシュできることを保証

GPUModelRunner.encoder_cache（物理ストレージ）

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:439

self.encoder_cache: dict[str, torch.Tensor] = {}

• キー: mm_hash（マルチモーダルデータのidentifier）
• 値: エンコーダ出力テンソル（GPU上）
• 書き込み: _execute_mm_encoder() 完了時に encoder_cache[mm_hash] = output
• 読み取り: _gather_mm_embeddings() でデコーダ入力に合成
• 削除: _update_states() で scheduler_output.free_encoder_mm_hashes に従い pop()

ECConnectorとの連携

エンコーダ出力をGPUキャッシュに保存した直後に、ECConnector（有効時）にも保存する：

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:2442-2445

for mm_hash, output in zip(mm_hashes, encoder_outputs):
    self.encoder_cache[mm_hash] = output
    self.maybe_save_ec_to_connector(self.encoder_cache, mm_hash)

Consumer側では、execute_model() の冒頭で ECConnector から encoder_cache にロードする：

参照: target/vllm/vllm/v1/worker/ec_connector_model_runner_mixin.py:76-77

if ec_connector.is_consumer:
    ec_connector.start_load_caches(encoder_cache, **kwargs)

EncoderDecoderCacheManager

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:323-382

Encoder-Decoderモデル（例: Whisper）用の暫定実装。EncoderCacheManagerを継承するがキャッシュ共有機能を持たず、毎回エンコーダを実行する。主な違い：

上流・下流依存関係

上流

• Scheduler: _schedule_encoder_inputs() でキャッシュヒット判定・割当・解放指示
• SchedulerConfig: encoder_cache_size, max_num_encoder_input_tokens で容量決定

下流

• GPUModelRunner: 物理テンソル保持、エンコーダ実行、gather処理
• ECConnector: 外部ストレージへの保存/読み込み（有効時）

データフロー

sequenceDiagram
    participant S as Scheduler
    participant ECM as EncoderCacheManager
    participant SO as SchedulerOutput
    participant GMR as GPUModelRunner
    participant EC as encoder_cache (GPU)

    Note over S: _schedule_encoder_inputs()
    S->>ECM: check_and_update_cache(req, i)
    alt キャッシュヒット
        ECM-->>S: True（計算スキップ）
    else キャッシュミス
        ECM-->>S: False
        S->>ECM: can_allocate(req, i, budget, scheduled)
        alt 空きあり（Eviction含む）
            ECM-->>S: True
            S->>ECM: allocate(req, i)
        else 空き不足
            ECM-->>S: False（トークン数調整）
        end
    end

    Note over S: _build_scheduler_output()
    S->>ECM: get_freed_mm_hashes()
    ECM-->>S: freed list
    S->>SO: free_encoder_mm_hashes, scheduled_encoder_inputs

    Note over GMR: execute_model()
    GMR->>EC: _execute_mm_encoder() → 保存
    GMR->>EC: _gather_mm_embeddings() → 読取
    GMR->>EC: _update_states() → free_encoder_mm_hashes に従い削除

注意事項

• キャッシュサイズはエンコーダ埋め込み数で測定される。画像間のテキストトークン（break tokens等）は含まない
• 物理メモリ解放はEviction判定（Scheduler側）と実際のpop()（Worker側）の間に1step以上のラグがある
• num_freeable_slots は num_free_slots 以上の値を常に持つ（freeable + free の合計）

EngineCore サマリー

深度: [MEDIUM] 確信度: [VERIFIED] 最終更新: 2026-02-11

概要

EngineCoreはバックエンドプロセス（EngineCoreProc）内で動作する推論ループの中央制御コンポーネントである。Scheduler、ModelExecutor、KVCacheManagerを統括し、step()メソッドで schedule → execute → update のサイクルを繰り返す。フロントエンドプロセスとはZMQ IPC経由で通信し、EngineCoreRequestを受信してEngineCoreOutputsを返す。

アーキテクチャ

graph TD
    subgraph EngineCoreプロセス
        EC["EngineCore"]
        Sched["Scheduler"]
        KVM["KVCacheManager"]
        Exec["ModelExecutor"]

        EC -->|"1. schedule()"| Sched
        Sched -->|"allocate_slots()"| KVM
        Sched -->|"SchedulerOutput"| EC
        EC -->|"2. execute_model()"| Exec
        Exec -->|"Future<ModelRunnerOutput>"| EC
        EC -->|"3. update_from_output()"| Sched
        Sched -->|"EngineCoreOutputs"| EC
    end

    ZMQ_IN["ZMQ ROUTER<br>(受信)"] -->|"EngineCoreRequest"| EC
    EC -->|"EngineCoreOutputs"| ZMQ_OUT["ZMQ PUSH<br>(送信)"]

主要コンポーネント

主要メソッド

step() サイクル

参照: target/vllm/vllm/v1/engine/core.py:389

EngineCore.step() -> tuple[dict[int, EngineCoreOutputs], bool]
  │
  ├─ スケジューラ停止チェック                           # L397
  │   if _scheduler_paused: return {}, False
  │
  ├─ リクエスト有無チェック                             # L402
  │   if not scheduler.has_requests(): return {}, False
  │
  ├─ 1. scheduler.schedule()                            # L404
  │   → SchedulerOutput
  │
  ├─ 2. executor.execute_model(scheduler_output,        # L405
  │       non_block=True)
  │   → Future[ModelRunnerOutput | None]
  │
  ├─ 3. scheduler.get_grammar_bitmask(scheduler_output) # L406
  │   → grammar_output（構造化出力用）
  │
  ├─ 4. future.result()                                 # L411
  │   → ModelRunnerOutput（ブロッキング待機）
  │
  ├─ 5. if model_output is None:                        # L413
  │       model_output = executor.sample_tokens(grammar_output)
  │   （非同期スケジューリング時: execute_modelとsamplingが分離）
  │
  ├─ 6. _process_aborts_queue()                         # L417
  │
  └─ 7. scheduler.update_from_output(                   # L418
  │       scheduler_output, model_output)
  │   → dict[int, EngineCoreOutputs]
  │
  └─ return (engine_core_outputs,                       # L422
             total_num_scheduled_tokens > 0)

戻り値:

• 第1要素: クライアントインデックス → EngineCoreOutputs のマッピング
• 第2要素: モデル実行が行われたか（total_num_scheduled_tokens > 0）

add_request() フロー

参照: target/vllm/vllm/v1/engine/core.py:288

add_request(request, request_wave=0)                    # L288
  ├─ request_id の型チェック（str必須）                   # L295
  ├─ pooling_params のタスクバリデーション                # L300
  ├─ kv_transfer_params の互換性チェック                  # L311
  └─ scheduler.add_request(request)                      # L319

batch_queue パイプライン並列化 [SHALLOW]

参照: target/vllm/vllm/v1/engine/core.py:434 (step_with_batch_queue)

max_concurrent_batches > 1 の場合、step_with_batch_queue() が step_fn として使用される。スケジューリングとモデル実行をパイプライン的にオーバーラップさせ、GPUのアイドル時間を削減する。

• batch_queue: deque[tuple[Future, SchedulerOutput, Future]]
• 新しいスケジュール結果を appendleft() で追加、完了待ちを pop() で取得
• 前のバッチの実行完了を待たずに次のバッチをスケジュール可能

KVキャッシュ初期化フロー [SHALLOW]

参照: target/vllm/vllm/v1/engine/core.py:82 (init)

EngineCore.__init__()
  → _initialize_kv_caches()
    → model_executor.get_kv_cache_specs()       # モデルのKVキャッシュ要件取得
    → determine_available_memory()               # GPUメモリプロファイリング
    → get_kv_cache_configs()                     # ブロック数等の設定算出
    → generate_scheduler_kv_cache_config()       # Scheduler用設定生成
    → model_executor.initialize_from_config()    # GPUメモリ確保

KV Connector（KV Transfer/LMCache連携）が有効な場合:

• scheduler.get_kv_connector() でコネクタ有無を確認 (L159)
• 各ワーカーのハンドシェイクメタデータを収集・統合 (L164-175)

async_scheduling [SHALLOW]

vllm_config.scheduler_config.async_scheduling で有効化。

• 通常: execute_model() がモデル実行 + トークンサンプリングをまとめて実行
• async有効時: execute_model() はモデル実行のみ（None を返す）→ sample_tokens() で別途サンプリング
• post_step() でのSpeculative Decodingドラフトトークン更新タイミングに影響

設定

呼び出しフロー

[EngineCoreProc イベントループ]
  ├─ ZMQ受信 → EngineCore.add_request()
  ├─ EngineCore.step_fn()  (= step() or step_with_batch_queue())
  │   ├─ Scheduler.schedule()
  │   ├─ ModelExecutor.execute_model()
  │   └─ Scheduler.update_from_output()
  ├─ EngineCore.post_step()
  └─ ZMQ送信 ← EngineCoreOutputs

関連ドキュメント

• Scheduler
• KVCacheManager
• EngineCoreClient
• エントリポイント
• データフロー

EngineCoreClient サマリー

深度: [SHALLOW] 確信度: [VERIFIED] 最終更新: 2026-02-09

概要

EngineCoreClientはフロントエンドプロセス（AsyncLLM / LLM）とバックエンドプロセス（EngineCore）間のプロセス間通信を抽象化するコンポーネントである。ZeroMQソケットとmsgpackシリアライゼーションを使用し、EngineCoreRequestの送信とEngineCoreOutputsの受信を効率的に行う。

アーキテクチャ

フロントエンドプロセス            バックエンドプロセス
┌───────────────────┐            ┌───────────────────┐
│  AsyncMPClient    │            │  EngineCore       │
│                   │            │                   │
│  input_socket     ├──ROUTER──→│  (ZMQ受信)        │
│  (zmq.ROUTER)     │  msgpack   │                   │
│                   │            │                   │
│  output_socket    │←──PULL────┤  (ZMQ送信)        │
│  (zmq.PULL)       │  msgpack   │                   │
│                   │            │                   │
│  outputs_queue    │            │                   │
│  (asyncio.Queue)  │            │                   │
└───────────────────┘            └───────────────────┘

主要コンポーネント

主要メソッド

EngineCoreClient (ABC)

AsyncMPClient

ファクトリ選択ロジック

参照: target/vllm/vllm/v1/engine/core_client.py:99 (make_async_mp_client)

make_async_mp_client(vllm_config, executor_class, ...)
  ├─ data_parallel_size > 1 の場合:
  │   ├─ external_lb → DPAsyncMPClient
  │   └─ internal_lb → DPLBAsyncMPClient
  └─ それ以外 → AsyncMPClient

設定

呼び出しフロー

[送信パス]
AsyncLLM.add_request()
  → engine_core.add_request_async(request)
    → AsyncMPClient._send_input(REQUEST, request)
      → MsgpackEncoder.encode(request)
      → input_socket.send_multipart(msg, copy=False)
        → ZMQ ROUTER → バックエンドプロセス

[受信パス]
process_outputs_socket() [バックグラウンドタスク]
  → output_socket.recv_multipart()
    → MsgpackDecoder.decode(frames) → EngineCoreOutputs
    → outputs_queue.put_nowait(outputs)

AsyncLLM._run_output_handler()
  → engine_core.get_output_async()
    → outputs_queue.get() → EngineCoreOutputs

設計上の特徴

• プロセス分離: EngineCoreが別プロセスで動作するため、GILの影響を受けずスケジューリングとGPU実行を並行可能
• msgpackシリアライゼーション: msgspec.Structのarray_like形式でコンパクトなバイナリ表現
• zero-copy: ZMQ copy=False でメモリコピーを最小化。テンソルバッキングバッファの追跡（add_pending_message）
• weakref: 出力タスクがクライアントへの循環参照を持たないようweakrefを使用

関連ドキュメント

• エントリポイント
• データフロー

エントリポイント (AsyncLLM / LLM) サマリー

深度: [SHALLOW] 確信度: [VERIFIED] 最終更新: 2026-02-09

概要

AsyncLLMとLLMはvLLMの2つの主要エントリポイントである。AsyncLLMはAPIサーバー（OpenAI互換API等）が使用する非同期パスで、LLMはオフラインバッチ推論用の同期パスである。どちらもInputProcessorで入力を処理し、EngineCoreClient経由でバックエンド（EngineCore）にリクエストを送信する。

アーキテクチャ

graph LR
    subgraph 非同期パス
        OpenAI["OpenAI API Server"] --> AsyncLLM
        AsyncLLM -->|"process_inputs()"| IP["InputProcessor"]
        IP -->|"EngineCoreRequest"| AsyncLLM
        AsyncLLM -->|"add_request_async()"| Client["EngineCoreClient"]
        Client -->|"ZMQ"| EC["EngineCore"]
    end

    subgraph 同期パス
        User["ユーザーコード"] --> LLM
        LLM -->|"process_inputs()"| IP2["InputProcessor"]
        IP2 -->|"EngineCoreRequest"| LLM
        LLM -->|"add_request()"| Client2["EngineCoreClient"]
    end

主要コンポーネント

主要メソッド

AsyncLLM

LLM

設定

呼び出しフロー

[APIサーバー or ユーザーコード]
  → AsyncLLM.generate() / LLM.generate()
    → InputProcessor.process_inputs()
      → EngineCoreRequest
    → EngineCoreClient.add_request_async()
      → ZMQ → EngineCore（別プロセス）

[バックグラウンド output_handler タスク]
  → EngineCoreClient.get_output_async()
    → EngineCoreOutputs
  → OutputProcessor.process_outputs()
    → RequestOutput → キューにpush

[generate() AsyncGenerator]
  → キューから取り出してyield

関連ドキュメント

• 入力処理
• EngineCoreClient
• データフロー

Executor

深度: [MEDIUM] 確信度: [VERIFIED] 最終更新: 2026-02-14

概要

Executorは、EngineCoreとWorker（GPUModelRunner）の間に位置する実行委譲レイヤーである。collective_rpc()パターンで全Workerに対して同一メソッドを呼び出し、出力ランクのWorkerの結果を返す。単一プロセス、マルチプロセス、Ray分散の3つの実装を持つ。

クラス階層

Executor (ABC)                                     abstract.py:36
├── UniProcExecutor                                uniproc_executor.py:26
│   └── ExecutorWithExternalLauncher               uniproc_executor.py:140
├── MultiprocExecutor                              multiproc_executor.py:93
└── RayDistributedExecutor                         ray_executor.py:62

参照: target/vllm/vllm/v1/executor/abstract.py:36 (Executor)

主要メソッド

collective_rpc()

参照: target/vllm/vllm/v1/executor/abstract.py:180 (collective_rpc)

全Workerに対して同一メソッドを実行するRPCメカニズム。

def collective_rpc(
    self,
    method: str | Callable[..., _R],  # メソッド名または関数
    timeout: float | None = None,
    args: tuple = (),
    kwargs: dict | None = None,
    non_block: bool = False,          # True: Future返却
) -> list[_R] | Future[list[_R]]

execute_model()

参照: target/vllm/vllm/v1/executor/abstract.py:202 (execute_model)

def execute_model(
    self,
    scheduler_output: SchedulerOutput,
    non_block: bool = False,
) -> ModelRunnerOutput | None | Future[ModelRunnerOutput | None]:
    output = self.collective_rpc("execute_model",
                                  args=(scheduler_output,),
                                  non_block=non_block)
    return output[0]   # 出力ランクWorkerの結果のみ返す

sample_tokens()

参照: target/vllm/vllm/v1/executor/abstract.py:222 (sample_tokens)

def sample_tokens(
    self,
    grammar_output: GrammarOutput | None,
    non_block: bool = False,
) -> ModelRunnerOutput | Future[ModelRunnerOutput]:
    output = self.collective_rpc("sample_tokens",
                                  args=(grammar_output,),
                                  non_block=non_block)
    return output[0]

実装の使い分け

MultiprocExecutor のプロセス間通信 [MEDIUM] [VERIFIED]

MultiprocExecutorはSharedMemory MessageQueue（ShmRingBuffer）を使って同一ノード内のWorkerプロセスと通信する。

MessageQueue の仕組み

参照: target/vllm/vllm/distributed/device_communicators/shm_broadcast.py:272 (MessageQueue)

2つのチャネルを併用:

1. ShmRingBuffer（共有メモリ）: 24MiB以下の通常データ。ロックフリー、~20nsメモリフェンスのみ
2. ZMQ PUB/SUB（フォールバック）: 24MiBを超えるデータ。ローカルはIPC、リモートはTCP

ShmRingBufferのメモリレイアウト:

┌──────────────────────────────────┬──────────────────────────────────────┐
│ data: chunk0 | chunk1 | ... | N  │ metadata: [written|r0|r1|...] × N   │
│ max_chunks × 24MiB               │ max_chunks × (1 + n_reader) bytes    │
└──────────────────────────────────┴──────────────────────────────────────┘

メタデータフラグで書き込み/読み取り状態を管理。全readerが読み取り完了するとチャンクが再利用される。

キュー構成

参照: target/vllm/vllm/v1/executor/multiproc_executor.py:131-136 (rpc_broadcast_mq生成)

collective_rpc の動作フロー

MultiprocExecutor.collective_rpc("execute_model", args=(...))
  │
  ├─ rpc_broadcast_mq.enqueue((method, args, kwargs, output_rank))
  │   → pickle → ShmRingBuffer書き込み → メモリフェンス
  │
  ├─ Worker-0: dequeue() → execute → response_mq.enqueue()
  ├─ Worker-1: dequeue() → execute → response_mq.enqueue()
  │
  └─ Executor: response_mqs[output_rank].dequeue() → 結果返却

参照: target/vllm/vllm/v1/executor/multiproc_executor.py:303-375 (collective_rpc) 参照: target/vllm/vllm/v1/executor/multiproc_executor.py:845-871 (worker_busy_loop)

Worker プロセスの起動とビジーループ

参照: target/vllm/vllm/v1/executor/multiproc_executor.py:696 (WorkerProc.worker_main)

WorkerProc.worker_main()
  ├─ Worker.init_device()
  │   └─ torch.distributed.init_process_group(backend="nccl")
  ├─ Worker.load_model()
  ├─ READY送信（Pipe経由）
  └─ worker_busy_loop():
      while True:
        method, args, kwargs, output_rank = rpc_broadcast_mq.dequeue()
        output = getattr(worker, method)(*args, **kwargs)
        worker_response_mq.enqueue((SUCCESS, output))

Worker（委譲先）

参照: target/vllm/vllm/v1/worker/gpu_worker.py:70 (Worker)

Worker(WorkerBase) はGPUModelRunnerのラッパーで、以下の追加処理を行う:

• Pipeline Parallelism: 前段ランクからのIntermediateTensors受信、後段への送信
• 推論モード管理: @torch.inference_mode() デコレータ

Worker.execute_model(scheduler_output)                    # L604
  ├─ PP: recv_tensor_dict() → IntermediateTensors        # L614-641
  ├─ model_runner.execute_model(scheduler_output, ...)    # L652
  │   → ModelRunnerOutput | None | IntermediateTensors
  ├─ PP: send_tensor_dict(intermediate_tensors)           # L660-671
  └─ return ModelRunnerOutput | None

EngineCore → 出力 の委譲フロー

EngineCore.step()
  └─ executor.execute_model(scheduler_output, non_block=True)
      └─ collective_rpc("execute_model")
          └─ Worker.execute_model()
              └─ GPUModelRunner.execute_model()
                  → ExecuteModelState 保存、None 返却

EngineCore.step()（続き）
  └─ executor.sample_tokens(grammar_output)
      └─ collective_rpc("sample_tokens")
          └─ Worker.sample_tokens()
              └─ GPUModelRunner.sample_tokens()
                  → ModelRunnerOutput 返却

上流・下流の関係

• 上流: EngineCore（step()から呼び出し）
• 下流: Worker → GPUModelRunner

Phase 2 深堀り候補

• MultiprocExecutorのMessageQueue実装詳細 → 調査済み（本ドキュメント）
• Pipeline Parallelism時のバッチスケジューリング
• Ray分散実行のオーバーヘッドと障害回復
• AsyncScheduling時のasync_output_busy_loop動作

主要ファイル

GPUModelRunner

深度: [MEDIUM] 確信度: [VERIFIED] 最終更新: 2026-02-15

概要

GPUModelRunnerは、推論パイプラインの実行中核を担う巨大クラス（約6,300行）である。SchedulerOutputを受け取り、入力テンソルの準備、モデルのforward実行、サンプリングを経て、ModelRunnerOutputを返す。2フェーズ実行パターン（execute_model() → sample_tokens()）を採用し、モデルフォワードとgrammar bitmask計算の並行実行を可能にしている。

クラス定義

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:329 (GPUModelRunner)

class GPUModelRunner(
    LoRAModelRunnerMixin,           # LoRAアダプタ管理
    KVConnectorModelRunnerMixin,    # KV Transfer対応
    ECConnectorModelRunnerMixin,    # エンコーダキャッシュ対応
):

状態管理

GPUModelRunnerは2つのデータ構造でリクエスト状態を管理する:

• self.requests: dict[str, CachedRequestState] — リクエストの論理状態（プリエンプション後も保持）
• self.input_batch: InputBatch — 永続バッチテンソル群（事前割り当て、差分更新）

永続バッチ最適化により、連続stepで変更があったリクエストのデータのみCPU側で更新し、GPUへはDMA一括転送する。

詳細は InputBatch: 永続バッチと状態管理 を参照。

KVCache-GPU Interface

KVCacheManager（Scheduler側）が割り当てた論理ブロックIDは、4段階の変換を経てAttentionカーネルが消費する形式になる:

_update_states()        ← ブロックID取込（3ケース: 新規/追加/プリエンプション復帰）
  ↓
BlockTable              ← CPU側テーブル（CpuGpuBuffer）
  ↓
_prepare_inputs()       ← commit_block_table() DMA + compute_slot_mapping()
  ↓
_get_slot_mappings()    ← by_gid（AttentionMetadata用）/ by_layer（ForwardContext用）
  ↓
_build_attention_metadata() ← CommonAttentionMetadata → per-layer AttentionMetadata

核心的な変換式: slot = block_number * block_size + (position % block_size)

詳細は KVCache-GPU Interface を参照。

2フェーズ実行パターン

GPUModelRunnerの中核設計。execute_model()でモデルフォワードとlogits計算を行い、結果をExecuteModelStateに保存してNoneを返す。その後sample_tokens()が状態を復元してサンプリングを実行する。

sequenceDiagram
    participant EC as EngineCore
    participant MR as GPUModelRunner

    EC->>MR: execute_model(scheduler_output)
    Note over MR: 入力準備 → モデルフォワード<br>→ logits計算 → 状態保存
    MR-->>EC: None

    Note over EC: grammar bitmask 計算<br>（並行処理）

    EC->>MR: sample_tokens(grammar_output)
    Note over MR: 状態復元 → grammar適用<br>→ サンプリング → 出力構築
    MR-->>EC: ModelRunnerOutput

Phase 1: execute_model()

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:3312 (execute_model)

execute_model(scheduler_output, intermediate_tensors=None)
  │
  ├─ 1. バッチ状態更新 _update_states()                     # L3376
  │     新規リクエスト登録、ブロックID更新、不要リクエスト除去
  │
  ├─ 2. 入力準備 _prepare_inputs()                          # L3383
  │     block_table DMA → slot_mapping計算 → positions/input_ids GPU転送
  │     ※ DMAオーバーラップ最適化（L1472-1474）
  │
  ├─ 3. CUDAGraph判定                                       # L3398
  │     _determine_batch_execution_and_padding()
  │     → CUDAGraphMode(FULL/PIECEWISE/NONE) + パディング量決定
  │
  ├─ 4. スロットマッピング2形式出力                            # L3468
  │     _get_slot_mappings() → by_gid + by_layer
  │
  ├─ 5. Attentionメタデータ構築                               # L3479
  │     _build_attention_metadata()
  │     → CommonAttentionMetadata → per-layer AttentionMetadata
  │
  ├─ 6. モデルフォワード                                      # L3538
  │     set_forward_context(slot_mapping=by_layer)
  │     → _model_forward() → model.forward() → logits
  │
  └─ 7. 状態保存                                              # L3605-3615
      ExecuteModelState に保存 → None を返す

戻り値のパターン:

• None — 通常ケース（sample_tokens()を後で呼ぶ）
• ModelRunnerOutput — プーリングモデル等（サンプリング不要）
• IntermediateTensors — Pipeline Parallelismの中間ランク
• EMPTY_MODEL_RUNNER_OUTPUT — スケジュールトークン0件

Phase 2: sample_tokens()

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:3621 (sample_tokens)

sample_tokens(grammar_output)
  │
  ├─ 1. 状態復元 — ExecuteModelState から logits 等を復元     # L3643-3657
  ├─ 2. Grammar制約適用 — bitmask → logits                  # L3659-3663
  ├─ 3. サンプリング — _sample() → SamplerOutput             # L3665-3666
  ├─ 4. 後処理 — バッチ状態反映、PP broadcast、ドラフト提案    # L3668-3699
  └─ 5. ModelRunnerOutput構築                                # L3775-3787

CUDAGraph統合 [VERIFIED]

CUDAGraphMode

3つの実行モードが存在する:

CudagraphDispatcher

参照: target/vllm/vllm/v1/cudagraph_dispatcher.py:14

事前キャプチャ済みCUDAGraphの中からランタイムで適切なグラフを選択する:

1. cudagraph_keys: dict[CUDAGraphMode, set[BatchDescriptor]] にキャプチャ済みのバッチ記述子を保持
2. dispatch() は入力 num_tokens を最小のパディングサイズに丸め上げ
3. FULL → PIECEWISE → NONE の優先順序でキーを探索

バッチパディング: CUDAGraphは固定形状のテンソルを要求するため、実際のトークン数をキャプチャ済みサイズに丸め上げる。未使用スロットはslot_mapping -1（PAD_SLOT_ID）で埋められ、reshape_and_cache() がスキップする。

_determine_batch_execution_and_padding()

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:3076

毎stepの実行モード判定:

1. _is_uniform_decode() — 全リクエストがデコードフェーズ（query_len=1）か判定
2. cudagraph_dispatcher.dispatch() — モードとパディングサイズを決定
3. Data Parallel時は coordinate_batch_across_dp() で全ランク間で合意

ExecuteModelState

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:313 (ExecuteModelState)

2フェーズ間の一時状態を保持するNamedTuple。GPUテンソルを含むため、シリアライズはされない。

6,300行の内訳 [VERIFIED]

マルチモーダル処理

マルチモーダル推論時、GPUModelRunnerは execute_model() 内で以下の追加処理を行う:

1. _execute_mm_encoder() (L2293): model.embed_multimodal() でビジョンエンコーダ実行。結果を encoder_cache[mm_hash] に格納
2. _gather_mm_embeddings() (L2449): encoder_cache からスケジュール範囲に対応する埋め込みをスライス。チャンクPrefill対応
3. embed_input_ids(): masked_scatter_ でテキスト + ビジョン埋め込みをマージ → inputs_embeds として model.forward() に渡す

encoder_cache: dict[str, torch.Tensor] はGPU上のシンプルなdictキャッシュで、Schedulerの free_encoder_mm_hashes 指示で解放される。

詳細は バックエンド MM処理パス を参照。

上流・下流の関係

• 上流: Worker（execute_model() / sample_tokens()経由で呼び出し）
• 下流: モデル層（model.forward()）、Sampler

深堀り候補（今後）

主要ファイル

InputBatch: 永続バッチと状態管理

深度: [MEDIUM] 確信度: [VERIFIED] 最終更新: 2026-02-14

概要

GPUModelRunnerは2つのデータ構造でリクエスト状態を管理する:

• CachedRequestState — リクエストごとの論理状態（step間で永続、プリエンプション後も保持）
• InputBatch — 全リクエストの物理バッチテンソル群（事前割り当て、step間でCPU側を差分更新）

永続バッチ最適化により、連続するstep間でリクエストの大部分が同じであることを前提に、差分のみを更新する。

CachedRequestState [VERIFIED]

参照: target/vllm/vllm/v1/worker/gpu_input_batch.py:30

@dataclass で定義されるリクエスト単位の状態。GPUModelRunner.requests: dict[str, CachedRequestState] に格納される。

ライフサイクル: _update_states() で作成され、finished_req_ids で削除される。プリエンプション時もInputBatchからは除去されるが self.requests には保持され、復帰時に再利用される。

num_tokens プロパティ: num_prompt_tokens + len(output_token_ids) — 現在のリクエスト全体のトークン数。

InputBatch [VERIFIED]

参照: target/vllm/vllm/v1/worker/gpu_input_batch.py:81

全リクエストの状態を事前割り当てテンソル群で管理するバッチマネージャー。

主要テンソル群

リクエスト管理

add_request() / remove_request() [VERIFIED]

参照: target/vllm/vllm/v1/worker/gpu_input_batch.py:304, 469

add_request():

1. 空きインデックスを探す（末尾追加 or 空スロット再利用）
2. token_ids_cpu にプロンプト+出力トークンIDをコピー
3. block_table.add_row() でブロックIDを設定
4. サンプリングパラメータを各テンソルにコピー

remove_request():

1. req_id_to_index から削除、_req_ids[index] = None で空スロット化
2. batch_update_builder.removed_append() で空きインデックスを記録
3. サンプリング関連のset/dictからも除去
4. テンソル自体はクリアしない（次のadd_requestで上書きされる）

condense() — バッチ圧縮 [VERIFIED]

参照: target/vllm/vllm/v1/worker/gpu_input_batch.py:626

remove_request() で生じた空スロットを埋める処理。末尾のリクエストを空スロットに移動し、連続した配列を保つ:

[A, _, B, _, C]  →  [A, C, B]  （Cを空スロット1に移動）

移動対象: token_ids_cpu, num_tokens_no_spec, num_prompt_tokens, num_computed_tokens_cpu, block_table.move_row(), サンプリングパラメータ等。

MultiGroupBlockTable [VERIFIED]

参照: target/vllm/vllm/v1/worker/block_table.py:253

KVキャッシュグループごとに BlockTable を保持するラッパー。Hybridモデル（異なるアテンションタイプが混在）では複数のBlockTableが存在する。

# アクセスパターン
input_batch.block_table[kv_cache_gid]  # → BlockTable
input_batch.block_table.append_row(block_ids, req_index)  # 全グループに委譲
input_batch.block_table.commit_block_table(num_reqs)       # 全グループDMA

block_ids は tuple[list[int], ...] 型で、外側タプルのインデックスがKVキャッシュグループIDに対応。

永続バッチ最適化の全体像 [VERIFIED]

sequenceDiagram
    participant S as Scheduler
    participant US as _update_states()
    participant IB as InputBatch
    participant PI as _prepare_inputs()
    participant GPU as GPU Tensors

    S->>US: SchedulerOutput
    Note over US: finished_req_ids → remove_request()
    Note over US: unscheduled → remove_request()
    Note over US: new_reqs → CachedRequestState作成
    Note over US: cached_reqs → block_ids更新
    US->>IB: add_request() / append_row() / condense()
    Note over IB: CPU側テンソルを差分更新
    IB->>PI: commit_block_table() (DMA)
    PI->>GPU: slot_mapping, positions, input_ids etc.

最適化の本質: 前stepと大部分が同じリクエスト群に対して、変更があったフィールド（新ブロックID、num_computed_tokens等）のみをCPU側で更新し、GPUへはDMA一括転送する。毎step全データを再構築する必要がない。

主要ファイル

KVCache-GPU Interface: ブロックテーブルとスロットマッピング

深度: [MEDIUM] 確信度: [VERIFIED] 最終更新: 2026-02-14

概要

KVCacheManager（Scheduler側）が割り当てた論理ブロックIDは、GPUModelRunner内で4段階の変換を経てAttentionカーネルが消費できる形式になる。この文書では、ブロックIDの取り込みからAttentionMetadata構築までの完全なデータパスを追跡する。

graph LR
    A["KVCacheManager<br>(論理ブロック割当)"] -->|SchedulerOutput<br>new_block_ids| B["_update_states()<br>(ブロックID取込)"]
    B -->|CachedRequestState<br>block_ids| C["BlockTable<br>(CPU側テーブル)"]
    C -->|"commit_block_table()<br>DMA (non-blocking)"| D["GPU block_table"]
    C -->|"compute_slot_mapping()"| E["CPU slot_mapping"]
    E -->|"commit_slot_mapping()<br>DMA"| F["GPU slot_mapping"]
    D --> G["_build_attention_metadata()"]
    F --> G
    G -->|"per-layer<br>AttentionMetadata"| H["Attention Kernel"]
    F -->|"set_forward_context()<br>slot_mappings_by_layer"| I["reshape_and_cache()"]

Stage A: ブロックID取込 — _update_states() [VERIFIED]

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:874

SchedulerOutputには3種類のリクエストデータが含まれ、それぞれブロックIDの扱いが異なる:

block_ids の型は list[list[int]] — 外側のリストはKVキャッシュグループ（Hybridモデルで複数）、内側はそのグループのブロックID列。

重要な最適化 — 永続バッチ: 前stepで存在し今回もスケジュールされたリクエストは、InputBatchに残り続ける。スケジュールされなかったリクエストだけが remove_request() で除去されるが、CachedRequestState は self.requests に保持される（L901-921）。

Stage B: スロットマッピング計算 — BlockTable.compute_slot_mapping() [VERIFIED]

参照: target/vllm/vllm/v1/worker/block_table.py:133

トークンの論理位置を、KVキャッシュの物理GPUメモリスロットに変換する式:

block_table_index = req_index * max_num_blocks_per_req + position // block_size
block_number = block_table[block_table_index]  # ravel()で1D化してルックアップ
block_offset = position % block_size
slot = block_number * block_size + block_offset

Hybrid Block対応

KVCacheManagerの割当ブロックサイズとAttentionカーネルのブロックサイズが異なる場合（例: 割当=32トークン、カーネル=16トークン）:

参照: target/vllm/vllm/v1/worker/block_table.py:203 (map_to_kernel_blocks)

# 割当ブロックID [0, 1, 2] → カーネルブロックID [0, 1, 2, 3, 4, 5]
# ブロック0 → [0, 1], ブロック1 → [2, 3], ブロック2 → [4, 5]
kernel_ids = block_id * blocks_per_kv_block + arange(blocks_per_kv_block)

append_row() と add_row() は、ブロックIDを追加する前にこの変換を適用する。compute_slot_mapping() では変換後の kernel_block_size が block_size として使用される。

Context Parallel対応

CP（DCP/PCP）有効時は「仮想ブロック」サイズ（= block_size * cp_world_size）を使ってブロックテーブルインデックスを算出し、ローカルランクに属さないトークンのスロットを -1 にマスクする（L142-179）。

Stage C: GPU転送 — _prepare_inputs() [VERIFIED]

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:1454

_prepare_inputs() は以下の順序でCPU→GPU転送を実行する:

1. commit_block_table(num_reqs)      ← 最初に発行（DMAオーバーラップ最適化）
2. positions計算 (CPU)               ← DMA中にCPU演算
3. token_indices計算 (CPU)           ← DMA中にCPU演算
4. compute_slot_mapping()            ← CPU演算
5. commit_slot_mapping()             ← DMA発行
6. query_start_loc → GPU
7. seq_lens → GPU
8. input_ids → GPU
9. positions → GPU

最適化ポイント: commit_block_table() をCPU演算の前に呼ぶことで、ブロックテーブルのDMA転送とCPU上のslot_mapping/positions計算を並行実行する（L1472-1474のコメント）。

CpuGpuBuffer

参照: target/vllm/vllm/v1/utils.py:105

ピン留めメモリCPUテンソル + GPUテンソルのペア。np 属性でnumpyビューを公開し、CPU側の演算をnumpy高速演算で行える。copy_to_gpu(n) は non_blocking=True でDMA転送を発行。

Stage D: 2形式のスロットマッピング出力 — _get_slot_mappings() [VERIFIED]

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:3237

_get_slot_mappings() はスロットマッピングを2つの形式で返す:

同一KVキャッシュグループ内のレイヤーは同じスロットマッピングテンソルを共有する。

CUDAGraph FULLモード時のパディング: 未使用トークンスロットは -1 で埋められる（L3283-3285）。これはMambaの PAD_SLOT_ID と一致し、reshape_and_cache() が -1 スロットをスキップする。

Stage E: Attentionメタデータ構築 — _build_attention_metadata() [VERIFIED]

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:1673

CommonAttentionMetadata

全KVキャッシュグループの共通基盤。グループ0のblock_table/slot_mappingで初期化し、他グループでは copy() (shallow copy) してblock_tableとslot_mappingのみ差し替える。

cm_base = CommonAttentionMetadata(
    query_start_loc=...,     # GPU tensor [num_reqs+1]
    seq_lens=...,            # GPU tensor [num_reqs]
    block_table_tensor=...,  # GPU tensor [num_reqs, max_blocks] ← グループ0
    slot_mapping=...,        # GPU tensor [num_tokens] ← グループ0
    max_query_len=...,
    max_seq_len=...,
    ...
)

Per-layer AttentionMetadata構築

graph TD
    A[CommonAttentionMetadata] -->|"copy() + グループ別<br>block_table/slot_mapping"| B["cm (per kv_cache_group)"]
    B --> C["AttentionMetadataBuilder.build()"]
    C --> D["AttentionMetadata"]
    D -->|"同一attn_group内の<br>全レイヤーが共有"| E["attn_metadata[layer_name]"]

_build_attn_group_metadata() 内部関数が各(kv_cache_gid, attn_gid)ペアに対して:

1. attn_group.get_metadata_builder() でビルダーを取得
2. builder.build(common_attn_metadata=cm) で AttentionMetadata を生成
3. attn_group.layer_names の全レイヤーに同じメタデータを割り当て

キャッシュ最適化

Hybridモデルで同じ KVCacheSpec + 同じビルダー型の組み合わせが複数グループに現れる場合、2番目以降は builder.update_block_table() で block_table のみ差し替え、ビルド全体をスキップする（L1824-1832）。

戻り値の型

PerLayerAttnMetadata = dict[str, AttentionMetadata]      # 通常
                     | list[dict[str, AttentionMetadata]] # UBatching(DBO)時

execute_model() 内の呼び出し順序 [VERIFIED]

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:3312

execute_model(scheduler_output)
  │
  ├─ 1. _prepare_inputs()                    # L3383
  │     block_table DMA + slot_mapping計算 + GPU転送
  │
  ├─ 2. _determine_batch_execution_and_padding()  # L3398
  │     CUDAGraphモード判定 → num_tokens_padded, num_reqs_padded
  │
  ├─ 3. _get_slot_mappings()                  # L3468
  │     2形式出力: by_gid (→ attn_metadata), by_layer (→ ForwardContext)
  │
  ├─ 4. _build_attention_metadata()           # L3479
  │     CommonAttentionMetadata → per-layer AttentionMetadata
  │
  ├─ 5. set_forward_context(slot_mapping=slot_mappings_by_layer)  # L3524
  │     ForwardContext にスロットマッピングを設定
  │
  └─ 6. _model_forward()                      # L3538
        model.forward() → Attention layer が ForwardContext から
        slot_mapping を取得し reshape_and_cache() を実行

主要ファイル

InputProcessor サマリー

深度: [SHALLOW] 確信度: [VERIFIED] 最終更新: 2026-02-09

概要

InputProcessorはユーザー入力（テキストプロンプト、SamplingParams等）を内部表現EngineCoreRequestに変換するコンポーネントである。トークナイズ、パラメータのバリデーションと正規化、マルチモーダル入力の前処理を担当する。AsyncLLMの初期化時に生成され、フロントエンドプロセスで動作する。

アーキテクチャ

graph LR
    Prompt["PromptType<br>(str / list[int] / dict)"] --> IP["InputProcessor"]
    Params["SamplingParams"] --> IP
    IP --> IPP["InputPreprocessor<br>tokenizer.encode()"]
    IPP --> PI["ProcessorInputs"]
    PI --> IP
    IP --> ECR["EngineCoreRequest"]

主要コンポーネント

主要メソッド

process_inputs() の処理フロー

process_inputs(request_id, prompt, params)
  1. バリデーション
     ├─ LoRAリクエスト検証
     ├─ パラメータ検証
     └─ data_parallel_rank 範囲チェック
  2. arrival_time 設定
  3. input_preprocessor.preprocess(prompt)
     → テキストをトークナイズ → ProcessorInputs
  4. split_enc_dec_inputs()
     → エンコーダ/デコーダ入力を分離
  5. SamplingParams 正規化
     ├─ clone() で複製
     ├─ max_tokens 未設定時: max_model_len - seq_len
     ├─ update_from_generation_config()
     └─ update_from_tokenizer()
  6. EngineCoreRequest を構築して返す

設定

呼び出しフロー

AsyncLLM.add_request() / LLM._add_request()
  → InputProcessor.process_inputs()
    → InputPreprocessor.preprocess()
      → tokenizer.encode()
    → EngineCoreRequest を返す
  → InputProcessor.assign_request_id()
    → 外部IDを external_req_id に退避
    → 内部ID（外部ID + 8文字ランダム）を request_id に設定

マルチモーダル処理

テキスト入力に加えて画像等のマルチモーダルデータがある場合、InputProcessorは以下の追加処理を行う:

1. MM Registry から BaseMultiModalProcessor を取得（_get_mm_processor()）
2. マルチモーダルデータのパース: mm_processor.info.parse_mm_data() → MultiModalDataItems
3. HF Processor 実行: mm_processor.apply() → MultiModalInputs（トークン列 + テンソル + ハッシュ + PlaceholderRange）
4. ProcessorCache: mm_processor_cache によるHF処理結果のキャッシュ（4種類: processor_only/lru/shm/none）
5. MultiModalFeatureSpec 構築: データ + 位置情報 + ハッシュを EngineCoreRequest.mm_features にセット

詳細は マルチモーダル フロントエンド処理 を参照。

関連ドキュメント

• エントリポイント
• データフロー
• マルチモーダル処理パイプライン

KVCacheManager サマリー

深度: [DEEP] 確信度: [VERIFIED] 最終更新: 2026-02-11

概要

KVCacheManager は PagedAttention に基づく KV キャッシュブロックの割り当て・解放・プレフィックスキャッシュ検索を管理するクラスである。4層の階層設計（KVCacheManager → KVCacheCoordinator → SingleTypeKVCacheManager → BlockPool）でマルチグループ KV キャッシュを統括する。Scheduler から呼び出され、各リクエストに必要な GPU メモリブロックを確保する。

アーキテクチャ

クラス階層

graph TD
    KVM["KVCacheManager<br>公開 API"]
    Factory["get_kv_cache_coordinator()<br>ファクトリ関数"]

    NPC["NoPrefixCache<br>キャッシュ無効時"]
    UC["UnitaryCoordinator<br>単一グループ"]
    HC["HybridCoordinator<br>複数グループ"]

    FAM["FullAttentionManager"]
    SWM["SlidingWindowManager"]
    CLM["ChunkedLocalManager"]
    MM["MambaManager"]
    CAM["CrossAttentionManager"]
    SFM["SinkFullAttentionManager"]

    BP["BlockPool<br>物理ブロック管理"]
    BH["BlockHashToBlockMap"]
    FQ["FreeKVCacheBlockQueue"]
    KB["KVCacheBlock"]

    KVM --> Factory
    Factory --> NPC
    Factory --> UC
    Factory --> HC

    UC --> FAM
    UC --> SWM
    HC --> FAM
    HC --> SWM
    HC --> CLM
    HC --> MM
    HC --> CAM
    HC --> SFM

    FAM --> BP
    SWM --> BP
    CLM --> BP
    MM --> BP
    CAM --> BP
    SFM --> BP

    BP --> BH
    BP --> FQ
    FQ --> KB

Coordinator 選択ロジック

参照: target/vllm/vllm/v1/core/kv_cache_coordinator.py:542

get_kv_cache_coordinator()
  ├─ enable_caching == False  → KVCacheCoordinatorNoPrefixCache
  ├─ kv_cache_groups == 1     → UnitaryKVCacheCoordinator
  └─ kv_cache_groups > 1      → HybridKVCacheCoordinator

KV キャッシュグループ

KV キャッシュグループとは、同一の KVCacheSpec（アテンションタイプ・ブロックサイズ）を共有するモデルレイヤーの集合である。

各グループは独立した SingleTypeKVCacheManager を持ち、異なるキャッシュ検索アルゴリズム・スキップポリシーを適用する。

KVCacheBlocks [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/kv_cache_manager.py:21

Scheduler と KVCacheManager のインターフェース。内部データ構造を隠蔽する。

@dataclass
class KVCacheBlocks:
    blocks: tuple[Sequence[KVCacheBlock], ...]
    # blocks[i][j] = i 番目の kv_cache_group、j 番目のブロック

GC 最適化: KVCacheManager は empty_kv_cache_blocks を事前生成し、空の結果を返す際に再利用する。

ブロック配置図（allocate_slots）

allocate_slots() がリクエストに割り当てるブロックの論理構造:

|  comp  | new_comp | ext_comp |   new   | lookahead |
|<------ 既計算トークン ------>|<-- 新規計算対象 -->|
                               |<- 割り当て対象 ->|

• comp: request.num_computed_tokens — 前ステップまでに計算済み
• new_comp: num_new_computed_tokens — プレフィックスキャッシュから新規にヒットしたトークン
• ext_comp: num_external_computed_tokens — KV コネクタ（LMCache 等）から取得したトークン
• new: num_new_tokens — 今回計算するトークン
• lookahead: num_lookahead_tokens — Speculative Decoding 用の先読みトークン

主要コンポーネント

主要メソッド

allocate_slots() の 5 段階フロー [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/kv_cache_manager.py:206

allocate_slots(request, num_new_tokens, ...)
  │
  ├─ Stage 1: スキップブロック解放（Sliding Window 用）
  │  └─ coordinator.remove_skipped_blocks(request_id, total_computed_tokens)
  │
  ├─ Stage 2: 容量チェック
  │  ├─ coordinator.get_num_blocks_to_allocate(...)
  │  └─ 空きブロック不足 → return None（プリエンプション誘発）
  │
  ├─ Stage 3: キャッシュヒットブロック割り当て
  │  └─ new_computed_blocks 非空 or external_computed > 0:
  │     └─ coordinator.allocate_new_computed_blocks(...)
  │
  ├─ Stage 4: 新規ブロック割り当て
  │  └─ coordinator.allocate_new_blocks(request_id, num_tokens_need_slot, ...)
  │
  └─ Stage 5: キャッシュ登録判定
     ├─ NOT enable_caching or delay_cache_blocks → スキップ
     └─ coordinator.cache_blocks(request, num_tokens_to_cache)
        ※ num_tokens_to_cache はドラフトトークンを除外

delay_cache_blocks: P/D（Prefill/Decode 分離）構成で KV Transfer 完了前にキャッシュ登録を遅延する。

プレフィックスキャッシュ

参照: target/vllm/vllm/v1/core/kv_cache_manager.py:164 (get_computed_blocks)

プロンプトトークン列をブロックサイズ単位でハッシュ化し、BlockHashToBlockMap で過去に計算済みのブロックを検索する。ハッシュチェーン（各ブロックのハッシュが前ブロックのハッシュに依存）により、プレフィックスの最長一致を効率的に検索する。

get_computed_blocks(request)
  → coordinator.find_longest_cache_hit(request.block_hashes, max_length)
    → アテンションタイプ別の検索アルゴリズム
  → (キャッシュ済みブロック, ヒットトークン数) を返却

制約: 全トークンがキャッシュヒットしても、logits 取得のため最後の 1 トークンは再計算が必要（max_cache_hit_length = request.num_tokens - 1）。

→ 詳細は プレフィックスキャッシュ詳細 を参照

参照カウントと Eviction

KVCacheBlock (L107) の ref_cnt フィールドでブロックの使用状況を管理:

• touch(): キャッシュヒット時に ref_cnt を増加し、空きキューから除外
• free_blocks(): ref_cnt を減少。0 になったら空きキューに戻す（逆順追加で LRU 効率化）
• _maybe_evict_cached_block(): 新規ブロック要求時に空きキューの先頭（最古）から Evict。ハッシュメタデータをリセット

→ 詳細は BlockPool 詳細 を参照

アテンションタイプ対応

7 種の SingleTypeKVCacheManager がアテンションタイプごとのブロック管理を担当:

→ 詳細は アテンションタイプ別 Manager を参照

設定

呼び出しフロー

Scheduler.schedule()
  ├─ kv_cache_manager.get_computed_blocks(request)     # プレフィックスキャッシュ検索
  ├─ kv_cache_manager.allocate_slots(request, ...)     # ブロック割り当て
  │   └─ None の場合 → プリエンプション実行
  └─ （完了時）kv_cache_manager.free(request)           # ブロック解放

ソースファイル一覧

詳細ドキュメント

• BlockPool 詳細 — FreeKVCacheBlockQueue、BlockHashToBlockMap、KVCacheBlock ライフサイクル、Eviction、KV Cache Events
• プレフィックスキャッシュ詳細 — ハッシュチェーン計算、Extra Keys、Lookup アルゴリズム、Hybrid fixed-point
• アテンションタイプ別 Manager — 7 種 Manager の詳細、スキップ計算、キャッシュ検索アルゴリズム

関連ドキュメント

• Scheduler
• EngineCore
• データフロー
• 用語集

アテンションタイプ別 Manager 詳細

深度: [DEEP] 確信度: [VERIFIED] 最終更新: 2026-02-11

概要

SingleTypeKVCacheManager は1種類のアテンションタイプの KV キャッシュ管理ロジックを担当する抽象基底クラスである。アテンションタイプごとにサブクラスが存在し、ブロックの割り当て・解放・プレフィックスキャッシュ検索をそれぞれのセマンティクスに合わせて実装する。

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py

spec_manager_map [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:1049

spec_manager_map = {
    FullAttentionSpec:            FullAttentionManager,
    MLAAttentionSpec:             FullAttentionManager,       # MLA も Full 扱い
    SlidingWindowSpec:            SlidingWindowManager,
    ChunkedLocalAttentionSpec:    ChunkedLocalAttentionManager,
    MambaSpec:                    MambaManager,
    CrossAttentionSpec:           CrossAttentionManager,
    SinkFullAttentionSpec:        SinkFullAttentionManager,
}

get_manager_for_kv_cache_spec(spec, **kwargs) ファクトリ関数がこのマップから Manager クラスをディスパッチする。

基底クラス: SingleTypeKVCacheManager [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:24

状態管理

コンストラクタ

def __init__(self, kv_cache_spec, block_pool, enable_caching,
             kv_cache_group_id, dcp_world_size=1, pcp_world_size=1):
    self.block_size = kv_cache_spec.block_size
    if dcp_world_size * pcp_world_size > 1:
        self.block_size *= dcp_world_size * pcp_world_size

DCP（Decode Context Parallelism）/ PCP（Prefill Context Parallelism）ではブロックサイズが並列度倍に拡大される。

get_num_blocks_to_allocate() [DEEP] [VERIFIED]

参照: L73

リクエストに必要な新規ブロック数を算出する。2 つのパスが存在:

get_num_blocks_to_allocate(request_id, num_tokens, new_computed_blocks, ...)
  │
  ├─ Fast-path: request_id in num_cached_block（RUNNING リクエスト）
  │  └─ max(num_required_blocks - num_req_blocks, 0)
  │     ※ Speculative Decoding のリジェクトで num_req_blocks > num_required_blocks もあり得る
  │
  └─ Slow-path: 新規リクエスト（プレフィックスキャッシュヒットあり）
     ├─ num_skipped_tokens = get_num_skipped_tokens(total_computed_tokens)
     ├─ num_skipped_blocks = num_skipped_tokens // block_size
     ├─ num_new_blocks = max(required - max(skipped, local_computed), 0)
     ├─ num_evictable_blocks = Σ(ref_cnt==0 かつ非null)
     │  ← touch() 時にキューから除去されるブロック分を加算
     └─ return num_new_blocks + num_evictable_blocks

Evictable blocks の加算理由: new_computed_blocks 内のブロックが空きキュー内（ref_cnt == 0）にある場合、touch() で空きキューから除去されるため、実質的に空きブロック数が減る。この分を事前に計上する。

allocate_new_computed_blocks() [DEEP] [VERIFIED]

参照: L137

プレフィックスキャッシュヒットしたブロックをリクエストに追加する。

allocate_new_computed_blocks(request_id, new_computed_blocks, ...)
  │
  ├─ RUNNING → assert len(new_computed_blocks) == 0 → return
  │
  └─ 新規リクエスト:
     ├─ num_skipped_blocks 計算
     ├─ スキップ分を new_computed_blocks から除去
     ├─ enable_caching → block_pool.touch(new_computed_blocks)
     ├─ req_blocks に null_block × num_skipped_blocks を追加
     ├─ req_blocks に new_computed_blocks を追加
     ├─ num_cached_block[request_id] = len(req_blocks)
     └─ external_computed_tokens > 0 → 追加ブロック割り当て

allocate_new_blocks() [VERIFIED]

参照: L208

def allocate_new_blocks(self, request_id, num_tokens, num_tokens_main_model):
    num_required_blocks = cdiv(num_tokens, self.block_size)
    num_new_blocks = num_required_blocks - len(req_blocks)
    if num_new_blocks <= 0:
        return []
    new_blocks = self.block_pool.get_new_blocks(num_new_blocks)
    req_blocks.extend(new_blocks)
    return new_blocks  # 新規分のみ返す

cache_blocks() [VERIFIED]

参照: L235

def cache_blocks(self, request, num_tokens):
    num_full_blocks = num_tokens // self.block_size
    if num_cached_blocks >= num_full_blocks:
        return  # 既に登録済み
    block_pool.cache_full_blocks(request, req_blocks, num_cached_blocks,
                                  num_full_blocks, block_size, group_id)
    num_cached_block[request_id] = num_full_blocks

free() [VERIFIED]

参照: L261

def free(self, request_id):
    req_blocks = self.req_to_blocks.pop(request_id, [])
    ordered_blocks = reversed(req_blocks)  # 逆順でLRU最適化
    self.block_pool.free_blocks(ordered_blocks)
    self.num_cached_block.pop(request_id, None)

逆順の理由: チェーン末尾（最新トークン）がキューの先頭側に来ることで、次の割り当て時に最初に evict される。先頭ブロック（プレフィックス）は長く残り、共有確率が上がる。

remove_skipped_blocks() [VERIFIED]

参照: L343

def remove_skipped_blocks(self, request_id, total_computed_tokens):
    num_skipped_tokens = self.get_num_skipped_tokens(total_computed_tokens)
    if num_skipped_tokens <= 0:
        return  # Full Attention: 何もしない
    # 後方から走査して null_block に遭遇したら停止
    for i in range(num_skipped_blocks - 1, -1, -1):
        if blocks[i] == null_block:
            break  # 前回の呼び出しで既に解放済み
        removed_blocks.append(blocks[i])
        blocks[i] = null_block
    block_pool.free_blocks(removed_blocks)

get_num_skipped_tokens() [VERIFIED]

参照: L386

デフォルト実装は return 0（全トークンがアテンション対象）。サブクラスでオーバーライド。

FullAttentionManager [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:400

標準的な全トークンアテンション。基底クラスの動作をそのまま継承し、2 つのメソッドのみ実装。

find_longest_cache_hit()

参照: L401

左→右にブロックハッシュを走査:
  キャッシュヒット → computed_blocks に追加
  キャッシュミス → break（チェーンが途切れたら以降は必ずミス）

EAGLE 使用時:
  最後のブロックを削除（hidden states 再計算が必要）

alignment_tokens でアライメント調整:
  Hybrid モデルで LCM ブロックサイズの倍数に切り詰め

Downward-closed 性質: Full Attention では blocks[0..n] がヒットするなら blocks[0..n-1] も必ずヒットする。この性質により、左→右の貪欲スキャンで最適解が得られる。

get_num_common_prefix_blocks()

参照: L450

def get_num_common_prefix_blocks(self, running_request_id):
    for block in blocks:
        if block.ref_cnt == len(self.req_to_blocks):
            num_common_blocks += 1
        else:
            break
    return num_common_blocks

原理: ref_cnt == 全リクエスト数 なら、そのブロックは全リクエストで共有されている → 共通プレフィックス。Cascade Attention で共通プレフィックスの再計算をスキップするために使用。

SlidingWindowManager [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:461

Sliding Window Attention 用。ウィンドウ外のトークンの KV キャッシュを解放してメモリを節約する。

コンストラクタ

def __init__(self, kv_cache_spec: SlidingWindowSpec, **kwargs):
    super().__init__(kv_cache_spec, **kwargs)
    self.sliding_window = kv_cache_spec.sliding_window

get_num_skipped_tokens()

参照: L556

def get_num_skipped_tokens(self, num_computed_tokens):
    return max(0, num_computed_tokens - self.sliding_window + 1)

例: sliding_window=4, num_computed_tokens=7

Tokens: [0 1 2 3 4 5 6 | 7]
                          ↑ 次に計算するトークン
                  [4 5 6 7]  ← sliding window（サイズ4）
        [0 1 2 3]            ← skipped（4トークン）

find_longest_cache_hit()

参照: L466

右→左にブロックハッシュを走査:
  キャッシュヒット → computed_blocks[i] にセット、連続カウント++
  キャッシュミス → 連続カウント = 0（リセット）

  連続カウント >= sliding_window_contiguous_blocks:
    末尾をトリミングして break

sliding_window_contiguous_blocks = ceil((window - 1) / block_size)

Right-to-left の理由: Sliding Window は最新のトークン付近のブロックが重要。右端から連続ヒットを探すことで、ウィンドウ内の有用なキャッシュを効率的に発見する。

初期値: computed_blocks は null_block で埋められ、ヒットした位置のみ実ブロックで置換される。

制約事項:

• DCP/PCP 非対応 (assert dcp_world_size == 1)
• EAGLE 使用時は sliding_window_contiguous_blocks += 1

get_num_common_prefix_blocks()

参照: L584

常に 0 を返す。プレフィックスブロックは全て null_block に置換されているため、Cascade Attention は使用不可。

ChunkedLocalAttentionManager [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:594

チャンク境界でアテンションが分割されるモデル用。各チャンク内のトークンのみが互いにアテンションする。

コンストラクタ

def __init__(self, kv_cache_spec: ChunkedLocalAttentionSpec, **kwargs):
    super().__init__(kv_cache_spec, **kwargs)
    self.attention_chunk_size = kv_cache_spec.attention_chunk_size

get_num_skipped_tokens()

参照: L691

def get_num_skipped_tokens(self, num_computed_tokens):
    return (num_computed_tokens // self.attention_chunk_size) * self.attention_chunk_size

例1: chunk_size=8, computed=13 → skipped=8  (チャンク[0,7]全体)
例2: chunk_size=8, computed=8  → skipped=8  (チャンク[0,7]全体)
例3: chunk_size=8, computed=7  → skipped=0  (まだチャンク内)

find_longest_cache_hit()

参照: L599

1. local_attention_start_idx = (max_length // chunk_size) * chunk_size
2. computed_blocks = [null_block] × (start_idx // block_size)  ← ウィンドウ外
3. start_idx から max_num_blocks まで左→右スキャン:
   ヒット → append、ミス → break

ウィンドウ外のブロックは null_block でパディングし、ウィンドウ内のみ FullAttention と同様の左→右スキャンを行う。

制約事項:

• EAGLE 非対応 (assert use_eagle is False)
• DCP/PCP 非対応
• 異なるブロックサイズの混在非対応

MambaManager [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:744

Mamba（State Space Model / 線形アテンション）用の Manager。Transformer ベースのアテンションとは根本的に異なり、KV キャッシュではなく「状態」を管理する。

2つのキャッシュモード

追加状態（align モード）

get_num_skipped_tokens()

参照: L967

def get_num_skipped_tokens(self, num_computed_tokens):
    return num_computed_tokens - 1  # 最後の状態のみ必要

Mamba は状態の累積的な更新なので、最後のトークンの状態さえあれば以前のトークンの状態は不要。

find_longest_cache_hit()

参照: L756

右→左に走査:
  最初のヒットで即座に break
  ヒット位置の前を null_block で埋める

最後の状態のみ必要なため、最右のヒット 1 つで十分。

get_num_blocks_to_allocate()（align モード） [DEEP] [VERIFIED]

参照: L832

align モード:
  ├─ 既存リクエスト（_allocated_block_reqs に存在）:
  │  └─ 最大 1 ブロック追加（speculative blocks 再利用のため）
  │
  └─ 新規リクエスト:
     └─ 1 + num_speculative_blocks ブロック

allocate_new_blocks()（align モード） [DEEP] [VERIFIED]

参照: L885

align モードの割り当ては複雑:

1. num_tokens を main model 分に制限（lookahead 除外）
2. last_state_block_idx を記録:
   - 既存: prev_len - 1 - num_speculative_blocks
   - 新規（キャッシュヒット有）: prev_len - 1
3. null_block でスキップ位置をパディング
4. 既存リクエスト: speculative blocks をスキップ位置に移動して再利用
5. 残りの新規ブロックを割り当て

remove_skipped_blocks()（align モード）

参照: L804

基底クラスの remove_skipped_blocks() に加え、last_state_block_idx のブロックも解放する:

if last_state_block_idx < cdiv(num_computed_tokens, block_size) - 1:
    block_pool.free_blocks([blocks[last_state_block_idx]])
    blocks[last_state_block_idx] = null_block

2 ステップ前のブロックが不要になるタイミングで解放する。

free()

参照: L961

def free(self, request_id):
    if self.mamba_cache_mode == "align":
        self._allocated_block_reqs.discard(request_id)
        self.last_state_block_idx.pop(request_id, None)
    super().free(request_id)

CrossAttentionManager [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:976

エンコーダ-デコーダモデル（Whisper 等）のクロスアテンション用。エンコーダ出力はリクエスト固有（異なる音声/画像入力）のため、プレフィックスキャッシュの恩恵がない。

制約

エンコーダブロックはリクエスト開始時に num_encoder_tokens に基づいて静的に割り当てられ、デコード中は変化しない。

SinkFullAttentionManager [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:1025

StreamingLLM のための Attention Sink 実装。FullAttentionManager を継承し、初期化時に先頭の sink ブロックを事前確保する。

コンストラクタ

class SinkFullAttentionManager(FullAttentionManager):
    def __init__(self, kv_cache_spec: SinkFullAttentionSpec, ...):
        super().__init__(...)
        sink_len = kv_cache_spec.sink_len
        assert sink_len > 0 and sink_len % self.block_size == 0
        num_sink_block = sink_len // self.block_size
        self.sink_blocks = self.block_pool.free_block_queue.popleft_n(num_sink_block)

特徴:

• sink_len は block_size の倍数でなければならない
• sink ブロックは初期化時に popleft_n() で確保され、以降解放されない
• FullAttentionManager の find_longest_cache_hit() と get_num_common_prefix_blocks() をそのまま使用

各 Manager の比較表 [VERIFIED]

関連ドキュメント

• KVCacheManager サマリー
• BlockPool 詳細
• プレフィックスキャッシュ詳細
• Scheduler

BlockPool 詳細

深度: [DEEP] 確信度: [VERIFIED] 最終更新: 2026-02-11

概要

BlockPool はKVキャッシュの物理ブロックを管理するクラスである。ブロックの割り当て・解放・プレフィックスキャッシュ索引を一元管理し、LRU Eviction によるメモリ再利用を実現する。3つの内部データ構造（FreeKVCacheBlockQueue、BlockHashToBlockMap、KVCacheBlock）で構成される。

参照: target/vllm/vllm/v1/core/block_pool.py:128

KVCacheBlock [DEEP] [VERIFIED]

KVキャッシュブロック1つのメタデータを保持する dataclass。物理メモリ自体は GPU 上にあり、このオブジェクトは CPU 側のメタデータのみを管理する。

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:107

フィールド

block_hash プロパティ

@block_hash.setter
def block_hash(self, block_hash: BlockHashWithGroupId):
    assert self.block_hash is None  # 二重設定を禁止
    self._block_hash = block_hash

def reset_hash(self):
    self._block_hash = None  # Eviction時にリセット

制約: setter は assert self.block_hash is None で二重設定を防止する。ハッシュのリセットは reset_hash() のみで行う。これによりブロックのライフサイクルが「未設定 → 設定 → リセット → 再設定」の順序で制御される。

ライフサイクル

1. 生成: BlockPool.__init__() で全ブロック生成（ref_cnt=0）
2. 割り当て: get_new_blocks() → ref_cnt=1
3. キャッシュ登録: cache_full_blocks() → block_hash 設定
4. 再利用（キャッシュヒット）: touch() → ref_cnt++
5. 解放: free_blocks() → ref_cnt-- → 0なら空きキューへ
6. Eviction: _maybe_evict_cached_block() → hash リセット → 再割り当て

FreeKVCacheBlockQueue [DEEP] [VERIFIED]

空きブロックを LRU 順序で管理する双方向リンクリスト。Python 組み込みの deque ではなく独自実装を採用している。

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:156

なぜ独自実装か

deque では中間要素の削除が O(n) であるのに対し、この実装では O(1) で削除できる。touch() でキャッシュヒットしたブロックを空きキューの中間から即座に除去する必要があるため、O(1) の remove() が不可欠である。

また、Python オブジェクトのアロケーションを行わず、KVCacheBlock の prev_free_block/next_free_block ポインタを直接操作するため、GC 負荷が低い。

センチネルノード

fake_head ⇄ block_0 ⇄ block_1 ⇄ ... ⇄ block_n ⇄ fake_tail

• fake_free_list_head: block_id=-1 のダミーノード。先頭の前に配置
• fake_free_list_tail: block_id=-1 のダミーノード。末尾の後に配置
• 目的: null チェックの分岐を減らし、コードを簡素化

操作一覧

LRU 順序の維持

• 初期状態: block_id 順（0, 1, 2, …）
• 再挿入時: free_blocks() でブロックが返却される際に逆順で追加される
  • 理由: リクエストのブロックチェーンの末尾（最新トークン）は先に evict されるべき。先頭（古いプレフィックス）は他のリクエストと共有される可能性が高いため後回し
  • 逆順操作は SingleTypeKVCacheManager.free() 側で実行される（BlockPool 外）

BlockHashToBlockMap [DEEP] [VERIFIED]

プレフィックスキャッシュのハッシュ→ブロック対応表。

参照: target/vllm/vllm/v1/core/block_pool.py:32

データ構造

_cache: dict[BlockHashWithGroupId, KVCacheBlock | dict[int, KVCacheBlock]]

Union 型の最適化: 大半のハッシュキーには 1 ブロックしか対応しないため、単一ブロックは直接格納し、2つ以上の場合のみ内部 dict に昇格する。これにより内部 dict の GC コストを削減。

重複排除なし設計

同一ハッシュのブロックが複数存在しても重複排除しない。理由: ブロック ID をリクエストに割り当てた後は追加のみ（append-only）を保証するため。重複排除するとブロック ID が変わり、ブロックテーブルの安定性が崩れる。

操作

insert の分岐

key なし       → _cache[key] = block          (単一格納)
key に 1 block → _cache[key] = {id: blk, ...}  (dict 昇格)
key に dict    → dict[block.block_id] = block   (dict 追加)

null_block [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/block_pool.py:174

特性

• block_id = 0: 初期化時に空きキューから最初に popleft される
• is_null = True: 解放・Eviction の対象外
• ref_cnt 未管理: touch() や free_blocks() で特別にスキップされる

用途

ガード条件

# touch() (L383)
if block.ref_cnt == 0 and not block.is_null:
    self.free_block_queue.remove(block)

# free_blocks() (L401-402)
[block for block in blocks_list if block.ref_cnt == 0 and not block.is_null]

# cache_full_blocks() (L260-261)
if blk.is_null:
    continue  # null ブロックはキャッシュしない

ブロック割り当てフロー [DEEP] [VERIFIED]

get_new_blocks()

参照: target/vllm/vllm/v1/core/block_pool.py:300

get_new_blocks(num_blocks)
  │
  ├─ 空きブロック数チェック → 不足なら ValueError
  │
  ├─ free_block_queue.popleft_n(num_blocks)
  │  └─ LRU 先頭（最古）から取り出し
  │
  ├─ enable_caching の場合:
  │  ├─ _maybe_evict_cached_block(block)  ← ハッシュクリア
  │  ├─ assert block.ref_cnt == 0
  │  ├─ block.ref_cnt += 1
  │  └─ metrics_collector.on_block_allocated(block)  ← サンプリング
  │
  └─ enable_caching でない場合:
     ├─ assert block.ref_cnt == 0
     ├─ block.ref_cnt += 1
     └─ metrics_collector.on_block_allocated(block)

注意: この関数はキャッシュ検索を行わない。キャッシュヒットの確認は get_cached_block() で別途行う。

get_cached_block()

参照: target/vllm/vllm/v1/core/block_pool.py:182

get_cached_block(block_hash, kv_cache_group_ids)
  │
  ├─ 各 group_id について:
  │  ├─ make_block_hash_with_group_id(block_hash, group_id)
  │  ├─ cached_block_hash_to_block.get_one_block(hash_with_id)
  │  └─ 1つでも miss → None を返す（全グループ一致が必須）
  │
  └─ 全ヒット → list[KVCacheBlock] を返す

All-or-nothing セマンティクス: 複数の KV キャッシュグループがある場合、全グループでヒットしなければキャッシュミスとして扱う。

ブロック解放フロー [DEEP] [VERIFIED]

free_blocks()

参照: target/vllm/vllm/v1/core/block_pool.py:389

def free_blocks(self, ordered_blocks: Iterable[KVCacheBlock]) -> None:
    blocks_list = list(ordered_blocks)           # イテレータを実体化
    for block in blocks_list:
        block.ref_cnt -= 1                       # 参照カウント減少
    self.free_block_queue.append_n(
        [block for block in blocks_list
         if block.ref_cnt == 0 and not block.is_null]  # 0 到達 & 非 null のみ
    )

逆順解放の理由: 呼び出し元（SingleTypeKVCacheManager.free()）がブロックを逆順にして渡す。チェーン末尾（最新トークン）がキューの先頭側に来るため、次回の get_new_blocks() で最初に evict される。先頭ブロック（プレフィックス）は末尾側に来るため、プレフィックスキャッシュとして長く生き残る。

touch()

参照: target/vllm/vllm/v1/core/block_pool.py:372

プレフィックスキャッシュヒット時に呼ばれ、ブロックの再利用を記録する。

touch(blocks)
  │
  ├─ ref_cnt == 0 かつ非 null の場合:
  │  └─ free_block_queue.remove(block)  ← 空きキューから除去
  │
  ├─ ref_cnt += 1
  │
  └─ metrics_collector.on_block_accessed(block)

Eviction メカニズム [DEEP] [VERIFIED]

_maybe_evict_cached_block()

参照: target/vllm/vllm/v1/core/block_pool.py:332

新規ブロック割り当て時に、そのブロックがプレフィックスキャッシュに登録されている場合にキャッシュから除去する。

_maybe_evict_cached_block(block)
  │
  ├─ metrics_collector.on_block_evicted(block)  ← 先にメトリクス記録
  │
  ├─ block.block_hash is None → return False（キャッシュ未登録）
  │
  ├─ cached_block_hash_to_block.pop(hash, block_id)
  │  └─ None → return False（マップに不在）
  │
  ├─ block.reset_hash()  ← ハッシュをクリア
  │
  ├─ enable_kv_cache_events の場合:
  │  └─ kv_event_queue.append(BlockRemoved(...))
  │
  └─ return True

タイミング: get_new_blocks() 内で ref_cnt をインクリメントする前に呼ばれる。

evict_blocks()

参照: target/vllm/vllm/v1/core/block_pool.py:405

外部（KV コネクタ）から特定の block_id 群を明示的に evict する。_maybe_evict_cached_block() を各ブロックに対して呼ぶ。ブロックは空きキューからは除去しない（ハッシュの除去のみ）。

reset_prefix_cache()

参照: target/vllm/vllm/v1/core/block_pool.py:424

全プレフィックスキャッシュのリセット。RLHF でモデル重み更新後にキャッシュを無効化する用途。

前提条件: 使用中のブロックが null_block のみ（num_used_blocks == 1）。条件を満たさない場合は False を返して失敗。

reset_prefix_cache()
  ├─ 使用中ブロック数 != 1 → return False
  ├─ cached_block_hash_to_block を新規インスタンスで置換
  ├─ 全ブロックの hash をリセット
  ├─ metrics_collector.reset()
  ├─ kv_event_queue.append(AllBlocksCleared())
  └─ return True

KV Cache Events [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/block_pool.py:177-178, 480-490

KV Transfer（Disaggregated Prefill）連携のためのイベントシステム。

def take_events(self) -> list[KVCacheEvent]:
    """アトミックにイベントキューを排出"""
    events = self.kv_event_queue
    self.kv_event_queue = []  # 新規リストで置換（参照スワップ）
    return events

キャッシュ使用率 [VERIFIED]

参照: target/vllm/vllm/v1/core/block_pool.py:467

def get_usage(self) -> float:
    total_gpu_blocks = self.num_gpu_blocks - 1  # null_block を除外
    return 1.0 - (self.get_num_free_blocks() / total_gpu_blocks)

null_block は常に「使用中」だが、使用率の計算からは除外される。

メトリクス収集 [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/kv_cache_metrics.py:46

KVCacheMetricsCollector はサンプリングベースのブロック滞留メトリクスを収集する。

BlockMetricsState

参照: target/vllm/vllm/v1/core/kv_cache_metrics.py:16

個別ブロックのライフサイクル指標:

サンプリング

sample_rate: float = 0.01  # デフォルト1%
def should_sample_block(self) -> bool:
    return random.random() < self.sample_rate

全ブロックを追跡するとオーバーヘッドが大きいため、割り当て時に確率的にサンプリングする。サンプリングされたブロックのみ BlockMetricsState が生成される。

イベントフック

Eviction 時に生成される KVCacheEvictionEvent には lifetime_seconds、idle_seconds、reuse_gaps_seconds が含まれ、drain_events() で一括取得できる。

BlockPool 初期化 [VERIFIED]

参照: target/vllm/vllm/v1/core/block_pool.py:147

def __init__(self, num_gpu_blocks, enable_caching, hash_block_size,
             enable_kv_cache_events=False, metrics_collector=None):
    self.blocks = [KVCacheBlock(idx) for idx in range(num_gpu_blocks)]
    self.free_block_queue = FreeKVCacheBlockQueue(self.blocks)
    self.cached_block_hash_to_block = BlockHashToBlockMap()
    self.null_block = self.free_block_queue.popleft()  # block_id=0
    self.null_block.is_null = True

• hash_block_size: ハッシュ計算に使うブロックサイズ。通常は実際のブロックサイズと一致するが、Hybrid モデル（異なるブロックサイズの KV キャッシュグループ）では異なる場合がある
• enable_kv_cache_events: KV Transfer 連携用のイベント発行を有効化
• metrics_collector: サンプリングベースの滞留メトリクス収集（オプション）

関連ドキュメント

• KVCacheManager サマリー
• プレフィックスキャッシュ詳細
• アテンションタイプ別 Manager
• Scheduler

プレフィックスキャッシュ詳細

深度: [DEEP] 確信度: [VERIFIED] 最終更新: 2026-02-11

概要

プレフィックスキャッシュは、異なるリクエスト間で共通するプロンプトプレフィックスの KV キャッシュブロックを再利用する機構である。トークン列をブロック単位でハッシュ化し、ハッシュチェーン（各ブロックのハッシュが前のブロックのハッシュに依存）を構築することで、プレフィックスの最長一致を効率的に検索する。

ハッシュチェーン計算 [DEEP] [VERIFIED]

hash_block_tokens()

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:525

各ブロックのハッシュは 3 要素のタプルから計算される:

def hash_block_tokens(hash_function, parent_block_hash, curr_block_token_ids,
                      extra_keys=None) -> BlockHash:
    if not parent_block_hash:
        parent_block_hash = NONE_HASH      # 先頭ブロック用のシード
    curr_block_token_ids_tuple = tuple(curr_block_token_ids)
    return BlockHash(
        hash_function((parent_block_hash, curr_block_token_ids_tuple, extra_keys))
    )

ハッシュ入力の 3 要素:

チェーン依存性

Block 0: hash(NONE_HASH, tokens[0:B], extra)   → H0
Block 1: hash(H0,        tokens[B:2B], extra)  → H1
Block 2: hash(H1,        tokens[2B:3B], extra) → H2
  ...

なぜチェーンか: 各ハッシュが全ての先行ブロックに依存するため、プレフィックスが異なれば後続のハッシュも必ず異なる。これにより左から右へのスキャンで「最初のミスで停止」すれば最長プレフィックス一致が得られる。

NONE_HASH

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:77

チェーンの起点となるシード値:

def init_none_hash(hash_fn):
    hash_seed = os.getenv("PYTHONHASHSEED")
    if hash_seed is None:
        NONE_HASH = BlockHash(os.urandom(32))    # ランダム 32 バイト
    else:
        NONE_HASH = BlockHash(hash_fn(hash_seed)) # 決定論的

• PYTHONHASHSEED 未設定: ランダムシード → プロセス間でハッシュが一致しない
• PYTHONHASHSEED 設定済み: 決定論的 → プロセス間でハッシュを共有可能（KV Transfer で必要）
• CBOR ベースのハッシュ関数で PYTHONHASHSEED 未設定の場合は警告が出る

BlockHash 型 [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:34

型階層

BlockHashWithGroupId のパッキング

def make_block_hash_with_group_id(block_hash, group_id):
    return BlockHashWithGroupId(
        block_hash + group_id.to_bytes(4, "big", signed=False)
    )

def get_block_hash(key):     return BlockHash(key[:-4])
def get_group_id(key):       return int.from_bytes(key[-4:], "big")

設計: tuple ではなく bytes 結合でパッキングすることで、Python オブジェクト生成を回避し、GC 負荷を低減。

ハッシュ関数 [DEEP] [VERIFIED]

参照: target/vllm/vllm/utils/hashing.py

4 種類のハッシュ関数が利用可能:

デフォルト: sha256_cbor — CBOR の canonical モードにより、PYTHONHASHSEED に依存しないシリアライゼーションが可能。プロセス間でハッシュを共有する KV Transfer に適している。

設定: vllm_config.cache_config.prefix_caching_hash_algo

Extra Keys [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:367

同一トークン列でも異なる KV キャッシュを持つ場合に、追加情報をハッシュに含める。

必要判定

def need_extra_keys(request):
    return (bool(request.mm_features)           # マルチモーダル
            or (request.lora_request is not None) # LoRA
            or (request.cache_salt is not None))  # キャッシュソルト

各 Extra Key の生成

結合順序

extra_keys = lora_extra_keys + mm_extra_keys + cache_salt_keys + prompt_embeds_keys

空の場合は None を返し、ハッシュ計算の extra_keys 引数として渡される。

マルチモーダル Extra Keys の詳細

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:387

_gen_mm_extra_hash_keys() はブロックの [start, end) トークン範囲と MM 入力の [offset, offset+length) 範囲の重なりを検出する:

MM入力: [offset ─────── offset+length]
Block:         [start ──── end]
               ↑ 重なりあり → identifier を extra_keys に追加

• mm_features は mm_position.offset でソート済みと仮定
• start_mm_idx で走査位置を追跡し、毎回先頭から検索しない
• start_mm_idx = -1 は「最後の MM 入力」を示す（生成トークンが増えるデコードフェーズで使用）

リクエストブロックハッシャー [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:555

ファクトリ関数

def get_request_block_hasher(block_size, caching_hash_fn):
    def request_block_hasher(request) -> list[BlockHash]:
        start_token_idx = len(request.block_hashes) * block_size
        # full ブロックのみハッシュ（不完全ブロックはスキップ）
        if start_token_idx + block_size > request.num_tokens:
            return []
        # ...ハッシュチェーンを走査して新規 full ブロックのハッシュを計算
    return request_block_hasher

遅延・インクリメンタル計算

1. 初期化時: Request.__init__() で block_hasher が渡された場合、即座に get_hash_new_full_blocks() を呼び、プロンプトの full ブロック分のハッシュを計算
2. トークン追加時: Request.append_output_token_ids() で新トークンが追加されるたびに get_hash_new_full_blocks() を呼び、新たに full になったブロックのハッシュをインクリメンタルに追加

# Request.__init__()
self.block_hashes = self.get_hash_new_full_blocks()  # 初期ハッシュ

# Request.append_output_token_ids()
self.block_hashes.extend(self.get_hash_new_full_blocks())  # 増分追加

制約: 不完全ブロック（最後のブロックが block_size 未満）はハッシュされない。これによりプレフィックスキャッシュは常にブロック境界単位で一致する。

チェーンの継続

prev_block_hash_value = request.block_hashes[-1] if request.block_hashes else None

前回計算済みの最後のハッシュを parent_block_hash として使い、チェーンを継続する。

BlockHashListWithBlockSize [DEEP] [VERIFIED]

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:1571

Hybrid モデル（異なるブロックサイズの KV キャッシュグループ）でハッシュ粒度を変換するアダプタ。

動作原理

hash_block_size = 16, target_block_size = 32 の場合:

元のハッシュ:  [H0, H1, H2, H3]  (各16トークン)
変換後:        [H0+H1, H2+H3]     (各32トークン)
                  ↑ bytes 結合

def _get_value_at(self, idx):
    base = idx * self.scale_factor   # scale_factor = target / hash
    end = base + self.scale_factor
    merged_hash = self.block_hashes[base]
    for i in range(base + 1, end):
        merged_hash += self.block_hashes[i]  # bytes 結合
    return BlockHash(merged_hash)

遅延評価: アクセス時にのみ変換を実行。__getitem__、__iter__、__len__ をサポートし、通常の list[BlockHash] と同じインターフェースで使える。

Lookup アルゴリズム [DEEP] [VERIFIED]

プレフィックスキャッシュの検索は SingleTypeKVCacheManager のサブクラスごとに異なるアルゴリズムを持つ。

FullAttentionManager: 左→右スキャン

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:401

for block_hash in block_hashes[:max_num_blocks]:
    if cache hit:
        computed_blocks.append(cached_block)
    else:
        break  ← 最初のミスで停止

• Downward-closed 性質: blocks[0..n] がヒットするなら blocks[0..n-1] も必ずヒットする
• EAGLE 使用時は最後のブロックを削除（hidden states が必要なため）
• alignment_tokens でアライメント調整（Hybrid モデルでの LCM ブロックサイズ）

SlidingWindowManager: 右→左スキャン

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:466

sliding_window_contiguous_blocks = ceil((sliding_window - 1) / block_size)

for i in range(max_num_blocks - 1, -1, -1):  # 右→左
    if cache hit:
        computed_blocks[i] = cached_block
        num_contiguous_blocks += 1
        if num_contiguous_blocks >= required:
            break  ← ウィンドウ分の連続ブロック確保
    else:
        num_contiguous_blocks = 0  ← 連続性リセット

• 連続ブロックが必須: Sliding Window Attention はウィンドウ内の連続したトークンにのみアテンションするため、不連続なブロックは使えない
• computed_blocks は初期値として null_block で埋められ、ヒットした位置のみ実ブロックで置換される
• アライメントチェック: 右端のブロックがアライメント境界に合わない場合はスキップ

ChunkedLocalAttentionManager

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:594

チャンク境界でアテンションが分割されるモデル用。ウィンドウ外のブロックは null_block でパディングし、ウィンドウ内のみ左→右スキャンで検索する。

MambaManager: 右→左、単一一致

参照: target/vllm/vllm/v1/core/single_type_kv_cache_manager.py:744

Mamba（線形アテンション）は最後の状態のみが必要なため、最初のヒットで即座に停止する。

HybridKVCacheCoordinator: 反復固定点

参照: target/vllm/vllm/v1/core/kv_cache_coordinator.py:448

複数のアテンションタイプが混在する Hybrid モデルでは、各グループの最長ヒット長が相互に制約し合う:

hit_length = max_cache_hit_length

while True:
    curr_hit_length = hit_length
    for each attention_group:
        if is_full_attention and cached:
            # Downward-closed: 既存結果を再利用
            curr_hit_length = (curr_hit_length // block_size) * block_size
        else:
            hit = find_longest_cache_hit(curr_hit_length)
            curr_hit_length = len(hit) * block_size

    if curr_hit_length >= hit_length:
        break  ← 収束（もう減らない）
    hit_length = curr_hit_length

    if is_simple_hybrid:  # FullAttn + 1種のみ
        break  ← 1回で十分

収束保証: hit_length は単調減少するため、有限回で収束する。 最適化: Full Attention は downward-closed なので、他グループの結果に合わせてカットするだけでよい。2グループの simple hybrid ケースでは 1 イテレーションで確定。

キャッシュ登録 [DEEP] [VERIFIED]

cache_full_blocks()

参照: target/vllm/vllm/v1/core/block_pool.py:209

計算済みの full ブロックをプレフィックスキャッシュに登録する。

cache_full_blocks(request, blocks, num_cached_blocks, num_full_blocks, ...)
  │
  ├─ num_cached_blocks >= num_full_blocks → return（既に登録済み）
  │
  ├─ new_full_blocks = blocks[num_cached_blocks:num_full_blocks]
  │
  ├─ block_size == hash_block_size の場合:
  │  └─ block_hashes = request.block_hashes（直接使用）
  │
  ├─ block_size != hash_block_size の場合:
  │  └─ block_hashes = BlockHashListWithBlockSize(...)（粒度変換）
  │
  └─ 各 new_full_block について:
     ├─ is_null → skip
     ├─ assert block_hash is None（二重登録防止）
     ├─ block_hash_with_group_id を生成
     ├─ blk.block_hash = block_hash_with_group_id
     ├─ cached_block_hash_to_block.insert(...)
     └─ enable_kv_cache_events → BlockStored イベント発行

num_cached_block トラッキング

SingleTypeKVCacheManager が num_cached_block[request_id] で各リクエストの登録済みブロック数を追跡する。cache_blocks() 呼び出し時に num_cached_blocks >= num_full_blocks なら何もせず、新たに full になったブロックのみを登録する。

データフロー全体 [VERIFIED]

EngineCore.__init__()
  └─ init_none_hash(hash_fn)        ← グローバル NONE_HASH 初期化
  └─ get_request_block_hasher(...)   ← ハッシャークロージャ生成

Request.__init__(block_hasher=...)
  └─ block_hashes = get_hash_new_full_blocks()  ← プロンプトの full ブロックを即時ハッシュ

Request.append_output_token_ids()
  └─ block_hashes.extend(get_hash_new_full_blocks())  ← 増分ハッシュ

Scheduler.schedule()
  ├─ kv_cache_manager.get_computed_blocks(request)
  │  └─ coordinator.find_longest_cache_hit(request.block_hashes, max_length)
  │     └─ block_pool.get_cached_block(hash, group_ids)
  │        └─ BlockHashToBlockMap.get_one_block(hash_with_group_id)
  │
  └─ kv_cache_manager.allocate_slots(request, ...)
     └─ coordinator.cache_blocks(request, num_tokens_to_cache)
        └─ block_pool.cache_full_blocks(request, blocks, ...)
           └─ BlockHashToBlockMap.insert(hash_with_group_id, block)

関連ドキュメント

• KVCacheManager サマリー
• BlockPool 詳細
• アテンションタイプ別 Manager
• 用語集

KV Transfer [MEDIUM] [VERIFIED]

最終更新: 2026-02-15 対象ソース: target/vllm/vllm/distributed/kv_transfer/, target/vllm/vllm/v1/worker/kv_connector_model_runner_mixin.py

概要

KV Transferは、vLLMインスタンス間またはストレージ間でデコーダKVキャッシュを転送するためのプラグインフレームワーク。Disaggregated Prefill（P/D分離）、KVキャッシュのオフロード、外部キャッシュ（LMCache等）との連携を実現する。

ECConnector（ec_transfer/）とは完全に独立した系統。ECConnectorがエンコーダキャッシュ専用であるのに対し、KV Transferはデコーダ側のKVキャッシュのみを対象とする。ただし、設計パターン（2ロール分離、Factory、Mixin統合）は共通している。

アーキテクチャ

graph TD
    subgraph Scheduler["Scheduler プロセス"]
        S[Scheduler] -->|"get_num_new_matched_tokens()"| KC_S[KVConnector<br/>SCHEDULER ロール]
        S -->|"update_state_after_alloc()"| KC_S
        S -->|"build_connector_meta()"| KC_S
        S -->|"request_finished()"| KC_S
        S -->|"take_events()"| KC_S
    end

    subgraph Worker["Worker プロセス"]
        MR[GPUModelRunner] -->|"Mixin"| KC_W[KVConnector<br/>WORKER ロール]
        KC_W -->|"start_load_kv()"| EXT[外部ストレージ<br/>LMCache / NIXL / etc.]
        KC_W -->|"save_kv_layer()"| EXT
        ATT[Attention層] -->|"wait_for_layer_load()"| KC_W
        ATT -->|"save_kv_layer()"| KC_W
    end

    KC_S -.->|"KVConnectorMetadata<br/>(via SchedulerOutput)"| KC_W
    KC_W -.->|"KVConnectorOutput<br/>(via ModelRunnerOutput)"| KC_S

参照: target/vllm/vllm/distributed/kv_transfer/kv_connector/v1/base.py:147 (KVConnectorBase_V1)

2ロール分離

KVConnectorBase_V1は同一クラスだが、SchedulerプロセスとWorkerプロセスで別インスタンスが生成される。KVConnectorFactory.create_connector()がロールを引数に取り、各プロセスで適切なインスタンスを構築する。

# KVConnectorRole enum
class KVConnectorRole(enum.Enum):
    SCHEDULER = 0  # Schedulerプロセス内
    WORKER = 1     # Workerプロセス内

参照: target/vllm/vllm/distributed/kv_transfer/kv_connector/v1/base.py:121

グローバル状態管理

Worker側のKVConnectorインスタンスはグローバル変数で管理される。

参照: target/vllm/vllm/distributed/kv_transfer/kv_transfer_state.py:16-74

KVConnectorBase_V1 抽象基底クラス

Abstract メソッド（7つ）

Worker側（4つ）

レイヤーバイレイヤー・パイプライニング: start_load_kv()で全レイヤーのロードを非同期開始し、各Attention層のforward内でwait_for_layer_load()を呼ぶことで、前のレイヤーの計算中に次レイヤーのKVをロードできる。セーブもsave_kv_layer()で即座に非同期開始し、wait_for_save()で全体の完了を保証する。

参照: target/vllm/vllm/distributed/kv_transfer/kv_connector/v1/base.py:275-338

Scheduler側（3つ）

get_num_new_matched_tokens() の戻り値:

• (N, False) — N個の外部トークンが同期的に利用可能
• (N, True) — N個の外部トークンが非同期ロード（WAITING_FOR_REMOTE_KVS状態へ遷移）
• (None, _) — まだ判定不能（次回再問い合わせ）
• (0, False) — 外部キャッシュなし

参照: target/vllm/vllm/distributed/kv_transfer/kv_connector/v1/base.py:416-485

非Abstract 重要メソッド

補助クラス・インタフェース

参照: target/vllm/vllm/distributed/kv_transfer/kv_connector/v1/base.py:82-144

Cross-Layer Blocks

prefer_cross_layer_blocksプロパティがTrueのコネクタは、全レイヤーのKVを1つの連続テンソルにまとめたレイアウトを使用する。これにより、ブロック単位で全レイヤーのKVデータを一括転送でき、転送効率が向上する。

参照: target/vllm/vllm/v1/worker/kv_connector_model_runner_mixin.py:113-177

KVConnectorFactory

遅延ロードパターンのファクトリ。module_path + class_nameを登録し、使用時にimportする。

登録済みコネクタ（10個）

動的ロード: kv_connector_module_path設定で未登録クラスも使用可能。旧2引数シグネチャとの互換性チェック（supports_kw()）あり。

参照: target/vllm/vllm/distributed/kv_transfer/kv_connector/factory.py:27-203

Scheduler統合

外部キャッシュ問い合わせフロー

WAITINGリクエストのスケジューリング時、ローカルプレフィックスキャッシュに加えて外部KVキャッシュも問い合わせる。

sequenceDiagram
    participant S as Scheduler
    participant KV as KVConnector (SCHEDULER)
    participant CM as KVCacheManager

    Note over S: _schedule_waiting()
    S->>CM: get_computed_blocks(request)
    CM-->>S: local_computed_tokens

    S->>KV: get_num_new_matched_tokens(request, local_computed_tokens)
    KV-->>S: (external_tokens, is_async)

    Note over S: total = local + external
    S->>CM: allocate_slots(request, num_new_tokens, ..., delay_cache_blocks=is_async)
    CM-->>S: new_blocks

    S->>KV: update_state_after_alloc(request, blocks, external_tokens)

    alt is_async=True
        Note over S: request.status = WAITING_FOR_REMOTE_KVS
    else is_async=False
        Note over S: request.status = RUNNING
    end

    Note over S: schedule()末尾
    S->>KV: build_connector_meta(scheduler_output)
    KV-->>S: KVConnectorMetadata

参照: target/vllm/vllm/v1/core/sched/scheduler.py:608-772

WAITING_FOR_REMOTE_KVS 状態管理

非同期KVロード中のリクエストはWAITING_FOR_REMOTE_KVS状態に遷移する。

1. _update_from_kv_xfer_finished(): Worker側コネクタのfinished_recving/finished_sendingを処理
   • finished_recving → finished_recving_kv_req_idsに追加（次stepで処理）
   • finished_sending → ブロック即時解放
2. _update_waiting_for_remote_kv(): WAITING_FOR_REMOTE_KVS状態のリクエストを確認
   • 受信完了 → kv_cache_manager.cache_blocks()でキャッシュ → WAITING状態に戻す
   • ロードエラー → 有効なcomputed_tokensだけキャッシュ、またはブロック解放

参照: target/vllm/vllm/v1/core/sched/scheduler.py:1961-2034

リクエスト完了時の遅延解放

_connector_finished()はrequest_finished()を呼び、コネクタがブロックの非同期送信を引き受けるかを確認する。

delay_free, kv_xfer_params = connector.request_finished(request, block_ids)
# delay_free=True → ブロックはget_finished()で送信完了報告後に解放
# kv_xfer_params → リクエスト出力に含めるKV転送パラメータ

参照: target/vllm/vllm/v1/core/sched/scheduler.py:1930-1959

Worker/GPUModelRunner 統合

KVConnectorModelRunnerMixin

GPUModelRunnerにミックスインされ、KVコネクタのライフサイクルを管理する。

_get_kv_connector_output() — コアライフサイクル

@contextmanager
def _get_kv_connector_output(scheduler_output, wait_for_save=True):
    output = KVConnectorOutput()
    kv_connector = get_kv_transfer_group()

    # 1. Scheduler側メタデータをバインド
    kv_connector.bind_connector_metadata(scheduler_output.kv_connector_metadata)

    # 2. 非同期KVロード開始（forward前）
    kv_connector.start_load_kv(get_forward_context())

    try:
        yield output  # ← ここでモデルforward実行（save_kv_layer含む）
    finally:
        # 3. セーブ完了待機
        if wait_for_save:
            kv_connector.wait_for_save()

        # 4. 完了・エラー情報収集
        output.finished_sending, output.finished_recving = (
            kv_connector.get_finished(scheduler_output.finished_req_ids))
        output.invalid_block_ids = kv_connector.get_block_ids_with_load_errors()
        output.kv_connector_stats = kv_connector.get_kv_connector_stats()
        output.kv_cache_events = kv_connector.get_kv_connector_kv_cache_events()

        # 5. メタデータクリア
        kv_connector.clear_connector_metadata()

参照: target/vllm/vllm/v1/worker/kv_connector_model_runner_mixin.py:80-111

execute_model() 内の呼び出し位置

# GPUModelRunner.execute_model()

# (1) プリエンプション処理
if scheduler_output.preempted_req_ids and has_kv_transfer_group():
    get_kv_transfer_group().handle_preemptions(scheduler_output.preempted_req_ids)

# (2) forward不要時のKV転送
if num_reqs == 0:
    return self.kv_connector_no_forward(scheduler_output, self.vllm_config)

# (3) モデルforward + KVコネクタ
with self.maybe_get_kv_connector_output(scheduler_output) as kv_connector_output:
    model_output = self._model_forward(...)

# (4) sample_tokens()に引き渡し
self.kv_connector_output = kv_connector_output  # ephemeral state

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:3330-3617

KVコネクタ初期化

GPUModelRunner._initialize_kv_caches()内で、KVキャッシュ確保後にコネクタを登録する。

if has_kv_transfer_group():
    kv_transfer_group = get_kv_transfer_group()
    if self.cross_layers_kv_cache is not None:
        kv_transfer_group.register_cross_layers_kv_cache(
            self.cross_layers_kv_cache, self.cross_layers_attn_backend)
    else:
        kv_transfer_group.register_kv_caches(kv_caches)
    kv_transfer_group.set_host_xfer_buffer_ops(copy_kv_blocks)

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:6079-6088

KVConnectorOutput

Worker→Schedulerへのフィードバック構造体。

参照: target/vllm/vllm/v1/outputs.py:123-148

KV Cache Events

外部システム（ルーティング、モニタリング等）へのKVキャッシュ状態通知システム。

イベント型

参照: target/vllm/vllm/distributed/kv_events.py:49-84

イベントフロー

1. Worker側コネクタがBlockStored/BlockRemovedイベントを生成
2. _get_kv_connector_output()がイベントをKVConnectorOutput.kv_cache_eventsに収集
3. Scheduler側でupdate_connector_output()→KVEventAggregatorで全Worker共通イベントを集約
4. take_events()で集約済みイベントを取得
5. EventPublisher（ZMQ PUB/ROUTERまたはNull）で外部に配信

EventPublisher

参照: target/vllm/vllm/distributed/kv_events.py:205-473

KVTransferConfig

KV Transferの設定。--kv-transfer-configで指定する。

参照: target/vllm/vllm/config/kv_transfer.py:17-117

ECConnectorとの比較

ディレクトリ構造

target/vllm/vllm/distributed/kv_transfer/
├── kv_connector/
│   ├── base.py                    # KVConnectorBase リダイレクト
│   ├── factory.py                 # KVConnectorFactory + 10コネクタ登録
│   ├── utils.py
│   └── v1/
│       ├── base.py                # KVConnectorBase_V1 (抽象基底)
│       ├── metrics.py             # KVConnectorStats, Prometheus
│       ├── example_connector.py   # safetensorsデバッグ用
│       ├── lmcache_connector.py   # LMCacheラッパー
│       ├── lmcache_mp_connector.py
│       ├── nixl_connector.py
│       ├── offloading_connector.py
│       ├── multi_connector.py     # 複合コネクタ
│       ├── decode_bench_connector.py
│       ├── lmcache_integration/   # native LMCache実装
│       │   ├── vllm_v1_adapter.py
│       │   ├── multi_process_adapter.py
│       │   └── utils.py
│       ├── p2p/                   # P2P NCCLコネクタ
│       ├── moriio/                # MORIIOコネクタ
│       └── mooncake/              # Mooncakeコネクタ
├── kv_transfer_state.py           # グローバル状態管理
└── __init__.py

target/vllm/vllm/distributed/kv_events.py  # イベントシステム
target/vllm/vllm/config/kv_transfer.py     # KVTransferConfig
target/vllm/vllm/v1/worker/kv_connector_model_runner_mixin.py  # Mixin

依存関係

上流（KV Transferを使う側）

下流（KV Transferが使う側）

マルチモーダル処理パイプライン サマリー

深度: [MEDIUM] 確信度: [VERIFIED] 最終更新: 2026-02-11

概要

vLLMのマルチモーダル処理パイプラインは、画像・音声・動画等の非テキストデータをLLMの推論に統合するシステムである。フロントエンド（P0）でのメディア前処理・キャッシュと、バックエンド（P1）でのエンコーダ実行・埋め込みマージの2段構成で動作する。

エンドツーエンド データフロー

graph TD
    A["API Request<br>(messages + images)"] --> B["ChatTemplate 適用<br>プレースホルダー挿入"]
    B --> C["InputPreprocessor<br>トークナイズ + HF Processor"]

    C --> D{"ProcessorCache<br>ヒット?"}
    D -->|HIT| E["キャッシュから取得<br>(HF処理スキップ)"]
    D -->|MISS| F["HF Processor 実行<br>pixel_values テンソル生成"]
    E --> G["MultiModalFeatureSpec 構築"]
    F --> G

    G --> H["EngineCoreRequest<br>ZMQ IPC 送信"]

    H --> I["Scheduler"]
    I --> J{"EncoderCacheManager<br>ヒット?"}
    J -->|HIT| K["エンコーダ計算スキップ"]
    J -->|MISS| L["encoder_compute_budget<br>から割り当て"]

    K --> M["GPUModelRunner"]
    L --> M

    M --> N["_execute_mm_encoder()<br>model.embed_multimodal()"]
    N --> O["encoder_cache に格納"]
    O --> P["_gather_mm_embeddings()<br>キャッシュからスライス"]
    P --> Q["embed_input_ids()<br>text + vision マージ<br>(masked_scatter_)"]
    Q --> R["model.forward()<br>統合推論"]

主要コンポーネント

キャッシュの3層構造

P0（フロントエンド）               P1（Scheduler）              P1（GPU）
┌──────────────────┐           ┌─────────────────┐        ┌──────────────┐
│ ProcessorCache   │           │ EncoderCache    │        │ encoder_cache│
│ LRU, サイズベース │           │ Manager         │        │ dict[str,    │
│                  │           │ RefCount + FIFO │        │  Tensor]     │
│ 何をキャッシュ:   │           │                 │        │              │
│ HF処理済みテンソル │           │ 何を管理:       │        │ 何をキャッシュ:│
│ + prompt_updates │           │ 容量・参照カウント│       │ エンコーダ出力│
│                  │           │ Evictionリスト   │        │ (GPUテンソル) │
└──────────────────┘           └─────────────────┘        └──────────────┘
  ヒット時:                      ヒット時:                   ヒット時:
  HF処理スキップ                 エンコーダ計算スキップ        テンソル再利用
  IPC転送量削減                  予算節約                    再計算不要

テキスト推論との主な差分

Gemma3 固有の特徴

• ビジョンエンコーダ: SiglipVisionModel（SIGLIP ViT、双方向Attention）
• プロジェクタ: AvgPool2d → GemmaRMSNorm → Linear（vision → text空間）
• プレースホルダー: <start_of_image> → image_token × 256 に展開
• Pan-and-Scan: アスペクト比が大きい画像を複数クロップ（V1では簡略化されたアテンション）
• 改行トークン結合: \n + \n\n → \n\n\n 等の特殊処理

詳細ドキュメント

上流・下流

• 上流: エントリポイント → InputProcessor
• 下流: Scheduler → GPUModelRunner → モデル層

主要ファイル

Gemma3 ビジョンエンコーダと画像処理 [MEDIUM] [VERIFIED]

最終更新: 2026-02-11

Gemma3 モデルにおけるビジョンエンコーダ（SiglipVisionModel）、プロジェクタ（Gemma3MultiModalProjector）、および text + vision 埋め込みマージの詳細。

モデルアーキテクチャ全体像

graph TD
    subgraph "Gemma3ForConditionalGeneration"
        subgraph "vision_tower (SiglipVisionModel)"
            PE["SiglipVisionEmbeddings<br>Conv2d patch embedding<br>+ position embedding"]
            ENC["SiglipEncoder<br>N層 Transformer<br>(双方向Attention)"]
            PE --> ENC
        end

        PROJ["Gemma3MultiModalProjector<br>AvgPool2d → RMSNorm → Linear"]
        ENC --> PROJ

        subgraph "language_model (Gemma3ForCausalLM)"
            EMB["embed_tokens()<br>テキスト埋め込み"]
            LM["Transformer Decoder<br>(因果的Attention)"]
            EMB --> LM
        end

        MERGE["masked_scatter_<br>text + vision マージ"]
        PROJ --> MERGE
        EMB --> MERGE
        MERGE --> LM
    end

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:481-694

1. SiglipVisionModel（ビジョンエンコーダ）

構造

参照: target/vllm/vllm/model_executor/models/siglip.py:848-894

SiglipVisionModel
  └─ SiglipVisionTransformer (L681)
      ├─ SiglipVisionEmbeddings (L282)
      │   ├─ patch_embedding: Conv2d(3, hidden_size, kernel=patch_size, stride=patch_size)
      │   └─ position_embedding: Embedding(num_patches, hidden_size)
      ├─ SiglipEncoder (L520)
      │   └─ layers: ModuleList[SiglipEncoderLayer] × N
      │       ├─ layer_norm1 → SiglipAttention (MMEncoderAttention)
      │       └─ layer_norm2 → SiglipMLP
      └─ post_layernorm: LayerNorm（最終層のみ）

パッチ埋め込み (SiglipVisionEmbeddings)

参照: target/vllm/vllm/model_executor/models/siglip.py:282-352

# 入力: pixel_values (batch, 3, H, W)
patch_embeds = self.patch_embedding(pixel_values)  # Conv2d: (batch, hidden_size, grid, grid)
embeddings = patch_embeds.flatten(2).transpose(1, 2)  # (batch, num_patches, hidden_size)
embeddings += self.position_embedding(position_ids)    # 位置埋め込みを加算

• image_size = 256 の場合、patch_size = 16 → num_patches = (256/16)² = 256
• 各パッチは 16×16×3 = 768 ピクセルから hidden_size 次元のベクトルに変換
• 位置埋め込みは学習済みの nn.Embedding（補間対応あり）

エンコーダ層 (SiglipEncoder)

参照: target/vllm/vllm/model_executor/models/siglip.py:520-567

各エンコーダ層の構造:

SiglipEncoderLayer:
    residual = hidden_states
    hidden_states = layer_norm1(hidden_states)
    hidden_states = self_attn(hidden_states)     ← MMEncoderAttention（双方向）
    hidden_states = residual + hidden_states
    residual = hidden_states
    hidden_states = layer_norm2(hidden_states)
    hidden_states = mlp(hidden_states)
    hidden_states = residual + hidden_states

• アテンション型: MMEncoderAttention（双方向、因果マスクなし）
• 全パッチが全パッチを参照できる（テキストの因果アテンションとは異なる）

forward() フロー

参照: target/vllm/vllm/model_executor/models/siglip.py:755-788

def forward(self, pixel_values, *, select_layers=None, feature_select_strategy=None):
    hidden_states = self.embeddings(pixel_values)      # (batch, num_patches, hidden_size)
    encoder_outputs = self.encoder(inputs_embeds=hidden_states)  # N層 Transformer
    encoder_outputs = resolve_visual_encoder_outputs(   # 特徴選択
        encoder_outputs, select_layers, feature_select_strategy
    )
    return self.last_hs_proc(encoder_outputs)           # post_layernorm + head

出力: (batch, num_patches, hidden_size) — 典型的に (batch, 256, 1152)

2. Gemma3MultiModalProjector（投射層）

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:432-473

ビジョンエンコーダの出力をテキスト埋め込み空間に変換する。

パラメータ

mm_input_projection_weight: (vision_hidden_size, text_hidden_size)  # 例: (1152, 2048)
mm_soft_emb_norm: GemmaRMSNorm(vision_hidden_size)
avg_pool: AvgPool2d(kernel_size, stride=kernel_size)

設定値の計算

patches_per_image = image_size // patch_size           # 256 // 16 = 16
tokens_per_side = int(mm_tokens_per_image ** 0.5)      # int(256 ** 0.5) = 16
kernel_size = patches_per_image // tokens_per_side     # 16 // 16 = 1

kernel_size = 1 の場合、AvgPool2dは実質的にno-op（パッチ数が変わらない）。mm_tokens_per_image が小さい設定ではダウンサンプリングが発生する。

forward() フロー

def forward(self, vision_outputs):
    # vision_outputs: (batch, hidden_size, num_patches) — エンコーダ出力のtranspose形式
    batch_size, _, seq_length = vision_outputs.shape

    # 1. 2Dグリッドへリシェイプ
    reshaped = vision_outputs.transpose(1, 2).reshape(
        batch_size, seq_length, patches_per_image, patches_per_image
    )  # (batch, seq_length, 16, 16)

    # 2. 平均プーリング（ダウンサンプリング）
    pooled = self.avg_pool(reshaped)  # kernel=1の場合: (batch, seq_length, 16, 16)
    pooled = pooled.flatten(2).transpose(1, 2)  # (batch, mm_tokens_per_image, seq_length)

    # 3. RMS正規化
    normed = self.mm_soft_emb_norm(pooled)

    # 4. 線形投射: vision_hidden_size → text_hidden_size
    projected = torch.matmul(normed, self.mm_input_projection_weight)
    # (batch, mm_tokens_per_image, text_hidden_size)

    return projected.type_as(vision_outputs)

重要な注意: テキスト埋め込みの正規化とは異なり、ビジョン埋め込みには mm_soft_emb_norm のみが適用される。vocab embedding に適用されるスケーリング（embed_tokens * normalizer）はビジョン埋め込みには適用 されない。

3. embed_multimodal() と _process_image_input()

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:567-594

GPUModelRunner の _execute_mm_encoder() から呼ばれるメインのエンコーダ実行パス:

def embed_multimodal(self, **kwargs):
    image_input = self._parse_and_validate_image_input(**kwargs)  # pixel_values 取得
    if image_input is None:
        return []
    return self._process_image_input(image_input)

def _process_image_input(self, image_input):
    pixel_values = image_input["pixel_values"]    # (total_patches, 3, image_size, image_size)
    num_patches = image_input["num_patches"]       # (num_images,) — 画像ごとのパッチ数

    # ビジョンエンコーダ実行
    image_features = self._image_pixels_to_features(self.vision_tower, pixel_values)

    # プロジェクタで投射
    image_embeds = self.multi_modal_projector(image_features)

    # 画像ごとに分割 + flatten
    return [e.flatten(0, 1) for e in image_embeds.split(num_patches.tolist())]
    # list[Tensor(mm_tokens_per_image, text_hidden_size)]

テンソル形状の追跡

画像1枚、Pan-and-Scan なし（num_patches=1）の場合:

4. テキスト + ビジョン埋め込みのマージ

embed_input_ids()

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:596-614

def embed_input_ids(self, input_ids, multimodal_embeddings=None, *, is_multimodal=None, ...):
    if multimodal_embeddings is None or is_multimodal is None:
        return super().embed_input_ids(input_ids)  # テキストのみ
    return super().embed_input_ids(
        input_ids, multimodal_embeddings=multimodal_embeddings,
        is_multimodal=is_multimodal, handle_oov_mm_token=True,
    )

_merge_multimodal_embeddings()

参照: target/vllm/vllm/model_executor/models/utils.py:445-487

def _merge_multimodal_embeddings(inputs_embeds, multimodal_embeddings, is_multimodal):
    mm_embeds_flat = _flatten_embeddings(multimodal_embeddings)
    # in-place 置換: is_multimodal=True の位置を mm_embeds_flat で上書き
    inputs_embeds.masked_scatter_(
        is_multimodal.unsqueeze(-1),
        mm_embeds_flat.to(dtype=inputs_embeds.dtype)
    )
    return inputs_embeds

masked_scatter_ の動作:

1. is_multimodal: (seq_len,) のboolテンソル（True = 画像プレースホルダー位置）
2. is_multimodal.unsqueeze(-1): (seq_len, 1) → ブロードキャストで (seq_len, hidden_size) に展開
3. mm_embeds_flat: True位置の数 × hidden_size の連続テンソル
4. True位置に順番に mm_embeds_flat の値を書き込む

制約: is_multimodal.sum() == len(mm_embeds_flat) でなければランタイムエラー

handle_oov_mm_token

Gemma3 は handle_oov_mm_token=True を指定。これは image_token_id が vocab の範囲外の場合でも安全に処理するための仕組み。

5. Pan-and-Scan（パノラマクロップ）

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:109-176

アスペクト比が大きい画像に対して、複数のクロップを生成して詳細認識を向上させる仕組み。

クロップ数の計算

def get_num_crops(self, *, image_width, image_height, processor):
    # 横長画像の場合
    if image_width >= image_height:
        if width/height < min_ratio:  return 0  # 比率が小さすぎる
        num_crops_w = min(floor(width/min_crop_size), floor(w/h + 0.5))
        num_crops_w = max(2, num_crops_w)
        num_crops_w = min(max_num_crops, num_crops_w)
        num_crops_h = 1

    # 縦長画像の場合は逆
    ...

    # クロップサイズが小さすぎる場合は無効
    if min(crop_size_w, crop_size_h) < min_crop_size:
        return 0

    return num_crops_w * num_crops_h

Pan-and-Scan時のプロンプト

"Here is the original image <full_image_seq> and here are some crops to help you see better <full_image_seq> <full_image_seq>"

各 <full_image_seq> は image_seq_length（=256）トークンを消費。

V1での制限: Pan-and-Scan は簡略化されたアテンションパターンを使用するため、最適ではない結果になる可能性がある。

6. forward() — 最終推論

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:616-635

def forward(self, input_ids, positions, intermediate_tensors=None, inputs_embeds=None, **kwargs):
    if intermediate_tensors is not None:
        inputs_embeds = None  # Pipeline Parallelism の中間ランク

    hidden_states = self.language_model.model(
        input_ids,
        positions,
        intermediate_tensors,
        inputs_embeds=inputs_embeds,  # text + vision マージ済み
        **kwargs,
    )
    return hidden_states

マルチモーダル時は inputs_embeds が渡され、input_ids は使用されない（embed_input_ids で既に埋め込み済みのため）。

データフロー全体

pixel_values: (total_patches, 3, 256, 256)
      │
      ▼
SiglipVisionEmbeddings
  Conv2d(3→1152, k=16, s=16) + position_embedding
      │
      ▼
(total_patches, 256, 1152)
      │
      ▼
SiglipEncoder (N層 Transformer, 双方向Attention)
      │
      ▼
(total_patches, 256, 1152)
      │
      ▼
Gemma3MultiModalProjector
  reshape → AvgPool2d → RMSNorm → matmul(1152→2048)
      │
      ▼
(total_patches, 256, 2048)
      │
      ▼
split by num_patches → list[(mm_tokens, 2048)]
      │
      ▼
encoder_cache[mm_hash] に格納
      │
      ▼
_gather_mm_embeddings() でスライス
      │
      ▼
embed_input_ids():
  text_embeds = embed_tokens(input_ids)     # (seq_len, 2048)
  merged = masked_scatter_(text_embeds, is_multimodal, mm_embeds)
      │
      ▼
language_model.model(inputs_embeds=merged)  # Gemma3 Decoder

主要ファイル

関連ドキュメント

• フロントエンド MM処理パス
• バックエンド MM処理パス
• マルチモーダル処理パイプライン概要

バックエンド マルチモーダル処理パス [MEDIUM] [VERIFIED]

最終更新: 2026-02-11

EngineCore（P1）でマルチモーダルリクエストがどのように処理されるかを追跡する。EncoderCacheManager、Schedulerのエンコーダ予算管理、GPUModelRunnerのエンコーダ実行・キャッシュ・埋め込みマージを含む。

全体フロー

sequenceDiagram
    participant S as Scheduler
    participant ECM as EncoderCacheManager
    participant MR as GPUModelRunner
    participant M as Model

    Note over S: schedule() 実行中
    S->>ECM: check_and_update_cache(req, i)
    alt キャッシュヒット
        ECM-->>S: True（エンコード不要）
    else キャッシュミス
        ECM-->>S: False
        S->>ECM: can_allocate(req, i, budget, scheduled)
        alt 空き/回収可能
            ECM-->>S: True（Eviction実行の可能性あり）
            S->>ECM: allocate(req, i)
            Note over S: scheduled_encoder_inputs[req_id].append(i)
        else 不足
            ECM-->>S: False
            Note over S: num_new_tokens を調整
        end
    end

    Note over S: SchedulerOutput 構築
    S->>MR: execute_model(scheduler_output)

    MR->>MR: _batch_mm_inputs_from_scheduler()
    MR->>M: embed_multimodal(pixel_values)
    M-->>MR: encoder_outputs
    MR->>MR: encoder_cache[mm_hash] = output

    MR->>MR: _gather_mm_embeddings()
    Note over MR: encoder_cache からスライス
    MR->>M: embed_input_ids(ids, mm_embeds, is_multimodal)
    Note over M: masked_scatter_ で text + vision マージ

    MR->>MR: free_encoder_mm_hashes の処理
    Note over MR: encoder_cache.pop(mm_hash)

1. EncoderCacheManager

概要

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:17-267

ビジョンエンコーダの出力（埋め込みテンソル）のライフサイクルを管理する。リファレンスカウント方式でリクエスト間のキャッシュ共有を実現し、遅延Evictionでメモリ効率を高める。

データ構造

主要操作

check_and_update_cache(request, input_id) → bool

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:91-117

1. mm_hash が cached にない → False（キャッシュミス）
2. cached[mm_hash] が空集合（参照なし）→ freeable から除去、num_freeable_slots 減算
3. cached[mm_hash] に request_id 追加 → True（キャッシュヒット）

キャッシュヒット時、エンコーダ計算が 完全にスキップ される。

can_allocate(request, input_id, budget, scheduled) → bool

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:119-178

1. num_embeds > encoder_compute_budget → False（予算不足）
2. total ≤ num_free_slots → True（空きあり）
3. total > num_freeable_slots → False（回収しても不足）
4. total > num_free_slots かつ ≤ num_freeable_slots
   → Eviction 実行: freeable から oldest-first で popitem(last=False)
   → cached から削除、freed に追加
   → num_free_slots 回復 → True

Eviction ポリシー: FIFO順（OrderedDict の挿入順）。最も古い unreferenced エントリを先にEvict。

allocate(request, input_id)

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:180-205

キャッシュスペースを予約（論理的な簿記のみ）。物理メモリの割り当てはGPUModelRunnerで行われる。

free(request)

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:242-253

リクエスト完了時に呼ばれる。全エンコーダ入力の参照を解放。参照セットが空になったエントリは freeable に移動する（物理メモリは解放しない）。

get_freed_mm_hashes() → list[str]

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:255-266

Evictされたmm_hashを返してクリア。SchedulerOutputに含められ、GPUModelRunnerに通知される。

キャッシュ予算の計算

参照: target/vllm/vllm/v1/core/encoder_cache_manager.py:269-316

encoder_compute_budget = max(max_num_encoder_input_tokens, max_tokens_per_mm_item)
encoder_cache_size = max(encoder_cache_size_config, max_tokens_per_mm_item)

• encoder_compute_budget: 1ステップあたりのエンコーダ計算量上限（埋め込み数）
• encoder_cache_size: キャッシュ全体の容量

2. Scheduler のエンコーダスケジューリング

_get_encoder_budget()

参照: target/vllm/vllm/v1/core/sched/scheduler.py:1060-1215

各リクエストのエンコーダ入力をスケジューリングするロジック。mm_features の各アイテムについて:

for i, mm_feature in enumerate(mm_features):
    1. 位置チェック: start_pos + num_encoder_tokens がスケジュール範囲内か
    2. 重複チェック: 同じ mm_hash が既にスケジュール済みか
    3. キャッシュチェック: encoder_cache_manager.check_and_update_cache() → True ならスキップ
    4. チャンクMMチェック: disable_chunked_mm_input の場合、部分スケジュール禁止
    5. 割り当てチェック: can_allocate() → False ならトークン数調整して break
    6. ECConnectorチェック: 外部キャッシュにある場合は external_load_encoder_input に追加
    7. encoder_inputs_to_schedule に追加、予算減算

SchedulerOutput のMM関連フィールド

参照: target/vllm/vllm/v1/core/sched/output.py:207-218

スケジューリングの統合

schedule() のRUNNINGフェーズとWAITINGフェーズの両方で _get_encoder_budget() が呼ばれる:

schedule()
  ├─ encoder_compute_budget = max_num_encoder_input_tokens  # 初期予算
  │
  ├─ RUNNING リクエスト処理
  │   └─ _get_encoder_budget(request, ...)
  │       → encoder_inputs_to_schedule, 調整後の num_new_tokens
  │       → allocate() 実行
  │
  ├─ WAITING リクエスト処理
  │   └─ _get_encoder_budget(request, ...)
  │       → 同上
  │
  └─ SchedulerOutput 構築
      ├─ scheduled_encoder_inputs = {req_id: [input_ids], ...}
      └─ free_encoder_mm_hashes = encoder_cache_manager.get_freed_mm_hashes()

3. GPUModelRunner のエンコーダ実行

encoder_cache

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:439

self.encoder_cache: dict[str, torch.Tensor] = {}

mm_hash をキーとして、エンコーダ出力テンソル（GPU上）を保持する単純なdictキャッシュ。

_batch_mm_inputs_from_scheduler()

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:2250-2291

SchedulerOutput の scheduled_encoder_inputs から、エンコーダに渡すデータをバッチにまとめる。

入力: scheduled_encoder_inputs = {req_id: [input_ids], ...}
出力: (mm_hashes, mm_kwargs, mm_lora_refs)

for req_id, encoder_input_ids in scheduled_encoder_inputs.items():
    for mm_input_id in encoder_input_ids:
        mm_feature = req_state.mm_features[mm_input_id]
        if mm_feature.data is None:  # P0キャッシュヒットで省略された場合
            continue
        mm_hashes.append(mm_feature.identifier)
        mm_kwargs.append((modality, mm_feature.data))

_execute_mm_encoder()

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:2293-2447

1. mm_kwargs をモダリティごとにグループ化（group_mm_kwargs_by_modality）
2. 各グループに対して model.embed_multimodal(**mm_kwargs_group) を実行
3. LoRA tower mapping が必要な場合は事前にセット
4. 出力を encoder_cache[mm_hash] に格納
5. ECConnector があれば maybe_save_ec_to_connector() で外部キャッシュにも保存

バッチ処理: 同一モダリティのアイテムはバッチ実行される。異なるモダリティは別グループとして処理。

_gather_mm_embeddings()

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:2449-2556

スケジュールされたトークン範囲に対応するエンコーダ出力をキャッシュから取得し、マージ用のデータを準備する。

for req_id in input_batch.req_ids:
    for mm_feature in req_state.mm_features:
        1. プレースホルダーの範囲 [start_pos, start_pos + num_encoder_tokens)
        2. スケジュールされた範囲 [num_computed_tokens, num_computed + num_scheduled)
        3. 重複部分を計算 → start_idx, end_idx
        4. encoder_cache[mm_hash] からスライス → mm_embeds_item
        5. is_mm_embed マスクの対応位置を True に設定

チャンクPrefill対応: num_computed_tokens と num_scheduled_tokens に基づいて部分的な埋め込み取得が可能。

出力:

• mm_embeds: list[torch.Tensor] — 全リクエストの埋め込みスライスを連結
• is_mm_embed: torch.Tensor — (total_num_scheduled_tokens,) のboolマスク

統合: _model_forward() 内の処理

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:2756-2777

# 1. エンコーダ実行 + キャッシュ格納
self._execute_mm_encoder(scheduler_output)

# 2. キャッシュから必要な埋め込みを収集
mm_embeds, is_mm_embed = self._gather_mm_embeddings(scheduler_output)

# 3. テキスト + ビジョン埋め込みのマージ
inputs_embeds_scheduled = self.model.embed_input_ids(
    self.input_ids.gpu[:num_scheduled_tokens],
    multimodal_embeddings=mm_embeds,
    is_multimodal=is_mm_embed,
)

embed_input_ids() は内部で masked_scatter_ を使い、is_multimodal=True の位置を mm_embeds で置換する。

エンコーダキャッシュの解放

参照: target/vllm/vllm/v1/worker/gpu_model_runner.py:898-899

for mm_hash in scheduler_output.free_encoder_mm_hashes:
    self.encoder_cache.pop(mm_hash, None)

SchedulerOutput に含まれる free_encoder_mm_hashes に基づいて、GPUメモリ上のテンソルを解放。

4. テキスト推論との差分まとめ

5. キャッシュの3層構造

P0（フロントエンド）          P1（バックエンド/Scheduler）      P1（バックエンド/GPU）
┌────────────────────┐     ┌───────────────────────┐      ┌──────────────────┐
│ ProcessorCache     │     │ EncoderCacheManager   │      │ encoder_cache    │
│ (LRU, mm_hash)     │     │ (RefCount, mm_hash)   │      │ (dict, mm_hash)  │
│                    │     │                       │      │                  │
│ キャッシュ対象:     │     │ キャッシュ対象:        │      │ キャッシュ対象:   │
│ HF処理済みテンソル  │     │ 論理的な存在管理      │      │ GPU上のテンソル   │
│ + prompt_updates   │     │ (容量・参照カウント)   │      │ (エンコーダ出力)  │
│                    │     │                       │      │                  │
│ Eviction: LRU      │     │ Eviction: FIFO        │      │ Eviction:        │
│ (サイズベース)      │     │ (OrderedDict oldest)  │      │ Scheduler指示    │
└────────────────────┘     └───────────────────────┘      └──────────────────┘
        ↓                           ↓                            ↓
  HF処理スキップ            エンコーダ計算スキップ          テンソル再利用

主要ファイル

関連ドキュメント

• フロントエンド MM処理パス
• Gemma3 ビジョンエンコーダ
• GPUModelRunner
• Scheduler
• KVCacheManager

フロントエンド マルチモーダル処理パス [MEDIUM→DEEP(§3)] [VERIFIED]

最終更新: 2026-02-17

APIリクエストに含まれる画像データが、フロントエンドプロセス（P0）でどのように処理され、EngineCoreRequest として ZMQ 経由でバックエンド（P1）へ送信されるかを追跡する。テキスト推論パスとの差分を中心に記述する。

全体フロー

graph TD
    A["API Request<br>(messages + images)"] --> B["ChatTemplate適用"]
    B --> C["InputPreprocessor.preprocess()"]
    C --> D["_process_multimodal()"]
    D --> E["mm_processor.info.parse_mm_data()"]
    E --> F["mm_processor.apply()"]
    F --> G{"ProcessorCache<br>ヒット?"}
    G -->|HIT| H["キャッシュからitem+prompt_updates取得<br>(HF処理スキップ)"]
    G -->|MISS| I["HF Processor実行<br>pixel_values等テンソル生成"]
    I --> J["キャッシュに格納"]
    H --> K["MultiModalInputs 構築"]
    J --> K
    K --> L["InputProcessor.process_inputs()"]
    L --> M["MultiModalFeatureSpec 構築"]
    M --> N["EngineCoreRequest<br>(mm_features)"]
    N --> O["ZMQ IPC 送信"]

1. チャットテンプレートとプレースホルダー

テンプレート適用前後の文字列（Gemma3の例）

適用前（OpenAI形式のメッセージ）:

{
  "messages": [
    {"role": "user", "content": [
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}},
      {"type": "text", "text": "この画像は何ですか？"}
    ]}
  ]
}

チャットテンプレート適用後（テキスト）:

<bos><start_of_turn>user
<start_of_image>この画像は何ですか？<end_of_turn>
<start_of_turn>model

ここで <start_of_image> がプレースホルダートークンとなる。

プレースホルダーの展開

Gemma3ProcessingInfo.get_image_repl() がプレースホルダーを展開する。

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:178

<start_of_image> → processor.full_image_sequence

processor.full_image_sequence はHuggingFace Gemma3Processorが定義する完全なトークン列で、<start_of_image> + image_token × image_seq_length + <end_of_image> の形式。

Pan-and-Scan有効時（複数クロップ）:

"Here is the original image <full_image_seq> and here are some crops to help you see better <full_image_seq> <full_image_seq>"

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:196-211

画像1枚あたりのトークン数

num_tokens = (num_crops + 1) * image_seq_length

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:213-230

• image_seq_length: Gemma3Processorの設定値（典型的に256）
• num_crops: Pan-and-Scan無効時は0、有効時はアスペクト比に基づいて計算（最大 pan_and_scan_max_num_crops）
• よって画像1枚で256〜1280+トークンを消費

トークン列の構造

テキスト推論ではトークン列は純粋なテキストトークンのみ。マルチモーダルでは以下の構造になる:

[BOS] [start_of_turn] [user] [\n]
[start_of_image] [image_token × 256] [end_of_image]    ← 画像プレースホルダー
[テキストトークン列...]                                    ← "この画像は何ですか？"
[end_of_turn] [\n] [start_of_turn] [model] [\n]

image_token の位置がマスクで追跡され（PlaceholderRange）、後にビジョンエンコーダの出力で置換される。

改行トークンの結合処理

Gemma3固有の問題：\n\n\n と \n\n\n\n が単一トークンとして存在する。画像置換テキストに \n\n が挿入されると、隣接する \n と結合が必要。

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:351-385

# _apply_token_matches() でトークンの結合を実行
replace_token_matches(token_ids, [newline_1, newline_2], [newline_3])  # \n + \n\n → \n\n\n
replace_token_matches(token_ids, [newline_2, newline_1], [newline_3])  # \n\n + \n → \n\n\n
replace_token_matches(token_ids, [newline_2, newline_2], [newline_4])  # \n\n + \n\n → \n\n\n\n

2. マルチモーダルデータの処理パイプライン

InputPreprocessor._process_multimodal()

参照: target/vllm/vllm/inputs/preprocess.py:193-232

_process_multimodal(prompt, mm_data, mm_processor_kwargs, mm_uuids)
  1. mm_processor.info.parse_mm_data(mm_data)
     → MultiModalDataItems（モダリティごとに型付きデータアイテムに変換）
  2. mm_processor.apply(prompt, mm_items, ...)
     → MultiModalInputs（トークン列 + テンソルデータ + プレースホルダー位置 + ハッシュ）

BaseMultiModalProcessor.apply()

HFプロセッサ実行、プロンプト更新（プレースホルダー検出・展開）、キャッシュ管理を統合的に処理する。

主な出力（MultiModalInputs）:

• prompt_token_ids: プレースホルダー展開済みのトークン列
• mm_kwargs: dict[modality, list[MultiModalKwargsItem]] — 処理済みテンソルデータ
• mm_hashes: dict[modality, list[str]] — 各アイテムのハッシュ値
• mm_placeholders: dict[modality, list[PlaceholderRange]] — プレースホルダー位置情報

Gemma3MultiModalProcessor._call_hf_processor()

参照: target/vllm/vllm/model_executor/models/gemma3_mm.py:277-310

親クラスのHFプロセッサ呼び出し後、num_patches を追加計算する。HFプロセッサはこの値をpopしてしまうため、vLLM側で再計算が必要。

num_crops = [self.info.get_num_crops(...) for size in image_sizes]
processed_outputs["num_patches"] = torch.tensor(num_crops) + 1  # +1 for original

HFプロセッサの出力:

• pixel_values: (total_patches, 3, image_size, image_size) — 全パッチのピクセルテンソル
• num_patches: (num_images,) — 画像ごとのパッチ数（= num_crops + 1）

3. MMハッシュ [DEEP] [VERIFIED]

マルチモーダル入力の同一性を判定するためのコンテンツベースハッシュ。2つの用途がある:

1. ProcessorCache — HFプロセッサの処理結果キャッシュ（同じ画像の再処理回避）
2. プレフィックスキャッシュのextra_keys — KVキャッシュブロックハッシュ計算時にブロック内のMMトークンを識別

3.1 ハッシュ計算の全体フロー

graph TD
    A["BaseMultiModalProcessor<br>apply() / _cached_apply_hf_processor()"] --> B["_hash_mm_items()"]
    B --> C{"mm_uuids<br>提供?"}
    C -->|"あり + kwargs空"| D["item_uuid をそのまま使用"]
    C -->|"なし or kwargs非空"| E["MultiModalHasher.hash_kwargs()"]
    E --> F["kwargs をキー名でソート"]
    F --> G["iter_item_to_bytes() で再帰的バイト変換"]
    G --> H["serialize_item() で型別シリアライズ"]
    H --> I["hasher.update() に逐次投入"]
    I --> J["hasher.hexdigest() → mm_hash"]

3.2 _hash_mm_items() — ハッシュ入力の構成

参照: target/vllm/vllm/multimodal/processing/processor.py:1300-1364

各モダリティ（画像の場合 "image"）ごとに、アイテム1つずつハッシュを計算する。

MultiModalHasher.hash_kwargs(
    model_id=model_id,         # e.g. "google/gemma-3-27b-it"
    image=item,                # PIL.Image.Image or MediaWithBytes
    **hf_processor_mm_kwargs,  # HFプロセッサに渡すkwargs（PaS設定等）
    **tokenization_kwargs,     # トークナイザkwargs
)

重要: ハッシュ入力は model_id + モダリティ名付きの画像データ + プロセッサkwargs + トークナイザkwargs。同じ画像でもプロセッサkwargsが異なればハッシュが変わる。

mm_uuids による分岐

_hash_mm_items() はアイテムごとに3つのパスを持つ:

2番目のパスは最適化: UUID文字列のハッシュは画像ピクセルのハッシュより高速だが、kwargsとの組み合わせで一意性を保つ必要がある。

get_item_for_hash() — ハッシュ用アイテムの取得

参照: target/vllm/vllm/multimodal/parse.py:118-120

ProcessorBatchItems.get_item_for_hash() は get() と異なり、MediaWithBytes ラッパーを剥がさずにそのまま返す。

# get() → self._unwrap(self.data[index])  → PIL.Image（ラッパー除去）
# get_item_for_hash() → self.data[index]  → MediaWithBytes[PIL.Image]（ラッパー保持）

これにより serialize_item() で元のバイト列（JPEG/PNG等）からハッシュを計算でき、PIL画像のピクセルデコードを回避できる。

3.3 MultiModalHasher.hash_kwargs() — ハッシュ関数本体

参照: target/vllm/vllm/multimodal/hasher.py:154-162

@classmethod
def hash_kwargs(cls, **kwargs: object) -> str:
    hasher = _get_hasher_factory(envs.VLLM_MM_HASHER_ALGORITHM)()
    for k, v in sorted(kwargs.items(), key=lambda kv: kv[0]):  # キー名でソート
        for bytes_ in cls.iter_item_to_bytes(k, v):
            hasher.update(bytes_)
    return hasher.hexdigest()

ハッシュアルゴリズム: VLLM_MM_HASHER_ALGORITHM 環境変数で設定（target/vllm/vllm/envs.py:73,793）

• blake3（デフォルト）: 高速
• sha256 / sha512: FIPS準拠用（政府・企業デプロイメント向け）

3.4 iter_item_to_bytes() — 再帰的バイト変換

参照: target/vllm/vllm/multimodal/hasher.py:134-151

dict/list/tupleを再帰的に展開し、キー名のバイト列 + 値のバイト列 を交互にyieldする。

# 例: image=PIL.Image(mode="RGB", data=...) の場合
# iter_item_to_bytes("image", {"mode": "RGB", "data": <numpy>})
#   → "image.mode".encode() + "RGB".encode()
#   → "image.data".encode() + <numpy raw bytes>

キー名がプレフィックスとして含まれるため、異なるkwargsキーの値が衝突しない（例: model_id の値と image の一部が同じバイト列でも区別される）。

3.5 serialize_item() — 型別シリアライズ

参照: target/vllm/vllm/multimodal/hasher.py:52-131

画像の3つのシリアライズパス

graph TD
    A["serialize_item(obj)"] --> B{"EXIF ImageID<br>UUID?"}
    B -->|Yes| C["UUID.bytes (16バイト)<br>最速"]
    B -->|No| D{"MediaWithBytes?"}
    D -->|Yes| E["original_bytes<br>(JPEG/PNG等エンコード済み)<br>高速"]
    D -->|No| F["mode + np.asarray(obj)<br>(全ピクセル展開)<br>低速"]

3.6 UUIDオーバーライド

キャッシュとプレフィックスキャッシュの両方が無効な場合、コンテンツハッシュの代わりに {request_id}-{modality}-{index} 形式のUUIDを使用する（ハッシュ計算コストの回避）。

参照: target/vllm/vllm/v1/engine/input_processor.py:551-574

3.7 LoRA対応のidentifier

LoRAのtower_connector_loraが有効な場合、同じ画像でもLoRAによって埋め込みが変わるため、identifier に LoRA名をプレフィックスとして付加する。

参照: target/vllm/vllm/v1/engine/input_processor.py:273-289

def _get_mm_identifier(self, mm_hash, lora_request):
    if lora_request is None or not enable_tower_connector_lora:
        return mm_hash
    return f"{lora_request.lora_name}:{mm_hash}"

3.8 mm_hash vs identifier — 2つのハッシュ値の使い分け

3.9 プレフィックスキャッシュでの使用

参照: target/vllm/vllm/v1/core/kv_cache_utils.py:388-444

ブロックハッシュ計算時に、ブロックのトークン範囲にMMプレースホルダが含まれる場合、mm_feature.identifier がextra_keysとして追加される。

def _gen_mm_extra_hash_keys(request, start_token_idx, end_token_idx, start_mm_idx):
    # ブロック範囲とMMプレースホルダ範囲の重なりをチェック
    while curr_mm_idx < len(mm_features):
        mm_feature = mm_features[curr_mm_idx]
        offset = mm_feature.mm_position.offset
        length = mm_feature.mm_position.length
        if end_token_idx > offset:
            extra_keys.append(mm_feature.identifier)  # ★ identifierを追加
            ...

これにより、同じトークン列でも異なる画像が挿入されたブロックは別のハッシュを持つ。逆に、同じ画像（同じidentifier）であればKVキャッシュのプレフィックスヒットが可能。

3.10 Gemma3における具体例

Gemma3は _hash_mm_items() をオーバーライドしていない。BaseMultiModalProcessor のデフォルト実装がそのまま使われる。

ハッシュ入力例:
  model_id = "google/gemma-3-27b-it"
  image = <MediaWithBytes[PIL.Image]>  (元のJPEGバイト列)
  ※ hf_processor_mm_kwargs, tokenization_kwargs は通常空

→ hash_kwargs() 内部:
  sorted keys: ["image", "model_id"]
  1. "image" → iter_item_to_bytes("image", MediaWithBytes)
     → serialize_item() → original_bytes (JPEG/PNGバイト列)
  2. "model_id" → iter_item_to_bytes("model_id", "google/gemma-3-27b-it")
     → "model_id".encode() + "google/gemma-3-27b-it".encode()

→ blake3.hexdigest() → "a1b2c3..." (mm_hash)

Pan-and-Scan（PaS）との関係: PaSによる画像分割はHFプロセッサ内で行われるため、ハッシュ計算の後に実行される。同じ画像 + 同じmodel_id + 同じkwargs → 同じmm_hash（PaS分割後の結果もキャッシュされる）。

4. プロセッサキャッシュ（P0側）

キャッシュタイプの選択

参照: target/vllm/vllm/multimodal/registry.py:284-320

mm_processor_cache_gb <= 0         → None（キャッシュ無効）
IPC非対応 or API process > 1       → processor_only
mm_processor_cache_type == "lru"   → lru（Sender + Receiver）
mm_processor_cache_type == "shm"   → shm（共有メモリ）

4種類のキャッシュ実装

参照: target/vllm/vllm/multimodal/cache.py

P0-P1 キャッシュの整合性

設計の核心: P0とP1のキャッシュは 同一のEviction順序 を維持する。

                 is_cached() × N    get_and_update()
P0: From API ───────────────────> ────────────────> To P1

                get_and_update()
P1: From P0 ───────────────────> To model

• is_cached() はP0キャッシュのみを参照（Eviction順序を変えない）
• get_and_update() は P0 と P1 で順番に呼ぶ必要がある（Eviction順序を同期）
• これにより、P0のキャッシュ状態を見るだけでP1のキャッシュ状態を推定できる（IPC不要）

キャッシュヒット時にスキップされる処理

1. HF Processor実行（画像のリサイズ、正規化、パッチ分割 → pixel_values テンソル生成）
2. テンソルデータのIPC送信（SenderCache/ShmCache 使用時、data=None にしてZMQ転送量削減）
3. プロンプト更新の再計算は常に必要（キャッシュにprompt_updatesが保存されているため計算はスキップだが、取得は必要）

5. EngineCoreRequest への組み立て

MultiModalFeatureSpec 構築

参照: target/vllm/vllm/v1/engine/input_processor.py:627-654

mm_features = []
for modality, idx in sorted_mm_idxs:
    base_mm_hash = decoder_mm_hashes[modality][idx]
    mm_features.append(
        MultiModalFeatureSpec(
            data=decoder_mm_inputs[modality][idx],     # MultiModalKwargsItem | None
            modality=modality,                          # "image"
            identifier=_get_mm_identifier(base_mm_hash, lora_request),
            mm_position=decoder_mm_positions[modality][idx],  # PlaceholderRange
            mm_hash=base_mm_hash,
        )
    )

sorted_mm_idxs は argsort_mm_positions() でプロンプト内の出現順にソートされる。

MultiModalFeatureSpec の構造

参照: target/vllm/vllm/multimodal/inputs.py:337-381

PlaceholderRange の構造

参照: target/vllm/vllm/multimodal/inputs.py:170-240

get_num_embeds() は実際のエンコーダ出力の埋め込み数を返す（is_embed のTrue数、またはlength）。

EngineCoreRequest

参照: target/vllm/vllm/v1/engine/__init__.py:55-101

テキスト推論との差分:

• mm_features: list[MultiModalFeatureSpec] | None — マルチモーダル時に設定される
• prompt_token_ids にはプレースホルダー展開済みのトークン列が入る

ZMQ送信時は msgspec によるバイナリシリアライゼーション。テンソルデータは MultiModalKwargsItem に含まれ、カスタムエンコーダで処理される。

6. キャッシュタイプ別のデータフロー

processor_only（P0完結）

P0: hash → cache miss → HF処理 → cache store(tensor+prompt) → tensor をリクエストに含めて送信
P0: hash → cache hit  → cache get(tensor+prompt) → tensor をリクエストに含めて送信

• テンソルデータは常にZMQ経由で送信される

lru（P0 Sender + P1 Receiver）

P0: hash → cache miss → HF処理 → meta store(size+prompt) → tensor をリクエストに含めて送信
P1: hash → cache miss → tensor を受信 → cache store(tensor)

P0: hash → cache hit  → meta get(prompt) → data=None で送信（テンソル省略）
P1: hash → cache hit  → cache get(tensor)

• キャッシュヒット時は テンソルデータのIPC転送がスキップ される

shm（共有メモリ）

P0: hash → cache miss → HF処理 → 共有メモリに書き込み → data=None で送信
P1: hash → cache miss → 共有メモリから読み取り

P0: hash → cache hit  → data=None で送信
P1: hash → cache hit  → 共有メモリから読み取り（ringバッファ）

主要ファイル

関連ドキュメント

• マルチモーダル処理パイプライン概要
• バックエンド MM処理パス
• Gemma3 ビジョンエンコーダ
• InputProcessor
• データフロー

OutputProcessor

深度: [SHALLOW] 確信度: [VERIFIED] 最終更新: 2026-02-11

概要

OutputProcessorはフロントエンドプロセスで動作し、バックエンド（EngineCore）からZMQ経由で受信したEngineCoreOutputを、ユーザー向けのRequestOutputに変換する。主な処理はインクリメンタルデトークナイズ、停止文字列判定、logprobs処理である。AsyncLLMのoutput_handlerバックグラウンドタスクから呼び出される。

process_outputs() フロー

参照: target/vllm/vllm/v1/engine/output_processor.py:582 (process_outputs)

OutputProcessor.process_outputs(engine_core_outputs)       # L582
  │
  for each engine_core_output:
    │
    ├─ req_state = request_states[req_id]                  # RequestState取得
    │   （abortされていればスキップ）
    │
    ├─ 統計情報更新                                         # L620-622
    │
    ├─ デトークナイズ + 停止文字列判定                       # L637-639
    │   stop_string = detokenizer.update(
    │       new_token_ids, stop_terminated)
    │   → トークン→テキスト変換（インクリメンタル）
    │   → 停止文字列検出時は finish_reason = STOP
    │
    ├─ logprobs処理                                         # L646
    │   logprobs_processor.update_from_output(output)
    │
    ├─ RequestOutput構築                                    # L649-656
    │   req_state.make_request_output(
    │       new_token_ids, finish_reason, stop_reason, ...)
    │   → CompletionOutput + RequestOutput
    │
    ├─ 出力配信                                             # L660-665
    │   ├─ AsyncLLM: req_state.queue.put(request_output)
    │   └─ LLM: request_outputs.append(request_output)
    │
    └─ 完了処理                                             # L668-687
        if finish_reason is not None:
          _finish_request(req_state)
          → リクエスト解放、統計記録

RequestState

参照: target/vllm/vllm/v1/engine/output_processor.py:116 (RequestState)

各リクエストのフロントエンド側状態を保持する。OutputProcessor.add_request()で作成される。

make_request_output()

参照: target/vllm/vllm/v1/engine/output_processor.py:269 (make_request_output)

make_request_output(new_token_ids, finish_reason, ...)
  │
  ├─ FINAL_ONLY モードかつ未完了 → None（出力なし）
  │
  ├─ プーリングモデル → PoolingRequestOutput
  │
  └─ テキスト生成 → RequestOutput
      ├─ _new_completion_output()                          # L377
      │   ├─ detokenizer.get_next_output_text(finished, delta)
      │   │   → DELTAモード: 新規テキストのみ
      │   │   → CUMULATIVEモード: 全テキスト
      │   └─ CompletionOutput(text, token_ids, logprobs, ...)
      └─ RequestOutput(request_id, outputs, finished, ...)

Detokenizer（インクリメンタルデトークナイズ）

参照: target/vllm/vllm/v1/engine/detokenizer.py:30 (IncrementalDetokenizer)

クラス階層

IncrementalDetokenizer (基底・No-op)               L30
└── BaseIncrementalDetokenizer (ABC)                L65
    ├── FastIncrementalDetokenizer                  L169
    │   → HF tokenizersの DecodeStream 使用
    └── SlowIncrementalDetokenizer                  L258
        → detokenize_incrementally() 使用

ファクトリメソッド from_new_request() がトークナイザの種類に応じて適切な実装を選択する。

update() メソッド

参照: target/vllm/vllm/v1/engine/detokenizer.py:65 (BaseIncrementalDetokenizer.update)

update(new_token_ids, stop_terminated) → stop_string | None
  │
  for each new_token_id:
    ├─ token_ids.append(new_token_id)
    └─ output_text += decode_next(new_token_id)  # 抽象メソッド
  │
  └─ check_stop_strings(output_text, ...)         # L316
      → (stop_string, truncate_offset) | None

停止文字列判定

参照: target/vllm/vllm/v1/engine/detokenizer.py:316 (check_stop_strings)

check_stop_strings()は累積テキストの末尾付近で停止文字列を検索する。検出時はテキストをトランケートし、停止文字列と切り詰め位置を返す。include_stop_str_in_outputフラグで停止文字列を出力に含めるか制御する。

LogprobsProcessor

参照: target/vllm/vllm/v1/engine/logprobs.py:28 (LogprobsProcessor)

SamplingParams.logprobs / prompt_logprobs の設定に基づいて初期化される。update_from_output()でEngineCoreOutputからlogprobs情報を抽出し、累積対数確率を更新する。

出力モード（RequestOutputKind）

参照: target/vllm/vllm/sampling_params.py:108 (RequestOutputKind)

AsyncLLMとの連携

AsyncLLM._run_output_handler()                     # async_llm.py:662
  while True:
    outputs = await engine_core.get_output_async()  # ZMQ受信
    for chunk in outputs.outputs:
      output_processor.process_outputs(chunk, ...)  # ← ここで呼ばれる
      → RequestOutputがper-requestキューにpush
      → generate()がキューからyield

上流・下流の関係

• 上流: AsyncLLM（output_handlerタスクから呼び出し）、EngineCoreOutputs（ZMQ経由受信）
• 下流: APIサーバー（RequestOutputをyield）

Phase 2 深堀り候補

• RequestOutputCollectorのキューイング実装
• ストリーミングモード（DELTA）時のテキスト差分計算詳細
• n>1サンプリング時のParentRequest管理

主要ファイル

Scheduler サマリー

深度: [MEDIUM] 確信度: [VERIFIED] 最終更新: 2026-02-11

概要

SchedulerはContinuous Batchingの中核コンポーネントであり、各ステップでどのリクエストにどれだけのトークンを計算させるかを決定する。schedule()メソッドは3フェーズ（RUNNING処理 → WAITING処理 → Output構築）で構成され、トークン予算の範囲内で最大限のリクエストをスケジュールする。Unified Compute Modelを採用し、Prefill/Decodeを明示的に区別せず num_computed_tokens の進捗で統一的に管理する。