# ClusterExec

**Repository Path**: hemiuhui/cluster-exec

## Basic Information

- **Project Name**: ClusterExec
- **Description**: 通过简单的适配，拉起任意集群的docker训练任务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2024-03-07
- **Last Updated**: 2024-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ClusterExec--极简的集群任务管理工具

# 介绍
大模型时代，模型动辄使用百卡、千卡、甚至万卡进行训练，如何在这些机器上管理训练任务，以做到任务快速拉起、任务进程监控与任务快速结束，是值得研究的主题。

本工具旨在方便用户进行多机任务管理：用户使用本工具，通过对模型启动脚本进行简单的适配，能够一键拉起集群任务；支持裸机与docker场景。

## 迭代计划

1. 易用性优化：以环境变量的形式传入hostfile并解析，简化适配代码

2. 集群环境检查：支持基本环境检查，包括驱动、cann、torch版本，光模块、网卡状态等

3. 实用脚本内置：如单算子连通性脚本内置

4. 易用性优化2：通过实时监听返回训练日志，用户不用自己自己写日志重定向逻辑

5. 日志解析工具：通过正则、匹配对比等方式快速识别出众多集群日志中出现异常的日志。

   ...


# 安装教程

1. 下载本仓库至集群共享磁盘：

   ```shell
   git clone https://gitee.com/hemiuhui/cluster-exec.git
   ```

2. 在使用本工具的机器（一般是master节点）上安装sshpass

   ```
   yum install sshpass
   apt-get xxx
   ```

   

# 使用前提与思路

1. 集群使用共享磁盘，每台机器上的共享盘目录相同；
2. 集群每台机器上任务启动命令相同：
   - 每台机器进入环境命令相同：如果是裸机conda环境，需要名称相同；如果是docker容器，要求容器名称相同，容器中如果有conda环境，也要求名称相同；
   - 每台机器拉起训练脚本的命令相同，例如都是"cd /home/model/; bash examples/start_to_train.sh --para1 xx --para2 xx"
   - 推荐模型代码放在共享磁盘中，或者复制到各个机器本地相同的目录。

**总体使用思路如下：**

1. 在共享盘目录下载本工具

2. 在config下面配置集群ip（`config/hostfile`文件）以及认证信息（`config/authority`）

3. 在项目代码根目录，执行`bash ./ssh2all_and_exec.sh --exec_file="path/to/your/scripts.sh"`

   工具会默认后台拉起进程，使用ssh进入到`config/hostfile`中的每台机器上，并执行--exec_file传入的脚本内容。

# 快速开始

本节给出ModelLink，llama2 70B脚本4机集群、docker容器训练为例，展示如下内容：

- 使用本工具一键拉起训练任务时，如何进行训练脚本适配（假设4机集群的ip为192.168.xxx.22~192.168.xxx.25）
- 完成适配后，如何一键拉起训练任务



## 任务拉起

### 步骤1：安装工具

下载本仓库至集群共享目录（参考安装教程）

### 步骤2：配置登录信息与机器IP

- 配置登录信息：修改`config/authority` ，写入集群机器的登录密码，默认每台机器密码一致

- 配置机器IP：默认使用`config/hostfile`, 写入所有机器内网`ip`：

  ```
  192.168.xxx.22
  192.168.xxx.23
  192.168.xxx.24
  192.168.xxx.25
  ```

  规则：第一行为master节点，一行一个ip，行末没有多余空行；RANK依次递增
  
  用户也可以传入自己的`hostfile`，密码同样配置在`config/authority`中

### 步骤3：模型启动脚本适配

①适配`hostfile`传参：在模型脚本中添加`--hostfile`参数传入逻辑

