昇腾NPU模型调试调优：msprobe/msdebug全家桶实战指南

在昇腾上跑大模型，最难受的往往不是模型本身有多少层、多少参数，而是出了问题之后你根本不知道去哪里查。精度掉点、偶发NaN、内存越界、算子跑得慢，这四类问题几乎贯穿了从模型迁移到上线的全过程。以前我一个个算子打日志、手动对比npy、盯着task sink日志猜问题，一圈下来半天就没了。后来我把昇腾这套调试调优工具链完整用了一遍，也就是 msprobe/msdebug 全家桶，才意识到之前那些“玄学问题”，其实都可以用系统化的方式去定位。

这套工具链即使不在一个统一的GUI里，四件套各管一摊：msprobe 做精度比对、msdebug 做溢出检测、msSanitizer 做内存检测、msOpProf 做算子级性能剖析。名字看着多，但核心逻辑很清晰——把“跑飞了”这件事拆成“算得不对”“算着爆了”“内存坏了”“跑得慢”四类，分别用不同的工具去抓现场。这篇文章我就按实际使用的顺序，把这四类工具从原理到实操完整过一遍，最后用一个 W8A8 量化的 DeepSeek-R1-Distill-Llama-70B 部署案例，把整个排查链路串起来。新人看完能直接照着操作，老手也可以拿它当一张排查地图用。

1. 认识 msprobe/msdebug 全家桶：从“盲人摸象”到“X光透视”

1.1 这个工具链到底是什么，能解决什么问题

先说一个宏观判断：昇腾是一个高度异构的计算平台，NPU上有AI Core、AI Vector、Cube Unit，还有专门的缓存和搬运机制，和GPU的编程模型差异非常大。你在GPU上跑得好好的模型，往昇腾上一迁移，浮点输出、算子执行顺序、内存布局全都会变。这带来两个结果：一是性能需要重新调，二是正确性需要重新验。不要以为“同一个ONNX转成OM就万事大吉”，算子融合以后中间结果都看不见了，一个精度问题可能藏在几十个算子之后。

msprobe/msdebug 全家桶解决的就是这个“黑盒”问题。msprobe 可以把NPU上算子的中间输出和标杆结果（比如PyTorch GPU结果、CPU算子结果、甚至你自己手写的黄金数据）做逐层比对。msdebug 则专门盯Inf和NaN，一旦张量里出现溢出值，它能快速定位到第一个爆掉的算子。msSanitizer 对应的是C/C++层面的内存问题，适合调自定义算子、框架扩展和通信代码时用。msOpProf 则是算子级性能剖析，告诉你每个算子在NPU上到底花了多长时间、AI Core利用率多少、有没有“搬数据比算数据还久”的尴尬情况。

这套工具链让我最满意的一点是，它不需要我们自己在模型里插桩打dump，而是在框架和运行时层面去采集。也就是说，你的模型代码不需要大改，只要把运行模式切到对应的诊断模式，然后复现一次问题，就能拿到现场数据。这对于生产环境的bug复现特别重要，很多偶发问题你就是不能在本地稳定复现，能不动代码就把现场采集出来，就已经赢了一半。

1.2 工具链全家福：四把螺丝刀的分工

这里我建议先把四个工具的分工刻在脑子里，不然用到的时候容易混：

这个表格看起来简单，但实际排查问题时非常有用。我自己的习惯是拿到一个bug先分类：如果结果是错的但没有告警，优先开 msprobe；如果日志里有浮点异常或者输出出现NaN，直接走 msdebug；如果是偶发crash、段错误、var unexpected，先想 msSanitizer；如果功能都正常但就是慢，才轮到 msOpProf。很多人一上来就开 profiling，发现性能没问题，转头又去查精度，结果兜了一大圈发现是精度错乱导致的伪性能问题。分类先行，是这套工具链里最重要的工作方法。

1.3 能用在哪，适合谁看

