TensorRT-LLM 源码完全拆解（二十七）：序列槽位与资源管理器——一个请求的座位、它背后的块，以及一次释放的回收顺序

BaseResourceManager 的六个钩子

执行器不直接和 KVCacheManager 或 SeqSlotManager 打交道，它只认识抽象基类 BaseResourceManager。基类里有两个抽象方法和四个可选的钩子：

1
class BaseResourceManager(ABC):
2
    @abstractmethod
3
    def get_max_resource_count(self) -> int:
4
        """Return the maximum number of real requests this manager can admit."""
5
        raise NotImplementedError
6

7
    @abstractmethod
8
    def get_needed_resource_to_completion(self, request: LlmRequest) -> int:
9
        raise NotImplementedError
10

11
    def get_request_kv_block_budget(self, request): ...   # 默认 None
12
    def kv_block_budget_applies(self) -> bool: ...        # 默认 False
13
    def add_dummy_requests(self, request_ids): pass
14
    def prepare_resources(self, scheduled_batch): pass
15
    def update_resources(self, scheduled_batch): pass
16
    def free_resources(self, request): pass
17
    def shutdown(self): pass

这两个抽象方法的语义差异很关键。get_max_resource_count 回答的是「我最多能同时容纳多少条请求」，对 KV 管理器它返回的是块数（self.impl.max_num_blocks），因为它是按「块」这个资源计量；对 SeqSlotManager 它返回的是座位数。get_needed_resource_to_completion 回答的是「跑完这条请求我还需要多少资源」，调用方是调度器做准入判断。

KVCacheManager.get_needed_resource_to_completion 的实现值得单独看一眼，因为它暴露了 Python 调度器与 C++ 调度器的一个历史分歧：

1
def get_needed_resource_to_completion(self, request: LlmRequest) -> int:
2
    # TODO: the C++ implementation of this method can be used, but the
3
    # Python and C++ schedulers currently do not agree on what "needed
4
    # resource to completion" means. The C++ one excludes already allocated
5
    # blocks; the Python one includes them.
6
    # ... This intentionally uses beam_width=1 to preserve the historical
7
    # beam-unaware value the Python scheduler expects.
8
    return self._num_blocks_to_completion(request.orig_prompt_len,
9
                                          request.max_new_tokens,
10
                                          beam_width=1)

注释说得很清楚：C++ 口径是「还需要多少」，Python 调度器期望的是「总共多少」，两者对同一字段的解释不同，所以这里固定用 beam_width=1，保持 Python 调度器熟悉的「不考虑 beam 的旧口径」。这提醒我们：读执行器源码时，不能把「资源管理器提供数字」误当成「数字含义在所有路径上都一致」，同一个接口名在不同后端里可以有不同的语义约定。

至于 add_dummy_requests，它只在 KV 管理器与 speculative 资源管理器上被真正实现；SeqSlotManager 没有覆盖它，也就是座位池不为 dummy 预热。这个细节后面会用到。

ResourceManager：一个有序字典

所有具体管理器被装进一个 ResourceManager 复合对象，内部是一个 OrderedDict[ResourceManagerType, BaseResourceManager]。类型枚举一共七个：

1
class ResourceManagerType(enum.Enum):
2
    KV_CACHE_MANAGER = "KV_CACHE_MANAGER"
3
    DRAFT_KV_CACHE_MANAGER = "DRAFT_KV_CACHE_MANAGER"
4
    CROSS_KV_CACHE_MANAGER = "CROSS_KV_CACHE_MANAGER"
5
    PEFT_CACHE_MANAGER = "PEFT_CACHE_MANAGER"
6
    SEQ_SLOT_MANAGER = "SEQ_SLOT_MANAGER"
7
    SPEC_RESOURCE_MANAGER = "SPEC_RESOURCE_MANAGER"
8
    KV_CACHE_COMPRESSION_MANAGER = "KV_CACHE_COMPRESSION_MANAGER"

复合对象本身不实现业务逻辑，只负责按顺序遍历。prepare_resources 是正序遍历，free_resources 是 reversed(...) 反序遍历：

1
def prepare_resources(self, scheduled_batch, *, publish_connector_output=True):
2
    for _, resource_manager in self.resource_managers.items():
3
        resource_manager.prepare_resources(scheduled_batch)
4
    # After every manager, so context_current_position / context_chunk_size
5
    # are final. See maybe_fit_token_budget.
