1. 六个仓库摆在面前，为什么一条 kernel 都跑不起来

DeepSeek 把昇腾相关的六个仓库一次性开源出来，这件事在圈子里传得挺快。我第一时间把六个仓库全 clone 到本地，想着怎么也能跑通一个算子看看效果，结果折腾了大半天，一条 kernel 都没真正跑起来。这不是我手生，而是这套东西的定位和很多人第一眼的预期之间，存在一道不小的认知鸿沟。

先把这六个仓库的性质说清楚。它们不是那种 clone 下来pip install就能用的应用级项目，而是围绕昇腾 AI 处理器做底层适配和算子实现的工程集合。核心关键词就三个：DeepSeek、昇腾、CANN。DeepSeek 提供模型侧的算法与结构，昇腾是华为的 AI 加速硬件平台，CANN 则是昇腾上的异构计算架构，相当于硬件和上层框架之间的那层"翻译官"。六个仓库里，有的是算子实现，有的是通信库适配，有的是推理框架的对接层，还有的是构建脚本和工具链配置。

为什么跑不起来？因为这类仓库的默认假设是：你手上已经有一台装好驱动、装好 CANN、配好环境变量的昇腾机器。它不负责帮你从零搭环境，它假设环境已经在了。而绝大多数人（包括我）拿到仓库的第一反应是"先跑个 demo 看看"，这个动作在普通开源项目里没问题，在这类底层工程里几乎必然失败。

这篇文章我想干的事很明确：把这六个仓库到底在做什么、彼此什么关系、为什么本地跑不通、想跑通需要补哪些前置条件，一条条拆开讲。适合两类人看——一类是手里真有昇腾设备、想把这套东西用起来的工程同学；另一类是暂时没设备、但想搞明白昇腾软件栈长什么样的学习者。前者能拿到可操作的排查路径，后者能建立一张完整的认知地图，不至于被六个仓库的名字绕晕。

2. 先把六个仓库的角色理清楚，别急着敲命令

2.1 昇腾软件栈的分层逻辑

要理解这六个仓库，得先知道昇腾的软件栈是怎么分层的。从下往上大致是这么几层：最底下是硬件和驱动，往上是 CANN（包含运行时、算子库、图编译器），再往上是各种框架适配层（PyTorch、MindSpore 等），最上面才是模型和应用。

DeepSeek 开源的这六个仓库，绝大部分落在中间那两层——CANN 算子层和框架适配层。这就解释了为什么它们不能独立运行：它们本来就是"中间件"，上游要接框架，下游要接 CANN，两头都不在自己手里，单独拎出来当然跑不动。

打个比方，这就像有人开源了一套汽车变速箱的齿轮图纸。图纸很完整，但你把它放在客厅地板上，它不会自己转起来。你得有发动机、有底盘、有油路，齿轮才能发挥作用。六个仓库就是这套"齿轮"，昇腾机器和 CANN 就是"发动机和底盘"。

2.2 六个仓库各自的定位

虽然具体仓库名会随版本变化，但从功能维度看，这六个仓库基本覆盖了这么几类角色：

这张表是我自己按功能归的类，不是官方分类，但用它来理解"为什么跑不起来"特别管用。你会发现，除了文档仓库，其余五个都有硬性的运行时依赖。你缺了 CANN，算子库编译都过不去；你缺了 HCCL，通信库连头文件都找不到。

2.3 为什么"读完"和"跑通"是两件事

很多人有个误区：以为把 README 读完、把依赖列表看一遍，就算"掌握了"。在这类底层工程里，读和跑之间隔着一条河。

读的时候你看到的是"这个算子实现了什么数学语义"，跑的时候你面对的是"这个算子在当前 CANN 版本下能不能编译、编译出来的 kernel 能不能在 A2 卡上加载、加载后数值对不对"。这三步每一步都可能卡住，而且卡住的原因往往不在仓库本身，而在环境。