这套工具链适合三类人：第一类是模型迁移工程师，从PyTorch/TensorFlow往昇腾迁移模型，跑通了MIGraphX/TorchAir又掉点，不知道怎么定位；第二类是算子开发工程师，写了自定义算子想验证边界条件、内存安全、性能基线；第三类是做推理优化的人，比如部署量化模型时发现输出和原始模型对不上、显存占用异常、首token延迟偏高，需要系统化的排查手段。

后面所有讲解我都会基于一个真实的部署场景展开：在910B上部署一个 W8A8 量化版本的 DeepSeek-R1-Distill-Llama-70B。这个模型权重和激活都用INT8，对算子的数值范围非常敏感，正是精度、溢出、内存、性能四类问题扎堆的地方。你不需要真的跑70B模型，它的排查链路和7B、13B完全一致，方法照样能复用。

2. 先准备环境：工具链安装与基本约束

2.1 版本配套与安装

工具链通常随 CANN 的 Toolkit 包一起发布，不需要单独安装。但有一个前提：版本要严格对齐。msprobe、msdebug、msSanitizer、msOpProf 和 CANN runtime、NNAL、驱动之间存在版本耦合，混着用很容易出现“工具能启动但采集不到数据”的情况。我踩过一次坑：CANN 6.3 的环境里直接用 7.0 版本配套的 msprobe 命令，工具报了dump config parse failed，查了半天是对应动态库版本不匹配。

安装方面，从昇腾社区下载对应版本的 CANN Toolkit，默认安装路径通常是/usr/local/Ascend/ascend-toolkit/latest。装完之后把下面几行加到~/.bashrc里，注意路径按你的实际安装位置调整：

source /usr/local/Ascend/ascend-toolkit/set_env.sh export ASCEND_DEVICE_ID=0 export ASCEND_GLOBAL_LOG_LEVEL=3

ASCEND_GLOBAL_LOG_LEVEL=3是ERROR级别，平时不要开成0或1，否则日志量大到你怀疑人生。调试阶段我建议先保持这个配置，等需要看更细的调度信息时再按需调整。

2.2 拿到一份“设备快照”

在开始任何诊断之前，先确认设备状态。这个习惯救了我很多次，尤其是排查偶发问题的时候，你以为的软件bug，很可能是芯片降频、内存ECC报错、或者相邻芯片抢占带宽导致。

npu-smi info

这个命令会显示每张卡的型号、固件版本、温度、功耗、显存用量和升频降频状态。我一般关注三个指标：温度超过85度先别急着重现，等凉下来再测；显存占用如果是慢慢爬升的，先怀疑泄漏再考虑其他；如果芯片工作模式显示为低频，可能是散热或者供电问题，这时候跑性能测试没有任何参考价值。

另外强烈建议用一个专门的目录保存所有诊断现场，比如：

mkdir -p /workspace/diag/{dump,prof,sanitizer,overflow}

后面每一轮诊断出的数据都归档到对应目录，文件名加上时间戳。排查精度问题经常会做多轮复现，没有归档习惯的话，你最后根本分不清哪份 dump 配的是哪次运行的结果。

2.3 几个必须提前知道的约束

工具链虽然强大，但不是万能药，有几点你得提前接受：

• 开启诊断模式通常会降低执行性能。msprobe 的逐算子 dump、msdebug 的溢出检测、msSanitizer 的内存插桩都会引入额外开销。小模型没问题，70B这种规模，建议先用小batch、小序列长度复现，别一上来就跑全量生产负载。
• 内存检测模式下不能和极致性能优化同时开。有些算子库在开启融合和重计算后，内存行为会变化，检测结果会引入噪声。先保证正确性，再谈性能。
• 工具输出的路径默认在运行目录下。建议在每次运行前显式指定输出目录，避免被CANN默认的、一层套一层的目录结构搞晕。

3. 精度比对：msprobe 的常规操作

3.1 为什么昇腾上精度问题如此阴魂不散

