快速开始

MindFormers套件对外提供两种使用和开发形式，为开发者提供灵活且简洁的使用方式和高阶开发接口。

方式一：使用已有脚本启动

用户可以直接clone整个仓库，按照以下步骤即可运行套件中已支持的任意configs模型任务配置文件，方便用户快速进行使用和开发：

一、使用msrun方式启动（推荐，仅适用于配套MindSpore2.3以上版本）

目前msrun方式启动不支持指定device_id启动，msrun命令会按当前节点所有显卡顺序设置rank_id。

• 单机多卡

  # 单机多卡快速启动方式，默认8卡启动
  bash scripts/msrun_launcher.sh "run_mindformer.py \
   --config {CONFIG_PATH} \
   --run_mode {train/finetune/eval/predict}"
  
  # 单机多卡快速启动方式，仅设置使用卡数即可
  bash scripts/msrun_launcher.sh "run_mindformer.py \
   --config {CONFIG_PATH} \
   --run_mode {train/finetune/eval/predict}" WORKER_NUM
  
  # 单机多卡自定义启动方式
  bash scripts/msrun_launcher.sh "run_mindformer.py \
   --config {CONFIG_PATH} \
   --run_mode {train/finetune/eval/predict}" \
   WORKER_NUM MASTER_PORT LOG_DIR JOIN CLUSTER_TIME_OUT
  

  • 使用示例

    # 单机多卡快速启动方式，默认8卡启动
    bash scripts/msrun_launcher.sh "run_mindformer.py \
     --config path/to/xxx.yaml \
     --run_mode finetune"
    
    # 单机多卡快速启动方式
    bash scripts/msrun_launcher.sh "run_mindformer.py \
     --config path/to/xxx.yaml \
     --run_mode finetune" 8
    
    # 单机多卡自定义启动方式
    bash scripts/msrun_launcher.sh "run_mindformer.py \
     --config path/to/xxx.yaml \
     --run_mode finetune" \
     8 8118 output/msrun_log False 300
    

• 多机多卡

  多机多卡执行脚本进行分布式训练需要分别在不同节点运行脚本，并将参数MASTER_ADDR设置为主节点的ip地址， 所有节点设置的ip地址相同，不同节点之间仅参数NODE_RANK不同。

  # 多机多卡自定义启动方式
  bash scripts/msrun_launcher.sh "run_mindformer.py \
   --config {CONFIG_PATH} \
   --run_mode {train/finetune/eval/predict}" \
   WORKER_NUM LOCAL_WORKER MASTER_ADDR MASTER_PORT NODE_RANK LOG_DIR JOIN CLUSTER_TIME_OUT
  

  • 使用示例

    # 节点0，节点ip为192.168.1.1，作为主节点，总共8卡且每个节点4卡
    bash scripts/msrun_launcher.sh "run_mindformer.py \
     --config {CONFIG_PATH} \
     --run_mode {train/finetune/eval/predict}" \
     8 4 192.168.1.1 8118 0 output/msrun_log False 300
    
    # 节点1，节点ip为192.168.1.2，节点0与节点1启动命令仅参数NODE_RANK不同
    bash scripts/msrun_launcher.sh "run_mindformer.py \
     --config {CONFIG_PATH} \
     --run_mode {train/finetune/eval/predict}" \
     8 4 192.168.1.1 8118 1 output/msrun_log False 300
    

• 参数说明

  参数	单机是否必选	多机是否必选	默认值	说明
  WORKER_NUM	√	√	8	所有节点中使用计算卡的总数
  LOCAL_WORKER	×	√	8	当前节点中使用计算卡的数量
  MASTER_ADDR	×	√	127.0.0.1	指定分布式启动主节点的ip
  MASTER_PORT	×	√	8118	指定分布式启动绑定的端口号
  NODE_RANK	×	√	0	指定当前节点的rank id
  LOG_DIR	×	√	output/msrun_log	日志输出路径，若不存在则递归创建
  JOIN	×	√	False	是否等待所有分布式进程退出
  CLUSTER_TIME_OUT	×	√	600	分布式启动的等待时间，单位为秒

二、使用rank table或动态组网方式启动

