Defragmenter Warm-Up

Defragmenter 在运行时通过将很少使用的、索引较高的块与较低的空闲索引进行交换，来回收和压缩稀疏的 KV-cache 块使用。其预热阶段会预先编译小的交换图（swap graphs），以便后续在线的 defragmentation 能够以接近零的图编译延迟执行。

当最高分配的块索引远高于实际使用的块数量时（即碎片化），Defragmentation 可能会在中途服务时触发。该操作本身是一系列应用于键值缓存的交换内核（swap kernels）。通过预热，所有代表性的填充大小（padded sizes）都会提前通过确定性的、最小化的交换进行预编译。这确保了在线的 defragmentation 成为一个可预测的、低延迟的维护任务。仅跳过 defragmenter 的预热不会影响正确性；它只会增加碎片化首次超过强制压缩阈值时的偶发性延迟的风险。

省略预热的潜在后果包括

• 需要一个先前未见的填充交换大小的第一个碎片化事件会在关键路径上触发图捕获和编译。
• 编译延迟可能会表现为用户请求的突发性尾部延迟峰值。
• 不同进程中的多个首次出现的交换大小可能会分别触发单独的编译。

您可以禁用预热步骤本身，也可以禁用整个 defragmentation 功能。要跳过包括 defragmenter 在内的所有预热阶段，请将 VLLM_SKIP_WARMUP=true 设置为 true。或者，在不使用统一注意力（unified attention）的情况下运行，有效地禁用了 defragmenter，因为它与统一注意力相关联；在这种情况下，预热将成为一个无操作（no-op）。请注意，在此版本中，没有独立的环保标志可以强制启用或禁用 defragmentation，独立于统一注意力。此外，如果您的执行模式支持，您可以通过设置 VLLM_DEFRAG_WITH_GRAPHS=false 来避免对 defragmenter 交换进行图编译。这会导致交换回退到常规执行，而预热仍然会执行它们，但不会触发图捕获。

相关的环境变量

• VLLM_DEFRAG_THRESHOLD：设置碎片化触发的启发式阈值。默认值为 32；较低的值会使压缩更积极。
• VLLM_DEFRAG_WITH_GRAPHS：确定交换路径是编译还是图化。默认情况下，此值遵循 bridge_mode == eager。
• VLLM_DEBUG=defrag：启用详细的 defragmentation 调试日志。
• VLLM_SKIP_WARMUP：禁用所有预热阶段，包括 defragmentation。

注意

禁用 defragmenter 预热本身并不会关闭 defragmentation，除非统一注意力或该功能被完全禁用。它只是跳过了预先的图准备，这可能会将编译成本转移到第一个实时碎片化事件上。

执行 Defragmenter Warm-Up

在主要的预热（warmup_model）期间，系统会在初始化 KV 缓存和 defragmenter 后调用内部的 warmup_defragmenter 方法。该过程通过以下预热步骤定义：

1. 确认 defragmenter 预热功能已启用（因为它仅在统一注意力启用时运行），并且 cache_utils 交换工具已准备就绪。
2. 建立填充阈值列表：[8, 16, 32, 64, 128, 256, 512]。
3. 选择一对最小的有效交换 [(1, 0)]，具有两个不同的块 ID。只需要两个实际的块。内部，每次交换调用都会填充到当前的阈值长度，以便生成该确切填充大小的编译图。
4. 遍历每个阈值并调用交换。这会根据执行模式捕获或编译该填充大小的交换图。
5. 当阈值数量为奇数时，执行一次额外的交换，使用第一个阈值。这会导致交换序列将 KV 缓存恢复到其原始状态（逻辑净变化为零）。
6. 完成日志记录。

未来的 defragmentation 交换请求总是会四舍五入或填充到这些已知阈值之一。所有操作的交换大小都会命中一个预编译的路径，并避免按需编译延迟。

日志

以下示例展示了当至少存在两个 KV 缓存块时，典型的日志序列

INFO 09-22 16:26:24 [hpu_model_runner.py:3428] Warming up defragmenter with thresholds: [8, 16, 32, 64, 128, 256, 512]
INFO 09-22 16:26:27 [hpu_model_runner.py:3452] Defragmenter warmup completed successfully

如果块不足，例如在极小的测试配置或分配失败的情况下，预热会优雅地被跳过，您可能会看到类似以下示例的日志

INFO 09-22 16:26:24 [hpu_model_runner.py:3428] Warming up defragmenter with thresholds: [8, 16, 32, 64, 128, 256, 512]
WARNING hh:mm:ss hpu_model_runner.py:#### Skipping defragmenter warmup, insufficient blocks (1)

要在实时 defragmentation（而不是仅用于最小化预热交换）期间发出细粒度的调试消息，请将 VLLM_DEBUG=defrag 添加到环境中。这样您就可以看到交换的块数量和压缩后的统计信息。