DeepInfer 源码完全拆解（二十）：启动时的显存 profiling——从峰值到 KV 块数的那笔账

峰值里到底装了什么

在进入 profile_run() 之前，先建立一张「谁占显存」的清单。DeepInfer 的峰值至少包含五类：

1. 模型权重。包括主干、MTP/DFlash、Engram 表、视觉塔；MoE 模型还有每个 EP rank 实际持有的物理专家。权重在 profile 之前就已经加载完成，所以它们会完整出现在 max_memory_allocated() 里。
2. 前向激活与 workspace。MoE 的 grouped GEMM workspace、DeepEP 的 dispatch/combine 缓冲、注意力 kernel 的临时张量、采样器的 logits 缓冲。它们随 batch 形状和路由分布变化，是这次 profile 真正想测的部分。
3. 临时 KV 池。profile_run() 为了让 cache 读写 kernel 也走到真实路径，会按哑序列的块表分配一个小型 CacheEngine。这块内存走 cuMemAlloc，不计入 PyTorch 的 allocator 统计，跑完就释放。
4. 非 PyTorch 持久内存。CUDA context、NCCL 通信缓冲、DeepEP 的 userbuffer、驱动/第三方库的常驻分配。它们不在 torch.cuda.memory_allocated() 里，但在 mem_get_info() 的差值里。
5. 词表矩阵这类容易被忽略的权重。DeepSeek-V4.1-Flash 的 vocab_size 是 129280、hidden_size 是 5120，且 tie_word_embeddings: false。tok_emb 与 lm_head 各是 $129280 \times 5120$ 的参数矩阵，BF16 下每个约 1.23 GiB，两块合计约 2.47 GiB。源码里的 prepare_meta_fp8() 会跳过名字含 tok_emb 或 head 的模块，所以它们不会跟随专家权重一起被 FP8/FP4 量化；VocabParallelEmbedding 和 ParallelLMHead 也直接持有完整权重。对单个 rank 来说，这两块矩阵是峰值里实打实的一部分。

第 5 类值得单独说一句，因为它解释了一个常见的直觉偏差：权重并不只有专家层。MoE 的专家权重很大，但词表两端的两块稠密矩阵同样按 rank 复制；在 DP Attention 下，每个 DP rank 都要各自持有一份完整的 tok_emb 和 lm_head。这不是浪费，而是为了避免在采样前对 logits 做跨 rank 的 all-gather；代价是每张卡多出约 2.47 GiB 的常驻权重。这笔钱在 profile_run() 之前就已经花掉，所以会原封不动地进入峰值。

为什么是 SequenceMetadata，不是 Sequence

profile_run() 构造的是 SequenceMetadata，不是调度器里的 Sequence。这两个对象的职责不同：

• Sequence 是请求的生命周期载体，带 request_id、user_id、arrival_time、sampling_params、状态机、块表、结构化输出 matcher 等；它由 add_request() 创建，进入 scheduler 的 waiting 队列。
• SequenceMetadata 是一次前向的输入描述：seq_data、block_table、seqlen_q、seqlen_k、last_output_token、last_next_n_token、state_id 等。调度器每步从 Sequence 组装出它，再交给 Worker。

显存测量只关心「这一次前向要读哪些 token、写哪些块、形状多大」，不关心请求从哪来、排队多久、有没有结构化输出。所以 profile_run() 直接跨过 add_request() 和调度器，手工拼 SequenceMetadata。这带来两个直接好处：

• 可以构造任意形状，包括「一个序列的 K 很长、其余序列的 K 很短」这种真实调度器不一定能立刻凑出的组合。
• 不会被请求校验、tokenizer、结构化输出编译、多模态预处理等路径干扰；profile 要测的是模型执行，不是请求入口。

代价是它必须自己补齐 SequenceMetadata 的所有字段。代码里几个看起来不起眼的赋值，其实都对应一个约束：

