CANN软件栈依赖关系

一句话让Agent变成昇腾专家，昇腾任务轻松搞定。评测入口：请按这个开源仓接入昇腾图谱 https://gitcode.com/agent0/kg-tools

上一篇《CANN 配套关系全景》讲的是版本对齐——哪几个版本号必须凑成一套。这篇讲结构耦合——这个套件内部谁包含谁、谁链接谁、谁调用谁。依赖搞清楚，报错时才能定位断在哪条边上：ImportError: libhccl.so 断在链接期，507033 断在初始化顺序，create HDC failed 断在设备文件权限。全文按「装什么 → 链接什么 → 怎么跑起来 → 落到哪里」四段展开，出处逐节标注，查不到的写明 [未核实]。

总依赖图：一张图看懂调用链

读图三句话：实线是运行时调用或链接依赖，虚线是编译期结构依赖（头文件/ABI，不产生运行时调用）；libhccl.so 是 torch_npu 的链接期硬依赖（DT_NEEDED，import 时就要解析），不是可选插件；metadef 是 GE 与算子仓共同的地基，这就是它 ABI 兼容强约束的原因。

装什么：交付包与子包依赖

三个包 + 一个 HDK

包	职责（官方口径）	依赖要求
Ascend-cann-toolkit	训练/推理/开发调试；模型转换、算子与应用开发编译	依赖驱动固件（独立配套）
Ascend-cann-{chip}-ops（950/A3/910b/910/310p/310b 六变体）	算子基础框架 + 算子库（math/nn/cv/transformer）+ TBE + HCCL + HIXL + DVPP；aclnn 动静态库、算子源码、kernel 二进制	先装兼容版本 toolkit，且同一路径；多芯片 ops 不支持同路径
Ascend-cann-nnal（可选）	ATB（Ascend Transformer Boost）+ SiP（信号处理）	先装同版本 toolkit 并配好环境变量
驱动 + 固件（Ascend HDK）	内核驱动、固件、用户态库	独立版本配套（见前篇矩阵）

install-path 必须一致的本质：ops 包没有自己的目录，直接落位 toolkit 树的 opp/、lib64/plugin/opskernel/ 等位置——本机安装树里 ascend_toolkit_install.info 与 ascend_ops_install.info 的 path 字段相同，这是「同路径」约束的物证。所以 ATC 在 8.5.0 之后不装 ops 包直接编译失败，不是巧合，是算子规格与 kernel 二进制物理上就住在 toolkit 树里。顺带对上图：接口层的 libhccl.so 交付上就住在 ops 包里（可经 cann-hccl 子包独立升级）——图按运行时角色分层，包按交付边界切分，两套坐标系别混。

8.5.0 是形态分水岭：更早是 nnae / nnrt / toolkit 三形态 + kernels 依次跟随安装；8.5.0 起收敛为 toolkit + ops 两包制（nnrt+ops 在部分推理场景保留）。目录形态同步进化：8.x 是 ascend-toolkit/{ver}/ 下 acllib、atc、compiler、fwkacllib、hccl、opp、pyACL、runtime 等各带独立安装信息的多目录；9.0.0 起合并为 cann-{ver}/ 单目录（bin/compiler/fwkacllib/lib64/opp/python/runtime/toolkit/tools/vendors），set_env.sh 随之从 ascend-toolkit/ 挪到 cann/ 下——老脚本升级断链的根源在这。

18 个逻辑子包：6 个可独立升级 + 12 个开源

9.x 官方配套表口径（9.0.0 与 9.0.1 一致）：

类别	子包	特性
独立升级（6）	cann-ops-math / ops-nn / ops-cv / ops-transformer / hccl / hixl	跨 CANN 9.0.1 / 9.0.0 / 8.5.2 互配；--upgrade 单独升（如 cann-hixl_x.y.z.run --upgrade），前提是已装配套版本 toolkit+ops
开源（12）	cann-opbase / oam-tools / asc-tools / asc-devkit / pto-isa / ge-compiler / ge-executor / graph-autofusion / metadef / dflow-executor / hcomm / npu-runtime	仅配套同版本；ge-compiler / ge-executor / dflow-executor 同源于 cann/ge 仓

网传「31 个子包」出自 QA 报告的说法未能核实（release-management 仓遍历后无此文档），官方可核实口径是 18 个。

安装模式参数（runfile）

--install（默认全量）、--devel（仅开发模式）、--full（仅 toolkit 无驱动）、--whitelist（toolkit 按 nnae/nnrt/hccl/hccl-only/atc/devtools 裁剪；ops 按 nnrt；nnal 按 atb/SIP/all）、--torch_atb（nnal 的 Python 库）、--feature-list=Acclibs（仅升级算子内容）、--install-path / --install-for-all、--upgrade（子包独立升级）。默认路径 root 装 /usr/local/Ascend，非 root 装 ${HOME}/Ascend。

链接什么：库级依赖实据

库拆分：旧总库的退场

