前言

算子开发是CANN生态的重要环节，但调试算子往往比开发算子更耗时。CANN asc-tools是一套算子调试工具集，包含正确性校验、CPU仿真、融合编译、SIM仿真等功能。昇腾NPU的算子调试有其特殊性：硬件指令复杂、错误信息晦涩、设备访问受限。asc-tools的设计目标是降低调试门槛，提高开发效率。

传统GPU算子调试可以使用CUDA-MEMCHECK、Nsight等工具。昇腾NPU缺乏类似的成熟工具生态，asc-tools填补了这一空白。它提供从开发期调试到部署期验证的全流程支持，让算子开发者不必每次都上机测试。

本文采用手把手实战模式，从工具安装到具体使用，完整呈现asc-tools的功能。

asc-tools工具链全景

asc-tools包含多个工具，各司其职。npuchk是算子正确性校验工具，对比NPU输出与CPU参考实现。cpudebug是CPU仿真调试工具，无需NPU硬件即可调试算子。融合编译工具支持算子融合和异构调用。SIM仿真工具提供更高精度的仿真环境。

工具之间的关系是层层递进的。开发期使用cpudebug快速迭代，无需等待NPU调度。初步验证后使用npuchk进行正确性校验。部署前使用融合编译优化性能。如果结果与预期不符，使用SIM仿真定位问题。

# 查看asc-tools安装位置
which npuchk
which cpudebug

# 查看版本
npuchk --version
cpudebug --version

工具的输入是算子二进制文件（.o或.so）和测试数据。测试数据可以是随机生成，也可以从真实模型中导出。输出是校验报告或调试日志，包含错误位置和可能原因。

npuchk算子校验详解

npuchk的核心功能是对比NPU输出与预期输出。它运行算子，收集输出数据，与参考实现对比，判断是否通过校验。参考实现可以是CPU版本算子，也可以是预设的金标准数据。

校验流程分为三步：数据生成、算子执行、结果对比。数据生成阶段，npuchk根据输入描述生成测试数据。算子执行阶段，npuchk加载算子二进制，在NPU上执行。结果对比阶段，npuchk计算输出与参考的差异，判断是否在容忍范围内。

# npuchk基本用法
npuchk \
  --operator my_add.o \
  --input "float16[1024,1024]:random" \
  --input "float16[1024,1024]:random" \
  --output "float16[1024,1024]" \
  --golden golden_output.bin \
  --rtol 0.001 \
  --atol 0.001

# 参数说明
# --operator: 算子二进制文件
# --input: 输入描述，格式为"类型[形状]:数据源"
# --output: 输出描述
# --golden: 参考输出文件
# --rtol/atol: 相对/绝对误差容忍度

误差容忍度是校验的关键参数。浮点计算存在精度损失，不可能要求完全一致。rtol（相对误差）和atol（绝对误差）共同决定容忍范围。npuchk判断公式为：|actual - expected| <= atol + rtol * |expected|。

npuchk支持多种数据生成方式。random生成随机数据，适合通用测试。file从文件加载数据，适合回归测试。golden从参考输出推导输入，适合反向验证。

# 从文件加载测试数据
npuchk \
  --operator my_matmul.o \
  --input "float16[256,256]:file:input_a.bin" \
  --input "float16[256,256]:file:input_b.bin" \
  --output "float16[256,256]" \
  --golden output_golden.bin \
  --rtol 0.001

校验失败时，npuchk会输出错误位置和差异统计。差异统计包括最大误差、平均误差、误差分布。这些信息有助于定位问题：如果误差均匀分布，可能是算法问题；如果误差集中在某个区域，可能是边界条件问题。

cpudebug CPU仿真调试详解

cpudebug是在CPU上仿真运行NPU算子的工具。它不需要NPU硬件，在开发机上即可调试算子逻辑。仿真精度与NPU略有差异，但逻辑正确性可以保证。

cpudebug的工作原理是解释执行算子的中间表示。NPU算子编译后生成中间表示（类似汇编），cpudebug逐条解释这些指令，在CPU上模拟执行。这种解释执行比NPU慢很多，但对于调试已经足够。