6
    self.maybe_fit_token_budget(scheduled_batch)
7
    ...
8

9
def free_resources(self, request: LlmRequest):
10
    for resource_type, resource_manager in reversed(self.resource_managers.items()):
11
        resource_manager.free_resources(request)

正着申请、反着释放，是资源管理里最常见的纪律，原因在「释放顺序」一节展开。这里先记住一点：OrderedDict 的次序不是构造时随手写的，构建函数 create_py_executor_resources 在最后显式把 KV 管理器、cross-KV 管理器、压缩管理器 move_to_end 到队尾，确保它们在 prepare 里最后跑、在 free 里最先跑。

为什么 KV 管理器必须最后 prepare

prepare_resources 在所有管理器跑完之后还有两步，这两步解释了「KV 管理器为什么排最后」：

1
    self.maybe_fit_token_budget(scheduled_batch)
2
    # Strictly after the trim: the connector is told how many tokens the
3
    # forward pass will compute, which is only settled once the trim has run.
4
    if publish_connector_output and hasattr(kv_cache_manager, "report_batch_to_connector"):
5
        kv_cache_manager.report_batch_to_connector(scheduled_batch)

maybe_fit_token_budget 在 KVCacheManager 里实现，作用是把超出 max_num_tokens 的 context chunk 当场裁短。它必须等到所有管理器都跑完才有意义，原因是微批调度器准入时用的 token 数是「估算的可复用 token」（estimated_reusable_tokens，来自前缀树的猜测），而真正复用了多少要等 addSequence 执行时才确定（prepopulated_prompt_len）。两者不一致的典型场景，就是估算说「这一段前缀能复用」，实际块表里只命中了一部分，于是本批真实前向的 token 数比预算多。只有在 prepare_resources 末尾，context_current_position 与 context_chunk_size 都是最终值，才能算出差额并裁短。

裁短安全的前提是「只缩不放」：没有任何请求被移出批次，所以此前各管理器为这条请求记录的 per-request 状态、attention-DP 的 _can_queue 投票、PP 的 inflight 集合都仍然与批次一致。如果这里改成「把超预算的请求踢出去」，那些已经为它分配了座位的管理器就必须回滚，复杂度会高一个量级。这也是一个值得记住的设计取舍：在流水线的末端做「缩小」比在末端做「移除」便宜得多。

report_batch_to_connector 则把最终要前向的 token 数告诉 KV connector（P/D 分离场景下负责跨实例搬运 KV 的组件）。它同样必须等裁剪结束，否则传输侧会按裁剪前的数字做预算。

边界一：重复申请只有 dummy 能例外

add_slot 遇到已经存在的 request_id，只有当它是 CUDA Graph 的 dummy 请求时才允许「幂等返回」，其余情况直接断言失败。这个例外来自一种真实的调用模式：同一个 dummy id 会在不同批次、不同 draft 长度的补齐路径上被反复申请，每次都新建映射就会把座位号泄漏，因为 remove_slot 只能移除一次。断言则是反向的保护：如果一条真实请求被重复申请座位，说明执行器在释放前又调度了它，这必然是状态机的 bug，与其静默覆盖映射，不如立刻崩掉。

边界二：没有空闲座位时抛 NoFreeSlotsError 而不是返回 None

NoFreeSlotsError 是 ValueError 的子类，名字是「seat」语义的直接延续（源码里的 NoFreeSlotsError 注释写的是 A slot-backed resource manager has no capacity for another request.）。它被 CUDA Graph 补齐路径专门捕获：

1
try:
2
    ...
3
    spec_res_mgr.add_dummy_requests([dummy_request_id])
4
    ...
5
except NoFreeSlotsError:
6
    rollback()
7
    return None
8
except Exception:
9
    rollback()
10
    raise

补齐 dummy 需要 KV 块，也需要 speculative 资源管理器的槽位；如果槽位不够，补齐应该「放弃补齐」，让这一步退回 eager 模式，而不是让整个执行器挂掉。rollback() 会对所有已登记的管理器反向 free_resources(dummy_request)，把已经分配出去的那部分资源还回去。这种「分配失败必须能整体回滚」的模式，与数据库事务是同一个思路：一个请求横跨多个资源管理器，只要有一个拒绝，前面成功的都得撤销，否则会留下半截状态。

边界三：shutdown 的断言是记账自检

1
def shutdown(self):
2
    req_ids_list = list(self.slot_mapping.keys())
3
    for rid in req_ids_list:
