Table of Contents
Shortcuts

配置参数详解

本指南详细介绍了 LightRFT 中提供的所有配置参数。为了方便查阅，参数按类别进行了归类。

目录

  1. 模型参数

  2. 训练参数

  3. Batch Size 配置

  4. 算法参数

  5. 分布式训练

  6. 推理引擎

  7. 内存优化

  8. 日志与监控

  9. 检查点管理

模型参数

--pretrain

  • 类型: str

  • 是否必填: 是

  • 描述: 预训练模型和分词器 (tokenizer) 的路径

  • 示例: /path/to/Qwen2.5-7B-Instruct

--reward_pretrain

  • 类型: str

  • 默认值: 与 --pretrain 相同

  • 描述: 奖励模型 (Reward Model) 的路径

  • 示例: /path/to/reward-model

--remote_rm_url

  • 类型: str

  • 默认值: None

  • 描述: 远程奖励模型服务器的 URL

  • 示例: http://localhost:5000

--max_len

  • 类型: int

  • 默认值: 4096

  • 描述: 最大序列长度（Prompt + Response）

--prompt_max_len

  • 类型: int

  • 默认值: 2048

  • 描述: 最大 Prompt 长度

训练参数

--num_episodes

  • 类型: int

  • 默认值: 1

  • 描述: 训练的总 Episode 数量

  • 建议: 大多数任务建议设置为 10-100

--max_epochs

  • 类型: int

  • 默认值: 1

  • 描述: 每个 Episode 中训练的 Epoch 数量

  • 建议: 1-3

--actor_learning_rate

  • 类型: float

  • 默认值: 5e-7

  • 描述: Actor（策略）模型的学习率

  • 建议范围: 1e-7 到 5e-6

--critic_learning_rate

  • 类型: float

  • 默认值: 9e-6

  • 描述: Critic（价值）模型的学习率

  • 建议范围: 1e-6 到 1e-5

--lr_warmup_ratio

  • 类型: float

  • 默认值: 0.03

  • 描述: Warmup 步数占总步数的比例

  • 范围: 0.0 到 0.1

--max_norm

  • 类型: float

  • 默认值: 1.0

  • 描述: 梯度裁剪的最大范数 (Gradient clipping norm)

--l2

  • 类型: float

  • 默认值: 0.0

  • 描述: L2 正则化系数

--adam_betas

  • 类型: tuple[float, float]

  • 默认值: (0.9, 0.95)

  • 描述: Adam 优化器的 beta 参数

Batch Size 配置

重要约束

规则: train_batch_size >= rollout_batch_size × n_samples_per_prompt

--train_batch_size (TBS)

  • 类型: int

  • 是否必填: 是

  • 描述: 所有 GPU 上的全局训练 Batch Size

  • 示例: 256

  • 计算公式: micro_train_batch_size × num_gpus × gradient_accumulation_steps

--micro_train_batch_size

  • 类型: int

  • 默认值: 1

  • 描述: 单个 GPU 上的训练 Batch Size

  • 常见值: 1, 2, 4

--rollout_batch_size (RBS)

  • 类型: int

  • 是否必填: 是

  • 描述: 所有 GPU 上的全局生成 (Rollout) Batch Size

  • 示例: 64

  • 注意: 必须能被 GPU 总数整除

--micro_rollout_batch_size

  • 类型: int

  • 默认值: 2

  • 描述: 单个 GPU 上的生成 (Rollout) Batch Size

  • 常见值: 2, 4, 8

配置示例

配置 1: 8 张 GPU，显存受限

--train_batch_size 128 \
--micro_train_batch_size 1 \
--rollout_batch_size 64 \
--micro_rollout_batch_size 2

配置 2: 8 张 GPU，追求高吞吐量

--train_batch_size 512 \
--micro_train_batch_size 2 \
--rollout_batch_size 256 \
--micro_rollout_batch_size 8

算法参数

--advantage_estimator

  • 类型: str

  • 选项: gae, reinforce, rloo, reinforce_baseline, group_norm, cpgd, reinforce++, on_policy_distillation

  • 默认值: group_norm

  • 描述: 优势估计 (Advantage estimation) 的方法

  • 建议:

    • group_norm: 通用选择 (GRPO)

    • reinforce: 需要低方差时使用

    • cpgd: 旨在保持基础模型能力时使用

  • 说明：当前参数解析器可以接受 reinforce++，但优势计算器工厂尚未提供对应映射；在该集成完成前不应使用此选项。

--n_samples_per_prompt

  • 类型: int

  • 默认值: 4

  • 描述: 每个 Prompt 采样生成的 Response 数量

  • 常见值: 4, 8, 16

  • 注意: 值越高效果通常越好，但速度越慢

--kl_estimator

  • 类型: str

  • 选项: k1, k2, k3

  • 默认值: k3

  • 描述: KL 散度估计器类型

  • 建议: 大多数情况下使用 k3

--init_kl_coef

  • 类型: float

  • 默认值: 0.001

  • 描述: 初始 KL 惩罚系数

  • 范围: 0.0001 到 0.01

