verl 昇腾 NPU 常见问题排查指南环境、性能分析与权重同步故障全解析【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verlverlHybridFlow在昇腾 NPU 上的训练与推理会遇到设备可见性、性能剖析、权重同步超限、非共享存储加载等特有故障。本文基于仓库中的 NPU 常见问题解答逐条还原问题现象、根因与解决方案并结合verl/源码与配置给出底层原理与可落地的调参建议。读完本文你将能独立定位 NPU 环境类错误、正确开启 profiler 采集并彻底解决update_weights_bucket_megabytes引发的权重传输断言失败。环境配置问题NPU 设备不可见问题现象torch_npu.npu.is_available()返回False即 PyTorch 侧无法感知任何昇腾设备。此时无论启动训练还是推理都会在初始化阶段报设备相关错误。解决方案按照“设备可见性 → Ray 变量 → 驱动状态”三步排查# 1. 检查设备可见性 echo $ASCEND_RT_VISIBLE_DEVICES # 2. 设置可见设备并禁用 Ray 自动设置 export ASCEND_RT_VISIBLE_DEVICES0,1,2,3,4,5,6,7 export RAY_EXPERIMENTAL_NOSET_ASCEND_RT_VISIBLE_DEVICES1 # 3. 检查驱动状态 npu-smi infoASCEND_RT_VISIBLE_DEVICES是昇腾侧的可见设备掩码其作用等价于 GPU 场景的CUDA_VISIBLE_DEVICESverl 在verl/utils/device.py、verl/plugin/platform/platform_npu.py中据此进行设备映射与 NPU 补丁加载。RAY_EXPERIMENTAL_NOSET_ASCEND_RT_VISIBLE_DEVICES1用于阻止 Ray 在创建 worker 时覆盖你手动设置的可见设备列表避免多机/多卡场景下设备分配错乱该变量在verl/utils/ray_utils.py及多个 NPU 启动脚本中被引用。npu-smi info输出若为空或报错说明 NPU 驱动/固件HDK未安装或未正常加载需回到昇腾环境安装环节处理。补充设备检测在 verl 中是自动化的is_npu_available()会根据 torch_npu 是否可导入自动判定设备类型并加载对应 NPU 适配补丁无需手动修改代码前提是环境变量与驱动正确。调试与诊断如何启用 NPU 性能分析verl 内置了面向昇腾的 profiler通过 actor 侧的tool_config.npu配置即可开启actor_rollout_ref.actor.profiler.tool_config.npu.discretetrue \ actor_rollout_ref.actor.profiler.tool_config.npu.contentsnpu,cpu \ actor_rollout_ref.actor.profiler.tool_config.npu.level1 \ actor_rollout_ref.actor.profiler.tool_config.npu.analysistrue各字段的语义与取值范围源码见 verl/utils/profiler/config.py 与 actor.yaml配置项含义可选值/默认值contents采集内容npu、cpu、memory、shapes、module、stack可组合为列表默认[]level采集级别详略程度level_none、level0、level1、level2默认level0analysis是否自动解析采集数据True/False默认Falsediscrete每个 task 独立 trace 数据库还是整步共享一个True/False默认False两点实践提示CPU 侧活动各 stage 的 mstx 标记本身是 CPU 事件无论如何都会采集contents中列cpu是冗余的其余选项按字面生效。discreteTrue时每个 task 拥有独立 trace便于按任务粒度对齐时间线discreteFalse时整个训练步的 worker 活动共享一条连续 trace适合观察全局调度。具体行为可参考 ascend_profiling.rst 及 profiler 模块源码。如何排查 NPU 训练失败排查步骤检查环境变量配置ASCEND_RT_VISIBLE_DEVICES、RAY_EXPERIMENTAL_NOSET_ASCEND_RT_VISIBLE_DEVICES等验证设备可见性npu-smi infotorch_npu.npu.is_available()检查 CANN 版本兼容性——安装指南中 CANN、torch_npu、MindSpeed 等组件版本是强绑定的例如当前文档对应的 CANN9.1.0/ torch_npu2.10.0.post4组合见 install_guidance.rst查看日志中的具体错误信息使用最小化示例复现问题如 quick_start.rst 中的小模型脚本。启用详细日志# VERL 框架日志 export VERL_LOGGING_LEVELDEBUG # 昇腾 NPU 日志0DEBUG, 1INFO, 2WARNING, 3ERROR export ASCEND_GLOBAL_LOG_LEVEL0 export ASCEND_SLOG_PRINT_TO_STDOUT1 # HCCL 通信日志 export HCCL_DEBUGINFOVERL_LOGGING_LEVELDEBUG会让 verl 各模块如verl/workers/rollout/vllm_rollout/bucketed_weight_transfer.py的 logger输出调试级信息便于观察权重同步、调度等内部细节。ASCEND_GLOBAL_LOG_LEVEL0与ASCEND_SLOG_PRINT_TO_STDOUT1将昇腾算子/CANN 日志输出到 stdoutHCCL_DEBUGINFO用于定位多卡通信集合通信问题。三者配合可覆盖“框架层 → 算子层 → 通信层”的完整日志链路。常见错误信息与解决方案torch_npu detected, but NPU device is not available or visible原因NPU 驱动未正确安装或设备对进程不可见。解决方案检查驱动安装状态npu-smi info与ASCEND_RT_VISIBLE_DEVICES设置确认与第一节一致后重试。KeyError: decoder.layers.0.self_attention.q_layernorm.weight原因MindSpeed 版本过低模型权重名映射HF 格式 → Megatron/MindSpeed 格式缺少对应键。解决方案将 MindSpeed 切换至2.3.0_core_r0.12.1。verl 在 NPU 上通过 install_vllm_mcore_npu.sh 等脚本安装 MindSpeed 适配层verl/workers/engine/mindspeed/下提供了带 LM Head / Value Head 的 MindSpeed 引擎实现版本不匹配时权重转换与q_layernorm等键名映射会失败。AssertionError: Weight ... is too large to fit in the bucket问题现象分布式训练权重同步阶段报错AssertionError: Weight model.embed_tokens.weight(torch.Size([151936, 4096]), torch.float32) is too large to fit in the bucket. Please increase rollout.update_weights_bucket_megabytes(2048 MB).原因模型某个权重张量的大小超过了权重传输 bucket缓冲区的默认容量 2048 MB。verl 在 RL 训练中需要把 actor 权重从 trainer 侧同步到 rollout 推理侧权重被分块打包进固定大小的通信 buffer 中批量传输当单个权重张量超过 bucket 大小时断言检查直接失败。该机制在源码中有两处关键实现verl/workers/rollout/vllm_rollout/bucketed_weight_transfer.py中BucketedWeightSender.async_send_weights会先把张量按 dtype 对齐后尝试塞入 bucketoffset weight.nbytes self.bucket_size放不下时触发断言并提示增大update_weights_bucket_megabytes非 shm 模式下超出 bucket 的大权重走_direct_send_large_weight直传通道shm 模式下则直接断言失败。bucket 大小统一由rollout.checkpoint_engine.update_weights_bucket_megabytes控制verl/checkpoint_engine/base.py#L332处bucket_size update_weights_bucket_megabytes 20verl/workers/engine_workers.py#L680与 sglang/trtllm rollout 中同样按 MB 换算为字节默认值 2048 定义在 rollout.py 及生成的 rollout.yaml 中。权重大小计算方法权重张量的内存占用字节 各维度大小的乘积 × 每个元素的字节数数据类型对应字节数torch.float32→ 4 字节torch.float16/torch.bfloat16→ 2 字节torch.int8→ 1 字节以报错中的model.embed_tokens.weight为例张量形状: torch.Size([151936, 4096]) 数据类型: torch.float32 (4 字节) 权重大小 151936 × 4096 × 4 2,483,027,968 字节 ≈ 2369 MB 默认 bucket 大小 2048 MB 2369 MB → 触发断言失败解决方案启动训练时增大update_weights_bucket_megabytes使 bucket 容量大于最大权重张量的内存占用actor_rollout_ref.rollout.checkpoint_engine.update_weights_bucket_megabytes4096参数值选择建议计算模型中最大权重张量的内存占用遍历模型所有参数找出nbytes最大的那个转换为 MB除以 1024²向上取整到 2 的幂次为便于内存分配和管理建议取最近的 2 的幂次如 2048、4096、8192 等。例如最大权重 2369 MB则取 4096 MB预留适当余量考虑内存对齐与运行时开销建议 bucket 至少为最大权重大小的 1.2~1.5 倍再向上取整到 2 的幂次注意内存限制bucket 大小直接影响 worker 节点内存占用设置过大会导致 OOM应在满足传输需求的前提下取尽量小的值。常见模型的推荐值模型规模典型最大权重形状推荐 bucket 大小7B (Qwen2 等)[151936, 4096] float324096 MB14B[152064, 5120] float324096 MB72B[152064, 8192] float328192 MB该参数在多卡/多机启动脚本中已有实践先例例如 run_qwen3_30b_a3b_megatron.sh 与 run_qwen3_235b_a22b_megatron.sh 均将update_weights_bucket_megabytes设置为 4096。非共享存储下 checkpoint 加载失败找不到 common.pt / .metadata / metadata.json问题现象verl Megatron 后端在非共享存储的多机环境下保存 checkpoint 正常但重新加载时报错提示找不到以下文件FileNotFoundError: common.pt FileNotFoundError: .metadata FileNotFoundError: metadata.json原因当前 checkpoint 机制对非共享存储的支持不完善具体表现为分布式训练权重是分节点保存的每个节点只保存自己负责的分片权重不会只在主节点保存全部权重但common.pt、.metadata、metadata.json等元数据文件仅保存在执行保存操作的节点上通常是 rank 0 所在节点其他节点本地没有这些文件加载 checkpoint 时每个节点都需要读取这些元数据文件来还原模型状态非共享存储下其他节点本地路径中不存在这些文件导致加载失败。临时解决方案手动将元数据文件从保存节点复制到所有其他节点# 假设 checkpoint 保存在 rank 0 节点的 /path/to/ckpt/ 目录下 # 将元数据文件从 rank 0 节点复制到其他所有节点 # 需要复制的文件 /path/to/ckpt/common.pt /path/to/ckpt/.metadata /path/to/ckpt/metadata.json # 示例使用 scp 复制到其他节点 scp /path/to/ckpt/common.pt node1:/path/to/ckpt/ scp /path/to/ckpt/.metadata node1:/path/to/ckpt/ scp /path/to/ckpt/metadata.json node1:/path/to/ckpt/ # 对所有节点重复上述操作注意事项每次保存 checkpoint 后都需要重新复制元数据文件因为保存操作可能更新这些文件的内容如果训练过程中频繁保存 checkpoint如按步数自动保存建议编写脚本在保存后自动触发复制避免遗漏长期方案应等待框架层面支持非共享存储的 checkpoint 加载使元数据文件能自动同步到所有节点。参考资料与更多帮助昇腾性能调优指南面向 NPU 的训练性能优化特性与算子融合建议昇腾快速上手说明基于 GRPO/DAPO 在 NPU 上跑通最小示例NPU-CI 添加指导为 NPU 场景接入持续集成测试昇腾 NPU 文档与 CANN 工具包文档可在昇腾官方站点查阅 HDK/CANN 安装、算子与通信库的详细说明。如果以上 FAQ 无法解决问题建议查看完整的错误日志结合上文的三层日志开关在 GitHub Issues 中搜索类似问题提供详细的错误信息和环境配置CANN、torch_npu、MindSpeed 版本等提供最小可复现示例便于社区快速定位。【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考