vLLM Ascend 架构总览

一、项目简介

vLLM Ascend（vllm-ascend）是 vLLM 社区维护的硬件插件，让 vLLM 可以无缝运行在华为昇腾 NPU 上。该项目的核心目标是将vLLM的高性能推理能力扩展到华为昇腾NPU硬件平台，使用户能够在昇腾NPU上获得与GPU相当的推理性能。

通过这个插件，用户可以像在GPU上使用vLLM一样，在昇腾NPU上部署和运行大语言模型。插件会自动处理NPU特有的硬件特性，包括内存管理、算子优化、通信优化等，用户无需修改任何代码即可在昇腾NPU上运行模型。

支持 Atlas 800I A2、Atlas A2 Training、Atlas 800I A3、Atlas A3 Training、Atlas 300I Duo 等硬件。这些硬件覆盖了从推理到训练的多种场景，可以满足不同规模的大语言模型部署需求。

graph LR
    A[vLLM 推理引擎] --> B[Hardware Plugin 接口]
    B --> C[vLLM Ascend 插件]
    C --> D[华为昇腾 NPU]
                

专题深度分析（平台对比系列）

以"对比"方式理解项目：同一模型/同一组件在 NVIDIA、AMD、Ascend 三个平台上的实现差异， 含函数级调用链与底层软件栈解析。按专题持续新增。

最新专题： DeepSeek V4.1-Flash 的 CED/CSA2 架构 × vllm-ascend 性能协助点（7 条机会）（2026-09-23）

进入专题对比目录 →

需求故事（一个 HTML 讲清一个需求）

每篇围绕一个真实需求（选自 git 提交记录，优先性能优化）：需求背景 → 相关流程 → 需求改动（真实 diff + 注释）→ 相关链接。与按模块"从上往下"的讲解互补。

最新故事： DeepSeek V4.1-Flash 登陆昇腾：框架支持与 Engram 主机卸载（PR #16925，73 文件 +10554 行）（2026-09-23）

进入需求故事目录 →

二、项目文件结构

vllm-ascend项目采用标准的Python项目结构，核心源码位于vllm_ascend目录下。每个子目录对应一个功能模块，职责清晰，便于维护和扩展。理解文件结构是深入学习项目的第一步。

核心源码目录（vllm_ascend/）：这是项目的核心，包含了所有NPU优化的实现代码。其中__init__.py是插件入口，定义了插件的注册机制；platform.py定义了NPU平台类；envs.py管理环境变量；ascend_config.py包含Ascend相关的配置选项。

功能模块目录：core/包含KV缓存管理和调度器等核心功能；models/定义了各种模型的实现；attention/包含多种注意力后端；ops/实现自定义算子；worker/是模型执行器；distributed/处理分布式通信；quantization/提供量化支持；patch/包含上游vLLM的补丁；compilation/处理图编译优化。

辅助目录：tests/包含单元测试和集成测试；docs/存放项目文档；examples/提供使用示例；benchmarks/包含性能基准测试。

vllm-ascend/
├── vllm_ascend/           # 核心源码目录
│   ├── __init__.py       # 插件入口
│   ├── platform.py       # NPU平台定义
│   ├── envs.py           # 环境变量管理
│   ├── ascend_config.py  # Ascend配置
│   ├── utils.py          # 工具函数
│   ├── core/             # 核心模块
│   ├── models/           # 模型定义
│   ├── attention/        # 注意力后端
│   ├── ops/              # 自定义算子
│   ├── worker/           # 执行器
│   ├── distributed/      # 分布式通信
│   ├── quantization/     # 量化支持
│   ├── patch/            # 上游补丁
│   ├── compilation/      # 编译优化
│   ├── sample/           # 采样器
│   ├── lora/             # LoRA适配
│   ├── spec_decode/      # 投机解码
│   ├── device/           # 设备管理
│   ├── model_loader/     # 模型加载
│   ├── profiler/         # 性能分析
│   └── _310p/            # 310P兼容层
├── tests/                 # 测试目录
├── docs/                  # 文档目录
├── examples/              # 示例代码
├── benchmarks/            # 性能基准
├── setup.py               # 安装脚本
├── pyproject.toml         # 项目配置
└── requirements.txt       # 依赖清单

