已合并
提供NPU verl环境的docker镜像以及使用说明 #728
Minds创建于 2025年11月5日
提供NPU verl环境的docker镜像以及使用说明 #728
已合并
Minds创建于 2025年11月5日
2 个文件变更+515-1
@@ -0,0 +1,509 @@
1+# VeRL镜像使用文档
2+ 
3+## 1.镜像环境导入
4+ 
W
Wwucong252025年12月5日

这个readme是不是放在verl_plugin的docs更加合适一点

likedislike
wucong25
2025年12月5日 评论:
Minds
Minds
2025年12月5日 评论:
Minds
Minds
2025年12月5日 评论:
wucong25
2025年12月5日 评论:
5+本镜像中已集成 CANN、PyTorch、PyTorch_npu、VeRL、MindSpeed、Megatron-LM、MindSpeed-RL/verl_npu等配套的依赖软件,仅需激活镜像后再导入**数据集和模型权重**即可使用。已按照[仓上安装文档](https://gitcode.com/Ascend/MindSpeed-RL/blob/2.2.0/rl-plugin/README.MD)完成了VeRL的NPU适配。
6+ 
7+### 1.1 关键依赖软件版本
8+ 
9+| 软件| 版本 |
10+|------| ----- |
11+|昇腾NPU固件与驱动| 25.3.RC1 |
12+| CANN | 8.3.RC1 |
13+| Python | 3.10.0 |
14+| Pytorch | 2.7.1 |
15+| Transformers | commit-id 836570e925|
16+| vLLM | commit-id 3821787aa7 |
17+| vLLM-ascend | commit-id 1de16ead8e |
18+| VeRL | commit-id 796871d7d0 |
19+| MindSpeed | commit-id 1cdd0abd75 |
20+| Megatron-LM | core_v0.12.1 |
21+| MindSpeedRL/rl-plugin | 2.2.0 |
22+ 
23+### 1.2 导入镜像并构造容器
24+ 
25+**下载镜像**
26+镜像归档在昇腾社区的[昇腾镜像仓库](https://www.hiascend.com/developer/ascendhub/detail/2a71f71cb92643baa95e527b39088e0e),命令行下载方式如下
27+```
28+910B:docker pull swr.cn-south-1.myhuaweicloud.com/ascendhub/verl_pt27_25rc3:a2-arm
29+AtlasA3:docker pull swr.cn-south-1.myhuaweicloud.com/ascendhub/verl_pt27_25rc3:a3-arm
30+A+X:docker pull swr.cn-south-1.myhuaweicloud.com/ascendhub/verl_pt27_25rc3:ax-x86
31+```
32+ 
33+查看docker是否建立成功,成功时会在REPOSITORY栏显示出swr.cn-south-1.myhuaweicloud.com/ascendhub/verl_pt27_25rc3
W
Wwucong252025年12月5日

swr.cn-south-1.myhuaweicloud.comswr.cn-south-1.myhuaweicloud.com这个是否涉及蓝区安全问题

likedislike
Minds
Minds
2025年12月5日 评论:
wucong25
2025年12月5日 评论:
34+```
35+docker images
36+```
37+ 
38+**构造容器**
39+ 
40+根据指定的swr.cn-south-1.myhuaweicloud.com/ascendhub/verl_pt27_25rc3:a2/a3-arm镜像构建一个名为verl_rc3的容器。
41+ 
42+针对于单机8卡的机器,如Ascend910B系列机器,构造容器命令如下:
43+ 
44+```
45+docker run -dit --ipc=host --network host --name 'verl_rc3' \
46+ --device=/dev/davinci0 \
47+ --device=/dev/davinci1 \
48+ --device=/dev/davinci2 \
49+ --device=/dev/davinci3 \
50+ --device=/dev/davinci4 \
51+ --device=/dev/davinci5 \
52+ --device=/dev/davinci6 \
53+ --device=/dev/davinci7 \
54+ --device=/dev/davinci_manager \
55+ --device=/dev/devmm_svm \
56+ --device=/dev/hisi_hdc \
57+ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
58+ -v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \
59+ -v /usr/local/sbin/:/usr/local/sbin/ \
60+ -v /home/:/home/ \
61+ -v /data/:/data/ \
62+ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
63+ -v /usr/bin/msnpureport:/usr/bin/msnpureport \
64+ swr.cn-south-1.myhuaweicloud.com/ascendhub/verl_pt27_25rc3:a2-arm \
65+ /bin/bash
66+```
67+ 
68+针对于单机16卡的机器,如Atlas A3系列机器,构造容器命令如下:
69+ 
70+```
71+docker run -dit --ipc=host --network host --name 'verl_rc3' \
72+ --device=/dev/davinci0 \
73+ --device=/dev/davinci1 \
74+ --device=/dev/davinci2 \
75+ --device=/dev/davinci3 \
76+ --device=/dev/davinci4 \
77+ --device=/dev/davinci5 \
78+ --device=/dev/davinci6 \
79+ --device=/dev/davinci7 \
80+ --device=/dev/davinci8 \
81+ --device=/dev/davinci9 \
82+ --device=/dev/davinci10 \
83+ --device=/dev/davinci11 \
84+ --device=/dev/davinci12 \
85+ --device=/dev/davinci13 \
86+ --device=/dev/davinci14 \
87+ --device=/dev/davinci15 \
88+ --device=/dev/davinci_manager \
89+ --device=/dev/devmm_svm \
90+ --device=/dev/hisi_hdc \
91+ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
92+ -v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \
93+ -v /usr/local/sbin/:/usr/local/sbin/ \
94+ -v /home/:/home/ \
95+ -v /data/:/data/ \
96+ -v /mnt/:/mnt/ \
97+ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
98+ -v /usr/bin/msnpureport:/usr/bin/msnpureport \
99+ swr.cn-south-1.myhuaweicloud.com/ascendhub/verl_pt27_25rc3:a3-arm \
100+ /bin/bash
101+```
102+ 
103+这条命令根据-v对文件进行映射,映射文件夹如下,也可以根据自己的需求添加更多映射文件夹:
104+ 
105+● /usr/local/Ascend/driver ;
106+● /usr/local/Ascend/firmware ;
107+● /usr/local/sbin/ ;
108+● /home ;
109+● /data ;
110+ 
111+查看容器是否建立成功,成功时会在IMAGE栏显示出swr.cn-south-1.myhuaweicloud.com/ascendhub/verl_pt27_25rc3:a3-arm,NAMES栏为verl_rc3的容器:
112+ 
113+```
114+docker ps -a
115+```
116+ 
117+**进入容器**
118+ 
119+```
120+docker exec -it verl_rc3 bash
121+```
122+ 
123+### 1.3 安全风险提示
124+ 
125+在使用 Docker 容器运行VeRL 时,需要注意以下安全风险:
126+ 
127+***使用 root 用户运行**​:容器默认以 root 用户身份运行,可能带来安全隐患。建议在生产环境中创建非特权用户来运行应用程序。
128+ 
129+> 在生产环境部署时,请根据实际安全要求调整容器配置,确保系统安全性。
130+ 
131+### 1.4 激活CANN
132+ 
133+cann相关包已经安装在`/usr/local/Ascend/cann/ascend-toolkit/``/usr/local/Ascend/cann/nnal`文件夹下:
134+ 
135+```shell
136+source /usr/local/Ascend/cann/ascend-toolkit/set_env.sh
137+source /usr/local/Ascend/cann/nnal/atb/set_env.sh
138+```
139+ 
140+### 1.5 激活conda VeRL环境
141+ 
142+执行以下命令,查看conda环境。
143+ 
144+```shell
145+conda env list
146+```
147+ 
148+```
149+# conda environments:
150+#
151+base * /root/miniconda3
152+verl_pt27_25rc3 /root/miniconda3/envs/verl_pt27_25rc3
153+```
154+ 
155+其中verl_pt27_25rc3为模型训练环境,包含VeRL强化学习框架及依赖,同时集成了评测工具aisbench运行环境。
156+ 
157+执行以下命令,激活VeRL训练环境
158+ 
159+```
160+conda activate verl_pt27_25rc3
161+```
162+ 
163+注:适用A+X型号机器的镜像中无需该步骤
164+ 
165+## 2. 模型训练
166+ 
167+**以下将基于 veRL 仓库中的示例脚本,使用 Qwen3-32B 模型及 dapo-math-17k 数学领域数据集,详细介绍整体的强化学习训练流程,训练代码位于`/examples/verl`中**
168+ 
169+### 2.1 训练数据集准备
170+ 
171+执行以下命令,进入`/examples/datasets`文件夹,完成DAPO-Math-17k和Aime2024数据集下载
172+ 
173+在huggingface下载数据集
174+ 
175+```shell
176+#!/usr/bin/env bash
177+set -uxo pipefail
178+ 
179+export VERL_HOME=${VERL_HOME:-"/examples"}
180+export TRAIN_FILE=${TRAIN_FILE:-"${VERL_HOME}/datasets/dapo-math-17k.parquet"}
181+export TEST_FILE=${TEST_FILE:-"${VERL_HOME}/datasets/aime-2024.parquet"}
182+export OVERWRITE=${OVERWRITE:-0}
183+ 
184+mkdir -p "${VERL_HOME}/data"
185+ 
186+if [ ! -f "${TRAIN_FILE}" ] || [ "${OVERWRITE}" -eq 1 ]; then
187+ wget -O "${TRAIN_FILE}" "https://huggingface.co/datasets/BytedTsinghua-SIA/DAPO-Math-17k/resolve/main/data/dapo-math-17k.parquet?download=true"
188+fi
189+ 
190+if [ ! -f "${TEST_FILE}" ] || [ "${OVERWRITE}" -eq 1 ]; then
191+ wget -O "${TEST_FILE}" "https://huggingface.co/datasets/BytedTsinghua-SIA/AIME-2024/resolve/main/data/aime-2024.parquet?download=true"
192+fi
193+ 
194+```
195+或在魔塔社区下载dapo-math-17k数据集
196+```
197+cd /examples/datasets
198+git clone https://www.modelscope.cn/datasets/AI-ModelScope/DAPO-Math-17k.git
199+cp DAPO-Math-17k/data/dapo-math-17k.parquet ./
200+rm -rf DAPO-Math-17k
201+```
202+ 
203+### 2.2 模型下载
204+ 
205+**执行以下命令,即可开始下载 Qwen3-32B 模型。**
206+ 
207+```shell
208+export HF_ENDPOINT=https://hf-mirror.com
209+huggingface-cli download --resume-download Qwen/Qwen3-32B --local-dir /path/to/local_dir
210+```
211+ 
212+**--local-dir:**模型保存路径。
213+ 
214+### 2.3 启动训练
215+ 
216+这里以**四台A3机器训练Qwen3-32B模型**为例,​如果需要使用A2机器启动训练,需修改yaml文件和训练脚本里的机器数量​。
217+ 
218+**主节点和从节点配置步骤一致**​,准备步骤如下:
219+ 
220+**2.3.1 修改启动脚本**
221+ 
222+打开 **`/examples/verl/start.sh`** 文件,该脚本文件用于配置**各类环境变量以及ray节点拉起**,进行如下修改:
223+ 
224+- 环境变量:修改为RAY和通信等相关环境变
225+- DEFAULT_SH:修改为训练所用配置sh路径
226+- NNODES和NPUS_PER_NODE:修改为使用节点和每个节点NPU数量
227+- MASTER_ADDR:修改为对应主节点 IP。即所有节点的MASTER_ADDR 应该相同。
228+- SOCKET_IFNAME, HCCL_SOCKET_IFNAME, GLOO_SOCKET_IFNAME:修改为对应通信网卡,通信网卡可以通过以下命令获取。
229+ 
230+```shell
231+ifconfig |grep "$(hostname -I |awk '{print $1}'|awk -F '.' '{print $0}')" -B 1|awk -F ':' '{print$1}' | head -1 | tail -1
232+```
233+ 
234+```shell
235+# ……
236+# 修改为当前需要跑的用例路径
237+DEFAULT_SH="./test_dapo_qwen3_32b_fsdp2_A3.sh"
238+# ……
239+NNODES=4
240+NPUS_PER_NODE=16
241+# 修改为对应主节点IP
242+MASTER_ADDR="IP FOR MASTER NODE"
243+# 修改为当前节点的通信网卡
244+SOCKET_IFNAME="Your SOCKET IFNAME"
245+export HCCL_SOCKET_IFNAME="SOCKET IFNAME FOR CURRENT NODE"
246+export GLOO_SOCKET_IFNAME="SOCKET IFNAME FOR CURRENT NODE"
247+# ……
248+ 
249+```
250+ 
251+**2.3.2 修改训练配置**
252+ 
253+使用多机训练时,训练配置要相同,包括模型路径,数据集路径等。打开`/examples/verl/test_dapo_qwen3_32b_fsdp2_A3.sh`,脚本展示如下,需要修改的参数:​**NNODES、N_GPUS_PER_NODE、MODEL_PATH、CKPTS_DIR**​,其余参数可自定义:
254+ 
255+- NNODES:修改为使用节点数量,与启动脚本保持一致
256+- N_GPUS_PER_NODE:修改为每个节点NPU数量,与启动脚本保持一致
257+- MODEL_PATH:修改为训练Qwen3-32b权重路径,需要下载
258+- CKPTS_DIR:修改为保存权重路径
259+ 
260+```shell
261+#!/usr/bin/env bash
262+# ……
263+# Ray
264+NNODES=4
265+N_GPUS_PER_NODE=16
266+# Paths
267+MODEL_PATH=# 修改为训练Qwen3-32b权重路径,需要下载
268+CKPTS_DIR=./ckpt/Qwen3-32B-save # 保存权重的路径
269+# ……
270+```
271+ 
272+### 2.4 分析训练日志
273+ 
274+在训练模型的过程中,可以通过输出的日志,分析模型的训练过程,输出日志的格式如下所示。
275+ 
276+```shell
277+step:1 - actor/grad_norm:0.04106094129383564 -
278+……
279+critic/rewards/mean:-0.4141845703125 -
280+response_length/mean:7385.140625 -
281+……
282+prompt_length/mean:152.890625 -
283+……
284+timing_s/generate_sequences:1081.803466796875 -
285+timing_s/gen:1315.2451746799998 -
286+……
287+timing_s/update_actor:303.92059642999993 -
288+timing_s/step:1738.0274970199998 -
289+……
290+timing_per_token_ms/gen:0.17391938503519522 -
291+……
292+perf/throughput:69.3938963605546
293+……
294+```
295+ 
296+在理想情况下,critic/rewards/mean 指标大体趋势应随着训练的进行逐步提升(允许在一定范围内有些许波动)。
297+ 
298+## 3. AIS-Benchmark模型评测
299+ 
300+**跑通以下模型评测流程,单机 A3 \* 16卡即可。评测文件夹位于镜像的/examples/benchmark中**
301+ 
302+### 3.1 FSDP模型合并
303+ 
304+在之前的模型训练中,使用了 FSDP 后端训练模型,因此需要将各个卡上碎片化的权重,重新合并为完整的模型权重。执行以下命令,即可调用 veRL 仓库中提供的 FSDP 模型合并脚本,获取完整的模型权重。
305+ 
306+```shell
307+python -m verl.model_merger merge \
308+ --backend fsdp \
309+ --local_dir /path/to/global_step_{num}/actor \
310+ --target_dir /path/to/qwen3-32b-after-rl
311+```
312+ 
313+**backend:** 训练后端,选择 `fsdp`
314+**local_dir:** FSDP 模型权重本地路径,可以在训练配置的保存路径中选择对应 step 的目录。
315+**target_dir:** 合并后模型权重本地保存路径。
316+ 
317+### 3.2 数据集下载
318+ 
319+`/examples/benchmark/ais_bench/datasets/aime` 中下载aime数据集
320+ 
321+```shell
322+# linux服务器内,处于工具根路径下
323+cd /examples/benchmark/ais_bench/datasets
324+mkdir aime/
325+cd aime/
326+wget http://opencompass.oss-cn-shanghai.aliyuncs.com/datasets/data/aime.zip
327+unzip aime.zip
328+rm aime.zip
329+```
330+ 
331+在{工具根路径}/ais_bench/datasets目录下执行tree aime/查看目录结构,若目录结构如下所示,则说明数据集部署成功。
332+ 
333+```shell
334+# /examples/benchmark/ais_bench/datasets
335+aime
336+└── aime.jsonl
337+```
338+ 
339+### 3.3 启动评测任务
340+ 
341+**3.3.1 启动vllm serve推理服务端**
342+ 
343+通过以下命令拉起NPU服务端,需要修改的参数:model和tensor-parallel-size。
344+ 
345+- model:保存训练后权重转换完的huggingface模型地址;
346+- tensor-parallel-size:张量并行副本数,TP建议和训练时infer的配置保持一致;
347+- data-parallel-size:数据并行副本数,DP建议和训练时infer的配置保持一致,默认为1;
348+- port:可任意设置空闲端口;
349+ 
350+```python
351+python -m vllm.entrypoints.openai.api_server \
352+ --model="path/to/Qwen3-32B/" \
353+ --served-model-name auto \
354+ --gpu-memory-utilization 0.9 \
355+ --max-num-seqs 24 \
356+ --max-model-len 22528 \
357+ --max-num-batched-tokens 22528 \
358+ --enforce-eager \
359+ --trust-remote-code \
360+ --distributed_executor_backend=mp \
361+ --tensor-parallel-size 8 \
362+ --data-parallel-size 1 \
363+ --generation-config vllm \
364+ --port 6380
365+```
366+ 
367+**3.3.2 修改aisbench推理配置**
368+ 
369+修改评测配置文件:
370+ 
371+```
372+vim /examples/benchmark/ais_bench/benchmark/configs/models/vllm_api/vllm_api_general.py
373+```
374+ 
375+python文件内容如下,**host_port需与服务端的port一致**,根据模型配置修改max_seq_len和max_out_len,推理示例设置为2k推20k:
376+ 
377+```python
378+# vim /examples/benchmark/ais_bench/benchmark/configs/models/vllm_api/vllm_api_general.py
379+from ais_bench.benchmark.models import VLLMCustomAPI
380+ 
381+models = [
382+ dict(
383+ attr="service",
384+ type=VLLMCustomAPI,
385+ abbr='vllm-api-general',
386+ path="",
387+ model="",
388+ request_rate = 0,
389+ retry = 2,
390+ host_ip = "localhost",
391+ host_port = 6380,
392+ max_seq_len = 2048,
393+ max_out_len = 20480,
394+ batch_size=48,
395+ trust_remote_code=False,
396+ generation_kwargs = dict(
397+ temperature = 0.5,
398+ top_k = 10,
399+ top_p = 0.95,
400+ seed = None,
401+ repetition_penalty = 1.03,
402+ )
403+ )
404+]
405+```
406+ 
407+**3.3.3 启动aisbench推理客户端**
408+ 
409+另起一个窗口进行评测,开启评测命令:
410+ 
411+```
412+cd /examples/benchmark
413+ais_bench --models vllm_api_general --datasets aime2024_gen
414+```
415+ 
416+**多轮评测脚本(可选)**
417+ 
418+提供脚本以供多轮评测取平均值
419+ 
420+```shell
421+#!/bin/bash
422+# 评测任务下发脚本 run.sh 循环多次执行评测任务
423+COMMAND="ais_bench --models vllm_api_general --datasets aime2024_gen"
424+ 
425+# 循环执行16次
426+LOOP_TIMES=16
427+for ((i=1; i<=$LOOP_TIMES; i++)); do
428+ echo "第 $i 次执行:"
429+ eval $COMMAND
430+done
431+```
432+ 
433+### 3.4 评测结果
434+ 
435+**训练前:**
436+ 
437+| dataset | version | metric | mode | vllm-api-general |
438+| -------- | ------- | -------- | ---- | ---------------- |
439+| aime2024 | 187240 | accuracy | gen | 38.99 |
440+ 
441+**训练100步后:**
442+ 
443+| dataset | version | metric | mode | vllm-api-general |
444+| -------- | ------- | -------- | ---- | ---------------- |
445+| aime2024 | 187240 | accuracy | gen | 45.33 |
446+ 
447+**经过 DAPO 100步训练后模型在 AIME2024 数据集上的准确率提升了6.34%。**
448+ 
449+**可以在 /examples/benchmark/outputs/default/ 目录下查看推理结果和评测结果。**
450+ 
451+## 4. 更多模型训练支持
452+ 
453+进入 **`/examples/verl`** 文件,该路径下存在Qwen3-8b、Qwen3-30b-A3b、Qwen3-235b训练配置文件
454+ 
455+```
456+test_dapo_qwen3_235b_megatron_A3.sh
457+test_dapo_qwen3_30b_fsdp_A3_6k.sh
458+test_dapo_qwen3_8b_fsdp.sh
459+test_dapo_qwen3_8b_megatron.sh
460+```
461+ 
462+修改以上配置文件中的**权重和数据集路径**,打开其中一个训练配置文件如下
463+ 
464+```shell
465+#!/usr/bin/env bash
466+# ……
467+# Ray
468+NNODES=2
469+N_GPUS_PER_NODE=16
470+# Paths
471+MODEL_PATH=# 修改为训练Qwen3-30b-A3b权重路径,需要下载
472+CKPTS_DIR=./ckpt/Qwen3-30B-save # 保存权重的路径
473+TRAIN_FILE=${TRAIN_FILE:-"/examples/datasets/dapo-math-17k.parquet"}
474+TEST_FILE=${TEST_FILE:-"/examples/datasets/aime-2024.parquet"}
475+# ……
476+```
477+ 
478+**修改启动脚本中使用的训练用例路径以及节点与各节点NPU数量如下**
479+ 
480+```
481+# ……
482+# 修改为当前需要跑的用例路径
483+DEFAULT_SH="./test_dapo_qwen3_30b_fsdp_A3_6k.sh"
484+# ……
485+NNODES=2
486+NPUS_PER_NODE=16
487+# ……
488+```
489+ 
490+## 5. 注意事项
491+ 
492+镜像中verl文件夹路径为/examples/verl,已经打好了相应的patch。
493+若需要本地拉取verl文件,使用以下命令:
494+ 
495+```
496+git clone https://github.com/volcengine/verl.git
497+cd verl
498+git checkout 796871d7d092f7cbc6a64e7f4a3796f7a2217f5e
499+pip install -e .
500+cd ..
501+```
502+ 
503+此时verl文件夹中并没有打上相应的patch,需要在verl/verl/\_\_init\_\_.py中第65行加入以下命令:
504+ 
505+```
506+if is_npu_available:
507+ import verl_npu
508+ print("NPU_acceleration enabled for verl")
509+```
@@ -7,7 +7,7 @@
7## 7##
8| MindSpeed RL版本 | PyTorch版本 | torch_npu版本 | CANN版本 | Python版本 |8| MindSpeed RL版本 | PyTorch版本 | torch_npu版本 | CANN版本 | Python版本 |
9| ---------------- | ------------ |-----------| ---------- | ---------- |9| ---------------- | ------------ |-----------| ---------- | ---------- |
10-| master(主线) | 2.7.1 | 2.7.1 | 8.2.RC1 | Python3.10 |10+| master(主线) | 2.7.1 | 2.7.1 | 8.3.RC1 | Python3.10 |
11 11 
12## 1、安装 vllm 和 vllm-ascend12## 1、安装 vllm 和 vllm-ascend
13```bash13```bash
@@ -82,6 +82,11 @@ VERL_PATH=path_to_verl pip install -e .
82`dapo``grpo`目录提供与 `configs` 对应的执行脚本,运行时配置好该脚本中的 `DEFAULT_SH` 即可拉起82`dapo``grpo`目录提供与 `configs` 对应的执行脚本,运行时配置好该脚本中的 `DEFAULT_SH` 即可拉起
83 83 
84 84 
85+# 镜像使用
86+目前,昇腾社区的[昇腾镜像仓库](https://www.hiascend.com/developer/ascendhub/detail/2a71f71cb92643baa95e527b39088e0e)已正式上线镜像资源,为广大开发者提供便捷可用的镜像服务支持。
87+ 
88+镜像使用指南详见[verl_docker](./docs/verl_docker.md)
89+ 
85# 插件开发90# 插件开发
86 91 
87## 插件框架特性92## 插件框架特性