我踩过的第一个坑就是版本。仓库 README 里写的 CANN 版本是某个具体号段，我本地装的是另一个号段，结果算子编译脚本里调用的一个头文件路径对不上，直接报找不到符号。这种问题你读一百遍 README 也读不出来，只有真去编译才会撞上。

提示：拿到这类仓库，第一件事不是 clone，而是先确认你手上的 CANN 版本和仓库要求的版本是否在同一个兼容区间。版本错配是最高频的失败原因，没有之一。

3. 环境这道坎：CANN、驱动、固件三件套缺一不可

3.1 CANN 到底装了什么

CANN 不是一个单一软件，它是一整套工具链的集合。装完之后，你的机器上会多出这些东西：算子编译工具、图编译运行时、算子库、通信库、性能分析工具、以及一堆环境变量脚本。这些东西分散在好几个目录里，靠set_env.sh之类的脚本串起来。

关键点在于：CANN 的安装和驱动、固件的安装是分开的，而且有严格的先后顺序。正确顺序是先装驱动，再装固件，最后装 CANN。顺序错了，轻则 CANN 装不上，重则驱动和固件版本不匹配导致设备识别异常。

我见过有人图省事，直接装 CANN 跳过驱动，结果npu-smi info命令压根不认设备。这时候你去翻 CANN 的日志，它会告诉你"找不到设备"，但不会告诉你"因为你没装驱动"。这种报错信息的不友好，是底层工具链的通病，得靠经验补。

3.2 驱动与固件的版本对齐

驱动和固件必须版本对齐，这是硬性要求。所谓对齐，不是版本号一模一样，而是它们属于同一个发布批次。华为的发布节奏是驱动、固件、CANN 三者配套发布，你从同一个发布说明里拿到的三个包，基本就是对齐的。

怎么验证对齐？装完之后跑npu-smi info，看输出的驱动版本和固件版本。如果这两个版本号差距很大，或者其中一个显示异常，那基本就是没对齐。这时候别急着往下走，先把版本问题解决掉，否则后面所有步骤都是白费。

3.3 环境变量为什么总配不对

CANN 装完后，环境变量是重灾区。它需要设置的不只是 PATH，还有LD_LIBRARY_PATH、ASCEND_HOME_PATH、PYTHONPATH里的一堆路径。少设一个，编译时可能不报错，运行时才崩。

我的做法是：永远用官方提供的set_env.sh脚本，不要自己手写 export。手写容易漏，而且不同 CANN 版本需要的变量名可能变。用官方脚本，它内部会处理好所有路径拼接。你只需要在~/.bashrc里 source 一下这个脚本就行。

# 假设 CANN 装在 /usr/local/Ascend source /usr/local/Ascend/ascend-toolkit/set_env.sh

source 完之后，用echo $ASCEND_HOME_PATH验证一下，能打印出正确路径才算配好。这一步看着简单，但它是后面所有编译和运行的前提。

注意：如果你在容器里跑，环境变量的继承规则和宿主机不一样。容器启动时如果没把 CANN 的路径挂进去，容器内 source 脚本会失败。这种情况要么在容器启动参数里挂载，要么在容器内重新装一遍 CANN。

4. 算子编译：从源码到能加载的 kernel 中间发生了什么

4.1 算子编程模型的基本概念

昇腾上的算子开发和 CUDA 那套思路有相似之处，但细节差别很大。核心概念有这么几个：算子原型定义、Tiling 策略、Kernel 实现、算子信息库。

算子原型定义描述的是这个算子"长什么样"——输入几个、输出几个、什么数据类型、什么形状。Tiling 策略决定的是"怎么切分计算"——大张量怎么分块、分多少块、每块多大。Kernel 实现是真正在 AI Core 上跑的代码。算子信息库则是给图编译器看的"说明书"，告诉它这个算子支持哪些输入组合。

