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。
现有仓库设计说明：docs/source/developer_guide/Design_Documents/ACL_Graph.md。

本文档有意不重新解释上游主题，例如图模式选择、调度器行为、批次描述符构建、捕获分桶、填充策略，或全图与分段执行的通用含义。

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 到 8 的 255 的倍数
从 16 到 256 的 max_cudagraph_capture_size 的倍数

概念上，默认列表如下所示：

[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。
对于 ACL 图路径，use_inductor 被禁用。
当 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.py
vllm_ascend/attention/mla_v1.py
vllm_ascend/attention/context_parallel/attention_cp.py
vllm_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 中提供了图感知的打印辅助工具，但这些是开发者诊断工具，而非执行设计的一部分。