精度掉点通常不是“某个算子算错了”，而是“计算顺序变了”。昇腾上有大量算子融合：把Conv+BN+ReLU合成一个算子，把Attention里的QKV变换和一个缩放合并，把LayerNorm的均值方差计算重排。融合后中间结果不再落盘，浮点运算的顺序就变了。浮点的加法和乘法不满足结合律，顺序一换，最后一位误差就可能被放大。再加上混合精度，FP16的表示范围小，BF16的精度又低，误差积累到一定程度就成了肉眼可见的掉点。

所以“精度比对”不是去证明“NPU完全等于GPU”，而是去量化“差异有多大、集中在哪一层”。这个差异如果远小于下游精度的敏感度阈值，就完全可以接受；如果大到让最终答案都变了，就必须定位到具体算子层。

3.2 精度比对配置实操

我用 msprobe 做精度比对的流程是这样的。第一步，准备一个“黄金标杆数据”。标杆来源可以是 CPU 上的 FP32 算子输出、GPU 上的 PyTorch 结果、或者 TensorRT 引擎的输出。关键是标杆本身要足够稳定可靠。我之前有一次用 PyTorch CPU FP32 当标杆，结果那版 PyTorch 的某个算子本身就有bug，全部白干，后来换了官方稳定版才好。

第二步，在 NPU 侧跑模型并同时开启 dump。一个典型的配置长这样：

{ "dump_mode": "all", "model_path": "/workspace/models/llama70b_w8a8.om", "input_data": "/workspace/data/calib_input.bin", "output_dir": "/workspace/diag/dump/round1", "compare": { "enable": true, "golden_path": "/workspace/data/golden_npu_cpu.json", "metrics": ["cosine_similarity", "max_abs_error", "relative_error"] } }

实际命令入口在不同版本里略有差异，但一般都能通过工具的自带帮助确认，运行前先看一眼：

msprobe --help

第三步，选择比对粒度。我通常先用“整网输出比对”快速确认差异量级，再用“按层比对”精确定位。如果整网的余弦相似度已经掉到0.99以下，那就说明问题比较严重了，直接进入单算子细查阶段。

3.3 看懂比对结果

比对结果里有两类指标非常关键：余弦相似度（Cosine Similarity）和最大绝对误差（Max Abs Error）。

余弦相似度看的是“方向”，如果某层输出余弦相似度接近1，说明大部分元素的大小关系是对的；但如果最大绝对误差又特别大，说明有个别离群点。这两种情况指向不同的根因：前者代表全局数值漂移，通常和计算顺序、混合精度策略有关；后者代表个别极端值错乱，往往是指数运算、归一化、量化反量化步骤里出了异常。

我实际遇到过一个非常典型的案例：模型前面所有层余弦相似度都在0.9999以上，到了最后一个分类头突然掉到0.9。开始我以为是分类头线性层的权重没有正确加载，折腾了很久。后来细看 dump 才发现，是输入到分类头之前有一个全局平均池化，池化窗口大小在NPU上被算子融合引擎自动调整了，导致个别batch的统计范围不一样。这种问题你不在中间层做dumpper根本看不出来。

3.4 常见精度异常定位经验

如果按层比对后发现误差集中在某几个算子，我的排查顺序是：

1. 先看是不是量化相关。W8A8模型里最常见的就是activation的scale估算不准，导致反量化后偏差大。把量化配置里的scale重新校准一遍，很多时候精度就回来了。
2. 再看是不是混合精度策略。如果模型脚本里用amp.initialize或torch.autocast指定了FP16，检查哪些算子被降精度了。昇腾上有些算子在非FP32模式下会有精度差异，你可以通过配置文件强制某一层走FP32再对比。
3. 最后才怀疑算子实现。如果误差集中在某一个自定义算子，那就需要单算子粒度验证。把该算子的输入、权重、参数全部dump下来，在CPU上用同一套输入重算一次，对比NPU输出，误差仍然大就说明是算子实现或调用方式的问题。

记住一个原则：比对是过程，不是结论。工具会告诉你“哪些层有差异”，但“哪一层是根因”还得结合模型结构去推理。误差传播路径上，越靠近输出端的算子，它的误差越可能是前面层传导过来的，真正需要修的第一个异常点往往在中间靠前的位置。