这四个部分缺一不可。你只写了 Kernel 实现，没有 Tiling 策略，算子编译能过，但运行时可能因为切分不合理而性能极差，甚至直接失败。

4.2 编译流程拆解

一个昇腾算子的编译，大致走这么几步：

1. 算子原型编译，生成算子描述文件
2. Tiling 代码编译，生成 Tiling 动态库
3. Kernel 代码编译，生成在 AI Core 上执行的二进制
4. 算子信息库编译，生成图编译器能读的配置
5. 打包成算子包，安装到 CANN 的算子目录

每一步都有对应的构建脚本。六个仓库里的构建工具链仓库，干的就是把这些脚本串起来的事。你如果手动一步步跑，很容易漏掉某一步，导致最后算子加载失败。

我踩过的坑是第 4 步。算子信息库没编译进去，结果图编译器根本不认识这个算子，报"unsupported op"。这个报错特别有迷惑性，因为它看起来像是算子没实现，实际上是信息库没注册。

4.3 编译参数怎么选

编译参数里最关键的是目标芯片型号。昇腾有多个系列，不同系列的 AI Core 架构不一样，编译时必须指定正确的SOC_VERSION。指定错了，编译能过，但生成的二进制在目标卡上加载不了。

常见的 SOC_VERSION 取值需要查你手上设备的型号。这个值不是随便填的，填错了编译产物就是废的。我的建议是：先用npu-smi info确认设备型号，再去 CANN 文档里查对应的 SOC_VERSION 字符串，别凭记忆填。

另一个关键参数是优化级别。调试阶段建议用低优化级别，方便定位问题；性能测试阶段再开高优化。一上来就开最高优化，出了问题你连是哪一步崩的都找不到。

5. 跑不起来的典型症状与排查路径

5.1 症状一：编译期找不到头文件

这是最常见的。报错信息通常是fatal error: xxx.h: No such file or directory。原因基本是 CANN 环境变量没配好，或者 CANN 版本和仓库要求的不一致。

排查顺序：先echo $ASCEND_HOME_PATH确认路径存在，再去那个路径下find一下报错的头文件在不在。如果头文件在，但编译器找不到，那就是 include 路径没传对，检查构建脚本里的 include 参数。如果头文件压根不在，那就是 CANN 版本不对，换版本。

5.2 症状二：链接期找不到符号

报错是undefined reference to xxx。这通常意味着某个库没链接上。昇腾的库分好几种，有运行时的、有算子的、有通信的。你得确认构建脚本里链接的库列表是否完整。

我遇到过一次，是通信库没链接，因为我的构建配置里默认关掉了多卡支持。单卡编译不需要通信库，但仓库的默认配置假设你要多卡，所以链接脚本里带了通信库的引用。这种"默认配置和实际需求不匹配"的问题，改配置就能解决。

5.3 症状三：运行期算子加载失败

编译都过了，一跑就报算子加载失败。这种最头疼，因为编译期没问题，说明代码本身是对的，问题出在运行环境。

常见原因有三个：算子包没安装到 CANN 的算子目录、算子信息库没注册、目标设备型号和编译时指定的不一致。排查方法是先确认算子包安装路径，再确认信息库文件存在，最后确认设备型号。

5.4 症状四：数值结果不对

最隐蔽的一种。算子能跑，不报错，但算出来的结果和预期对不上。这种问题往往出在 Tiling 策略或者数据类型处理上。

排查思路：先用小尺寸输入测，排除切分问题；再用单一数据类型测，排除类型转换问题；最后对比 CPU 参考实现，定位是哪一步开始偏的。这个过程很磨人，但没办法，数值问题只能靠二分定位。

提示：这张表建议存下来。昇腾算子开发里 80% 的问题都能归到这几类，按表排查比盲目搜索快得多。

6. 没有昇腾设备，这套东西还能怎么学

6.1 读代码能学到什么