graph LR
    A[vllm_ascend] --> B[core 核心模块]
    A --> C[models 模型定义]
    A --> D[attention 注意力]
    A --> E[ops 算子]
    A --> F[worker 执行器]
    A --> G[distributed 分布式]
    A --> H[quantization 量化]
    A --> I[patch 补丁]
    A --> J[compilation 编译]
                

三、上下游关系

vllm-ascend不是独立运行的，它必须配合vLLM核心引擎一起使用。vLLM提供通用的推理调度能力，vllm-ascend提供NPU硬件适配。两者通过vLLM定义的Hardware Plugin接口对接。

3.1 上游：vLLM核心引擎（需要安装）

vLLM是上游项目，提供推理系统的核心组件。这些组件在vllm-ascend中不重复实现，而是直接复用vLLM的代码。

安装方式：pip install vllm 或从源码安装

源码位置：D:\demo\202609\vllm-ascend\vllm\vllm-main\vllm\

3.2 下游：vllm-ascend插件（本项目）

vllm-ascend实现vLLM定义的Platform接口，将NPU硬件能力暴露给vLLM。

源码位置：D:\demo\202609\vllm-ascend\vllm-ascend-main\vllm_ascend\

3.3 依赖关系

vllm-ascend依赖vLLM的核心组件，同时依赖以下库：

四、整体架构

理解vllm-ascend的架构，首先要分清两个层面：一个是vLLM核心引擎（上游项目，负责通用的推理调度），一个是vllm-ascend插件（本项目，负责NPU硬件适配）。用户看到的Scheduler、Worker、vLLM Engine都属于vLLM核心引擎，不是本项目的代码；本项目只提供NPUPlatform、Attention Backend、Custom Ops等NPU适配层。

4.1 vLLM核心引擎（上游，不是本项目）

vLLM Engine：整个推理系统的入口，负责接收用户请求、管理推理会话、协调各组件工作。它不关心底层是GPU还是NPU，只负责上层调度。

Scheduler调度器：负责请求的调度和资源分配。它决定哪些请求优先处理、如何分配显存/NPU内存、如何进行连续批处理等。Scheduler是vLLM的核心组件，与硬件无关。

Worker执行器：每个Worker负责在一块GPU或NPU上执行实际的推理任务。Worker会调用底层的注意力后端、自定义算子等完成计算。vllm-ascend的工作就是让Worker能够在NPU上运行。

4.2 vllm-ascend插件（本项目）

NPUPlatform：封装昇腾NPU的硬件特性，告诉vLLM如何使用NPU。这是本项目的核心入口，通过Hardware Plugin接口注册到vLLM。

Attention Backend：实现NPU上的注意力计算，包括标准注意力、MLA、SFA等后端。

Custom Ops：实现NPU优化的自定义算子，如RMSNorm、SiluAndMul等。

Model Runner：负责模型的前向传播，调用注意力后端和自定义算子完成计算。

graph LR
    A[vLLM Engine] --> B[Scheduler]
    B --> C[Worker]
    C --> D[NPUPlatform]
    D --> E[Attention 后端]
    E --> F[Custom Ops]
    F --> G[NPU]
                

4.3 请求处理完整流程

当用户发送推理请求时，请求经过以下流程：

1. 用户请求：用户指定模型名称和输入文本

2. vLLM Engine：接收请求，创建推理会话

3. Scheduler：调度请求，分配资源，决定处理顺序

4. Worker：在指定的NPU上执行推理任务

5. NPUPlatform：提供NPU硬件抽象，管理NPU设备

6. Attention Backend：执行注意力计算（标准/MLA/SFA）

7. Custom Ops：执行自定义算子（RMSNorm、激活函数等）

8. Model Runner：协调模型的前向传播

9. 昇腾NPU：执行实际的计算

10. 推理结果：将生成的文本返回给用户