# cpudebug基本用法
cpudebug \
  --operator my_add.o \
  --input "float16[1024]:random" \
  --input "float16[1024]:random" \
  --output "float16[1024]" \
  --log-level debug

# 参数说明
# --log-level: 日志级别，debug输出详细执行过程

日志级别控制输出详细程度。error只输出错误信息，warn输出警告和错误，info输出关键步骤，debug输出每条指令的执行结果。调试时建议使用debug级别，定位问题后切换到info减少输出。

cpudebug支持断点调试。可以设置条件断点，当变量满足特定条件时暂停执行。这对于定位循环中的错误很有帮助。

# 设置断点
cpudebug \
  --operator my_conv.o \
  --input "float16[1,3,224,224]:random" \
  --output "float16[1,64,112,112]" \
  --breakpoint "loop_idx==128" \
  --interactive

# 交互模式下可以查看变量值、单步执行、继续运行

cpudebug的局限性在于精度差异。某些NPU特有的数值行为在CPU上无法完美复现，如FP16的舍入方式、累加器的精度等。对于这类问题，需要结合npuchk在NPU上验证。

融合编译与异构调用调试

融合编译是将多个算子合并为一个复合算子的过程。asc-tools提供融合编译工具，支持用户自定义融合规则。融合后的算子减少内存访问，性能提升显著。

融合编译的输入是多个算子二进制和融合描述文件。融合描述文件指定算子的连接方式、中间数据的内存布局。工具生成融合后的算子二进制，可以直接在NPU上执行。

# 融合编译示例
asc-fusion \
  --operators "conv.o,bn.o,relu.o" \
  --fusion-plan fusion_plan.json \
  --output fused_conv_bn_relu.o

# fusion_plan.json 描述算子连接
cat fusion_plan.json
# {
#   "inputs": ["conv_input"],
#   "outputs": ["relu_output"],
#   "connections": [
#     {"from": "conv", "to": "bn"},
#     {"from": "bn", "to": "relu"}
#   ]
# }

异构调用是指算子内部调用其他算子或运行时API。这种模式在复杂算子中常见，如Flash Attention内部调用矩阵乘和softmax。调试异构调用需要追踪调用链，asc-tools提供了调用图分析功能。

# 分析异构调用
asc-analyze \
  --operator flash_attention.o \
  --call-graph

# 输出调用图
# flash_attention -> matmul -> cube_mmad
#                -> softmax -> vector_reduce

SIM仿真模式详解

SIM（Software In-Memory）仿真是asc-tools提供的高精度仿真环境。它在CPU上模拟NPU的完整行为，包括内存层次、流水线调度、指令冲突等。SIM仿真的精度比cpudebug更高，但速度也更慢。

SIM仿真适用于定位与硬件行为相关的问题。例如，某个算子在cpudebug上正确，在NPU上错误，可能是流水线冲突或缓存一致性导致。SIM仿真可以复现这类问题。

# SIM仿真示例
asc-sim \
  --operator my_attention.o \
  --input "float16[1,32,1024,64]:random" \
  --output "float16[1,32,1024,64]" \
  --config sim_config.yaml

# sim_config.yaml 配置仿真参数
# memory_model: detailed  # 详细内存模型
# pipeline_stall: true    # 模拟流水线停顿
# cache_coherence: true   # 模拟缓存一致性

SIM仿真的配置参数很多，主要分为三类：内存模型配置控制内存访问延迟和带宽；流水线配置控制指令调度和冲突；精度配置控制数值精度。

SIM仿真与真实NPU的差距主要在性能上。SIM仿真速度约为真实NPU的千分之一，仅适合调试单个算子，不适合性能测试。

常见调试失败案例分析

调试过程中会遇到各种错误。asc-tools提供了错误码和诊断建议，帮助开发者快速定位问题。

内存越界是最常见的错误。当算子访问超出分配范围的内存时，触发内存越界。npuchk会检测到这种错误，输出越界位置和访问大小。

