摘要：Ascend C 是华为昇腾 AI 处理器上的原生算子开发语言，采用 C/C++ 语法扩展，支持 Tiling、SPMD 并行模型等高级特性。搭建一个稳定、高效的开发环境是开启 Ascend C 之旅的第一步。本文将详细介绍从硬件检查、系统依赖安装、CANN Toolkit 部署，到第一个 "Hello World" 工程编译运行的全流程。本文档内容覆盖了 910A/910B 等主流训练芯片及 310P 推理芯片。

参考资源：

AscendNPU-IR GitCode 仓库

昇腾社区官方文档

Ascend C 算子开发指南

一、 环境准备与硬件兼容性深度解析

在开始安装软件栈之前，首先需要确认硬件环境以及底层驱动是否就绪。昇腾软件栈（CANN）对驱动版本有严格的配套要求，版本不匹配将直接导致运行时错误。

官网的资料最精华也是最权威的，在搭建环境这种问题上，我们直接找官方的资料就可以快速入门了。

Gitcode里面的docs可以找到构建指南：

cke_38793.png

1. 硬件支持列表

Ascend C 目前主要支持以下硬件平台：

  • Atlas 训练系列：Atlas 800 训练服务器 (型号 9000/9010), Atlas 300T 训练卡。核心芯片为 Ascend 910A / 910B。
  • Atlas 推理系列：Atlas 300I Pro 推理卡, Atlas 300V 视频解析卡。核心芯片为 Ascend 310P (注意：老款 Ascend 310 对 Ascend C 的支持有限，建议查阅最新文档)。

2. 操作系统要求

推荐使用以下 LTS 版本 Linux 发行版：

  • Ubuntu 20.04.x LTS / 22.04.x LTS (x86_64 / aarch64)
  • EulerOS 2.8 / 2.9 / 2.10 (aarch64)
  • CentOS 7.6 / 8.2 (x86_64 / aarch64)

3. 驱动与固件检查 (npu-smi)

使用 npu-smi 工具检查 NPU 设备状态。这是最基础也是最关键的一步。

cke_65675.png

常见问题：

  • 如果执行 npu-smi 提示 command not found，说明驱动未安装或未添加路径。
  • 如果 Health 显示 Alarm 或其他错误，请联系系统管理员检查硬件连接或重新安装驱动。

二、 依赖软件的安装与配置陷阱

CANN Toolkit 依赖于一系列系统库和 Python 包。如果依赖缺失，安装脚本可能会报错，或者在编译算子时出现莫名其妙的链接错误。

1. 系统级依赖 (apt/yum)

以 Ubuntu 为例，需要安装 gcc, g++, make, cmake, zlib, openssl 等基础工具。

Bash

# 更新源

sudo apt-get update

# 安装基础编译工具

sudo apt-get install -y gcc g++ make cmake zlib1g zlib1g-dev openssl libsqlite3-dev libssl-dev libffi-dev unzip pciutils net-tools libblas-dev gfortran libblas3

# 检查 CMake 版本

cmake --version

# 注意：Ascend C 编译通常要求 CMake >= 3.16。如果系统默认版本过低，请通过源码编译安装最新版 CMake。

安装运行过程：

cke_92523.png

2. Python 环境依赖

CANN 深度依赖 Python，用于模型转换（ATC）和算子编译。

  • 版本要求：Python 3.7.0 ~ 3.9.x (推荐 3.7.5 或 3.9.2)。
  • 必装包：attrs, numpy, decorator, sympy, cffi, pyyaml, pathlib2, protobuf, scipy, requests.

Bash

# 升级 pip

python3 -m pip install --upgrade pip

# 安装 Python 依赖

pip3 install attrs numpy decorator sympy cffi pyyaml pathlib2 protobuf scipy requests

三、 CANN Toolkit 的全量安装流程

CANN  是昇腾 AI 处理器的软件栈核心，包含了编译器 (CCEC)、运行时 (Runtime)、算子库 (OPP) 等关键组件。

1. 获取安装包

访问昇腾社区或通过命令行下载对应架构（aarch64 或 x86_64）的 Ascend-cann-toolkit 安装包。

文件名格式通常为：Ascend-cann-toolkit_{version}_linux-{arch}.run。

