作者：昇腾实战派

在大模型部署与训练过程中，精度问题往往成为影响模型效果的关键瓶颈。尤其是在异构计算平台（如NPU）上运行时，由于计算精度、算子实现差异等因素，模型输出可能与预期存在偏差。

本文系统介绍基于Ascend生态MindStudio的msit、msprobe和msprof三大工具，涵盖从推理中间层数据采集、精度比对、训练过程监控到性能分析的全流程能力，帮助开发者实现从问题发现到根因定位的闭环调试。

---

常用命令速查表

工具	命令	用途
msit	msit llm dump --exec "python x.py"	采集推理中间层
msit	msit llm compare	精度比对
msprobe	msprobe dump	问题现场精度采集
msprobe	msprobe compare	精度问题定位、跨平台比对
msprobe	msprobe accuracy-checker	初步排查精度异常，不受累计误差影响
msprobe	msprobe monitor	长周期训练中的异常检测
msprof	msprof op python3 x.py	上板性能分析
msprof	msprof op simulator	仿真指令流水

---

msit 工具：推理精度分析利器

1. 工具包安装

pip 安装

# 1. 安装 msit（核心工具）
pip install msit

# 2. 安装 llm、probe、profiler 模块
msit install llm
msit install probe
msit install profiler

---

2. 工具使用说明

msit —— 推理精度分析

场景：采集中间层 Tensor，对比 CPU/NPU 推理结果

步骤 1：修改推理脚本

from msit_llm import DumpConfig, register_hook

dump_config = DumpConfig(dump_path="./dump_npu")
register_hook(llm.llm_engine.model_executor.model_runner, dump_config)

步骤 2：运行数据采集

msit llm dump --exec "python inference.py" --type model tensor -er 1,1

命令说明
msit llm dump --exec "精度测试命令" --type {比对类型} -er {[比对token的索引位置]}

• --type：指定 dump 类型，支持 tensor（Tensor 级）、model（模型层级）等，可组合使用，如 --type model tensor。
• -er：指定用于精度比对的 token 索引位置（如 1,1 表示第2个token的第2个位置）。
• 可选参数：-o {dump路径}、--device-id {设备ID}。
  更多参数详见：msit/msit/README.md · Ascend/msit - AtomGit | GitCode

---

典型场景 Dump 数据结构说明

根据模型是否包含 warmup 阶段，dump 数据组织结构有所不同：

场景 1：无 warmup 阶段

├── msit_dump_{TIMESTAMP}
│   ├── tensors
│   │   ├── {device_id}_{PID}
│   │   │   ├── 0                               # 第一轮推理（含 Prefill）
│   │   │   │   ├── 0_WordEmbedding/
│   │   │   │   ├── 1_PositionalEmbeddingGather/
│   │   │   │   ├── 2_Prefill_layer/
│   │   │   │   ├── 3_Prefill_layer/
│   │   │   │   └── 40_Decoder_layer/           # Decode 阶段
│   │   │   │   └── 41_Decoder_layer/
│   │   │   ├── 1                               # 第二轮推理（仅 Decode）
│   │   │   │   ├── 40_Decoder_layer/
│   │   │   │   └── 41_Decoder_layer/
│   │   │   └── ...

场景 2：有 warmup 阶段（仅 Prefill）

├── msit_dump_{TIMESTAMP}
│   ├── tensors
│   │   ├── {device_id}_{PID}
│   │   │   ├── 0                               # Warmup 阶段（Prefill + Decode）
│   │   │   ├── 1                               # 正式推理第一轮（Prefill + Decode）
│   │   │   ├── 2                               # 正式推理第二轮（仅 Decode）
│   │   │   └── ...

场景 3：有 warmup 阶段（Prefill + Decode）

├── msit_dump_{TIMESTAMP}
│   ├── tensors
│   │   ├── {device_id}_{PID}
│   │   │   ├── 0                               # Warmup 阶段（完整推理流程）
│   │   │   ├── 1                               # 正式推理第一轮（Prefill + Decode）
│   │   │   ├── 2                               # 正式推理第二轮（仅 Decode）
│   │   │   └── ...

说明：通常 Prefill 仅执行一次，后续轮次仅包含 Decode 阶段数据。建议在正式推理阶段采集数据，避免 warmup 干扰。

---

步骤 3：精度比对

msit llm compare -gp {path} -mp {path} [可选参数]

说明：

• -gp：指定标杆环境（如 CPU/GPU）的 dump 路径。
• -mp：指定目标设备（如 NPU）的 dump 路径。
  输出包含余弦相似度、相对误差、最大误差等指标，支持异常算子标记。
  详情参见：msit/msit/README.md · Ascend/msit - AtomGit | GitCode

