企业官网建设流程全解析

• CANN
• Ascend
• 人工智能
• 任务调度

导读

Dump 功能是 CANN Runtime 在算子执行异常、精度问题与性能分析场景下的核心维测手段。本指南以example/5_performance/adump/目录下的示例为主线，系统讲解 CANN Runtime 提供的 Dump 能力体系——从"算子信息统计 → 回调式 Dump → 配置化 Dump → 异常算子 Dump"四个递进层次，覆盖aclopStartDumpArgs、acldumpRegCallback、aclmdlInitDump、acldumpSaveExceptionInfo等关键接口的调用方式，并结合dump_artifact_analysis_en.md给出 Dump 文件路径定位、转换命令与字段含义的完整分析方法。读完本文，你将掌握 Dump 的四种打开方式、输出路径的优先级规则，以及如何通过回调字段和 Tensor 字段对 Dump 产物进行准确的诊断与定位。

一、adump 示例目录与 Dump 能力全景

在 CANN Runtime 仓库中，example/5_performance/adump/ 目录集中承载了 Dump 相关的全部示例。从示例的组织结构可以看出 Dump 能力的演进路线，即"operator information statistics（算子信息统计）→ callback Dump（回调式 Dump）→ configuration-based Dump（配置化 Dump）→ Exception operator Dump（异常算子 Dump）"四个阶段：

• 0_adump_args：通过aclopStartDumpArgs/aclopStopDumpArgs导出单算子参数（算子信息文件），并查询当前 Dump 输出路径；
• 1_adump_callback：通过acldumpRegCallback/acldumpUnregCallback注册回调，以回调方式接收 Dump 数据，并演示acldumpChunk的基础解析；
• 2_model_dump_config：通过aclmdlInitDump/aclmdlSetDump/acldumpGetPath/aclmdlFinalizeDump组合，演示基于配置文件的 Dump；
• 3_save_exception_info：通过acldumpGetExceptionInfoPath/acldumpSaveExceptionInfo主动将自定义张量数据保存到异常算子 Dump 路径。

所有示例均支持 Ascend 950PR/Ascend 950DT、Atlas A3 训练/推理系列产品、Atlas A2 训练/推理系列产品。

二、环境准备与一键运行

2.1 运行前置条件

• 已安装 CANN 开发运行环境，默认安装根目录为/usr/local/Ascend；
• 已获取本仓库（cann/runtime）的示例代码。

2.2 编译运行步骤

参考各子示例 README 中的统一流程（以 0_adump_args/README_en.md 为例）：

# 1. 加载 CANN 环境变量，${install_root} 为 CANN 安装根目录，默认 /usr/local/Ascend source ${install_root}/cann/set_env.sh # 2. 自动识别 SOC_VERSION 与 ASCENDC_CMAKE_DIR source ${git_clone_path}/example/set_sample_env.sh # 3. 编译并运行单个示例 bash run.sh

2.3 批量运行全部 Dump 示例

adump/run.sh 提供了顺序执行全部四个示例的入口脚本：

bash run.sh

脚本行为如下：

• 首先source ../../common/resolve_cann_env.sh并调用resolve_cann_env完成 CANN 环境解析；
• 依次遍历0_adump_args、1_adump_callback、2_model_dump_config、3_save_exception_info四个示例目录，在每个子目录内执行bash run.sh；
• 每个示例执行成功打印[SUCCESS]，失败打印[FAILURE]并将failed置 1；
• 任一示例失败，脚本最终返回非零状态码exit 1，全部通过则打印[SUCCESS] All adump samples completed successfully.。

这种"逐示例执行 + 失败即退出非零"的设计，便于在 CI 或批量验证场景中快速定位失败项。

三、示例一：0_adump_args —— 单算子参数 Dump 与路径查询

3.1 功能定位

