作者：昇腾实战派

背景概述

Tile Language 是一种面向高性能计算的领域特定语言，基于 TVM 编译器基础设施，结合类 Python 的简洁语法，旨在降低 GPU/CPU 及 NPU 上高性能算子开发的复杂度。

其 Ascend 变体——Tilelang Ascend，专为昇腾 NPU 架构优化，支持 GEMM、向量运算与注意力机制等核心算子的高效实现。编译器后端支持两种技术路线： Ascend C & PTO 和 AscendNPU IR 。

本文档针对开发者在实际部署过程中遇到的环境配置难题，提供可复现、稳定运行的完整搭建方案，涵盖 ascendc_pto 与 npuir 两种后端技术路线，助力快速进入开发状态。

环境准备

• 操作系统：Ubuntu 24.04 LTS aarch64
• 容器镜像：swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.11
• 开发主机：支持 NPU 的服务器（如 Atlas 800I 推理服务器）
• 工作目录：在 /home 下创建个人目录，例如 /home/developer

---

一、创建容器环境

1. 检查镜像是否存在

docker images | grep 8.5.0

2. 启动容器

docker run -it --shm-size=1000g --privileged -uroot --net=host --name tilelang-test \
--device=/dev/davinci0 \
--device=/dev/davinci1 \
--device=/dev/davinci2 \
--device=/dev/davinci3 \
--device=/dev/davinci4 \
--device=/dev/davinci5 \
--device=/dev/davinci6 \
--device=/dev/davinci7 \
--device=/dev/davinci_manager \
--device=/dev/devmm_svm \
--device=/dev/hisi_hdc \
-v /dev/shm:/dev/shm \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/common \
-v /usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/driver/lib64/driver \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /home/developer:/home \
<image-id> \
/bin/bash

注：<image-id> 为实际镜像 ID，可通过 docker images 查看。

---

二、获取并配置 Tilelang Ascend 源码

1. 克隆主仓库

git clone https://github.com/tile-ai/tilelang-ascend.git
cd tilelang-ascend

2. 修复子模块仓库地址（关键步骤）

.gitmodules 文件中 catlass 仓库地址指向错误源（gitee），需手动修改为 gitcode：

vim .gitmodules

将以下内容：

[submodule "third_party/catlass"]
    path = third_party/catlass
    url = https://gitee.com/tile-ai/catlass.git

替换为：

[submodule "third_party/catlass"]
    path = third_party/catlass
    url = https://gitcode.com/tile-ai/catlass.git

保存后执行：

git submodule sync
git submodule update --init --recursive

✅ 成功后应看到 third_party/catlass 已正确下载。

---

三、安装依赖与构建环境

1. 安装系统依赖

apt update && apt upgrade -y
apt install -y clang libzstd-dev zlib1g-dev

2. 安装 Python 依赖

pip install torch_npu ninja PyYAML

---

四、编译 Tilelang（按分支选择）

✅ 方案一：ascendc_pto 分支

bash install_ascend.sh
cd build
make

✅ 方案二：npuir 分支

注意：install_npuir.sh 中存在静默编译问题，需启用详细输出以定位错误。

修改编译命令以显示错误信息

编辑 install_npuir.sh 文件，找到第 158 行的 make 命令，添加 VERBOSE=1：

make VERBOSE=1

此操作可确保在编译失败时输出完整错误日志，便于排查缺失依赖。

执行安装脚本：

bash install_npuir.sh
cd build
make

---

五、配置运行环境

编译完成后，设置环境变量：

# 设置 CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh    # CANN 8.3
source /usr/local/Ascend/cann-8.5.0/set_env.sh        # CANN 8.5

# 解决 TVM 与 ACL 冲突
export ACL_OP_INIT_MODE=1

# （可选）启用 IR 输出用于调试
export TILELANG_DUMP_IR=1

# 设置 Tilelang 路径
export PYTHONPATH=$(pwd)
export TL_ROOT=$(pwd)

---

六、环境验证

进入示例目录并运行测试：

cd examples/gemm
python example_gemm.py

✅ 预期输出（ascendc_pto 分支）：

init successful!
Kernel Output Match!

✅ 预期输出（npuir 分支）：

AscendNPU IR OPT success
AscendNPU IR compile success:
...
All check passed.

输出匹配即表示环境搭建成功，可开始开发高性能算子。

---

常见问题

1. .gitmodules内三方库URL错误

直接执行

1
git clone --recursive https://github.com/tile-ai/tilelang-ascend.git

会报错如下：

2. 编译过程中缺库

问题现象为编译tilelang到99%后返回错误码ERROR2。

解决方案

1. .gitmodules内三方库URL错误

先不下载三方库，只下载tilelang-ascend

git clone https://github.com/tile-ai/tilelang-ascend.git -b npuir

然后修改.gitmodules文件，将catlass地址修改正确即可

vim .gitmodules

\#将catlass仓库从gitee改为gitcode，如下图

git submodule sync

git submodule update --init --recursive

2. 编译过程中缺库

Makefile 136行

由于有 $(MAKESILENT) 所以我们看不到任何错误信息

所以需要在Make时加上 VERBOSE=1，确保我们可以看到错误输出。具体代码在 install_npuir.sh的第158行，在make 后加上 “VERBOSE=1”即可

后续看到明确错误提示缺库后，安装库即可。

apt update && apt upgrade

pip install torch_npu ninja PyYAML

apt install clang

apt-get install libzstd-dev zlib1g-dev