```shell
for para in $*
do
    if [[ $para == --hostfile* ]];then
        HOSTFILE=`echo ${para#*=}`
    fi
done
```

②适配分布式参数获取：通过解析`hostfile`文件，拉起任务；下面是参考逻辑

```shell
MASTER_ADDR=$(head -n1 $HOSTFILE | awk '{print $1;}')  # 获取hostfile第一行为masteraddr
MASTER_PORT=6006
NODE_ADDR=`hostname -I | awk '{for(i=1;i<=NF;i++)print $i}' | grep ${MASTER_ADDR%.*}. | awk -F " " '{print$1}'`  # 获取本机IP
NODE_RANK=$(awk '{ranks[$1]=(FNR-1);}END{print ranks["'$NODE_ADDR'"];}' $HOSTFILE)
NNODES=$(cat $HOSTFILE | wc -l)
NPUS_PER_NODE=8
WORLD_SIZE=$(($NPUS_PER_NODE*$NNODES))
```

③适配日志保存逻辑：关注最后一行，日志重定向逻辑，重定向至共享目录

```shell
 nohup python  python -m torch.distributed.launch $DISTRIBUTED_ARGS \
       pretrain_llama.py \
       --DDP-impl local \
       --use-flash-attn \
       --sequence-parallel \
       --mlp-layer-fusion \
       --use-fused-rmsnorm \
       ...
       -bf16 >> ${共享盘目录}/logs/train_128nodes_${NODE_RANK}_20000iters.log 2>&1 &
```

### 步骤4：启动多机训练（docker场景）

①**批量启动容器**:

- 配置`config/docker.cfg`文件

  ```shell
  container_name="llama2_70b_loss"  
  ...
  ```

  其中`container_name`为容器名称，`begin_train_cmd`为进入容器后运行的命令，一般包含启动前准备与拉起启动脚本的命令。

- 一键启动所有集群上的容器：

  ```shell
  bash ./ssh2all_and_exec.sh  --exec_file=./task/docker_run.sh

默认使用`config/hostfile`机器；也可以使用用户自己配置的`hostfile`，通过`--hostfile`传入，启动其中对应ip机器上的对应名称容器。

②**配置启动命令**：修改`docker.cfg`文件的`begin_train_cmd`参数，例如：

```shell
begin_train_cmd="
source ~/.bashrc;
conda activate llama2_70b;
source /usr/local/Ascend/ascend-toolkit/set_env.sh;
pkill -9 python;
pkill -9 torchrun;
cd /data/llama2_70b/ModelLink;
bash examples/llama2/pretrain_llama2_70B_ptd_8nodes_neimeng.sh --hostfile=/hpfs-data/1000/cluster-exec_lxz/cluster-exec/hostfile_cur;
"
```

③**一键拉起多机docker训练**：在本项目代码目录下执行：

```shell
bash ./ssh2all_and_exec.sh --exec_file=./task/docker_train.sh
```

默认使用`config/hostfile`机器；也可以使用用户自己配置的`hostfile`，通过`--hostfile`传入

`--exec_file`必须传入，不传入会报错



## 日志查看

执行后，项目代码根目录下会生成logs文件夹，包含命令执行返回的原始日志

如果用户想批量整合并查看日志，可以执行命令：

```shell
bash integr_log.sh ${日志文件夹名称}
```



# 使用说明

## 前置操作：配置登录信息与机器IP

- 配置登录信息：修改`config/authority` ，写入集群机器的登录密码，默认每台机器密码一致

- 配置机器IP：默认使用`config/hostfile`, 写入所有机器内网`ip`,如

  ```
  192.168.xxx.22
  192.168.xxx.23
  192.168.xxx.24
  192.168.xxx.25
  ```

  规则：第一行为master节点，一行一个ip，行末没有多余空行；RANK依次递增

  用户也可以传入自己的`hostfile`，密码同样配置在`config/authority`中

## 功能1：集群连通性测试

   ```shell
   bash ssh2all_and_exec.sh --exec_file=./task/test_connect.sh
   ```

## 功能2：集群网卡状态测试

```shell
bash ssh2all_and_exec.sh --exec_file=./task/check_npu_link.sh
```

## 敬请期待...