在单算子执行场景下，Dump 算子信息并输出到path参数指定的目录。其特点在于：每个 shape 对应一个算子信息文件，文件内容包含算子类型、算子属性、算子输入输出 format、数据类型、shape 等信息。需要注意的是，aclopStartDumpArgs输出的是算子信息文件而非张量数据文件。

3.2 核心调用序列

从 0_adump_args/main.cpp 的源码可以看到完整流程：

// 1. 初始化：aclInit + 设置 Device + 创建 Stream CHECK_ERROR(adump::InitRuntime(deviceId, &stream, dumpCfgPath)); // dumpCfgPath = "./acl.json" // 2. 开启算子参数 Dump 功能 CHECK_ERROR(aclopStartDumpArgs(ACL_OP_DUMP_OP_AICORE_ARGS, dumpPath)); // dumpPath = "/tmp" LogDumpPath(DATA_DUMP, dumpPath); // 查询当前 Dump 输出路径 // 3. 构造输入输出（shape 为 {4, 2} 的 aclTensor），调用算子库接口 CHECK_ERROR(aclnnAddGetWorkspaceSize(self, other, alpha, out, &workspaceSize, &executor)); CHECK_ERROR(aclnnAdd(workspaceAddr, workspaceSize, executor, stream)); // 4. 等待任务完成并拷贝结果 CHECK_ERROR(aclrtSynchronizeStream(stream)); CHECK_ERROR(aclrtMemcpy(resultData.data(), ..., ACL_MEMCPY_DEVICE_TO_HOST)); // 5. 关闭算子参数 Dump 功能 CHECK_ERROR(aclopStopDumpArgs(ACL_OP_DUMP_OP_AICORE_ARGS)); // 6. 释放资源并反初始化 CHECK_ERROR(aclrtDestroyStream(stream)); CHECK_ERROR(aclrtResetDeviceForce(deviceId)); CHECK_ERROR(aclFinalize());

其中关键 API：

示例同时覆盖了 Device 管理（aclrtSetDevice/aclrtSynchronizeDevice/aclrtResetDeviceForce）、Stream 管理（aclrtCreateStream/aclrtSynchronizeStream/aclrtDestroyStream）、内存管理（aclrtMalloc/aclrtFree）与数据搬移（aclrtMemcpy）等 Runtime 基础能力。

3.3 配置与输出

该示例的 acl.json 内容为：

{"dump": {"dump_path": "./", "dump_list": [], "dump_op_switch": "on", "dump_data": "tensor"}}

示例运行后的典型输出如下（摘自 0_adump_args/README_en.md）：

[INFO] The dump data path is /tmp. [INFO] acldumpGetPath returned dump path: ... [INFO] result[0] is: 1.000000 ... [INFO] result[7] is: 11.000000 [INFO] Run the device_normal sample successfully. please make sure dump data has been in path: /tmp

四、示例二：1_adump_callback —— 回调方式接收 Dump 数据

4.1 功能定位

当不希望 Dump 数据直接落盘、而希望在宿主进程内即时处理时，可以通过注册回调函数的方式接收 Dump 数据。示例在单算子执行场景下注册acldumpRegCallback回调，在回调中解析acldumpChunk的 fileName、offset、isLastChunk、flag 及数据预览，并输出汇总统计。

4.2 核心调用序列

从 1_adump_callback/README_en.md 可知其关键接口：

• 初始化：aclInit→acldumpRegCallback（注册 Dump 回调）→acldumpGetPath（查询输出路径）→acldumpUnregCallback（注销回调）→aclFinalize；
• 回调数据解析：在回调内解析acldumpChunk的 fileName、offset、isLastChunk、flag 与数据预览；
• acldumpGetPath：与回调中收到的文件名做对应，确认 Dump 数据来源目录。

其配置同样位于 1_adump_callback/acl.json，与算子参数示例一致：

{"dump": {"dump_path": "./", "dump_list": [], "dump_op_switch": "on", "dump_data": "tensor"}}

4.3 典型输出