4. 溢出检测：msdebug 如何定位 Inf/NaN

4.1 溢出到底是怎么回事

溢出检测是很多人的知识盲区，因为GPU上你很少开这类检查，CUDA默认是 “Garbage in, garbage out” 的风格，出了NaN你也只能瞪眼。但昇腾上，msdebug 可以帮你在数值刚开始出现问题的时候就抓住现场。

先讲原理。FP16 能表示的最大值是 65504，BF16 虽然能到 3.39e38，但它的尾数位只有7位，精度损失大。在把 FP32 模型转成 FP16/BF16 混合精度或者 W8A8 量化模型时，最容易爆的一个场景是：某个中间结果在 FP32 下是 50000，转成 FP16 后还在范围内，但再经过一次乘加，直接变成 80000，溢出成了 Inf。之后任何用到这个 Inf 的算子都会产生 NaN。

更阴险的是，有些场景下不出现 Inf，而是出现“次正规数”（subnormal）或者极端小的数值。这类数值在FP16下精度极低，可能导致除数为0，进而产生Inf。msdebug 把这些情况都归为“溢出类异常”，统一去检测。

4.2 启动溢出检测

启动 msdebug 的核心思路很简单：让运行环境在检测到张量中有 Inf/NaN 时立即停住，并给出该张量的产生位置。CANN里通常用环境变量或者调试工具的run模式来开启。一个典型的启动方式：

export MSDEBUG_OVERFLOW_MODE=1 export MSDEBUG_DUMP_PATH=/workspace/diag/overflow/round1 python run_infer.py --model /workspace/models/llama70b_w8a8.om --input /workspace/data/overflow_test.bin

开启后，框架运行时会在算子执行的前后检查输出张量。一旦发现异常值，会记录当前算子的名称、输入输出 shape、以及异常值所在的具体位置索引。

这一步的要诀是“用最接近崩溃的输入去复现”。溢出问题往往和输入数据的分布强相关，如果你随便拿一批正态分布的数据测，可能根本测不出来。最好的复现材料是真实生产流量里已经触发过NaN的那一批数据，如果没有，就用校准集里“最难”的样本，比如文本长度特别长、attention分数特别高的seq。

4.3 解析溢出报告

溢出报告里最重要的一行是它给出的第一个异常算子。我用 msdebug 定位到的第一个案例，报给我们的算子是一个 LayerNorm。一开始我很困惑：LayerNorm 的输出有除法，理论上确实可能出问题，但报错发生在模型比较靠前的位置，后面还有几百个算子呢。

后来我做了个实验，把该 LayerNorm 前面一层的输出手动 dump 出来，用脚本检查，果然那里已经有一个元素接近 FP16 的最大值，只是还没溢出。到了 LayerNorm 里做方差计算时数值爆掉，才被检测到。这说明：msdebug 报出的算子，是“临界点”，不一定是“源头”。排查时从报告算子往前倒推5到10个算子，逐个检查中间张量，找到第一次出现超大值或异常值的地方，那才是根因。

为了加快这个回溯过程，我建议同时开启前若干层的 dump。比如：

export MSDEBUG_RETRO_DUMP_LAYERS=10

这样溢出被掐住的同时，你也能拿到之前10层的输出快照，省得再跑一轮。

4.4 W8A8 场景下的溢出案例

在 W8A8 量化模型里，溢出还有一个特殊来源：反量化时的 scale 精度。DeepSeek-R1-Distill-Llama-70B 这类模型的激活值在不同层分布差异很大，有些层激活值范围特别宽，如果scale设置过小，反量化后数值非常大，后面的 GELU、Softmax 这种非线性算子直接就把 FP16 干爆了。

我遇到的一个具体case是：量化后的激活值经过一个残差连接后，数值范围比预期的大了30倍。正常 FP32 下这个位置不会出问题，但转成 FP16 后已经达到 50000 左右。再过一层 GELU，输出直接是 Inf。msdebug 定位到 GELU 算子，我又回看了残差前的输出，才发现是量化 scale 估低了，重新校准了那一层的 scale 之后，问题彻底消失。