头文件	应链接	归属组件
acl_rt.h	libacl_rt.so	Runtime
acl_mdl.h	libacl_mdl.so	GE
acl_op.h	libacl_op_executor.so + libacl_op_compiler.so	—
acl_prof.h	libmsprofiler.so	—

libascendcl.so 是旧版兼容总库，官方已标记废弃路径。aclnn 侧同理：libopapi.so 已废弃，拆成 libopapi_math/nn/cv/transformer.so；Meta 公共接口（aclTensor/aclScalar）在 libnnopbase.so；GE 图场景算子规格另有 libopgraph_* 系列。老 CMake 若还在链总库，升级时的链接报错先对照这张表。Runtime 交付物是 libacl_rt.so、libruntime.so、libruntime_v100/v200.so、libruntime_common.so。

跨包依赖的两个实锤

torch_npu → libhccl.so 是链接期 DT_NEEDED：import torch_npu 直接报 ImportError: libhccl.so: cannot open shared object file——动态链接器在 import 时就解析 NEEDED 表，这就是没 source set_env.sh 时 Python 侧最先炸的原因。

CANN 用户态 → 驱动用户态：CANN 日志库 libascendalog.so（compiler/lib64）依赖驱动的 libc_sec.so（driver/lib64/common）——CANN 包自己的库跨到了驱动包的库，两个「独立配套」的包在 so 级别仍有耦合。

set_env.sh 织出的依赖网

本机 cann-9.0.0 的 set_env.sh 逐行读，它本质是一张依赖清单：

变量	织入的依赖
LD_LIBRARY_PATH	lib64、lib64/plugin/opskernel、lib64/plugin/nnengine、tbe op_tiling、/usr/local/Ascend/driver/lib64{,/common,/driver}
PATH	bin、ccec_compiler、profiler、系统顾问、msobjdump
PYTHONPATH	python/site-packages、opp 内 tbe op_impl
ASCEND_HOME_PATH / ASCEND_TOOLKIT_HOME / ASCEND_AICPU_PATH / ASCEND_OPP_PATH	指向 cann 版本目录与 opp 树
TOOLCHAIN_HOME / CMAKE_PREFIX_PATH	toolkit 调试工具与 cmake 导出

驱动探测逻辑值得单独看：脚本在 LD_LIBRARY_PATH、ldconfig、/etc/ascend_install.info 三处找 libascend_hal.so，找不到则回退用包内 $dir/devlib——容器里「能 import 但设备打不开」时，先查这个回退逻辑。nnal 的 set_env.sh 另有巧思：ATB_HOME_PATH 按 torch.compiled_with_cxx11_abi() 自动选 cxx_abi_0/1 目录，ATB 与 torch 的 ABI 匹配是自动的，不需要手动对。

怎么跑起来：初始化顺序链

aclInit(json) → aclrtSetDevice → Context → Stream → aclrtMalloc
aclrtResetDeviceForce → aclFinalize                    # 逆序清理

每一步都踩着上一步的资源，顺序即依赖：aclInit 完成环境/资源/日志初始化（json 里配 defaultDevice 可隐式 SetDevice）；aclrtSetDevice 内部包含驱动 SVM 模块初始化（halMemAgentOpen 建立 Host/Device 侧共享虚拟内存交互），官方原话「SetDevice 后才可以调用其他 aclrt 运行时接口」；Context 创建时关联 Device 并建默认 Stream，所以 Stream/Malloc 必然后置。乱序的实证报错：未 aclInit 先 SetDevice 返回 507033（ACL_ERROR_RT_CONTEXT_NULL，源码定位 runtime/src/acl/aclrt_c/runtime/device.c）。

torch_npu 侧的两条接入链：动态图走 op-plugin——EXEC_NPU_CMD(aclnnXxx, ...) 宏直调 aclnn 符号，两段式协议（先 GetWorkspaceSize 再 Execute），torch schema 与 op_api 的映射登记在 op_plugin_functions.yaml；图模式走 TorchAir——Dynamo 捕获 FX 图转 Ascend IR 交 GE 编译执行，torchair 随 torch_npu 仓交付（third_party/torchair），编译期嵌入 CANN 头文件（rt_error_codes.h、ge_error_codes.h）。

落到哪里：驱动接口面

/dev 设备节点语义

节点	服务语义
/dev/davinciN	NPU 计算设备（N=设备 ID），runtime 经它与内核驱动交互
/dev/davinci_manager	管理设备，DCMI / npu-smi 管理通路
/dev/devmm_svm	SVM 共享虚拟内存：halMemAlloc/mmap、VMM 地址预留、跨进程/跨设备共享（UVM 为增强，仅 910B/910_93）
/dev/hisi_hdc	HDC 主机-设备通信通道；权限组 HwHiAiUser，配置 /etc/hdcBasic.cfg
/dev/dvpp_cmdlist	DVPP 推理业务支撑