sequenceDiagram
    participant A as 用户
    box rgb(255,243,205) 上游vLLM
    participant B as Engine
    participant C as Scheduler
    participant D as Worker
    end
    box rgb(212,237,218) 本项目vllm-ascend
    participant E as NPUPlatform
    participant F as Attention 后端
    participant G as Custom Ops
    end
    participant H as NPU设备

    A->>B: 发送请求（模型名+输入）
    B->>C: 调度：决定谁先跑
    Note over C: 调度族：chunkPrefill 长输入切块
异步调度两步流水 · DPLB 实例均衡
    C->>D: 分配：KV 与显存资源
    Note over D: 缓存族：prefix cache 前缀复用
kv offload 下沉 DRAM · KV 池化与块管理
    D->>E: 执行：每 step 前向
    E->>F: attention 计算
    Note over F: 模型特性5族（GLM 驱动）：
并行切分 · W8A8 量化 · weight NZ
融合算子 · multi stream 双流
    F->>G: 算子调用
    Note over G: 自定义算子：RMSNorm · 激活
量化等 NPU 优化算子
    G->>H: NPU 执行
    Note over B,H: decode 侧：MTP 投机解码 · Sample 分片去重 · PD 分离
执行：CPU 绑核 · ACL Graph 图捕获回放 · model_runner v2
横切：EPLB 专家均衡 · 启动期：权重加载 多线程/lazy 与 NZ 转换
    H-->>G: 结果
    G-->>F: 回传
    F-->>D: 输出
    D-->>A: 返回
                

读法：20 个特性族已按流程位置标注在链路上——调度 3 + 缓存 4 + 执行 3 + 模型 5 + 解码部署 3 + 横切 1 + 加载 1；各族职责与代码落点见 《vLLM-Ascend 特性地图解读》。

# 1. vLLM Engine接收请求（vllm/v1/engine/llm_engine.py）
class LLMEngine:
    def generate(self, inputs):
        # 接收用户请求，传给Scheduler
        self.engine_core.add(request)

# 2. Scheduler调度请求（vllm/v1/core/）
# 决定哪些请求优先处理，分配KV缓存

# 3. Worker执行推理（vllm/v1/worker/gpu_worker.py）
class Worker:
    def execute_model(self, input_ids):
        # 调用ModelRunner执行前向传播
        return self.model_runner.execute(input_ids)

# 4. vllm-ascend的NPUPlatform（vllm_ascend/platform.py）
class NPUPlatform(Platform):
    # 实现Platform接口，告诉vLLM如何使用NPU
    device_name = "npu"

# 5. vllm-ascend的注意力后端（vllm_ascend/attention/）
# 实现NPU上的注意力计算

五、插件注册机制

vllm-ascend通过vLLM的插件机制进行注册。当vLLM启动时，会扫描所有已安装的插件，并调用每个插件的register函数。vllm-ascend的register函数会返回NPUPlatform类，告诉vLLM这是一个NPU硬件平台。之后，vLLM会实例化这个平台类，完成NPU的初始化。

插件注册流程：vLLM启动 → 扫描插件 → 调用register函数 → 返回NPUPlatform → 实例化平台 → NPU可用。这个流程确保了NPU平台能够在vLLM启动时正确初始化，为后续的推理任务做好准备。

模型注册机制：除了插件注册，vllm-ascend还需要注册支持的模型。每个模型都有一个唯一的名称和对应的类路径。当用户指定模型名称时，vLLM会根据注册信息动态导入模型类并实例化。这种机制使得模型可以按需加载，避免了不必要的资源消耗。

graph TD
    A[vLLM启动] --> B[扫描插件]
    B --> C[调用register]
    C --> D[返回NPUPlatform]
    D --> E[实例化平台]
    E --> F[NPU可用]
                

graph TD
    A[register_model] --> B[注册 KimiK3]
    A --> C[注册 DeepSeekV4]
    A --> D[注册 MiniMaxM3]
    A --> E[注册 Qwen3]
                

六、核心模块详解

vllm-ascend由多个功能模块组成，每个模块负责特定的功能。这些模块协同工作，共同实现了NPU上的高性能推理。下面详细介绍每个模块的功能和职责。

core模块是项目的核心，包含KV缓存管理和调度器等关键功能。KV缓存管理负责管理模型推理过程中的键值对缓存，调度器负责请求的调度和资源分配。这些功能对于大语言模型的推理至关重要，直接影响推理性能和资源利用率。