# 内存越界错误示例
npuchk --operator my_op.o ...
# Error: Memory access out of bounds
#   Address: 0x7fff0000 (expected range: 0x0000-0x0fff)
#   Access size: 16 bytes
#   Kernel: my_kernel, line 42

精度不达标是另一类常见错误。算子输出与参考差异超过容忍度，触发精度错误。npuchk会输出误差分布，帮助判断是算法问题还是数值问题。

# 精度不达标错误示例
npuchk --operator my_op.o --rtol 0.001 ...
# Error: Accuracy check failed
#   Max error: 0.0156 (at position [128, 256])
#   Mean error: 0.0023
#   Error distribution: 45% in [0, 0.001], 50% in [0.001, 0.01], 5% > 0.01
#   Suggestion: Check quantization or rounding behavior

死锁是异构调用特有的错误。当算子内部的同步机制不当时，可能造成死锁。SIM仿真可以检测死锁，输出等待图。

# 死锁检测示例
asc-sim --operator my_op.o ...
# Error: Deadlock detected
#   Thread 0 waiting for Thread 1
#   Thread 1 waiting for Thread 0
#   Wait graph: 0 -> 1 -> 0

dump数据导出是高级调试手段。当错误难以定位时，可以导出算子执行过程中的中间数据，逐层对比与预期的差异。

# 导出中间数据
npuchk --operator my_op.o --dump-intermediate

# 生成的dump文件
# input_0.bin
# intermediate_0.bin
# intermediate_1.bin
# output.bin

oat_check是自动化检查工具，可以批量检查算子的常见问题。它静态分析算子代码，发现潜在的bug和性能问题。

# 自动化检查
oat_check my_op.o

# 输出检查结果
# [WARNING] Unused variable: temp
# [ERROR] Possible integer overflow: idx * sizeof(float)
# [SUGGESTION] Use vector instruction for better performance

调试最佳实践

算子调试是一个系统工程，需要有序进行。推荐的工作流程是：单元测试驱动开发，仿真调试快速迭代，NPU验证最终确认。

单元测试应该在算子开发的同时编写。每个算子至少需要一个正向测试和一个边界测试。正向测试验证典型输入的正确性，边界测试验证极端输入的健壮性。

import torch_npu
from my_ops import custom_add

def test_basic():
    a = torch.randn(1024, device="npu")
    b = torch.randn(1024, device="npu")
    result = custom_add(a, b)
    expected = a + b
    assert torch.allclose(result, expected, rtol=1e-3)

def test_edge_cases():
    # 零张量
    zero = torch.zeros(1024, device="npu")
    assert custom_add(zero, zero).sum() == 0
    
    # 大值张量
    large = torch.full((1024,), 1e10, device="npu")
    result = custom_add(large, large)
    assert not torch.isnan(result).any()  # 不应产生NaN
#  单元测试覆盖典型和边界场景，在开发阶段捕获大部分问题

仿真调试的价值在于快速迭代。每次修改算子代码后，可以在CPU上立即测试，无需等待NPU调度。仿真结果与NPU结果可能有小差异，但逻辑错误可以准确定位。

NPU验证是最终确认步骤。仿真通过不代表NPU一定正确，因为仿真无法完全复现硬件行为。NPU验证应该覆盖性能测试和精度测试两个方面。

import torch_npu
import time

def benchmark(op, inputs, warmup=10, repeat=100):
    # 预热
    for _ in range(warmup):
        op(*inputs)
    torch_npu.npu.synchronize()
    
    # 计时
    start = time.time()
    for _ in range(repeat):
        op(*inputs)
    torch_npu.npu.synchronize()
    elapsed = time.time() - start
    
    return elapsed / repeat

# 性能测试
latency = benchmark(custom_add, [a, b])
print(f"Latency: {latency*1000:.2f}ms")
#  性能测试需要同步等待，避免异步执行导致的计时错误

与其他调试工具的协作

