cann-recipes-train 实战：Qwen2.5 GRPO 单卡云环境部署指南——verl 框架下昇腾 NPU 的 vLLM 0.13.0 兼容路径-北京尧图网络

cann-recipes-train 实战Qwen2.5 GRPO 单卡云环境部署指南——verl 框架下昇腾 NPU 的 vLLM 0.13.0 兼容路径【免费下载链接】cann-recipes-train本项目针对LLM与多模态模型训练业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-train本文是一份基于 CANN 平台的单卡昇腾 NPU 强化学习实战指南核心目标是帮助开发者在云环境单卡Ascend Atlas 910B2C上通过 verl 框架完成 Qwen2.5-1.5B-Instruct 模型在 MATH-lighteval 数据集上的 GRPO 训练。文章完整覆盖从 Docker 环境拉起、依赖安装、vLLM 0.13.0 兼容性适配、权重与数据准备、训练脚本配置到启动训练与验证的全流程读者照此即可在单卡云环境复现整套 RL 训练链路。一、背景与适用场景为什么需要 vLLM 0.13.0 兼容路径本样例位于仓库llm_rl/qwen2_5/verl_npu_demo/目录默认主文档 README.md 所描述的依赖栈基于vLLM 0.9.1。而在实际单卡云环境中不同厂商镜像预装的 CANN 与 Python 版本差异较大直接沿用默认依赖栈可能出现依赖解析冲突或 API 路径不兼容问题。本文档对应的配套说明文件为 README_single_card_cloud_vllm0.13.0.md补充的是一条单卡云环境 vLLM 0.13.0的兼容部署路径两者关系如下如果你使用官方 README 默认的 vLLM 0.9.1 依赖栈优先参考 README.md如果你希望在单卡云环境中按 vLLM 0.13.0 路径完成部署、训练和验证则需按下文步骤做额外适配。该路径的实测环境信息如下项目配置NPUAscend Atlas 910B2C单卡部署方式DockerCANN8.2.RC1模型Qwen2.5-1.5B-Instruct数据集MATH-lighteval训练算法GRPO兼容路径vLLM 0.13.0二、启动 Docker 容器在单卡云环境中建议直接使用经过验证的 CANN 8.2.RC1 容器镜像并显式设置--shm-size避免共享内存过小导致 RL 训练中 vLLM 引擎初始化失败docker run -d -it \ --name qwen-grpo \ --shm-size8g \ --device/dev/davinci0 \ --device/dev/davinci_manager \ --device/dev/devmm_svm \ --device/dev/hisi_hdc \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \ -v /usr/local/Ascend/add-ons:/usr/local/Ascend/add-ons \ ascendhub.huawei.com/public-ascendhub/cann:8.2.RC1-910b-openeuler22.03-py3.11 \ /bin/bash进入容器docker exec -it qwen-grpo bash参数说明--device/dev/davinci0映射单张昇腾 NPU 设备单卡场景只需一个 davinci 设备节点--device/dev/davinci_manager、/dev/devmm_svm、/dev/hisi_hdc昇腾驱动运行所需的设备节点-v /usr/local/Ascend/driver与-v /usr/local/Ascend/add-ons挂载宿主驱动与算子扩展保证容器内 CANN 运行时可用--shm-size8g扩容/dev/shmvLLM 引擎与 verl 的 Ray 任务对共享内存有较高需求。三、安装依赖先铺齐项目 requirements再统一固定核心版本单卡云环境依赖安装的核心原则是先安装项目自身 requirements再在最后统一固定核心兼容依赖其中 vLLM 相关建议按vllm - vllm-ascend的顺序安装。这样安排的原因在于requirements.txt与requirements-npu.txt中的依赖解析可能覆盖此前手动安装的核心版本后续全部兼容性修改都建立在vLLM 0.13.0 transformers 4.57.6这组版本组合之上必须保证最终生效版本与之对齐vllm-ascend依赖vllm并会带出所需的torch_npu/torch依赖链因此显式先装vllm再装vllm-ascend更稳妥不使用--force-reinstall避免引入不必要的重复重装。3.1 下载项目代码先获取样例工程再进入本地verl目录并固定到经过验证的提交版本保证后续兼容性适配与训练脚本修改有明确代码基线git clone https://gitcode.com/cann/cann-recipes-train.git cd cann-recipes-train/llm_rl/qwen2_5/verl_npu_demo如果当前verl_npu_demo/verl/目录下还没有 verl 源码则单独拉取并固定版本git clone https://github.com/volcengine/verl.git cd verl git checkout 634bd935 cd ..3.2 先安装项目 requirements让项目依赖先把通用 Python 库铺齐pip install -r requirements.txt cd verl pip install -r requirements-npu.txt cd ..仓库 requirements.txt 中主要包含math_verify、latex2sympy2_extended新奖励函数依赖、ray[default]verl 分布式运行时、tensordictRL 数据缓冲、datasets、pyarrow以及swanlab/tensorboard等可视化组件这些都属于训练链路的基础依赖先行安装不会与核心版本冲突。3.3 最后统一固定核心兼容依赖这一步必须放在最后执行避免前面的 requirements 再次覆盖关键版本# 配置 PyTorch CPU wheel 源 pip config set global.index-url https://download.pytorch.org/whl/cpu # 固定核心兼容依赖 pip install torch2.8.0cpu pip install torch_npu2.8.0 pip install torchvision0.23.0cpu pip install transformers4.57.6 pip install ray2.41.0 pip install sympy1.13.3 pip install gguf0.18.0 pip install compressed-tensors0.12.2 # 卸载 uvloop避免 asyncio 冲突 # 注意放到最后防止前面的 requirements 又把它装回来 pip uninstall -y uvloop # vLLM 相关按顺序安装先 vllm再 vllm-ascend pip install vllm0.13.0 pip install vllm-ascend0.13.0各核心依赖的用途说明torch2.8.0cpu与torch_npu2.8.0昇腾 NPU 上 torch 与 torch_npu 版本必须严格对齐此处统一为 2.8.0torchvision0.23.0cpu与 torch 2.8.0 配套的 torchvision 版本transformers4.57.6与 vLLM 0.13.0 兼容的 transformers 版本也是后续导入适配的前提ray2.41.0verl 依赖 Ray 做训练任务调度sympy、gguf、compressed-tensorsvLLM 推理链路所需的符号计算、模型格式与压缩支持卸载uvloop避免其在 Ray 的 asyncio 事件循环上引发冲突。3.4 安装本地源码基于当前环境安装本地 verl 源码使用--no-deps避免再次触发依赖解析cd verl pip install -e . --no-deps cd ..保留--no-deps是为了确保本地源码安装不会改变上一步已经固定好的版本组合。3.5 可选使用 constraints 文件进一步锁定版本如需更高复现稳定性可额外准备constraints.txt内容如下torch2.8.0cpu torch_npu2.8.0 torchvision0.23.0cpu transformers4.57.6 ray2.41.0 sympy1.13.3 gguf0.18.0 compressed-tensors0.12.2 vllm-ascend0.13.0安装命令相应变为pip install -c constraints.txt -r requirements.txt cd verl pip install -c ../constraints.txt -r requirements-npu.txt cd ..这样可以在 requirements 解析阶段就直接限制核心版本从源头避免依赖漂移。四、兼容性适配让 verl 适配 vLLM 0.13.0 transformers 4.57.6由于采用了 vLLM 0.13.0 transformers 4.57.6 的依赖组合需要对 verl 源码做三处兼容性修改。以下命令均在cann-recipes-train/llm_rl/qwen2_5/verl_npu_demo/verl目录下执行。注意区分外层目录verl_npu_demo/verl/verl 工程根与内层源码包目录verl_npu_demo/verl/verl/Python 包先cd进入明确目录再执行cat命令避免写错路径。4.1 补齐 NPU 工具函数文件新建文件./verl/workers/engine/fsdp/npu_padding_utils.py提供昇腾 NPU 上的 padding/unpadding 工具函数替代新版 transformers 中已迁移或缺失的npu_flash_attention接口cat ./verl/workers/engine/fsdp/npu_padding_utils.py EOF import torch from einops import rearrange as einops_rearrange def index_first_axis(x, indices): return x[indices] def pad_input(hidden_states, indices, batch, seqlen): output torch.zeros( batch * seqlen, *hidden_states.shape[1:], dtypehidden_states.dtype, devicehidden_states.device ) output[indices] hidden_states return output.view(batch, seqlen, *hidden_states.shape[1:]) def rearrange(tensor, pattern): return einops_rearrange(tensor, pattern) def unpad_input(hidden_states, attention_mask): seqlens_in_batch attention_mask.sum(dim-1, dtypetorch.int32) indices torch.nonzero(attention_mask.flatten(), as_tupleFalse).flatten() max_seqlen_in_batch seqlens_in_batch.max().item() cu_seqlens torch.nn.functional.pad( torch.cumsum(seqlens_in_batch, dim0, dtypetorch.int32), (1, 0) ) return ( index_first_axis(hidden_states.view(-1, *hidden_states.shape[2:]), indices), indices, cu_seqlens, max_seqlen_in_batch, ) EOF该文件实现了unpad_input按 attention mask 将 padding 后的序列还原为变长序列同时输出cu_seqlens与 batch 内最大序列长度与pad_input反向补齐是 FSDP 训练引擎处理变长 batch 的关键支撑。4.2 调整 transformers 相关导入将以下 5 个文件中的transformers.integrations.npu_flash_attention导入路径替换为上述本地兼容实现./verl/workers/engine/fsdp/transformer_impl.py./verl/workers/actor/dp_actor.py./verl/trainer/fsdp_sft_trainer.py./verl/workers/critic/dp_critic.py./verl/workers/fsdp_workers.py执行命令sed -i s/from transformers.integrations.npu_flash_attention import/from verl.workers.engine.fsdp.npu_padding_utils import/g \ ./verl/workers/engine/fsdp/transformer_impl.py \ ./verl/workers/actor/dp_actor.py \ ./verl/trainer/fsdp_sft_trainer.py \ ./verl/workers/critic/dp_critic.py \ ./verl/workers/fsdp_workers.py4.3 调整 vLLM 0.13.0 API 路径vLLM 0.13.0 相对旧版本发生了 API 迁移需要做三处替换sed -i s/CompilationLevel/CompilationMode/g \ ./verl/workers/rollout/vllm_rollout/vllm_rollout_spmd.py sed -i s/from vllm.worker.worker_base/from vllm.v1.worker.worker_base/g \ ./verl/workers/rollout/vllm_rollout/vllm_rollout_spmd.py sed -i s/from vllm.lora.models/from vllm.lora.lora_model/g \ ./verl/utils/vllm/utils.py替换含义CompilationLevel→CompilationMode对齐 vLLM 0.13.0 的编译模式枚举命名vllm.worker.worker_base→vllm.v1.worker.worker_basevLLM 0.13.0 默认启用 V1 引擎worker 基类迁移至vllm.v1命名空间这也与训练脚本中VLLM_USE_V11的环境变量设置一致vllm.lora.models→vllm.lora.lora_modelLoRA 模型模块路径调整。五、准备权重建议在verl_npu_demo/verl/目录下下载模型权重cd cann-recipes-train/llm_rl/qwen2_5/verl_npu_demo/verl hf download Qwen/Qwen2.5-1.5B-Instruct --local-dir model/Qwen2_5_1_5B_Instruct/如果访问 Hugging Face 较慢可先切换镜像站export HF_ENDPOINThttps://hf-mirror.com hf download Qwen/Qwen2.5-1.5B-Instruct --local-dir model/Qwen2_5_1_5B_Instruct/权重下载完成后模型文件位于verl_npu_demo/verl/model/Qwen2_5_1_5B_Instruct/。5.1 替换 Tokenizer 配置文件本样例对 tokenizer 做了定制见仓库中的 tokenizer_config.json其 chat_template 中为系统提示注入了think与answer标签的输出规范指令并在additional_special_tokens中声明了|im_start|、|im_end|等 Qwen2 系列特殊 token。这一步需在模型权重下载完成后执行用样例定制配置覆盖模型自带的 tokenizer 配置cp ../tokenizer_config.json ./model/Qwen2_5_1_5B_Instruct/tokenizer_config.json从 tokenizer_config.json 可以看到其 chat_template 要求模型在回答时先输出think内的推理过程再以\boxed{}形式在answer内输出最终答案——这正是下文中新奖励函数评分所依赖的格式约定。六、准备数据数据处理方式与官方 README 保持一致使用 verl 自带的预处理脚本在线获取 MATH-lighteval 数据集并处理成 verl 所需格式train.parquet与test.parquet。此前文档曾直接使用./data/math/raw/train.jsonl与./data/math/raw/test.jsonl作为输入参数但未说明获取方式容易引起歧义本文档统一改为与官方 README 一致的调用方式。在verl_npu_demo/verl目录下执行cd cann-recipes-train/llm_rl/qwen2_5/verl_npu_demo/verl/examples/data_preprocess python3 math_dataset.py --local_dir ../../data/math/data执行完成后会在verl_npu_demo/verl/data/math/data/目录下生成训练所需的train.parquet与test.parquet。6.1 无法联网时的离线准备方式如果当前环境无法访问 Hugging Face可先手动下载数据集cd cann-recipes-train/llm_rl/qwen2_5/verl_npu_demo/verl hf download DigitalLearningGmbH/MATH-lighteval --repo-typedataset --local-dir data/math将数据集文件放到verl_npu_demo/verl/data/math/路径下后再参考官方 README 附录的方式把examples/data_preprocess/math_dataset.py中的datasets.load_dataset(...)从在线加载改为本地 parquet 加载verl 较新版本可通过--local_dataset_path参数直接指定本地原始 parquet 目录无需修改源码然后重新执行cd examples/data_preprocess python3 math_dataset.py --local_dir ../../data/math/data七、配置训练脚本在启动训练前需要完成奖励函数替换并将单卡运行参数和 NPU 相关配置正确写入训练脚本。以下命令建议在cann-recipes-train/llm_rl/qwen2_5/verl_npu_demo/verl目录下执行。7.1 替换奖励函数将仓库定制的奖励函数复制到 verl 的 reward_score 目录cp ../new_math_reward.py ./verl/utils/reward_score/new_math_reward.py7.2 将训练脚本移动到 verl/ 目录训练脚本run_qwen2_5_1_5b.sh需要放在verl_npu_demo/verl/下执行若脚本仍在上一层目录可先移动mv ../run_qwen2_5_1_5b.sh ./run_qwen2_5_1_5b.sh7.3 替换参数不要直接用 cat 追加此前使用cat run_qwen2_5_1_5b.sh只是把新参数追加到文件末尾不能保证原有参数被替换。如果脚本中前面已有同名参数最终生效值可能不是预期值。建议改为替换已有参数补充缺失环境变量的方式# 替换单卡相关参数按键名替换原值 sed -i s/^trainer\.n_gpus_per_node.*/trainer.n_gpus_per_node1 \\/ run_qwen2_5_1_5b.sh sed -i s/^actor_rollout_ref\.rollout\.tensor_model_parallel_size.*/actor_rollout_ref.rollout.tensor_model_parallel_size1 \\/ run_qwen2_5_1_5b.sh sed -i s/^actor_rollout_ref\.model\.use_shm.*/actor_rollout_ref.model.use_shmFalse \\/ run_qwen2_5_1_5b.sh # 若缺失则追加 NPU 环境变量 grep -q ^export VLLM_ASCEND_ENABLE_NZ run_qwen2_5_1_5b.sh || echo export VLLM_ASCEND_ENABLE_NZ0 run_qwen2_5_1_5b.sh grep -q ^export PYTORCH_CUDA_ALLOC_CONF run_qwen2_5_1_5b.sh || echo export PYTORCH_CUDA_ALLOC_CONFmax_split_size_mb:512 run_qwen2_5_1_5b.sh grep -q ^export OMP_NUM_THREADS run_qwen2_5_1_5b.sh || echo export OMP_NUM_THREADS4 run_qwen2_5_1_5b.sh各配置项的作用VLLM_ASCEND_ENABLE_NZ0关闭 FRACTAL_NZ 相关影响降低 RL 场景下的精度风险PYTORCH_CUDA_ALLOC_CONFmax_split_size_mb:512优化内存分配行为减少碎片化OMP_NUM_THREADS4控制线程数量降低单卡多进程间的资源争抢trainer.n_gpus_per_node1单卡训练actor_rollout_ref.rollout.tensor_model_parallel_size1关闭多卡并行切分假设actor_rollout_ref.model.use_shmFalse规避共享内存相关问题。7.4 参考单卡训练脚本的完整参数基线仓库中已提供一份适配单卡的完整脚本 run_qwen2_5_1_5b_single.sh其核心训练参数可作为配置基线参考algorithm.adv_estimatorgrpo优势估计器使用 GRPO无需 Critic 网络data.train_batch_size256、data.max_prompt_length512、data.max_response_length1024训练 batch 与序列长度配置data.filter_overlong_promptsTrue、data.truncationerror超长样本处理策略custom_reward_function.path./verl/utils/reward_score/new_math_reward.py调用样例定制奖励函数actor_rollout_ref.actor.optim.lr1e-6、lr_warmup_steps10学习率与 warmupactor_rollout_ref.actor.use_kl_lossTrue、kl_loss_coef0.001、kl_loss_typelow_var_klKL 约束actor_rollout_ref.rollout.namevllm、gpu_memory_utilization0.8、n8使用 vLLM 引擎采样每个 prompt 生成 8 条 response 供 GRPO 分组比较actor_rollout_ref.rollout.enforce_eagerTrue单卡路径下关闭 CUDA Graph 相关图模式trainer.devicenpu显式指定训练设备为昇腾 NPUtrainer.n_gpus_per_node1、trainer.nnodes1单机单卡trainer.total_epochs5、trainer.save_freq70训练总轮数与 checkpoint 保存频率。八、启动训练先确保当前目录位于cann-recipes-train/llm_rl/qwen2_5/verl_npu_demo/verlmkdir -p run_log bash run_qwen2_5_1_5b.sh训练脚本内部通过python3 -m verl.trainer.main_ppo启动主训练入口并配合脚本头部的昇腾环境变量ASCEND_RT_VISIBLE_DEVICES、HCCL_*超时与端口配置、ASCEND_GLOBAL_LOG_LEVEL3等完成 NPU 运行时初始化日志通过tee ./run_log/qwen2_5_1_5b_math.log同时输出到终端与日志文件。九、观察训练状态建议同时观察日志和 NPU 状态确认训练是否已稳定进入运行阶段。查看训练日志tail -f run_log/qwen2_5_1_5b_math.log查看 NPU 状态watch -n 1 npu-smi info如果训练已经正常跑起来一般可以看到日志持续滚动AICore 使用率较高HBM 占用持续上升并保持稳定训练脚本能够进入持续执行状态。十、训练完成后的验证建议如果只看到训练启动成功还不能算整条链路完全闭环。建议在训练完成后继续接入验证流程例如使用 OpenCompass 对基模和强化学习后模型进行对比测试确认最终效果提升是否符合预期。若已沿用原样例的验证流程可继续参考 README.md 中的 OpenCompass 相关说明将训练得到的 checkpoint 通过verl.model_merger merge合并为完整权重后使用同一测试数据分别对基模与 RL 模型进行对比测试--datasets math_gen_a58d9d数据格式转换可使用仓库中的 parquet2json.py它会将含problem/level/type/solution字段的 parquet 转换为 OpenCompass 所需的math.json格式。十一、版本检查防止核心依赖漂移为在安装结束后快速确认核心依赖没有发生漂移建议额外执行python - EOF import torch import transformers import sympy import ray print(torch:, torch.__version__) print(transformers:, transformers.__version__) print(sympy:, sympy.__version__) print(ray:, ray.__version__) EOF pip show torch_npu pip show vllm-ascend pip show compressed-tensors pip show gguf如果输出结果与本文档固定版本torch/torch_npu 2.8.0、transformers 4.57.6、ray 2.41.0、vllm/vllm-ascend 0.13.0等不一致建议不要直接继续训练而是先排查是否被requirements或其他安装步骤重新覆盖。十二、源码级补充本样例定制奖励函数的设计原理虽然部署文档聚焦于跑起来但理解训练脚本引用的 new_math_reward.py 有助于判断训练日志中奖励曲线的合理性它是本样例 GRPO 训练效果的关键。verl 原生 MATH 奖励函数仅做字符串等价性判断在数学含义等价但形式不同如0.25与1/4时会产生误判且只输出 0/1 二元奖励信号过于稀疏。本样例从三个维度重新设计答案正确性优先0.7 分compute_accuracy_score使用math_verify的parse/verify做数学语义级等价判断同时支持 Latex 与表达式两种抽取模式并启用boxedall归一化答案正确得 0.7 分只要答案错误accuracy_score 0.7总分直接为 0格式与思维链奖励一律不计。这一正确性优先原则防止模型钻格式奖励的空子。格式规范性0.2 分compute_format_score检查think//think、answer//answer四组标签是否各出现一次每组 0.05 分同时校验标签顺序如/think出现在think前、answer在/think前等视为非法并对think前或/answer后的多余文本按长度扣分每字符 0.001上限 0.1。思维链完整性0.1 分compute_cot_score解析think内文本匹配Step 1:、1.、(1)等编号模式并检查是否从 1 开始连续递增同时统计solve、equation、therefore等推理关键词连续步骤 ≥3 且关键词 ≥2 得 0.1 分≥2 步且 ≥1 关键词得 0.05 分。奖励函数总分结构为正确性 0.7 格式 0.2 思维链 0.1 1.0通过稀疏二元信号 → 多维分级信号的设计缓解了奖励稀疏问题同时引导模型输出规范、可验证的推理过程。该函数通过训练脚本中custom_reward_function.path参数被 verl 的 reward 模块动态加载无需改动 verl 主框架代码。结语本文完整覆盖了 verl 框架在单卡昇腾 NPU 云环境上的 vLLM 0.13.0 兼容部署路径从 CANN 8.2.RC1 容器拉起到先铺齐 requirements、再统一固定核心版本的依赖安装策略再到npu_padding_utils.py补齐与 vLLM API 路径替换的源码适配最后完成权重/数据准备、训练脚本配置、启动训练与版本校验。配合仓库中的 run_qwen2_5_1_5b_single.sh、new_math_reward.py 与 tokenizer_config.json即可在单卡环境完整复现数据准备 → GRPO 训练 → 效果验证的强化学习闭环。【免费下载链接】cann-recipes-train本项目针对LLM与多模态模型训练业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-train创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

cann-recipes-train 实战：Qwen2.5 GRPO 单卡云环境部署指南——verl 框架下昇腾 NPU 的 vLLM 0.13.0 兼容路径

相关推荐

从分布式人工智能到多Agent协作：DAI三分支与Agent架构全解析

FAIRChem 自定义数据集构建指南：使用 ASE 数据库与 ASE 可读文件训练与推理

DeepSeek开发环境配置指南：API与本地部署选型实战

更多资讯

为什么 coding agent 大多基于 Node.js？工程现实解析

小红书服饰营销通案的技术拆解：从数据采集到效果归因

C#调用DeepSeek实现多模态AI：图像描述与文本分类工程实践

六问Codex 智能体工厂：TaoToken Key 到底谁消耗

基于CGAN-LSTM的无监督网络异常流量检测算法解析

kohya_ss新手完整指南：从安装到训出第一张图的四步LoRA实操

今日更新

AReaL 调试指南：从 Agent Workflow 验证到分布式训练死锁诊断

MATLAB实现GPS L1 C/A信号仿真与二维捕获验证

彻底搞懂ASCII、Unicode与UTF-8：从乱码根源到编码实战

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？