• 准备工作

  • step1：克隆mindformers仓库。

    git clone -b dev https://gitee.com/mindspore/mindformers.git
    cd mindformers
    

  • step2: 准备相应任务的数据集，请参考docs目录下各模型的README.md文档准备相应数据集。

  • step3：修改配置文件configs/{model_name}/run_{model_name}_***.yaml中数据集路径。

  • step4：如果要使用分布式训练，则需提前生成RANK_TABLE_FILE。 注意：不支持在镜像容器中执行该命令，请在容器外执行。

    # 不包含8本身，生成0~7卡的hccl json文件
    python mindformers/tools/hccl_tools.py --device_num [0,8)
    

• 单卡启动：统一接口启动，根据模型的config配置，完成任意模型的单卡训练、微调、评估、推理流程。

  # 训练启动，run_mode支持train、finetune、eval、predict四个关键字，以分别完成模型训练、评估、推理功能，默认使用配置文件中的run_mode
  python run_mindformer.py --config {CONFIG_PATH} --run_mode {train/finetune/eval/predict}
  

• 多卡启动：scripts脚本启动，根据模型的config配置，完成任意模型的单卡/多卡训练、微调、评估、推理流程。

  • 使用 rank table方式启动

    # 8卡分布式运行， DEVICE_RANGE = [0,8), 不包含8本身
    cd scripts
    bash run_distribute.sh RANK_TABLE_FILE CONFIG_PATH DEVICE_RANGE RUN_MODE
    

  • 使用动态组网方式启动

    # 8卡分布式运行
    启动前的准备:
    1. 使用hostname命令将每台服务器hostname设置为各自的ip:  hostname [host ip], 如果在docker内需求设置为docker内部ip,同时保证各个服务器之间docker网络互通
    2. 设置环境变量: export SERVER_ID=0; export SERVER_NUM=1; export PER_DEVICE_NUMS=8; export MS_SCHED_HOST=[HOST IP]; export MS_SCHED_PORT=[PORT]
    cd scripts
    # SERVER_ID为当前服务器序号，SERVER_NUM为服务器的总数，PER_DEVICE_NUMS为每台服务器使用的卡数默认值为8，MS_SCHED_HOST为调度节点的ip，MS_SCHED_PORT为通信端口
    bash run_distribute_ps_auto.sh CONFIG_PATH RUN_MODE
    

• 常用参数说明

  RANK_TABLE_FILE: 由mindformers/tools/hccl_tools.py生成的分布式json文件
  CONFIG_PATH: 为configs文件夹下面的{model_name}/run_*.yaml配置文件
  DEVICE_ID: 为设备卡，范围为0~7
  DEVICE_RANGE: 为单机分布式卡的范围, 如[0,8]为8卡分布式，不包含8本身
  RUN_MODE: 为任务运行状态，支持关键字 train\finetune\eval\predict\export
  

方式二：调用API启动

详细高阶API使用教程请参考：MindFormers大模型使用教程

• 准备工作

  • step 1：安装mindformers

    具体安装请参考第二章。

  • step2: 准备数据

    准备相应任务的数据集，请参考docs目录下各模型的README.md文档准备相应数据集。