asc-tools可以与其他CANN调试工具协作，形成完整的调试工具链。常见的协作模式包括：npuchk验证正确性、msprof分析性能、asc-tools定位问题。

msprof是CANN的性能分析工具，可以采集算子执行的时间线、内存访问、核利用率等信息。当npuchk发现算子正确但性能不达标时，使用msprof分析瓶颈。

# 使用msprof分析算子
msprof --output=./profiling_data python my_test.py

# 查看分析结果
msprof --parse=./profiling_data

asc-tools与msprof的协作在于：asc-tools定位算法错误，msprof定位性能瓶颈。两者互补，覆盖调试的不同维度。

CI/CD集成与自动化测试

将asc-tools集成到CI/CD流水线，可以在代码提交时自动执行测试。这保证了每次提交的质量，避免问题累积。

npuchk适合作为正确性测试工具。在CI中运行npuchk，对比输出与金标准，如果差异过大则失败。

# GitLab CI示例
stages:
  - test

npuchk_test:
  stage: test
  script:
    - npuchk --operator my_op.o --golden golden.bin --rtol 0.001
  artifacts:
    when: on_failure
    paths:
      - npuchk_report.txt

cpudebug适合作为快速冒烟测试。在CI中运行cpudebug，确保算子可以编译和执行，不检查精度。

cpudebug_smoke:
  stage: test
  script:
    - cpudebug --operator my_op.o --log-level error
  timeout: 5m  # 限时5分钟

自动化测试的关键是测试覆盖率。每个算子应该有多个测试用例，覆盖正常输入、边界输入、异常输入。

test_cases = [
    {"name": "basic", "input": [(1024, 1024)], "expected": "pass"},
    {"name": "small", "input": [(16, 16)], "expected": "pass"},
    {"name": "large", "input": [(8192, 8192)], "expected": "pass"},
    {"name": "zero", "input": [(0, 0)], "expected": "error"},
]

for case in test_cases:
    try:
        npuchk --operator my_op.o --input {case['input']}
        assert case['expected'] == 'pass'
    except:
        assert case['expected'] == 'error'
#  全面的测试覆盖提前发现潜在问题

版本兼容性管理

asc-tools与CANN工具链有版本依赖关系。不同版本的asc-tools可能支持不同的功能或接口。管理版本兼容性对于长期维护很重要。

asc-tools遵循语义版本号规则。主版本号变化表示不兼容的接口变更，次版本号变化表示新增功能，修订号变化表示bug修复。

# 检查版本
npuchk --version
# 输出: npuchk 2.1.3
# 主版本=2, 次版本=1, 修订=3

版本兼容性矩阵记录了asc-tools与CANN toolkit的兼容关系。升级CANN toolkit时，需要检查asc-tools是否兼容。

asc-tools版本	CANN版本	兼容性
2.1.x	8.0.x	完全兼容
2.0.x	7.0.x	部分功能不可用
1.x	6.0.x	不兼容

建议在项目文档中明确记录使用的asc-tools版本，避免因版本不匹配导致的意外问题。

性能测试最佳实践

asc-tools不仅用于正确性验证，也可以用于性能测试。了解性能测试的最佳实践，可以获得准确的性能数据。

性能测试的一个常见错误是忽略预热。首次调用算子时会有编译和初始化开销，这部分开销不应计入性能测试。应该先运行几次预热，再开始计时。

import torch_npu
import time

# 预热
for _ in range(10):
    output = my_op(input)
torch_npu.npu.synchronize()  # 等待预热完成

# 计时
start = time.time()
for _ in range(100):
    output = my_op(input)
torch_npu.npu.synchronize()  # 等待计算完成
elapsed = time.time() - start
print(f"Average latency: {elapsed/100*1000:.2f}ms")
#  预热避免冷启动影响，同步避免异步执行导致的计时错误

性能测试的另一个关键是稳定性。同一算子多次运行的延迟可能有波动，应该运行多次取平均值或中位数。

import statistics

latencies = []
for _ in range(100):
    start = time.time()
    output = my_op(input)
    torch_npu.npu.synchronize()
    latencies.append(time.time() - start)

