profiler/msprof_analyze/precheck/README.md · Ascend/mstt

# 预检工具用户指南

欢迎使用预检工具！本指南将详细介绍该工具的功能、使用方法以及内部实现原理，帮助您快速上手并充分利用其性能分析能力。

## 目录
- [1. 概述](#1-概述)
- [2. 安装和卸载](#2-安装和卸载)
- [3. 预检工具使用](#3-预检工具使用)
  - [3.1 使用限制](#31-使用限制)
  - [3.2 接口参数](#32-接口参数)
  - [3.3 使用场景](#33-使用场景)
  - [3.4 使用方法](#34-使用方法)

## 1. 概述

预检工具是一个用于分布式训练/推理任务的环境分析工具，可以快速检测并定位到环境变量、慢卡、慢链路等与模型无关的软硬件环境问题。

预检工具作为辅助检测工具，能够对线上环境进行初步分析和检查，排除常见的软硬件问题，避免用户在实际业务执行阶段因为软硬件问题出现性能、精度问题甚至中断业务。

## 2. 安装和卸载
### 源代码编译安装
1. 安装依赖。

```bash
   pip3 install wheel
   ```

2. 下载源码。

```bash
   git clone https://gitee.com/ascend/mstt.git
   ```

3. 切换分支。

```bash
   cd mstt/profiler/msprof_analyze
   git checkout poc-precheck
   ```

4. 编译whl包。

```bash
   pip3 install -r requirements.txt && python3 setup.py bdist_wheel
   ```

以上命令执行完成后在mstt/profiler/msprof_analyze/dist目录下生成性能工具whl安装包`msprof_analyze-{version}-py3-none-any.whl`。

5. 安装。

执行如下命令进行性能工具安装。

```bash
   cd dist
   pip3 install ./msprof_analyze-{version}-py3-none-any.whl
   ```
   如果要更新工具，请执行以下命令
   ```bash
   cd dist
   pip3 install ./msprof_analyze-{version}-py3-none-any.whl --force-reinstall --no-deps
   ```

### 卸载
   ```bash
   pip3 uninstall msprof-analyze
   ```

## 3. 预检工具使用

## 3.1 使用限制
需要有torch环境

## 3.2 接口参数

```bash
msprof-analyze precheck env [OPTION]
```
OPTION:

| 参数名                            | 类型   | 必需 | 默认值         | 说明                                                               |
|--------------------------------|------|---|-------------|------------------------------------------------------------------|
| --nproc_per_node               | int  | Y | -           | 每进程节点数                                                           |
| --nnodes                       | int  | Y | -           | 总结点数                                                             |
| --node_rank                    | int  | Y | -           | 当前节点序号(0到nnodes-1)                                               |
| --master_addr                  | int  | N | "localhost" | 主节点IP地址                                                          |
| --master_port                  | int  | N | 6000        | 主节点通信端口                                                          |
| --tensor-model-parallel-size   | int  | N | 1           | tensor 并行数                                                       |
| --pipeline-model-parallel-size | int  | N | 1           | pipeline 并行数                                                     |
| --context-parallel-size        | int  | N | 1           | context 并行数                                                      |
| --expert-model-parallel-size   | int  | N | 1           | expert 并行数                                                       |
| --output                       | str  | N | "./output"  | 结果输出路径                                                           |
| --check-type                   | str  | N | "all"       | 检测项，通过"\|"分隔不同检测项，例如--check-type="cpu\|npu"，将会执行cpu快慢检测和npu快慢卡检测 |
| --no-shared-storage            | bool | N | False       | 是否共享存储，默认共享存储                                                    |

## 3.3 使用场景

| --check-type取值  | 检测项   | 说明                                                                                                                               |
|-----------------|-------|----------------------------------------------------------------------------------------------------------------------------------|
| "env_variable"  | 环境变量检测 | 检测是否使用合适的环境变量                                                                                                                    |
| "python_lib"    | 三方库检测   | 检测环境中的三方库是否配套版本，将GPU调用的三方库导入mstt\profiler\msprof_analyze\precheck\env_check\target_config\target_requirements.txt中，可实现与GPU版本比对功能 |
| "cpu"           | cpu快慢检测   | 在CPU中运行matmul计算，集群场景检测CPU性能是否一致                                                                                                  |
| "npu"           | npu快慢卡检测   | 在NPU侧运行matmul计算，检测是否有快慢卡                                                                                                         |
| "communication" | 通信链路检测   | p2p运行通信任务，检测卡间通信带宽，以及快慢链路                                                                                                        |
| "io"            | 存储io检测   | 模拟日志记录和dataloader数据读取，对大小数据的读写进行压测，通过快慢，判断IO瓶颈                                                                                   |
| "all"           | 检测所有项目   | 检测所有项目                                                                                                                           |

## 3.4 使用方法

### 方法1: 调用msprof-analyze

将指令嵌入模型运行脚本中
```bash
#!/bin/bash
export CUDA_DEVICE_MAX_CONNECTIONS=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export HCCL_CONNECT_TIMEOUT=3600

NPUS_PER_NODE=16
MASTER_ADDR=localhost #主节点IP
MASTER_PORT=6000
NNODES=32
NODE_RANK=0
WORLD_SIZE=$(($NPUS_PER_NODE*$NNODES))

TP=2
PP=8
VPP=2
EP=32
CP=1
CP_TYPE='ulysses_cp_algo'
NUM_LAYERS=64
SEQ_LEN=4096
MBS=1
GBS=3840

DISTRIBUTED_ARGS="
    --nproc_per_node $NPUS_PER_NODE \
    --nnodes $NNODES \
    --node_rank $NODE_RANK \
    --master_addr $MASTER_ADDR \
    --master_port $MASTER_PORT
"

MLA_ARGS="
    --multi-head-latent-attention \
    --qk-rope-head-dim 64 \
    --qk-nope-head-dim 128 \
    --q-lora-rank 1536 \
    --kv-lora-rank 512 \
    --v-head-dim 128 \
    --qk-layernorm \
    --mla-mm-split \
    --mla-fa-without-pad \
"

MOE_ARGS="
    --moe-grouped-gemm \
    --moe-permutation-async-comm \
    --use-fused-moe-token-permute-and-unpermute \
"

MTP_ARGS="
    --num-nextn-predict-layers 1 \
    --share-mtp-embedding-and-output-weight \
    --recompute-mtp-norm \
"

ROPE_ARGS="
    --rope-scaling-beta-fast 32 \
    --rope-scaling-beta-slow 1 \
"

GPT_ARGS="
    --no-shared-storage \
    --use-distributed-optimizer \
    --reuse-fp32-param \
    --use-flash-attn \
    --use-mcore-models \
    --tensor-model-parallel-size ${TP} \
    --pipeline-model-parallel-size ${PP} \
    --num-layers-per-virtual-pipeline-stage ${VPP} \
    --expert-model-parallel-size ${EP} \
    --sequence-parallel \
    --context-parallel-size ${CP} \
    --context-parallel-algo  ${CP_TYPE} \
    --num-layers ${NUM_LAYERS} \
"

# 添加如下指令
msprof-analyze precheck env \
    $DISTRIBUTED_ARGS \
    --tensor-model-parallel-size ${TP} \
    --pipeline-model-parallel-size ${PP} \
    --expert-model-parallel-size ${EP} \
    --context-parallel-size ${CP} \
    --no-shared-storage \
    --output "./output" \
    --check-type="all"

#python -m torch.distributed.launch $DISTRIBUTED_ARGS pretrain_gpt.py \
#    $GPT_ARGS \
#    $DATA_ARGS \
#    $OUTPUT_ARGS \
#    $MLA_ARGS \
#    $ROPE_ARGS \
#    $MOE_ARGS \
#    $MTP_ARGS \
#    --distributed-backend nccl \
#    --save $CKPT_SAVE_DIR \
#    --load $CKPT_LOAD_DIR \
#    | tee logs/pretrain_deepseek3_671b_4k_A3_ptd.log
```

### 方法2: python直调

可将mstt代码置于当前目录中，模型运行脚本中嵌入python指令
```bash
#!/bin/bash
export CUDA_DEVICE_MAX_CONNECTIONS=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export HCCL_CONNECT_TIMEOUT=3600

NPUS_PER_NODE=16
MASTER_ADDR=localhost #主节点IP
MASTER_PORT=6000
NNODES=32
NODE_RANK=0
WORLD_SIZE=$(($NPUS_PER_NODE*$NNODES))

TP=2
PP=8
VPP=2
EP=32
CP=1
CP_TYPE='ulysses_cp_algo'
NUM_LAYERS=64
SEQ_LEN=4096
MBS=1
GBS=3840

DISTRIBUTED_ARGS="
    --nproc_per_node $NPUS_PER_NODE \
    --nnodes $NNODES \
    --node_rank $NODE_RANK \
    --master_addr $MASTER_ADDR \
    --master_port $MASTER_PORT
"

MOE_ARGS="
    --moe-grouped-gemm \
    --moe-permutation-async-comm \
    --use-fused-moe-token-permute-and-unpermute \
"

MTP_ARGS="
    --num-nextn-predict-layers 1 \
    --share-mtp-embedding-and-output-weight \
    --recompute-mtp-norm \
"

ROPE_ARGS="
    --rope-scaling-beta-fast 32 \
    --rope-scaling-beta-slow 1 \
"

# 添加如下指令
CUR_DIR=$(dirname $(readlink -f $0))
cd $CUR_DIR/mstt/profiler
torchrun $DISTRIBUTED_ARGS $CUR_DIR/mstt/profiler/msprof_analyze/precheck/precheck.py \
    $GPT_ARGS \
    $MLA_ARGS \
    $ROPE_ARGS \
    $MOE_ARGS \
    $MTP_ARGS \
    --output $CUR_DIR \
    --check-type="all"

python $CUR_DIR/mstt/profiler/msprof_analyze/precheck/precheck_analyze.py \
    $DISTRIBUTED_ARGS \
    $GPT_ARGS \
    $MLA_ARGS \
    $ROPE_ARGS \
    $MOE_ARGS \
    $MTP_ARGS \
    --output $CUR_DIR \
    --check-type="all"

Ascend/mstt
暂停

简介

发行版 (2)

贡献者

语言

近期动态

Ascend/mstt暂停 .gitee-modal { width: 500px !important; }

简介

发行版 (2)

开源评估指数源自 OSS-Compass 评估体系，评估体系围绕以下三个维度对项目展开评估：

贡献者

语言

近期动态

搜索帮助

Ascend/mstt
暂停