4
        self.remove_slot(rid)
5
    assert len(self.slot_mapping) == 0 and len(self.free_slots) == self.max_num_requests

最后那行断言等价于「所有座位都回到了空闲集合」。它在进程退出时运行，是座位池记账的自检：如果之前某条路径把座位取走了却忘了还，这里会直接暴露，而不是等到下一次复用同一个请求 id 时才出现莫名其妙的采样错乱。对这类薄记账结构，退出时做一次守恒检查成本几乎为零，收益却很高。

发放条件：只在「还没有座位」时发

prepare_resources 对批次里每条请求检查 seq_slot is None，只在请求还没有座位时调用 add_slot。这个条件不是性能优化，而是正确性要求：同一条请求会在很多个迭代里被重复调度（每解码一个 token 就是一个迭代），prepare_resources 每个迭代都会对整批请求跑一遍。如果每轮都无条件申请，第二次就会撞上 add_slot 的重复申请断言。

seq_slot 和 py_seq_slot 是两个字段。seq_slot 是绑定到 LLMEngine 那一侧的编号，py_seq_slot 是 PyTask/PyExecutor 这一侧的镜像。分配时两者同时写，正是为了让两条路径在第一个迭代就一致。两者也会出现分歧，最典型的是 P/D 分离：py_executor.py 里有三处注释写着「init_disagg_gen_requests 必须在引擎前向之前执行，因为前向会更新 prev_seq_slot」，意思是生成侧第一次前向会把引擎侧的 prev_seq_slot 换成新的座位号，而 PyTask 一侧的 py_seq_slot 不会自动跟着变。如果采样器在同步完成之前就按 py_seq_slot 去读 new_tokens，读到的就是旧的（甚至是上一条请求的）那一行。这也是生成侧初始化时先不发座位、等传输完成标记置位再发的原因之一：让发号与首次使用尽可能贴近。

get_needed_resource_to_completion 返回常数 1，含义是「一条请求永远只占一个座位」。这让调度器可以非常简单地把座位当作「一个人一个位子」的约束来计算，不必像 KV 那样按 prompt 长度和生成长度估块数。

第一个分支处理的是 P/D 分离场景下的 DISAGG_GENERATION_INIT 状态：这是一个「生成侧初始化、但还没真正拿到 KV」的中间态，此时不给它分配座位，等 KV 传输完成的标记 is_disagg_generation_transmission_complete 置位后再发。这样做的动机是座位需要索引采样器的持久状态（见下文），而传输完成前生成行还不存在，提前占座只会让座位在等待网络传输的这段时间里被白白锁住。

副作用：第一条排进队的请求在这里打时间戳

if llm_req.return_perf_metrics: llm_req.set_first_scheduled_time() 这行容易被忽略。first_scheduled_time 是性能指标里「请求从进入执行器到第一次被调度」的延迟，它的起点正是「拿到了座位」这一刻。把打点放在这里，比放在调度器出口更准确，因为调度器出口还有 _can_queue 投票、connector 预留等可能把本批撤销的步骤；座位发放发生在 prepare_resources 里，而 prepare_resources 只在 can_queue 为真时才被调用（_step 里先是 _can_queue，通过了才准备资源）。也就是说，「拿到座位」与「这一批确实会执行」在同一时刻发生，用它作为延迟指标起点，不会把被撤销的批次计入。

座位被谁使用：采样器里那些「按座位寻址」的数组

座位号到底进了哪些数组？在 sampler/sampler.py 的 TorchSampler 里可以找到最直观的答案。构造函数里有这样一组合约：

1
self.max_num_sequences = args.max_num_sequences
2
self.dummy_slot_row = self.max_num_sequences
3
self.NEW_TOKENS_SHAPE = (self.max_tokens, self.max_num_sequences + 1, self.max_beam_width)
4
self.CACHE_INDIRECTION_SHAPE = (self.max_num_sequences, self.max_beam_width, self.max_seq_len)
5
self.LOGPROBS_SHAPE = (self.max_num_sequences, self.max_beam_width, self.max_tokens)

new_tokens 的形状是 (max_tokens, max_num_sequences + 1, max_beam_width)，多出来的那一行就是 dummy_slot_row。源码给出的理由是：

1
# One row past the real sequence slots. CUDA graph padding rows own no
2
# slot, but the captured graph scatters a token for every row it
3
# replays, so they need a destination that belongs to nobody: every
4
# index in range(max_num_sequences) is owned by some request, and the
5
# overlap scheduler reads a slot's row back as that request's next input
6
# token. Mirrors the spec path's dummy_slot_row.