1
seq = SequenceMetadata(
2
    request_id=str(seq_id),
3
    seq_id=seq_id,
4
    is_prompt=is_prompt,
5
    seq_data=SequenceData(prompt_ids),
6
    compressed_seq_data=SequenceData(compressed_prompt_ids),
7
    multi_modal_data=None,
8
    sampling_params=SamplingParams(top_p=0.99, top_logprobs=20),
9
    block_table=list(range(num_blocks, num_blocks + num_seq_blocks)),
10
    seqlen_q=seq_len_q,
11
    seqlen_k=seq_len_k,
12
    last_output_token=0,
13
    last_accepted_token=[],
14
    last_next_n_token=[] if is_prompt else nextn_pad_token_id,
15
    # Unlike padding dummies, profile-run sequences need distinct writable slots.
16
    mtp_info_write_slot=seq_id + 1,
17
    state_id=seq_id % num_state_slots,
18
)

• block_table 是手工从 num_blocks 开始的连续块号，不经过 BlockManager。这样 profile 的临时 cache 可以按「这些哑序列刚好需要多少块」来分配，不必预留正式池的容量。
• mtp_info_write_slot = seq_id + 1 把 0 号槽空出来。CUDA Graph 重放时的 padding 序列会写 0 号槽，profile 的真实哑序列需要各自不同的可写槽；如果也从 0 开始，多个序列会踩同一块 MTP 元数据。这个细节在 CUDA Graph 捕获与重放 里也出现过。
• last_next_n_token 在 decode profile 时填 nextn_pad_token_id，让 MTP/DFlash 的草稿 token 也进入形状；prompt profile 时留空。
• state_id = seq_id % num_state_slots 保证每个序列落在一个存在的状态槽里；状态槽数量来自 get_num_state_slots(max_num_seqs)，不一定等于 max_num_seqs，取模是必要的边界保护。

prompt 形状：一条长序列加一群短序列

prompt 引擎的哑批次由 _build_prompt_profile_seq_lens() 生成。它的规则可以用三句话概括：

1. 把 max_num_batched_tokens 尽量平均分给 max_num_seqs 条序列，得到每条序列的 seqlen_q。
2. 把第一条序列的 seqlen_k 直接拉到 runtime_max_model_len，其余序列的 seqlen_k 先等于自己的 seqlen_q。
3. 如果设置了 DEEPINFER_PREFILL_MAX_SUM_SEQLEN_K，再把总 K 限制在「最小可行值」和「最大可能值」之间，多出来的 K 平均摊给其余序列。

代码里的前两步是：

1
profile_seq_lens_q = [
2
    max_num_batched_tokens // max_num_seqs
3
    + (seq_id < max_num_batched_tokens % max_num_seqs)
4
    for seq_id in range(max_num_seqs)
5
]
6
profile_seq_lens_k = profile_seq_lens_q.copy()
7
runtime_max_model_len = self.model_config.runtime_max_model_len
8
assert all(seq_len_q <= runtime_max_model_len for seq_len_q in profile_seq_lens_q)
9
profile_seq_lens_k[0] = runtime_max_model_len

这个形状是刻意做出来的「混合负载」：

• 第一条序列的 q 只是平均值，但 k 是最大运行时长度。它模拟的是 chunked prefill 里最常见的长上下文场景：这一拍只算一小段 query，却要 attend 到全部历史 KV。注意力的 workspace 和 K 的读取量由 seqlen_k 决定，不是由 seqlen_q 决定；把 k 拉满，才能让长上下文注意力 kernel 的临时缓冲真正分配出来。
• 其余序列的 q = k，模拟的是短序列的整段 prefill。它们让 batch 维度、block table 的条目数、CP 切分后的行数都达到 max_num_seqs 量级。
• 两者的组合同时压到了「单条长序列的 K」和「多条序列的 batch」两个维度。如果只用一个均匀批次，长上下文注意力和大 batch 的 workspace 可能有一个测不到。

runtime_max_model_len 不是用户填的 max_model_len，而是加上了调度和草稿开销的上界。ModelConfig._get_runtime_max_model_len() 的定义是：