• Trainer 快速入门

  用户可以通过以上方式安装mindformers库，然后利用Trainer高阶接口执行模型任务的训练、微调、评估、推理功能。

  • Trainer 训练/微调启动

    用户可使用Trainer.train或者Trainer.finetune接口完成模型的训练/微调/断点续训。

    import mindspore; mindspore.set_context(mode=0, device_id=0)
    from mindformers import Trainer
    
    cls_trainer = Trainer(task='image_classification', # 已支持的任务名
                          model='vit_base_p16', # 已支持的模型名
                          train_dataset="/data/imageNet-1k/train", # 传入标准的训练数据集路径，默认支持ImageNet数据集格式
                          eval_dataset="/data/imageNet-1k/val") # 传入标准的评估数据集路径，默认支持ImageNet数据集格式
    # Example 1： 开启训练复现流程
    cls_trainer.train()
    # Example 2： 加载集成的mae权重，开启微调流程
    cls_trainer.finetune(finetune_checkpoint='mae_vit_base_p16')
    # Example 3： 开启断点续训功能
    cls_trainer.train(train_checkpoint=True, resume_training=True)
    

  • Trainer 评估启动

    用户可使用Trainer.evaluate接口完成模型的评估流程。

    import mindspore; mindspore.set_context(mode=0, device_id=0)
    from mindformers import Trainer
    
    cls_trainer = Trainer(task='image_classification', # 已支持的任务名
                          model='vit_base_p16', # 已支持的模型名
                          eval_dataset="/data/imageNet-1k/val") # 传入标准的评估数据集路径，默认支持ImageNet数据集格式
    # Example 1： 开启评估已集成模型权重的复现流程
    cls_trainer.evaluate()
    # Example 2： 开启评估训练得到的最后一个权重
    cls_trainer.evaluate(eval_checkpoint=True)
    # Example 3： 开启评估指定的模型权重
    cls_trainer.evaluate(eval_checkpoint='./output/checkpoint/rank_0/mindformers.ckpt')
    

    结果打印示例(已集成的vit_base_p16模型权重评估分数)：

    Top1 Accuracy=0.8317
    

  • Trainer推理启动

    用户可使用Trainer.predict接口完成模型的推理流程。

    import mindspore; mindspore.set_context(mode=0, device_id=0)
    from mindformers import Trainer
    
    cls_trainer = Trainer(task='image_classification', # 已支持的任务名
                          model='vit_base_p16') # 已支持的模型名
    input_data = './cat.png' # 一张猫的图片
    # Example 1： 指定输入的数据完成模型推理
    predict_result_d = cls_trainer.predict(input_data=input_data)
    # Example 2： 开启推理（自动加载训练得到的最后一个权重）
    predict_result_b = cls_trainer.predict(input_data=input_data, predict_checkpoint=True)
    # Example 3： 加载指定的权重以完成推理
    predict_result_c = cls_trainer.predict(input_data=input_data, predict_checkpoint='./output/checkpoint/rank_0/mindformers.ckpt')
    print(predict_result_d)
    

    结果打印示例(已集成的vit_base_p16模型权重推理结果)：

    {‘label’: 'cat', score: 0.99}
    

• pipeline 快速入门

  MindFormers套件为用户提供了已集成模型的pipeline推理接口，方便用户体验大模型推理服务。

  pipeline使用样例如下：

  # 以gpt2 small为例
  import mindspore; mindspore.set_context(mode=0, device_id=0)
  from mindformers.pipeline import pipeline
  
  pipeline_task = pipeline(task="text_generation", model="gpt2")
  pipeline_result = pipeline_task("An increasing sequence: one,", do_sample=False, max_length=20)
  print(pipeline_result)
  

  结果打印示例(已集成的gpt2模型权重推理结果)：

  [{'text_generation_text': ['An increasing sequence: one, two, three, four, five, six, seven, eight,']}]
  

• AutoClass 快速入门

  MindFormers套件为用户提供了高阶AutoClass类，包含AutoConfig、AutoModel、AutoProcessor、AutoTokenizer四类，方便开发者进行调用。

  • AutoConfig获取已支持的任意模型配置

    from mindformers import AutoConfig
    
    # 获取gpt2的模型配置
    gpt2_config = AutoConfig.from_pretrained('gpt2')
    # 获取vit_base_p16的模型配置
    vit_base_p16_config = AutoConfig.from_pretrained('vit_base_p16')
    

  • AutoModel获取已支持的网络模型

    from mindformers import AutoModel
    
    # 利用from_pretrained功能实现模型的实例化（默认加载对应权重）
    gpt2 = AutoModel.from_pretrained('gpt2')
    # 利用from_config功能实现模型的实例化（默认加载对应权重）
    gpt2_config = AutoConfig.from_pretrained('gpt2')
    gpt2 = AutoModel.from_config(gpt2_config)
    # 利用save_pretrained功能保存模型对应配置
    gpt2.save_pretrained('./gpt2', save_name='gpt2')
    

  • AutoProcessor获取已支持的预处理方法

    from mindformers import AutoProcessor
    
    # 通过模型名关键字获取对应模型预处理过程（实例化gpt2的预处理过程，通常用于Trainer/pipeline推理入参）
    gpt2_processor_a = AutoProcessor.from_pretrained('gpt2')
    # 通过yaml文件获取相应的预处理过程
    gpt2_processor_b = AutoProcessor.from_pretrained('configs/gpt2/run_gpt2.yaml')
    

  • AutoTokenizer获取已支持的tokenizer方法

    from mindformers import AutoTokenizer
    # 通过模型名关键字获取对应模型预处理过程（实例化gpt2的tokenizer，通常用于Trainer/pipeline推理入参）
    gpt2_tokenizer = AutoTokenizer.from_pretrained('gpt2')