Uni-Core Tutorial 101

Uni-Core是dp内部广泛使用构建深度学习模型的框架，利用其可以快速地构建模型并开始训练，用户只需要关注数据处理，模型构建和损失函数定义即可。

目前dp内部基于Uni-Core构建的深度学习模型有：

Uni-Mol: https://github.com/dptech-corp/Uni-Mol
Uni-Fold: https://github.com/dptech-corp/Uni-Fold
Uni-MoF: https://github.com/dptech-corp/Uni-MOF

Uni-Core安装

安装可以有很多形式，这里说几种方法，可以自行选择。包括源码安装，wheel包安装，或者直接使用镜像。

源码安装

git clone https://github.com/dptech-corp/Uni-Core.git
cd Uni-Core
python setup.py install

从github链接安装

pip install git+https://github.com/dptech-corp/Uni-Core.git

从wheel包链接安装

ps: 此种方式需要找到对应的python版本，torch版本，cuda版本的wheel包，cu117表示cuda版本11.7, torch2.0.0表示pytorch版本2.0.0，cp310表示python 3.10。

wget https://github.com/dptech-corp/Uni-Core/releases/download/0.0.3/unicore-0.0.1+cu117torch2.0.0-cp310-cp310-linux_x86_64.whl
pip install unicore-0.0.1+cu117torch2.0.0-cp310-cp310-linux_x86_64.whl

从dockerhub拉取镜像

ps: dockerhub的tag同样也需要注意torch版本，cuda版本。

docker pull dptechnology/unicore:latest-pytorch2.0.1-cuda11.7-rdma

Uni-Core如何构建模型并训练

以仓库里examples下的bert为例子，如何在此框架下实现新场景的模型？

实现task模块并注册task

整体参考example/bert/task.py文件，但是需要实现__init__函数，setup_task函数，load_dataset函数，build_model函数。

1. __init__函数：初始化各种信息和操作，比如example加了token到idx的映射逻辑。
2. setup_task函数：辅助信息，用于接受args, kwargs，用户传进来的参数。
3. load_dataset函数：实现dataset的数据预处理信息，注意通过split标识位来区分train / valid / test (训练集/校验集/测试集)，通过self.dataset[split] = newdataset函数实现。注意newdataset的实现一定需要继承BaseWrapperDataset类，具体可以参考其他dataset实现。(注意：一般sequence任务在一个batch内会pad成统一长度。)
4. build_model函数，基本不需要改动。

实现model模块并注册model

整体参考example/bert/model.py文件

1. 实现add_args 用于获取命令传递的参数，用法和argparse一致。
2. 实现__init__函数，此处定义模型的layer和权重初始化相关。
3. 实现forward函数，定义NN graph。具体的输入是有loss函数调用model的时候对应的。

实现loss模块并注册loss

unicore自身自带一些loss函数，可以参考文件unicore/losses/*文件，已经实现有cross_entropy和masked_lm。 也可以通过继承UnicoreLoss实现自己loss函数。

1. 实现__init__函数，初始化相关信息和数据。
2. 实现forward模块，注意输入和输出需要规范一下。
3. def forward(self, model, sample, reduce=True) model是之前定义的model模块的实例，sample是task里定义的数据实例，使用方式需要和自己定义的内容保持一致。
4. return loss, sample_size, logging_output 需要返回3个内容，loss是forward之后计算出的损失函数值，sample_size是当前输入sample的数据样本规模，logging_output希望输出打印的内容（可自定义）。

运行构建的模型

[ -z "${MASTER_PORT}" ] && MASTER_PORT=10086
export NCCL_ASYNC_ERROR_HANDLING=1
export OMP_NUM_THREADS=1

# 配置gpu卡数。
[ -z "${n_gpu}" ] && n_gpu=$(nvidia-smi -L | wc -l)   

torchrun --standalone --nnodes=1 --nproc_per_node=$n_gpu
       --master_port=<span class="katex"><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8333em;vertical-align:-0.15em;"></span><span class="mord mathnormal" style="margin-right:0.10903em;">M</span><span class="mord mathnormal">A</span><span class="mord mathnormal" style="margin-right:0.05764em;">STE</span><span class="mord"><span class="mord mathnormal" style="margin-right:0.00773em;">R</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.3283em;"><span style="top:-2.55em;margin-left:-0.0077em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight" style="margin-right:0.13889em;">P</span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span></span><span class="mord mathnormal" style="margin-right:0.13889em;">ORT</span></span></span></span>(which unicore-train) 
       ./example_data  # 数据路径，
       --user-dir . \  # 用户自定义模块的目录，*注意不要导入错误*
       --train-subset train \  # 训练集合的名字
       --valid-subset valid \  # 校验集合的名字
       --num-workers 0 \  # worker数量
       --ddp-backend=c10d \
       --task bert \  # task为前面自定义的task, 记得需要注册
       --loss masked_lm \  # loss为前面自定义的loss模块, 记得需要注册
       --arch bert_base  \ # arch为在model里定义的架构信息
       --optimizer adam \ #优化器
       --adam-betas '(0.9, 0.98)' \
       --adam-eps 1e-6 \
       --clip-norm 1.0 \ #梯度裁剪
       --lr-scheduler polynomial_decay \ #lr 变化策略
       --lr 1e-4 \ # learning rate
       --warmup-updates 100 \ # warmup的步数
       --total-num-update 10000 \ # 总共的更新步数
       --batch-size 4 \ 一个iter使用的batch size
       --update-freq 1 \ backward的更新频次，total bs = batch_size * update_freq
       --seed 1 \ 随机种子，固定用于可复现
       --tensorboard-logdir ./tsb/ \ # tensorboar的地址
       --max-update 10000 \ # 最大更新步数
       --log-interval 100 \ # 日志打印频次
       --log-format simple \
       --save-interval-updates 5000 \ 每多少步保存一次模型
       --validate-interval-updates 5000 \ # 每多少步做一次validatian
       --keep-interval-updates 30 \
       --no-epoch-checkpoints  \
       --save-dir ./save

具体torch启动的脚本可以参考：（注意需要将环境替换成自己的参数）

单机版本：https://github.com/dptech-corp/Uni-Core/blob/main/examples/bert/train_bert_test.sh
多机版本：https://github.com/dptech-corp/Uni-Core/blob/main/examples/bert/train_bert_test_multi_node.sh

其他注意事项

1. 目前Uni-Core master的代码是使用torchrun的启动方式，如果遇到以下报错，请先确定自己的torch版本。

unicore-train: error: unrecognized arguments: --local-rank=0

2. Uni-Core和其他软件包一样，可以在自有环境安装，如果发现不需要编译cuda算子或者某些类型的卡不支持，可以加入--disable-cuda-ext的编译选项将其关闭。

python setup.py install --disable-cuda-ext

3. 如何自己编译符合需求的Uni-Core镜像

参考 https://github.com/dptech-corp/Uni-Core/blob/main/docker/rdma/Dockerfile 

base镜像可以从nvidia ngc找到对应的cuda cudnn版本:
    https://docs.nvidia.com/deeplearning/frameworks/pytorch-release-notes/
    https://catalog.ngc.nvidia.com/orgs/nvidia/containers/pytorch/tags