graph-autofusion 编译构建辅助 Skill 实战指南build.sh 全参数解析与 CANN 环境配置【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion本文以.claude/skills/af-build-runner/README.md为核心骨架系统讲解 CANN graph-autofusion 开源仓库的编译构建辅助 Skill——af-build-runner 的能力边界、build.sh的全部命令行参数与编译模式、CANN Toolkit 依赖版本匹配、第三方依赖管理以及 CMake 编译错误的定位思路。读完本文你将能独立完成该仓库从环境初始化、模块化编译、UT/ST 测试到 run 包打包的完整流程并学会在编译报错时结合源码快速定位根因。一、af-build-runnergraph-autofusion 的编译构建辅助 Skillaf-build-runner 是 graph-autofusion 项目内置的一个 Claude/opencode Skill定位为项目编译构建辅助面向开发者在本地编译、打包、跑测、排错四个典型场景提供指导。其能力范围依据 .claude/skills/af-build-runner/README.md包括能力项说明build.sh 参数指导指导使用仓库根目录 build.sh 的各种参数和编译模式CMake 错误解析解析 CMake 编译错误并给出修复建议CANN Toolkit 依赖版本匹配管理 CANN Toolkit 依赖版本匹配避免安装路径、版本不匹配导致的编译失败环境配置与第三方依赖管理指导环境配置如ASCEND_INSTALL_PATH、CANN_3RD_LIB_PATH和第三方依赖管理Skill 的触发场景是关键词驱动的当用户提到编译、构建、build、cmake、make编译报错、编译错误、build error打包、pkg、packagebuild.sh、编译选项、编译类型等关键词时自动触发。这意味着该 Skill 是面向真实编译排障工作流的感知层——它不替代构建系统本身而是指导 Agent 正确使用仓库既有的构建脚本体系。二、build.sh一站式构建入口与全参数解析仓库根目录的 build.sh 是整个项目的统一构建入口覆盖四大受支持模块superkernel、autofuse_framework、autofuse_ascendc_api、autofuse_e2e见 build.sh 中SUPPORTED_MODULES数组。脚本通过getopt解析参数未携带任何选项时直接报错退出强制用户显式声明意图。2.1 完整参数一览参数说明默认值/取值-h, --help打印使用说明---pkg构建并打包生成 run 包off--no-autofuse跳过 autofuse 后端构建/打包产物off即默认构建 autofuse-j N编译线程数默认 16超过 CPU 核数时自动截断为 CPU 核数仅接受正整数-j8、-j16均可-u, --ut对支持的实现运行单元测试off-s, --st对支持的实现运行系统测试off--implpy\|cpp\|all在-u/-s下选择实现类型all--modulename选择模块all或上述 4 个模块之一all-c, --coverage带覆盖率报告运行测试若未显式选择测试类型则自动同时开启 UT 与 SToff--output_pathPATHrun 包输出目录./build_out--cann_3rd_lib_pathPATH第三方依赖包安装路径./output/third_party--build-typeTYPE编译类型Debug/ReleaseRelease--pkg-typeTYPE打包类型run/rpm/debrun-f FILE传入变更文件清单文件触发智能模块选择-2.2 参数校验细节源码级从 build.sh 的check_param_j可看到-j的严格校验空值、0、负数、非数字均报错退出且超过 CPU 核数时会被钳制为CPU_NUM脚本通过/proc/cpuinfo统计核数。--impl只接受py|cpp|all三值--build-type只接受Debug|Release--pkg-type只接受run|rpm|deb--module必须是SUPPORTED_MODULES之一否则一律报错并打印 usage。值得注意的两点设计--cann_3rd_lib_path的缓存机制首次编译时第三方包third_party会花费一定时间下载/编译后续构建若路径不变则跳过编译直接复用这是官方 usage 明确说明的提速手段。-f智能模块选择-f接收一个包含变更文件清单的文件每行一个文件脚本会剔除README.md、CONTRIBUTING.md、docs/、examples/、.claude/、.opencode/、AGENTS.md等非构建相关路径后见 build.sh 的analyze_changed_modules按以下规则决策仅super_kernel/变更跳过 autofuse 构建与 autofuse 测试ENABLE_AUTOFUSEoff、SKIP_AUTOFUSE_TESTSon仅autofuse/变更跳过 superkernel 测试SKIP_SUPERKERNEL_TESTSon两处均有变更全量构建仅文档/示例等变更直接退出并返回退出码 200。这一机制与仓库.gitcode/scripts/下的 CI 脚本配合用于在 pre-commit 流水线中按改动范围做增量构建避免无谓的全量编译耗时。2.3 常用命令示例# 查看帮助 sh build.sh -h # 全量构建默认 Release含 autofuse 后端 sh build.sh # 8 线程 Debug 构建并打包 run 包 sh build.sh --build-typeDebug -j 8 --pkg # 构建 rpm 包 sh build.sh --pkg --pkg-typerpm # 跳过 autofuse仅构建 superkernel sh build.sh --no-autofuse # 对 superkernel 模块运行 Python 单元测试 sh build.sh -u --modulesuperkernel --implpy # 对 autofuse_framework 运行全部 ST 并生成覆盖率 sh build.sh -s --moduleautofuse_framework -c2.4 打包流程与产物当指定--pkg时build_package在build目录执行cmake_configbuild all package随后从_CPack_Packages/makeself_staging/复制cann-graph-autofusion*.run到--output_path默认 build_out 目录并打印产物路径见 build.sh。CMake 配置阶段会注入-DCMAKE_INSTALL_PREFIX、-DASCEND_INSTALL_PATH、-DCMAKE_BUILD_TYPE、-DCANN_3RD_LIB_PATH、-DPACKAGE_TYPE、-DBUILD_AUTOFUSE等关键变量见 build.sh。三、模块化测试执行UT/ST 与覆盖率3.1 测试动作路由表build.sh 内部通过MODULE_ACTION_HANDLERS关联表见 build.sh将模块:动作路由到具体处理器模块动作处理器superkernelpy_ut / cpp_ut / py_st / cpp_stsuperkernel_py_ut 等autofuse_frameworkall_ut / all_stautofuse_module_test_suiteautofuse_ascendc_apiall_ut / all_stautofuse_module_test_suiteautofuse_e2eall_stautofuse_module_test_suitenormalize_test_selectionbuild.sh会按--implpy/cpp/all与--module展开成实际要执行的EXEC_ACTIONS列表若同时满足未选测试类型但开了-c则自动补齐 UTST。3.2 superkernel 测试细节Python 测试superkernel_py_ut先pip install -e .[dev] --force-reinstall再以pytest tests/ut -m ut -n auto并行执行ST 同理为tests/st -m st开启覆盖率时追加--cov-configscripts/sk_ut_cfg.toml/sk_st_cfg.toml并输出 term-missing/html/xml 三种报告见 build.sh。C 测试通过 CMake 开关-DENABLE_CPP_UTEST/-DENABLE_CPP_STEST/-DENABLE_GCOV控制支持--test_case传入 gtest filter映射为-DGTEST_FILTER--gtest_filter...覆盖率模式走collect_coverage_data目标见 build.sh。3.3 autofuse 测试细节autofuse 各模块的 UT/ST 统一由 scripts/test/run_autofuse_test.sh 承接见 build.sh该脚本会用select_compilers依据CC/CXX/GCC_VERSION环境变量选择 gcc/g 版本Ubuntu24 默认 gcc-14自动探测ASCEND_INSTALL_PATH默认/usr/local/Ascend/ascend-toolkit/latest与ASCEND_3RD_LIB_PATH默认./output/third_party先构建pyautofusemake -jN pyautofuse再按-m指定的模块att/ascir/optimize/common/codegen/ascendc_api/framework/e2e/backend/tools/all分别执行对应的build_ut/build_st子流程最终统一用ctest --output-on-failure -jN -L label拉取用例覆盖 att、ascir、codegen、optimize、backend 等多个测试套件见 run_autofuse_test.sh覆盖率模式-c要求环境已安装与 gcc/g 版本匹配的 lcov、gcov、genhtml生成结果写入根目录cov/get_coverage。四、CANN Toolkit 依赖版本匹配与环境初始化af-build-runner 的第三项核心能力是管理 CANN Toolkit 依赖版本匹配。构建 graph-autofusion 强依赖已安装的 CANN 组件编译期通过ASCEND_INSTALL_PATH环境变量ASCEND_HOME_PATH定位 toolkit。4.1 一键环境初始化仓库提供 scripts/init_env.sh可自动完成系统依赖、CANN Toolkit、Python 依赖三部分安装# 默认安装 CANN 9.0.0 910b ops 包到 /usr/local/Ascend sh scripts/init_env.sh # 仅安装依赖跳过 CANN 与 ops sh scripts/init_env.sh --skip-cann --skip-ops # 指定芯片类型安装910b / 950 / A3 sh scripts/init_env.sh --chip-type 950脚本要点依据 init_env.sh系统依赖自动识别 apt-get/yum安装 curl、wget、git、cmake、make、g、ccache、autoconf、automake、libtool、gperf、openssh-server 及 python3-dev/python3-devel并修复 libz.so.1 问题CANN 安装从华为镜像站实时抓取最新构建日期目录下载Ascend-cann-toolkit_9.0.0_linux-arch.runarch 通过uname -m判定 x86_64/aarch64以--full --quiet静默安装可选安装Ascend-cann-910b-ops包脚本内置 CANN 版本9.0.0、芯片类型910b两个可调变量Python 依赖配置清华 pip 镜像安装 pytest、coverage、pytest-cov、pybind11 等并额外安装 super_kernel/requirements-dev.txt 中的依赖安装完成后需执行source /usr/local/Ascend/cann/set_env.sh使环境变量生效。4.2 CANN Toolkit 安装 Skill仓库还内置了独立的cann-toolkit-installerSkill见 .claude/skills/cann-toolkit-installer/SKILL.md用于快速安装/更新社区版 CANN Toolkit支持/cann-toolkit-installer一键执行也可指定arch version install-path。其下载源与 init_env.sh 一致镜像站master/{build_date}/Ascend-cann-toolkit_{version}_linux-{arch}.run安装命令为bash pkg.run --install --force -q并要求 bash 5.1.16、python3 3.9、cmake 3.16 的环境前提。4.3 版本不匹配时的典型报错与排查当编译报错提示找不到 CANN Toolkit 时按以下顺序排查确认环境变量已生效echo $ASCEND_HOME_PATH、echo $ASCEND_INSTALL_PATH确认安装路径存在ls /usr/local/Ascend/ascend-toolkit/latest或自定义安装路径重新执行source install-path/cann/set_env.sh后重试编译若为第三方包缺失检查--cann_3rd_lib_path默认./output/third_party是否已完整生成可先清理后重新编译一次以触发完整下载。五、第三方依赖管理第三方依赖的下载与编译由 CMake 层承接根 CMakeLists.txt 引入 cmake/fetch_cann_cmake.cmake 与 cmake/dependencies.cmake通过ASCEND_INSTALL_PATH也可由环境变量ASCEND_INSTALL_PATH注入与CANN_3RD_LIB_PATH环境变量ASCEND_3RD_LIB_PATH两个缓存变量定位依赖见 CMakeLists.txt。CMake 的ExternalProject_Add通过 curl 下载第三方 tarball因此若 git 可用但 cmake 下载失败通常是代理只配置在~/.gitconfig而进程环境缺少http_proxy/https_proxy——build.sh 在启动时会检测并提示这类情况见 build.sh首次构建第三方包耗时较长属正常现象后续构建因路径不变会跳过编译直接复用。仓库还提供 autofuse/scripts/prepare_third_party.sh 用于 autofuse 侧第三方依赖的准备。六、CMake 编译错误解析与修复建议af-build-runner 的功能之一是解析 CMake 编译错误并给出修复建议。结合构建链路可将错误分为三类并给出对应排查路径配置期错误cmake 阶段多由依赖路径或工具链问题引起。重点核对-DASCEND_INSTALL_PATH、-DCANN_3RD_LIB_PATH、-DCMAKE_BUILD_TYPE是否合法--build-type仅支持 Debug/Release--pkg-type仅支持 run/rpm/deb--impl仅支持 py/cpp/all参数拼写错误时 build.sh 会直接以 usage 提示退出。编译期错误make 阶段注意 run_autofuse_test.sh 默认导出DISABLE_COMPILATION_WERRORON见 run_autofuse_test.sh源码中标注为待修复的 TODO若手动编译时告警被当作错误-Werror可在测试场景下参考该开关正式构建则建议修复告警本身。链接期错误多为动态库搜索路径问题。可参考 run_autofuse_test.sh 的set_test_ld_library_path将本地构建产物路径如build/graph_metadef/...、output/metadef/lib与 CANN 的lib64目录依次加入LD_LIBRARY_PATH后再验证。七、Skill 生效验证依据 .claude/skills/af-build-runner/README.md 的验证方法在 opencode 中输入以下三条指令即可确认 Skill 是否被正确触发如何编译项目build.sh 有哪些参数编译报错找不到 CANN Toolkit 怎么办三者分别覆盖 Skill 的四大能力中的构建流程指导参数解析指导与CANN 依赖版本匹配/环境配置指导可作为开发环境自检的最小用例。八、小结一条完整的编译链路将以上内容串起来graph-autofusion 从零到可运行的标准链路为sh scripts/init_env.sh # 1. 安装系统依赖 CANN Toolkit Python 依赖 source /usr/local/Ascend/cann/set_env.sh # 2. 生效环境变量ASCEND_HOME_PATH 等 sh build.sh -j N # 3. 全量编译Release sh build.sh -u/-s --modulem --implpy|cpp # 4. 按模块跑 UT/ST sh build.sh --pkg [--pkg-typerpm|deb] # 5. 打包 run/rpm/deb 产物每一步都可通过 build.sh、scripts/test/run_autofuse_test.sh、scripts/init_env.sh 与 .claude/skills/af-build-runner/README.md 对照查证编译遇到问题时优先核对 CANN 安装路径与版本、第三方依赖路径、编译器版本CC/CXX/GCC_VERSION三组关键输入即可覆盖绝大多数构建失败场景。【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考