安装toolkit 的步骤和流程在官网也可以找到对应的资料：

cke_119522.png

2. 执行安装

使用 root 用户或 sudo 权限执行安装脚本。建议使用 --install 参数进行全量安装。

Bash

# 赋予执行权限

chmod +x Ascend-cann-toolkit_8.0.RC1_linux-aarch64.run

# 执行安装

./Ascend-cann-toolkit_8.0.RC1_linux-aarch64.run --install

安装路径说明：

  • 默认安装路径：/usr/local/Ascend/ascend-toolkit
  • 该目录下通常会有 latest 软链接，指向当前安装的版本。我们在配置环境变量时，推荐使用 latest，这样后续升级版本时无需修改配置文件。

cke_146504.png

四、 环境变量的配置艺术与验证

很多初学者安装完 CANN 后，发现编译命令找不到，或者运行时报错，90% 的原因都是环境变量未生效或配置混乱。

1. 核心环境变量解析

我们需要将 CANN 的关键路径添加到系统的查找路径中。

  • ASCEND_HOME: CANN 安装根目录，后续变量引用的基准。
  • PATH: 添加 bin 目录，以便能直接运行 atc, ccec 等命令。
  • LD_LIBRARY_PATH: 添加 lib64 目录，确保程序运行时能找到动态链接库（.so）。
  • PYTHONPATH: 添加 Python 库路径，确保 Python 脚本能 import te, topi 等模块。
  • ASCEND_OPP_PATH: 算子库路径，自定义算子编译时需要用到。

2. 修改 .bashrc

建议将以下内容写入用户目录下的 .bashrc 文件：

Bash

# Ascend CANN Toolkit 环境变量

export ASCEND_HOME=/usr/local/Ascend/ascend-toolkit/latest

export PATH=${ASCEND_HOME}/bin:${ASCEND_HOME}/compiler/ccec_compiler/bin:${PATH}

export LD_LIBRARY_PATH=${ASCEND_HOME}/lib64:${LD_LIBRARY_PATH}

export PYTHONPATH=${ASCEND_HOME}/python/site-packages:${PYTHONPATH}

export ASCEND_OPP_PATH=${ASCEND_HOME}/opp

export ASCEND_AICPU_PATH=${ASCEND_HOME}

# 可选：开启算子调测日志 (0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR)

export ASCEND_GLOBAL_LOG_LEVEL=3

# 可选：将日志直接输出到屏幕

export ASCEND_SLOG_PRINT_TO_STDOUT=1

cke_169274.png

五、 构建第一个 Ascend C 算子工程

环境就绪后，我们不急着跑大模型，先通过一个最小化的 CMake 工程来验证开发环境是否完备。我们将实现一个简单的 Add 算子。

1. 工程目录结构

一个标准的 Ascend C 工程建议采用如下结构，清晰分离主机侧（Host）和设备侧（Kernel）代码。

cke_192050.png

2. 核心代码实现

文件 src/add_custom.cpp (Kernel 实现)：

C++

#include "kernel_operator.h"

using namespace AscendC;

constexpr int32_t TOTAL_LENGTH = 8 * 1024;                            // 总数据量

constexpr int32_t TILE_NUM = 8;                                       // 切分数量

constexpr int32_t BLOCK_LENGTH = TOTAL_LENGTH / TILE_NUM;             // 每个 Tile 数据量

class KernelAdd {

public:

    __aicore__ inline void Init(GM_ADDR x, GM_ADDR y, GM_ADDR z) {

        // 初始化 Global Memory 地址

        xGm.SetGlobalBuffer((__gm__ half*)x + BLOCK_LENGTH * GetBlockIdx(), BLOCK_LENGTH);

        yGm.SetGlobalBuffer((__gm__ half*)y + BLOCK_LENGTH * GetBlockIdx(), BLOCK_LENGTH);

        zGm.SetGlobalBuffer((__gm__ half*)z + BLOCK_LENGTH * GetBlockIdx(), BLOCK_LENGTH);

        // 初始化 Pipe 和 Queue

        pipe.InitBuffer(inQueueX, BUFFER_NUM, BLOCK_LENGTH * sizeof(half));

        pipe.InitBuffer(inQueueY, BUFFER_NUM, BLOCK_LENGTH * sizeof(half));

        pipe.InitBuffer(outQueueZ, BUFFER_NUM, BLOCK_LENGTH * sizeof(half));

    }