1
def _get_runtime_max_model_len(max_model_len: int) -> int:
2
    nextn = envs.DEEPINFER_USE_NEXTN_DECODE
3
    scheduler_overhead = nextn + (nextn + 1 if envs.DEEPINFER_ZERO_OVERHEAD_SCHEDULING else 0)
4
    draft_overhead = nextn
5
    return max_model_len + scheduler_overhead + draft_overhead

按默认 nextn = 5、ZOS 开启来算，开销是 $5 + 6 + 5 = 16$ 个 token。也就是说，一条标称 32768 的序列，运行时位置上界是 32784。profile 用这个上界做 k，是为了覆盖「调度器多排了几个 token、草稿又插进来几个 token」之后的最坏位置；如果只用 max_model_len，长上下文注意力的最后几个位置可能测不到。

sum-K 上限：不要让最坏形状把显存算爆

默认情况下，max_num_seqs 条序列的 K 之和可以非常大：第一条是 runtime_max_model_len，其余每条至少是 max_num_batched_tokens / max_num_seqs。如果 max_num_seqs 和 max_model_len 都很大，这个总 K 会远超真实负载，导致 profile 高估注意力 workspace，进而低估 KV 池。

DEEPINFER_PREFILL_MAX_SUM_SEQLEN_K 就是给这个总 K 设上限的。代码先算出最小值（第一条拉满、其余取 q）和最大值（每条都拉满），再把目标值夹在两者之间；多出来的 K 按剩余序列数平均分摊，每条序列最多加到 runtime_max_model_len：

1
min_profile_sum_seqlen_k = sum(profile_seq_lens_k)
2
max_profile_sum_seqlen_k = max_num_seqs * runtime_max_model_len
3
prefill_sum_seqlen_k_limit = envs.DEEPINFER_PREFILL_MAX_SUM_SEQLEN_K
4
if prefill_sum_seqlen_k_limit is not None:
5
    profile_sum_seqlen_k_target = min(
6
        max(prefill_sum_seqlen_k_limit, min_profile_sum_seqlen_k),
7
        max_profile_sum_seqlen_k,
8
    )
9
    # 把 target - min 平均摊给其余序列，每条不超过 runtime_max_model_len

这里有一个取舍：这个环境变量不是「越大越安全」，而是「越接近真实负载越有意义」。设得太小，profile 测不到长上下文注意力的真实 workspace；设得太大，又会把 KV 池预算压得太低。源码在目标值被 clamp 时会打 warning，提示实际使用的值已经不等于用户给的值。

一条具体形状：以 offline 示例的配置走一遍

examples/offline_inference.py 用了一组便于本机跑的配置：max_num_seqs=4、max_num_batched_tokens=32768、max_model_len=32768。按上面的规则，q 会平均分成四条 8192；第一条的 k 拉到 32768 + 16 = 32784，其余三条的 k 仍是 8192。于是这个哑批次的形状是：

这不是一个「四条一样长」的批次，而是一条长上下文序列和三条普通序列拼在一起。它同时覆盖了：

• 单条序列 32K 上下文的注意力读取与 workspace；
• 四条序列的 block table、状态槽、MTP 写槽；
• CP 开启时，q 行数按 CP 切分后的镜像布局；
• 采样器要处理的 total_q 行 logits。

如果换成默认的 max_num_seqs=256、max_model_len=4096，形状会变成「256 条短序列，第一条 k 约 4112，其余每条 k 约 16」。这两种形状测出来的峰值可能相差很大，前者偏长上下文，后者偏大 batch。profile_run() 用 max_num_seqs 和 max_num_batched_tokens 而不是写死一个形状，就是为了让配置改变时，测量跟着改变。

decode 形状：1 + nextn 个 token

COMPLETION 引擎不做 prefill，它只测 decode。此时 is_prompt=False，每条序列的 q 和 k 都是 1 + nextn：

1
seq_len_q = 1 + self.nextn
2
seq_len_k = 1 + self.nextn
3
seq_data_len = seq_len_k - seq_len_q + 1

