Knowledge note
Block Table
The per-request logical-to-physical mapping that tells paged attention kernels which physical KV block holds each logical block of a sequence.
Block Table
Block Table is the per-request mapping from logical KV block index to physical block ID that lets paged attention kernels fetch a sequence’s non-contiguous KV blocks in constant time.
Why It Exists
Paged KV caches store a sequence’s blocks at arbitrary physical addresses. Without a mapping, kernels could not find a logical block cheaply; with one, memory can be allocated on demand, shared across requests, and freed block-by-block without moving data.
How It Works
A request’s KV cache is a list of logical blocks filled left to right. The block table records, for each logical block, the physical block ID and how many slots are filled. Each table entry is fixed-size, so the mapping is dense and cheap to ship to the worker, where it becomes an int32 tensor that the attention kernel indexes as block_table[row][col]. A new row/block is appended only when the previous block fills.
Tradeoffs
The table itself costs a small constant indirection per block per step. If block size is small, tables are long and kernel indirection overhead grows; if block size is large, internal fragmentation grows. Append-only maintenance keeps worker block tables stable across steps but means identical cached blocks are not de-duplicated.
Common Confusions
- Block table vs. slot mapping: The block table maps logical blocks to physical blocks; the slot mapping maps individual scheduled tokens to exact physical slots. Both are passed to the kernel, the latter derived from the former.
- Block table vs. page table: Same idea as OS page tables; block tables are per-request and per-KV-cache-group rather than per-process.
Where It Appears
- vLLM: PagedAttention Serving Framework — Introduces block tables as the vLLM analogue of an OS page table.
- vLLM Block Table Management — How the V1 codebase builds, shares, prefixes-caches, and materializes block tables on the worker.
- vLLM-Ascend Prefill and Decode Scheduling: Qwen3.5 GQA — Shows block tables crossing the scheduler-to-FIA handoff for mixed decode and prompt chunks.
- Triton in Practice: How vLLM and vllm-ascend Use Triton — A codebase-driven tour of Triton kernel development in vLLM (NVIDIA GPU) and vllm-ascend (Ascend NPU), covering infrastructure.
- vLLM — vLLM serving framework pages: PagedAttention paper, continuous batching, and Kimi K3 code.
- vLLM Continuous Batching: Scheduler, KV Blocks, and Runtime Flow — A code-backed explanation of how vLLM rebuilds a token-level batch each engine iteration, mixes prefill and decode work.
- vLLM Architecture and Code Organization Overview — A top-down code-reading map of the vLLM repository at commit a0c092ee72c0: how the V1 serving engine, model executor, config.
- vLLM DCP and PCP: Decode and Prefill Context Parallelism — DCP scales attention block size while PCP retains global block ownership.
Related Terms
- PagedAttention — The attention algorithm that consumes block tables.
- KV Cache — The data the block table addresses.