这个案例给我的教训是：量化模型部署时，溢出检测不应该只在最终验证阶段跑一次，而要在每次修改量化配置后都跑一遍。很多“看起来像随机挂掉”的推理异常，其实都是溢出导致的连锁反应。

5. msSanitizer 内存检测：越界、野指针与泄漏

5.1 内存问题是AI框架里的“隐形地雷”

AI框架的内存问题比普通C/C++工程更隐蔽。因为大多数时候你用的是Python，根本看不到内存分配和释放的细节。但一旦你写了自定义算子，比如C++实现的MHA、RoPE、量化矩阵乘法，这些代码里一个越界写就会悄无声息地破坏旁边张量的数据。更麻烦的是，这类错误通常不会当场崩溃，而是隔了一段时间后模型输出突然错乱，回看日志什么都没有。

msSanitizer 的角色就是内存层面的“安检仪”。它会对内存操作做插桩，检测堆越界、栈越界、use-after-free（悬空指针）、double-free（重复释放）和未初始化读取。它的定位思路和CPU上的 AddressSanitizer 很像，但要适配昇腾的异构内存管理系统，所以不能直接拿ASan的指令去类比，必须用专门面向NPU的工具。

5.2 运行 msSanitizer

运行 msSanitizer 有一个关键前提：它检测的是实际执行在NPU上的指令，所以你要让模型真正跑到NPU，而不是停留在Python图构建阶段。

我的操作流程是：

1. 把模型迁移成一个最简单的可复现用例。哪怕你最终要跑70B模型，检测阶段也要砍成1层、batch=1、token数16这种迷你配置。因为内存检测的插桩开销非常大，全模型跑一轮可能要几十分钟。
2. 开启MSANITIZER_MODE=1，并设置输出目录：

export MSANITIZER_MODE=1 export MSANITIZER_OUTPUT=/workspace/diag/sanitizer/round1 python run_custom_op_test.py

3. 跑完以后去输出目录看报告，主要关注三点：报告里有没有heap-buffer-overflow、use-after-free、double-free这几类关键词；报错时所在的调用栈；报错地址和线程ID。

这里要特别注意：msSanitizer 报告里的调用栈可能只到框架层，看不到你自己算子的函数名。这是因为NPU上的kernel执行是异步的，真正出错时CPU侧的调用栈早就返回了。解决办法是在自定义算子代码里加辅助性的日志打印，或者用msopz之类的工具把task id映射回算子名。

5.3 解读报告并修复

拿到报告后，修复逻辑反而简单，关键是要看懂“报告描述的是哪一次访问”。比如报告里写WRITE of size 4 at 0x...，同时报出访问地址是某个buffer内部，但偏移量超过了该buffer的声明长度，那就是越界写。

我自己定位过最典型的一个问题是：自定义MHA算子里，计算attention score的时候，score矩阵的shape是[batch, head, seq, seq]，但我在代码里用的下标是[batch, seq, head, seq]，导致在某些极端 seq 长度下下标计算越界。普通测试数据下，越界只是写到了相邻的K/V缓存上，不会立刻报错；但换成长文本时，相邻缓存被破坏，模型输出就彻底崩了。用 msSanitizer 一抓，直接定位到那个循环里的越界写。

修复的时候有一个经验：不要只修报告指出的那一行。因为越界写一旦发生，可能已经破坏了内存中的多块区域，你修完第一处之后建议再跑一轮 sanitizer，确认没有第二处。我遇到过修了三个越界点才把报告清零的情况。

5.4 内存检测的实战心得

