msProbe工具安装指南

1. 安装说明

使用本工具前需要安装CANN，具体操作请参见《CANN 快速安装》安装昇腾NPU驱动和CANN软件（包含Toolkit和ops包），并配置环境变量。

如需单独升级本工具或使用最新版本，您可通过以下三种方式进行安装：在线安装、离线安装、源码安装。

2. 安装方式

2.1 在线安装

pip install mindstudio-probe

打印如下信息时，表示msProbe安装成功。

Successfully installed mindstudio-probe-{version}

2.2 离线安装

1. 请参见msProbe Release下载msProbe的whl软件包和对应数字签名文件（.sha256）。

   下载本软件即表示您同意《华为企业业务最终用户许可协议（EULA）》的条款和条件。

2. 验证whl包的完整性。

   1. 在whl包所在目录执行如下命令获取whl软件包的sha256校验码。

      sha256sum {name}.whl
      

      打印如下示例信息。

      {sha256} {name}.whl
      

   2. 用记事本打开数字签名文件查看sha256校验码。

   3. 比对两个文件的sha256校验码是否一致。

      若两个校验码一致，则表示下载了正确的软件包；若不一致，请不要使用该软件包，如需支持与服务，请在论坛求助或提交技术工单。

3. 安装whl包。

   pip install ./mindstudio_probe-{version}-py3-none-any.whl
   

   打印如下信息时，表示msProbe安装成功。

   Successfully installed mindstudio-probe-{version}
   

   若覆盖安装，请在命令行末尾添加 --force-reinstall 参数。

   以上提供的whl包链接不包含aclgraph_dump、atb_probe和nan_check等功能，如果需要使用这些功能，请参见源码安装下载源码编译whl包。

2.3 源码安装

前置说明

建议在源码安装前拉取Docker编译镜像，以确保编译环境一致性。

1. 拉取Docker镜像。

   docker pull swr.cn-north-4.myhuaweicloud.com/mindstudio-image/mindstudio-build:26.1.0-20260610
   

2. 启动容器。

   docker run -it --name msprobe-compile \
   --network host \
   swr.cn-north-4.myhuaweicloud.com/mindstudio-image/mindstudio-build:26.1.0-20260610 \
   /bin/bash
   

功能说明

通过build.py脚本编译msProbe工具的whl软件包。

命令格式

# 完整构建命令
python3 build.py [local] [-v <version>] [-e include-mod=<include_mode>] [-e no-check=true|false]

参数说明

参数	可选/必选	说明
local	可选	本地构建，即复用本地已有依赖，不主动下载第三方依赖
-v / --version	可选	指定构建版本号，默认从pyproject.toml读取。
-e / --extra	可选	额外构建选项，KEY=VALUE格式，可多次指定。支持的KEY： • include-mod：指定可选模块，可取值：  - tb_graph_ascend：表示在编译whl包时加入模型分级可视化插件。模型分级可视化构建相关依赖和推荐版本为Node.js v20.19.3、npm v10.8.2。模型分级可视化插件的详细依赖及功能使用说明请参见PyTorch场景分级可视化构图比对或MindSpore场景分级可视化构图比对。  - trend_analyzer：表示在编译whl包时加入趋势可视化插件。趋势可视化构建相关依赖和推荐版本为Node.js v20.19.3、npm v10.8.2。趋势可视化插件的功能说明请参见趋势可视化。  - atb_probe：表示在编译whl包时加入atb_probe模块。atb_probe模块用于ATB推理场景下的数据采集。  - aclgraph_dump：表示在编译whl包时加入aclgraph_dump模块，用于在aclgraph场景通过acl_save保存.pt文件。编译环境需要额外依赖torch和TorchNPU。  - nan_check：表示在编译whl包时加入nan_check模块，用于在nan_check场景下做寄存器溢出状态监测。  - xor_checksum：表示在编译whl包时加入XOR校验加速算子，用于PyTorch场景下summary_mode配置为xor时加速校验值采集，可带来数倍性能提升。编译环境需要额外依赖torch和TorchNPU。 默认未配置该参数，表示编译基础工具包。 指定多个模块时，模块间以","连接，例如tb_graph_ascend,trend_analyzer。 指定atb_probe模块时，编译环境需具备git、curl、GCC 7.5或以上版本、CMake 3.19.3或以上版本等第三方依赖软件。 配置该参数生成的whl包，仅限编译时使用的Python版本和处理器架构可用。 • no-check：跳过证书校验，值为true或false。include-mod指定可选模块后，会下载所依赖的第三方库包，下载过程会进行证书校验，配置本参数可以跳过证书校验。

使用示例

• 安装基础工具包

  git clone https://gitcode.com/Ascend/msprobe.git
  cd msprobe
  
  pip install uv
  
  python3 build.py
  cd ./artifacts
  pip install ./mindstudio_probe*.whl
  