models模块定义了各种大语言模型的实现，包括DeepSeek V4、Kimi K3、MiniMax M3、Qwen3等。每个模型都有针对NPU优化的实现，充分利用NPU的硬件特性加速推理。

attention模块提供多种NPU优化的注意力后端，包括标准注意力、MLA多头潜在注意力、SFA稀疏注意力等。不同的注意力后端适用于不同的模型架构，用户可以根据需要选择合适的后端。

ops模块实现NPU优化的自定义算子，包括激活函数、线性层、MoE混合专家等。这些算子经过深度优化，能够充分发挥NPU的计算能力。

worker模块是模型执行的核心，负责模型的加载、初始化和推理执行。它与vLLM的Worker模块对接，将NPU的优化能力暴露给上层应用。

七、注意力后端

注意力机制是大语言模型的核心组件，负责计算输入序列中每个位置与其他位置的相关性。vllm-ascend提供了多种注意力后端，针对不同的模型架构和硬件特性进行优化。选择合适的注意力后端可以显著提升推理性能。

标准注意力后端（AscendAttentionBackend）：适用于标准的Transformer模型，实现标准的多头注意力计算。这是最通用的后端，适用于大多数模型。

MLA注意力后端（AscendMLABackend）：专为DeepSeek系列模型设计，实现了多头潜在注意力机制。MLA通过将注意力计算分解为多个低秩投影，减少了计算复杂度和内存占用。

SFA注意力后端（AscendSFABackend）：实现了稀疏注意力机制，适用于具有稀疏注意力模式的模型。SFA只计算部分位置之间的注意力，大大减少了计算量。

选择逻辑：系统会根据模型的配置自动选择合适的注意力后端。如果模型使用MLA，则选择MLA后端；如果使用稀疏注意力，则选择SFA后端；否则使用标准注意力后端。

graph TD
    A[get_attn_backend_cls] --> B{use_mla?}
    B -->|Yes| C[AscendMLABackend]
    B -->|No| D{use_sparse?}
    D -->|Yes| E[AscendSFABackend]
    D -->|No| F[AscendAttentionBackend]
                

graph LR
    A[模型类型] --> B[标准Transformer]
    A --> C[DeepSeek MLA]
    A --> D[稀疏注意力模型]
    B --> E[AscendAttentionBackend]
    C --> F[AscendMLABackend]
    D --> G[AscendSFABackend]
                

八、推理流程

当用户发送推理请求时，vllm-ascend会按照以下流程处理：首先接收用户的推理请求，然后由调度器进行调度和资源分配，接着Worker执行器开始执行推理任务，模型进行前向传播计算，最后采样器生成输出token。这个过程会循环进行，直到生成完整的输出序列。

详细流程：1. 接收请求：系统接收用户的推理请求，包含输入文本和生成参数。2. 调度分配：调度器根据系统资源和请求优先级进行调度。3. Worker执行：Worker加载模型并开始执行推理。4. 模型前向：模型进行前向传播，计算每个位置的输出概率。5. 采样输出：根据采样策略生成下一个token。6. 循环生成：重复步骤4-5，直到生成结束符或达到最大长度。7. 返回结果：将生成的文本返回给用户。

性能优化：在推理过程中，vllm-ascend会应用多种优化技术，包括PagedAttention（分页注意力）、连续批处理、量化加速等。这些优化技术可以显著提升推理吞吐量和降低延迟。

graph TD
    A[接收请求] --> B[调度分配]
    B --> C[Worker执行]
    C --> D[模型前向]
    D --> E[采样输出]
    E --> F{是否结束?}
    F -->|No| D
    F -->|Yes| G[返回结果]
                

九、技术栈

vllm-ascend基于多种先进技术构建，这些技术共同支撑了NPU上的高性能推理。下面介绍每个技术组件的作用和特点。

Python是项目的主要开发语言，提供了丰富的库和工具支持。Python的易用性和快速开发特性使得项目能够快速迭代和扩展。

PyTorch是深度学习框架，提供张量计算和自动微分功能。PyTorch的动态计算图特性使得模型开发和调试更加方便。