• 检测前先关闭NPU的算子融合和图优化。有些图融合变换会改变内存分配方式，插桩结果会包含大量误报。关闭方式通常是设置--disable_fusion或环境变量，具体看CANN版本。
• 检测时需要把CUDA或GPU分支完全走不到的位置也覆盖。很多自定义算子用宏区分昇腾和GPU实现，普通测试跑的是GPU分支，迁移到昇腾后出错的是NPU分支，这个分支差异本身就是bug高发区。
• 不要忽略“内存泄漏”检测结果。推理服务长稳运行时的显存爬升，很多是自定义算子里分配的workspace没有释放。msSanitizer 能抓到这一类，表现为每次调用都多出一块固定大小的分配。
• 如果报告里大量报错集中在一个偏置张量或权重缓存上，优先怀疑模型加载逻辑里的字节对齐问题。昇腾对某些buffer有64位对齐要求，你用malloc分配了sizeof(float)*N，但没有做对齐，访问时就可能越界。

6. msOpProf 算子调优：把热力图变成优化清单

6.1 性能问题定位思路

功能修对了，下一个问题就是性能。很多团队在跑分阶段发现昇腾上的 performance 不到预期，第一反应是“硬件不行”。但根据我的经验，绝大多数情况是“算子没有充分调优”或者“数据传输掩盖了计算”。你需要的不是抱怨，而是真实数据。

msOpProf 的价值在于把性能问题从“感觉慢”变成“具体哪个算子慢”。它能采集每个算子的耗时、AI Core利用率、搬运引擎耗时、任务下发耗时等。有了这些数据，你能做出一个“优化清单”，而不是在一个已经优化到顶的算子上瞎使劲。

6.2 采集 Profiling 数据

msOpProf 的使用方式非常直接。我习惯把 profiling 采集封装成一个脚本，方便多次重复：

msopprof --output=/workspace/diag/prof/round1 \ --application="python run_infer.py --model /workspace/models/llama70b_w8a8.om --input /workspace/data/bench.bin" \ --profiling-level=2

--profiling-level决定采集粒度。level 0 只采整网数据，level 1 增加按迭代的数据，level 2 到算子级，level 3 还会包含指令级的细微耗时。日常先用 level 2，它带来的采集开销相对可控，数据量也不会大到没法处理。只有在定位特定算子内部的load/store不均衡时，才上 level 3。

采集完成后，输出目录里会出现op_summary.csv、timeline.json、kernel_details*.csv之类的文件。我个人的习惯是先看op_summary.csv，按耗时降序排一下，看Top 20算子占据了多少比例。如果Top 20就占了70%以上的时间，方向就很明确了；如果耗时分散在几百个小算子上，那说明你的图优化做得不够，需要考虑更激进的算子融合策略。

6.3 从数据到优化

拿到数据后，我有一套固定的分析方法：

第一，先把“纯计算型算子”和“搬运型算子”分开。Conv、MatMul、GELU这种是计算型，拷贝、transpose、concat这个类型的算子消耗的是带宽。计算型算子看AI Core利用率，利用率低于50%的，优先怀疑tiling策略不对或者shape不规整。搬运型算子看搬运数据量和实际耗时，如果耗时和数据量不成比例，多半是内存布局不对导致的多余搬运。

第二，检查 Host 和 Device 侧是否重叠。AI框架在推理时，Host侧要完成输入预处理、模型调度，Device侧要执行算子。如果timeline显示Device侧有大量空闲等待，而Host侧事件密度极高，说明是host-bound。这种情况下开再多的算子融合也没用，要优化的是预处理流程和任务下发机制。

第三，找“串行尾巴”。很多模型在最后阶段存在明显的串行依赖，一个算子算完才能算下一个。如果你的模型里连续多个算子都是前一个依赖后一个，没有任何可供并行的分支，那这些算子的耗时就是要被重点优化的对象。常见手段是把它们合成一个算子，减少设备间同步次数。

6.4 昇腾上几个立竿见影的优化手段

我自己用得最多的优化手段有四个：

一是算子融合，这个不是新概念，但昇腾上融合带来的红利比GPU更明显。比如 LayerNorm+Residual+Add 这种模式，如果分开跑，每个算子都要读写一遍HBM，融合后一次搞定，耗时肉眼可见地下降。

二是优化KV Cache 的 layout。推理大模型时，KV Cache的存取非常频繁。如果layout是[batch, seq, head, dim]，对于某些并行场景并不友好；改成[batch, head, seq, dim]之后，搬运量能降低不少。这个用 msOpProf 很容易验证：对比两次profiling里Gather算子的耗时差异。

