PyPTO Pass 错误分析报告:从日志定位到根因链的标准编写方法
PyPTO Pass 错误分析报告:从日志定位到根因链的标准编写方法
导读
本文面向需要在 CANN/PyPTO 编译框架中排查 Pass(编译优化与变换阶段)异常的开发者与 AI Agent,系统讲解"PyPTO Pass 问题分析报告"的标准结构与编写方法。文章以仓库内的报告模板为骨架,结合Pass 异常分析流程指导、IR 分析指导以及框架源码,完整呈现一份合格报告所必需的六个章节、日志解析规则、异常分类口径与"现象 → 触发位置 → 状态异常 → 违反规则"根因链的构建方法。读完本文,你将能够按照统一格式产出事实准确、证据可查、修复建议可执行的 Pass 错误分析报告。
一、报告模板的定位与整体结构
1.1 模板解决什么问题
PyPTO 的 Pass 模块在编译流水线中负责计算图的各类变换(图切分、内存类型分配、Buffer 合并、调度等),异常往往表现为编译中断、图结构损坏、内存越界或段错误。由于涉及日志、计算图 JSON、IR 文件与源码四处证据,排查结果若缺乏统一格式,很容易出现"结论不可复现、证据链断裂、修复建议泛化"的问题。
PyPTO Pass 问题分析报告模板正是为此设计的标准输出格式,它把一次完整的错误定位过程收敛为六个章节:
- 基本信息——问题的复现入口与环境快照;
- 错误位置——错误在源码与 Pass 流水线中的精确坐标;
- 错误信息——原始日志、核心解析与关联上下文;
- 错误原因分析——异常分类、多类证据与根因链;
- 修复建议——可执行的修复方案与验证方式;
- 附录——全部证据文件的清单。
从源码看,这一模板与 Pass 框架的执行模型严格对应:在 pass.cpp 中,每个 Pass 依次执行 PreRun → RunOnFunction → PostRun,任一步骤返回 FAILED 都会导致编译中断,这也解释了模板中"错误位置""错误信息""根因链"为何都要以"源码文件 + 行号 + Pass 模块 + 触发条件"为核心要素。
1.2 合格报告的最低标准
结合技能定义(SKILL.md)中的输出成功标准,一份合格的报告必须同时满足:
- 包含基本信息、错误位置、错误信息、原因分析、修复建议五个必要部分(模板共六章);
- 代码位置精确到文件与行号;
- 修复建议具体、可执行,而非泛化描述;
- 错误原因分析基于日志与源码证据;
- 根因链完整:现象 → 触发位置 → 状态异常 → 违反规则。
下文按模板章节逐一讲解每一部分的填写方法与背后依据。
二、第一章:基本信息——锁定复现环境
基本信息是整份报告的"案发现场快照",必须能让任何人按原样复现。模板要求的字段及填写要点如下:
| 字段 | 填写要点 |
|---|---|
| 问题标题 | 一句话概述问题,例如"NBufferMerge Pass 在处理 hashOrder 为 0 的图时因非法 VEC_NBUFFER_SETTING 键值中断" |
| 错误级别 | ERROR / WARN / INFO 三选一,取自日志级别 |
| 复现命令 | 用户提供的完整执行命令,例如 python3 build_ci.py -c -f=cpp -u=NBufferMergeTest.TestMode4 |
| 用户代码路径 | 相关脚本或测试用例路径 |
| 环境信息 | PyPTO 版本、Python 版本、NPU 型号、关键环境变量 |
| 是否开启调试模式 | 是/否,并注明 debug_options 配置 |
2.1 调试模式的开启方式(python 脚本场景)
如果用户执行的是 Python 脚本,需要在复现前开启图编译阶段调试模式。开启后,编译时会默认在 $(pwd)/output 目录下输出各 Pass 模块执行前后的**计算图(JSON)**与 IR(.tifwkgr) 文件:
@pypto.frontend.jit(
debug_options={"compile_debug_mode": 1, "runtime_debug_mode": 1}
)
2.2 日志相关环境变量
复现前还需设置日志输出目录与级别环境变量:
export ASCEND_PROCESS_LOG_PATH=$(pwd)/logs/$(date +%Y%m%d%H%M%S)
export ASCEND_GLOBAL_LOG_LEVEL=0
重要:设置环境变量与执行复现命令必须在同一个会话中完成,否则环境变量不会生效,这也是"环境信息"字段必须记录关键环境变量的原因。
三、第二章:错误位置——精确到文件行号的坐标定位
模板要求错误位置包含五个要素:
- 源码文件:打印错误日志或抛出异常的 C++ 源文件路径;
- 代码行号:精确行号(例如
n_buffer_merge.cpp:530); - Pass 模块:错误所属 Pass 名称(注意:日志中的模块信息不一定是 Pass 名,也可能是被 Pass 调用的工具模块,需结合上下文判断);
- 相关函数/接口:函数名或入口,如
RunOnFunction; - 定位依据:日志中的
文件:行号、触发条件、关键分支变量、返回码。
3.1 定位依据从哪来
错误位置的证据来源按优先级排列:
- 日志中的
[文件:行号]标记——这是最直接的定位依据; - 计算图 JSON 中 Operation 的
file与line字段——用 computation_graph_analyzer.py 查询后可直接回看用户代码位置; - IR 文件中的注释——
/* /path/to/xxx.py:20 */形式的注释标记了原始 Python 代码行号,用于 IR 与源代码的对应。
3.2 源码上下文抓取
拿到行号后,用 sed 抓取上下文进行代码级分析:
sed -n '<line-20>,<line+20>p' <source_file>
注意区分两种"行号":日志 [n_buffer_merge.cpp:530] 是打印日志代码的行号;计算图 Operation 的 file/line 是用户 Python 代码映射的行号。报告中应分别标注,避免混淆。
四、第三章:错误信息——日志的三层拆解
4.1 原始错误日志:完整保留
3.1 原始错误日志 要求保留完整错误文本,不做删减。以技能文档中给出的 pass 模块日志为例:
[ERROR] PYPTO(638465):2026-03-16 10:02:24.711 [n_buffer_merge.cpp:530][PASS]:[NBufferMerge.Config]:The VEC_NBUFFER_SETTING key -3 is incorrect; Please set keys of VEC_NBUFFER_SETTING between -1 and max hashOrder 0.
4.2 核心解析:七个字段逐项拆解
3.2 核心解析 要求把一条日志按字段拆解,模板列出的字段对应关系如下:
| 字段 | 日志中的取值 | 说明 |
|---|---|---|
| 日志级别 | [ERROR] |
ERROR/WARN/INFO |
| 进程 | PYPTO(638465) |
模块名及进程 ID |
| 时间 | 2026-03-16 10:02:24.711 |
日志打印时间 |
| 文件及行号 | [n_buffer_merge.cpp:530] |
打印日志代码所在文件与行号 |
| 所属模块类型 | [PASS] |
标明日志来自 Pass 框架 |
| 具体模块信息 | [NBufferMerge.Config] |
可能是 Pass 模块名,也可能是被 Pass 调用的工具模块,需结合上下文判断 |
| 错误内容 | The VEC_NBUFFER_SETTING key -3 is incorrect; ... |
提取后的核心报错信息 |
从源码可以验证该日志的真实性:n_buffer_merge.cpp 中维护了 hashOrder_[hashColor[i]] 映射,将 hash 颜色映射为合并顺序,VEC_NBUFFER_SETTING 的合法取值区间正是 [-1, max hashOrder]。这印证了"核心解析"中"模块信息不一定是 Pass 名"的提示——NBufferMerge.Config 描述的是该 Pass 内的配置检查阶段。
4.3 关联日志与上下文:不要只贴一行
3.3 关联日志/上下文 要求收集多行上下文,包括:
- 错误前后的
[WARN]日志(往往是根因的前置信号); - 相邻 Pass 的日志(用于判断异常是当前 Pass 引入还是上游遗留);
- 完整的错误堆栈(段错误、崩溃场景必须保留
bt full输出); - 跨越多行的错误信息需合并提取,避免截断丢失关键字段。
日志级别处理口径:[ERROR] 是必须处理的关键错误;[WARN] 是可能导致问题的警告,需结合上下文判断是否与本次异常相关;[INFO] 仅作辅助调试信息。
五、第四章:错误原因分析——构建证据链与根因链
这是整份报告的核心章节,模板将其拆分为异常分类、证据分析、根因链、特殊说明四部分。
5.1 异常分类:七类常见异常与日志特征
模板 4.1 给出了异常类型枚举(参数配置异常/算子约束违反/段错误/属性缺失/计算图成环/索引越界/其他),技能文档进一步补充了各类异常的典型日志特征,整理如下:
| 异常类型 | 日志特征 | 关键信息提取 |
|---|---|---|
| 参数配置异常 | vec_nbuffer_setting、cube_l1_reuse_setting、cube_nbuffer_setting、sg_set_scope |
异常参数名、参数配置值 |
| 算子约束违反 | constraint violated、invalid parameter |
opcode 类型、op_magic 信息 |
| 段错误 | segment fault、Segmentation fault (core dumped)、SIGSEGV、退出码 139 |
调用堆栈信息、空指针变量 |
| 属性缺失 | attribute not found、missing attribute、required attribute、get attribute failed、HasAttr(...) == false |
属性名称、算子名称、期望属性类型 |
| 计算图成环 | cycle detected、graph cycle、topological sort failed、circular dependency |
成环节点、循环路径、依赖关系 |
| 索引越界 | index out of range、invalid index |
索引值、范围、张量形状 |
| 内存越界 | Alloc tensor .* size .* exceeds .* size、MEM_UB、MEM_L1、MEM_L0A、MEM_L0B、MEM_L0C |
超限 tensor、内存层级、hardware_limit |
分类依据必须写清"对应日志特征、关键字段、代码行为",不能仅凭直觉下结论。
5.2 证据分析:四类证据缺一不可
模板 4.2 要求同时组织四类证据:
(1)日志证据:引用日志片段并附加说明,说明该片段揭示了什么状态。
(2)源码证据:给出文件路径、行号范围、触发条件、关键分支变量、返回码,并附关键源码片段:
// 示例:异常返回前的图状态落盘插桩(来自异常前补打计算图流程)
function.DumpJsonFile("./config/pass/json/pass_x_pre_topology_check.json");
auto ret = OperationLoopCheck(function);
if (ret != SUCCESS) {
GELOGE(INTERNAL_ERROR, "loop check failed");
return ret;
}
(3)计算图/IR 证据:给出 Before 图/After 图路径,描述图结构变化、IR 异常、After 缺失等状态。可借助仓库提供的 computation_graph_analyzer.py 对图 JSON 执行节点查询与成环检测:
python3 .agents/skills/pypto-pass-error-locator/scripts/computation_graph_analyzer.py \
--json-path <graph_json_path> \
--op-magic <op_magic>
(4)规则/约束证据:引用参考文档与违反的规则条目。参数类问题查 pypto-set_pass_options.md,算子类问题查 operation 文档目录。
5.3 根因链:现象 → 触发位置 → 状态异常 → 违反规则
模板 4.3 明确根因链为必需环节,且四个节点必须逐一对应:
- 现象(日志):看到的外部报错/中断现象,引用真实日志文本;
- 触发位置(源码切片):具体文件、行号、函数、代码片段;
- 状态异常(计算图/IR 变化):Before/After 差异、属性缺失、图结构异常;
- 违反规则(约束文档):具体规则、约束条目、接口要求。
以"计算图成环"场景为例,标准根因链输出格式为:
现象(某 pass 报 cycle) -> 图证据(某 JSON 中的 op/subgraph 环路) -> 首次引入位置(某上游 pass) -> 触发源码(某文件某行的依赖修改逻辑)
5.3.1 成环场景的关键辨析
成环是错误定位中最容易误判的类型,报告必须区分三个概念:
- 报错 pass:第一个抛出成环异常的 pass;
- 根因候选 pass:首次引入环的 pass——报错 pass 不一定是根因 pass,某些 pass 只是首次执行拓扑检查/排序而最先暴露问题,环可能由更早的 pass 引入;
- 根因未定:图文件不完整或隐式依赖无法从 JSON 还原时的结论,此时只能给出"根因候选",不得伪造成确定结论。
回溯方法:对当前报错 pass 的输入图、上一个 pass 的输出图逐级执行 --detect-op-cycle 与 --detect-subgraph-cycle,找到"前一阶段无环、当前阶段有环"的边界 pass:
python3 .agents/skills/pypto-pass-error-locator/scripts/computation_graph_analyzer.py \
--json-path <curr_graph> --detect-op-cycle
python3 .agents/skills/pypto-pass-error-locator/scripts/computation_graph_analyzer.py \
--json-path <prev_graph> --detect-op-cycle
脚本还支持前后图对比模式:--before-json <prev> --after-json <curr> --compare-cycle,可自动给出"环首次出现在 after 图"或"环在 before 图已存在"的根因提示。
需要特别说明的是能力边界:脚本的成环检测基于显式 tensor 数据流(ioperands/ooperands),而 JSON 未直接导出 dependOperand。若日志来自拓扑排序或调度阶段,可能存在 JSON 未表达的隐式依赖,必须回到源码侧确认——报告结论中应如实标注这一边界。
5.4 特殊说明:初始无异常日志的场景
模板 4.4 覆盖了最棘手的场景——pass 中断但无任何异常日志。此时报告需按三步补充证据:
- 首次外显现象:pass 中断且
After图缺失。注意:"缺失 After 文件"更常见的含义是"图已被部分修改,但尚未来得及统一落盘",不能直接当作"pass 未修改图"。 - 补充诊断手段:在最后中断的 pass 模块中增加异常捕获代码(覆盖
catch (const std::exception& e)打印e.what()、catch (...)打印 unknown exception),必要时在关键步骤前后增加临时日志缩小中断位置;随后重新编译安装并复现。 - 最终异常证据:补充捕获后新增的错误码、错误文本、源码行号。
5.4.1 为何 After 图会缺失:Before/After 落盘机制
从源码可以确认 Before/After 图的落盘时机:pass.cpp 在 PreRun 阶段(执行 RunOnFunction 之前)统一调用 DumpFunctionJson(function, passFolder_, true) 生成 Before 图;而 After 图在 PostRun 阶段才统一落盘(pass.cpp)。RunOnFunction 一旦中途异常,PostRun 不会执行,因此只有 Before 图而没有 After 图。这正是模板要求"若 After 图未成功打印,不得直接基于 Before 图下结论"的原因。
5.4.2 异常前补打计算图
针对 After 缺失,需在异常前最近位置插入临时 DumpJsonFile 代码(优先对当前正被 pass 修改的 Function 对象调用):
function.DumpJsonFile("/tmp/pass_debug/<pass_name>_before_abort.json");
// 或持有指针时:
currFunctionPtr->DumpJsonFile("./config/pass/json/<pass_name>_before_abort.json");
插桩点选择优先级:异常日志对应代码行之前最近一次图结构修改完成处 > 即将执行拓扑/成环/属性校验的调用前 > return FAILED、CHECK、throw、PYPTO_ASSERT 之前。插桩文件命名需包含 pass 名称与阶段语义(如 cycle_detect_before_abort.json、pass_x_pre_topology_check.json),且父目录必须真实存在,否则 Function::DumpJsonFile 打开文件会失败。
插桩后重新编译安装(常规命令 python3 build_ci.py --clean --no_isolation && bash build_out/cann-pypto_*.run --full -q --pylocal),在相同日志环境变量下重跑复现脚本,拿到"中断前最后一版图"后再继续分析,并在最终结论中明确标注该图来源于临时异常前 dump,不得误写成框架自动导出的标准 After 图。定位完成后须回退临时插桩。
六、第五章:修复建议——从根因到可执行步骤
6.1 修复方案
模板 5.1 要求给出明确、具体、可执行的修复方向。不同异常类型有对应的修复范式:
| 异常类型 | 典型修复方向 |
|---|---|
| 参数配置异常 | 修正用户参数值使其满足约束区间,或修正 Pass 的参数处理逻辑 |
| 算子约束违反 | 修正用户代码以符合算子文档约束,或修正 Pass 的算子映射逻辑 |
| 段错误 | 增加判空保护(if (ptr == nullptr) { return FAILED; }),或修复上游漏传节点的 pass |
| 属性缺失 | 增加 HasAttr 判断与默认值兜底,或在上游重建算子时补齐属性继承/拷贝 |
| 计算图成环 | 修正首次引入环的 pass 中的依赖建立/修改逻辑(如避免复用旧 tensor 串错边) |
| 内存越界 | 调整 tile_shape/dtype,或修复首次生成/放大超限 tensor 的 pass |
6.2 具体步骤
模板 5.2 要求四步递进:
- 步骤 1:修改哪个文件、哪个逻辑(精确到函数与行号);
- 步骤 2:增加什么校验/判空/映射修正(给出具体代码形态);
- 步骤 3:如何重新编译安装与复现验证(给出构建命令与复现命令);
- 步骤 4:如何确认修复生效(预期日志/图/IR 结果)。
6.3 验证方式
模板 5.3 要求写明验证命令与预期结果。例如:修复后重跑复现命令,预期 [ERROR] 日志消失、对应 Pass_xxx 目录下正常生成 After 计算图与 IR 文件,且根因链中"状态异常"环节描述的图差异不再出现。
七、第六章:附录——证据文件清单
附录要求汇总全部证据文件的路径,作为报告的"证据索引":
- 完整日志路径:如
$ASCEND_PROCESS_LOG_PATH/debug/plog/pypto-*.log; - 相关源码文件:如
framework/src/passes/tile_graph_pass/graph_partition/n_buffer_merge.cpp; - 计算图/IR 文件:Before 图路径、After 图路径、IR 路径(形如
output/output_*/Pass_XX_Name/Before_XX_PassName_funcname.json与After_XX_PassName_funcname.tifwkgr); - 相关文档:约束文档路径(如 pypto-set_pass_options.md)。
八、报告产出后的质量校验
报告完成后,按以下三项自检(对应技能文档的校验逻辑):
- 格式校验:是否包含六个必需章节(基本信息、错误位置、错误信息、原因分析、修复建议、附录);
- 证据链校验:根因链是否完整,且各环节有对应证据(日志片段、源码行号、计算图差异、文档约束);
- 可执行性校验:修复建议是否包含具体操作步骤而非泛化描述。
若校验失败,按回退路径处理:格式不完整回退到异常分析环节重新汇总;证据链断裂回退到关键信息获取环节补充缺失的日志或计算图证据;修复建议不可执行回退到异常分类环节重新定位根因并细化修复方案。
九、配套工具链与关键源码索引
为便于实际操作,汇总本文涉及的仓库资源:
| 资源 | 路径 | 用途 |
|---|---|---|
| 报告模板 | pass-error-report-template.md | 报告输出格式 |
| 异常分析流程指导 | pass-error-analysis-guide.md | 六类异常的专项分析流程与 After 缺失补打流程 |
| IR 分析指导 | ir-analysis-guide.md | .tifwkgr 文件结构、IR 元素语法、Before/After 对比方法 |
| 计算图 JSON 分析器 | computation_graph_analyzer.py | 节点查询(--op-magic/--tensor-magic)与成环检测(--detect-op-cycle/--detect-subgraph-cycle/--compare-cycle) |
| OP 信息查询器 | get_op_info.py | 从 IR 中查询指定 OP 的 shape、内存类型、属性(支持 --format json) |
| Pass 执行框架 | pass.cpp | PreRun → RunOnFunction → PostRun 执行模型与 Before/After 落盘时机 |
| Pass 配置 API 文档 | pypto-set_pass_options.md | 参数配置异常场景的约束查询入口 |
结语
一份合格的 PyPTO Pass 错误分析报告,本质上是"日志、源码、计算图、约束文档"四类证据的严格对齐:用日志锁定坐标,用源码确认逻辑,用图变化验证状态,用文档判定违规,最后汇成"现象 → 触发位置 → 状态异常 → 违反规则"的完整根因链。按照本文所述模板与流程编写,既能保证结论可复现、可追溯,也能让修复建议真正落到可执行的代码层面。