这里把两个边界叠在了一起。第一，CUDA Graph 捕获的采样步骤会「对每一行都散写一个 token」，补齐出来的行也不可避免。第二，在 overlap scheduler 下，采样（第 i 步）发生在 update_requests（第 i-1 步）之前，主机侧还没把采样结果折回请求，于是它会把 new_tokens[slot] 这一行直接当作该请求的下一步输入 token 读回来。如果补齐行落在某个真实座位号上，就会把一条真实请求的下一输入悄悄篡改。所以必须留一行「谁都不拥有」的 scratch 行。

随座位号一起分配的持久状态还有：self._pending_steps = [0] * self.max_num_sequences（每个座位上有几个采样步还没折回）、TopPDecayHandler(self.max_num_sequences)、SlotSamplingParams(self.max_num_sequences + 1)、FinishReasonsHandler(max_num_sequences=...)。它们共同满足一条不变量：除了 new_tokens 多一行 scratch，其它数组的座位维必须完全一致。构造函数里有一行断言专门守住它：

1
assert (
2
    new_tokens_shape[0] == finish_reasons_shape[0]
3
    and new_tokens_shape[1] == finish_reasons_shape[1] + 1
4
    and new_tokens_shape[2] == finish_reasons_shape[2]
5
), f"{new_tokens_shape} is not {finish_reasons_shape} plus a scratch slot row"

如果把座位池想成「一排寄存柜」，那么每个柜子里预置了采样器要用的本子（待折回的步数、Top-P 衰减状态、采样参数、结束原因）；KV 块则是另一套按块租用的大仓库。座位池的尺寸就是柜子数，而柜子数不对，先坏掉的往往是采样而不是注意力。

另一个按座位寻址的池：mRoPE 的 delta 缓存

多模态模型 Qwen2-VL / Qwen3-VL 使用 mRoPE，位置被拆成时间、高、宽三个轴。每个请求需要一个「位置增量 delta」，执行的时候要按座位号把 delta 读出来。CUDA Graph 捕获时不能读一个真实请求的 delta，所以 cuda_graph_runner.py 为它准备了专门的座位：

1
def get_mrope_dummy_seq_slot(max_num_tokens: int, pp_size: int) -> int:
2
    """Cache slot index reserved for MRoPE dummy/no-delta requests."""
3
    return max_num_tokens * pp_size

这个号是 max_num_tokens * pp_size，也就是「座位池之外的第一行」。为什么它能放在池外？因为 mRoPE 的 delta 缓存本身不是按 compute_max_num_sequences 分配的，它按 max_num_tokens * pp_size + 1 分配、按 py_seq_slot 索引，依赖 max_batch_size <= max_num_tokens 才能保证真实座位号不越过它。这直接引出了下一节的核心问题：座位池的尺寸到底按什么算。

为什么 PP 要乘 pp_size

流水并行把模型层切成 $P_{\text{pp}}$ 段，同一时刻每一段上都有不同的微批在跑。一个批次在某一 rank 上做前向时，前一个微批可能还在下一段上执行，后一个微批已经在上游被组装。座位号是全局编号，采样器、mRoPE 缓存等池在每个 rank 上都按同一套编号分配，因此池必须能同时容纳「所有可能同时在飞的微批」里的请求。乘 pp_size 是把这段流水里的最大重数算进去。

注意这里没有用 max_batch_size * pp_size 之外的额外系数，也没有把 attention-DP 的复制算进去：attention DP 的每个 rank 各自有独立的座位池，编号在 rank 内自洽，不需要跨 rank 唯一。只有 PP 不同——PP 切的是层，不是请求，请求会穿过所有 PP rank，所以座位编号必须在 rank 间是同一套。

overlap headroom：为什么普通场景下要额外多一倍的座位

默认 enable_overlap_headroom=False，非 PP 时座位池就是 max_batch_size。但开启 overlap scheduler 后会有一个微妙的问题，should_enable_overlap_headroom 的 docstring 讲得很清楚：

1
True only where a retiring request and the replacement that took its place
2
can own a seat at the same time: non-PP, overlap-on, V2 and non-hybrid.
3