三是固定shape。动态shape会让NPU上的内存分配和算子tiling在每次执行时重新计算，带来额外开销。如果你能接受固定序列长度，把模型导出成固定shape的OM，性能往往有20%以上的提升。代价是灵活性下降，业务上要能接受padding。

四是量化和精度档位调整。W8A8 本身就是为了性能而做的量化，但在具体实现里，很多算子还能进一步选择“高精度模式”或“高性能模式”。不是所有算子都要用高性能模式，遇到那些对精度极不敏感的算子，比如GELU、残差连接，可以走高性能模式，对整体精度影响不大，但速度提升明显。

7. 综合实战：W8A8 量化模型在昇腾上的“体检”

7.1 场景描述

前面几节是单独介绍，现在我们做一个完整串联。我们要部署一个 DeepSeek-R1-Distill-Llama-70B 的 W8A8 量化版，权重和激活都用 INT8。昇腾肯定是支持这类模型的，但“支持”和“跑得好”之间有几个坎：精度对齐、数值稳定、内存安全、性能达标。下面的过程基于我做过的一次真实排查，细节稍作调整，链路完全一致。

我的习惯是先确定一个“体检清单”：

• msprobe：整网输出与标杆比对的余弦相似度 ≥ 0.99
• msdebug：一个评测集跑完，报告里没有任何溢出
• msSanitizer：小规模复现时，报告完全干净
• msOpProf：首token延迟和生成token速率达到业务要求

这个清单既是验收标准，也是排查顺序。

7.2 第一轮：用 msprobe 抓精度掉点

第一轮就直接上真实推理场景。我用 msprobe 做了整网输出的比对，标杆数据是原始FP32模型在CPU上的输出。结果出乎意料，整体余弦相似度只有0.96，远低于0.99的验收线。进一步按层看误差分布，发现误差主要集中在第25层附近和最后5层。

先看最后一层，这个判断起来容易：它靠近输出，误差可能是前面积累的。但第25层的误差就值得深挖了。我把第25层的输入、输出单独dump出来，和标杆做逐元素对比，发现最大绝对误差出现在一条特定的token路径上。这个token是长文本里的一个罕见字，对应的激活值分布和校准集偏差较大。

根因很快锁定：那一层是Attention的QKV 线性层，量化时用了一个全局静态scale，但这个scale在极端激活值下明显偏小。我的处理办法是改成按token动态估算scale，或者至少对这一层用per-channel scale。重新校准后，整体余弦相似度从0.96涨到了0.993。

这一轮验证了一个观点：精度比对不是跑一遍就完事，关键在于按层定位。没有 msprobe，我根本不知道误差聚集在哪一层，只能全局调scale，最后很可能把正常的层也调乱。

7.3 第二轮：msdebug 与 msSanitizer 联手排雷

精度修到0.993之后，我满以为可以收工了。结果用评测集一跑，两条路径偶发出现NaN。我立刻开启 msdebug，用出问题的样本复现。报告指向一个Softmax 后面的 Add 算子。但正如前面讲的，报错点不是根因。我往前倒查，发现Softmax的输入其实已经有一个元素是-Inf了。为什么会-Inf？再往前看，是注意力分数在量化反量化过程中乘以了一个非常大的scale因子，导致某个极端负值溢出成-Inf。

修复方法：把注意力分数的量化scale从静态改为基于当前QK最大值动态缩放，并且给反量化结果做一个数值范围裁剪。这个修完，NaN问题消失。

接下来是内存检查。由于这个模型里有我自研的MHA融合算子，一直没有用官方实现，所以我对内存安全性心里没底。我把模型缩减成2层、batch=1、seq=32的迷你版本，开启 msSanitizer 跑了20步，果然抓到一个 Heap-buffer-overflow，位置就在MHA自定义算子计算注意力矩阵的循环里，越界发生在seq维度上。查下来是索引变量写成了head_idx * seq_len + head_idx，多算了几个下标。