[INFO] acldumpGetPath returned dump path: ... [INFO] Receive dump tensor data success. file=..., bufLen=..., isLastChunk=..., offset=..., flag=..., preview=... ... [INFO] Dump callback summary: total chunks=..., total bytes=..., total files=... [INFO] Run the device_normal sample successfully.

输出中的Dump callback summary直接给出本次回调接收到的分片总数、总字节数与文件总数，用于快速判断 Dump 数据是否完整。

五、示例三：2_model_dump_config —— 基于配置文件的模型级 Dump

5.1 功能定位

该示例在单算子 API 场景中使用模型级 Dump 配置接口，与目录中其他示例互补，展示配置化 Dump 的用法。配置文件采用单算子 Dump 场景推荐的dump_op_switch: on配置。

5.2 核心调用序列

• 初始化：aclInit→aclmdlInitDump（初始化 Dump 配置）→aclmdlSetDump（加载 Dump 配置文件）→acldumpGetPath（查询当前 Dump 输出路径）→aclmdlFinalizeDump（结束当前 Dump 配置）→aclFinalize；
• 其余为常规的 Device/Stream/内存/搬移管理。

其 acl.json 与算子参数示例的差别在于dump_list中放入了一个空对象[{}]：

{"dump": {"dump_path": "./", "dump_list": [{}], "dump_op_switch": "on", "dump_data": "tensor"}}

5.3 典型输出

[INFO] Configured model dump path is: ... [INFO] result[0] is: 1.000000 ... [INFO] Run the model dump config sample successfully.

六、示例四：3_save_exception_info —— 主动保存自定义张量到异常算子 Dump 路径

6.1 功能定位

在实际工程中，部分组件或框架需要在算子发生异常时保存自定义数据。该示例通过dump_scene=aic_err_brief_dump开启异常算子 Dump，先运行一个正常的aclnnAdd算子，随后：

1. 调用acldumpGetExceptionInfoPath查询异常算子 Dump 根路径（含 deviceId）；
2. 构造acldumpTensorInfo（复用算子的 Device 地址、shape 与数据类型），调用acldumpSaveExceptionInfo在该路径下保存张量数据，userTag会写入 Dump 文件 proto 头的 OpAttr 中。

6.2 关键约束（务必遵守）

• fileName是相对路径：不能为空，也不能包含..段，最终落盘位置被限制在异常算子 Dump 根路径之内；
• 避免重复覆盖：为避免重复运行覆盖已有文件，示例在fileName后追加.custom.{毫秒级时间戳}后缀作为实际落盘文件名，例如save_exception_info变为save_exception_info.custom.20260721153012345；
• 必须先开启异常算子 Dump：调用前必须通过dump_scene=aic_err_brief_dump开启异常算子 Dump，否则接口返回失败；
• 地址与放置类型：该接口直接把tensorAddr作为 Device 数据地址读取，因此示例将addrType置为ACL_DUMP_ADDR_RAW、placement置为ACL_DUMP_PLACEMENT_DEVICE。

6.3 配置与输出

3_save_exception_info/acl.json 采用异常算子 Dump 场景的专用配置：

{ "dump": { "dump_path": "./", "dump_scene": "aic_err_brief_dump" } }

典型输出：

[INFO] acldumpGetExceptionInfoPath success, exception dump path is: .../extra-info/data-dump/0/ [INFO] acldumpSaveExceptionInfo success, data has been saved under exception dump path: .../extra-info/data-dump/0/ [INFO] result[0] is: 1.000000 ... [INFO] Run the save_exception_info sample successfully.

七、Dump 文件路径规则与优先级

依据 dump_artifact_analysis_en.md 的说明，Dump 文件目录由 Dump 类型、配置与环境变量共同决定，具体规则如下：