4
Under the overlap scheduler a request that emitted its last token keeps its
5
seat until the next iteration's ``_process_previous_batch``, which runs
6
after that iteration has already admitted new work. Admission excludes such
7
retiring requests whenever this gate is on (``ADPRouter`` on the
8
attention-DP path, ``_fetch_new_requests`` otherwise), so the replacement
9
cohort needs seats of its own. Without the extra micro-batch, a workload
10
whose requests retire after one iteration -- a context server, where every
11
request finishes in its prefill step -- can only refill the seats the
12
previous iteration did not use, and runs at roughly half its batch.

把这段话拆成时序会更容易理解。设第 $i$ 个迭代：

1. 调度器挑出新请求，prepare_resources 给它们发座位；
2. 前向执行；
3. 采样得到 token；
4. _process_previous_batch 处理第 $i-1$ 批的采样结果，把已经产出结束 token 的请求标记完成。

overlap 的含义是「第 3 步和第 4 步不互相等待」：第 $i$ 步的采样在 _process_previous_batch 之前就跑了。于是第 $i-1$ 批里一条已经结束的请求，它的座位要到第 $i$ 步末尾才被释放，但第 $i$ 步开始时调度器已经又放进了一批新请求。如果座位池刚好只有 max_batch_size 个，新请求就只能填「上一轮没用到的那些座位」，而那些「已经结束但还没被回收」的座位仍然被占着。

对一个 context server（每条请求在 prefill 这一步就结束）这种极端负载，结果就是每轮只能填一半的座位，批大小掉到约一半。这正是源码注释里 runs at roughly half its batch 的来源。多留一个微批的座位（2 倍），等于是给「退役中」和「新上任」两个群体各留一套座位，重叠才真正生效。

为什么两类模型不能加这个 headroom

should_enable_overlap_headroom 的返回值是三个条件的与：

1
if is_hybrid or has_mrope_delta_cache or not kv_cache_manager_is_v2:
2
    return False
3
return not mapping.has_pp() and not disable_overlap_scheduler

is_hybrid 指混合模型（注意力层 + Mamba/RWKV 之类的线性注意力层）。原因是 MambaCacheManager 自己按 max_batch_size * pp_size 推容量，并不读 compute_max_num_sequences；座位池翻倍后，Mamba 的状态池仍按旧尺寸分配，第一批多出来的座位就会越界。

has_mrope_delta_cache 指 Qwen2/2.5-VL 与 Qwen3-VL。它们按 py_seq_slot 索引一块 max_num_tokens * pp_size + 1 大小的 delta 缓存，依赖 max_batch_size <= max_num_tokens 保证真实座位号不越界；多出来的那一行是预留的 dummy 槽位。座位池翻倍后，先会「别名」到那一行 dummy（补齐请求读到了真实请求的 delta），再往后就直接越过数组末尾。

这两个例子说明一件事：座位池并不是一个孤立数组，它是若干「按座位号索引的池」的共同长度契约。只要有一个池的容量不是由同一个公式推出来的，放大座位池就会破坏不变量。 因此 headroom 做成了显式开关，并且由启动期检查兜底：

1
def validate_seq_slot_pool_covers_admission(max_num_sequences: int, kv_cache_manager) -> None:
2
    """Fail at startup if the KV index pool cannot cover the seat pool.
3

4
    The check is one-sided on purpose: an index pool narrower than the seat pool
5
    silently defers admitted requests, while a wider one is legitimate.
6
    """
7
    admissible = getattr(kv_cache_manager, "max_admissible_sequences", None)
8
    if not isinstance(admissible, int):
9
        return
10
    if admissible >= max_num_sequences:
11
        return
12
    raise ValueError(
13
        f"... can lease KV cache indices for {admissible} concurrent sequences "
14
        f"but the executor's sequence-slot pool holds {max_num_sequences}: ... "
15
        "(nvbug 6627795). The seat pool must come from "
16
        "_util.compute_max_num_sequences and the index pool must cover it; a "
17
        "shortfall means one of them was re-derived from max_batch_size.")

检查是单向的：索引池比座位池大是合法的（浪费一点内存），比座位池小则一定是 bug。原因写在报错信息里——如果索引池更小，准入时「通过了座位检查、却拿不到 KV 索引」的请求会被一条条静默延后（每次调度都只能退回队列），表现为吞吐诡异下降而不是明确报错。启动期直接失败，比线上慢慢劣化好得多。报错文案最后一句还点出了根因模式：两个池里有一个是从 max_batch_size 重新推导的，而不是统一走 compute_max_num_sequences。