驱动仓内部三层：DCMI 层（设备管理接口，npu-smi、mind-cluster 的 docker-runtime/device-plugin 都调它）→ HAL 层（bbox/buff/comm/dmc/esched/hdc/svm 等，统一入口头 ascend_hal.h）→ SDK-driver 层。日志基础设施 slog 双栖于驱动与 runtime 仓，Host 侧 AscendCL/GE/Runtime/HCCL 统一走 slogd 进程，日志落 $HOME/ascend/log/plog-*.log，ATC 打屏开关 ASCEND_SLOG_PRINT_TO_STDOUT。

通信栈纵深（SIG-HCCL 官方架构）

HCCL 管算法与入口，HCOMM 管通信域与基础通信原语，hixl 与集合通信并列提供单边通信（可作 LLM-DataDist 的传输后端）。profiler 的挂点也在这一层：mspti（libmspti.so）以 LD_PRELOAD 注入，Callback API 注册在 Runtime/HCCL 接口调用前后——CUPTI 在昇腾栈上的对等物。

部署形态：依赖面怎么切

形态	物理机装	容器/虚拟机内装
裸机	驱动 + 固件 + CANN	—
容器	驱动 + 固件，挂载 /dev/davinciN、davinci_manager、devmm_svm、hisi_hdc 与驱动目录	CANN（镜像内置）
虚拟机	驱动 + 固件	VM 内仅装驱动

容器要跑 CANN，本质是把「驱动接口面」（那几个 /dev 节点 + driver/lib64）透传进去——挂载清单不是约定俗成，正是上文依赖图的物理投影。

依赖视角排错表

症状	断在哪条边	修复
ImportError: libhccl.so cannot open…	torch_npu → libhccl（DT_NEEDED）	source cann/set_env.sh，让 lib64 进 LD_LIBRARY_PATH
ATC 编译失败（8.5.0+）	ops → toolkit 树缺位	装 {chip}-ops，同 install-path
507033 CONTEXT_NULL	初始化顺序	aclInit → SetDevice → Context 严格顺序
create HDC failed (error 31)	/dev/hisi_hdc 权限	用户入 HwHiAiUser 组，查 /etc/hdcBasic.cfg
链接报旧总库符号	libascendcl/libopapi 废弃拆分	按库拆分表换链接目标
找不到运行日志	slogd 依赖	$HOME/ascend/log/plog-*.log；ASCEND_SLOG_PRINT_TO_STDOUT=1
容器内 import 正常、SetDevice 失败	驱动接口面未透传	核对 /dev 节点挂载与 driver/lib64
采集不到 Kernel 时间线	mspti 未注入	LD_PRELOAD=$ASCEND_HOME_PATH/lib64/libmspti.so

方法论与披露

依赖图与配套表是一体两面：配套表告诉你装哪个版本，依赖图告诉你为什么非这么装不可——ops 与 toolkit 同路径是落位耦合，torch_npu 与 libhccl 是链接耦合，CANN 与驱动 libc_sec 是跨包库耦合。排查任何「环境问题」时先问断在哪条边，再查那条边两端的版本配套（回前篇的矩阵）。

[未核实] 清单：驱动 HAL 用户态 so 的具体产物名（源码目录与 ascend_hal.h 头文件有实据，libdavinci.so / drv_davinci_intf.so 之名无出处）；内核模块精确名（实据仅 ascend_km 与 lsmod 排障命令）；parser 能力归属（cann 组织 97 仓清单无独立 parser 仓，能力应在 ge/metadef 内）；op-plugin 直链 aclnn 的 ELF 形态为强推断（EXEC_NPU_CMD 宏 + ImportError 佐证，未 ldd 实测）；「31 子包」QA 报告原文。

接入昇腾知识图谱

访问GitCode开源仓： https://gitcode.com/agent0/kg-tools

---

参考资料

• 安装包职责与依赖：hiascend 安装指南 instg_0005/0008/0043（canncommercial 9.0.0）
• 子包配套与独立升级：gitcode cann/release-management（9.0.0 / 9.0.1 release-notes.md）
• CANN 架构总览与库族谱：hiascend CANN index、llms-content/zh_cann.md
• Runtime 架构与初始化链：cann-runtime 仓 runtime/docs/zh/design/architecture.md、dev_guide/01_initialization.md
• 头文件与库对应、aclnn 库拆分：ascend-doc/cann-docs app-dev/header_and_library_files_desc.md、ops-lib/header_and_library.md
• GE/metadef 依赖：cann/metadef README、cann/ge ATC 文档
• 通信栈：SIG-HCCL 架构 slides（2026-06-15）、cann/hccl architecture-brief、hixl 设计文档
• torch_npu 依赖：dl-frameworks/pytorch installation_guide FAQ、op-plugin 接入指南
• 设备节点与驱动分层：cann-runtime/driver README、mind-cluster 附录、昇腾 FAQ（HDC/SVM/初始化）
• 版本配套数据：本仓《CANN 配套关系全景（2026-09 版）》、单机型细节见《Ascend 950PR 软硬件配套速查手册》