From e41f153f43c7b502e025b69bd7debcbf335f09f7 Mon Sep 17 00:00:00 2001
From: y30062407 <handsome0324@163.com>
Date: Fri, 16 Aug 2024 17:33:42 +0800
Subject: [PATCH 1/2] =?UTF-8?q?feat:=E5=A2=9E=E5=8A=A0=E6=9D=83=E9=87=8D?=
 =?UTF-8?q?=E8=BD=AC=E6=8D=A2=E6=96=87=E6=A1=A3-Lora=E6=9D=83=E9=87=8D?=
 =?UTF-8?q?=E5=90=88=E5=B9=B6=E6=A8=A1=E5=9D=97=E6=96=87=E6=A1=A3=E5=92=8C?=
 =?UTF-8?q?=E9=A2=84=E8=AE=AD=E7=BB=83=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../mindformers/function/weight_conversion.md |  62 ++++++
 .../mindformers/usage/pre_training.md         | 181 ++++++++++++++++++
 2 files changed, 243 insertions(+)

diff --git a/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md b/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md
index a2c2fe74fc..6c90780ff6 100644
--- a/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md
+++ b/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md
@@ -1,3 +1,65 @@
 # 权重转换功能
+# Lora权重合并
+## 概述
+
+LoRA（Low-Rank Adaptation）的基本原理是对原始模型的参数进行低秩重参数化。合并权重的核心过程是将 LoRA 分支的权重计算并叠加到对应的模型权重中。这一操作不会对推理结果产生任何影响，因此合并后的模型在推理时依然能够保持与原始模型一致的性能。
+
+有关 LoRA 的详细原理和实现，请参阅以下资源：
+
+- 论文: [LoRA: Low-Rank Adaptation of Large Language Models](https://arxiv.org/abs/2106.09685)
+- GitHub: [https://github.com/microsoft/LoRA](https://github.com/microsoft/LoRA)
+
+## 使用说明
+
+本教程将指导您如何将通过 LoRA（Low-Rank Adaptation）微调后的权重与原始模型的权重进行合并，生成可用于推理的完整模型权重文件。合并后的权重将使您能够在推理过程中直接利用 LoRA 的微调效果。若有其他需求，例如仅有 LoRA 权重或对权重进行进一步操作，您可以基于此方法自行调整脚本。
+
+```shell
+python mindformers/tools/transform_ckpt_lora.py \
+--src_ckpt_strategy src_strategy_path_or_dir \
+--src_ckpt_path_or_dir src_ckpt_path_or_dir \
+--dst_ckpt_dir dst_ckpt_dir \
+--prefix "checkpoint_" \
+--lora_scaling lora_alpha/lora_rank
+```
+
+### 参数说明
+
+- **src_ckpt_strategy**：源权重对应的分布式策略文件路径，通常在启动训练任务后默认保存在 `output/strategy/` 目录下。如果源权重为完整权重，则无需填写此参数；如果为分布式权重，需根据以下情况填写：
+  
+  - **源权重开启了流水线并行**：权重转换基于合并的策略文件，填写分布式策略文件夹路径。脚本会自动将文件夹内的所有 `ckpt_strategy_rank_x.ckpt` 文件合并，并在文件夹下生成 `merged_ckpt_strategy.ckpt`。如果已经存在 `merged_ckpt_strategy.ckpt`，可以直接填写该文件的路径。
+  - **源权重未开启流水线并行**：权重转换可基于任一策略文件，填写任意一个 `ckpt_strategy_rank_x.ckpt` 文件的路径即可。
+  
+  **注意**：如果策略文件夹下已存在 `merged_ckpt_strategy.ckpt` 且仍传入文件夹路径，脚本会首先删除旧的 `merged_ckpt_strategy.ckpt`，再合并生成新的 `merged_ckpt_strategy.ckpt` 以用于权重转换。因此，请确保该文件夹具有足够的写入权限，否则操作将报错。
+- **src_ckpt_path_or_dir**：源权重的路径。如果为分布式权重，请填写源权重所在文件夹的路径，源权重应按 `model_dir/rank_x/xxx.ckpt` 格式存放，并将文件夹路径填写为 `model_dir`。若源权重为完整权重，则填写完整权重的绝对路径。
+- **dst_ckpt_dir**：目标权重的保存路径，需为自定义的空文件夹路径。目标权重将按 `model_dir/rank_x/xxx.ckpt` 格式保存。
+- **prefix**：目标权重文件的命名前缀，默认值为 "checkpoint_"，即目标权重将按照 `model_dir/rank_x/checkpoint_x.ckpt` 格式保存。
+- **lora_scaling**：LoRA 权重的合并系数，默认为 `lora_alpha/lora_rank`，这两个参数即为 LoRA 模型配置时的参数，需自行计算。
+
+## 示例
+
+### 场景 1：完整的带 LoRA 的权重
+
+如果您拥有一个完整的带 LoRA 的权重文件，并希望将其转换为完整的原始权重，您可以按照以下方式填写参数（直接输入完整权重的路径）：
+
+```bash
+python mindformers/tools/transform_ckpt_lora.py \
+--src_ckpt_path_or_dir .../xxx/xxx.ckpt \
+--dst_ckpt_dir dst_ckpt_dir \
+--prefix "checkpoint_" \
+--lora_scaling lora_alpha/lora_rank
+```
+
+### 场景 2：带 LoRA 的分布式权重
+
+如果您拥有一个经过分布式切分的带 LoRA 的权重文件，并希望将其转换为完整的原始权重，您可以按照以下方式填写参数（需输入权重文件夹路径和分布式策略文件夹路径）：
+
+```bash
+python mindformers/tools/transform_ckpt_lora.py \
+--src_ckpt_strategy .../xxx/mindformers/output/strategy/ \
+--src_ckpt_path_or_dir .../xxx/model_dir \
+--dst_ckpt_dir dst_ckpt_dir \
+--prefix "checkpoint_" \
+--lora_scaling lora_alpha/lora_rank
+```
 
 [![查看源文件](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source.svg)](https://gitee.com/mindspore/docs/blob/master/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md)
\ No newline at end of file
diff --git a/docs/mindspore/source_zh_cn/mindformers/usage/pre_training.md b/docs/mindspore/source_zh_cn/mindformers/usage/pre_training.md
index 43e2f84adb..d6aaa3765c 100644
--- a/docs/mindspore/source_zh_cn/mindformers/usage/pre_training.md
+++ b/docs/mindspore/source_zh_cn/mindformers/usage/pre_training.md
@@ -1,3 +1,184 @@
 # 预训练
+## 概述
+
+预训练是指在大规模未标注数据上训练模型，使其能够捕捉语言的广泛特性。通过预训练，模型可以学习到词汇、句法和语义等方面的知识，这些知识在下游任务中可以被微调，以实现特定任务的优化。
+
+## MindFormers的预训练目标
+
+MindFormers框架的预训练目标是帮助开发者快速、便捷地构建和训练基于Transformer架构的预训练模型。它通过优化的训练流程、丰富的模型库和高效的分布式训练支持，帮助用户在各种NLP任务中实现高效的模型开发。
+
+## 数据集
+
+### 数据集下载
+
+MindFormers提供**Wiki103**作为[预训练](#预训练)数据集，**alpaca**作为[微调](#微调)数据集。
+
+| 数据集名称   |            适用模型            |   适用阶段   |                                      下载链接                                       |
+|:--------|:--------------------------:|:--------:|:-------------------------------------------------------------------------------:|
+| Wikitext2 | llama2-7b <br />llama2-13b <br /> llama2-70b | Pretrain |    [Link](https://gitee.com/link?target=https%3A%2F%2Fascend-repo-modelzoo.obs.cn-east-2.myhuaweicloud.com%2FMindFormers%2Fdataset%2Fwikitext-2%2Fwikitext-2-v1.zip)     |
+| alpaca  |  llama2-7b <br />llama2-13b <br /> llama2-70b | Finetune | [Link](https://github.com/tatsu-lab/stanford_alpaca/blob/main/alpaca_data.json) |
+
+### 数据预处理
+
+- **Wiki103 数据预处理**
+  
+  使用`research/llama3/llama_preprocess.py`对下载后的数据进行预处理，并生成Mindrecord数据。
+  
+  ```shell
+  python llama_preprocess.py \
+   --dataset_type wiki \
+   --input_glob /{path}/wiki.train.tokens \
+   --model_file /{path}/tokenizer.model \
+   --seq_length 8192 \
+   --output_file /{path}/wiki8192.mindrecord
+  
+  # 参数说明
+  dataset_type: 预处理数据类型
+  input_glob:   输入下载后wiki.train.tokens的文件路径
+  model_file:   模型tokenizer.model文件路径
+  seq_length:   输出数据的序列长度
+  output_file:  输出文件的保存路径
+  ```
+- **alpaca 数据预处理**
+  
+  1. 执行`mindformers/tools/dataset_preprocess/llama/alpaca_converter.py`，使用fastchat工具添加prompts模板，将原始数据集转换为多轮对话格式。
+  
+  ```shell
+   python alpaca_converter.py \
+     --data_path /{path}/alpaca_data.json \
+     --output_path /{path}/alpaca-data-conversation.json
+  
+   # 参数说明
+   data_path:   输入下载的文件路径
+   output_path: 输出文件的保存路径
+  ```
+  
+  2. 执行`research/llama3/llama_preprocess.py`，生成Mindrecord数据，将带有prompt模板的数据转换为mindrecord格式。
+  
+  ```shell
+   # 此工具依赖fschat工具包解析prompt模板, 请提前安装fschat >= 0.2.13 python = 3.9
+   python llama_preprocess.py \
+     --dataset_type qa \
+     --input_glob /{path}/alpaca-data-conversation.json \
+     --model_file /{path}/tokenizer.model \
+     --seq_length 8192 \
+     --output_file /{path}/alpaca-fastchat8192.mindrecord
+  
+   # 参数说明
+   dataset_type: 预处理数据类型
+   input_glob:   转换后的alpaca的文件路径
+   model_file:   模型tokenizer.model文件路径
+   seq_length:   输出数据的序列长度
+   output_file:  输出文件的保存路径
+  ```
+
+> 数据处理时候注意bos，eos，pad等特殊`ids`要和配置文件中`model_config`里保持一致。
+
+## 单机单卡训练
+
+以下内容将以Llama2-7b为例，展示如何在单卡的配置下进行训练。
+
+### 启动训练
+
+```
+# 运行run_mindformer.py的入参会覆盖模型配置文件中的参数
+python run_mindformer.py --config configs/llama2/pretrain_llama2_7b.yaml --run_mode train
+```
+
+## 单机多卡训练
+
+```
+# 1. 单机多卡快速启动方式，默认8卡启动
+bash scripts/msrun_launcher.sh "run_mindformer.py \
+  --config {CONFIG_PATH} \
+  --run_mode {train/finetune/eval/predict}"
+
+# 2. 单机多卡快速启动方式，仅设置使用卡数即可
+bash scripts/msrun_launcher.sh "run_mindformer.py \
+  --config {CONFIG_PATH} \
+  --run_mode {train/finetune/eval/predict}" WORKER_NUM
+
+# 3. 单机多卡自定义启动方式
+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
+```
+
+以下内容将以Llama2-7b为例，展示如何在单机8卡的配置下进行分布式训练。
+
+### 启动训练
+
+使用`msrun`命令启动训练脚本：
+
+```bash
+bash scripts/msrun_launcher.sh "run_mindformer.py \
+ --config configs/llama2/pretrain_llama2_7b.yaml \
+ --train_dataset_dir /{path}/wiki4096.mindrecord \
+ --use_parallel True \
+ --run_mode train" 8
+```
+
+## 多机多卡训练
+
+多机多卡执行脚本进行分布式训练需要分别在不同节点运行脚本，并将参数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
+```
+
+以Llama2-13b为例，进行2机16卡的预训练。
+
+### 配置文件修改
+
+根据实际使用的节点数和设备数，修改配置文件`configs/llama2/pretrain_llama2_7b.yaml`：
+
+```yaml
+parallel_config:
+  data_parallel: 2
+  model_parallel: 4
+  pipeline_stage: 2
+  micro_batch_num: 16
+  vocab_emb_dp: True
+  gradient_aggregation_group: 4
+```
+
+**注意：** 如果节点数和设备数发生变化，需根据实际情况修改`data_parallel`、`model_parallel`和`pipeline_stage`，使其满足设备数的需求，即 `device_num = data_parallel × model_parallel × pipeline_stage`，同时需确保`micro_batch_num >= pipeline_stage`。
+
+### 启动多机多卡训练
+
+分别在不同节点运行以下脚本，并将参数`MASTER_ADDR`设置为主节点的IP地址。所有节点使用相同的IP地址设置，不同节点之间仅`NODE_RANK`参数不同。
+
+- 主节点（节点0）启动脚本：
+
+```bash
+bash scripts/msrun_launcher.sh "run_mindformer.py \
+  --config {CONFIG_PATH} \
+  --train_dataset_dir /{path}/wiki4096.mindrecord \
+  --use_parallel True \
+  --run_mode {train}" \
+  16 8 {ip_addr} 8118 0 output/msrun_log False 300
+```
+
+- 从节点（节点1）启动脚本，仅修改`NODE_RANK`参数：
+
+```bash
+bash scripts/msrun_launcher.sh "run_mindformer.py \
+  --config {CONFIG_PATH} \
+  --train_dataset_dir /{path}/wiki4096.mindrecord \
+  --use_parallel True \
+  --run_mode {train}" \
+  16 8 {ip_addr} 8118 1 output/msrun_log False 300
+```
+
+## 更多信息
+
+更多关于不同模型的训练示例，请访问[MindFormers已支持模型库](https://gitee.com/mindspore/mindformers#/mindspore/mindformers/blob/r1.2.0/docs/model_cards/llama2.md)。
+
+---
 
 [![查看源文件](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source.svg)](https://gitee.com/mindspore/docs/blob/master/docs/mindspore/source_zh_cn/mindformers/usage/pre_training.md)
\ No newline at end of file
-- 
Gitee


From 77c84f595ff1c4613fe3974e3e6a461b33c680b1 Mon Sep 17 00:00:00 2001
From: y30062407 <handsome0324@163.com>
Date: Fri, 16 Aug 2024 17:44:34 +0800
Subject: [PATCH 2/2] =?UTF-8?q?feat:=E5=8F=AA=E4=BF=9D=E7=95=99=E9=A2=84?=
 =?UTF-8?q?=E8=AE=AD=E7=BB=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../mindformers/function/weight_conversion.md | 62 -------------------
 1 file changed, 62 deletions(-)

diff --git a/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md b/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md
index 6c90780ff6..a2c2fe74fc 100644
--- a/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md
+++ b/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md
@@ -1,65 +1,3 @@
 # 权重转换功能
-# Lora权重合并
-## 概述
-
-LoRA（Low-Rank Adaptation）的基本原理是对原始模型的参数进行低秩重参数化。合并权重的核心过程是将 LoRA 分支的权重计算并叠加到对应的模型权重中。这一操作不会对推理结果产生任何影响，因此合并后的模型在推理时依然能够保持与原始模型一致的性能。
-
-有关 LoRA 的详细原理和实现，请参阅以下资源：
-
-- 论文: [LoRA: Low-Rank Adaptation of Large Language Models](https://arxiv.org/abs/2106.09685)
-- GitHub: [https://github.com/microsoft/LoRA](https://github.com/microsoft/LoRA)
-
-## 使用说明
-
-本教程将指导您如何将通过 LoRA（Low-Rank Adaptation）微调后的权重与原始模型的权重进行合并，生成可用于推理的完整模型权重文件。合并后的权重将使您能够在推理过程中直接利用 LoRA 的微调效果。若有其他需求，例如仅有 LoRA 权重或对权重进行进一步操作，您可以基于此方法自行调整脚本。
-
-```shell
-python mindformers/tools/transform_ckpt_lora.py \
---src_ckpt_strategy src_strategy_path_or_dir \
---src_ckpt_path_or_dir src_ckpt_path_or_dir \
---dst_ckpt_dir dst_ckpt_dir \
---prefix "checkpoint_" \
---lora_scaling lora_alpha/lora_rank
-```
-
-### 参数说明
-
-- **src_ckpt_strategy**：源权重对应的分布式策略文件路径，通常在启动训练任务后默认保存在 `output/strategy/` 目录下。如果源权重为完整权重，则无需填写此参数；如果为分布式权重，需根据以下情况填写：
-  
-  - **源权重开启了流水线并行**：权重转换基于合并的策略文件，填写分布式策略文件夹路径。脚本会自动将文件夹内的所有 `ckpt_strategy_rank_x.ckpt` 文件合并，并在文件夹下生成 `merged_ckpt_strategy.ckpt`。如果已经存在 `merged_ckpt_strategy.ckpt`，可以直接填写该文件的路径。
-  - **源权重未开启流水线并行**：权重转换可基于任一策略文件，填写任意一个 `ckpt_strategy_rank_x.ckpt` 文件的路径即可。
-  
-  **注意**：如果策略文件夹下已存在 `merged_ckpt_strategy.ckpt` 且仍传入文件夹路径，脚本会首先删除旧的 `merged_ckpt_strategy.ckpt`，再合并生成新的 `merged_ckpt_strategy.ckpt` 以用于权重转换。因此，请确保该文件夹具有足够的写入权限，否则操作将报错。
-- **src_ckpt_path_or_dir**：源权重的路径。如果为分布式权重，请填写源权重所在文件夹的路径，源权重应按 `model_dir/rank_x/xxx.ckpt` 格式存放，并将文件夹路径填写为 `model_dir`。若源权重为完整权重，则填写完整权重的绝对路径。
-- **dst_ckpt_dir**：目标权重的保存路径，需为自定义的空文件夹路径。目标权重将按 `model_dir/rank_x/xxx.ckpt` 格式保存。
-- **prefix**：目标权重文件的命名前缀，默认值为 "checkpoint_"，即目标权重将按照 `model_dir/rank_x/checkpoint_x.ckpt` 格式保存。
-- **lora_scaling**：LoRA 权重的合并系数，默认为 `lora_alpha/lora_rank`，这两个参数即为 LoRA 模型配置时的参数，需自行计算。
-
-## 示例
-
-### 场景 1：完整的带 LoRA 的权重
-
-如果您拥有一个完整的带 LoRA 的权重文件，并希望将其转换为完整的原始权重，您可以按照以下方式填写参数（直接输入完整权重的路径）：
-
-```bash
-python mindformers/tools/transform_ckpt_lora.py \
---src_ckpt_path_or_dir .../xxx/xxx.ckpt \
---dst_ckpt_dir dst_ckpt_dir \
---prefix "checkpoint_" \
---lora_scaling lora_alpha/lora_rank
-```
-
-### 场景 2：带 LoRA 的分布式权重
-
-如果您拥有一个经过分布式切分的带 LoRA 的权重文件，并希望将其转换为完整的原始权重，您可以按照以下方式填写参数（需输入权重文件夹路径和分布式策略文件夹路径）：
-
-```bash
-python mindformers/tools/transform_ckpt_lora.py \
---src_ckpt_strategy .../xxx/mindformers/output/strategy/ \
---src_ckpt_path_or_dir .../xxx/model_dir \
---dst_ckpt_dir dst_ckpt_dir \
---prefix "checkpoint_" \
---lora_scaling lora_alpha/lora_rank
-```
 
 [![查看源文件](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source.svg)](https://gitee.com/mindspore/docs/blob/master/docs/mindspore/source_zh_cn/mindformers/function/weight_conversion.md)
\ No newline at end of file
-- 
Gitee