nextn 来自 DEEPINFER_USE_NEXTN_DECODE，默认 5，所以 decode profile 每条序列按 6 个 token 算。这 6 个 token 对应「1 个主模型 token + 5 个草稿 token」的变长验证形状。它测的是 decode 路径上的 MoE workspace、DFlash 草稿头、采样器的 batch 维度，而不是长上下文注意力。

临时 KV 池：为什么要真的分配，还要清零

profile_run() 不是只跑模型前向。它会在跑之前按哑序列的块表分配一个小型 CacheEngine：

1
cache_engine = CacheEngine(
2
    cache_config, self.model.cfg, max_num_seqs, num_gpu_blocks=num_blocks
3
)
4
cache_engine.gpu_blocks.zero_()
5
cache_engine.gpu_states.zero_()

这两行清零不是洁癖。chunked prefill 的某些注意力路径会按 block table 做全量 gather；如果临时 cache 里是未初始化的显存，gather 可能读到 NaN 或极大值，污染注意力输出，甚至让后面的 kernel 走到异常分支。清零保证 profile 跑的是「数值上可预期」的路径，同时仍然走真实的 cache 读写 kernel，让这部分显存开销被计入峰值。

临时 cache 的块数 num_blocks 来自哑序列的 seq_len_k，不是正式池的块数；它只覆盖「这组哑序列刚好需要多少块」。源码注释明确说这块 cache 走 cuMemAlloc，不计入 PyTorch 显存统计，并且随 profile_run() 返回即释放，所以它不会污染后面的 profile_num_available_blocks() 记账。换句话说，临时 cache 的峰值被有意排除在 KV 预算之外：它只是为了测 kernel，不是正式池的一部分。

前向、采样、后处理都算

profile_run() 最后调用 execute_model_profile_run()：

1
def execute_model_profile_run(self, seq_metadata_list, kv_caches) -> None:
2
    main_model_output = self.execute_main_model(seq_metadata_list, kv_caches)
3
    input_metadata = main_model_output.input_metadata
4
    model_output = Movable(main_model_output.model_output)
5
    del main_model_output
6

7
    sampler_output = self.execute_sample(
8
        seq_metadata_list, input_metadata, model_output, kv_caches
9
    )
10
    torch.cuda.current_stream().synchronize()
11
    self.post_process(seq_metadata_list, sampler_output, input_metadata.is_prompt)

这个顺序说明 profile 测的不只是 Transformer 前向：

• execute_main_model() 测主干、MoE、注意力、MTP 目标层特征写入；
• execute_sample() 测采样器：logits 的 bf16_gemm_nt、温度/top-p/top-k、log-softmax、拒绝采样、结构化输出 mask；
• post_process() 测输出回传、SamplerOutput 的构造、可能的 logprobs 物化。

采样器的 logits 缓冲很容易被低估。词表 129280、total_q 是整批 query 行数时，logits 是一个 [total_q, 129280] 的 BF16/FP32 张量；即使只对选中的行算，临时 workspace 也不小。把它纳入 profile，才能让这部分内存在 KV 预算里被预留出来。

MoE 强制不均衡：1.8 倍是经验值

profile 的哑 token 是随机生成的，路由分布接近均匀。均匀路由下，每个专家分到的 token 数接近平均值，DeepEP 的 dispatch/combine 缓冲、grouped GEMM 的 workspace 都会偏小。真实请求的 token 分布很少这么均匀，热专家可能承担远高于平均的 token 数。

DeepInfer 的处理是：

1
envs.DEEPINFER_FORCE_IMBALANCE_RATIO = 1.8
2
self.execute_model_profile_run(seqs, cache_engine.gpu_cache)
3
envs.DEEPINFER_FORCE_IMBALANCE_RATIO = 0.0

源码注释只说了「with MoE simulated imbalance enabled」，没有给出 1.8 的推导。合理的解释是：它把最热专家的负载抬到平均值的 1.8 倍左右，让按「每专家最大 token 数」定尺的通信/计算缓冲提前分配出来。这个系数是经验值，不是对真实流量的上界证明；如果线上路由比 1.8 更偏，profile 仍然可能低估。工程上应该把 EPLB 的负载统计和实际显存监控一起看，而不是把 1.8 当成安全保证。

