CANN/PyPTO精度调试指南

精度调试【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto简介当PyPTO算子执行后无功能告警或报错但输出数据不符合预期时可基于以下方法进行精度问题的定界和定位。精度问题主要来源于两个方面功能错误硬件静默故障、软件静默功能问题、公式实现错误引起的明显数据错误或误差。计算误差数据类型、算法切分、累积、公式近似差异等引起的明显数据误差。整体流程确认问题合法性确认问题判定方式是否合理经验判断与实验证明。误差阈值是否使用合理例如存在bfloat16等低精度数据类型的算子使用了float32的误差阈值。计算路径较深的算子使用了小算子的误差阈值。对于不合理部分根据经验进行修正若问题消失则完成精度调试。确认问题可稳定复现。重复执行多轮输出数据一致且为异常值。更换其它环境多轮输出仍旧一致且为异常值。若无法稳定复现则明确为功能问题建议中止精度调试。基础预检基础预检为指导性说明指出常见但易被忽视的高概率出错问题。如果用户或调试人员确认相应检查项无误可以跳过这些步骤。借助asys工具检查硬件问题。使用硬件自检工具排除硬件安装问题。使用硬件压测工具排除硬件故障。检查软件问题。基于安装指导确认软件版本正确。执行项目中example用例确认结果正确。检查用户侧是否引入问题。多方评审算子代码确认计算过程与算法原型一致。数据类型、计算类型与竞品实现一致若无竞品实现需由提供算子实现方案的设计人员完成类型确认。若无法确认则分析后续发现的问题点时需额外分析是否为用户侧引入。规避已知问题精度调试前应确保已规避当前软件存在的已知问题详细请参见已知问题。缩小问题规模缩小问题规模通常是一个可选步骤旨在简化问题提高复现和定位的效率。缩小问题规模后需能复现同样问题然后继续进行后续的工具自检或人工调试对于缩小后出现新问题的情况建议尝试其它缩小方法以复现原始问题不建议将新问题纳入关键定位流程。然而在某些情况下缩小问题规模是必选步骤例如对于较大的模型主机内存不足导致自检工具无法执行。文件存储空间过小导致自检工具无法保存中间计算数据。其它分析流程或工具的耗时超过主观容忍范围甚至无法执行等阻塞式情况。通常通过以下方法缩小问题规模减少子图数量和大小。例如减少loop的次数或减少cube/vector Tiling块的个数即增大TileShape的大小。裁剪模型。例如调小模型的Shape规格如batch_size、seq_len等。采用二分法移除尾部计算。按模型计算的顺序采用二分法移除靠近尾部的计算并将断开的输出加入算子的输出列表。执行算子并观察、分析新的输出列表如果数据正常无 inf/nan、无主观认为随机的值、或与参考基准数据误差较小则返回上步继续二分操作。如果数据存在异常则将代码恢复到本次移除前的状态作为最新的候选问题场景。如果裁剪后的模型规模已经很小可以停止二分操作并选择最新的候选问题场景进行后续的定位。工具自检和分析工具简介PyPTO在计算图编译的各Pass阶段拥有完整的中间表示可翻译成第三方计算代码并在其它计算单元例如Host CPU上模拟计算过程。该工具通过模拟计算结果与基准数据的误差对比可以检测算子异常或者某个Pass的处理结果是否存在异常并定位首个出现异常的计算节点。主要特性及使用场景Tensor Graph校验用于校验算子代码、框架前端处理的正确性。基于用户提供的基准golden输入输出数据与Tensor Graph模拟计算的最终结果对比检测整体计算的正确性。常用于以下情况当用户存在可用的算子基准golden输入、输出数据时可先使能粗检特性粗略排除算子代码、框架前端处理是否引入差异。Pass阶段校验用于自检Pass的正确性。基于各Pass模拟计算的结果对比检测Pass正确性及异常计算节点。常用于以下情况当用户算子精度刚刚出现问题且没有明确方向可先使能自检特性排除Pass处理阶段是否引入潜在错误。当用户大致明确某个Pass出问题时使能自检特性获取该Pass及前序Pass的模拟计算中间数据对比数据找出潜在出问题的计算操作。中间结果分析指定单个计算结果保存到文件或者以可读形式打印到输出、日志。当Tensor Graph校验失败时可使用pass_verify_print/pass_verify_save特性打印、保存模拟计算的中间数据对比数据找出潜在出问题的计算操作。使用约束当前精度调试工具存在以下限制完整计算流表示仅保存在pass运行上下文中无法使用检测功能不支持上板执行的中间数据检查仅支持前端及pass的检查。不支持特定pass特定pass例如SubgraphToFunction属于中间的优化过程缺少完整计算信息工具内部做自动跳过处理。不支持pass间的自动对比校验需人工进行数据对比。不支持程序退出后在任意运行环境构造并模拟计算。需在算子编译期间所对应的主机CPU及进程上构造并模拟计算。不支持基于昇腾AI处理器调用Ascend C构造并模拟计算。不支持基于GPU构造并模拟计算。不支持包含GATHER_IN_UB和GATHER_IN_L1两个operation的校验。如ExpandFunction校验结果出现B200BU报错则该场景仅在InferDynShape后校验结果有效。inplace的op目前只确保pass24及以后的pass校验通过。环境准备最新 master 分支代码及 0.1.1 之后版本不含 0.1.1 版本支持在运行时在线编译精度工具所需 C 二进制不需重新编译安装 PyPTO, 但需确认在线编译所需的构建工具符合以下要求- cmake 3.16.3 - make - g 9.4.0早期PyPTO源码需要重新编译并安装PyPTO后才能使用该工具。确认GCC安装并升级到9.4.0或更高版本。重新通过源码编译安装PyPTO。主要区别是在编译安装命令中增加选项 --no-build-isolation其他操作请参见编译安装。python3 -m pip install . --verbose --no-build-isolation工具使用操作步骤开启精度调试开关。参考样例为hello_world.py。... verify_options { enable_pass_verify: True, pass_verify_save_tensor: True, ... } pypto.frontend.jit(verify_optionsverify_options) def add_kernel( input0: pypto.Tensor((1, 4, 1, 64), pypto.DT_FP32), input1: pypto.Tensor((1, 4, 1, 64), pypto.DT_FP32), out: pypto.Tensor((1, 4, 1, 64), pypto.DT_FP32), ): pypto.set_vec_tile_shapes(1, 4, 1, 64) out[:] input0 input1 ...verify_options 参数说明参数名类型默认值说明enable_pass_verifyboolFalse总体使能开关决定所有pass_verify_*选项和接口是否生效。必须设置为True才能使其他参数生效pass_verify_save_tensorboolFalse是否将模拟计算数据存盘。设置为True时会在{work_path}/output/output_*/目录下生成verify_*目录pass_verify_save_tensor_dirstr{RUNNING_DIR}/output/output_{TS}检测结果及数据的保存路径。可指定绝对路径pass_verify_pass_filterList[str]空配置待自检的Pass名称列表。不指定则默认校验特定pass指定all则校验所有pass指定[]不校验pass只校验tensor_graphpass_verify_error_tolList[float][1e-3, 1e-3]精度对比的容差配置。第一个值为相对误差容差rtol第二个值为绝对误差容差atol设置 golden 数据可选如果需要进行tensor_graph验证需要设置 golden 数据... def test_add(): shape (1, 16, 1, 64) input_data0 torch.rand(shape, dtypetorch.float) input_data1 torch.rand(shape, dtypetorch.float) torch_add torch.add(input_data0, input_data1) # 设置golden数据 pypto.set_verify_golden_data(goldens[None, None, torch_add]) input_data0 input_data0.to(npu) input_data1 input_data1.to(npu) out torch.empty(shape, dtypetorch.float, devicenpu) add(input_data0, input_data1, out) ...set_verify_golden_data 接口说明函数原型set_verify_golden_data(in_out_tensorsNone, goldensNone)参数说明参数名类型说明in_out_tensorsList[Union(pypto.Tensor, torch.Tensor)]将用户可选执行算子时实际的输入、输出列表按照相同位置对应地设置到检测工具。jit 调用模式下该选项不需设置goldensList[Union(pypto.Tensor, torch.Tensor)]将用户已有的计算基准数据golden输出设置到工具中做对比检测。该列表与算子输入、输出参数列表的长度一致、位置对应。若相应位置设置为 None表示跳过该位置的数据对比。注意torch.Tensor 的 device 属性需为 CPU不支持 NPU约束说明该函数需设置pypto.set_verify_options(enable_pass_verifyTrue)后生效执行修改后用例。python3 examples/00_hello_world/hello_world.py打印类似以下输出指示对应的自检结果为通过PASS、未通过FAIL(ED)或跳过校验NO_COMPARE2025-mm-dd HH:MM:SS:xxx V | tensor_graph Verify for 3 data view list index 0 result NO_COMPARE 2025-mm-dd HH:MM:SS:xxx V | tensor_graph Verify for 3 data view list index 1 result NO_COMPARE 2025-mm-dd HH:MM:SS:xxx V | tensor_graph Verify for 3 data view list index 2 result PASS 2025-mm-dd HH:MM:SS:xxx V | function_TENSOR_loop_0_Unroll1_PATH0_hiddenfunc0_8.pass_00_RemoveRedundantReshape Verify result PASS 2025-mm-dd HH:MM:SS:xxx V | function_TENSOR_loop_0_Unroll1_PATH0_hiddenfunc0_8.pass_01_AutoCast Verify result PASS 2025-mm-dd HH:MM:SS:xxx V | function_TENSOR_loop_0_Unroll1_PATH0_hiddenfunc0_8.pass_02_InferMemoryConflict Verify result PASS ... 2025-mm-dd HH:MM:SS:xxx V | function_TENSOR_loop_0_Unroll1_PATH0_hiddenfunc0_8.pass_34_InsertSync Verify result PASS 2025-mm-dd HH:MM:SS:xxx V | function_TENSOR_loop_0_Unroll1_PATH0_hiddenfunc0_8.pass_35_MixSubgraphSplit Verify result PASS 2025-mm-dd HH:MM:SS:xxx V | function_TENSOR_loop_0_Unroll1_PATH0_hiddenfunc0_8.pass_36_CodegenPreproc Verify result PASS执行结束后在${work_path}/output/output_*/目录*代表时间戳下生成verify_*目录存放检测结果文件与日志。├── tensor_graph # 保存前端初始计算图模拟计算后的中间数据作为基础数据 │ ├── *.data │ └── ... ├── verify_graph_data_metainfo.csv # 结果报告保存中间数据元信息及对应数据文件名 ├── verify_graph_result_brief.csv # 精度比对摘要PASS/FAIL/NO_COMPARE、误差统计等 ├── verify_graph_result_brief.log # 精度比对异常详情失败项、异常路径、错误明细 ├── interpreter.log # interpreter 模块拆分日志默认记录 ERROR / EVENT ├── Pass_{PASS_SEQ}_{PASS_NAME} # 保存中间pass计算图模拟计算后的中间数据作为待测数据 │ ├── *.data │ └── ...其中verify_graph_result_brief.log和interpreter.log位于同一个verify_*目录下verify_graph_result_brief.log偏向校验结果摘要与异常明细对比失败、异常路径。interpreter.log偏向 interpreter 执行过程中的拆分日志当前默认仅 ERROR/EVENT 落盘。后续处理建议。对于tensor_graph校验结果中标记FAIL的情况建议多方评审检查PyPTO前端代码的正确性。在前端代码无明显异常的前提下可使用pass_verify_print和pass_verify_save保存/打印中间结果进行进一步分析详见步骤7。对于tensor_graph校验结果通过Pass阶段校验结果中标记FAIL的情况建议建议收集相关结果信息并提交ISSUE进行处理。使用pass_verify_print和pass_verify_save分析中间结果可选。使用场景当Tensor Graph校验失败时可使用这两个接口打印、保存模拟计算的中间数据对比数据找出潜在出问题的计算操作。重要说明pass_verify_print和pass_verify_save保存的是tensor graph 验证阶段模拟计算的结果这些结果是在主机 CPU 上通过模拟执行计算图得到的与实际在 NPU 上板执行的结果可能存在差异主要用于算法逻辑验证使用示例pypto.frontend.jit(verify_optionsverify_options) def add_kernel( input0: pypto.Tensor((1, 4, 1, 64), pypto.DT_FP32), input1: pypto.Tensor((1, 4, 1, 64), pypto.DT_FP32), out: pypto.Tensor((1, 4, 1, 64), pypto.DT_FP32), ): pypto.set_vec_tile_shapes(1, 4, 1, 64) # 保存中间结果到文件 pypto.pass_verify_save(input1, input1_by_pass_verify) # 打印中间结果到控制台 pypto.pass_verify_print(input0) out[:] input0 input1 def add(input_data0, input_data1, out): add_kernel(input_data0, input_data1, out) def test_add(): shape (1, 4, 1, 64) input_data0 torch.rand(shape, dtypetorch.float, devicenpu) input_data1 torch.rand(shape, dtypetorch.float, devicenpu) out torch.empty(shape, dtypetorch.float, devicenpu) add(input_data0, input_data1, out) ...执行修改后用例python3 examples/00_hello_world/hello_world.py控制台输出示例input0:64x64xFP16/64x64xFP16 [[0.03955 0.6094 0.1519 ... 0.7339 0.8789 0.8662] [0.6284 0.01465 0.6333 ... 0.2422 0.03516 0.8423] [0.231 0.02686 0.6055 ... 0.7466 0.2529 0.2231] ... [0.3477 0.4243 0.05273 ... 0.9287 0.1138 0.5083] [0.05273 0.9941 0.4985 ... 0.8345 0.8613 0.188] [0.3184 0.8047 0.833 ... 0.7734 0.2578 0.1392]]生成的文件结构执行结束后在{work_path}/output/output_*/目录*代表时间戳下生成tensor/目录├── tensor/ │ ├── input1_by_pass_verify.data # 保存的指定模拟计算数据格式为Tensor数据的直接内存转储 │ ├── input1_by_pass_verify.csv # 模拟计算数据的元数据包括数据类型、shape信息后续数据处理建议根据元数据信息使用常用的torch.from_file()、numpy.load()等接口打开数据文件并转换为可解析的数值再进一步进行通常开发者使用的数据分析方法例如检查异常数据的偏移规律、异常数据的值特征inf/nan/zero 等。上板执行tensor dump1. 功能概述支持在上板执行时dump leaf function的输入输出数据用于精度问题定位支持和模拟计算结果对比分析。2. 启用方式import os # 设置环境变量启用上板dump, 或者执行前单独设置环境变量export PTO_DATADUMP_ENABLEtrue os.environ[PTO_DATADUMP_ENABLE] true # 配置验证选项 pypto.frontend.jit( runtime_options{run_mode: pypto.RunMode.NPU}, verify_options{ enable_pass_verify: True, pass_verify_save_tensor: True } ) def kernel(...): ...3. Dump 数据输出路径output/output_*/dump_tensor_*/device_{deviceId}/ └── {taskId}_{seqNo}_{callopMagic}_{rootHash}_{funcHash}_{rawMagic}_{timeStamp}_{dataType}_{input/output}{index}.tdump4. 数据处理工具工具位置tools/verifier/parse_dump_tensors.py主要功能解析 dump 的二进制数据.tdump 文件提取 tensor 数据为 .data 文件自动合并分片 tensor 为完整的 raw tensor针对多个 task 处理同一 raw tensor 的场景支持 codegen pass tensor 对比验证需配合enable_pass_verify使用使用方法# 基本用法未使能enable_pass_verify 不进行验证 python3 tools/verifier/parse_dump_tensors.py \ --dump_tensor_path output/output_20260101120000/dump_tensor_20260101120000/device_0 # 带验证的用法需先开启 enable_pass_verify 并运行算子 python3 tools/verifier/parse_dump_tensors.py \ --dump_tensor_path output/output_20260101120000/dump_tensor_20260101120000/device_0 \ --verify_path output/output_20260101120000/verify_20260101120000参数说明参数必需/可选说明默认值--dump_tensor_path必需dump 数据目录路径指向device_x目录无--verify_path可选verify 结果目录路径包含 verify_graph_data_metainfo.csv不对比验证输出文件output/output_*/dump_tensor_*/device_0/ ├── *.data # 提取的 tensor 数据文件 ├── raw_{rawMagic}_{dataType}_{ioflag}.data # 合并后的 raw tensor如有分片 └── ../ # 上级目录生成对比结果报告 └── verify_task_result_cmp~{timestamp}.csv # 对比验证结果报告verify_task_result_cmp~{timestamp}.csv 字段说明字段前缀说明B前缀表示上板 dump 的原始数据A前缀表示验证数据来自 pass verifyAB前缀表示对比验证结果基础信息字段字段说明BtaskId任务 IDROOT_CALL:opmagic算子调用 magic 标识ROOT_CALL:rawmagic原始 tensor magic 标识Bvalidshapetensor 实际 shapeBoffsettensor 在 raw tensor 中的偏移BrawShape原始完整 tensor 的 shapeBtensorAddrtensor 内存地址Bdatatype数据类型字符串如 FP32、INT8IO_FLAG输入/输出标记input/outputBseqNo序列号BTIMESTAMP时间戳BfuncIdFunction IDROOT_FUNC:hashRoot Function hash 值FUNC:hashFunction hash 值验证对比字段启用 --verify_path 时字段说明APHASE_NAME验证数据的阶段名称如 Pass_36_CodegenPreprocAFILENAME验证数据文件路径Adatatype验证数据的数据类型Avalidshape验证数据的 shapeABRESULT对比结果PASS、FAIL、NO_CMPerror_count误差元素数量对比失败时error_rate误差元素占比对比失败时max_abs_error最大绝对误差对比失败时max_rel_error最大相对误差对比失败时mean_abs_error平均绝对误差对比失败时mean_rel_error平均相对误差对比失败时result_reason未对比原因NO_CMP 时如 unsupported dtype: BOTTOM对比验证流程数据匹配通过ROOT_CALL:opmagic、ROOT_CALL:rawmagic、IO_FLAG、Boffset匹配上板数据与验证数据容差配置根据数据类型自动选择容差FP32/FP64标准容差rtol1e-3, atol1e-3FP16/BF16/FP8放宽容差rtol1e-2, atol1e-2Shape 处理自动处理 shape 不一致的对比取公共部分不支持类型HF4、HF8、BOTTOM 等类型标记为 NO_CMPRaw Tensor 合并说明当多个 task 处理同一个 raw tensor 的不同分片时脚本会自动按ROOT_CALL:rawmagic分组根据Boffset和Bvalidshape计算切片位置合并所有分片数据到完整 raw tensor生成的文件命名为raw_{rawMagic}_{dataType}_{ioflag}.data算子级别的输入输出tensor dump1. 功能概述支持整网中算子级别的输入输出上板dump的能力。2. 启用方式在脚本运行目录下创建 acl.json 文件内容如下{ dump:{ dump_path:/your/path, dump_mode:all, dump_debug:off, dump_op_switch:on } }在要执行的用例 test.py 中添加如下配置import torch import torch_npu torch.npu.init_dump() torch.npu.set_dump(acl.json)3. Dump 数据输出路径数据输出路径就是 acl.json 里面配置的 dump_path在该路径下会生成如下文件/your/path └── 20260415084134/0 └── TENSOR_batchmatmul_3d_kernel.TENSOR_batchmatmul_3d_kernel.29.46.1776242496294291调用 CANN 已有的工具解析该文件命令如下python3 /${CANN_PACKAGE_PATH}/Ascend/cann-9.0.0/tools/operator_cmp/compare/msaccucmp.py convert -d /your/path/20260415084134/0 -out /your/path/20260415084134/0/out解析后生成如下 npy 文件/your/path └── 20260415084134/0 ├── out/ │ ├── TENSOR_batchmatmul_3d_kernel.TENSOR_batchmatmul_3d_kernel.29.46.1776242496294291.input.0.npy │ ├── TENSOR_batchmatmul_3d_kernel.TENSOR_batchmatmul_3d_kernel.29.46.1776242496294291.input.1.npy │ └── TENSOR_batchmatmul_3d_kernel.TENSOR_batchmatmul_3d_kernel.29.46.1776242496294291.input.2.npy └── TENSOR_batchmatmul_3d_kernel.TENSOR_batchmatmul_3d_kernel.29.46.1776242496294291【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考