前言昇腾NPU上的CANN生态里有一个cann-learning-hub仓库。你刚开始学 CANN昇腾 AI 计算神经网络。你想写一个 CANN 程序比如用 AscendCL 做图像分类推理。你打开 CANN 的官方文档——文档很全但太多、太散你不知道从哪篇开始读。你希望有一个入口能让你快速找到跟我场景匹配的 Sample、“跟我问题匹配的方案”、“跟我水平适配的教程”。昇腾 CANN 生态里有一个开源社区学习中心叫做cann-learning-hub。它专门用来集中管理 CANN 生态的学习资源教程、博客、竞赛、样例。一、cann-learning-hub 的内容结构与查找方法仓库组织方式按算子类别组织 Sample、按应用场景组织教程cann-learning-hub的仓库组织方式是按算子类别组织 Sample比如samples/ops-nn/ops-nn 算子的 Sample、samples/ge/GE 融合算子的 Sample、samples/hccl/hccl 通信算子的 Sample、等等。按应用场景组织教程比如tutorials/inference/推理场景的教程、tutorials/training/训练场景的教程、tutorials/distributed/分布式场景的教程、等等。博客和竞赛blogs/技术博客、competitions/竞赛题目和答案。快速找到你需要的 Sample用关键词搜索 按 CANN 版本过滤方法 1用关键词搜索推荐。你可以git clone这个仓库到本地然后用grep或者rgripgrep搜索关键词。比如你想找图像分类推理的 Samplegitclone https://atomgit.com/cann/cann-learning-hub.gitcdcann-learning-hub rg图像分类samples/方法 2按 CANN 版本过滤。每个 Sample 的 README 里都会标注适用的 CANN 版本比如CANN 7.0。你可以根据自己环境的 CANN 版本过滤掉不适用的 Sample。比如你的环境是 CANN 6.0那就要找 README 里标注CANN 6.0的 Sample不要找CANN 7.0的 Sample因为不兼容。哪些 Sample 是必读的ops-nn 基础 Sample、GE 融合 Sample、hccl 通信 Sample如果你是 CANN 新手建议先读这 3 类 Sampleops-nn 基础 Sample教你如何调用 ops-nn 的算子比如卷积、池化、激活函数等。这是 CANN 程序的基础几乎所有 CANN 程序都要调 ops-nn 的算子。GE 融合 Sample教你如何写 GE 融合算子把多个算子融合成一个提升性能。这是 CANN 性能调优的关键。hccl 通信 Sample教你如何做分布式训练/推理用 hccl 做梯度同步、参数同步。这是 CANN 分布式场景的基础。关键点不是所有 Sample 都适合你的 CANN 版本——技能文件中提到的兼容性过滤问题技能文件里提到了兼容性问题——这不是Sample 写得不好是你的 CANN 版本和 Sample 要求的 CANN 版本不匹配。比如Sample 要求CANN 7.0因为用了 CANN 7.0 新增的 API但你的环境是CANN 6.0那这个 Sample 就跑不通会报API 不存在的错。解决方案按 CANN 版本过滤 Sample前面讲过。不要强行跑要求 CANN 版本高于你的环境的 Sample——要么升级 CANN要么换一个 Sample。二、在昇腾 910B2 上运行第一个 Sample 的完整流程硬件环境确认npu-smi info查看设备信息和 CANN 版本步骤 1用npu-smi info确认 NPU 设备信息。npu-smi info输出应该能看到你的 NPU 设备比如昇腾 910B2。如果看不到那可能是驱动没装好或者 NPU 设备没插好。步骤 2查看 CANN 版本。cat/usr/local/Ascend/CANN/VERSION输出应该能看到 CANN 的版本号比如7.0.0。记下来后面要用来过滤 Sample。Sample 选择选一个 PyTorch 接口的 Sample兼容性最好建议你选一个PyTorch 接口的 Sample兼容性最好。因为 PyTorch 接口的 Sample对 CANN 版本的依赖比较低PyTorch 是 Python 接口比较稳定。比如samples/ops-nn/conv2d_pytorch/卷积算子的 PyTorch 接口 Sample。逐步运行环境准备 → 依赖安装 → 编译如需 → 运行 → 解读输出步骤 1环境准备。确认 CANN 环境变量已经设置echo$ASCEND_HOMEecho$PATHecho$LD_LIBRARY_PATH如果没有设置要先设置把下面内容加到~/.bashrc或者~/.zshrcexportASCEND_HOME/usr/local/AscendexportPATH$ASCEND_HOME/CANN/bin:$PATHexportLD_LIBRARY_PATH$ASCEND_HOME/CANN/lib64:$LD_LIBRARY_PATH步骤 2依赖安装。PyTorch 接口的 Sample需要安装torch和torch_npu昇腾适配的 PyTorch。pipinstalltorch torch_npu步骤 3编译如需。如果这个 Sample 包含自定义算子需要编译成 .o 文件那就要编译。否则不需要编译直接运行。比如samples/ops-nn/conv2d_pytorch/不需要编译直接用 PyTorch 接口调算子。但samples/ascendc/conv2d_custom/需要编译自定义算子。步骤 4运行。cdsamples/ops-nn/conv2d_pytorch/ python inference.py步骤 5解读输出。运行后会输出推理结果比如分类 top-1 的类别和置信度。你要确认推理结果是对的比如输入一张猫的图片输出是猫的类别。踩坑预警Sample 的 README 中的 CANN 版本要求和你的环境不匹配时别直接放弃——先试export ASCEND_RT_VISIBLE_DEVICES0技能文件里提到了一个救命命令export ASCEND_RT_VISIBLE_DEVICES0。具体来说如果 Sample 的 README 里要求CANN 7.0但你的环境是CANN 6.0那不要直接放弃——先试这个命令exportASCEND_RT_VISIBLE_DEVICES0这个命令的作用是指定只用 1 张 NPU 卡Device 0。有些 Sample 跑不通是因为默认用多卡你的环境可能只有 1 张卡指定只用 1 张卡后就能跑通了。如果还是跑不通那再考虑升级 CANN或者换一个 Sample。三、Sample 兼容性问题的诊断与解决问题 1ascendc 自定义算子 Sample 编译失败返回E19999现象运行bash build.sh编译自定义算子返回错误码E19999并且输出ASCENDC operator compilation failed。原因CANN 版本 7.0不支持该算子这个算子是 CANN 7.0 新增的。解决方案 A升级 CANN 到 7.0。方案 B换一个 Sample选一个要求CANN 6.0的 Sample。问题 2AICPU 自定义算子 Sample 推理结果为全零现象运行 Sample 的推理脚本输出结果全是 0比如分类结果全是 0置信度全是 0.0。原因没有注册算子二进制文件.o 文件。AICPU 自定义算子需要把编译好的 .o 文件注册到 CANN 的算子库里。如果没有注册那推理时就会找不到算子输出全零。解决按照 Sample 的 README 中的算子注册步骤操作。一般来说是运行一个register_op.sh脚本cdsamples/aicpu/your_op/bashregister_op.sh问题 3ACL 接口 Sample 在多 batch 场景下 QPS 很低现象运行 ACL 接口 SampleC 接口在多 batch 场景下比如batch size 32QPS每秒查询数很低比如只有 100 QPS。原因没有设置dynamic batch参数。ACL 接口默认是固定 batch size的——如果你要跑多 batch就要在模型转换时指定--dynamic_batch_size。解决在模型转换时指定--dynamic_batch_size。比如你的模型是 ONNX 格式要转成 CANN 的离线模型.om 文件atc--modelyour_model.onnx--framework5--outputyour_model--soc_versionAscend910B2--dynamic_batch_size1,4,8,16,32这样转换出来的 .om 文件就支持动态 batch size1、4、8、16、32。推理时你可以根据输入 batch size动态选择。四、基于 Sample 改编从跑通到用在生产环境第一步理解 Sample 的数据流输入 → 预处理 → 推理 → 后处理要改编 Sample首先要理解 Sample 的数据流。数据流一般是输入读取输入数据比如图片文件、文本文件、等等。预处理把输入数据转成模型需要的格式比如图片 resize、归一化、转成 tensor、等等。推理把预处理后的数据送给模型推理调 ACL 接口或者 PyTorch 接口。后处理把推理结果转成人类可读的格式比如分类结果转成类别 置信度、检测框画到图片上、等等。你要读懂 Sample 的代码搞清楚每一步在干什么“数据格式是什么”“用的什么 API”。第二步替换为你自己的模型和数据集理解完 Sample 的数据流后就可以替换为你自己的模型和数据集了替换模型把 Sample 里的模型比如ResNet-50换成你自己的模型比如YOLOv8。要注意模型的输入/输出格式可能跟 Sample 不一样要改预处理和后处理。替换数据集把 Sample 里的数据集比如ImageNet换成你自己的数据集比如你的业务数据。要注意数据集的格式可能跟 Sample 不一样要改数据读取和预处理。第三步性能测试——对比 Sample 默认配置 vs 你的生产配置的延迟/吞吐替换完模型和数据集后要做性能测试测试 Sample 默认配置的延迟/吞吐用 Sample 原来的模型数据集跑一遍记录延迟单张推理的时间和吞吐每秒推理的张数。测试你的生产配置的延迟/吞吐用你自己的模型数据集跑一遍记录延迟和吞吐。对比看你的生产配置是不是比 Sample 默认配置慢很多。如果是那就要调优比如开 AOE 调优、用 GE 融合算子、调大 batch size、等等。关键点Sample 的价值不是直接用是理解 CANN 程序的标准写法Sample 的价值不是直接用到生产环境因为 Sample 是演示用的不是生产级的。Sample 的价值是帮你理解 CANN 程序的标准写法。比如ACL 接口 Sample教你怎么用 ACL API 写 CANN 程序标准的初始化、内存申请、推理、内存释放流程。PyTorch 接口 Sample教你怎么用 PyTorch 接口写 CANN 程序标准的 Dataset、DataLoader、Model、推理流程。GE 融合 Sample教你怎么写 GE 融合算子标准的算子注册、算子融合、性能测试流程。读懂了 Sample 的代码你就会写标准的 CANN 程序了不会写出野路子的代码。五、贡献自己的 Sample 到 cann-learning-hub社区贡献流程Fork → 开发 → 本地测试 → 提交 PR → Code Review如果你想把自己写的 CANN 程序比如一个很好的图像分类 Sample贡献给 cann-learning-hub让更多人用到那流程是Fork在 atomgit.com 上把cann/cann-learning-hub仓库 fork 到你的账号下。开发在你的 fork 里开发你的 Sample写代码、写 README、写测试用例。本地测试在你的环境里跑通你的 Sample确保代码可运行、结果正确。提交 PRPull Request把你的 fork 里的修改提交 PR 到cann/cann-learning-hub仓库。Code Reviewcann-learning-hub 的维护者会 review 你的 PR检查代码质量、README 完整性、CANN 版本标注是否清楚。如果 review 通过你的 PR 就会被合并你的 Sample 就正式进入 cann-learning-hub 了。Sample 的质量标准代码可运行、README 完整、CANN 版本标注清楚你的 Sample 要被合并必须满足 3 个质量标准代码可运行别人在任何满足 CANN 版本要求的环境下能跑通你的 Sample不会编译失败、不会运行崩溃、不会输出错误结果。README 完整README 里要包含Sample 的用途、适用的 CANN 版本、环境准备步骤、依赖安装步骤、编译步骤如需、运行步骤、输出解读、常见问题解决。CANN 版本标注清楚README 里要明确标注适用的 CANN 版本比如CANN 7.0。这样别人就不会用不兼容的 CANN 版本来跑你的 Sample。关键点技能文件中提到的社区贡献的内容经过审核后整合进来——所以别担心质量不够好技能文件里提到了社区贡献的内容经过审核后整合进来。也就是说你提交的 PR会有维护者帮你 review检查代码质量、README 完整性、CANN 版本标注是否清楚。如果 review 发现问题维护者会给你反馈让你修改。你修改后再提交 PR直到 review 通过。所以别担心我的 Sample 质量不够好——只要你愿意贡献维护者会帮你提升质量的。使用前 vs 使用后效率对比表格假设你是 CANN 新手要写一个 CANN 程序比如图像分类推理。你在两个方案下做使用前自己从头写 CANN 程序不看 Sample靠猜。使用后先跑通 cann-learning-hub 里的官方 Sample再改编成自己的程序。下面是概括性描述的效率对比表格不捏造具体数字对比维度使用前自己从头写 CANN 程序靠猜使用后先跑通官方 Sample 再改编效率提升开发效率低需要大量试错高有可运行的基础代码显著改善兼容性风险高容易踩版本坑低Sample 经过测试社区验证价值性能调优起点从零开始有基线可对比迭代优化关键为什么会有这个效率提升核心原因有三个有可运行的基础代码使用后你不需要从零开始写不用自己摸索 CANN API 的调用顺序、内存申请释放流程、等等。你直接在 Sample 的代码上改改模型、改数据集、改预处理后处理开发效率就高了。Sample 经过测试cann-learning-hub 里的 Sample都是经过测试的维护者会确保 Sample 在指定的 CANN 版本下能跑通。所以你用 Sample就不会踩版本不兼容的坑兼容性风险低。有基线可对比使用后你有一个性能基线Sample 默认配置的延迟/吞吐。你改编后的程序如果比基线慢很多那你就知道要调优了性能调优有方向。代码段 1运行第一个 Sample 的完整命令行记录# 1. 克隆 cann-learning-hub 仓库gitclone https://atomgit.com/cann/cann-learning-hub.gitcdcann-learning-hub# 2. 查看 NPU 设备信息和 CANN 版本npu-smi infocat/usr/local/Ascend/CANN/VERSION# 3. 设置 CANN 环境变量如果还没设置exportASCEND_HOME/usr/local/AscendexportPATH$ASCEND_HOME/CANN/bin:$PATHexportLD_LIBRARY_PATH$ASCEND_HOME/CANN/lib64:$LD_LIBRARY_PATH# 4. 安装依赖PyTorch 接口的 Samplepipinstalltorch torch_npu# 5. 进入 Sample 目录选一个 PyTorch 接口的 Samplecdsamples/ops-nn/conv2d_pytorch/# 6. 运行 Samplepython inference.py# 7. 解读输出应该能看到推理结果比如分类 top-1 的类别和置信度这段代码展示了运行第一个 Sample的完整命令行。关键点git clone把 cann-learning-hub 仓库克隆到本地。npu-smi info和cat /usr/local/Ascend/CANN/VERSION查看 NPU 设备信息和 CANN 版本用来过滤 Sample。设置 CANN 环境变量确保 CANN 的二进制和库能被找到。pip install torch torch_npu安装 PyTorch 和昇腾适配的 PyTorchPyTorch 接口的 Sample 需要。cd samples/ops-nn/conv2d_pytorch/进入 Sample 目录选了一个 PyTorch 接口的 Sample。python inference.py运行 Sample推理。解读输出确保推理结果是对的比如输入猫的图片输出猫的类别。代码段 2三个兼容性问题的诊断和解决命令行记录# 问题 1ascendc 自定义算子 Sample 编译失败返回E19999# 诊断查看 CANN 版本cat/usr/local/Ascend/CANN/VERSION# 假设输出是 6.0.0# 解决升级 CANN 到 7.0或者换一个 Sample# 这里选择换一个 Samplecd../../cdsamples/ops-nn/conv2d_pytorch/# 换一个不依赖 CANN 7.0 的 Sample# 问题 2AICPU 自定义算子 Sample 推理结果为全零# 诊断检查算子是否已经注册ls$ASCEND_HOME/CANN/opp/opproto/aicpu/# 如果看不到你的算子 proto 文件那就是没有注册# 解决运行 register_op.sh 注册算子cdsamples/aicpu/your_op/bashregister_op.sh# 问题 3ACL 接口 Sample 在多 batch 场景下 QPS 很低# 诊断查看模型转换命令是否指定了 --dynamic_batch_sizecatbuild.sh|grepatc# 如果看不到 --dynamic_batch_size那就是没有指定# 解决修改 build.sh在 atc 命令里加上 --dynamic_batch_size# 比如--dynamic_batch_size1,4,8,16,32vimbuild.sh# 修改完后重新编译bashbuild.sh这段代码展示了三个兼容性问题的诊断和解决的命令行。关键点问题 1 的诊断和解决用cat /usr/local/Ascend/CANN/VERSION查看 CANN 版本。如果版本低于 Sample 要求的版本就升级 CANN 或者换一个 Sample。问题 2 的诊断和解决用ls $ASCEND_HOME/CANN/opp/opproto/aicpu/检查算子是否已经注册。如果看不到就运行register_op.sh注册。问题 3 的诊断和解决用cat build.sh | grep atc查看模型转换命令是否指定了--dynamic_batch_size。如果没有就修改build.sh加上--dynamic_batch_size然后重新编译。代码段 3基于 Sample 改编的完整流程代码替换模型数据集# 基于 samples/ops-nn/conv2d_pytorch/ 改编替换模型数据集importtorchimporttorch_npufromtorchvisionimportdatasets,transformsfromyour_modelimportYourModel# 你自己的模型# 1. 替换模型从 ResNet-50 换成你自己的模型YourModelmodelYourModel()model.load_state_dict(torch.load(your_model.pth))model.eval()model.npu()# 2. 替换数据集从 ImageNet 换成你自己的数据集YourDatasettransformtransforms.Compose([transforms.Resize((224,224)),transforms.ToTensor(),transforms.Normalize(mean[0.485,0.456,0.406],std[0.229,0.224,0.225])])datasetdatasets.ImageFolder(your_dataset/,transformtransform)dataloadertorch.utils.data.DataLoader(dataset,batch_size32,shuffleFalse)# 3. 推理跟 Sample 一样的流程withtorch.no_grad():forimages,labelsindataloader:imagesimages.npu()outputsmodel(images)# 后处理把推理结果转成人类可读的格式_,predstorch.max(outputs,1)print(fPredicted:{preds.cpu().numpy()}, Ground Truth:{labels.numpy()})# 4. 性能测试对比 Sample 默认配置 vs 你的生产配置的延迟/吞吐# 这里省略性能测试代码可以用 torch.utils.benchmark 来测这段代码展示了基于 Sample 改编的完整流程替换模型数据集。关键点替换模型把 Sample 里的 ResNet-50换成你自己的模型YourModel。要注意模型的输入/输出格式可能跟 Sample 不一样要改预处理和后处理。替换数据集把 Sample 里的 ImageNet换成你自己的数据集YourDataset。要注意数据集的格式可能跟 Sample 不一样要改数据读取和预处理。推理流程跟 Sample 一样的流程模型设为 eval 模式、放到 NPU 上、前向推理、后处理。性能测试对比 Sample 默认配置和你的生产配置的延迟/吞吐可以用torch.utils.benchmark来测。代码段 4提交 Sample 贡献的 git 命令行记录# 1. Fork cann-learning-hub 仓库在 atomgit.com 上操作# 2. 克隆你的 fork 到本地gitclone https://atomgit.com/your_username/cann-learning-hub.gitcdcann-learning-hub# 3. 创建新分支用来开发你的 Samplegitcheckout-badd_your_sample# 4. 开发你的 Sample写代码、写 README、写测试用例mkdirsamples/your_category/your_sample/# 把你的代码、README、测试用例放到这个目录里# 5. 本地测试确保代码可运行、结果正确cdsamples/your_category/your_sample/ python inference.py# 确保输出正确# 6. 提交到你的 forkgitadd.gitcommit-mAdd your_sample: 你的 Sample 的描述gitpush origin add_your_sample# 7. 提交 PR在 atomgit.com 上操作# 8. 等待 Code Review维护者会给你反馈# 9. 根据反馈修改如需# 10. PR 被合并你的 Sample 正式进入 cann-learning-hub这段代码展示了提交 Sample 贡献的 git 命令行。关键点Fork在 atomgit.com 上操作把cann/cann-learning-hubfork 到你的账号下。克隆你的 fork把你的 fork 克隆到本地。创建新分支不要直接在main分支上开发创建一个新分支比如add_your_sample。开发你的 Sample在你的分支上写代码、写 README、写测试用例。本地测试确保代码可运行、结果正确。提交到你的 fork用git add、git commit、git push提交到你的 fork。提交 PR在 atomgit.com 上操作提交 PR 到cann/cann-learning-hub仓库。等待 Code Review维护者会 review 你的 PR检查代码质量、README 完整性、CANN 版本标注是否清楚。根据反馈修改如果 review 发现问题维护者会给你反馈让你修改。你修改后再提交 PR直到 review 通过。PR 被合并你的 Sample 正式进入 cann-learning-hub别人都能用到你的 Sample 了。总结这篇文章从 cann-learning-hub 的内容结构讲起到在昇腾 910B2 上运行第一个 Sample、Sample 兼容性问题的诊断与解决、基于 Sample 改编从跑通到用在生产环境最后给出了贡献自己的 Sample 到 cann-learning-hub的完整流程。核心要点回顾cann-learning-hub 是CANN 生态的入口集中管理学习资源教程、博客、竞赛、样例。找 Sample 的方法用关键词搜索按 CANN 版本过滤。运行第一个 Sample 的流程环境准备 → 依赖安装 → 编译如需 → 运行 → 解读输出。Sample 兼容性问题的诊断和解决看错误现象 → 找原因 → 解决升级 CANN、注册算子、指定 dynamic batch 参数。基于 Sample 改编的流程理解数据流 → 替换模型和数据集 → 性能测试。贡献 Sample 到 cann-learning-hub 的流程Fork → 开发 → 本地测试 → 提交 PR → Code Review。cann-learning-hub 在昇腾生态中的定位是学习资源的入口和集散地。如果你刚接触 CANN建议先花 2 小时把 cann-learning-hub 里的 Sample 过一遍不用全跑看代码就行——这样你就能快速理解 CANN 程序的标准写法避免从零开始摸索的低效。给新手的行动建议先花 2 小时把全部 Sample 过一遍不用全跑看代码就行。这样你就能快速找到跟你场景匹配的 Sample、“跟你问题匹配的方案”、“跟你水平适配的教程”。仓库链接https://atomgit.com/cann/cann-learning-hub附加代码段Sample查找和筛选的Python脚本# 从 cann-learning-hub 仓库中查找与图像分类相关的 Sampleimportosimportredeffind_samples(keyword):查找包含关键词的 Sampleresults[]forroot,dirs,filesinos.walk(.):forfileinfiles:iffile.endswith(.md)orfile.endswith(.py):filepathos.path.join(root,file)withopen(filepath,r,encodingutf-8)asf:textf.read()ifkeywordintext:results.append(filepath)returnresults# 查找图像分类相关的 Samplesamplesfind_samples(图像分类)print(f找到{len(samples)}个相关 Sample:)forsampleinsamples:print(f -{sample})这段脚本展示了如何从 cann-learning-hub 仓库中查找 Sample。关键点os.walk(.)递归遍历当前目录下的所有文件。if file.endswith(.md) or file.endswith(.py)只检查 Markdown 文件和 Python 文件Sample 的 README 是 .md代码是 .py。if keyword in text检查文件内容是否包含关键词。应用场景当你想找某个关键词的 Sample 时可以运行这个脚本不用手动翻 cann-learning-hub 仓库。附加代码段Sample 兼容性自动检测脚本# 自动检测 Sample 的 CANN 版本要求并与当前环境对比importreimportosdefcheck_sample_compatibility(sample_dir):检查 Sample 的兼容性# 读取 README.mdreadme_pathos.path.join(sample_dir,README.md)ifnotos.path.exists(readme_path):returnNone,README.md 不存在withopen(readme_path,r,encodingutf-8)asf:readmef.read()# 提取 CANN 版本要求version_matchre.search(rCANN\s*\s*(\d\.\d),readme)ifnotversion_match:returnNone,未找到 CANN 版本要求required_versionversion_match.group(1)# 读取当前环境的 CANN 版本withopen(/usr/local/Ascend/CANN/VERSION,r)asf:current_versionf.read().strip()# 对比版本iffloat(current_version)float(required_version):returnTrue,f兼容当前版本{current_version} 要求版本{required_version}else:returnFalse,f不兼容当前版本{current_version} 要求版本{required_version}# 检查当前目录下的所有 Sampleforsampleinos.listdir(.):ifos.path.isdir(sample):compatible,msgcheck_sample_compatibility(sample)ifcompatibleisnotNone:print(f{sample}:{msg})仓库链接https://atomgit.com/cann/cann-learning-hub
昇腾CANN学习资源中心cann-learning-hub深度技术剖析：从Sample查找运行到社区贡献的完整实战指南
发布时间：2026/6/10 20:16:07
前言昇腾NPU上的CANN生态里有一个cann-learning-hub仓库。你刚开始学 CANN昇腾 AI 计算神经网络。你想写一个 CANN 程序比如用 AscendCL 做图像分类推理。你打开 CANN 的官方文档——文档很全但太多、太散你不知道从哪篇开始读。你希望有一个入口能让你快速找到跟我场景匹配的 Sample、“跟我问题匹配的方案”、“跟我水平适配的教程”。昇腾 CANN 生态里有一个开源社区学习中心叫做cann-learning-hub。它专门用来集中管理 CANN 生态的学习资源教程、博客、竞赛、样例。一、cann-learning-hub 的内容结构与查找方法仓库组织方式按算子类别组织 Sample、按应用场景组织教程cann-learning-hub的仓库组织方式是按算子类别组织 Sample比如samples/ops-nn/ops-nn 算子的 Sample、samples/ge/GE 融合算子的 Sample、samples/hccl/hccl 通信算子的 Sample、等等。按应用场景组织教程比如tutorials/inference/推理场景的教程、tutorials/training/训练场景的教程、tutorials/distributed/分布式场景的教程、等等。博客和竞赛blogs/技术博客、competitions/竞赛题目和答案。快速找到你需要的 Sample用关键词搜索 按 CANN 版本过滤方法 1用关键词搜索推荐。你可以git clone这个仓库到本地然后用grep或者rgripgrep搜索关键词。比如你想找图像分类推理的 Samplegitclone https://atomgit.com/cann/cann-learning-hub.gitcdcann-learning-hub rg图像分类samples/方法 2按 CANN 版本过滤。每个 Sample 的 README 里都会标注适用的 CANN 版本比如CANN 7.0。你可以根据自己环境的 CANN 版本过滤掉不适用的 Sample。比如你的环境是 CANN 6.0那就要找 README 里标注CANN 6.0的 Sample不要找CANN 7.0的 Sample因为不兼容。哪些 Sample 是必读的ops-nn 基础 Sample、GE 融合 Sample、hccl 通信 Sample如果你是 CANN 新手建议先读这 3 类 Sampleops-nn 基础 Sample教你如何调用 ops-nn 的算子比如卷积、池化、激活函数等。这是 CANN 程序的基础几乎所有 CANN 程序都要调 ops-nn 的算子。GE 融合 Sample教你如何写 GE 融合算子把多个算子融合成一个提升性能。这是 CANN 性能调优的关键。hccl 通信 Sample教你如何做分布式训练/推理用 hccl 做梯度同步、参数同步。这是 CANN 分布式场景的基础。关键点不是所有 Sample 都适合你的 CANN 版本——技能文件中提到的兼容性过滤问题技能文件里提到了兼容性问题——这不是Sample 写得不好是你的 CANN 版本和 Sample 要求的 CANN 版本不匹配。比如Sample 要求CANN 7.0因为用了 CANN 7.0 新增的 API但你的环境是CANN 6.0那这个 Sample 就跑不通会报API 不存在的错。解决方案按 CANN 版本过滤 Sample前面讲过。不要强行跑要求 CANN 版本高于你的环境的 Sample——要么升级 CANN要么换一个 Sample。二、在昇腾 910B2 上运行第一个 Sample 的完整流程硬件环境确认npu-smi info查看设备信息和 CANN 版本步骤 1用npu-smi info确认 NPU 设备信息。npu-smi info输出应该能看到你的 NPU 设备比如昇腾 910B2。如果看不到那可能是驱动没装好或者 NPU 设备没插好。步骤 2查看 CANN 版本。cat/usr/local/Ascend/CANN/VERSION输出应该能看到 CANN 的版本号比如7.0.0。记下来后面要用来过滤 Sample。Sample 选择选一个 PyTorch 接口的 Sample兼容性最好建议你选一个PyTorch 接口的 Sample兼容性最好。因为 PyTorch 接口的 Sample对 CANN 版本的依赖比较低PyTorch 是 Python 接口比较稳定。比如samples/ops-nn/conv2d_pytorch/卷积算子的 PyTorch 接口 Sample。逐步运行环境准备 → 依赖安装 → 编译如需 → 运行 → 解读输出步骤 1环境准备。确认 CANN 环境变量已经设置echo$ASCEND_HOMEecho$PATHecho$LD_LIBRARY_PATH如果没有设置要先设置把下面内容加到~/.bashrc或者~/.zshrcexportASCEND_HOME/usr/local/AscendexportPATH$ASCEND_HOME/CANN/bin:$PATHexportLD_LIBRARY_PATH$ASCEND_HOME/CANN/lib64:$LD_LIBRARY_PATH步骤 2依赖安装。PyTorch 接口的 Sample需要安装torch和torch_npu昇腾适配的 PyTorch。pipinstalltorch torch_npu步骤 3编译如需。如果这个 Sample 包含自定义算子需要编译成 .o 文件那就要编译。否则不需要编译直接运行。比如samples/ops-nn/conv2d_pytorch/不需要编译直接用 PyTorch 接口调算子。但samples/ascendc/conv2d_custom/需要编译自定义算子。步骤 4运行。cdsamples/ops-nn/conv2d_pytorch/ python inference.py步骤 5解读输出。运行后会输出推理结果比如分类 top-1 的类别和置信度。你要确认推理结果是对的比如输入一张猫的图片输出是猫的类别。踩坑预警Sample 的 README 中的 CANN 版本要求和你的环境不匹配时别直接放弃——先试export ASCEND_RT_VISIBLE_DEVICES0技能文件里提到了一个救命命令export ASCEND_RT_VISIBLE_DEVICES0。具体来说如果 Sample 的 README 里要求CANN 7.0但你的环境是CANN 6.0那不要直接放弃——先试这个命令exportASCEND_RT_VISIBLE_DEVICES0这个命令的作用是指定只用 1 张 NPU 卡Device 0。有些 Sample 跑不通是因为默认用多卡你的环境可能只有 1 张卡指定只用 1 张卡后就能跑通了。如果还是跑不通那再考虑升级 CANN或者换一个 Sample。三、Sample 兼容性问题的诊断与解决问题 1ascendc 自定义算子 Sample 编译失败返回E19999现象运行bash build.sh编译自定义算子返回错误码E19999并且输出ASCENDC operator compilation failed。原因CANN 版本 7.0不支持该算子这个算子是 CANN 7.0 新增的。解决方案 A升级 CANN 到 7.0。方案 B换一个 Sample选一个要求CANN 6.0的 Sample。问题 2AICPU 自定义算子 Sample 推理结果为全零现象运行 Sample 的推理脚本输出结果全是 0比如分类结果全是 0置信度全是 0.0。原因没有注册算子二进制文件.o 文件。AICPU 自定义算子需要把编译好的 .o 文件注册到 CANN 的算子库里。如果没有注册那推理时就会找不到算子输出全零。解决按照 Sample 的 README 中的算子注册步骤操作。一般来说是运行一个register_op.sh脚本cdsamples/aicpu/your_op/bashregister_op.sh问题 3ACL 接口 Sample 在多 batch 场景下 QPS 很低现象运行 ACL 接口 SampleC 接口在多 batch 场景下比如batch size 32QPS每秒查询数很低比如只有 100 QPS。原因没有设置dynamic batch参数。ACL 接口默认是固定 batch size的——如果你要跑多 batch就要在模型转换时指定--dynamic_batch_size。解决在模型转换时指定--dynamic_batch_size。比如你的模型是 ONNX 格式要转成 CANN 的离线模型.om 文件atc--modelyour_model.onnx--framework5--outputyour_model--soc_versionAscend910B2--dynamic_batch_size1,4,8,16,32这样转换出来的 .om 文件就支持动态 batch size1、4、8、16、32。推理时你可以根据输入 batch size动态选择。四、基于 Sample 改编从跑通到用在生产环境第一步理解 Sample 的数据流输入 → 预处理 → 推理 → 后处理要改编 Sample首先要理解 Sample 的数据流。数据流一般是输入读取输入数据比如图片文件、文本文件、等等。预处理把输入数据转成模型需要的格式比如图片 resize、归一化、转成 tensor、等等。推理把预处理后的数据送给模型推理调 ACL 接口或者 PyTorch 接口。后处理把推理结果转成人类可读的格式比如分类结果转成类别 置信度、检测框画到图片上、等等。你要读懂 Sample 的代码搞清楚每一步在干什么“数据格式是什么”“用的什么 API”。第二步替换为你自己的模型和数据集理解完 Sample 的数据流后就可以替换为你自己的模型和数据集了替换模型把 Sample 里的模型比如ResNet-50换成你自己的模型比如YOLOv8。要注意模型的输入/输出格式可能跟 Sample 不一样要改预处理和后处理。替换数据集把 Sample 里的数据集比如ImageNet换成你自己的数据集比如你的业务数据。要注意数据集的格式可能跟 Sample 不一样要改数据读取和预处理。第三步性能测试——对比 Sample 默认配置 vs 你的生产配置的延迟/吞吐替换完模型和数据集后要做性能测试测试 Sample 默认配置的延迟/吞吐用 Sample 原来的模型数据集跑一遍记录延迟单张推理的时间和吞吐每秒推理的张数。测试你的生产配置的延迟/吞吐用你自己的模型数据集跑一遍记录延迟和吞吐。对比看你的生产配置是不是比 Sample 默认配置慢很多。如果是那就要调优比如开 AOE 调优、用 GE 融合算子、调大 batch size、等等。关键点Sample 的价值不是直接用是理解 CANN 程序的标准写法Sample 的价值不是直接用到生产环境因为 Sample 是演示用的不是生产级的。Sample 的价值是帮你理解 CANN 程序的标准写法。比如ACL 接口 Sample教你怎么用 ACL API 写 CANN 程序标准的初始化、内存申请、推理、内存释放流程。PyTorch 接口 Sample教你怎么用 PyTorch 接口写 CANN 程序标准的 Dataset、DataLoader、Model、推理流程。GE 融合 Sample教你怎么写 GE 融合算子标准的算子注册、算子融合、性能测试流程。读懂了 Sample 的代码你就会写标准的 CANN 程序了不会写出野路子的代码。五、贡献自己的 Sample 到 cann-learning-hub社区贡献流程Fork → 开发 → 本地测试 → 提交 PR → Code Review如果你想把自己写的 CANN 程序比如一个很好的图像分类 Sample贡献给 cann-learning-hub让更多人用到那流程是Fork在 atomgit.com 上把cann/cann-learning-hub仓库 fork 到你的账号下。开发在你的 fork 里开发你的 Sample写代码、写 README、写测试用例。本地测试在你的环境里跑通你的 Sample确保代码可运行、结果正确。提交 PRPull Request把你的 fork 里的修改提交 PR 到cann/cann-learning-hub仓库。Code Reviewcann-learning-hub 的维护者会 review 你的 PR检查代码质量、README 完整性、CANN 版本标注是否清楚。如果 review 通过你的 PR 就会被合并你的 Sample 就正式进入 cann-learning-hub 了。Sample 的质量标准代码可运行、README 完整、CANN 版本标注清楚你的 Sample 要被合并必须满足 3 个质量标准代码可运行别人在任何满足 CANN 版本要求的环境下能跑通你的 Sample不会编译失败、不会运行崩溃、不会输出错误结果。README 完整README 里要包含Sample 的用途、适用的 CANN 版本、环境准备步骤、依赖安装步骤、编译步骤如需、运行步骤、输出解读、常见问题解决。CANN 版本标注清楚README 里要明确标注适用的 CANN 版本比如CANN 7.0。这样别人就不会用不兼容的 CANN 版本来跑你的 Sample。关键点技能文件中提到的社区贡献的内容经过审核后整合进来——所以别担心质量不够好技能文件里提到了社区贡献的内容经过审核后整合进来。也就是说你提交的 PR会有维护者帮你 review检查代码质量、README 完整性、CANN 版本标注是否清楚。如果 review 发现问题维护者会给你反馈让你修改。你修改后再提交 PR直到 review 通过。所以别担心我的 Sample 质量不够好——只要你愿意贡献维护者会帮你提升质量的。使用前 vs 使用后效率对比表格假设你是 CANN 新手要写一个 CANN 程序比如图像分类推理。你在两个方案下做使用前自己从头写 CANN 程序不看 Sample靠猜。使用后先跑通 cann-learning-hub 里的官方 Sample再改编成自己的程序。下面是概括性描述的效率对比表格不捏造具体数字对比维度使用前自己从头写 CANN 程序靠猜使用后先跑通官方 Sample 再改编效率提升开发效率低需要大量试错高有可运行的基础代码显著改善兼容性风险高容易踩版本坑低Sample 经过测试社区验证价值性能调优起点从零开始有基线可对比迭代优化关键为什么会有这个效率提升核心原因有三个有可运行的基础代码使用后你不需要从零开始写不用自己摸索 CANN API 的调用顺序、内存申请释放流程、等等。你直接在 Sample 的代码上改改模型、改数据集、改预处理后处理开发效率就高了。Sample 经过测试cann-learning-hub 里的 Sample都是经过测试的维护者会确保 Sample 在指定的 CANN 版本下能跑通。所以你用 Sample就不会踩版本不兼容的坑兼容性风险低。有基线可对比使用后你有一个性能基线Sample 默认配置的延迟/吞吐。你改编后的程序如果比基线慢很多那你就知道要调优了性能调优有方向。代码段 1运行第一个 Sample 的完整命令行记录# 1. 克隆 cann-learning-hub 仓库gitclone https://atomgit.com/cann/cann-learning-hub.gitcdcann-learning-hub# 2. 查看 NPU 设备信息和 CANN 版本npu-smi infocat/usr/local/Ascend/CANN/VERSION# 3. 设置 CANN 环境变量如果还没设置exportASCEND_HOME/usr/local/AscendexportPATH$ASCEND_HOME/CANN/bin:$PATHexportLD_LIBRARY_PATH$ASCEND_HOME/CANN/lib64:$LD_LIBRARY_PATH# 4. 安装依赖PyTorch 接口的 Samplepipinstalltorch torch_npu# 5. 进入 Sample 目录选一个 PyTorch 接口的 Samplecdsamples/ops-nn/conv2d_pytorch/# 6. 运行 Samplepython inference.py# 7. 解读输出应该能看到推理结果比如分类 top-1 的类别和置信度这段代码展示了运行第一个 Sample的完整命令行。关键点git clone把 cann-learning-hub 仓库克隆到本地。npu-smi info和cat /usr/local/Ascend/CANN/VERSION查看 NPU 设备信息和 CANN 版本用来过滤 Sample。设置 CANN 环境变量确保 CANN 的二进制和库能被找到。pip install torch torch_npu安装 PyTorch 和昇腾适配的 PyTorchPyTorch 接口的 Sample 需要。cd samples/ops-nn/conv2d_pytorch/进入 Sample 目录选了一个 PyTorch 接口的 Sample。python inference.py运行 Sample推理。解读输出确保推理结果是对的比如输入猫的图片输出猫的类别。代码段 2三个兼容性问题的诊断和解决命令行记录# 问题 1ascendc 自定义算子 Sample 编译失败返回E19999# 诊断查看 CANN 版本cat/usr/local/Ascend/CANN/VERSION# 假设输出是 6.0.0# 解决升级 CANN 到 7.0或者换一个 Sample# 这里选择换一个 Samplecd../../cdsamples/ops-nn/conv2d_pytorch/# 换一个不依赖 CANN 7.0 的 Sample# 问题 2AICPU 自定义算子 Sample 推理结果为全零# 诊断检查算子是否已经注册ls$ASCEND_HOME/CANN/opp/opproto/aicpu/# 如果看不到你的算子 proto 文件那就是没有注册# 解决运行 register_op.sh 注册算子cdsamples/aicpu/your_op/bashregister_op.sh# 问题 3ACL 接口 Sample 在多 batch 场景下 QPS 很低# 诊断查看模型转换命令是否指定了 --dynamic_batch_sizecatbuild.sh|grepatc# 如果看不到 --dynamic_batch_size那就是没有指定# 解决修改 build.sh在 atc 命令里加上 --dynamic_batch_size# 比如--dynamic_batch_size1,4,8,16,32vimbuild.sh# 修改完后重新编译bashbuild.sh这段代码展示了三个兼容性问题的诊断和解决的命令行。关键点问题 1 的诊断和解决用cat /usr/local/Ascend/CANN/VERSION查看 CANN 版本。如果版本低于 Sample 要求的版本就升级 CANN 或者换一个 Sample。问题 2 的诊断和解决用ls $ASCEND_HOME/CANN/opp/opproto/aicpu/检查算子是否已经注册。如果看不到就运行register_op.sh注册。问题 3 的诊断和解决用cat build.sh | grep atc查看模型转换命令是否指定了--dynamic_batch_size。如果没有就修改build.sh加上--dynamic_batch_size然后重新编译。代码段 3基于 Sample 改编的完整流程代码替换模型数据集# 基于 samples/ops-nn/conv2d_pytorch/ 改编替换模型数据集importtorchimporttorch_npufromtorchvisionimportdatasets,transformsfromyour_modelimportYourModel# 你自己的模型# 1. 替换模型从 ResNet-50 换成你自己的模型YourModelmodelYourModel()model.load_state_dict(torch.load(your_model.pth))model.eval()model.npu()# 2. 替换数据集从 ImageNet 换成你自己的数据集YourDatasettransformtransforms.Compose([transforms.Resize((224,224)),transforms.ToTensor(),transforms.Normalize(mean[0.485,0.456,0.406],std[0.229,0.224,0.225])])datasetdatasets.ImageFolder(your_dataset/,transformtransform)dataloadertorch.utils.data.DataLoader(dataset,batch_size32,shuffleFalse)# 3. 推理跟 Sample 一样的流程withtorch.no_grad():forimages,labelsindataloader:imagesimages.npu()outputsmodel(images)# 后处理把推理结果转成人类可读的格式_,predstorch.max(outputs,1)print(fPredicted:{preds.cpu().numpy()}, Ground Truth:{labels.numpy()})# 4. 性能测试对比 Sample 默认配置 vs 你的生产配置的延迟/吞吐# 这里省略性能测试代码可以用 torch.utils.benchmark 来测这段代码展示了基于 Sample 改编的完整流程替换模型数据集。关键点替换模型把 Sample 里的 ResNet-50换成你自己的模型YourModel。要注意模型的输入/输出格式可能跟 Sample 不一样要改预处理和后处理。替换数据集把 Sample 里的 ImageNet换成你自己的数据集YourDataset。要注意数据集的格式可能跟 Sample 不一样要改数据读取和预处理。推理流程跟 Sample 一样的流程模型设为 eval 模式、放到 NPU 上、前向推理、后处理。性能测试对比 Sample 默认配置和你的生产配置的延迟/吞吐可以用torch.utils.benchmark来测。代码段 4提交 Sample 贡献的 git 命令行记录# 1. Fork cann-learning-hub 仓库在 atomgit.com 上操作# 2. 克隆你的 fork 到本地gitclone https://atomgit.com/your_username/cann-learning-hub.gitcdcann-learning-hub# 3. 创建新分支用来开发你的 Samplegitcheckout-badd_your_sample# 4. 开发你的 Sample写代码、写 README、写测试用例mkdirsamples/your_category/your_sample/# 把你的代码、README、测试用例放到这个目录里# 5. 本地测试确保代码可运行、结果正确cdsamples/your_category/your_sample/ python inference.py# 确保输出正确# 6. 提交到你的 forkgitadd.gitcommit-mAdd your_sample: 你的 Sample 的描述gitpush origin add_your_sample# 7. 提交 PR在 atomgit.com 上操作# 8. 等待 Code Review维护者会给你反馈# 9. 根据反馈修改如需# 10. PR 被合并你的 Sample 正式进入 cann-learning-hub这段代码展示了提交 Sample 贡献的 git 命令行。关键点Fork在 atomgit.com 上操作把cann/cann-learning-hubfork 到你的账号下。克隆你的 fork把你的 fork 克隆到本地。创建新分支不要直接在main分支上开发创建一个新分支比如add_your_sample。开发你的 Sample在你的分支上写代码、写 README、写测试用例。本地测试确保代码可运行、结果正确。提交到你的 fork用git add、git commit、git push提交到你的 fork。提交 PR在 atomgit.com 上操作提交 PR 到cann/cann-learning-hub仓库。等待 Code Review维护者会 review 你的 PR检查代码质量、README 完整性、CANN 版本标注是否清楚。根据反馈修改如果 review 发现问题维护者会给你反馈让你修改。你修改后再提交 PR直到 review 通过。PR 被合并你的 Sample 正式进入 cann-learning-hub别人都能用到你的 Sample 了。总结这篇文章从 cann-learning-hub 的内容结构讲起到在昇腾 910B2 上运行第一个 Sample、Sample 兼容性问题的诊断与解决、基于 Sample 改编从跑通到用在生产环境最后给出了贡献自己的 Sample 到 cann-learning-hub的完整流程。核心要点回顾cann-learning-hub 是CANN 生态的入口集中管理学习资源教程、博客、竞赛、样例。找 Sample 的方法用关键词搜索按 CANN 版本过滤。运行第一个 Sample 的流程环境准备 → 依赖安装 → 编译如需 → 运行 → 解读输出。Sample 兼容性问题的诊断和解决看错误现象 → 找原因 → 解决升级 CANN、注册算子、指定 dynamic batch 参数。基于 Sample 改编的流程理解数据流 → 替换模型和数据集 → 性能测试。贡献 Sample 到 cann-learning-hub 的流程Fork → 开发 → 本地测试 → 提交 PR → Code Review。cann-learning-hub 在昇腾生态中的定位是学习资源的入口和集散地。如果你刚接触 CANN建议先花 2 小时把 cann-learning-hub 里的 Sample 过一遍不用全跑看代码就行——这样你就能快速理解 CANN 程序的标准写法避免从零开始摸索的低效。给新手的行动建议先花 2 小时把全部 Sample 过一遍不用全跑看代码就行。这样你就能快速找到跟你场景匹配的 Sample、“跟你问题匹配的方案”、“跟你水平适配的教程”。仓库链接https://atomgit.com/cann/cann-learning-hub附加代码段Sample查找和筛选的Python脚本# 从 cann-learning-hub 仓库中查找与图像分类相关的 Sampleimportosimportredeffind_samples(keyword):查找包含关键词的 Sampleresults[]forroot,dirs,filesinos.walk(.):forfileinfiles:iffile.endswith(.md)orfile.endswith(.py):filepathos.path.join(root,file)withopen(filepath,r,encodingutf-8)asf:textf.read()ifkeywordintext:results.append(filepath)returnresults# 查找图像分类相关的 Samplesamplesfind_samples(图像分类)print(f找到{len(samples)}个相关 Sample:)forsampleinsamples:print(f -{sample})这段脚本展示了如何从 cann-learning-hub 仓库中查找 Sample。关键点os.walk(.)递归遍历当前目录下的所有文件。if file.endswith(.md) or file.endswith(.py)只检查 Markdown 文件和 Python 文件Sample 的 README 是 .md代码是 .py。if keyword in text检查文件内容是否包含关键词。应用场景当你想找某个关键词的 Sample 时可以运行这个脚本不用手动翻 cann-learning-hub 仓库。附加代码段Sample 兼容性自动检测脚本# 自动检测 Sample 的 CANN 版本要求并与当前环境对比importreimportosdefcheck_sample_compatibility(sample_dir):检查 Sample 的兼容性# 读取 README.mdreadme_pathos.path.join(sample_dir,README.md)ifnotos.path.exists(readme_path):returnNone,README.md 不存在withopen(readme_path,r,encodingutf-8)asf:readmef.read()# 提取 CANN 版本要求version_matchre.search(rCANN\s*\s*(\d\.\d),readme)ifnotversion_match:returnNone,未找到 CANN 版本要求required_versionversion_match.group(1)# 读取当前环境的 CANN 版本withopen(/usr/local/Ascend/CANN/VERSION,r)asf:current_versionf.read().strip()# 对比版本iffloat(current_version)float(required_version):returnTrue,f兼容当前版本{current_version} 要求版本{required_version}else:returnFalse,f不兼容当前版本{current_version} 要求版本{required_version}# 检查当前目录下的所有 Sampleforsampleinos.listdir(.):ifos.path.isdir(sample):compatible,msgcheck_sample_compatibility(sample)ifcompatibleisnotNone:print(f{sample}:{msg})仓库链接https://atomgit.com/cann/cann-learning-hub