MoE 的并行细节、EPLB 如何重排专家，见 MoE 专家并行与 EPLB；这里只关心它对显存峰值的影响：专家路由越集中，单卡上的临时缓冲越大。

为什么利用率乘的是总显存，不是空闲显存

gpu_memory_utilization 的语义是「最多允许这个引擎使用设备总显存的多少」。这和 vLLM 的 request_memory() 一致：它也是 total_memory * gpu_memory_utilization，然后和启动时的空闲显存做校验。DeepInfer 的写法更直接：预算从总显存算，不从空闲显存算；因为权重已经加载，空闲显存里已经扣掉了权重，如果再用空闲显存乘利用率，会漏掉权重这块最大的固定成本。

这个语义也解释了为什么 gpu_memory_utilization 不能设得太低。假设权重和运行时缓冲已经占了总显存的 70%，利用率设 0.75，预算只有总显存的 75%，留给 KV 和状态池的就只剩 5%；设 0.70 以下，available_kv_cache_memory 直接变成负数，块数为 0。反过来，利用率设得接近 1.0，虽然 KV 池变大，但 CUDA Graph 捕获、NCCL 缓冲增长和显存碎片就没有余量，启动后段容易 OOM。

empty_cache() 与 non_torch：两个不同世界的账

empty_cache() 在 profile 前后各出现一次，但作用不同：

• 第一次在 profile 之前：把 PyTorch 缓存分配器里暂时不用的块还给驱动，让 mem_get_info() 的初始空闲值反映真实状态。否则缓存分配器占着的显存会算进「其它占用」，让 non_torch 偏大。
• 第二次在 profile 之后：profile 期间产生的临时激活可能已经被缓存分配器保留；先清掉再读 torch.cuda.memory_allocated()，留下的才是长期驻留的 tensor。如果不清理，non_torch 会把「可复用的缓存」误当成「PyTorch 之外的占用」。

non_torch 这一项覆盖的是 PyTorch allocator 之外的世界：

• CUDA context、cuBLAS/cuDNN 的 workspace、驱动自身的分配；
• NCCL 通信缓冲、DeepEP 的 dispatch/combine 缓冲、userbuffer；
• cuMemAlloc 分配的 KV 池（在 profile 阶段是临时 cache，之后是正式池）；
• 其它进程在同一张卡上的显存占用。

最后一条是双刃剑。mem_get_info() 是设备级的，torch.cuda.memory_allocated() 是进程级的；如果同一张卡上还有别的进程，non_torch 会把别人的占用也算进来，导致峰值偏高、KV 池偏小。保守地说，这不会让引擎超分；但如果别的进程在 profile 期间释放了显存，non_torch 可能变成负数，代码用 max(non_torch, 0) 把它夹到 0。这个 clamp 只能防止记账出现负值，不能修复「测量期间别人改了显存」这个事实。生产环境应该把推理进程独占显卡，或者至少保证 profile 窗口内没有别的进程在分配/释放。

peak_torch 里有什么，没有什么

peak_torch 是 PyTorch allocator 视角的峰值，包含：

• 权重（在 profile 之前就已分配）；
• 前向激活、注意力 workspace、MoE grouped GEMM workspace；
• 采样器的 logits、top-k/top-p 临时缓冲；
• torch.empty 一类的临时张量。

它不包含：

• 临时 CacheEngine 的 gpu_blocks / gpu_states，因为它们走 cuMemAlloc，不在 PyTorch allocator 里；
• NCCL/DeepEP 的持久缓冲，因为它们也不在 PyTorch allocator 里；
• CUDA Graph 的私有池，因为图还没捕获；
• 显存碎片造成的不可用空洞。

所以 peak_allocated_memory = peak_torch + non_torch 是一个「尽量把两个世界都算上」的近似，而不是一次完整的显存审计。它的准确性取决于三件事：profile 形状是否覆盖真实最坏情况、non_torch 是否只包含本进程、以及后续阶段（图捕获）是否还在预算内。