没设备不代表这套仓库没价值。恰恰相反，算子实现代码本身是很好的学习材料。你能看到工业级的算子是怎么写的：怎么处理边界条件、怎么设计 Tiling、怎么用向量化指令。这些东西和你有没有设备无关，读懂了就是你的。

我的建议是挑一个相对简单的算子（比如逐元素运算类），把它的原型定义、Tiling、Kernel 三部分对着看一遍。看完你对昇腾算子开发的全流程就有概念了。

6.2 用模拟器能跑到什么程度

CANN 提供了算子模拟执行的能力，可以在没有真实设备的情况下验证算子的功能正确性。模拟器能跑通逻辑，但跑不出真实性能。所以它能帮你验证"算得对不对"，但验证不了"算得快不快"。

对于学习目的，模拟器够用了。你能把算子编译、加载、执行的完整链路走一遍，理解每个环节在干什么。这比纯读代码的收获大得多。

6.3 建立认知地图比跑通更重要

说到底，这六个仓库最大的价值不是让你立刻跑出一个 kernel，而是让你看清昇腾软件栈的全貌。你知道算子在哪一层、通信在哪一层、框架对接在哪一层，以后遇到具体问题就知道该往哪个方向查。

这种认知地图的建立，比跑通一个 demo 重要得多。demo 跑通了可能只是运气好环境对了，认知地图建立了才是真的懂了。

7. 几个我踩过的坑和对应的经验

第一个坑是盲目相信 README 的依赖列表。README 里列的依赖往往是最小集合，实际编译时可能还需要一些隐式依赖。我的做法是：先按 README 装，报错了再补，别一开始就想把所有依赖装全，那样容易装出一堆版本冲突。

第二个坑是在错误的目录下执行构建脚本。昇腾的构建脚本很多是假设你在特定目录下执行的，换个目录就找不到相对路径。执行前先pwd确认一下，别想当然。

第三个坑是忽略日志。昇腾工具链的日志分好几级，默认级别往往只打印错误，不打印警告。有些问题在警告级别就有提示，你调高日志级别能看到更多线索。构建失败时，先把日志级别调到 debug 再看一遍。

第四个坑是版本混用。有人图方便，驱动用 A 版本，CANN 用 B 版本，觉得差不多就行。这种混用在简单场景可能没事，一旦涉及算子编译就必出问题。老老实实按配套版本装，省下的时间远比折腾的时间多。

第五个坑是不验证环境就开跑。装完环境后，先跑官方提供的最小验证用例，确认环境是通的，再去编译你要的算子。跳过验证直接上，出了问题你分不清是环境问题还是代码问题。

8. 这套开源对做底层适配的人意味着什么

从工程角度看，DeepSeek 把昇腾适配的六个仓库开源，最大的意义是把原本黑盒的适配层摊开了。以前做昇腾适配，很多细节只能靠猜或者靠官方支持，现在代码摆在那，你能看到具体怎么实现的。

对做算子优化的人来说，这是好事。你能参考工业级的实现来优化自己的算子。对做框架对接的人来说，这也是好事。你能看到框架图是怎么落到昇腾执行引擎上的。

但也要清醒：开源不等于开箱即用。这套东西的门槛在于环境，而环境这块恰恰是开源代码覆盖不到的。你得自己有设备、自己配环境、自己踩坑。开源给你的是"怎么做"的答案，但"能不能做"取决于你的环境。

我个人的体会是，这类底层开源项目的正确打开方式是：先花时间把环境搞通，再花时间把代码读懂，最后才是动手改。顺序反了，就会陷入"代码读了一堆但一条都跑不起来"的困境。这不是项目的问题，是打开方式的问题。

最后分享一个实用的小习惯：每次动这类仓库之前，先建一个环境快照或者记录当前的环境变量和版本号。出了问题能快速回滚，也能对比出是哪一步改动导致的。这个习惯帮我省过好几次重装环境的时间。