ACL 图#
概述#
ACL 图是 vLLM 静态图执行的昇腾实现。上游 vLLM 和 PyTorch 文档已描述了通用图模型，包括 CUDAGraphMode、运行时调度、批处理描述符、分桶与填充，以及全图和分段图的定义。本文档聚焦于 vllm-ascend 中昇腾特有的内容：平台集成点、ACL 图捕获引入的额外约束，以及在重放期间保持注意力参数正确的机制。
在昇腾上，设计目标与上游静态图执行相同：减少中小运行时形状的主机启动开销。实现边界不同。vLLM 提供通用调度路径，而 vllm-ascend 提供 ACL 图重放所需的平台包装器、捕获大小修剪和注意力特定更新逻辑。
前提条件与参考资料#
上游 vLLM 通用图概念设计文档：CUDA Graphs。
PyTorch 通用捕获与重放语义文档：Accelerating PyTorch with CUDA Graphs。
昇腾操作启用用户指南：Graph Mode Guide。
现有仓库设计说明：ACL Graph
本文档有意不重新解释上游主题，如图模式选择、调度器行为、批处理描述符构建、捕获分桶、填充策略，或全图与分段执行的通用含义。
ACL 图如何融入 vLLM#
vLLM 拥有通用静态图流程。在昇腾上，NPUPlatform.get_static_graph_wrapper_cls() 返回 vllm_ascend.compilation.acl_graph.ACLGraphWrapper，这是 vLLM 启用静态图模式时使用的平台特定包装器。
ACLGraphWrapper 负责：
从前向上下文中读取运行时模式和
batch_descriptor，决定是立即执行、捕获新的 ACL 图，还是重放缓存的 ACL 图，
按批处理描述符缓存图条目，
保留昇腾后端所需的图池和重放记账信息。
该包装器不定义上游调度策略。它假设运行时模式和批处理描述符已由 vLLM 正确选择，然后对该具体运行时形状应用昇腾捕获或重放。
捕获大小与分桶#
vLLM 图重放需要稳定的运行时形状，因此 vLLM 不会尝试捕获所有可能的批处理形状。相反，它准备一组有限的捕获大小，并将运行时批处理调度到最近的支持大小。如果运行时批处理大于配置的最大捕获大小，则跳过图模式并回退到立即执行模式。
默认情况下，vLLM 构建捕获大小为：
1,2,4从
8到255的8的倍数从
256到max_cudagraph_capture_size的16的倍数
概念上，默认列表如下：
[1, 2, 4, 8, 16, 24, 32, ..., 248, 256, 272, 288, ...]
小批量时步长较小，可减少延迟最敏感区域的填充开销；大批量时步长较大，可控制捕获图的数量。
在昇腾上，此通用上游分桶策略仍是起点，但最终捕获大小可能因平台特定约束而进一步减少：
序列并行过滤可能移除不支持的大小，
运行时资源限制仍可能阻止某些配置大小被捕获，
某些运行时模式可能在捕获开始前被规范化。
昇腾特定设计约束#
捕获广度仍受运行时资源限制#
与 CUDA 设备上的 CUDA Graph 不同，昇腾上的 ACL 图捕获在所选图大小消耗的运行时资源超过当前后端可提供的能力时仍可能失败。分段模式是最敏感的情况，因为它捕获许多子图，且总捕获成本随模型深度和配置大小覆盖范围而扩展。
旧版 vLLM Ascend 应用了本地 update_aclgraph_sizes() 启发式方法，在最终捕获前缩小PIECEWISE 捕获大小集。该启发式方法已被移除。当前实现保持上游大小和调度行为不变，然后在 vllm_ascend/compilation/acl_graph.py 中拦截确认的捕获时流资源签名，并重新抛出更清晰的缓解指导。
在实践中，这意味着当捕获失败时，用户应将 cudagraph_capture_sizes 和 max_cudagraph_capture_size 作为主要调优杠杆。更新的 HDK/CANN 组合可以显著改善ACL 图容量，而通信密集型配置可能仍需要更小的配置大小集。
平台模式规范化比通用上游行为更严格#
昇腾目前在 vllm_ascend.platform.NPUPlatform.check_and_update_config() 中收窄了一些通用上游模式。
编码器-解码器模型被强制使用
PIECEWISE。use_inductor在 ACL 图路径上被禁用。启用 ACL 图时，
ASCEND_LAUNCH_BLOCKING=1被拒绝。Xlite 图模式可以禁用 ACL 图全模式，或根据配置回退到
FULL_DECODE_ONLY。
这些检查记录了当前 Ascend 后端能够安全执行的上游图行为子集。其中一些是长期平台约束，而另一些在当前实现中显然是过渡性的。
关键 Ascend 特有机制#
用于全图重放的主机端注意力参数更新#
Ascend 上的全图重放有一个上游通用文档未详细涵盖的额外问题：即使整体图是静态的，某些注意力算子也需要运行时元数据更新。Ascend 实现通过将图捕获与主机端任务参数更新分离来处理此问题。
流程如下：
在捕获期间，注意力后端记录每个图的任务句柄、事件、工作空间，以及需要刷新的张量或元数据的弱引用。
在重放之前，
update_full_graph_params()调用后端特定的update_graph_params()实现。该后端在更新流上运行参数刷新，在底层注意力算子启动前后分别调用
torch.npu.graph_task_update_begin(...)和torch.npu.graph_task_update_end(...)。torch.npu.ExternalEvent对象用于强制主机端更新流与重放流之间的顺序。
该机制在以下注意力后端中实现：
vllm_ascend/attention/attention_v1.pyvllm_ascend/attention/mla_v1.pyvllm_ascend/attention/context_parallel/attention_cp.pyvllm_ascend/attention/context_parallel/mla_cp.py
重要的设计点是，Ascend 全图支持依赖于后端提供的 update_graph_params() 钩子。没有该钩子，仅靠捕获不足以重放正确的注意力状态。
重放顺序与同步#
ACLGraphWrapper 在通用路径上的重放之前同步当前流，以确保主机端参数更新与将要消费它们的图执行保持对齐。这在异步调度或多线程执行中尤其重要。
如果顺序未被保持，迭代 i 的参数更新可能被迭代 i-1 的重放观察到，或者迭代 i 的重放可能在其自身参数更新完成之前开始。实际上，这意味着注意力算子可能以不匹配的运行时元数据运行，从而导致结果错误、精度问题甚至挂起。代码为主全图 eagle 场景保留了一条更窄的路径，但总体设计假设相同：重放不得超越待处理的参数更新工作。
Ascend 上的全图与分段图#
上游文档已在语义上定义了全图和分段图。在 Ascend 上，实际差异由后端支持和资源成本驱动。
分段模式#
分段模式是保守路径。它依赖于通用的 vLLM 拆分执行策略，然后将 ACL 图捕获应用于编译路径选择的非注意力段。在 Ascend 上，此模式目前是更广泛支持的选项，但它对流压力也最敏感，因为捕获的图数量随模型深度扩展。
全图模式#
当注意力后端能够通过 update_graph_params() 支持运行时参数修补时，全图模式是更注重性能的路径。在 Ascend 上，全图支持与那些注意力特定的更新钩子、工作空间缓存和重放顺序保证相关联。
诊断与操作说明#
确认图模式已激活的最简单方法是启用 cudagraph 指标并保持日志统计启用。在 CLI 使用中，使用
--cudagraph-metrics且不要传递--disable-log-stats。在 Python 使用中，设置cudagraph_metrics=True和disable_log_stats=False。然后检查输出的指标和日志。性能分析也可以确认是否正在发生重放，开发者在本地调试时可以在重放前添加临时打印，但这些是次要方法，此处不展开说明。
捕获大小选择主要遵循上游配置和分发行为；仅在确认流资源捕获失败时，才会在运行时重写为用户可见的指导信息。
在调试模式下，
ACLGraphWrapper断言重放使用捕获期间记录的相同张量地址。在当前实现中，
ASCEND_LAUNCH_BLOCKING=1与 ACL 图启用不兼容。为了在图执行中进行调试，该仓库还在
vllm_ascend.utils中提供了图感知的打印辅助工具，但这些属于开发者诊断功能，而非执行设计的一部分。