状态池为什么要乘 2

state_size *= 2 旁边的注释是 state store & copy buffer。DeepInfer 的状态缓存不是只有一份：一份是长期保存的状态槽，另一份是拷贝缓冲。拷贝缓冲服务于状态克隆、P/D 交接或跨拍复制；如果只按一份分配，运行时的 clone 路径会额外申请显存，破坏预算。

状态池的尺寸还与 max_num_seqs 绑定。get_state_shape(cfg, max_num_seqs) 的乘积随并发数增长，所以 max_num_seqs 不只是调度参数，也是显存参数。调低它可以给 KV 池腾出空间，但代价是并发上限下降；调高它会让状态池先吃掉预算。站内 KV 内存与 SWA 有界重放 拆过状态块的三段布局和 DEEPINFER_NUM_STATE_SLOTS_RATIO 的放大关系，这里只强调记账顺序：状态池必须在除块之前扣掉，否则块数会把状态池的钱也花掉。

max_seq_len 的 0.8 校验

块数算出来之后，_init_cache() 还会做一次校验：

并要求：

其中 $b$ 是每块 token 数，$N_{\text{blocks}}$ 是上一步算出的块数，$L_{\text{runtime,max}}$ 是 runtime_max_model_len。这个校验回答的是：这块 KV 池能不能容纳一条最长序列，并且还留出 20% 的余量。

0.8 是硬编码的，源码没有给出推导。从效果倒推，它至少覆盖三类开销：

• 块表本身不是按「一条序列连续占满」组织的，块号可能分散；池子里需要留出分配碎片。
• 一条最长序列之外，引擎还要同时服务其它序列；如果池子刚好只够一条序列，任何并发都会触发抢占。
• 状态槽、MTP 元数据、cache 读写 kernel 的临时索引也占用同一预算的边角。

如果校验失败，启动直接报错，提示提高 gpu_memory_utilization 或降低 max_model_len。以 V4.1-Flash 的 890 字节/token 为例，一条 1M token 的序列需要约 890 MB KV；按 0.8 折算，池子至少要约 1.04 GiB 才能通过校验。这个数字本身不大，但它是「单条序列」的下限，不是「整个服务」的推荐容量。

一个示例账本

为了把减法顺序走通，下面用一组假想的数字演示，不是任何实测结果：

如果每 token 是 890 字节，块大小按 128 token 算，单块约 111.25 KiB，76 GiB 可以切出约 71.6 万个块，对应约 9170 万 token 的 KV 容量。这个结果说明：在 890 字节/token 的模型上，KV 池通常不是最先见底的那一项；权重、激活、状态和图捕获才是。也正因如此，max_seq_len 校验和 gpu_memory_utilization 的选择，往往比「KV 池能装多少 token」更影响能不能启动。

和 vLLM：同一套记账，多了状态池和平均对齐

vLLM V1 的启动账是：

1
# vllm/v1/worker/gpu_worker.py, determine_available_memory
2
self.model_runner.profile_run(randomize_inputs=self.randomize_dummy_inputs)
3
...
4
self.available_kv_cache_memory_bytes = (
5
    self.requested_memory
6
    - profile_result.non_kv_cache_memory
7
    - cudagraph_memory_estimate_applied
8
)

其中 requested_memory 来自 request_memory()：

1
requested_memory = math.ceil(
2
    init_snapshot.total_memory * cache_config.gpu_memory_utilization
3
)

三者的共同点是：

• 都按「设备总显存 × 利用率」给出预算，而不是按空闲显存；
• 都用一次真实 profile run 测峰值；
• 都区分 torch 内与 torch 外的占用。

DeepInfer 多了两处：

1. 状态池要单独减掉，而且乘 2。vLLM 的模型不需要第二本状态账，它的 KV cache 就是主池；DeepInfer 的状态槽独立于 KV 块，必须在除法之前扣。
2. 块数在 world group 上取平均并对齐偶数。vLLM 也会把各 worker 的容量收敛成一份所有 worker 都能用的配置；DeepInfer 的写法是 SUM // size // 2 * 2，这个平均语义意味着它假设各 rank 同构。

