已合并
修改mindspeed-rl-master-readme相关说明文档 #701
NIE SHIYU创建于 2025年10月14日
修改mindspeed-rl-master-readme相关说明文档 #701
已合并
NIE SHIYU创建于 2025年10月14日
7 个文件变更+41-22
@@ -47,7 +47,7 @@ MindSpeed RL依赖配套如下表:
47 </tr>47 </tr>
48 <tr>48 <tr>
49 <td>Python</td>49 <td>Python</td>
50- <td><a href="https://gitcode.com/ascend/pytorch#pytorch%E4%B8%8Epython%E7%89%88%E6%9C%AC%E9%85%8D%E5%A5%97%E8%A1%A8">PT配套版本</a></td>50+ <td><a href="https://gitcode.com/ascend/pytorch#pytorch%E4%B8%8Epython%E7%89%88%E6%9C%AC%E9%85%8D%E5%A5%97%E8%A1%A8">PyTorch与Python版本配套表</a></td>
51 </tr>51 </tr>
52 <tr>52 <tr>
53 <td>PyTorch</td>53 <td>PyTorch</td>
@@ -323,6 +323,7 @@ MindSpeed RL已发布版本维护策略:
323 323 
324| **MindSpeed RL版本** | **对应标签** | **维护策略** | **当前状态** | **发布时间** | **后续状态** | **EOL日期** |324| **MindSpeed RL版本** | **对应标签** | **维护策略** | **当前状态** | **发布时间** | **后续状态** | **EOL日期** |
325|--------------------| ------------ |----------|----------|-----------|----------|-----------|325|--------------------| ------------ |----------|----------|-----------|----------|-----------|
326+| 2.2.0 | \ | 正式版本 | 商用 | \ | \ | 2026/03/30 |
326| 2.1.0 | \ | 正式版本 | 商用 | \ | \ | 2025/12/30 |327| 2.1.0 | \ | 正式版本 | 商用 | \ | \ | 2025/12/30 |
327| 2.0.0 | \ | 预览版本 | 预览 | \ | \ | 2025/9/30 |328| 2.0.0 | \ | 预览版本 | 预览 | \ | \ | 2025/9/30 |
328 329 
@@ -15,8 +15,8 @@
15 15 
16## 文件权限控制16## 文件权限控制
171. 建议用户在主机(包括宿主机)及容器中设置运行系统umask值为0027及以上,保障新增文件夹默认最高权限为750,新增文件默认最高权限为640。171. 建议用户在主机(包括宿主机)及容器中设置运行系统umask值为0027及以上,保障新增文件夹默认最高权限为750,新增文件默认最高权限为640。
18-2. 建议用户对个人数据、商业资产、源文件、训练过程中保存的各类文件等敏感内容做好权限管控。涉及场景如MindSpeed-RL-LLM安装目录权限管控、多用户使用共享数据集权限管控,管控权限可参考表1进行设置。18+2. 建议用户对个人数据、商业资产、源文件、训练过程中保存的各类文件等敏感内容做好权限管控。涉及场景如MindSpeed-RL安装目录权限管控、多用户使用共享数据集权限管控,管控权限可参考表1进行设置。
19-3. MindSpeed-RL-LLM在数据预处理中会生成训练数据,在训练过程会生成权重文件,文件权限默认640,用户可根据实际需求对生成文件权限进行进阶管控。19+3. MindSpeed-RL在数据预处理中会生成训练数据,在训练过程会生成权重文件,文件权限默认640,用户可根据实际需求对生成文件权限进行进阶管控。
20 20 
21**表1 文件(夹)各场景权限管控推荐最大值**21**表1 文件(夹)各场景权限管控推荐最大值**
22| 类型 | linux权限参考最大值 |22| 类型 | linux权限参考最大值 |
@@ -36,6 +36,11 @@ bash examples/data/preprocess_data.sh math_17k
36* `log_interval`:设置日志记录的间隔,每处理多少条数据时记录一次日志,用于监控数据处理的进度和状态;36* `log_interval`:设置日志记录的间隔,每处理多少条数据时记录一次日志,用于监控数据处理的进度和状态;
37* `handler_name`:指定处理数据的处理器名称;37* `handler_name`:指定处理数据的处理器名称;
38* `seq_length`:设置数据预处理最大序列长度,超过了会过滤掉;38* `seq_length`:设置数据预处理最大序列长度,超过了会过滤掉;
39+* `map_keys`:指定数据处理时使用的映射字典,用于将原始数据中的字段映射到目标字段中;
40+ - prompt:主指令/题目文本(Alpaca 格式里的 instruction)。例如把原始样本的 "problem" 作为指令。
41+ - query:可选的补充输入/上下文(Alpaca 格式里的 input)。没有就设为空串 ""。
42+ - response:目标答案/参考输出(训练时作为监督标签)。这里映射到原始样本的 "answer"。
43+ - system:可选的系统提示(chat 模板的 system 角色,用于全局行为设定)。没有就设为空串 ""。
39 44 
40## 模型权重转换45## 模型权重转换
41 46 
@@ -47,10 +52,9 @@ bash examples/data/preprocess_data.sh math_17k
47权重文件可以从 Huggingface 网站上获取,可以根据模型的使用场景灵活选择,在这里以52权重文件可以从 Huggingface 网站上获取,可以根据模型的使用场景灵活选择,在这里以
48[Qwen2.5-32B](https://huggingface.co/Qwen/Qwen2.5-32B/tree/main) 为参考。53[Qwen2.5-32B](https://huggingface.co/Qwen/Qwen2.5-32B/tree/main) 为参考。
49### hf 转 mcore54### hf 转 mcore
50-在训练前,需要将 Hugging Face 权重转换成 Mcore 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的 [MindSpeed-LLM](https://gitcode.com/Ascend/MindSpeed-LLM) 权重转换部分 55+在训练前,需要将 Hugging Face 权重转换成 Mcore 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的[MindSpeed-LLM 权重转换部分](https://gitcode.com/Ascend/MindSpeed-LLM/blob/2.1.0/docs/pytorch/solutions/checkpoint_convert.md)。
51- 
52### mcore 转 hf(可选)56### mcore 转 hf(可选)
53-训练结束后,如果需要将生成的 Mcore 格式权重转换回 Hugging Face 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的 [MindSpeed-LLM](https://gitcode.com/Ascend/MindSpeed-LLM) 权重转换部分 57+训练结束后,如果需要将生成的 Mcore 格式权重转换回 Hugging Face 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的[MindSpeed-LLM 权重转换部分](https://gitcode.com/Ascend/MindSpeed-LLM/blob/2.1.0/docs/pytorch/solutions/checkpoint_convert.md)。
54 58 
55## 启动训练59## 启动训练
56 60 
@@ -36,6 +36,11 @@ bash examples/data/preprocess_data.sh orca_rlhf
36* `log_interval`:设置日志记录的间隔,每处理多少条数据时记录一次日志,用于监控数据处理的进度和状态;36* `log_interval`:设置日志记录的间隔,每处理多少条数据时记录一次日志,用于监控数据处理的进度和状态;
37* `handler_name`:指定处理数据的处理器名称;37* `handler_name`:指定处理数据的处理器名称;
38* `seq_length`:设置数据预处理最大序列长度,超过了会过滤掉;38* `seq_length`:设置数据预处理最大序列长度,超过了会过滤掉;
39+* `map_keys`:指定数据处理时使用的映射字典,用于将原始数据中的字段映射到目标字段中;
40+ - prompt:主指令/题目文本(Alpaca 格式里的 instruction)。例如把原始样本的 "problem" 作为指令。
41+ - query:可选的补充输入/上下文(Alpaca 格式里的 input)。没有就设为空串 ""。
42+ - response:目标答案/参考输出(训练时作为监督标签)。这里映射到原始样本的 "answer"。
43+ - system:可选的系统提示(chat 模板的 system 角色,用于全局行为设定)。没有就设为空串 ""。
39 44 
40## 模型权重转换45## 模型权重转换
41 46 
@@ -47,10 +52,10 @@ bash examples/data/preprocess_data.sh orca_rlhf
47权重文件可以从 Huggingface 网站上获取,可以根据模型的使用场景灵活选择,在这里以52权重文件可以从 Huggingface 网站上获取,可以根据模型的使用场景灵活选择,在这里以
48[Qwen3-30B-A3B](https://huggingface.co/Qwen/Qwen3-30B-A3B) 为参考。53[Qwen3-30B-A3B](https://huggingface.co/Qwen/Qwen3-30B-A3B) 为参考。
49### hf 转 mcore54### hf 转 mcore
50-在训练前,需要将 Hugging Face 权重转换成Mcore格式,具体权重转换方式可见安装指南中对应 commit id 的 MindSpeed-LLM 权重转换部分 55+在训练前,需要将 Hugging Face 权重转换成Mcore格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的[MindSpeed-LLM 权重转换部分](https://gitcode.com/Ascend/MindSpeed-LLM/blob/2.1.0/docs/pytorch/solutions/checkpoint_convert.md)
51 56 
52### mcore 转 hf(可选)57### mcore 转 hf(可选)
53-训练结束后,如果需要将生成的mcore格式权重转换回 Hugging Face 格式,具体权重转换方式可见安装指南中对应 commit id 的 MindSpeed-LLM 权重转换部分 58+训练结束后,如果需要将生成的mcore格式权重转换回 Hugging Face 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的[MindSpeed-LLM 权重转换部分](https://gitcode.com/Ascend/MindSpeed-LLM/blob/2.1.0/docs/pytorch/solutions/checkpoint_convert.md)
54 59 
55## 启动训练60## 启动训练
56 61 
@@ -59,6 +59,7 @@ bash examples/data/preprocess_data.sh deepscaler
59 - query:可选的补充输入/上下文(Alpaca 格式里的 input)。没有就设为空串 ""。59 - query:可选的补充输入/上下文(Alpaca 格式里的 input)。没有就设为空串 ""。
60 - response:目标答案/参考输出(训练时作为监督标签)。这里映射到原始样本的 "answer"。60 - response:目标答案/参考输出(训练时作为监督标签)。这里映射到原始样本的 "answer"。
61 - system:可选的系统提示(chat 模板的 system 角色,用于全局行为设定)。没有就设为空串 ""。61 - system:可选的系统提示(chat 模板的 system 角色,用于全局行为设定)。没有就设为空串 ""。
62+* `dataset_additional_keys: ["labels"]`:指定在数据处理后需要保留的原始数据集中的额外字段。
62 63 
63## 模型权重转换64## 模型权重转换
64 65 
@@ -72,17 +73,18 @@ bash examples/data/preprocess_data.sh deepscaler
72权重文件可以从 Huggingface 网站上获取,可以根据模型的使用场景灵活选择,在这里以73权重文件可以从 Huggingface 网站上获取,可以根据模型的使用场景灵活选择,在这里以
73[Qwen2.5-7B](https://huggingface.co/Qwen/Qwen2.5-7B) 为参考。74[Qwen2.5-7B](https://huggingface.co/Qwen/Qwen2.5-7B) 为参考。
74### hf 转 mcore75### hf 转 mcore
75-在训练前,需要将 Hugging Face 权重转换成 Mcore 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的 [MindSpeed-LLM](https://gitcode.com/Ascend/MindSpeed-LLM) 权重转换部分 76+在训练前,需要将 Hugging Face 权重转换成 Mcore 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的[MindSpeed-LLM 权重转换部分](https://gitcode.com/Ascend/MindSpeed-LLM/blob/2.1.0/docs/pytorch/solutions/checkpoint_convert.md)。
77+ 
76 78 
77### mcore 转 hf(可选)79### mcore 转 hf(可选)
78-训练结束后,如果需要将生成的 Mcore 格式权重转换回 Hugging Face 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的 [MindSpeed-LLM](https://gitcode.com/Ascend/MindSpeed-LLM) 权重转换部分 80+训练结束后,如果需要将生成的 Mcore 格式权重转换回 Hugging Face 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的[MindSpeed-LLM 权重转换部分](https://gitcode.com/Ascend/MindSpeed-LLM/blob/2.1.0/docs/pytorch/solutions/checkpoint_convert.md)。
79 81 
80## 启动训练82## 启动训练
81 83 
82以 Qwen25 7B 模型为例,在启动训练之前,需要修改[ 启动脚本 ](../../examples/grpo/grpo_trainer_qwen25_7b.sh)的配置:84以 Qwen25 7B 模型为例,在启动训练之前,需要修改[ 启动脚本 ](../../examples/grpo/grpo_trainer_qwen25_7b.sh)的配置:
831. 根据实际安装路径设置 jemalloc 环境变量,用于更好管理内存,避免长跑过程中内存 OOM ,例如:export LD_PRELOAD=/usr/local/lib/libjemalloc.so.2 851. 根据实际安装路径设置 jemalloc 环境变量,用于更好管理内存,避免长跑过程中内存 OOM ,例如:export LD_PRELOAD=/usr/local/lib/libjemalloc.so.2
842. 修改 DEFAULT_YAML 为指定的 yaml,目前已支持的配置文件放置在 configs / 文件夹下,同时需要对[ 环境变量配置文件 ](../../configs/envs/runtime_env.yaml) 中的 VLLM_DP_SIZE 及 HCCL_SOCKET_IFNAME 等参数进行配置,具体参数说明可见 [配置文件参数介绍](../features/grpo_yaml.md);862. 修改 DEFAULT_YAML 为指定的 yaml,目前已支持的配置文件放置在 configs / 文件夹下,同时需要对[ 环境变量配置文件 ](../../configs/envs/runtime_env.yaml) 中的 VLLM_DP_SIZE 及 HCCL_SOCKET_IFNAME 等参数进行配置,具体参数说明可见 [配置文件参数介绍](../features/grpo_yaml.md);
85-3. 根据使用机器的情况,修改 NNODES 、NPUS_PER_NODE 配置, 例如单机 A3 可设置 NNODES 为 1 、NPUS_PER_NODE 为16;87+3. 根据使用机器的情况,修改 NNODES 、NPUS_PER_NODE 配置, 例如单机 A3 可设置 NNODES 为 1 、NPUS_PER_NODE 为16;单机 A2 可设置 NNODES 为 1 、NPUS_PER_NODE 为8;
864. 如果是单机,需要保证 MASTER_ADDR 与 CURRENT_IP 一致,如果为多机,需要保证各个机器的 MASTER_ADDR 一致,CURRENT_IP 为各个节点的 IP (需要注意的是MASTER_ADDR 与 CURRENT_IP 不能设置为 localhost);884. 如果是单机,需要保证 MASTER_ADDR 与 CURRENT_IP 一致,如果为多机,需要保证各个机器的 MASTER_ADDR 一致,CURRENT_IP 为各个节点的 IP (需要注意的是MASTER_ADDR 与 CURRENT_IP 不能设置为 localhost);
875. 启动脚本中的 SOCKET_IFNAME 需要设置为 CURRENT_IP 所对应的通信网卡名;895. 启动脚本中的 SOCKET_IFNAME 需要设置为 CURRENT_IP 所对应的通信网卡名;
88```bash90```bash
@@ -136,7 +138,7 @@ rl_config:
136 138 
137* 全共卡方案下总时间分布139* 全共卡方案下总时间分布
138 140 
139-`timing/all` >= `timing/rollout` +`timing/old_log_p` + `timing/update` + `timing/reference` + `timing/reshard_to_train` + `timing/reshard_to_infer` + `max(timing/non_overlap_rule_reward, timing/non_overlap_reference_model)`141+`timing/all` >= `timing/rollout` +`timing/old_log_p` + `timing/update` + `timing/reference_model` + `timing/reshard_to_train` + `timing/reshard_to_infer` + `max(timing/non_overlap_rule_reward, timing/non_overlap_reference_model)`
140 142 
141 143 
142**其他指标**144**其他指标**
@@ -42,6 +42,12 @@ bash examples/data/preprocess_data.sh deepscaler
42* `log_interval`:设置日志记录的间隔,每处理多少条数据时记录一次日志,用于监控数据处理的进度和状态;42* `log_interval`:设置日志记录的间隔,每处理多少条数据时记录一次日志,用于监控数据处理的进度和状态;
43* `handler_name`:指定处理数据的处理器名称;43* `handler_name`:指定处理数据的处理器名称;
44* `seq_length`:设置数据预处理最大序列长度,超过了会过滤掉;44* `seq_length`:设置数据预处理最大序列长度,超过了会过滤掉;
45+* `map_keys`:指定数据处理时使用的映射字典,用于将原始数据中的字段映射到目标字段中;
46+ - prompt:主指令/题目文本(Alpaca 格式里的 instruction)。例如把原始样本的 "problem" 作为指令。
47+ - query:可选的补充输入/上下文(Alpaca 格式里的 input)。没有就设为空串 ""。
48+ - response:目标答案/参考输出(训练时作为监督标签)。这里映射到原始样本的 "answer"。
49+ - system:可选的系统提示(chat 模板的 system 角色,用于全局行为设定)。没有就设为空串 ""。
50+* `dataset_additional_keys: ["labels"]`:指定在数据处理后需要保留的原始数据集中的额外字段。
45 51 
46## 模型权重转换52## 模型权重转换
47 53 
@@ -72,7 +78,7 @@ bash examples/data/preprocess_data.sh deepscaler
72 78 
73### mcore 转 hf(可选)79### mcore 转 hf(可选)
74 80 
75-训练结束后,如果需要将生成的 Mcore 格式权重转换回 Hugging Face 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的 [MindSpeed-LLM](https://gitcode.com/Ascend/MindSpeed-LLM) 权重转换部分 81+训练结束后,如果需要将生成的 Mcore 格式权重转换回 Hugging Face 格式,具体权重转换方式可见[安装指南](../install_guide.md)中对应 commit id 的[MindSpeed-LLM 权重转换部分](https://gitcode.com/Ascend/MindSpeed-LLM/blob/2.1.0/docs/pytorch/solutions/checkpoint_convert.md)。
76 82 
77## 单卡多进程83## 单卡多进程
78### 技术概述84### 技术概述
@@ -151,7 +157,7 @@ rl_config:
151 157 
152* 全共卡方案下总时间计算方式158* 全共卡方案下总时间计算方式
153 159 
154-`timing/all` >= `timing/rollout` +`timing/old_log_p` + `timing/update` + `timing/reference` + `timing/reshard_to_train` + `timing/reshard_to_infer` + `max(timing/non_overlap_rule_reward, timing/non_overlap_reference_model)`+`timing/critic_model` +`timing/update_critic`160+`timing/all` >= `timing/rollout` +`timing/old_log_p` + `timing/update` + `timing/reference_model` + `timing/reshard_to_train` + `timing/reshard_to_infer` + `max(timing/non_overlap_rule_reward, timing/non_overlap_reference_model)`+`timing/critic_model` +`timing/update_critic`
155 161 
156**其他指标**162**其他指标**
157 163 
@@ -15,6 +15,7 @@ MindSpeed RL支持Atlas 800T A2等昇腾训练硬件形态。软件版本配套
15## 安装依赖的软件15## 安装依赖的软件
16 16 
17在安装MindSpeed RL之前,请参考[版本配套表](#版本配套表),安装配套的昇腾软件栈,软件列表如下:17在安装MindSpeed RL之前,请参考[版本配套表](#版本配套表),安装配套的昇腾软件栈,软件列表如下:
18+(注:Ascend提供[满足商用标准的稳定版本](https://www.hiascend.com/developer/download/commercial)和[具有新特性的社区体验版本](https://www.hiascend.com/developer/download/community)供开发者选择)
18 19 
19<table>20<table>
20 <tr>21 <tr>
@@ -66,7 +67,7 @@ MindSpeed RL支持Atlas 800T A2等昇腾训练硬件形态。软件版本配套
66 67 
67### 驱动固件安装68### 驱动固件安装
68 69 
69-下载参考:[Ascend资源下载中心](https://www.hiascend.com/developer/download/community)70+(注:下载参考:[商用稳定版固件与驱动](https://www.hiascend.com/hardware/firmware-drivers/commercial)和[社区体验版固件与驱动](https://www.hiascend.com/hardware/firmware-drivers/community)
70 71 
71```shell72```shell
72bash Ascend-hdk-*-npu-firmware_*.run --full73bash Ascend-hdk-*-npu-firmware_*.run --full
@@ -74,12 +75,12 @@ bash Ascend-hdk-*-npu-driver_*.run --full
74```75```
75 76 
76### CANN安装77### CANN安装
77- 78+(注:下载参考:[商用稳定版CANN](https://www.hiascend.com/developer/download/commercial/result?module=cann)和[8.3.RC1 社区体验版CANN](https://www.hiascend.com/developer/download/community/result?module=cann))
78```shell79```shell
79-bash Ascend-cann-toolkit_8.2.RC1_linux-aarch64.run --install80+bash Ascend-cann-toolkit_*_linux-aarch64.run --install
80-bash Atlas-A3-cann-kernels_8.2.RC1_linux-aarch64.run --install81+bash Atlas-A3-cann-kernels_*_linux-aarch64.run --install
81source /usr/local/Ascend/ascend-toolkit/set_env.sh82source /usr/local/Ascend/ascend-toolkit/set_env.sh
82-bash Ascend-cann-nnal_8.2.RC1_linux-aarch64.run --install83+bash Ascend-cann-nnal_*_linux-aarch64.run --install
83source /usr/local/Ascend/nnal/atb/set_env.sh84source /usr/local/Ascend/nnal/atb/set_env.sh
84```85```
85 86 
@@ -110,7 +111,7 @@ pip install ray==2.42.1
110```111```
111 112 
112### PyTorch框架安装113### PyTorch框架安装
113-(注:可从[PTA官方代码仓](https://gitcode.com/Ascend/pytorch/releases)获取对应版本torch和torch_npu的whl包)114+(注:[PyTorch框架和torch_npu插件安装教程](https://www.hiascend.com/document/detail/zh/Pytorch/710/configandinstg/instg/insg_0004.html);可从[PyTorch-Ascend官方代码仓](https://gitcode.com/Ascend/pytorch/releases)获取PyTorch各个版本对应的torch_npu的whl包)
114```shell115```shell
115# 安装torch和torch_npu116# 安装torch和torch_npu
116pip install torch-2.5.1-cp310-cp310-*.whl117pip install torch-2.5.1-cp310-cp310-*.whl
@@ -127,9 +128,9 @@ pip install apex-0.1.dev*.whl
127```shell128```shell
128sudo apt install libjemalloc2129sudo apt install libjemalloc2
129```130```
130-在启动任务前执行如下命令通过环境变量导入jemalloc:131+在启动任务前执行如下命令通过环境变量导入jemalloc,需先通过 **find /usr -name libjemalloc.so.2** 确认文件是否存在
131```shell132```shell
132-# arm64架构(可通过 find /usr -name libjemalloc.so.2 确认文件是否存在) 133+# arm64架构
133export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2134export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2
134# x86_64架构135# x86_64架构
135export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2136export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2