座位池与调度器容量：那个 +1

构建资源时还有一段相关代码：

1
scheduler_capacity = max_batch_size * mapping.pp_size
2
if scheduler_capacity == 1 and mapping.enable_attention_dp and kv_cache_manager:
3
    scheduler_capacity += 1

这是调度器的容量，不是座位池的容量。容量为 1 且开启 attention DP 时，需要给 attention-DP 的 dummy 请求留一个额外的调度位置，否则 DISAGG_GENERATION_INIT 状态的请求会一直卡在调度器里：唯一的调度位被 dummy 占了，真正的请求永远排不进来。注意它加的是调度器容量，而座位池并不为 dummy 发号——dummy 在采样器里用的是 dummy_slot_row，不占真实座位。这两个数字容易混淆，但服务的是不同对象。

座位池尺寸进了哪些下游

max_num_sequences 会被传给 TorchSampler 的 Args、FinishReasonsHandler、TopPDecayHandler、SlotSamplingParams；模型引擎在 _init_from_model 里也按同一个公式算出 max_num_seq_slots，并把它作为 num_seq_slots 交给 C++ 侧的 DecoderRunnerConfig。create_py_executor_resources 里的 resolve_max_num_sequences 则遵循「显式参数优先、其次读引擎已公布的 max_num_seq_slots、最后才重新计算」的顺序，避免两处各算一遍算出不同数字。换句话说，座位池尺寸一变，采样器、执行器资源、解码 runner 几处都要同时跟上；这也是为什么改这个公式时必须同时看 should_enable_overlap_headroom 里的两个排除项。

一次释放其实分两层：先采样器，再资源管理器

执行器释放一条请求的执行资源，走的是 _free_request_resources：

1
def _free_request_resources(self, request: LlmRequest) -> None:
2
    """Release execution resources without removing response routing."""
3
    connector = getattr(self, "kv_connector_manager", None)
4
    if (self.enable_attention_dp and connector is not None
5
            and connector.has_pending_transfers(request.request_id)):
6
        self._kv_connector_fail(...)
7
    self.sampler.release_request(request)
8
    self.resource_manager.free_resources(request)
9
    self._prefetched_request_ids.discard(request.py_request_id)
10
    self.disagg.forget_request(request.py_request_id)
11
    for engine in (self.model_engine, self.draft_model_engine):
12
        release = getattr(getattr(engine, "model", None),
13
                          "release_request_state", None)
14
        if release is not None:
15
            release(request.py_request_id)

采样器先于资源管理器释放，Sampler.release_request 的 docstring 一句话点明顺序：

1
"""Release sampler-owned state before the request's slot is returned."""

这是「反向依赖」的典型写法。座位号本身只是整数，被 FinishReasonsHandler、TopPDecayHandler 之类按座位索引的状态对象使用。释放顺序必须保证：当座位号被归还、可能立刻被另一个请求用掉时，没有任何旧状态还挂在这个号上。 想象先还座位、后清理采样器状态：新请求拿到同一个号，采样器里属于旧请求的结束原因、Top-P 衰减计数还没清掉，新请求的第一步就会读到脏数据。先清状态、再还号，座位号在被重新发放时一定是干净的。

release_request 在 TorchSampler 里只做一件事：self._finish_reasons_handler.release_request(request)；基类里其它子类可以有不同实现。这样一个「先清谁」的纪律被写进了基类接口，而不是散落在执行器各个分支里。

复合对象的反向遍历

资源管理器内部的顺序是 reversed(...)。为什么需要反着？看构建函数里的排序就能理解：

1
# KV cache manager runs last (others may depend on it), except the
2
# compression manager which reconciles after it (below).
3
if kv_cache_manager is not None:
4
    resource_manager.resource_managers.move_to_end(
5
        ResourceManagerType.KV_CACHE_MANAGER, last=True)
6
if cross_kv_cache_manager is not None:
7
    resource_manager.resource_managers.move_to_end(
8
        ResourceManagerType.CROSS_KV_CACHE_MANAGER, last=True)
9
if ResourceManagerType.KV_CACHE_COMPRESSION_MANAGER in resource_manager.resource_managers:
10
    resource_manager.resource_managers.move_to_end(
11
        ResourceManagerType.KV_CACHE_COMPRESSION_MANAGER, last=True)