vLLM 提供了 profile_cudagraph_memory()；在开启图显存估算时，它会把估算值从 KV 预算里扣掉；DeepInfer 的 profile_run() 不包含图捕获，图捕获发生在 warm_up_model 阶段，余量靠 gpu_memory_utilization 里的未用部分承担。这是两者在「预算时点」上的一个实际差异：vLLM 把图的账提前算进预算，DeepInfer 把它留给运行时余量。

vLLM 的 KV 池还有一层 DeepInfer 没有的分组抽象。下图来自 vLLM 的 hybrid KV cache manager 文档：每一行是一个 KVCacheTensor，对应一组共享同一 page size 的层，例如 full attention 层与若干 sliding-window 层；这些 group 从同一个 block 号空间里取块，斜线区表示该 group 当前未被分配的尾部。

图源：vLLM 官方文档 docs/assets/design/hybrid_kv_cache_manager/memory_layout.png。这张图说明的是 vLLM 的「分组 + 共享块池」抽象：不同层只要 page size 兼容，就可以从同一块号空间里分配。DeepInfer 的账本不是这种按 group 拼层的组织，它把主 KV 池、SWA/index 相关缓存与状态池分开记；分账的目的是让状态槽和 KV 块解耦，而不是让所有层共享同一张块表。两种组织方式解决的是不同问题，不能直接比谁的「内存利用率更高」。

和 SGLang：静态比例 vs. 实测峰值

SGLang 的显存管理走的是另一条路：用 mem_fraction_static 作为静态显存比例，在模型 runner 初始化时计算 KV 池的可用 token 数，再把剩余部分留给动态激活和临时缓冲。对比之下：

SGLang 的静态比例把「KV 池能占多少」直接写成一个比例，优点是启动快、行为可预测；缺点是比例不随模型结构自动变化。DeepInfer 的实测峰值自动包含模型特化部分（Engram、索引器、状态池），代价是启动慢，而且测量窗口里如果其它进程在动显存，测量就不准。

站内 SGLang 源码完全拆解（十五）：内存池与显存管理 拆过 SGLang 的 ReqToTokenPool、KVPool 与 allocator 如何记物理账；可以对照着看两边对「物理账」的切分方式。

和 TensorRT-LLM：预算是配置推导，不是实测

TensorRT-LLM 的 KV 容量由 max_tokens、max_gpu_total_bytes 等配置推导，并在 profiling 之后做一轮显式预留（多模态编码器、workspace、惩罚表等）。它的预算更像「配置 + 已知项」，而不是「跑一遍量峰值」。DeepInfer 的选择正好相反：让最坏形状自己去分配，再把测出来的值反推成块数。

三种方式没有绝对优劣：

• 配置推导快、可复现，但漏掉某一类临时缓冲时只能靠显式预留补；
• 实测峰值覆盖未知项，但测量窗口受环境影响，且形状选择决定测到多少；
• 静态比例最简单，但对模型特化的部分不敏感。

DeepInfer 之所以能选择实测，是因为它只服务 V4.1-Flash 这一族模型：模型结构已知、状态池和索引器的开销已知，最坏形状可以手工构造。通用框架要覆盖几百种模型，很难为每种模型都写一个精确的 profile 形状。

启动失败的三类报错