    __aicore__ inline void Process() {

        // 循环处理每个 Tile

        for (int32_t i = 0; i < TILE_NUM; i++) {

            CopyIn(i);

            Compute(i);

            CopyOut(i);

        }

    }

private:

    // ... CopyIn, Compute, CopyOut 具体实现略 (使用 DataCopy, Add 指令) ...

};

extern "C" __global__ __aicore__ void add_custom(GM_ADDR x, GM_ADDR y, GM_ADDR z) {

    KernelAdd op;

    op.Init(x, y, z);

    op.Process();

}

文件 src/main.cpp (Host 调用)：

C++

#include "acl/acl.h"

// ... ACL 初始化、Device 申请、内存拷贝、Kernel Launch 代码 ...

// 核心调用：

// aclrtLaunchKernel(functionName, blockDim, args, stream);

3. CMakeLists.txt 编写

这是构建系统的灵魂。需要特别注意 include_directories 和 link_libraries。

CMake

cmake_minimum_required(VERSION 3.16)

project(AscendCDemo)

# 设置 CANN 路径

if(DEFINED ENV{ASCEND_HOME})

    set(ASCEND_HOME $ENV{ASCEND_HOME})

else()

    set(ASCEND_HOME "/usr/local/Ascend/ascend-toolkit/latest")

endif()

include_directories(${ASCEND_HOME}/include)

link_directories(${ASCEND_HOME}/lib64)

add_executable(ascend_c_demo src/main.cpp src/add_custom.cpp)

# 链接 ACL 运行时库

target_link_libraries(ascend_c_demo ascendcl acl_op_compiler)

六、 编译运行与调试技巧

最后一步，进行代码编译和上板运行。

1. 编译流程

创建一个 build 目录进行外部构建，保持源码目录整洁。

Bash

mkdir build

cd build

cmake ..

make -j4

2. 运行验证

运行生成的可执行文件。如果一切正常，你将看到类似下面的输出：

cke_219110.png

3. 调试技巧

  • Printf 调试：Ascend C 支持在 Kernel 侧使用 PRINTF 宏（需包含 kernel_operator.h），日志会输出到 Host 端屏幕（需设置 ASCEND_SLOG_PRINT_TO_STDOUT=1）。
  • 模拟仿真：如果没有 NPU 硬件，可以使用 CPU 模拟运行模式（Camodel），在 CMake 中添加 -DASCEND_COMPUTE_UNIT=cpu（具体取决于 CANN 版本支持情况）。

七、 总结

通过上面这一整套流程，整个 Ascend C 的开发环境就从零搭建好了——从硬件检测、依赖准备、安装 CANN Toolkit，一直到环境变量配置、示例算子的编译和运行，都已经能够完整走通。做到这一步，已经具备开展原生 Ascend C 算子开发的基础条件。

在接下来的算子编写过程中，可以继续对照 CANN 提供的算子库（OPP）、官方示例工程以及 Ascend C 的开发手册，逐步深入诸如 Tiling 设计、算子 Pipeline、已有算子的复用、性能调优 等更进阶的内容。随着昇腾硬件和软件栈不断更新，保持开发环境和文档的同步，也会让后续调试和构建更加顺畅。

# 人工智能
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

NVIDIA迁移昇腾踩坑记：为何数据拷贝成了“背锅侠”？（附1.5s→0.7s优化复盘）

本次小模型迁移性能调优实战，从最初的性能衰退到最终的超越原平台性能，整个过程充满了技术挑战和发现。最关键的是，我们打破了直觉的误导，通过科学的Profiling分析找到了真正的性能瓶颈。目前CANN的迭代速度很快，建议大家在迁移时如果遇到性能瓶颈，不要死磕代码逻辑，先跑一遍Profiler，大概率能帮你省下几天排查时间。如果常规手段搞不定，试试Torchair或者MindIE这种针对性的推理后端，

avatar 人工智能6S服务平台
cover

关于与鸿蒙HarmonyOS共同成长路上的技术提升与总结

avatar 人工智能6S服务平台
cover

从GPU到NPU：大模型部署的新选择——MindSpeed-LLM实战全记录

avatar 人工智能6S服务平台