CANN是华为昇腾计算框架，提供NPU的底层计算支持。CANN包含了丰富的算子库和优化工具，能够充分发挥NPU的计算能力。

vLLM是高性能推理引擎，提供PagedAttention、连续批处理等优化技术。vllm-ascend作为插件，将这些优化技术扩展到NPU平台。

Triton是内核编译器，用于编写和优化GPU内核。triton-ascend是Triton的昇腾版本，支持在NPU上编写高性能内核。

Ray是分布式框架，提供分布式计算和任务调度支持。Ray使得vllm-ascend能够轻松部署在多机多卡环境中。

十、硬件支持

vllm-ascend支持多种华为昇腾NPU硬件，覆盖从推理到训练的多种场景。不同的硬件具有不同的计算能力和内存容量，用户可以根据实际需求选择合适的硬件。

Atlas 800I A2：面向推理场景的高性能NPU，具有大容量HBM内存和高计算密度，适合部署大规模语言模型。

Atlas A2 Training：面向训练场景的NPU，支持高吞吐量的训练任务，适合模型微调和预训练。

Atlas 800I A3：新一代推理NPU，相比A2有显著的性能提升，支持更先进的计算特性。

Atlas A3 Training：新一代训练NPU，提供更强的计算能力和更大的内存容量。

Atlas 300I Duo：双芯NPU，通过两个芯片协同工作，提供更高的计算性能。

graph LR
    A[昇腾NPU] --> B[Atlas 800I A2]
    A --> C[Atlas A2 Training]
    A --> D[Atlas 800I A3]
    A --> E[Atlas A3 Training]
    A --> F[Atlas 300I Duo]
                

十一、模块协作关系（核心：用户是怎么用的）

前面介绍了各个模块，但最关键的问题是：这些模块跟用户加载模型、执行推理到底是什么关系？下面用一个完整的时序图展示从用户指定模型名称到获得推理结果的全过程，每个模块在什么时候被调用、做了什么，一目了然。

11.1 用户视角：加载模型的完整流程

当用户在vLLM中指定一个模型名称（如"DeepseekV4ForCausalLM"）时，系统会自动完成以下步骤：首先models模块在注册表中查找这个模型名称，找到对应的类路径；然后动态导入模型类并实例化；接着加载预训练权重；最后将模型交给worker模块执行推理。整个过程对用户是透明的，用户只需要指定模型名称即可。

sequenceDiagram
    participant U as 用户
    box rgb(255,243,205) 上游vLLM
    participant E as vLLM Engine
    participant W as Worker
    end
    box rgb(212,237,218) 本项目vllm-ascend
    participant M as models模块
    participant A as attention模块
    participant O as ops模块
    end
    participant N as NPU设备
    
    U->>E: 指定模型名称
    E->>M: 查找并导入模型
    M-->>E: 返回模型对象
    E->>W: 传入模型
    W->>A: 选择注意力后端
    W->>O: 初始化算子
    
    U->>E: 发送推理请求
    E->>W: 调度到Worker
    W->>O: 调用算子
    W->>A: 计算注意力
    A->>N: NPU执行
    N-->>A: 结果
    A-->>W: 输出
    W-->>E: 返回
    E-->>U: 推理结果
                

# 1. models模块注册模型（vllm_ascend/models/__init__.py）
def register_model():
    ModelRegistry.register_model(
        "DeepseekV4ForCausalLM",
        "vllm_ascend.models.deepseek_v4:AscendDeepseekV4ForCausalLM",
    )

# 2. 模型类定义（vllm_ascend/models/deepseek_v4/model.py）
class AscendDeepseekV4ForCausalLM(torch.nn.Module):
    def __init__(self, config):
        # 创建模型结构
        self.layers = nn.ModuleList([...])
    
    def forward(self, input_ids):
        # 前向传播
        return hidden_states

# 3. Worker调用模型（vllm/v1/worker/gpu_worker.py）
class Worker:
    def execute_model(self, input_ids):
        return self.model_runner.execute(input_ids)

