Ascend C 环境检查

快速检查开发环境配置和 NPU 设备状态。

工作流程

环境检查
    │
    ├─ NPU 设备检查
    │   └─ npu-smi info -m / scripts/npu_info.sh
    │
    ├─ CANN 环境检查
    │   └─ scripts/check_env.sh
    │
    └─ NPU 架构检测
        └─ scripts/get_npu_arch.py

NPU 设备检查

快速命令

# 查看设备详细信息（包含设备列表）
npu-smi info

# 监控设备资源
npu-smi info -t usages -i <device_id>

脚本工具

# 综合 NPU 信息（推荐）
bash scripts/npu_info.sh

详细命令参数见 npu_commands.md，npu-smi 不可用时的回退方案见 asys_commands.md

CANN 环境检查

# 完整环境检查（推荐）
bash scripts/check_env.sh

检查项

检查项	说明	必需
ASCEND_HOME_PATH	CANN Toolkit 路径	是
CANN 版本	检测版本号及运行时依赖基线	建议确认
ASCEND_OPP_PATH	CANN Ops 路径	运行时必需
自定义算子包	op_api 库	运行自定义算子必需
CANN 工具	msprof/cannsim	可选
Simulator状态	检查必要的模拟器状态	KirinX90、Kirin9030 等 Kirin 平台开发必需

⚠️ 注意：官方环境变量为 ASCEND_HOME_PATH，不是 ASCEND_HOME。部分旧文档或示例代码可能使用 ASCEND_HOME，这是错误用法。

详细环境配置见 env_config_guide.md，版本配套关系见其中「CANN 版本兼容性」章节

NPU 架构检测

前置条件：先 source CANN 安装目录下的 set_env.sh（asys 与 DSMI 库依赖其 PATH / LD_LIBRARY_PATH）。

重要：npu-smi 的 Chip Name 作为 short-soc-version 不可信（A3 机型误报 Ascend910，issue #587），禁止用于芯片型号识别。

# 人读报告（含用途注释与证据链）
python3 scripts/get_npu_arch.py

# 仅输出裸 NpuArch 数值（如 3510）
python3 scripts/get_npu_arch.py --raw

# 机器可读 JSON（键名：full_soc / full_soc_source / npu_arch / npu_arch_source / short_soc / ccec_aiv_version / variant_dir / ini_path / npu_count / warnings）
python3 scripts/get_npu_arch.py --json

获取链：

获取项	优先来源	备选来源
full-soc-version（如 Ascend950PR_9579）	asys info -r=hardware Chip Info	DSMI dsmi_get_chip_info
NpuArch（如 3510）	asys Arch Info	ini 文件（full-soc-version 精确匹配）
short-soc-version / CCE_AIV_version / variant_dir	ini 文件	—

• short-soc-version（如 Ascend950）用于算子原型定义文件 xxx算子_def.cpp 的 AddConfig() 第一个参数（如 this->AICore().AddConfig("ascend950", aicConfig)）
• variant_dir（如 dav_c310）决定读CANN安装目录下源码时只看 **/dav_c310/ 下的文件
• ini 匹配按 SoC_version= 字段精确匹配，禁止文件名/前缀模糊匹配

依赖：Ascend driver 和 CANN toolkit。

诊断脚本

脚本	用途
scripts/npu_info.sh	NPU 设备信息综合查询
scripts/check_env.sh	CANN 环境配置检查
scripts/get_npu_arch.py	运行时检测当前设备 NPU 架构

也可直接调用 _npu_info.py Python 脚本获取结构化数据，支持 --json（完整 JSON 输出）、--list（设备 ID 列表）、--health（健康状态）等参数。

Kirin 平台开发

Kirin 系列芯片（KirinX90、Kirin9030等以 Kirin 开头的平台）是端侧 AI 处理器，当前主要支持使用模拟器 Simulator 的开发方式，需要注意环境检查结果中的 Simulator 支持情况，如不支持则环境检查结论是不支持 Kirin 平台开发，需要强调并告知用户。

当前 Kirin 开发使用的 CANN 版本和服务器有差异，Kirin 系列芯片开发，需要安装对应的 mobile-station 版本的 CANN 才有 Kirin 的 Simulator。

详细内容（mobile-station CANN 的安装方法、常见问题）见 kirin_platform_guide.md

常见问题

• NPU 不可见：先执行 npu-smi info -m 检查设备映射表，再排查驱动是否安装正确
• 算子运行失败：优先运行 check_env.sh 检查环境配置是否完整，并检查关键环境变量（ASCEND_HOME_PATH、ASCEND_OPP_PATH）是否已正确设置
• 确认是否有进程占用 NPU：使用 npu-smi info -t usages -i <device_id> 查看运行中的进程；注意空闲设备仍会有少量 HBM 被驱动占用（正常现象），不应误判为设备被占用

详细排查见 troubleshooting.md