图模式指南

图模式指南#

概述#

本指南解释了如何在 vLLM Ascend 中使用图模式。

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

本文档侧重于 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: Default mode, same as the upstream vLLM strategy. The compile-time path follows PIECEWISE compilation, while the runtime may still use full-graph behavior for uniform decode batches.

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

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

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

cudagraph_mode

编译时

运行时

Npugraph_ex

FULL_AND_PIECEWISE

Piecewise compilation path

Mixed: PIECEWISE for mixed batches, FULL-capable for uniform decode batches

禁用

FULL / FULL_DECODE_ONLY

Npugraph_ex FX 优化

ACLGraph 捕获/重放

Enabled

PIECEWISE

仅融合过程

ACLGraph 捕获/重放

禁用

NONE

无

即时执行

禁用

此外，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 图文档仍然是模式语义的权威参考。

命令行示例：

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 上生效的图模式可能与配置中请求的模式不同。

使用 Npugraph_ex#

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

默认行为#

当 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) 收集运行模型的 profiling 跟踪数据。

  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。

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

  • Encoder-decoder models currently do not keep FULL_AND_PIECEWISE; on Ascend they fall back to PIECEWISE or NONE depending on compilation support.

回退到 Eager 模式#

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

离线推理示例：

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

参考资料#