昇腾部署第 A3 课：HDK 到底指什么——驱动、固件、工具集是不是一回事

编制：观澜｜日期：2026-10-05｜级别：T2 标准级 层级：A 层 · L0 硬件与环境（第 3 课，前接 A2《产品线与形态》）素材来源：昇腾官方文档 MCP 实时抓取（HDK 26.1.x 官方文档 + Atlas A2/A3 系列）数据纪律：工具名、路径、职责描述、部署场景分类逐字出自官方文档；标注「归纳」的是便于记忆的整理，非官方口径。

第一段 · 章前定位

A1 讲了驱动和固件各是什么、怎么装、怎么查。 A2 讲了卡有哪几代、哪几种形态。 这一课解决一个一直被跳过的问题：

你在官方文档里到处看到 HDK 这个词 —— 「HDK 文档」「HDK 驱动包」「HDK 版本 26.1.x」。 它和驱动、固件，到底是一回事还是三回事？

这个问题不搞清，会出现两种典型症状：

在文档站搜"HDK"，搜出来的东西看着都对，但不确定该装哪个；
遇到"这个命令在当前部署场景不支持"，以为是权限或配置问题，其实是不该在这儿用。

这一课就是把这个词拆开。

第二段 · 学习目标

学完这一课，你应该能回答：

Ascend HDK 指的是什么范围——它包含哪些东西、不包含哪些
HDK 里那四个工具/接口各是干什么的、分别住哪
为什么同一条命令，在不同部署环境下"支持情况"不一样
遇到"命令不存在"或"此场景不支持"时，先查什么

第三段 · 先给结论：三个词不是一回事，但住在同一层

词	指什么	在哪一层
驱动	让 Host 操作系统认得这张卡的程序	L0 硬件层（住在 Host OS）
固件	卡自己的运行程序（卡内部的系统）	L0 硬件层（住在卡里）
HDK	一个文档与交付范围的名字——驱动、固件，以及随驱动一起装上的那套工具集	L0 硬件层（打包口径）

一句话区分：

驱动和固件是"两个具体的东西"；HDK 是"它们俩加上工具集"这一片的统称。 你在文档站看到的「HDK 26.1.x」，指的是这一片的版本，不是某一个单独程序。

⚠️ 数据纪律提示：官方文档正文里没有展开 HDK 三个字母的全称，用户必读页只称其为 Ascend HDK。所以本课不替它编全称，只讲它覆盖什么。

A1 留下的钩子在这里解开：A1 说「驱动包官方全名是『驱动 & npu-smi 工具包』」—— 为什么驱动包里会有个 npu-smi 工具？因为工具是随驱动一起交付的，而这整片交付，官方归在 HDK 名下。

第四段 · HDK 里的四个工具/接口（官方原文）

这是本课最实用的一段。以下四条逐字出自官方《Ascend HDK 接口和命令工具简介》：

① `npu-smi` —— 设备管理工具

官方原文：npu-smi（NPU System Management Interface）是 NPU 的设备管理工具，在驱动安装完成后，可以使用该工具查询 NPU 设备的信息和使用情况，便于用户了解当前 NPU 的状态，并提供命令用于对 NPU 进行 固件升级、清除设备信息、配置参数和资源复位等操作。驱动安装过程中会默认安装 npu-smi 工具至 /usr/local/sbin/ 和 /usr/local/bin/ 路径下。

记住三件事： - 它是命令行工具（你在终端敲的那个） - 路径是 /usr/local/sbin/ 和 /usr/local/bin/ —— 这两个都在 PATH 里，所以装完直接就能敲 - 它不只"查"，还能改：固件升级、清设备信息、配参数、资源复位

⚠️ A1 的补充：这就是为什么"没装驱动就没有 npu-smi 命令"—— 不是 npu-smi 没装，是它随驱动一起装。

② DCMI —— 设备管理 API 接口

官方原文：DCMI（DaVinci Card Management Interface）是 NPU 的设备管理 API 接口，在驱动安装完成后，可以使用该接口查询 NPU 设备的信息和使用情况…… 用户可以根据业务需要，调用 DCMI 接口完成第三方系统二次集成开发。

和 npu-smi 的关系（归纳，便于记忆）：

	`npu-smi`	DCMI
形态	命令行工具（人敲）	编程接口（程序调）
使用者	运维 / 部署人员	做监控平台、管理系统的开发者
能做的事	查信息、固件升级、清信息、配参数、复位	同类能力，通过代码调用

一句话：你要在机器上敲什么，用 npu-smi；你要做个平台去管一堆机器，用 DCMI。

③ `hccn_tool` —— 集群网络管理工具

官方原文：hccn_tool（Huawei Collective Communications Network Tool）是 NPU 的集群网络管理工具，可以使用该工具设置和获取 NPU 设备上网口的信息，并持久化 NPU 设备网口的配置信息，便于用户进行网络初始化、配置优化以及故障排查等工作。驱动安装过程中会默认安装 hccn_tool 工具，在驱动安装完成后， hccn_tool 放置在软链接 /usr/bin/ 下，实际路径为 /usr/local/Ascend/driver/tools。