--kl_target

  • 类型: float

  • 默认值: 0.01

  • 描述: 目标 KL 散度（用于 CPGD）

--clip_range

  • 类型: float

  • 默认值: 0.2

  • 描述: PPO 的裁剪范围 (Clipping range)

  • 范围: 0.1 到 0.3

--clip_range_higher

  • 类型: float

  • 默认值: 0.3

  • 描述: 上限裁剪范围（用于 Clip Higher 算法）

--temperature

  • 类型: float

  • 默认值: 1.0

  • 描述: 采样温度 (Sampling temperature)

  • 范围: 0.6 到 1.2

  • 注意: 值越低生成结果越确定

--top_p

  • 类型: float

  • 默认值: 0.9

  • 描述: 核采样 (Nucleus sampling) 概率

  • 范围: 0.8 到 1.0

分布式训练

--zero_stage

  • 类型: int

  • 选项: 1, 2, 3

  • 默认值: 2

  • 描述: DeepSpeed ZeRO 优化阶段

  • 建议:

    • Stage 1: 优化器状态分片

    • Stage 2: 优化器状态 + 梯度分片（推荐）

    • Stage 3: 优化器状态 + 梯度 + 参数分片（最大程度节省显存）

--fsdp

  • 操作: store_true

  • 默认值: False

  • 描述: 使用 FSDP 代替 DeepSpeed

  • 适用场景: 原生 PyTorch 工作流，追求极致的显存效率

--fsdp_cpu_offload

  • 操作: store_true

  • 默认值: False

  • 描述: 将 FSDP 优化器状态卸载 (Offload) 到 CPU

  • 注意: 减少 GPU 显存占用，但会降低速度

--bf16

  • 操作: store_true

  • 默认值: 通常默认启用

  • 描述: 使用 bfloat16 混合精度

--gradient_checkpointing

  • 操作: store_true

  • 默认值: False

  • 描述: 启用梯度检查点 (Gradient checkpointing)

  • 注意: 以增加计算量为代价换取显存节省

--sp_size

  • 类型: int

  • 默认值: 1

  • 描述: 序列并行 (Sequence parallelism) 大小

  • 建议: 处理极长序列时建议设置为 1, 2, 4

推理引擎

--engine_type

  • 类型: str

  • 选项: vllm, sglang

  • 默认值: vllm

  • 描述: 推理引擎类型

--engine_tp_size

  • 类型: int

  • 默认值: 1

  • 描述: 推理引擎的张量并行 (Tensor Parallelism) 大小

  • 建议:

    • 7B 模型: 1 或 2

    • 13B-34B 模型: 2 或 4

    • 70B+ 模型: 4 或 8

  • 约束: GPU 总数 (world_size) % engine_tp_size == 0

--engine_mem_util

  • 类型: float

  • 默认值: 0.5

  • 范围: 0.3 到 0.9

  • 描述: 用于 KV 缓存的 GPU 显存占比

  • 建议:

    • 显存充裕: 0.8 - 0.9

    • 显存适中: 0.5 - 0.7

    • 显存紧张: 0.3 - 0.5

--enable_engine_sleep

  • 操作: store_true

  • 默认值: True

  • 描述: 启用推理引擎休眠模式

  • 注意: 在不使用引擎阶段释放显存

--disable_engine_sleep

  • 操作: store_false

  • 目标名为: enable_engine_sleep

  • 描述: 禁用推理引擎休眠模式

--rm_use_engine

  • 操作: store_true

  • 默认值: False

  • 描述: 奖励模型 (Reward Model) 使用推理引擎进行计算

  • 适用场景: 需要高吞吐量的奖励计算

内存优化

--adam_offload

  • 操作: store_true

  • 默认值: False

  • 描述: 将 Adam 优化器状态卸载 (Offload) 到 CPU

--use_mp_opt

  • 操作: store_true

  • 默认值: False

  • 描述: 使用混合精度优化器 (FSDP)

--packing_samples

  • 操作: store_true

  • 默认值: False

  • 描述: 将多个样本打包 (Pack) 到同一序列中

  • 适用场景: 序列长度差异较大时，可提高 GPU 利用率

--fused_linear_logprob

  • 操作: store_true

  • 默认值: False

  • 描述: 融合线性层和 logprob 计算

  • 注意: 对于大词表模型可节省显存

--chunk_size

  • 类型: int

  • 默认值: 4096

  • 描述: 融合操作的分块大小 (Chunk size)

日志与监控

--log_dir

  • 类型: str

  • 默认值: None

  • 描述: 日志及可视化结果的保存目录

--plot_every

  • 类型: int

  • 默认值: 10

  • 描述: 每隔 N 步绘制一次生成长度分布图

--use_tensorboard

  • 类型: str

  • 默认值: None

  • 描述: TensorBoard 日志目录

--use_wandb

  • 类型: str

  • 默认值: None

  • 描述: Weights & Biases 项目名称