prepare 的正序是「先轻后重」：座位、LoRA、speculative 这些便宜的先拿到，KV 管理器最后跑，因为它要等前面所有管理器确定这一批的真实形状；压缩管理器排更后，因为它依赖 KV 管理器已经分配好物理页，才能做「冷页编码」这类事后处理。

free 的反序于是变成「先重后轻」：压缩管理器先归还页级状态，KV 管理器再释放块，最后才轮到 SeqSlotManager 把座位还回去。这个顺序保证了一件很实际的事——在 KV 块被释放、块表被改写的那一刻，请求的座位号仍然有效，于是任何需要「按座位号找到这条请求」的清理逻辑（比如日志、性能打点、按 request id 做映射的回调）都不会拿到一个已经被复用给别人的座位号。

抢占路径上的一条注释：不能只暂停

V2 KV 管理器的抢占（preemption）有一条特殊路径：

1
if not self.kv_cache_manager.try_complete_preemption(request):
2
    return False
3
# The same teardown an immediate recompute pause does. Pausing alone
4
# would clear py_seq_slot while SeqSlotManager still owned the slot,
5
# and the next schedule would trip its assertion.
6
self._free_request_resources(request)
7
self._pause_recompute_request(request)
8
return True

注释里描述了一个很具体的 bug 形态：抢占时如果只做「暂停」（把请求挂起、清空 py_seq_slot，等待稍后重新 prefill），座位并没有被 SeqSlotManager 收回；下一次调度这条请求时，prepare_resources 看到 seq_slot is None，就会再次向 SlotManager.add_slot 申请同一个 request_id。add_slot 对非 dummy 的重复申请会断言失败——因为映射里已经有这个 id，而代码只允许 CUDA Graph dummy 幂等。于是整个执行器崩溃。

修法是「走完整的释放路径」：先 _free_request_resources（采样器状态 + 资源管理器，含座位归还），再 _pause_recompute_request。这里有个顺序细节：如果先 pause 把 py_seq_slot 清掉，再走释放，SeqSlotManager.free_resources 仍然按 request_id 去 remove_slot，能正确归还；但如果在别处先清 seq_slot（引擎侧的编号），采样器就会在释放前读到 None，assert request.py_seq_slot is not None 之类的地方会先炸。所以「先释放、后暂停」不是风格问题，而是字段生命周期决定的唯一安全顺序。

一条请求从进队到回收的完整资源时序

把上面几节串起来，一条普通解码请求的资源账大致是：

这张表的重点是第二列与第四列的先后：座位先于 KV 块拿到，后于 KV 块归还。座位是「这条请求存在过」的最早证据，也是「这条请求已经结束」的最后证据。

顺带一提，update_resources 这一步会把本批各请求新分配的块写进注意力元数据，并给 KV 管理器一个机会在不跳过的前提下更新。ResourceManager.update_resources 里对 KV 管理器做了特殊处理：

1
if resource_type == ResourceManagerType.KV_CACHE_MANAGER:
2
    if skip_kv_cache_manager:
3
        continue
4
    resource_manager.update_resources(scheduled_batch, attn_metadata, kv_cache_dtype_byte_size)
5
else:
6
    resource_manager.update_resources(scheduled_batch)

skip_kv_cache_manager 的用途是某些路径（例如已经单独更新过 KV 元数据的场景）不重复跑一遍。其它管理器比如 speculative 资源管理器只收 scheduled_batch，因为它们的更新内容不依赖注意力元数据。这种「只有需要元数据的管理器才收元数据」的签名差异，是读执行器时需要留意的细节：接口形状本身就编码了依赖关系。

补齐行为什么没有座位

回到 TensorRT-LLM。CUDA Graph 补齐会构造一条 dummy 请求，它要拿 KV 块，却不拿座位：SeqSlotManager 没有实现 add_dummy_requests，所以 dummy 的 seq_slot 始终是 None。这不是遗漏，而是有意为之：

• 采样器为补齐行准备了 dummy_slot_row = max_num_sequences 这一行 scratch，所有补齐行都写到同一行，写脏了也无所谓；
• mRoPE 有自己预留的 max_num_tokens * pp_size 号 dummy 座位，同样在真实座位池之外；
• 如果 dummy 也占一个真实座位，那么在「座位刚好用满」的边界上，补齐就会因为 NoFreeSlotsError 失败，进而让整个解码步骤退回 eager——而补齐本来就是为了避免 eager。

所以规则是：真实请求占真实座位，补齐行走池外的 scratch 行。 两者的生命周期完全不同：真实座位随请求走，scratch 行随进程走，只分配一次，永不归还。