为什么它会被归到 HDK（而不是"网络"那一章）：

因为它是驱动安装过程中默认装上的，和 npu-smi 一起交付。 多卡机器上"卡之间通信不正常"，第一站就是它。

④ `msnpureport` —— Device 侧日志导出工具

官方原文：msnpureport 工具是 NPU 的设备导出工具，在驱动安装完成后，可以使用该工具导出 Device 侧产生的系统类日志和文件，查询和设置 Device 侧的维测信息，便于用户进行后续的日志分析和问题定位等工作。

这条直接接上 E1（报错定位法）：E1 讲过"日志分三处：应用侧、服务侧、Device 侧"。 Device 侧那份日志，导出的工具就是 msnpureport。

一张表记住四个

工具 / 接口	一句话职责	怎么用	谁最需要
`npu-smi`	设备管理	命令行	所有人（A1/A2 天天用）
DCMI	设备管理	API 调用	做管理平台的开发者
`hccn_tool`	集群网络管理	命令行	多卡 / 超节点运维
`msnpureport`	Device 侧日志导出	命令行	排障（接 E1）

四个都是"驱动安装过程中默认安装"的——这就是它们被统称为 HDK 的原因。

第五段 · 为什么同一条命令，换个环境就"不支持"

这是 HDK 这一片最容易误判的地方，也是官方专门用一整节来讲的事。

官方原文：用户在使用 npu-smi 工具、DCMI 接口和 hccn_tool 工具时， 对于不同产品的不同命令或接口，在不同的部署场景下支持情况亦不相同，详细情况请参见相关命令或接口的「不同部署场景下的支持情况」表。

官方把部署场景分成三大类、九个子场景

大类	子场景（官方原文）
物理机场景	物理机场景（裸机）／物理机+普通容器／物理机+特权容器
虚拟机场景	直通虚拟机／直通虚拟机+普通容器／直通虚拟机+特权容器
昇腾虚拟化实例（AVI）	物理机+容器 AVI／物理机+虚拟机 AVI／虚拟机+容器 AVI

官方对「昇腾虚拟化实例」的解释：

AVI（全称 Ascend Virtual Instance）——在物理机上通过 npu-smi 工具或 DCMI API 接口 对 NPU 硬件资源根据用户指定的需求划分出 vNPU，再把 vNPU 挂载到容器或虚拟机中使用。单个 vNPU 只能给单个虚拟机使用，但是单个虚拟机可以挂载多个 vNPU。

官方给的三条读表规则（原文）

如果部分部署场景在本文档的相关命令或接口描述中未提及，则表明该产品不涉及此场景，当前未规划。

「不同部署场景下的支持情况」表中的 Y 表示支持；N 表示不支持；NA 表示不涉及，当前未规划此场景。

这对你意味着什么（实操结论）

你看 npu-smi 的命令文档时，会看到一张「不同部署场景下的支持情况」表。必须先确认自己在哪个场景，再看这张表——否则你会照着一条命令敲，然后得到"不支持"，却以为是环境坏了。

归纳（便于记忆的判断顺序）： ① 我在裸机、容器里、还是虚拟机里？ ② 这个环境是直通还是虚拟化实例（AVI）？ ③ 再去查这条命令在你那个格子里的值是 Y / N / NA。

第六段 · 怎么确认 HDK 这一片装对了

依次敲（命令详解见附录 B）：

# ① 卡在不在（npu-smi 本身能不能用）
npu-smi info -l

# ② 驱动 / 固件版本
npu-smi info -t board -i 0

# ③ 集群网络工具在不在
which hccn_tool
ls -l /usr/local/Ascend/driver/tools

# ④ Device 侧日志导出工具在不在
which msnpureport

四条全过 = HDK 这一片装齐了。

为什么用 which 和 ls -l 一起查 hccn_tool：官方说明它是软链接（/usr/bin/）指向实际路径（/usr/local/Ascend/driver/tools）。用 ls -l 才能看出软链接指向哪里——软链接断了，敲命令会报"找不到"，但文件其实还在。

第七段 · 出问题了怎么查

现象	先查什么
敲 `npu-smi` 说"command not found"	驱动装了没（A1）；`npu-smi` 随驱动一起装
`npu-smi` 能用，但 `hccn_tool` 找不到	`ls -l /usr/local/Ascend/driver/tools` 看实际文件在不在、软链接有没有断
多卡之间通信异常	`hccn_tool` 查网口信息（官方定位：网络初始化、配置优化、故障排查）
要分析 Device 侧的问题	用 `msnpureport` 导出 Device 侧日志（接 E1 的日志三处）
一条命令在本机报"不支持"	先查部署场景（裸机 / 容器 / 虚拟机 / AVI），再对官方支持情况表
要把设备信息接进自建监控平台	用 DCMI（`npu-smi` 是给人敲的，DCMI 是给程序调的）

⭐ 一个最省时间的判断法

遇到"不支持 / command not found"这类问题，先分清是「没装」还是「这个场景不支持」。

没装 → 文件不存在（ls 看不到）→ 回 A1 装驱动
场景不支持 → 文件在、命令能识别，但执行报不支持 → 查官方的部署场景支持表
软链接断 → 文件在（ls -l 的实际路径能看到），但 which 找不到 → 修软链接