--wandb_org

  • 类型: str

  • 默认值: None

  • 描述: W&B 组织名称

--wandb_run_name

  • 类型: str

  • 默认值: 自动生成

  • 描述: W&B Run 名称

检查点管理

--save_path

  • 类型: str

  • 是否必填: 是

  • 描述: 检查点 (Checkpoint) 保存目录

--ckpt_path

  • 类型: str

  • 默认值: None

  • 描述: 加载检查点的路径

--load_checkpoint

  • 操作: store_true

  • 默认值: False

  • 描述: 启用检查点加载

--save_interval

  • 类型: int

  • 默认值: 1

  • 描述: 每隔 N 个 Episode 保存一次检查点

--max_ckpt_num

  • 类型: int

  • 默认值: 3

  • 描述: 保留检查点的最大数量

--max_ckpt_mem

  • 类型: int

  • 默认值: 1000

  • 描述: 最大检查点存储空间（GB）

奖励处理

--reward_running_norm

  • 操作: store_true

  • 默认值: False

  • 描述: 对奖励应用实时归一化 (Running normalization)

--reward_running_norm_minus_mean

  • 操作: store_true

  • 默认值: False

  • 描述: 奖励归一化时减去均值

--advantages_norm

  • 操作: store_true

  • 默认值: False

  • 描述: 对优势 (Advantages) 进行归一化

--advantage_clip

  • 类型: float

  • 默认值: 0.0

  • 描述: 对优势进行裁剪 (0 表示不裁剪)

--reward_clip

  • 类型: float

  • 默认值: 0.0

  • 描述: 对奖励进行裁剪 (0 表示不裁剪)

多模态 (VLM) 参数

--mixed_mm_data

  • 操作: store_true

  • 默认值: False

  • 描述: 处理混合的多模态和纯文本数据

--processor

  • 类型: str

  • 默认值: 自动检测

  • 描述: 多模态处理器 (Processor) 类型

完整配置示例

数学推理 (GSM8K, MATH)

python train.py \
    # 模型
    --pretrain /path/to/Qwen2.5-7B-Instruct \
    --reward_pretrain /path/to/reward-model \
    --max_len 4096 \
    --prompt_max_len 2048 \
    \
    # 训练
    --num_episodes 20 \
    --max_epochs 1 \
    --actor_learning_rate 5e-7 \
    --critic_learning_rate 9e-6 \
    \
    # Batch Size
    --train_batch_size 128 \
    --micro_train_batch_size 1 \
    --rollout_batch_size 64 \
    --micro_rollout_batch_size 2 \
    \
    # 算法
    --advantage_estimator group_norm \
    --n_samples_per_prompt 8 \
    --kl_estimator k3 \
    --init_kl_coef 0.001 \
    --temperature 0.6 \
    \
    # 分布式
    --zero_stage 2 \
    --bf16 \
    --gradient_checkpointing \
    \
    # 引擎
    --engine_type vllm \
    --engine_tp_size 1 \
    --engine_mem_util 0.85 \
    --enable_engine_sleep \
    \
    # 内存
    --adam_offload \
    --fused_linear_logprob \
    \
    # 日志
    --use_tensorboard ./tb_logs \
    --plot_every 10 \
    \
    # 检查点
    --save_path ./checkpoints \
    --save_interval 1 \
    --max_ckpt_num 3 \
    \
    # 奖励
    --reward_running_norm \
    --advantages_norm

多模态 VLM 训练

python train_vl.py \
    # 模型
    --pretrain /path/to/Qwen2-VL-7B-Instruct \
    --max_len 4096 \
    \
    # 训练
    --num_episodes 10 \
    --actor_learning_rate 1e-6 \
    \
    # Batch Size
    --train_batch_size 64 \
    --micro_train_batch_size 1 \
    --rollout_batch_size 32 \
    --micro_rollout_batch_size 1 \
    \
    # 算法
    --advantage_estimator group_norm \
    --n_samples_per_prompt 4 \
    \
    # 分布式
    --fsdp \
    --fsdp_cpu_offload \
    --gradient_checkpointing \
    \
    # 引擎
    --engine_tp_size 4 \
    --engine_mem_util 0.6 \
    \
    # VLM 特定
    --mixed_mm_data \
    --packing_samples

参数依赖校验

LightRFT 会自动验证参数的合法性。常见的校验规则包括：

  1. Batch Size: train_batch_size >= rollout_batch_size × n_samples_per_prompt

  2. 整除性: Batch Size 必须能被 GPU 数量整除

  3. 显存: 引擎的 TP size 必须能整除 world size

  4. 学习率: Actor LR 通常小于 Critic LR

  5. KL Target: 为了训练稳定，建议设置较小的值 (0.001-0.01)

环境变量

用于优化性能的有用环境变量：

# NCCL 优化
export TORCH_NCCL_AVOID_RECORD_STREAMS=1

# CUDA 显卡设置
export CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7

# 调试
export TORCH_DISTRIBUTED_DEBUG=INFO
export NCCL_DEBUG=INFO

另请参阅