图模式指南

概述

本指南说明如何在 vLLM Ascend 中使用图模式。

vLLM 已提供通用的图模式架构、模式定义和编译集成。有关这些上游概念，请参阅：

• CUDA 图

• torch.compile

本文档聚焦于 Ascend 特有视角：图模式在 Ascend 上的工作原理、涉及的组件、如何配置以及用户应注意的约束条件。

Ascend 上的当前状态

• 图模式当前仅在 V1 引擎 上可用。

• ACLGraph（通过 torch.npu.NPUGraph 进行捕获/重放）是 Ascend 上默认图路径使用的运行时图执行机制。

• Npugraph_ex 是一个编译时 FX 图优化层，在 FULL/FULL_DECODE_ONLY 模式下默认启用。它在 ACLGraph 捕获之前优化图。

• XliteGraph 是一个可选的图路径，适用于选定的模型系列和环境。

• 在上下文并行场景中，cudagraph_mode="FULL" 尚未得到充分支持。

Ascend 上的图路径

vLLM Ascend 提供两种图路径：

图路径	默认	描述	自版本
ACLGraph (+ Npugraph_ex)	是	编译时 FX 优化 (Npugraph_ex) + 运行时捕获/重放 (ACLGraph)	v0.9.0rc1（Npugraph_ex 自 v0.15.0rc1 起）
XliteGraph	否	针对选定模型系列的预配置图路径。需要单独安装	v0.11.0

图模式在 Ascend 上的工作原理

Ascend 上的默认图路径包含两个阶段：编译时优化 和 运行时捕获/重放。ACLGraph 处理运行时捕获/重放。编译时阶段因 cudagraph_mode 而异：

• FULL_AND_PIECEWISE：默认模式，与上游 vLLM 策略相同。编译时路径遵循 PIECEWISE 编译，而运行时对于均匀解码批次可能仍使用全图行为。

• FULL / FULL_DECODE_ONLY：Npugraph_ex 通过 npugraph_ex 优化 FX 图（force_eager=True，仅编译时，无捕获）。优化后的可调用对象随后由 ACLGraph 在运行时捕获和重放。

• PIECEWISE：Npugraph_ex 被禁用。编译时仅应用基本的 FX 融合 pass。ACLGraph 在运行时捕获和重放生成的可调用对象。

• NONE：无编译或图捕获。模型以 eager 模式运行。

cudagraph_mode	编译时	运行时	Npugraph_ex
FULL_AND_PIECEWISE	分段编译路径	混合：混合批次使用 PIECEWISE，均匀解码批次支持 FULL	禁用
FULL / FULL_DECODE_ONLY	Npugraph_ex FX 优化	ACLGraph 捕获/重放	启用
PIECEWISE	仅融合 pass	ACLGraph 捕获/重放	禁用
NONE	无	Eager 执行	禁用

此外，XliteGraph 可作为可选的替代图路径用于选定的模型系列（请参阅 使用 XliteGraph）。

使用 ACLGraph

ACLGraph 是 Ascend 上的运行时图捕获/重放机制。当图模式激活时（即 cudagraph_mode 不是 NONE），它会自动启用，无需显式配置。

基本用法

离线示例：

from vllm import LLM

llm = LLM(model="path/to/Qwen3-0.6B")
outputs = llm.generate("Hello, how are you?")

在线示例：

vllm serve Qwen/Qwen3-0.6B

显式 cudagraph_mode 配置

通用 cudagraph_mode 选项来自上游 vLLM。在 Ascend 上，最终生效的模式可能仍会根据平台和后端支持进行调整，因此官方 vLLM CUDA 图文档仍是模式语义的权威参考。

CLI 示例：

vllm serve Qwen/Qwen3-0.6B \
  --compilation-config '{"cudagraph_mode": "PIECEWISE"}'

Python 示例：

from vllm import LLM

llm = LLM(
    model="Qwen/Qwen3-0.6B",
    compilation_config={"cudagraph_mode": "PIECEWISE"},
)

