写 AI 模型调试的人，应该都有过这种体验：模型在训练或推理设备上跑出来的结果不对，但你在宿主机的日志里翻半天，只能看到一行行张量 shape 和几个让人摸不着头脑的错误码。你根本看不到模型内部长什么样，算子之间的数据是怎么流动的，也不知道某个节点到底有没有被真正执行。这就是典型的"黑盒调试"困境。model-inspector这个项目，解决的就是这个问题——在 CANN 生态里，把模型结构和执行过程变成你能直接“看到”的东西。
CANN 是面向 AI 处理器的异构计算架构，在这套生态里做模型适配和调优，最头疼的就是模型从框架侧到设备侧的转换过程不透明。你在 PyTorch 或 MindSpore 里定义好的网络，经过图编译、算子选型、任务下发这一套流程后，最终在设备上执行的东西跟你写的原始代码已经差得很远了。模型结构、算子映射关系、执行顺序、甚至某个节点是否真的生成了任务，这些信息全靠猜。model-inspector的定位就是给这一整条链路装上一个"透视镜"，让开发者能直观看到模型的计算图结构，看到算子级别的执行流水，看到传输和计算的时间分布。
这篇文章我会从项目要解决的问题讲起，拆解它的核心设计思路、关键技术选型，再带你走一遍完整的接入和实操流程，最后把我在使用过程中踩过的坑和排查经验一并分享出来。无论你是刚开始接触 CANN 的初学者，还是已经在做算子移植和性能优化的老手，这套可视化调试的思路应该都能给你一些直接能用的东西。
1. 项目定位与核心价值：模型调试为什么需要“透视”
1.1 CANN 生态里的调试痛点
先说说我为什么会觉得可视化调试这件事在 CANN 生态里尤其重要。CANN 生态的典型使用路径是这样的：你有一个训练好的模型，通过各种转换工具把它转成设备可执行的格式，然后通过应用层接口加载执行。中间这一大段——图编译、算子融合、任务编排——对开发者来说基本是个黑盒。
我见过太多类似的场景了。某个同学在 MindSpore 上写了一个包含自定义算子的网络，转成离线模型后加载执行，发现精度对不上。他花了一整天去查，最后发现是某个融合规则把两个本不该融合的算子合在了一起，导致中间结果的精度丢了。这种问题，你如果只能看到一个执行日志，根本无从下手。但如果有一个工具能把编译后的计算图展开给你看，哪个算子被融合了、哪个算子被重排了、数据流是怎么走的，一眼就清楚了。
还有一个更常见的痛点：性能问题。模型跑得慢，你想知道瓶颈在哪儿。传输耗时占比高？某个算子执行时间异常？还是任务下发频率太高导致同步开销过大？没有执行过程的透视能力，你只能靠猜，或者用分析工具去看一堆聚合统计，很难定位到具体是哪个环节出了问题。
1.2model-inspector解决什么问题
这个项目的核心目标，用一句话概括就是：把模型从“图”到“执行”的全过程，变成可浏览、可检索、可分析的结构化视图。
它做的事情主要落在这几个层面：
- 解析模型的计算图结构，展示节点、连接关系、张量维度信息；
- 跟踪模型在设备上的实际执行顺序，标注每个任务的启动时间、持续时间；
- 关联图节点与执行任务，让你能回答“这个算子在图上长什么样、它实际对应哪个内核函数、它在流水线上占了多长时间”这类问题；
- 输出结构化的转储文件，既支持在 Web 界面里交互式浏览，也支持用脚本做批量分析和回归对比。
我把它理解成是“模型层面的调试器”。普通调试器让你看变量值、看调用栈，model-inspector让你看算子、看图节点、看执行时间线。两者干的是同一件事：把不确定性变成确定性，把隐藏的信息暴露出来。
1.3 适合谁用
如果你属于下面这几类开发者，这个项目的思路和用法会对你有直接帮助：
- 刚接触 CANN 生态，想搞明白模型从框架侧到设备侧到底经历了什么；
- 在做模型迁移适配，需要验证转换前后结构是否一致、是否有算子被意外替换；
- 在做性能优化，需要精确定位耗时瓶颈在某类算子还是某个传输环节；
- 在开发自定义算子或图编译插件，需要验证自己的改动在图层面产生了什么效果。
即使你暂时不需要完整实现一个这样的工具，读完这篇内容，你对 CANN 生态里“图”和“执行”这两个层面的理解也会清晰很多。而这套“透视”方法论，放到其他 AI 编译栈里同样适用。
2. 技术原理拆解：模型结构与执行过程是怎么被“看穿”的
2.1 模型结构的三个层次
要透视模型，首先得搞清楚“结构”这个词在 CANN 生态里到底指什么。我习惯把它拆成三个层次来看。
第一个层次是框架侧的计算图。这是你在 PyTorch、MindSpore、TensorFlow 里定义网络时构建出来的图，节点是算子，边是张量依赖。这个层次的图最接近你的源代码语义，但不包含任何设备相关的信息。
第二个层次是编译后的中间图。模型经过图编译器的各种优化（算子融合、常量折叠、内存复用、数据布局转换）之后，会生成一个更贴近硬件执行语义的图。这个图里有的节点已经变了，比如原来的几个算子被融合成一个大的融合算子，有的节点被重排了位置，有的算子被替换成了设备上更高效的实现。
第三个层次是任务级执行图。编译器把中间图进一步转换成具体可在设备上执行的任务序列，包含内核函数的启动参数、输入输出张量的内存地址、依赖关系等。这个层次不再是一个直观的“图”，更像是一份执行计划。
model-inspector做透视的关键，就是要把这三个层次打通：从用户看到的框架图，到编译器产生的中间图，再到设备上实际执行的任务序列，中间每一步的映射关系都记录下来。这样你看到一个中间图节点时，可以反查到它对应框架图中的哪个算子；看到一个执行任务时，可以知道它是为哪个图节点服务的。
2.2 执行过程的关键观测点
有了结构，接下来要解决的是“过程”的透视。模型在设备上执行时，有价值的信息不只是“哪些算子跑了”，还包括“它们怎么跑的”。这里有几个关键观测点。
第一个是任务下发顺序和依赖关系。AI 处理器的执行模型通常是流（stream）加事件（event）的异步模型。多个任务可以在不同的流上并行执行，流之间通过事件同步。如果不把这一层信息可视化，你就很难理解为什么模型的总耗时不是所有算子耗时的简单相加。
第二个是数据搬运与计算的时间分布。在异构架构里，数据在主机内存、设备内存之间搬运的时间和设备上算子执行的时间是两条并行的线。很多性能问题的根源是数据搬运没有和计算重叠，导致设备在空等。执行过程透视如果不区分这两类时间，那你看到的耗时数据就是一团浆糊。
第三个是算子实际执行的内核信息，比如内核名称、工作负载的配置参数这些细节。它们能帮你判断某个算子到底走的是哪个实现分支，是否有回退到了低效的实现路径。
2.3 可视化数据的组织方式
把上述信息采集回来之后，怎么组织才能让使用者高效浏览？这是model-inspector在设计上花心思最多的地方。
我的经验是，可视化调试工具最忌讳的是把所有信息平铺给用户。所以这个项目采用了“多视图联动”的组织方式：
- 结构视图：展示图节点和连接关系，支持按算子类型着色、按融合组折叠、按节点名检索；
- 时间线视图：展示任务在设备上的执行时间，支持按流分组、按算子类型筛选、缩放定位；
- 映射关系视图：展示框架算子、中间节点、执行任务三者之间的对应关系，支持点击跳转。
三个视图共享同一份底层数据，你在结构视图里选中某个节点，时间线视图会自动高亮这个节点对应的执行任务。这种“点一下就关联上看”的交互方式，比单独看一张静态图高效得多。
3. 项目实现路径与关键技术选型
3.1 整体架构设计
model-inspector的实现思路可以概括成“采集-解析-关联-呈现”四层链路。
采集层负责从 CANN 生态的各个接口拿到原始数据，包括图结构数据、任务执行数据和性能计数器数据。解析层把这些数据统一转换成内部定义的中间格式。关联层打通三个层次之间的映射关系。呈现层提供命令行文本输出和 Web 可视化两种方式。
这个分层设计我认为很关键，尤其是采集层和数据模型层之间的解耦。CANN 生态本身在快速演进，不同版本的图编译接口、执行接口会有差异。如果解析和关联逻辑直接依赖某一个版本的接口，那每次版本升级都要改一大片代码。把它们隔离开之后，换一个版本的采集实现，上层的数据模型和可视化逻辑几乎不用动。
3.2 关键数据结构的设计
如果把项目比作一个建筑，那内部的数据模型就是承重墙。这里我给你看一下核心数据结构的大致设计思路，不算完整代码，但能让你理解它是怎么把三张“网”织成一张的。
我设计了一个统一的“节点描述”（NodeDesc）结构来承载图节点信息。它不关心图是来自框架侧还是中间侧，而是通过一个“图层级”字段来区分。一个节点可能同时存在于框架图和中间图中，这时它们共享同一个节点标识，只是挂在不同层级下。
@dataclass class NodeDesc: node_id: str # 全局唯一标识 layer_level: str # "framework" 或 "compiled" op_type: str # 算子类型 name: str # 节点名称 shape: tuple # 输出张量形状 fused_from: list # 若为融合节点，记录被融合的子节点 mapped_task_ids: list # 对应执行层的任务标识执行任务的结构则独立成另一份数据，承载设备侧的时间信息：
@dataclass class TaskDesc: task_id: str # 任务标识 op_node_id: str # 关联的图节点 stream_id: int # 所在流 event_before: str # 前置事件 event_after: str # 后置事件 kernel_name: str # 内核函数名称 start_us: int # 启动时间（微秒） duration_us: int # 执行时长（微秒）这样设计的好处是，图结构和执行过程被分开了，但通过op_node_id和mapped_task_ids互相引用。渲染的时候，无论从哪个视图切入，都能通过索引快速找到关联对象。
3.3 数据采集的两种方案
采集层是全项目里最依赖生态接口的部分，也是我建议你重点关注的地方。拿到模型结构和执行过程信息，在 CANN 生态里有两种方案。
第一种方案是基于图编译接口的静态采集。在图编译完成之后、模型加载执行之前，通过注册回调接口拿到编译后的图描述信息。这种方案的优点是信息完整，能拿到完整的图结构，包括每个节点的属性、张量形状、融合信息。缺点是需要侵入编译流程，无法直接对已有的离线模型做分析，而且某些执行期的动态信息（比如实际内核启动参数）拿不到。
第二种方案是基于运行时分析接口的动态采集。模型实际执行时，通过运行时提供的剖析能力拿到任务级的执行信息，配合日志里的任务依赖关系做重建。这种方案能看到真实执行情况，但拿不到完整的图结构，因为执行过程中的任务序列已经经过了高度编排。
model-inspector的实际做法是把两种方案结合起来：静态采集用于构建结构视图的底图，动态采集用于构建时间线视图和执行任务列表。两者的桥接点就是算子级映射关系——编译器在你把图节点下发成任务时，记录下这个节点的标识。有了这个标识，结构视图和时间线视图就能对齐了。
3.4 呈现层的技术选型考虑
呈现层我尝试过几种方案，简单说说选型中的取舍。
第一版我用的是命令行文本输出，就是把节点列表、任务列表按层级缩进打印出来，再加上每类算子的耗时统计。这个方案胜在轻量，任何环境都能跑，适合做自动化检查和脚本回归。但说实话，一个结构复杂的模型有上千个节点，纯文本看下来眼睛很难受，节点之间的依赖关系也无法直观表达。
第二版我用过静态图片渲染的方案，就是让工具生成一张完整的大图。这个方案对于节点数量在几十个的小模型来说很直观，但模型大一点之后，图片会变成一个密密麻麻的蜘蛛网，根本没法用。
最终落地的是基于 Web 的交互式方案。前端画布支持缩放和平移，可以按算子类型做颜色映射，支持点击节点查看详情，还支持跨视图联动。数据量再大，也可以通过按算子类型筛选、按融合组折叠来解决。唯一的缺点是环境里需要一个浏览器窗口。所以我把文本输出也保留了，两套呈现方案互不替代。
4. 实操过程实录：让一个真实模型“现形”
4.1 准备环境与最小接入流程
下面进入实操环节。我假设你手里已经有一套可运行的 CANN 环境，并且有一个已经能正常加载执行的模型文件。这个工具不要求在训练环境里装额外的东西，它只需要在模型加载执行的入口做一点接入动作。
整个接入流程分成四步，每一步的意图我都会说清楚。
第一步是初始化采集器。在应用启动、加载模型之前，先创建采集器实例，并指定采集结果的输出路径。这个路径会用来存放后续生成的中间转储文件。
inspector-cli start --output-dir /tmp/inspector_logs --enable-graph --enable-runtime--enable-graph表示采集图结构信息，--enable-runtime表示采集运行时执行信息。这两个开关是独立的，你可以根据场景只开启其中一个。
第二步是在模型编译完成的回调点注入一次“快照采集”。这一步是让采集器把当前编译后的图结构抓取下来，存成中间文件。不同的框架侧接入方式会稍有差异，但核心都是在模型编译方法调用返回之后、实例化执行会话之前。
第三步是在模型执行结束后再采集一次运行时信息。这步采集的是实际执行阶段的任务数据。对于推理模型，你可以在一个 batch 的执行调用返回后立刻触发。对于训练模型，建议在某个 step 结束后触发。
第四步是调用汇总导出接口，让采集器把原始数据转换成规范化的转储文件，并输出一份摘要报告。
inspector-cli export --input-dir /tmp/inspector_logs --format json执行完这四条命令，你会在输出目录里看到graph.json、trace.json、summary.json三个文件。前两个分别是结构数据和执行数据，第三个是自动生成的统计摘要，后面单独聊怎么读它。
4.2 从文本摘要开始读数据
对于第一次接触这个工具的开发者，我建议先从文本摘要读起，不要一上来就开 Web 界面。摘要文件里已经按算子类型聚合了最核心的统计信息，能让你快速建立对模型执行概况的认知。
我拿一个模拟场景举例，假设你测的是一个包含卷积、归一化、激活、全连接和自定义算子的分类网络，设备执行完一个 batch 之后，摘要里会有一张按算子类型分组的耗时表：
| 算子类型 | 节点数 | 总耗时（微秒） | 平均耗时（微秒） | 耗时占比 |
|---|---|---|---|---|
| 卷积 | 17 | 8120 | 478 | 42.1% |
| 归一化 | 17 | 1950 | 115 | 10.1% |
| 激活 | 16 | 880 | 55 | 4.6% |
| 全连接 | 2 | 3560 | 1780 | 18.5% |
| 自定义算子 | 1 | 220 | 220 | 1.1% |
| 数据搬运 | 3 | 4560 | 1520 | 23.6% |
这张表能回答的第一个问题是：时间花在哪了？如果数据搬运占比很高，那你要优先检查数据切分和流水线配置。如果某种算子占比异常高，你就需要对这个类型的算子做更细粒度的排查——要么是这个算子的实现走了低效分支，要么是输入 shape 触发了某种不合适的切分策略。
摘要文本减少了我大量“盲猜”的时间。很多时候我拿到一个性能问题，第一件事就是看这张表，从最大的那个占比项往下钻。
4.3 交互式检查图结构和执行映射
文本摘要能告诉你“是什么”，但要回答“为什么”，还得回到图结构和时间线视图里看细节。
我通常的排查路径是这样的：先在结构视图里检索一个可疑的算子或节点名，然后查看它的输入输出张量 shape、算子属性、是否参与融合。再切到时间线视图，看它对应的执行任务在流上的排布情况——周围有哪些邻居任务，是否和某个数据搬运任务形成了串行等待。
举一个我实际遇到过的例子。某个模型推理的总耗时一直比预期高，摘要表里卷积算子占比正常，数据搬运占比偏高但可接受。我打开时间线视图，按流分组展开，结果发现一个本应该在流 A 上执行的归一化算子，它的任务却被分发到了流 B 上，而且流 B 前面刚好跟着一个长耗时的全连接任务。两个任务之间虽然没有显式的依赖事件，但流 B 是顺序执行的，归一化就只能干等全连接跑完。这就是典型的“任务被编排到错误的流上导致伪依赖”问题。如果没有时间线视图，这种问题从聚合统计里根本看不出来。
这类排查经验想说明一点：可视化调试的价值不只是“把图显示出来”，而是把执行过程中那些原本隐形的排队等待、流分配、依赖关系变得可见。结构视图让你知道模型“应该是什么样”，时间线视图让你看到模型“实际怎么跑的”，两者一对，问题往往就浮出水面了。
5. 踩坑记录与典型问题排查速查
5.1 采集数据不一致怎么办
我第一个要分享的坑是：静态图结构和动态执行数据经常对不上。原因在于编译期拿到了上千个图节点，但运行时任务序列里只出现了一部分，或者反过来，运行时出现了一些任务，你在图里找不到对应的节点。
遇到这种情况不要慌，先分清是哪一种错配。
如果运行时任务多于图节点，大概率是编译器插入了额外设备侧任务，比如内存拷贝、格式转换这类你没有显式定义但编译器自动添加的操作。这种任务在结构视图里往往没有对应节点，但它们记录了真实的执行过程，所以不能在解析时过滤掉。
如果图节点多于运行时任务，可能原因有两种：一是某些节点经过融合后没有单独生成任务，它们的执行被合并到了融合算子的任务里；二是某些节点只在特定分支下执行，这次推理走的是另一条分支。处理方式是把这类节点标记为“未执行”，而不是直接删除，否则下次执行走了另一个分支时数据对不上。
5.2 时间线数据漂移问题
第二个坑是关于时间戳的。运行时接口返回的每个任务有个启动时间和持续时间，但不同任务的计时基准可能不完全一致。如果某个任务没有显式的依赖，它的启动时间可能是基于设备内部的时钟快照换算出来的，存在一个固定的偏移。
这个问题的直接表现是：时间线视图里两个明明没有依赖关系的任务出现了极小的重叠，或者两个有串行依赖的任务之间有非零的间隔。为了解决这个问题，我在项目里加了一个“时间校准”步骤，用流上已知的依赖事件作为锚点，把各流的时钟偏移拉到同一个基准上。
校准逻辑不复杂：找到每个流上第一个有明确启动根因的任务，把它的实际启动时间当作该流的基准零点，然后让所有任务的时间都相对这个零点做平移。做了校准之后，任务之间的依赖间隙才能被真实反映。我建议你在实现类似工具时，一定要保留校准前后的两套时间，方便排查数据异常。
5.3 大模型的界面卡顿问题
第三个坑是可视化性能。我第一次拿一个包含上千节点的模型去跑 Web 界面时，浏览器直接卡住了。问题出在渲染层一次性绘制了所有节点和边，没有做视口裁剪，而且每条边的渲染都创建了独立对象。
解决的方案是采用“按需渲染加层级聚合”的策略。视口缩放级别较高时，只显示被融合组折叠后的粗粒度视图；缩放进入某个区域后，再加载该区域的详细节点。边的渲染改成用批量绘制的方式，避免大量独立绘制对象。这个优化做完，上千节点的图也能流畅地平移和缩放。
5.4 典型问题速查表
| 症状 | 可能原因 | 排查方法 |
|---|---|---|
| 运行时任务数远大于图节点数 | 编译器插入了隐式转换或拷贝任务 | 检查时间线视图里未被结构视图关联的任务类型 |
| 某个算子在图上存在但未执行 | 该节点被融合或走了非本次执行分支 | 查看节点的“是否融合”标记和“所属分支”属性 |
| 数据搬运耗时始终偏高 | 数据切分过细或未与计算重叠 | 切换时间线视图查看搬运任务与计算任务的排布 |
| 两个无依赖任务出现固定偏移 | 计时基准不一致 | 用事件锚点做时间校准后重新观察 |
| 图节点多、任务少且性能下降 | 算子融合过度导致中间结果写回 | 检查融合组内的子节点输出是否在后续被重复引用 |
这套速查表是我在实际使用中沉淀出来的，遇到同类问题时按图索骥，能省不少时间。
6. 进阶实践与个人体会
6.1 把透视能力接入自动化回归
可视化调试工具做出来，如果只停留在“出问题时打开看一眼”，价值会打不少折扣。我后来把它接入到项目的自动化回归流程里，效果出乎意料地好。
做法是这样的：每次模型转换或代码改动后，自动运行一遍采集和导出，生成当前版本的图结构和执行摘要。然后和上一个版本的基准文件做结构化对比，重点关注三类变化：节点数量的增减、算子类型分布的偏移、关键算子的耗时波动。任何一类变化超过阈值，就自动触发告警并附带差异报告。
这套机制帮我抓住了两起潜在的性能劣化。一次是图编译器升级后，某类算子的融合策略变化导致整体耗时上升 12%；另一次是某个自定义算子的内核函数改动后，该算子在时间线上的排布从并行变成了串行。两类问题如果靠人力手动排查，都得花上一两天，自动化对比几分钟就能定位。
6.2 对调试方法论的思考
用过model-inspector这类工具之后，我最大的感触是：在异构计算生态里做调试，光靠日志和断点是不够的。因为问题往往发生在“图”这个抽象层和“任务”这个执行层的缝隙里，你盯着一层看，永远看不到另一层的问题。
可视化透视解决的不是“看”的问题，而是“关联”的问题。它把原本分散在图结构、任务序列、时间戳、内核映射里的信息，用统一的关联视图组织起来，让开发者能在不同抽象层之间自由跳转。这种能力，比单纯画一张漂亮的图有价值得多。
我也建议你在使用这类工具时，不要只把它当“出了问题才用的工具”，而是把它当作理解模型的常规手段。每次适配新模型时，都花几分钟浏览一遍结构视图和时间线视图，你会对自己模型在设备上的“真实样貌”建立起比代码更准确的直觉。
6.3 最后分享一个小技巧
在项目里我保留了一个特别好用的功能：指定节点名称的关键路径高亮。它会自动找出从输入到该节点、以及从该节点到输出的所有依赖路径，在图上用醒目的颜色标出来，同时在时间线视图里高亮这些路径上的任务。
排查精度问题时，我一般会先选一个可疑的中间节点，启用关键路径高亮，然后沿着路径逐个检查每个节点的输入输出 shape 和数据类型是否和预期一致。这样做比在整张图里漫无目的地翻找高效得多。有一次精度问题排查，我靠这个功能在一小时内锁定了某个数据类型转换节点，它在框架图上本应是半精度计算，编译后却被替换成了单精度实现，导致后续所有节点的数值分布都变了。
如果你准备自己动手实现一个类似的可视化调试工具，我建议把“关键路径高亮”作为优先实现的功能之一。它上手简单、效果直观，而且几乎适用于所有调试场景。