print(f"Mean: {statistics.mean(latencies)*1000:.2f}ms")
print(f"Median: {statistics.median(latencies)*1000:.2f}ms")
print(f"StdDev: {statistics.stdev(latencies)*1000:.2f}ms")
#  标准差反映性能稳定性，标准差大说明有干扰

性能对比测试需要控制变量。对比不同实现时，应保持输入规模、硬件环境、编译选项一致。

# 对比测试示例
implementations = [impl_a, impl_b, impl_c]
results = {}

for impl in implementations:
    # 相同的输入、相同的预热、相同的迭代次数
    warmup_and_benchmark(impl, input, warmup=10, repeat=100)
    results[impl.name] = elapsed

print(results)
#  控制变量确保对比公平，性能差异来源于实现本身

调试工作流程总结

将asc-tools整合到日常开发工作流程中，可以最大化其价值。推荐的工作流程如下：

开发阶段：编写算子代码，使用cpudebug快速验证逻辑。cpudebug响应快，适合频繁迭代。

集成阶段：将算子集成到模型，使用npuchk验证正确性。npuchk提供详细的错误报告，帮助定位问题。

优化阶段：使用SIM仿真分析硬件行为，使用msprof分析性能瓶颈。两者结合可以找到优化方向。

部署阶段：将asc-tools集成到CI/CD，自动执行回归测试。保证每次提交的质量。

这个工作流程覆盖了算子开发的完整生命周期，从开发到部署都有相应工具支持。

调试高级技巧

除了基本的调试功能，asc-tools还提供了一些高级技巧，应对复杂场景。

技巧一是条件断点。在cpudebug中设置条件断点，只在特定条件下暂停执行。这对于定位偶发问题很有用。

import cpudebug

# 设置条件断点
cpudebug.set_breakpoint(
    "my_op.o",
    condition="i == 128 and iter == 10"
)

# 运行到断点
result = cpudebug.run(my_op, input)
#  条件断点缩小问题范围，避免在大量正确迭代中手动翻找

技巧二是反向调试。某些错误在发生后难以定位，反向调试可以让程序倒退执行，找到错误源头。

import cpudebug

# 启用记录模式
cpudebug.enable_recording()

# 执行程序
result = cpudebug.run(my_op, input)

# 发现错误后倒退
cpudebug.reverse_step()
cpudebug.reverse_continue()
#  反向调试适合定位难以复现的问题，如内存损坏

技巧三是内存访问追踪。追踪所有内存访问，发现越界或未初始化访问。

import cpudebug

# 启用内存追踪
cpudebug.enable_memory_trace()

# 执行程序
result = cpudebug.run(my_op, input)

# 查看内存访问记录
trace = cpudebug.get_memory_trace()
for access in trace:
    print(f"{access.type} at {hex(access.addr)}, size={access.size}")
#  内存追踪发现隐藏的内存问题，如读越界、写野指针

技巧四是多算子联合调试。当多个算子组合时，问题可能出现在交互处。asc-tools支持多算子联合调试。

import cpudebug

# 加载多个算子
op1 = cpudebug.load("op1.o")
op2 = cpudebug.load("op2.o")

# 设置断点
op1.set_breakpoint("exit")
op2.set_breakpoint("entry")

# 联合执行
result = cpudebug.run_pipeline([op1, op2], input)
#  联合调试验证算子交互正确性，发现接口不匹配问题

这些高级技巧需要一定的学习成本，但在复杂问题定位中能发挥重要作用。

效率对比

调试维度	传统方式	asc-tools优化	差异来源
调试周期	上机测试每次30分钟	cpudebug本地调试	调试周期从天级降至小时级
错误定位	手动对比数据	npuchk自动报告	错误定位时间从小时降至分钟
仿真精度	无法模拟	SIM高精度仿真	复现NPU特有行为，定位硬件相关问题
回归测试	手动执行	自动化检查	每次提交自动检查，问题拦截率提升90%

---

仓库链接：https://atomgit.com/cann/asc-tools