有关 NONE、PIECEWISE、FULL、FULL_DECODE_ONLY 和 FULL_AND_PIECEWISE 的详细含义以及通用回退策略，请参阅上游 CUDA 图 设计文档。

注意力后端兼容性

并非所有注意力后端都支持所有图模式。vLLM 在兼容性检查期间会检查注意力后端兼容性，并在可能的情况下自动将 cudagraph_mode 调整为更兼容的模式，而不是立即失败。实际上，这意味着请求的全图模式可能会被缩小为混合或分段模式，如果后端完全无法支持图执行，图模式可能会被禁用。

在 Ascend 上，当前注意力后端的支持级别如下：

注意力后端	声明支持	实际含义
attention_v1	ALWAYS	支持混合预填充/解码批次的图执行
context_parallel/attention_cp	ALWAYS	支持混合预填充/解码批次的图执行
mla_v1	UNIFORM_BATCH	图执行仅限于均匀批次；完整图的限制更严格
context_parallel/mla_cp	UNIFORM_BATCH	图执行仅限于均匀批次；完整图的限制更严格
sfa_v1	UNIFORM_BATCH	图执行仅限于均匀批次；完整图的限制更严格
context_parallel/sfa_cp	UNIFORM_BATCH	图执行仅限于均匀批次；完整图的限制更严格

这就是为什么 Ascend 上的实际图模式可能与配置中请求的模式不同。

排查捕获资源耗尽问题

如果 ACLGraph 捕获失败，原因是配置的图大小超过了当前栈上可用的运行时资源，vLLM Ascend 现在会抛出一个专用错误并附带缓解指导。实践中，最有用的操作包括：

• 升级到可用的较新 HDK/CANN 栈；

• 减小 cudagraph_capture_sizes 或 max_cudagraph_capture_size；

• 当工作负载主要是均匀解码时，优先使用 FULL 或 FULL_DECODE_ONLY；

• 临时禁用图模式以确认问题与捕获相关。

这最可能出现在 PIECEWISE 或 FULL_AND_PIECEWISE 配置中，因为这些路径往往比均匀的全图解码捕获更多的图。

使用 Npugraph_ex

如 RFC 所述，Npugraph_ex 是一个编译时 FX 图优化层，与 ACLGraph 协同工作。它在 ACLGraph 运行时捕获之前优化模型的 FX 图。其性能优势主要来自于将多个算子融合为单个内核（例如，add + rms_norm → npu_add_rms_norm），以减少内核启动开销。

备注

Atlas 300I DUO 和 Atlas 200I Pro 不支持 enable_npugraph_ex。请设置 --additional-config '{"ascend_compilation_config": {"enable_npugraph_ex":false}}'。

默认行为

当 cudagraph_mode 为 FULL 或 FULL_DECODE_ONLY 时，Npugraph_ex 默认启用。在 PIECEWISE 或 NONE 模式下会自动禁用。

这意味着对于大多数用户，Npugraph_ex 无需任何显式配置即可生效：

from vllm import LLM

# Npugraph_ex is enabled by default in FULL/FULL_DECODE_ONLY mode
llm = LLM(model="path/to/Qwen2-7B-Instruct")
outputs = llm.generate("Hello, how are you?")

显式配置

要显式控制 Npugraph_ex：

离线示例：

from vllm import LLM

model = LLM(
    model="path/to/Qwen2-7B-Instruct",
    additional_config={
        "ascend_compilation_config": {
            "enable_npugraph_ex": True,
        }
    }
)
outputs = model.generate("Hello, how are you?")

在线示例：

vllm serve Qwen/Qwen2-7B-Instruct \
  --additional-config '{"ascend_compilation_config":{"enable_npugraph_ex":true}}'

要显式禁用 Npugraph_ex：

vllm serve Qwen/Qwen2-7B-Instruct \
  --additional-config '{"ascend_compilation_config":{"enable_npugraph_ex":false}}'

静态内核编译