---

msprobe 工具：训练与推理精度调试专家

1. 工具安装

pip 安装

pip install mindstudio-probe --pre

安装成功后将输出：

Successfully installed mindstudio-probe-{version}

whl 包安装

# 下载链接
https://ptdbg.obs.cn-north-4.myhuaweicloud.com/msprobe/26.0.0/mindstudio_probe-26.0.0a1-py3-none-any.whl

pip install ./mindstudio_probe-26.0.0a1-py3-none-any.whl

源码编译安装

git clone https://gitcode.com/Ascend/msprobe.git
cd msprobe

pip install setuptools wheel

# 基础安装
python3 setup.py bdist_wheel

# 带拓展模块安装（如需）
python3 setup.py bdist_wheel --include-mod=tb_graph_ascend,trend_analyzer --no-check

cd ./dist
pip install ./mindstudio_probe*.whl

参数说明：

• --include-mod：指定可选模块，支持：
  • adump：L2级静态图 dump（需 MindSpore ≥ 2.5.0）
  • tb_graph_ascend：模型分级可视化插件（需 Node.js v20.19.3 + Npm v10.8.2）
  • trend_analyzer：趋势可视化分析
  • atb_probe：ATB推理场景数据采集
  • aclgraph_dump：aclgraph场景下保存 .pt 文件（需 torch + torch_npu）
  • 多模块以逗号分隔，如 adump,atb_probe
• --no-check：跳过证书校验，适用于网络受限环境。

---

2. 工具使用

msprobe 是面向 PyTorch 与 MindSpore 框架的精度调试工具包，专为定位训练与推理过程中的精度异常而设计。

核心功能模块

功能模块	说明
精度采集（Dump）	支持 API 级（L0）、Module 级（L1）或混合级（mix）数据采集，可选真实 Tensor 或统计量。
训练状态监控（Monitor）	轻量级采集激活值、梯度、优化器状态、通信算子中间值，适用于长周期训练。
分级可视化	解析 dump 数据，还原模型结构，支持层级精度比对与溢出分析。
精度比对	对比 NPU 与 CPU/GPU 输出，计算余弦相似度、相对误差、最大误差等指标。
精度预检（Accuracy Checker）	扫描模型中所有 MindSpore.mint API，自动构造单元测试，快速定位异常算子。
溢出检测	检测输出数值范围，识别潜在溢出风险。
梯度状态监测	采集梯度数据并进行相似度比对，精准定位问题 step。
训练前配置检查	对比环境配置差异（如库版本、随机种子、超参等），提前规避精度风险。

---

1. 数据采集（以 PyTorch 为例）

from msprobe.pytorch import PrecisionDebugger, seed_all

# 固定随机种子，确保可复现
seed_all(mode=True)

# 初始化调试器，加载配置
debugger = PrecisionDebugger(config_path="./config.json", model=model)

# 训练循环中插入采集逻辑
for step in range(num_steps):
    debugger.start()
    output = model(data)
    loss = criterion(output, target)
    loss.backward()
    debugger.stop()
    debugger.step()

config.json 配置说明：

• level：可选 L0（API级）、L1（Module级）、mix（混合级）
• 支持配置采集路径、范围、是否采集真实数据、是否记录调用栈等

---

2. 精度预检

msprobe accuracy-checker \
  --dump-dir /path/to/npu_dump \
  --ref-backend cpu \
  --output report.json

输入：NPU 采集的 dump 数据
输出：API 级精度分析报告，标注异常算子
适用于快速排查潜在精度差异，不受累计误差影响。

---

3. 精度比对

msprobe compare \
  --npu-dump /path/to/npu_dump \
  --gpu-dump /path/to/gpu_dump \
  --output report.json \
  --mapping mapping.yaml

• 支持自定义映射文件 mapping.yaml，用于对齐不同框架的层名
• 输出包含误差分布、相似度、异常指标统计
• 可导入 MindStudio 进行图形化分析，提升问题定位效率

---

总结

msit、msprobe 和 msprof 构成了一套完整的 AI 模型调试工具链，覆盖从推理中间层采集、精度比对、训练过程监控到性能分析的全生命周期。通过合理使用这些工具，开发者可高效定位精度异常、性能瓶颈与运行时问题，显著提升模型在异构平台上的可靠性与稳定性。建议在模型开发、调优与部署阶段系统性地集成这些工具，构建可复现、可验证的调试流程。