Ascend Setup and Usage¶

总览¶

Ascend Backend 依赖 Ascend CANN、ATB 运行时和对应头文件/库文件。当前文档面向 mllm/backends/ascend、examples/qwen_ascend 和 tests/ascend 的开发与验证流程。

环境要求¶

运行或编译 Ascend Backend 前，需要确认：

已安装可用的 Ascend CANN 环境。
已安装 ATB，并能找到 ATB 头文件和库。
编译器、CMake、Python 依赖满足 mLLM 基础构建要求。
目标设备上可以正常访问 Ascend NPU。

使用 ACL 和 ATB 前，需要加载 Ascend Toolkit 和 ATB 的环境脚本：

source <ASCEND_TOOLKIT_ROOT>/set_env.sh
source <ATB_ROOT>/set_env.sh

其中 <ASCEND_TOOLKIT_ROOT> 是 Ascend Toolkit 的安装入口目录，<ATB_ROOT> 是 ATB 的安装入口目录。开发机上可以把这两行加入 ~/.bashrc，新开的交互式 shell 会自动加载；CI、非交互式脚本或新机器上仍建议在构建/运行前显式加载。

当前验证使用的版本：

组件	版本
Ascend Toolkit / CANN	`8.2.RC1`，组件版本号 `8.2.0.0.201`
ATB	`8.2.RC1.B150`，平台 `aarch64`

常用环境变量如下：

变量	说明
`ASCEND_HOME_PATH`	Ascend CANN 安装路径，测试目标会读取其 include/lib。
`ATB_HOME_PATH`	ATB 安装路径，测试目标会读取其 include/lib。

构建¶

当前 Ascend 开发路径使用仓库中的构建任务：

pip install -r requirements.txt
python task.py tasks/build_arm_ascend.yaml

该任务会打开 Ascend Backend，并同时启用 Arm Backend：

-DMLLM_BUILD_ASCEND_BACKEND=ON
-DMLLM_BUILD_ARM_BACKEND=ON

如果手动配置 CMake，至少需要确保 MLLM_BUILD_ASCEND_BACKEND 被打开，并且 CANN/ATB 头文件与库路径能被 CMake 找到。

Qwen Ascend 示例¶

Qwen Ascend 示例目标为 mllm-qwen-ascend-runner，入口文件位于 examples/qwen_ascend/main.cpp。示例会在加载权重前先执行 model.to(kAscend)，这样 Ascend Linear 算子可以直接读取模型文件中的 W8A8 量化参数。

默认模式是 QA generation：

./mllm-qwen-ascend-runner \
  -m /path/to/model.mllm \
  -c /path/to/config.json \
  -t /path/to/tokenizer.json \
  -p "请用一句话介绍你自己。" \
  -g 64

参数说明：

参数	说明
`-m` / `--model_path`	mLLM 模型文件路径。
`-c` / `--config_path`	Qwen Ascend 配置文件路径。
`-t` / `--tokenizer_path`	tokenizer json 路径，QA generation 必填。
`-p` / `--prompt`	输入问题。
`-g` / `--max_new_tokens`	最大生成 token 数。
`-mv` / `--model_version`	模型文件版本，默认 `v2`。

也可以运行 synthetic forward smoke test：

./mllm-qwen-ascend-runner \
  -m /path/to/model.mllm \
  -c /path/to/config.json \
  --forward_smoke_test \
  -s 8

该模式只构造简单 token 序列，适合快速确认模型 forward、权重加载和设备执行链路。

运行测试¶

Ascend 单测目标为 Mllm-Test-AscendKernel，测试代码位于 tests/ascend。

测试覆盖内容包括：

基础 ATB 算子：Add、Sub、Mul、Linear、RMSNorm、Softmax、Transpose、Concat、Slice、SiLU。
ACLNN 辅助算子：Cast、Abs、MaxDim、broadcast RealDiv/Mul。
模型相关算子：Embedding、RoPE、CausalMask、Attention、GQA。
Graph 路径：GraphBuilder、Linear graph、Linear+Softmax graph、CausalMask plugin graph。
W8A8 路径：activation quantization 到 ATB Linear W8A8 的端到端 pipeline。

常用开关¶

环境变量	说明
`MLLM_ASCEND_QWEN_DECODER_GRAPH`	控制 Qwen Ascend decoder graph，默认开启；设为 `0` 可回退 eager 路径。
`MLLM_ASCEND_QWEN_DECODER_GRAPH_SETUP_BUCKET`	decoder graph attention setup bucket 大小。
`MLLM_ASCEND_ENABLE_DYNAMIC_W8A8`	打开 dynamic eager W8A8 调试路径，默认关闭。

注意事项¶

Dynamic W8A8 eager 路径仅用于精度和调试验证，不是默认推理路径。
Decoder graph 是 Qwen Ascend 的默认优化路径；遇到 graph 问题时可通过 MLLM_ASCEND_QWEN_DECODER_GRAPH=0 回退到 eager 路径定位。