• 模型 Dump、单算子数据 Dump、溢出算子 Dump：目录由配置文件中的dump_path指定，环境变量不会覆盖该路径；
• 算子信息统计：目录由aclopStartDumpArgs(uint32_t dumpType, const char *path)的path参数指定，该接口只输出算子信息文件，不输出张量数据文件；
• 当前输出路径查询：可调用acldumpGetPath(acldumpType dumpType)查询某 Dump 类型的当前输出路径；
• 异常算子 Dump 根路径：为<dumpPath>/extra-info/data-dump/<deviceId>/，其路径优先级为ASCEND_DUMP_PATH>ASCEND_WORK_PATH> 配置文件中的dump_path> 当前目录./，也可调用acldumpGetExceptionInfoPath(char *path, size_t maxLen)查询。

各 Dump 类型的路径定位方式汇总：

八、Dump 文件转换与数据分析

8.1 张量 Dump 文件转换

使用msaccucmp.py convert将张量 Dump 文件转换为便于查看的格式，以下示例以 NumPy 为目标：

msaccucmp.py convert -d <dump_file> -out <output_dir>

注意：aclopStartDumpArgs生成的算子信息文件不适用于上述张量 Dump 转换命令。

转换完成后，用 Python 直接查看 NumPy 数据：

import numpy as np data = np.load("<converted_file>.npy") print(data.shape) print(data.dtype) print(data)

8.2 大数据量下的快速体检

当数据量较大时，应优先检查 shape、dtype、最大值、最小值以及是否包含 NaN 或 Inf，而不是直接打印全部数据：

import numpy as np data = np.load("<converted_file>.npy") print("shape:", data.shape) print("dtype:", data.dtype) print("min:", np.nanmin(data)) print("max:", np.nanmax(data)) print("has_nan:", np.isnan(data).any()) print("has_inf:", np.isinf(data).any())

这套"先 shape/dtype/范围/异常值，再数值比对"的顺序，与后文的分析建议一脉相承，能够显著减少精度问题排查时的无效操作。

九、回调字段与张量字段详解

9.1acldumpChunk回调字段

注册acldumpRegCallback回调后，回调函数可通过acldumpChunk获取分块（chunk）的 Dump 数据。各字段含义与建议如下：

9.2acldumpTensorInfo张量字段

在异常算子 Dump 或自定义张量保存场景中，acldumpTensorInfo的关键字段如下：

十、Dump 问题定位的实战建议

综合 dump_artifact_analysis_en.md 与各示例的实际用途，可按以下顺序展开分析：

1. 先定位文件：根据路径优先级、配置文件dump_path或 API 返回的路径，确认文件是否按预期生成，再选择需要转换和查看的文件；
2. 精度问题先查元数据：比对 shape、dataType、format 是否符合预期，再比较数值差异，避免在元数据错误的情况下误判数值结果；
3. 异常算子 Dump 结合日志：先查看异常算子名称、输入、输出、workspace 与 Tiling 信息，再结合 Runtime 日志或 AI Core Error 信息定位问题；
4. 分块数据先还原再分析：对回调方式接收的分块数据，必须依据fileName、offset、isLastChunk还原出完整文件后再进行分析，切忌对单个分块直接下结论。

十一、小结

CANN Runtime 的 adump 示例目录以四个递进示例完整覆盖了 Dump 能力的不同打开方式：aclopStartDumpArgs面向算子信息统计与单算子参数导出，acldumpRegCallback面向进程内实时接收分块数据，aclmdlInitDump/aclmdlSetDump面向配置文件驱动的模型级 Dump，acldumpGetExceptionInfoPath/acldumpSaveExceptionInfo面向异常场景下自定义张量的主动保存。配合acldumpGetPath的路径查询能力与msaccucmp.py convert的转换工具链，开发者可以在算子精度、异常与溢出排查中快速建立"开启 Dump → 定位文件 → 转换数据 → 校验元数据 → 数值比对"的完整工作流。更多 API 的调用顺序与参数约束，可进一步参考 Dump 配置 API 参考文档。

• CANN
• Ascend
• 人工智能
• 任务调度