静态内核编译是一个可选功能，它在编译时使用固定形状预编译算子二进制文件，从而减少静态或近似静态形状网络的运行时开销。它默认禁用，必须显式启用。

备注

启用静态内核会在服务启动时的图捕获阶段触发一次编译过程。根据待编译算子的数量和模型复杂度，这可能会增加几分钟到几十分钟的启动时间。一旦完成，后续的请求处理不受影响。

离线示例：

from vllm import LLM

model = LLM(
    model="path/to/Qwen2-7B-Instruct",
    additional_config={
        "ascend_compilation_config": {
            "enable_npugraph_ex": True,
            "enable_static_kernel": True,
        }
    }
)
outputs = model.generate("Hello, how are you?")

在线示例：

vllm serve Qwen/Qwen2-7B-Instruct \
  --additional-config '{"ascend_compilation_config":{"enable_npugraph_ex":true, "enable_static_kernel":true}}'

验证静态内核是否生效

推荐通过 Ascend Profiling 来验证静态内核是否生效：

1. 使用 Ascend PyTorch Profiler (torch_npu.profiler) 收集运行模型的性能分析跟踪。

2. 打开生成的 op_statistic.csv 文件。

3. 查找 op_type 或 name 列包含关键字 static_kernel 的算子。如果存在此类条目，则静态内核编译已对这些算子生效。

在编译阶段，您将看到一个 Python 警告（默认可见）：

Starting static kernel compilation, the build directory is <path>

这确认了编译已被触发。如果没有此消息，则表示静态内核未启用或直接复用了缓存结果。

有关 Npugraph_ex 的更多详细信息，请参阅 npugraph_ex 指南。

使用 XliteGraph

XliteGraph 是 Llama、Qwen 稠密系列模型、Qwen MoE 系列模型和 Qwen3-VL 的可选路径。它需要安装 Xlite 并通过 xlite_graph_config 进行配置。

首先安装 Xlite：

pip install xlite

离线示例：

from vllm import LLM

# Xlite supports decode-only mode by default.
# Full mode can be enabled with "full_mode": True.
llm = LLM(
    model="path/to/Qwen3-32B",
    tensor_parallel_size=8,
    additional_config={
        "xlite_graph_config": {
            "enabled": True,
            "full_mode": True,
        }
    },
)
outputs = llm.generate("Hello, how are you?")

在线示例：

vllm serve path/to/Qwen3-32B \
  --tensor-parallel-size 8 \
  --additional-config '{"xlite_graph_config": {"enabled": true, "full_mode": true}}'

有关 Xlite 的更多详细信息，请参阅 Xlite README。

常见限制与注意事项

• XliteGraph 应被视为一种替代图路径，而非在所有场景下直接替换 ACLGraph。

• 模型和后端覆盖范围仍在发展中，因此适用于一个模型系列的配置可能尚不推荐用于另一个模型系列。

• 编码器-解码器模型当前不保留 FULL_AND_PIECEWISE；在 Ascend 上，它们会根据编译支持回退到 PIECEWISE 或 NONE。

回退到 Eager 模式

如果遇到图模式问题，可以通过设置 enforce_eager=True 临时回退到 eager 模式。

如果ACL图捕获失败，且错误文本中包含确认的流资源签名（例如207008与Stream resources are insufficient或Insufficient_Stream_Resources同时出现），vLLM Ascend将重新抛出该捕获失败，并附带针对性的缓解指导。实践中，主要手段包括：升级到更新的HDK/CANN堆栈、减少cudagraph_capture_sizes、降低max_cudagraph_capture_size，或在工作负载主要为均匀解码时优先使用FULL/FULL_DECODE_ONLY。

离线示例：

from vllm import LLM

llm = LLM(model="path/to/your/model", enforce_eager=True)
outputs = llm.generate("Hello, how are you?")

在线示例：

vllm serve path/to/your/model --enforce-eager

参考资料

• CUDA 图

• torch.compile

• Xlite README

• Npugraph_ex 指南

• Npugraph_ex RFC

• ACL图开发者指南