# 4. ModelRunner执行（vllm_ascend/worker/model_runner_v1.py）
class NPUModelRunner:
    def execute(self, input_ids):
        # 调用attention和ops模块
        for layer in self.model.layers:
            hidden_states = layer.attention(hidden_states)
            hidden_states = layer.feed_forward(hidden_states)
        return logits

11.2 每个模块到底做了什么

下面的表格清晰展示了每个模块在用户操作中的具体作用：

11.3 为什么需要这些模块

简单来说，models负责"是什么模型"，worker负责"怎么跑模型"，attention负责"怎么算注意力"，ops负责"怎么加速计算"，distributed负责"怎么多卡协作"，quantization负责"怎么省显存"。

它们之间的关系可以用一句话概括：用户指定模型名称 → models找到模型 → worker创建执行环境 → attention和ops提供计算能力 → distributed处理多卡通信 → quantization优化内存和速度。

graph LR
    A[用户: 指定模型名称] --> B[models: 这是什么模型?]
    B --> C[worker: 怎么跑这个模型?]
    C --> D[attention: 怎么算注意力?]
    C --> E[ops: 怎么加速计算?]
    C --> F[distributed: 怎么多卡协作?]
    C --> G[quantization: 怎么省显存?]
    
    D --> H[NPU执行计算]
    E --> H
    F --> H
    G --> H
    
    H --> I[返回推理结果给用户]
                

11.4 一个具体例子：加载DeepSeek V4

假设用户要推理DeepSeek V4模型，下面是具体的模块协作过程：

1. 用户指定 "model=DeepseekV4ForCausalLM"

2. models模块在注册表中找到 "vllm_ascend.models.deepseek_v4.model:AscendDeepseekV4ForCausalLM"

3. models模块动态导入这个类，调用__init__创建模型结构，加载预训练权重

4. worker模块接收模型对象，创建ModelRunner

5. attention模块检测到DeepSeek使用MLA，选择AscendMLABackend

6. ops模块初始化RMSNorm、SiluAndMul等自定义算子

7. distributed模块如果使用多卡，会建立NPU间的通信链接

8. 用户发送推理请求，worker调用ops和attention在NPU上执行计算

9. 推理完成，结果返回给用户

sequenceDiagram
    participant U as 用户
    box rgb(212,237,218) 本项目vllm-ascend
    participant M as models
    participant W as worker
    participant A as attention(MLA)
    participant O as ops(RMSNorm等)
    end
    participant N as NPU
    
    U->>M: model="DeepseekV4ForCausalLM"
    M->>M: 查找注册表
    M->>M: 动态导入并加载权重
    M-->>W: 返回模型对象
    W->>A: 选择AscendMLABackend
    W->>O: 初始化算子
    
    loop 每个token
        U->>W: 发送输入
        W->>O: RMSNorm归一化
        W->>A: MLA注意力计算
        A->>N: NPU执行
        N-->>A: 注意力结果
        W->>O: FFN前馈网络
        W-->>U: 输出token
    end
                

# 1. DeepSeek V4模型注册（vllm_ascend/models/__init__.py）
ModelRegistry.register_model(
    "DeepseekV4ForCausalLM",
    "vllm_ascend.models.deepseek_v4.model:AscendDeepseekV4ForCausalLM",
)

# 2. DeepSeek V4模型类（vllm_ascend/models/deepseek_v4/model.py）
class AscendDeepseekV4ForCausalLM(torch.nn.Module):
    def __init__(self, config):
        # MLA注意力层
        self.layers = nn.ModuleList([
            DeepseekV4Layer(config) for _ in range(config.num_hidden_layers)
        ])
    
    def forward(self, input_ids):
        hidden_states = self.embed_tokens(input_ids)
        for layer in self.layers:
            hidden_states = layer(hidden_states)
        return hidden_states

# 3. MLA注意力后端（vllm_ascend/attention/mla.py）
class AscendMLABackend:
    def forward(self, hidden_states):
        # 多头潜在注意力计算
        attn_output = self.attn(hidden_states)
        return attn_output

# 4. RMSNorm算子（vllm_ascend/ops/rmsnorm.py）
def rms_norm(x, weight):
    # NPU优化的RMSNorm
    return ascend_rms_norm(x, weight)