1. No available memory for the cache blocks。说明 $M_{\text{KV}} \le 0$，即预算在减掉峰值和状态池之后已经没有余量。排查顺序：先看权重和非 torch 占用是否偏高（是否多加载了东西、是否有别的进程占卡），再看状态池是否过大（max_num_seqs 是否设得过高），最后才考虑调高 gpu_memory_utilization。直接调高利用率可能只是把 KV 池从负数拉到接近零，随后在 max_seq_len 校验或图捕获时再次失败。
2. runtime max seq len ... larger than the maximum number of tokens that can be stored in KV cache。说明块数非零，但 block_size × num_gpu_blocks × 0.8 小于 runtime_max_model_len。这时 KV 池能装的总 token 不够一条最长序列。要么提高利用率，要么降低 max_model_len。注意 runtime_max_model_len 比 max_model_len 多出 nextn 相关的十几个 token，报错里的两个数字不要混淆。
3. init_cache_engine / warm_up_model 阶段 OOM。预算算出来了，但实际分配失败。常见原因是多卡平均把某个 rank 的块数抬高了，或者 CUDA Graph 捕获超出了余量。排查时分别看：每个 rank 打印的 # GPU blocks 是否一致、图捕获阶段是否有额外的显存峰值、是否开了过多的图尺寸桶。

测量窗口的污染

profile_run() 依赖 mem_get_info() 和 max_memory_allocated() 的差值。下面这些情况会让差值失真：

• 同卡上还有别的进程在分配/释放显存：non_torch 把别人的占用算进来，或者在别人释放时变成负数（被 clamp 到 0）。
• 第一次 empty_cache() 之前缓存分配器里有大块可复用内存：mem_get_info() 的空闲值偏低，但这部分会被 torch_allocated 抵消一部分，影响取决于碎片形态。
• 临时 CacheEngine 走 cuMemAlloc，它的峰值在 mem_get_info() 差值里，但不在 max_memory_allocated() 里；如果它还没释放，non_torch 会把它算成本进程占用。源码注释说明它随 profile_run() 返回即释放，所以正常情况下不会进入最终账。
• 其它 rank 的 NCCL 通信在 profile 期间分配缓冲：这些缓冲与 profile 的形状有关，可能让某个 rank 的 non_torch 偏高。

DeepInfer 没有对「其它进程」做显式检测；它靠的是用户独占显卡。生产部署里，把推理进程和监控/训练进程放在同一张卡上，是最常见也最难排查的预算失真来源。

形状选择的影响

profile_run() 测的是形状的函数。下面几项改一个，测出来的峰值就可能明显不同：

离线示例用 max_num_seqs=4 跑得动，不代表生产用 max_num_seqs=256 时同样的预算还成立；反过来，生产设了很大的 max_num_seqs，状态池和 batch 维度会先把预算占掉。调这些参数时，应该同时看启动日志里的 peak、non_torch、state_size、kv_cache_size 四个数，而不是只看最终块数。

CUDA Graph 的余量

warm_up_model 里的图捕获不在 profile 峰值里，但会真实占显存。工程上要留多少，取决于：

• 图尺寸桶的数量与最大尺寸（build_graph_batch_sizes 的幂次段 + 定宽段）；
• DFlash 的独立图；
• NCCL 在图里的依赖缓冲。

站内 CUDA Graph 捕获与重放 里提到，图捕获阶段的峰值可能高于运行时，而且图池一旦捕获就常驻。DeepInfer 因此把 gpu_memory_utilization 的未用部分当作图与碎片的余量；利用率设得越接近 1，这部分余量越少。遇到图捕获 OOM，优先调低利用率或减少桶，而不是去改 profile 逻辑。

一个可复现的启动检查清单

启动一个 DeepInfer 实例之后，按下面顺序读日志：

1. Memory profiling results: duration=..., total_gpu_memory=..., initial_memory_usage=..., initial_torch_memory=...：看 profile 开始前的初始占用，判断权重加载是否正常。
2. peak_torch_memory=...：和模型参数量对得上吗？如果明显偏高，先怀疑 profile 形状或 MoE 不均衡系数。
3. non_torch_memory=...：是否超过预期？超过说明有别的进程或通信缓冲常驻。
4. state_size=...：和 max_num_seqs 一起看；状态池过大时先调并发，而不是调利用率。
5. kv_cache_size=...：这是除块之前的可用 KV 字节数。
6. RANK ..., # GPU blocks: ...：多 rank 之间是否一致；不一致说明同构假设被破坏。
7. 图捕获与 warmup 是否成功；失败说明余量不足。