三种原因的处置完全不同，别混着试。

第八段 · 常见报错清单

⚠️ 本节是方法论清单（"遇到什么、去哪儿查"），不含编造的报错原文。查具体案例用官方故障案例库检索：https://www.hiascend.com/document/caselibrary/detail/<案例编号>

#	情况	去哪儿查
1	没有 `npu-smi`	A1 第八段（驱动层，含真实案例编号）
2	有 `npu-smi`、找不到 `hccn_tool`	查软链接与 `/usr/local/Ascend/driver/tools` 实际路径
3	命令报"当前场景不支持"	对官方「不同部署场景下的支持情况」表（Y/N/NA）
4	多卡通信问题	`hccn_tool` 的网口信息 + 官方集群网络文档
5	要看 Device 侧日志	`msnpureport`（与 E1 的日志三处呼应）

第九段 · 小结与下一课

三句话带走

驱动和固件是两个具体的东西；HDK 是"它们俩 + 随驱动一起装的那套工具集"这一片的统称。
HDK 四件套：npu-smi（设备管理，人敲）、DCMI（设备管理，程序调）、hccn_tool（集群网络）、msnpureport（Device 侧日志）。
同一命令在不同部署场景下支持情况不同——报"不支持"时先分清是没装、场景不支持、还是软链接断了。

本课在体系里的位置

A0 一张地图        ← 有哪几层，谁依赖谁
A1 驱动与固件      ← 卡怎么被系统认出来
A2 产品线与形态    ← 认出来的是张什么卡
A3 HDK 到底指什么  ← 驱动、固件、工具集是什么关系   ★ 本课
B1（拟）CANN：装在哪、环境变量、版本对应关系

本课留下的"钩子"

钩子	在哪一课填
CANN 与 HDK 的版本对应关系	B1
AVI（虚拟化实例）怎么切分 vNPU	F 场景实战
`hccn_tool` 的完整命令与多卡组网	F 场景实战

课后自测（3 题）

用一句话说清：驱动、固件、HDK 三者的关系。
npu-smi 和 DCMI 都能"管理设备"，什么情况下该用哪个？
一条官方文档上有的命令，你在机器上敲了报"不支持"。你的排查顺序是什么？

附录 A · 本课引用的官方出处

内容	出处
`npu-smi` / DCMI / `hccn_tool` / `msnpureport` 四者的定义、职责、安装路径	官方《Ascend HDK 接口和命令工具简介》（用户必读） `https://www.hiascend.com/document/detail/zh/HDK/2610/A3/A3HCCN/hccntool_003.html`
「不同部署场景下支持情况」的读表规则（Y/N/NA）	同上
部署场景分类（物理机／虚拟机／AVI 九个子场景）	同上，表 1
昇腾虚拟化实例 AVI 与 vNPU 的定义	同上
HDK 版本文档（26.1.x）	`zh/HDK/2610/` 文档树
`npu-smi` 命令与字段	见 A1《驱动与固件》附录（同一命令族）

附录 B · 本课出现的命令详解

`which <命令名>`

含义：在 PATH 环境变量列出的目录里，找这个命令实际会被执行到哪一个文件。
拆解：which（哪个）+ 一个命令名。
用法：which hccn_tool、which msnpureport
期望结果：输出该命令的完整路径（例如 /usr/bin/hccn_tool）；找不到则什么都不输出（不是报错）。
不用会怎样：只能凭"敲一下试试"判断工具在不在，试不出来也不知道为什么。

`ls -l <路径>`

含义：列出文件/目录的详细信息（权限、属主、大小、软链接指向）。
拆解：ls（list，列出）+ -l（long，长格式）。
用法：ls -l /usr/local/Ascend/driver/tools；单独看某个软链接：ls -l /usr/bin/hccn_tool
期望结果：如果那一项是软链接，输出形如 hccn_tool -> /usr/local/Ascend/driver/tools/hccn_tool —— 箭头右边就是实际文件。
关键用途：判断"软链接断了" —— 箭头指向的文件不存在时，命令会报"找不到"，但目录里其实还有东西。
不用会怎样：分不清"文件没了"和"软链接指向错了"，这两种的修法完全不同。

`npu-smi info -l` / `npu-smi info -t board -i 0`

见 A1《驱动与固件》附录 B（本课只是复用同一条命令族做 HDK 装机确认）。

参数速查表

命令	关键参数	含义
`which`	命令名	找命令的实际路径
`ls`	`-l`	长格式列出（能看到软链接指向）
`npu-smi info`	`-l` / `-t <类型>` / `-i <设备ID>`	见 A1 附录
`msnpureport`	见官方《msnpureport 工具使用指南》	导出 Device 侧日志

附：A1 / A2 / A3 三课分工（避免重复）

问题	在哪一课
驱动、固件各是什么、怎么装、安装顺序	A1
卡是哪一代、哪个系列、什么形态	A2
HDK 这个名字覆盖什么、四个工具各干什么、为什么场景会影响支持情况	本课（A3）
CANN 是什么、装在哪、环境变量	B1