• 安装基础工具包（指定自定义版本）

  git clone https://gitcode.com/Ascend/msprobe.git
  cd msprobe
  
  pip install uv
  
  python3 build.py -v 26.0.0
  cd ./artifacts
  pip install ./mindstudio_probe-26.0.0*.whl
  

• 安装基础工具包和aclgraph_dump模块

  git clone https://gitcode.com/Ascend/msprobe.git
  cd msprobe
  
  pip install uv
  
  python3 build.py -e include-mod=aclgraph_dump -e no-check=true
  cd ./artifacts
  pip install ./mindstudio_probe*.whl
  

• 安装基础工具包和分级可视化插件

  git clone https://gitcode.com/Ascend/msprobe.git
  cd msprobe
  
  pip install uv
  
  python3 build.py -e include-mod=tb_graph_ascend -e no-check=true
  cd ./artifacts
  pip install ./mindstudio_probe*.whl
  

• 安装基础工具包和趋势可视化插件

  git clone https://gitcode.com/Ascend/msprobe.git
  cd msprobe
  
  pip install uv
  
  python3 build.py -e include-mod=trend_analyzer -e no-check=true
  cd ./artifacts
  pip install ./mindstudio_probe*.whl
  

• 安装基础工具包和分级可视化、趋势可视化插件

  git clone https://gitcode.com/Ascend/msprobe.git
  cd msprobe
  
  pip install uv
  
  python3 build.py -e include-mod=tb_graph_ascend,trend_analyzer -e no-check=true
  cd ./artifacts
  pip install ./mindstudio_probe*.whl
  

• 安装基础工具包和atb_probe模块

  git clone https://gitcode.com/Ascend/msprobe.git
  cd msprobe
  
  pip install uv
  
  python3 build.py -e include-mod=atb_probe -e no-check=true
  cd ./artifacts
  pip install ./mindstudio_probe*.whl
  

• 安装基础工具包和nan_check模块

  git clone https://gitcode.com/Ascend/msprobe.git
  cd msprobe
  
  pip install uv
  
  python3 build.py -e include-mod=nan_check -e no-check=true
  cd ./artifacts
  pip install ./mindstudio_probe*.whl
  

• 安装基础工具包和xor_checksum加速算子

  git clone https://gitcode.com/Ascend/msprobe.git
  cd msprobe
  
  pip install uv
  
  python3 build.py -e include-mod=xor_checksum
  cd ./artifacts
  pip install ./mindstudio_probe*.whl
  

输出说明

打印如下信息时，表示msProbe安装成功。

Successfully installed mindstudio-probe-{version}

3. 验证安装

安装完成后，执行以下命令验证工具是否安装成功：

pip show mindstudio-probe

若输出不报错，且能显示工具信息，则表明安装成功。

若 pip show mindstudio-probe 提示命令不存在，请确认当前终端使用的是安装 msProbe 的 Python 环境。

4. 卸载

执行如下命令卸载msProbe工具。

pip uninstall mindstudio-probe

打印如下信息时，表示msProbe卸载成功。

Successfully uninstalled mindstudio-probe-{version}

5. 升级

msProbe工具不支持直接升级，需要先完成卸载后再重新安装。

可通过pip show mindstudio-probe命令查看当前环境的版本信息，再选择需要升级的版本。升级版本时需要关注版本配套关系，请参见《版本说明》。

6. 附录

6.1 工具限制与注意事项

• 工具读写的所有路径，如config_path、dump_path等，只允许包含大小写字母、数字、下划线、斜杠、点和短横线。

• 出于安全性及权限最小化角度考虑，本工具不应使用root等高权限账户，建议使用普通用户权限安装执行。

• 使用本工具前请确保执行用户的umask值大于等于0027，否则可能会导致工具生成的精度数据文件和目录权限过大。

• 用户须自行遵循最小权限原则，如给工具输入的文件要求other用户不可写，在一些对安全要求更严格的功能场景下还需确保输入的文件group用户不可写。

• msProbe建议执行用户与安装用户保持一致，如果使用root执行，请自行关注root高权限触及的安全风险。

6.2 查看msProbe工具信息

pip show mindstudio-probe

示例如下：

Name: mindstudio-probe
Version: 26.x.x
Summary: Ascend MindStudio Probe Utils
Home-page: https://gitcode.com/Ascend/MindStudio-Probe
Author: 
Author-email: Ascend Team <pmail_mindstudio@xx.com>
License-Expression: MulanPSL-2.0
Location: /home/xxx/miniconda3/envs/xxx/lib/python3.x/site-packages/
Requires: einops, matplotlib, numpy, openpyxl, pandas, psutil, pytz, pyyaml, rich, skl2onnx, tensorboard, tqdm, wheel
Required-by: 

6.3 Ascend生态链接

6.3.1 安装TorchNPU

请参见Ascend for PyTorch。

6.3.2 安装MindSpeed LLM

请参见MindSpeed LLM。