修完这个之后我又跑了一轮 sanitizer，报告完全干净。这里多说一句：内存问题在普通功能验证时非常难暴露，只有sanitizer这种深度插桩工具才能让它在可控时间内现形。花30分钟开一次sanitizer，比线上偶发crash之后熬夜排查要值太多。

7.4 第三轮：msOpProf 把性能压到业务线以内

功能全部正常后，我开始跑性能基线。业务要求首 token 在2秒内，生成token速率不低于每秒25个token。第一次 msOpProf 数据显示，模型整体耗时里，Attention相关算子占了48%，其中KV Cache的Gather算子占了13%，这明显异常。

我打开timeline，看到Gather算子每次从HBM里取KV时，跨步访问得很厉害。原因是KV Cache用的是[batch, head, seq, dim]layout，但我的Gather算子实现是按seq维做拷贝，导致每个头都要搬运一整条不连续的数据块。我把KV Cache layout调整成[batch, head, dim, seq]，并且为Gather算子加了连续读取的tiling优化，Gather的耗时直接降了一半以上。整网算子耗时Top列表里的瓶颈，从Gather变成了MatMul。

接着我看Host vs Device的重叠情况。数据显示Device侧在等待Host侧下发算子，对于一个70B模型，任务下发开销不能小看。我把输入预处理尽量挪到另一个线程，并把多个小算子合并成一个大的融合算子，减少了下发次数。最终首token降到1.4秒，生成速率到了每秒31个token，达标。

回看整个优化过程，如果没有 msOpProf 的数据支撑，我很可能先去调MatMul的tiling，而不是发现Gather和Host下发才是真正的瓶颈。数据永远是先于直觉的。

8. 常见问题速查与避坑清单

8.1 高频问题速查表

下面这几类问题是我在团队里被问得最多的，直接做成速查表：

这张表不等于完整手册，但覆盖了我个人经历里80%的日常问题。遇到表格里没有的情况，我的建议是回到六个字：先分类，再复现。拿准确认是精度、数值、内存还是性能，然后针对性地开对应的诊断工具。

8.2 我的独家避坑经验

最后分享几条常规文档里不会写的经验。

第一，一定要养成“固定输入固定模型”的复现习惯。很多偶发问题其实是因为输入分布变化触发的，你没有固定现场，后面所有诊断都是打空气。我会把每次出问题的输入数据单独切成一个小文件保存，诊断时直接喂给工具，保证每次复现的是同一个问题。

第二，不要在同一个环境里混用多个版本的CANN工具包。我见过很多人为了贪图某个新特性，在系统里保留了旧版本的环境变量路径，结果msprobe报告的数据严重失真。装新版本前，先把旧版本的ASCEND_HOME、LD_LIBRARY_PATH清干净。

第三，诊断数据一定要保存原始格式，不要在中间做一次“转换”再分析。比如msprobe的dump结果，你转成npy之后又经过一次脚本处理，精度信息可能已经被二次污染。正确做法是用官方工具直接生成报告，再人工分析，保持原始数据只读。

第四，性能优化时别陷入“单算子最优”的执念。有时候为了把某个算子优化到极致，会引入更复杂的tiling，结果是这个算子快了，但相邻算子的数据布局变了，反而让整体变慢。所以每次改动都要用 msOpProf 重新看整网，而不是只看单个算子的时长。

8.3 后续还能怎么扩展

这套工具链不只是排查问题的“事后诸葛”，它完全可以前移到开发流程里。我现在给团队定的规矩是：模型迁移完成后，第一轮跑通功能不算完，必须过一遍“精度+溢出+内存”三项体检，性能验收再额外走 msOpProf。每个版本合并前，在CI里加一个精简版的 sanitizer 跑批任务，防止新改动引入内存隐患。

如果你正在做昇腾模型部署，或者准备把团队的自定义算子质量往上提一个档次，这套全家桶值得你花一个下午完整跑一遍。工具是死的，方法是活的。先把定位问题的顺序练成肌肉记忆，后面遇到再诡异的bug，你也会比别人多一份底气。