坑一：座位泄漏表现为「越跑越慢，最后拒绝服务」

如果某条路径取走座位却没有归还，free_slots 会单调变少。由于座位池大小等于 max_batch_size 乘以微批数，泄漏几个座位不会立刻出错，只会让调度器可用的并发上限缓慢下降；等到空闲集合耗尽，add_slot 开始抛 NoFreeSlotsError。从外部看，就是吞吐逐步下滑、最后新请求全部失败。

定位方法是看 SlotManager.slot_mapping 的大小是否等于「当前活跃请求数」。这个映射本身是纯 Python 的 dict，可以直接打日志；更省事的办法是在 shutdown 之前打印一次，和 max_num_requests - len(free_slots) 对照。源码在 shutdown 里已经做了守恒断言，但那只在进程退出时触发，线上更常见的是「泄漏但不退出」。

坑二：重复发号触发断言，多半是暂停/抢占路径漏了释放

add_slot 对非 dummy 的重复申请直接断言。线上如果真的崩在这里，通常不是 SlotManager 的问题，而是某条「把请求挂起、稍后重来」的路径只清了 py_seq_slot 却没有走 free_resources。前面引用过的那条注释就是这类 bug 的修复记录。排查时可以顺着 _pause_recompute_request 与 try_complete_preemption 的分支看，确认每条「暂停」路径都配了一次 _free_request_resources。

坑三：座位池比 KV 索引池大，表现为「准入成功但一直不执行」

这正是 validate_seq_slot_pool_covers_admission 要防的情况。V2 KV 管理器如果按 max_batch_size 重新推导了自己的 max_admissible_sequences，而座位池按 compute_max_num_sequences 算出了更大的值（比如开启了 overlap headroom），那么两者之间就有一条「座位有、KV 索引没有」的缝隙。落在这条缝隙里的请求会被准入、然后在拿 KV 索引时被一条条延后，看起来像调度器卡住。启动期的 ValueError 会把这种问题在第一时间暴露出来。

坑四：把 dummy_slot_row 当成真实座位读

采样器的 new_tokens 有 max_num_sequences + 1 行，最后一行是 scratch。任何新增的代码如果按「行号 < new_tokens.shape[1]」去遍历，就会把 scratch 行算进去；如果又恰好按行号去某张按座位大小的表里取值，就会越界。源码用一行断言把「new_tokens 只比 finish_reasons 多一行」这个不变式钉死，新增按座位索引的缓冲时，最好也把它加进这行断言。

坑五：在 P/D 生成侧过早使用 py_seq_slot

DISAGG_GENERATION_INIT 状态下不发座位，等 is_disagg_generation_transmission_complete 置位后才发。如果自定义代码在传输完成前就按 py_seq_slot 去访问采样器状态，读到的会是 None 或上一轮的旧号。调试这类问题时，打印 request.seq_slot、request.py_seq_slot、request.is_disagg_generation_init_state 三个字段，往往比读完整条链路更快定位。

怎么验证自己的理解

如果想动手验证「座位池尺寸」这条主线，可以做一个很小的实验：把 max_batch_size 固定为 8，分别运行 disable_overlap_scheduler=True 与 False，打印 max_num_seq_slots 与采样器的 NEW_TOKENS_SHAPE。前者应该看到 8，后者在满足 headroom 条件时应该看到 16。再换一个 Mamba 混合模型，会看到即使开了 overlap，座位池仍然停在 8——因为 is_hybrid 把 headroom 关掉了。三个数字对照，就能把本节讲的「公式 + 三个排除条件」落到具体输出上。

与前后篇的关系

本篇拆的是「座位」这一层，属于执行器资源管理的主干。KV 块的详细账本见 TensorRT-LLM 源码完全拆解（四）：KVCacheManager 与块管理；采样器的完整管线见 TensorRT-LLM 源码完全拆解（十七）：Sampler；CUDA Graph 的补齐机制见 TensorRT-LLM 源码完全拆解（二十）：CUDA Graph 与编译路径；执行器释放请求的完整状态机则与前一篇 TensorRT-LLM 源码完全拆解（二十五）：GenerationExecutor 的三根队列 相衔接。

下一篇将讨论 TensorRT-LLM 的 speculative 资源管理器：草稿模型的 KV 池如何与目标模型的座位池共享同一套编号，以及一条请求在被拒绝草稿后如何只回滚尾部而不重建整个座位。