ms-swift GRPO 训练实战指南算法原理、Colocate/Async 双模式部署与参数详解【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift本文基于 ms-swift 仓库中的 GRPO 官方文档GRPO.md系统讲解 GRPOGroup Relative Policy Optimization强化学习训练。读完本文你将理解 GRPO 的目标函数与组内相对优势机制掌握swift rlhf/swift rollout两套命令在 Colocate 与 Async 两种部署模式下的完整启动方式并学会在显存受限的集群上通过 sleep、offload、LoRA 权重同步等手段把训练跑稳。算法原理用组内相对优势替代价值模型GRPO 算法利用组内相对优势计算来替代 PPO 中独立的价值模型value model并直接在损失函数中加入 KL 散度惩罚以提高训练稳定性。其目标函数为$$ \mathcal{J}{GRPO}(\theta) \mathbb{E}{\left[q \sim P(Q),\left{o_i\right}{i1}^G \sim \pi{\theta_{old}}(O \mid q)\right]} \frac{1}{G} \sum_{i1}^G \frac{1}{\left|o_i\right|} \sum_{t1}^{\left|o_i\right|} \left{ \min \left[\frac{\pi_\theta\left(o_{i,t} \mid q, o_{i,t}\right)}{\pi_{\theta_{old}}\left(o_{i,t} \mid q, o_{i,t}\right)} \hat{A}{i,t},\ \operatorname{clip}\left(\frac{\pi\theta\left(o_{i,t} \mid q, o_{i,t}\right)}{\pi_{\theta_{old}}\left(o_{i,t} \mid q, o_{i,t}\right)}, 1-\varepsilon, 1\varepsilon\right) \hat{A}_{i,t}\right] -\beta \mathbb{D}_{KL}\left[\pi_\theta | \pi_{ref}\right] \right} $$其中优势函数定义为一个 prompt 组内各样本奖励的标准化值$$ \hat{A}{i,t} \frac{R_i - \text{mean}({R_j}{j1}^G)}{\text{std}({R_j}_{j1}^G)} $$也就是说每个 prompt 采样出 G 个 completion用组内奖励的均值/标准差做归一化得到优势无需训练额外的 critic 网络。下面用一段伪代码完整还原 GRPO 的四个阶段Rollout 生成 → 奖励计算 → 策略优化 → 更新# 1. Rollout Generation Phase prompt Question: Which is bigger? 9.11 or 9.9? # Generate multiple completions through parallel sampling completions rollout_function( modelcurrent_policy_model, promptprompt, num_generations8, # Hyperparameter: number of samples per prompt temperature1.0 # Hyperparameter: sampling diversity ) completions [ (completion 1) The larger number is 9.9..., (completion 2) 9.11 is bigger than..., ... (completion 8) After calculation, 9.9... ] # 2. Reward Calculation Phase # Evaluate generated completions using reward model rewards reward_function( completionscompletions, ground_truth9.9 # Expected correct answer ) rewards [ (reward 1) 1.0, # Correct answer (reward 2) 0.0, # Incorrect ... (reward 8) 1.0 # Correct ] # Normalize rewards to advantages rewards_mean mean(rewards) # μ 0.5 rewards_std std(rewards) # σ 0.25 advantages (rewards - rewards_mean) / (rewards_std 1e-8) # Standardization advantages [ (advantage 1) 2.0, # (1.0 - 0.5)/0.25 (advantage 2) -2.0, ... (advantage 8) 2.0 ] # 3. Policy Optimization Phase # Get token-level log probabilities from different models current_logps get_per_token_logps(current_policy_model, prompt, completions) # π_θ old_logps get_per_token_logps(old_policy_model, prompt, completions) # π_θ_old ref_logps get_per_token_logps(reference_model, prompt, completions) # π_ref # PPO Clipped Objective is_ratio exp(current_logps - old_logps) # Importance sampling ratio: e^(π_θ - π_θ_old) clipped_ratio clip(is_ratio, 1-ε, 1ε) # ε0.2 typically # Policy gradient term (dual form) policy_loss -mean( minimum(is_ratio * advantages, # Unclipped objective clipped_ratio * advantages) # Clipped objective ) # KL Divergence Penalty (K3 estimator) # KL(π_θ||π_ref) ≈ e^(logπ_ref - logπ_θ) - (logπ_ref - logπ_θ) - 1 kl_penalty beta * mean( exp(ref_logps - current_logps) - (ref_logps - current_logps) - 1 ) # Total Loss Policy Loss KL Penalty total_loss policy_loss kl_penalty # 4. Update Rule # Apply gradient descent to minimize total_loss optimizer.zero_grad() total_loss.backward() optimizer.step()在 ms-swift 中上述逻辑由 grpo_trainer.py 实现KL 散度采用 K3 无偏估计器KL 项既可以作为独立损失项kl_in_rewardFalseGRPO 默认也可以直接并入奖励kl_in_rewardTrueRLOO/REINFORCE 默认相关定义可见 args_mixin.py。训练快速上手GRPO 训练通过swift rlhf --rlhf_type grpo启动完整训练脚本示例参考仓库 examples/train/grpo 目录。以多模态模型为例vllm_vl7b.sh 展示了一个典型的 8 卡 colocate 训练配置MAX_PIXELS1003520 \ NPROC_PER_NODE8 \ swift rlhf \ --rlhf_type grpo \ --model Qwen/Qwen2.5-VL-7B-Instruct \ --tuner_type lora \ --dataset AI-ModelScope/chartqa_digit_r1v_format \ --load_from_cache_file true \ --use_vllm true \ --vllm_mode colocate \ --vllm_gpu_memory_utilization 0.5 \ --vllm_tensor_parallel_size 4 \ --torch_dtype bfloat16 \ --system examples/train/grpo/prompt.txt \ --num_train_epochs 1 \ --per_device_train_batch_size 1 \ --per_device_eval_batch_size 1 \ --learning_rate 1e-6 \ --save_total_limit 2 \ --logging_steps 5 \ --output_dir output \ --gradient_accumulation_steps 1 \ --warmup_ratio 0.05 \ --dataloader_num_workers 4 \ --max_completion_length 1024 \ --reward_funcs accuracy format \ --num_generations 8 \ --sleep_level 1 \ --temperature 1.0 \ --top_p 0.85几个关键参数默认值来自 args_mixin.py 中GRPOArgumentsMixin的定义参数默认值说明epsilon0.2PPO 风格 clip 系数限制重要性采样比偏离范围epsilon_highNone上界 clip 系数设置后 clip 区间为[1-epsilon, 1epsilon_high]num_generations-每个 prompt 采样的 completion 数量Greward_funcs-奖励函数名列表内置实现见 orm.pybeta-KL 惩罚系数设为 0 时关闭 KL 损失且不加载 ref modelscale_rewardsgroup随advantage_estimator奖励缩放策略group/batch/none/gdpooverlong_filterFalse跳过因过长被截断的样本不计入 lossdynamic_sampleFalse过滤组内奖励标准差为 0 的 prompt 并重新采样max_resample_times3dynamic_sample开启时的最大重采样次数log_entropyFalse记录训练中 token entropy 动态top_entropy_quantile1.0仅让 entropy 处于指定分位以上的 token 参与 lossnum_generations_evalNone评估阶段采样数可为省算力单独设置更多 GRPO 与 vLLM/rollout 参数的完整说明可参考 Command-line-parameters.md 中的GRPO 参数小节以及 vLLM 参数 与 rollout 参数 小节。集群支持两种 vLLM 部署模式GRPO 训练框架支持集成 vLLM 等高性能推理引擎来加速采样过程提供两种部署模式。1. ColocateInternal模式训练与推理共享 GPU 资源在 Trainer 内部启动推理服务。启动参数--use_vllm true \ --vllm_mode colocate从源码结构看vllm_mode的取值为server/colocate二选一且在use_vllmfalse时设置vllm_mode会直接报错校验逻辑位于 rlhf_args.py该处还有一个细节当使用async_generate或vllm_modeserver时sleep_level会被强制置为 0外部/异步服务无需释放本地显存。Colocate 模式下的显存优化方案在 Colocate 模式下运行时容易出现显存不足OOM的情况。以下是几种有效的显存优化方法和参数配置参数定义见 args_mixin.py降低vllm_gpu_memory_utilization参数该参数默认 0.9控制 vLLM KV cache 占用的显存比例降低可为训练侧腾出空间上文示例即使用 0.5。在训练阶段释放 vLLM 占用的显存--sleep_level 1sleep_level默认 0不释放取值越大释放越多但可能有额外开销。 3.在 vLLM 推理阶段释放模型和优化器占用的显存--offload_optimizer true \ --offload_model true \二者默认均为 False开启后在推理前把优化器状态/模型权重卸载到 CPU。 4.在 vLLM 中使用 Tensor Parallel 技术--vllm_tensor_parallel_size [tp_size]将模型切分到多卡以降低单卡显存压力。 5.分批 Gather 模型权重zero3 下同步 vLLM 权重时--move_model_batches [批次数量]move_model_batches默认 None设置后可避免一次性 gather 全量权重导致的显存峰值。 6.将 Megatron 导出的用于 vLLM 更新的 HF 格式权重存放在 CPU 主存中以降低 GPU 显存占用--offload_bridge true2. AsyncExternal模式训练与推理资源分离启动单独的推理服务器。使用swift rollout命令部署 vLLM 服务器现仅支持 vLLM backend命令入口见 rollout.py以下三个示例分别演示不同卡数下的 TP/DP 组合CUDA_VISIBLE_DEVICES0 \ swift rollout \ --model Qwen/Qwen2.5-VL-7B-Instruct \ --vllm_tensor_parallel_size 2 \ --vllm_data_parallel_size 1 CUDA_VISIBLE_DEVICES0,1 \ swift rollout \ --model Qwen/Qwen2.5-VL-7B-Instruct \ --vllm_tensor_parallel_size 2 \ --vllm_data_parallel_size 1 CUDA_VISIBLE_DEVICES0,1,2,3 \ swift rollout \ --model Qwen/Qwen2.5-VL-7B-Instruct \ --vllm_tensor_parallel_size 2 \ --vllm_data_parallel_size 2注意在使用vllm_use_async_engine时仅开启 DP 可能会导致错误对应 vLLM 上游 issue #18567。如果出现错误请尝试同时启用 TP 和 DP或升级 vLLM。训练侧使用以下参数配置外部 vLLM 服务器--use_vllm true \ --vllm_mode server \ --vllm_server_host 服务器IP \ --vllm_server_port 服务端口 \ --vllm_server_timeout 超时时间 \相关默认值vllm_server_port默认[8000]vllm_server_timeout默认 240 秒若设置了vllm_server_base_url如http://localhost:8000则 host/port 会被忽略见 args_mixin.py。完整的外部模式训练脚本可参考 examples/train/grpo/external多机混合部署示例在 examples/train/grpo/multi_node。权重同步加速设置以下参数可以通过仅同步 LoRA adapter 权重而非全量模型权重优化 LoRA 训练的权重同步速度。注意这种同步方式会略微影响 vLLM 推理速度。# rollout(server mode) swift rollout \ --vllm_enable_lora true \ --vllm_max_lora_rank xxx # 与训练脚本lora_rank一致 ... # grpo(colocate mode) swift rlhf \ --rlhf_type grpo \ --vllm_mode colocate \ --vllm_enable_lora true \ ... # megatron grpo(colocate mode) swift megatron rlhf \ --rlhf_type grpo \ --vllm_mode colocate \ --vllm_enable_lora true \ ...其中vllm_enable_lora默认 Falsevllm_max_lora_rank默认 16lora_rankcolocate 模式下 vLLM 加载的 LoRA 秩默认 8设置时应大于等于理想等于训练脚本的 LoRA rank。多模态模型 ViT 层 LoRA 同步如果训练时开启了 ViT 层的 LoRAfreeze_vit false在仅同步 LoRA 的模式下需要相应在 vLLM 侧开启 tower/connector LoRA 支持通过vllm_engine_kwargs传入--vllm_engine_kwargs {enable_tower_connector_lora: true}该功能为 vLLM 实验性特性目前支持 Qwen2.5-VL、Qwen3-VL 等模型具体支持情况请参阅 vLLM 官方文档与 issuevllm-project/vllm#31479。logged metrics训练过程中记录的指标及其含义如下可用于诊断采样质量、奖励分布与训推一致性Completion 长度指标completions/mean_length生成的 completion 的平均长度。completions/min_length生成的 completion 的最小长度。completions/max_length生成的 completion 的最大长度。completions/clipped_ratio被长度截断的 completion 占比。奖励指标reward/{reward_func_name}/mean某个特定 reward function 的平均奖励值。reward/{reward_func_name}/std某个特定 reward function 的奖励标准差。注意上述两个指标是在所有 completions 范围内统计得到的。reward加权reward_weights后的整体平均奖励。reward_std加权reward_weights后每个 batch 内整体奖励的标准差。注意上述两个指标是先在每个组内分别计算均值/std然后再对各组的结果取平均。frac_reward_zero_std在生成 batch 中reward 标准差为零的样本比例意味着该 prompt 上的答案几乎无多样性所有回答奖励一致这类样本对策略梯度没有贡献比例过高时建议开启dynamic_sample。kl生成的 completion 上模型与参考模型之间的平均 KL 散度。仅当 beta 非零时记录。Clip 指标clip_ratio/region_mean不同句子中被 CLIP 的 token 平均比例clip_ratio/low_mean不同句子中被下 CLIP 的 token 平均比例clip_ratio/low_min不同句子中被下 CLIP 的 token 最小比例clip_ratio/high_mean不同句子中被上 CLIP 的 token 平均比例clip_ratio/high_max不同句子中被上 CLIP 的 token 最大比例注意如果开启overlong_filterkl 和 clip_ratio 指标会过滤超长的样本。Entropy 指标设置log_entropy后记录entropy/mean不同句子中的 entropy 均值entropy/max不同句子中的 entropy 最大值entropy/min不同句子中的 entropy 最小值注意这里的句子 entropy 指 completion 中的 token entropy 均值。如果设置了top_entropy_quantile参数 1.0则会记录 entropy threshold 的值entropy/threshold分位点处的 entropy 值小于该值的 token 将不会被计算 loss。训推一致性指标前缀为rollout_correction需设置log_rollout_offpolicy_metricstrue或rollout_importance_sampling_mode实现见 grpo_algorithm.pykl/k3_kl训练策略与 rollout 策略之间的 KL 散度直接估计器 / K3 估计器training_ppl/rollout_ppl训练策略和 rollout 策略的困惑度log_ppl_difflog PPL 差异反映分布偏移程度ppl_ratioPPL 比率chi2_token/chi2_seqToken/Sequence 级别的 χ² 散度IS 校正指标需设置rollout_importance_sampling_modeis_weight_mean平均重要性采样权重ess有效样本大小Effective Sample Sizeclipped_frac被截断或屏蔽的样本比例训推一致性指标的详细说明请参考 Training-Inference-Mismatch 文档。训练动态记录如果设置了log_completions将保存训练动态在 output 对应文件夹中包括step记录时的训练步数prompt模型输入completion模型采样回答{reward_func_name}特定奖励entropyentropy token 均值在设置log_entropy时记录设置report_to wandb/swanlab将训练动态 Table 推送到对应的平台。如果需要在 Table 中额外记录其他列请在GRPOTrainer._generate_and_score_completions方法中设置metrics_to_gather字典。默认自动检测image视觉数据集图像输入暂时只支持 wandbsolution数据集中的 solution 列。FAQ1. 训练过程中 loss 等于 0 / 接近 0 / 小于 0正常情况。在 on-policy 训练中新旧策略相同重要性采样比恒为 1policy loss 本身接近 0甚至因数值误差为负这是社区广泛确认的行为参考 huggingface/open-r1#239。2. num_generations / 批量大小相关在 GRPO 中batch_size 以 completion模型生成结果为单位。例如设置per_device_train_batch_size8表示每张 GPU 在训练过程中会同时处理 8 个 completion 的 loss 计算。训练阶段在一次完整的梯度累计 batch 中总的批量大小等于effective_batch_size num_processes * per_device_train_batch_size * gradient_accumulation_steps采样阶段总的批量大小completion-level数量等于设置generation_batch_size下等于generation_batch_size设置steps_per_generation下等于per_device_train_batch_size * steps_per_generation * num_processes默认情况下steps_per_generation gradient_accumulation_stepsgeneration_batch_size per_device_train_batch_size * steps_per_generation * num_processes effective_batch_size在评估阶段completion 的数量等于num_processes * per_device_eval_batch_size参数num_generations必须能够被以上采样阶段和评估的总批量大小整除以保证生成任务可以均匀分配到各个设备上。这一整除约束在源码中被严格执行_init_generation_batch_params会对generation_batch_size、num_generations以及评估侧 batch size 做可整除性校验不满足时直接抛出 ValueError 并列出合法取值。示例num_processes 8、per_device_train_batch_size 4、gradient_accumulation_steps 8、generation_batch_size 512、num_generations 64采样需要的总数据prompt量等于 512 / 64 8每次采样 512 条模型回复每次更新模型权重批量大小为 8 × 4 × 8 2563. 为什么 KL 出现了 NaN开启overlong_filter后某一卡上的所有 completion 都被截断导致参与 KL 计算的样本为空出现 NaN。4. 训练的 steps 怎么计算可参考仓库 issue modelscope/ms-swift#3912 中的推导核心是总样本数 / effective_batch_size决定优化步数。5. clip_ratio 为什么总是 0Clip 机制的核心目的是限制策略更新的幅度防止因单次更新过大而导致策略性能崩溃即策略更新后表现急剧下降。Clip 操作的具体公式如下$$ L_{\text{CLIP}}(\theta) \mathbb{E}_{t} \left[ \min\left(r_{t}(\theta) \hat{A}{t}, \text{clip}(r{t}(\theta), 1 - \epsilon, 1 \epsilon) \hat{A}_{t} \right) \right] $$其中$r_{t}(\theta) \frac{\pi_{\theta}(a_{t} \mid s_{t})}{\pi_{\text{old}}(a_{t} \mid s_{t})}$ 是重要性采样比衡量新旧策略的差异$\hat{A}{t}$ 是优势函数advantage function表示动作的相对收益$\epsilon$ 用于限制 $r{t}(\theta)$ 的偏离范围。在 on-policy 训练过程中由于每次更新都使用最新策略生成的数据新旧策略相同即 $\pi_{\theta} \pi_{\text{old}}$因此重要性采样比恒为 1此时 clip 操作不会生效。在设置以下参数情况下算法为 off-policynear-on-policynum_iterations 1或者gradient_accumulation_steps % steps_per_generation ! 0此时新旧策略产生差异clip 才真正发挥作用。6. 如何设置训练的 mini-batch size在 GRPO 训练中可以通过以下两种方式配置 mini-batch 更新设置generation_batch_size为训练 global batch sizeeffective_batch_size的整数倍或设置steps_per_generation为gradient_accumulation_steps的整数倍典型配置示例当配置steps_per_generation 16, gradient_accumulation_steps 8, mini_batch_size steps_per_generation / gradient_accumulation_steps 2时1 次 rollout 结果将拆分成 2 批 mini-batch 进行更新。7. swift deploy 与 swift rollout 的区别swift deploy主要用于模型的部署和推理支持 Transformers、vLLM、SGLang 等多种引擎兼容流式推理与 OpenAI API 的调用格式。swift rollout则专注于 GRPO 推理加速目前仅支持 vLLM 引擎并内置了权重自动同步的功能。8. 如何取消 KL 项损失将参数设置为--beta 0即可关闭 KL 损失的计算并且不会加载参考模型ref model。延伸阅读完整训练脚本examples/train/grpo含 internal/external/multi_node 分类目录GRPO 参数、vLLM 参数、rollout 参数Command-line-parameters.md训推一致性Training-Inference-Mismatchtraining_inference_mismatch.md奖励函数开发reward_function.md、reward_model.md多轮 GRPO 与 Gym 环境multi_turn.md、gym_env.md参数默认值与校验逻辑args_mixin.py、rlhf_args.py【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ms-swift GRPO 训练实战指南：算法原理、Colocate/Async 双模式部署与参数详解
ms-swift GRPO 训练实战指南算法原理、Colocate/Async 双模式部署与参数详解【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift本文基于 ms-swift 仓库中的 GRPO 官方文档GRPO.md系统讲解 GRPOGroup Relative Policy Optimization强化学习训练。读完本文你将理解 GRPO 的目标函数与组内相对优势机制掌握swift rlhf/swift rollout两套命令在 Colocate 与 Async 两种部署模式下的完整启动方式并学会在显存受限的集群上通过 sleep、offload、LoRA 权重同步等手段把训练跑稳。算法原理用组内相对优势替代价值模型GRPO 算法利用组内相对优势计算来替代 PPO 中独立的价值模型value model并直接在损失函数中加入 KL 散度惩罚以提高训练稳定性。其目标函数为$$ \mathcal{J}{GRPO}(\theta) \mathbb{E}{\left[q \sim P(Q),\left{o_i\right}{i1}^G \sim \pi{\theta_{old}}(O \mid q)\right]} \frac{1}{G} \sum_{i1}^G \frac{1}{\left|o_i\right|} \sum_{t1}^{\left|o_i\right|} \left{ \min \left[\frac{\pi_\theta\left(o_{i,t} \mid q, o_{i,t}\right)}{\pi_{\theta_{old}}\left(o_{i,t} \mid q, o_{i,t}\right)} \hat{A}{i,t},\ \operatorname{clip}\left(\frac{\pi\theta\left(o_{i,t} \mid q, o_{i,t}\right)}{\pi_{\theta_{old}}\left(o_{i,t} \mid q, o_{i,t}\right)}, 1-\varepsilon, 1\varepsilon\right) \hat{A}_{i,t}\right] -\beta \mathbb{D}_{KL}\left[\pi_\theta | \pi_{ref}\right] \right} $$其中优势函数定义为一个 prompt 组内各样本奖励的标准化值$$ \hat{A}{i,t} \frac{R_i - \text{mean}({R_j}{j1}^G)}{\text{std}({R_j}_{j1}^G)} $$也就是说每个 prompt 采样出 G 个 completion用组内奖励的均值/标准差做归一化得到优势无需训练额外的 critic 网络。下面用一段伪代码完整还原 GRPO 的四个阶段Rollout 生成 → 奖励计算 → 策略优化 → 更新# 1. Rollout Generation Phase prompt Question: Which is bigger? 9.11 or 9.9? # Generate multiple completions through parallel sampling completions rollout_function( modelcurrent_policy_model, promptprompt, num_generations8, # Hyperparameter: number of samples per prompt temperature1.0 # Hyperparameter: sampling diversity ) completions [ (completion 1) The larger number is 9.9..., (completion 2) 9.11 is bigger than..., ... (completion 8) After calculation, 9.9... ] # 2. Reward Calculation Phase # Evaluate generated completions using reward model rewards reward_function( completionscompletions, ground_truth9.9 # Expected correct answer ) rewards [ (reward 1) 1.0, # Correct answer (reward 2) 0.0, # Incorrect ... (reward 8) 1.0 # Correct ] # Normalize rewards to advantages rewards_mean mean(rewards) # μ 0.5 rewards_std std(rewards) # σ 0.25 advantages (rewards - rewards_mean) / (rewards_std 1e-8) # Standardization advantages [ (advantage 1) 2.0, # (1.0 - 0.5)/0.25 (advantage 2) -2.0, ... (advantage 8) 2.0 ] # 3. Policy Optimization Phase # Get token-level log probabilities from different models current_logps get_per_token_logps(current_policy_model, prompt, completions) # π_θ old_logps get_per_token_logps(old_policy_model, prompt, completions) # π_θ_old ref_logps get_per_token_logps(reference_model, prompt, completions) # π_ref # PPO Clipped Objective is_ratio exp(current_logps - old_logps) # Importance sampling ratio: e^(π_θ - π_θ_old) clipped_ratio clip(is_ratio, 1-ε, 1ε) # ε0.2 typically # Policy gradient term (dual form) policy_loss -mean( minimum(is_ratio * advantages, # Unclipped objective clipped_ratio * advantages) # Clipped objective ) # KL Divergence Penalty (K3 estimator) # KL(π_θ||π_ref) ≈ e^(logπ_ref - logπ_θ) - (logπ_ref - logπ_θ) - 1 kl_penalty beta * mean( exp(ref_logps - current_logps) - (ref_logps - current_logps) - 1 ) # Total Loss Policy Loss KL Penalty total_loss policy_loss kl_penalty # 4. Update Rule # Apply gradient descent to minimize total_loss optimizer.zero_grad() total_loss.backward() optimizer.step()在 ms-swift 中上述逻辑由 grpo_trainer.py 实现KL 散度采用 K3 无偏估计器KL 项既可以作为独立损失项kl_in_rewardFalseGRPO 默认也可以直接并入奖励kl_in_rewardTrueRLOO/REINFORCE 默认相关定义可见 args_mixin.py。训练快速上手GRPO 训练通过swift rlhf --rlhf_type grpo启动完整训练脚本示例参考仓库 examples/train/grpo 目录。以多模态模型为例vllm_vl7b.sh 展示了一个典型的 8 卡 colocate 训练配置MAX_PIXELS1003520 \ NPROC_PER_NODE8 \ swift rlhf \ --rlhf_type grpo \ --model Qwen/Qwen2.5-VL-7B-Instruct \ --tuner_type lora \ --dataset AI-ModelScope/chartqa_digit_r1v_format \ --load_from_cache_file true \ --use_vllm true \ --vllm_mode colocate \ --vllm_gpu_memory_utilization 0.5 \ --vllm_tensor_parallel_size 4 \ --torch_dtype bfloat16 \ --system examples/train/grpo/prompt.txt \ --num_train_epochs 1 \ --per_device_train_batch_size 1 \ --per_device_eval_batch_size 1 \ --learning_rate 1e-6 \ --save_total_limit 2 \ --logging_steps 5 \ --output_dir output \ --gradient_accumulation_steps 1 \ --warmup_ratio 0.05 \ --dataloader_num_workers 4 \ --max_completion_length 1024 \ --reward_funcs accuracy format \ --num_generations 8 \ --sleep_level 1 \ --temperature 1.0 \ --top_p 0.85几个关键参数默认值来自 args_mixin.py 中GRPOArgumentsMixin的定义参数默认值说明epsilon0.2PPO 风格 clip 系数限制重要性采样比偏离范围epsilon_highNone上界 clip 系数设置后 clip 区间为[1-epsilon, 1epsilon_high]num_generations-每个 prompt 采样的 completion 数量Greward_funcs-奖励函数名列表内置实现见 orm.pybeta-KL 惩罚系数设为 0 时关闭 KL 损失且不加载 ref modelscale_rewardsgroup随advantage_estimator奖励缩放策略group/batch/none/gdpooverlong_filterFalse跳过因过长被截断的样本不计入 lossdynamic_sampleFalse过滤组内奖励标准差为 0 的 prompt 并重新采样max_resample_times3dynamic_sample开启时的最大重采样次数log_entropyFalse记录训练中 token entropy 动态top_entropy_quantile1.0仅让 entropy 处于指定分位以上的 token 参与 lossnum_generations_evalNone评估阶段采样数可为省算力单独设置更多 GRPO 与 vLLM/rollout 参数的完整说明可参考 Command-line-parameters.md 中的GRPO 参数小节以及 vLLM 参数 与 rollout 参数 小节。集群支持两种 vLLM 部署模式GRPO 训练框架支持集成 vLLM 等高性能推理引擎来加速采样过程提供两种部署模式。1. ColocateInternal模式训练与推理共享 GPU 资源在 Trainer 内部启动推理服务。启动参数--use_vllm true \ --vllm_mode colocate从源码结构看vllm_mode的取值为server/colocate二选一且在use_vllmfalse时设置vllm_mode会直接报错校验逻辑位于 rlhf_args.py该处还有一个细节当使用async_generate或vllm_modeserver时sleep_level会被强制置为 0外部/异步服务无需释放本地显存。Colocate 模式下的显存优化方案在 Colocate 模式下运行时容易出现显存不足OOM的情况。以下是几种有效的显存优化方法和参数配置参数定义见 args_mixin.py降低vllm_gpu_memory_utilization参数该参数默认 0.9控制 vLLM KV cache 占用的显存比例降低可为训练侧腾出空间上文示例即使用 0.5。在训练阶段释放 vLLM 占用的显存--sleep_level 1sleep_level默认 0不释放取值越大释放越多但可能有额外开销。 3.在 vLLM 推理阶段释放模型和优化器占用的显存--offload_optimizer true \ --offload_model true \二者默认均为 False开启后在推理前把优化器状态/模型权重卸载到 CPU。 4.在 vLLM 中使用 Tensor Parallel 技术--vllm_tensor_parallel_size [tp_size]将模型切分到多卡以降低单卡显存压力。 5.分批 Gather 模型权重zero3 下同步 vLLM 权重时--move_model_batches [批次数量]move_model_batches默认 None设置后可避免一次性 gather 全量权重导致的显存峰值。 6.将 Megatron 导出的用于 vLLM 更新的 HF 格式权重存放在 CPU 主存中以降低 GPU 显存占用--offload_bridge true2. AsyncExternal模式训练与推理资源分离启动单独的推理服务器。使用swift rollout命令部署 vLLM 服务器现仅支持 vLLM backend命令入口见 rollout.py以下三个示例分别演示不同卡数下的 TP/DP 组合CUDA_VISIBLE_DEVICES0 \ swift rollout \ --model Qwen/Qwen2.5-VL-7B-Instruct \ --vllm_tensor_parallel_size 2 \ --vllm_data_parallel_size 1 CUDA_VISIBLE_DEVICES0,1 \ swift rollout \ --model Qwen/Qwen2.5-VL-7B-Instruct \ --vllm_tensor_parallel_size 2 \ --vllm_data_parallel_size 1 CUDA_VISIBLE_DEVICES0,1,2,3 \ swift rollout \ --model Qwen/Qwen2.5-VL-7B-Instruct \ --vllm_tensor_parallel_size 2 \ --vllm_data_parallel_size 2注意在使用vllm_use_async_engine时仅开启 DP 可能会导致错误对应 vLLM 上游 issue #18567。如果出现错误请尝试同时启用 TP 和 DP或升级 vLLM。训练侧使用以下参数配置外部 vLLM 服务器--use_vllm true \ --vllm_mode server \ --vllm_server_host 服务器IP \ --vllm_server_port 服务端口 \ --vllm_server_timeout 超时时间 \相关默认值vllm_server_port默认[8000]vllm_server_timeout默认 240 秒若设置了vllm_server_base_url如http://localhost:8000则 host/port 会被忽略见 args_mixin.py。完整的外部模式训练脚本可参考 examples/train/grpo/external多机混合部署示例在 examples/train/grpo/multi_node。权重同步加速设置以下参数可以通过仅同步 LoRA adapter 权重而非全量模型权重优化 LoRA 训练的权重同步速度。注意这种同步方式会略微影响 vLLM 推理速度。# rollout(server mode) swift rollout \ --vllm_enable_lora true \ --vllm_max_lora_rank xxx # 与训练脚本lora_rank一致 ... # grpo(colocate mode) swift rlhf \ --rlhf_type grpo \ --vllm_mode colocate \ --vllm_enable_lora true \ ... # megatron grpo(colocate mode) swift megatron rlhf \ --rlhf_type grpo \ --vllm_mode colocate \ --vllm_enable_lora true \ ...其中vllm_enable_lora默认 Falsevllm_max_lora_rank默认 16lora_rankcolocate 模式下 vLLM 加载的 LoRA 秩默认 8设置时应大于等于理想等于训练脚本的 LoRA rank。多模态模型 ViT 层 LoRA 同步如果训练时开启了 ViT 层的 LoRAfreeze_vit false在仅同步 LoRA 的模式下需要相应在 vLLM 侧开启 tower/connector LoRA 支持通过vllm_engine_kwargs传入--vllm_engine_kwargs {enable_tower_connector_lora: true}该功能为 vLLM 实验性特性目前支持 Qwen2.5-VL、Qwen3-VL 等模型具体支持情况请参阅 vLLM 官方文档与 issuevllm-project/vllm#31479。logged metrics训练过程中记录的指标及其含义如下可用于诊断采样质量、奖励分布与训推一致性Completion 长度指标completions/mean_length生成的 completion 的平均长度。completions/min_length生成的 completion 的最小长度。completions/max_length生成的 completion 的最大长度。completions/clipped_ratio被长度截断的 completion 占比。奖励指标reward/{reward_func_name}/mean某个特定 reward function 的平均奖励值。reward/{reward_func_name}/std某个特定 reward function 的奖励标准差。注意上述两个指标是在所有 completions 范围内统计得到的。reward加权reward_weights后的整体平均奖励。reward_std加权reward_weights后每个 batch 内整体奖励的标准差。注意上述两个指标是先在每个组内分别计算均值/std然后再对各组的结果取平均。frac_reward_zero_std在生成 batch 中reward 标准差为零的样本比例意味着该 prompt 上的答案几乎无多样性所有回答奖励一致这类样本对策略梯度没有贡献比例过高时建议开启dynamic_sample。kl生成的 completion 上模型与参考模型之间的平均 KL 散度。仅当 beta 非零时记录。Clip 指标clip_ratio/region_mean不同句子中被 CLIP 的 token 平均比例clip_ratio/low_mean不同句子中被下 CLIP 的 token 平均比例clip_ratio/low_min不同句子中被下 CLIP 的 token 最小比例clip_ratio/high_mean不同句子中被上 CLIP 的 token 平均比例clip_ratio/high_max不同句子中被上 CLIP 的 token 最大比例注意如果开启overlong_filterkl 和 clip_ratio 指标会过滤超长的样本。Entropy 指标设置log_entropy后记录entropy/mean不同句子中的 entropy 均值entropy/max不同句子中的 entropy 最大值entropy/min不同句子中的 entropy 最小值注意这里的句子 entropy 指 completion 中的 token entropy 均值。如果设置了top_entropy_quantile参数 1.0则会记录 entropy threshold 的值entropy/threshold分位点处的 entropy 值小于该值的 token 将不会被计算 loss。训推一致性指标前缀为rollout_correction需设置log_rollout_offpolicy_metricstrue或rollout_importance_sampling_mode实现见 grpo_algorithm.pykl/k3_kl训练策略与 rollout 策略之间的 KL 散度直接估计器 / K3 估计器training_ppl/rollout_ppl训练策略和 rollout 策略的困惑度log_ppl_difflog PPL 差异反映分布偏移程度ppl_ratioPPL 比率chi2_token/chi2_seqToken/Sequence 级别的 χ² 散度IS 校正指标需设置rollout_importance_sampling_modeis_weight_mean平均重要性采样权重ess有效样本大小Effective Sample Sizeclipped_frac被截断或屏蔽的样本比例训推一致性指标的详细说明请参考 Training-Inference-Mismatch 文档。训练动态记录如果设置了log_completions将保存训练动态在 output 对应文件夹中包括step记录时的训练步数prompt模型输入completion模型采样回答{reward_func_name}特定奖励entropyentropy token 均值在设置log_entropy时记录设置report_to wandb/swanlab将训练动态 Table 推送到对应的平台。如果需要在 Table 中额外记录其他列请在GRPOTrainer._generate_and_score_completions方法中设置metrics_to_gather字典。默认自动检测image视觉数据集图像输入暂时只支持 wandbsolution数据集中的 solution 列。FAQ1. 训练过程中 loss 等于 0 / 接近 0 / 小于 0正常情况。在 on-policy 训练中新旧策略相同重要性采样比恒为 1policy loss 本身接近 0甚至因数值误差为负这是社区广泛确认的行为参考 huggingface/open-r1#239。2. num_generations / 批量大小相关在 GRPO 中batch_size 以 completion模型生成结果为单位。例如设置per_device_train_batch_size8表示每张 GPU 在训练过程中会同时处理 8 个 completion 的 loss 计算。训练阶段在一次完整的梯度累计 batch 中总的批量大小等于effective_batch_size num_processes * per_device_train_batch_size * gradient_accumulation_steps采样阶段总的批量大小completion-level数量等于设置generation_batch_size下等于generation_batch_size设置steps_per_generation下等于per_device_train_batch_size * steps_per_generation * num_processes默认情况下steps_per_generation gradient_accumulation_stepsgeneration_batch_size per_device_train_batch_size * steps_per_generation * num_processes effective_batch_size在评估阶段completion 的数量等于num_processes * per_device_eval_batch_size参数num_generations必须能够被以上采样阶段和评估的总批量大小整除以保证生成任务可以均匀分配到各个设备上。这一整除约束在源码中被严格执行_init_generation_batch_params会对generation_batch_size、num_generations以及评估侧 batch size 做可整除性校验不满足时直接抛出 ValueError 并列出合法取值。示例num_processes 8、per_device_train_batch_size 4、gradient_accumulation_steps 8、generation_batch_size 512、num_generations 64采样需要的总数据prompt量等于 512 / 64 8每次采样 512 条模型回复每次更新模型权重批量大小为 8 × 4 × 8 2563. 为什么 KL 出现了 NaN开启overlong_filter后某一卡上的所有 completion 都被截断导致参与 KL 计算的样本为空出现 NaN。4. 训练的 steps 怎么计算可参考仓库 issue modelscope/ms-swift#3912 中的推导核心是总样本数 / effective_batch_size决定优化步数。5. clip_ratio 为什么总是 0Clip 机制的核心目的是限制策略更新的幅度防止因单次更新过大而导致策略性能崩溃即策略更新后表现急剧下降。Clip 操作的具体公式如下$$ L_{\text{CLIP}}(\theta) \mathbb{E}_{t} \left[ \min\left(r_{t}(\theta) \hat{A}{t}, \text{clip}(r{t}(\theta), 1 - \epsilon, 1 \epsilon) \hat{A}_{t} \right) \right] $$其中$r_{t}(\theta) \frac{\pi_{\theta}(a_{t} \mid s_{t})}{\pi_{\text{old}}(a_{t} \mid s_{t})}$ 是重要性采样比衡量新旧策略的差异$\hat{A}{t}$ 是优势函数advantage function表示动作的相对收益$\epsilon$ 用于限制 $r{t}(\theta)$ 的偏离范围。在 on-policy 训练过程中由于每次更新都使用最新策略生成的数据新旧策略相同即 $\pi_{\theta} \pi_{\text{old}}$因此重要性采样比恒为 1此时 clip 操作不会生效。在设置以下参数情况下算法为 off-policynear-on-policynum_iterations 1或者gradient_accumulation_steps % steps_per_generation ! 0此时新旧策略产生差异clip 才真正发挥作用。6. 如何设置训练的 mini-batch size在 GRPO 训练中可以通过以下两种方式配置 mini-batch 更新设置generation_batch_size为训练 global batch sizeeffective_batch_size的整数倍或设置steps_per_generation为gradient_accumulation_steps的整数倍典型配置示例当配置steps_per_generation 16, gradient_accumulation_steps 8, mini_batch_size steps_per_generation / gradient_accumulation_steps 2时1 次 rollout 结果将拆分成 2 批 mini-batch 进行更新。7. swift deploy 与 swift rollout 的区别swift deploy主要用于模型的部署和推理支持 Transformers、vLLM、SGLang 等多种引擎兼容流式推理与 OpenAI API 的调用格式。swift rollout则专注于 GRPO 推理加速目前仅支持 vLLM 引擎并内置了权重自动同步的功能。8. 如何取消 KL 项损失将参数设置为--beta 0即可关闭 KL 损失的计算并且不会加载参考模型ref model。延伸阅读完整训练脚本examples/train/grpo含 internal/external/multi_node 分类目录GRPO 参数、vLLM 参数、rollout 参数Command-line-parameters.md训推一致性Training-Inference-Mismatchtraining_inference_mismatch.md奖励函数开发reward_function.md、reward_model.md多轮 GRPO 与 Gym 环境multi_turn.md、gym_env.md参数默认值与校验逻辑args_mixin.py、rlhf_args.py【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考