Skip to content

configuration.md

Latest commit

 

History

History
630 lines (487 loc) · 40.3 KB

configuration.md

File metadata and controls

630 lines (487 loc) · 40.3 KB
Raw

配置参考手册

参数分为三类：

  1. megatron 参数：Relax 会读取 PYTHONPATH 中的 megatron 里设置的所有参数，可以通过传入如 --tensor-model-parallel-size 2 的方式配置 megatron；
  2. sglang 参数：支持环境中安装的 sglang 的所有参数，这些参数需要以 --sglang 起始，例如 --mem-fraction-static 需要通过 --sglang-mem-fraction-static 传入。
  3. Relax 自身的参数请见：relax/utils/arguments.py

常见配置用法和示例请参见快速开始指南。

集群与资源配置

Ray 启动参数

参数 类型 默认值 说明
--rollout-num-gpus-per-engine int 1 每个 SGLang 推理引擎使用的 GPU 数，等同于 SGLang 的 tp_size
--num-gpus-per-node int 8 每个节点的 GPU 数。如果在 colocate 模式下每个节点使用少于 8 张 GPU 需要设置此值
--resource json - Ray 资源配置，JSON 格式。'{"actor":[副本数, 卡数], "rollout":[副本数, 卡数]}'
--colocate flag False 是否将推理引擎和训练 Actor 共置在相同的 GPU 上。开启后会同时将 --offload 设为 True
--offload flag False 等同于同时设置 --offload-train 和 --offload-rollout
--offload-train flag None 训练期间是否将训练 Actor 卸载到 CPU。--colocate 时始终为 True
--offload-rollout flag None 训练期间是否将 Rollout 生成器卸载到 CPU。--colocate 时始终为 True
--distributed-backend str nccl 分布式后端
--distributed-timeout-minutes int 10 分布式超时时间（分钟）

TransferQueue 数据队列

参数 类型 默认值 说明
--num-data-storage-units int 1 TransferQueue SimpleStorageUnit Actor 数量
--per-rank-fetch flag False 让每个 TP/PP rank 都并行地各自从 TransferQueue 拉一份数据，省掉 rank-0 pickle + TP/PP broadcast。跨 rank 一致性依赖 TQ sampler 的 (partition_id, task_name, dp_rank, batch_index) 缓存（PP/TP 不变量）。当 rollout_routed_experts 出现在 data_fields 时自动禁用（jagged NestedTensor broadcast 路径不兼容）。多卡训练推荐配合 --num-data-storage-units >= TP world size 使用。在 pickle 主导 tgd_bcast_tp_time 时有收益。
--max-staleness int 0 TransferQueue 数据系统的最大陈旧度（0=on-policy）
--polling-mode bool True 获取 metadata 时是否使用轮询模式
--num-iters-per-train-update int 1 全异步流水线中每个 global batch 的迭代次数

训练后端与模式

参数 类型 默认值 可选值 说明
--train-backend str megatron megatron 训练后端选择
--qkv-format str thd thd, bshd Megatron 后端的 QKV 布局。bshd 模式下不支持动态批处理，必须指定 --micro-batch-size
--megatron-to-hf-mode str raw raw, bridge Megatron 到 HF 权重转换方式。bridge 使用 megatron bridge 自动转换
--true-on-policy-mode flag False - 是否启用真正的 on-policy 模式
--fully-async flag False - 是否使用全异步训练流水线

检查点配置

参数 类型 默认值 说明
--hf-checkpoint str None HuggingFace 模型检查点路径。用于初始化 SGLang 和提供 tokenizer。不需要包含最新的参数，只需与训练模型架构一致
--ref-load str None 参考模型检查点路径。当 --load 未设置时，会作为训练的初始检查点
--ref-ckpt-step int None 参考模型检查点的步数
--load str None Actor 模型检查点加载路径。断点续训时指向此路径
--save str None 训练中模型的保存路径
--save-interval int None 模型保存间隔（步数）
--save-hf str None Megatron 后端时保存 HuggingFace 格式模型的路径。路径可包含 {rollout_id} 占位符
--async-save flag False 异步保存检查点
--no-save-optim flag False 保存检查点时不保存优化器状态。减少检查点大小但无法从该检查点恢复训练
--rotate-ckpt flag False 是否轮换检查点。需要同时设置 --save、--save-interval 和 --async-save
--max-actor-ckpt-to-keep int None 保留的最大 Actor 检查点数
--checkpoint-engine-backend str nccl 检查点引擎后端
--critic-load str None Critic 模型检查点路径。None 时等于 --load
--critic-save str None Critic 模型保存路径

数据配置

数据集

参数 类型 默认值 说明
--prompt-data str None 训练 Prompt 数据集路径
--input-key str input 数据集中输入字段的 key
--label-key str None 数据集中标签字段的 key
--conversation-key-map json None 将非 OpenAI 格式的对话消息改写成 SFT 期望的 {role, content} 结构的 JSON 映射。一个扁平 map 同时覆盖两种重命名：字段名重命名（作用于每个消息 dict 的所有 key，例如 from→role、value→content）与 role 值重命名（仅作用于重命名后名为 role 字段的值，例如 human→user、gpt→assistant——因此消息正文中即使出现相同词也不会被误改）。仅在未设置 --label-key（即 --input-key 整列为完整的 messages list）时生效。sharegpt 示例：'{"from":"role","value":"content","human":"user","gpt":"assistant"}'
--metadata-key str metadata 数据集中元数据字段的 key
--tool-key str tools 应用 Chat Template 时的 tools 字段 key
--apply-chat-template flag False 将输入作为 OpenAI message 格式应用 Chat Template
--apply-chat-template-kwargs json {} Chat Template 的额外参数
--system-prompt str None 可选的系统提示词，会添加到用户输入之前。最终消息为 <system_prompt> + <dataset_prompt>
--rollout-shuffle flag False Rollout 时是否打乱 Prompt 顺序
--rollout-seed int 42 Rollout 的随机种子，用于打乱 Prompt 和随机采样
--use-streaming-dataset flag False 使用流式数据集以节省内存
--streaming-buffer-size int 10000 流式数据集的缓冲区大小
--prefetch-chunk-size int 32 每轮预取时分派到线程池的样本数。较大的值可以提高吞吐量但也会增加内存压力。仅在设置了 --use-streaming-dataset 且数据集包含多模态数据时生效
--prefetch-max-cached int 256 预取缓存中保留的最大预加载样本数。缓存满时后台预取线程会暂停，直到消费者释放空间。设为 0 可禁用预取。仅在设置了 --use-streaming-dataset 且数据集包含多模态数据时生效
--prefetch-num-workers int 1 预取缓冲区中用于 I/O 密集型媒体解码（视频/图像）的并行工作线程数。设为 1 可序列化所有解码操作（对 FFmpeg 非线程安全问题最安全）。较高值可提高并行度，但在某些平台上可能触发 EAGAIN 错误。仅在启用预取时生效
--custom-prompt-path str None 自定义 Prompt 转换函数的 Python 点分导入路径。该函数在对话/多模态处理之前调用。函数签名：def custom_fn(prompt, data: dict) -> prompt。示例：my_package.prompt_utils.add_prefix
--data-source-path str relax.engine.rollout.data_source.RolloutDataSourceWithBuffer Rollout 数据源类路径
--start-rollout-id int None 起始 Rollout 步数。未设置时会尝试从 --load 的检查点中读取

多模态数据

参数 类型 默认值 说明
--multimodal-keys json None 多模态数据字段映射。示例：'{"image": "image_key"}'
--use-audio-in-video flag False 是否处理视频中的音频
--image-max-token-num int None 图像处理的最大 Token 数。未设置时使用默认值 16384
--image-min-token-num int None 图像处理的最小 Token 数。未设置时使用默认值 4
--video-min-token-num int None 视频帧处理的最小 Token 数。未设置时使用默认值 128
--video-max-token-num int None 视频帧处理的最大 Token 数。未设置时使用默认值 768
--video-fps float None 视频处理的目标 FPS。未设置时使用默认值 2.0
--video-fps-min-frames int None 视频处理的最少帧数。未设置时使用默认值 4
--video-fps-max-frames int None 视频处理的最多帧数。未设置时使用默认值 768
--image-resize-scale-factor int None 图像缩放尺寸对齐因子。默认使用 patch_size * spatial_merge_size（通常为 28）。设为 0 可禁用对齐
--audio-sample-rate int None 音频处理的采样率。未设置时使用默认值 16000
--frame-factor int None 帧数对齐因子。未设置时使用默认值 2
--mm-processor-pool-size int 0 多模态处理器池大小。0（默认）禁用进程池，使用 ThreadPoolExecutor。设置为正整数时，创建指定数量 worker 的 ProcessPoolExecutor，实现无 GIL 竞争的真正并行

Rollout 配置

采样参数

参数 类型 默认值 说明
--num-rollout int None 总 Rollout 轮数。与 --num-epoch 二选一
--num-epoch int None 训练 Epoch 数。会根据数据集大小自动计算 num_rollout。若同时设置 --num-rollout 则此参数被忽略
--rollout-batch-size int 必填 每轮采样的 Prompt 数量。总数据量 = rollout-batch-size * n-samples-per-prompt
--n-samples-per-prompt int 1 每个 Prompt 生成的响应数量
--rollout-temperature float 1.0 推理引擎的采样温度
--rollout-top-p float 1.0 推理引擎的 Top-p 采样参数
--rollout-top-k int -1 推理引擎的 Top-k 采样参数。-1 表示不使用
--rollout-max-response-len int None 响应的最大长度，等同于 SGLang 的 max_tokens
--rollout-max-prompt-len int None Prompt 的最大长度。设置后会在数据集初始化时过滤长 Prompt
--rollout-max-context-len int None 推理引擎的最大上下文长度。不应超过 HuggingFace 模型 config.json 中的 max_position_embeddings
--rollout-stop str (列表) None Rollout 时的停止词。可以是一个或多个字符串
--rollout-stop-token-ids int (列表) None Rollout 时的停止 Token ID
--rollout-skip-special-tokens flag False 响应中是否跳过特殊 Token

过采样与动态过滤

参数 类型 默认值 说明
--over-sampling-batch-size int None 采样批次粒度。None 时使用 rollout-batch-size 的值。必须 >= rollout-batch-size
--dynamic-sampling-filter-path str None 动态采样过滤函数路径。用于实现类似 DAPO 的过滤（如排除全部正确或全部错误的样本）。示例：relax.engine.filters.dynamic_sampling_filters.check_reward_nonzero_std
--buffer-filter-path str None Buffer 过滤函数路径。函数签名：list[list[Sample]] -> list[list[Sample]]

Partial Rollout

参数 类型 默认值 说明
--partial-rollout flag False 启用部分 Rollout。未完成的样本会被回收到数据缓冲区，适合长响应场景
--partial-rollout-max-aborted-count int None 样本被中断的最大次数。达到阈值后不再中断该样本，保证其完成生成
--mask-offpolicy-in-partial-rollout flag False 部分 Rollout 中是否 mask 之前的生成内容。设置后只有 on-policy 生成的 Token 参与训练

权重更新

参数 类型 默认值 说明
--update-weight-buffer-size int 512MB 权重更新的缓冲区大小（字节）。分块更新权重，对 MoE 模型有用
--update-weights-interval int 1 权重更新间隔
--keep-old-actor flag False 是否在训练过程中保留 Rollout 模型

外部推理引擎

参数 类型 默认值 说明
--rollout-external flag False 使用外部 SGLang 实例而非框架内启动的实例
--rollout-external-engine-addrs str (列表) None 外部引擎的地址和端口列表

SGLang 引擎参数

更多参数请参照 SGLang 官方文档。

参数 类型 默认值 说明
--sglang-mem-fraction-static float - SGLang 静态内存分配比例
--sglang-profile flag False 启用 SGLang 引擎的 torch profiling。在 Rollout 推理期间触发，每步保存 profile trace
--sglang-profile-steps int (列表) None 指定要进行 SGLang profiling 的绝对 rollout step ID（0-indexed）列表。优先级高于 --sglang-profile-step-start/end。例如 --sglang-profile-steps 3 10 50
--sglang-profile-step-start int None SGLang profiling 的起始 rollout step（inclusive，0-indexed）。与 --sglang-profile-step-end 配合指定连续范围。设置了 --sglang-profile-steps 时被忽略
--sglang-profile-step-end int None SGLang profiling 的结束 rollout step（inclusive，0-indexed）。与 --sglang-profile-step-start 配合指定连续范围。设置了 --sglang-profile-steps 时被忽略。例如 start=2, end=4 会采集 step 2, 3, 4
--sglang-profile-output-dir str None SGLang profile trace 的输出目录。默认使用 traces/<tb_experiment_name>/sglang_trace
--sglang-profile-num-steps int 3 每轮 Rollout 中要 profile 的 SGLang 前向步数。-1 表示 profile 整个 Rollout 步，直到调用 stop_profile
--sglang-profile-activities str (列表) ["CPU", "GPU"] 要 profile 的活动类型（例如 CPU GPU）
--sglang-profile-by-stage flag False 按阶段（prefill/decode）分别进行 profile
--sglang-profile-with-stack flag False 在 profile trace 中记录调用栈
--sglang-profile-record-shapes flag False 在 profile trace 中记录张量形状

自定义 Rollout 函数

参数 类型 默认值 说明
--rollout-function-path str relax.engine.rollout.sglang_rollout.generate_rollout Rollout 生成函数路径
--custom-generate-function-path str None 自定义 generate 函数，替换默认 rollout 中的 generate 函数。适合实现多轮对话、function calling 等特殊逻辑
--rollout-data-postprocess-path str None Rollout 数据后处理函数，在获取完所有数据（包含 log_probs）后调用。可用于更新 loss mask
--custom-rollout-log-function-path str None 自定义 Rollout 日志函数
--custom-eval-rollout-log-function-path str None 自定义评估 Rollout 日志函数

批处理配置

参数 类型 默认值 说明
--global-batch-size int None 全局批次大小。定义执行一次参数更新（optimizer.step）所需的样本量
--micro-batch-size int 1 微批次大小。开启 --use-dynamic-batch-size 后该值被忽略
--num-steps-per-rollout int None 每次 Rollout 的训练步数。等效于设置 GBS = rollout_batch_size * n_samples_per_prompt / num_steps_per_rollout
--use-dynamic-batch-size flag False 启用动态批处理。根据样本长度动态打包，使每个 micro-batch 的总 Token 数接近 --max-tokens-per-gpu 限制
--max-tokens-per-gpu int None 每个 GPU 的最大 Token 数。启用动态批处理时必须设置。使用 CP 时应设为约 max_response_len / cp_size
--log-probs-max-tokens-per-gpu int None 计算 log probs 时每个 GPU 的最大 Token 数。None 时等于 max-tokens-per-gpu
--balance-data flag False 使用 karmarkar_karp 算法在数据并行 rank 间平衡 Token 数量。仅在 colocate 模式下可用，不支持 --fully-async。注意同一 Prompt 的不同响应可能被分到不同训练步

并行配置

参数 类型 默认值 说明
--tensor-model-parallel-size int 1 张量并行大小
--pipeline-model-parallel-size int 1 流水线并行大小
--sequence-parallel flag False 启用序列并行
--context-parallel-size int 1 上下文并行大小
--expert-model-parallel-size int 1 专家并行大小（MoE 模型）
--expert-tensor-parallel-size int 1 专家张量并行大小

重计算

重计算部分使用的是 Megatron 原生参数，具体可参考 Megatron 文档。

参数 类型 默认值 说明
--recompute-granularity str - 重计算粒度：full、selective
--recompute-method str - 重计算方法：uniform、block
--recompute-num-layers int - 重计算层数

优化器配置

参数 类型 默认值 说明
--lr float 1e-6 学习率
--optimizer str - 优化器类型（Megatron 原生参数）
--lr-decay-style str - 学习率衰减方式（Megatron 原生参数）
--weight-decay float - 权重衰减（Megatron 原生参数）
--adam-beta1 float - Adam beta1（Megatron 原生参数）
--adam-beta2 float - Adam beta2（Megatron 原生参数）
--clip-grad float 1.0 梯度裁剪
--seed int 1234 随机种子
--optimizer-cpu-offload flag - 启用 CPU offload 优化器状态（Megatron 原生参数）
--overlap-cpu-optimizer-d2h-h2d flag - 重叠 CPU 优化器 D2H/H2D 通信（Megatron 原生参数）
--use-precision-aware-optimizer flag - 使用精度感知优化器（Megatron 原生参数）
--use-distributed-optimizer flag - ZeRO-1 风格分片优化器状态（Megatron 原生参数）
--overlap-grad-reduce flag - 反向计算与 grad reduce-scatter 重叠（Megatron 原生参数）
--overlap-param-gather flag - reduce-scatter 与下一步 param all-gather 重叠，强制配合 --overlap-grad-reduce（Megatron 原生参数）
--calculate-per-token-loss flag False 按 Token 计算损失（Megatron 原生参数）

优化器 Flag 兼容性

场景 --use-distributed-optimizer --overlap-grad-reduce / --overlap-param-gather
纯文本 Dense ✅ ✅
Dense VL，CP = 1 ✅ ✅
Dense VL，CP > 1 ✅ ❌
MoE ✅ ❌

算法配置

优势估计

参数 类型 默认值 可选值 说明
--advantage-estimator str grpo grpo, gspo, on_policy_distillation, sapo 优势估计器。注意：OPD 现在独立于优势估计器，使用 --opd-kl-coef > 0 在任何估计器上启用 OPD
--normalize-advantages flag False - 是否归一化优势
--disable-grpo-std-normalization flag - - 禁用 GRPO 标准差归一化（来自 Dr.GRPO）
--disable-rewards-normalization flag - - 禁用 reward 归一化
--disable-compute-advantages-and-returns flag - - 禁用优势和回报计算。用于 SFT 或自定义损失函数

损失函数

参数 类型 默认值 可选值 说明
--loss-type str policy_loss policy_loss, sft, custom_loss 损失类型。policy_loss 跑 PPO/GRPO 等 RL 训练；sft 跑监督微调（详见 SFT 配置）；custom_loss 需配 --custom-loss-function-path。sft_loss 是 sft 的已弃用别名。
--custom-loss-function-path str None - 自定义损失函数路径
--eps-clip float 0.2 - PPO 裁剪范围（下界）
--eps-clip-high float None - PPO 裁剪上界。None 时等于 --eps-clip
--eps-clip-c float None - Dual-clip PPO 的值下界（论文）
--value-clip float 0.2 - 值函数裁剪范围
--entropy-coef float 0.0 - 熵损失系数

KL 散度相关

参数 类型 默认值 说明
--kl-coef float 0.0 KL 惩罚系数，用于 reward shaping（在优势计算之前应用到 reward 信号）。不能与 --kl-loss-coef 同时非零
--use-kl-loss flag False 是否使用 GRPO 中的 KL 损失
--kl-loss-coef float 0.0 KL 惩罚系数，添加到最终 PPO 损失中。不能与 --kl-coef 同时非零
--kl-loss-type str k1 k1, k2, k3, low_var_kl
--use-unbiased-kl flag False 启用无偏 KL 估计
--ref-update-interval int None 参考模型更新间隔（Rollout 步数）。None 表示不更新参考模型

SAPO 参数

参数 类型 默认值 说明
--sapo-tau-pos float 1.0 SAPO 正优势温度
--sapo-tau-neg float 1.05 SAPO 负优势温度

Critic 配置

参数 类型 默认值 说明
--num-critic-only-steps int 0 仅训练 Critic 的步数
--critic-train-only flag False 仅训练 Critic 模型
--critic-lr float None Critic 学习率。None 时等于 --lr
--critic-lr-warmup-iters int 0 Critic 模型线性预热的迭代数

Off-Policy 修正

参数 类型 默认值 说明
--use-rollout-logprobs flag False 计算重要性采样比率时使用 Rollout 的 logprobs。未设置时使用 Actor 模型的 logprobs
--use-tis flag False 启用 TIS（Truncated Importance Sampling）off-policy 重要性采样
--tis-clip float 2.0 重要性采样比率的裁剪阈值上界
--tis-clip-low float 0 重要性采样比率的裁剪阈值下界
--custom-tis-function-path str None 自定义 TIS/RS 函数路径
--custom-pg-loss-reducer-function-path str None 自定义 pg_loss reducer 函数路径。设置后 pg_loss 使用自定义 reducer，其他指标仍使用默认的 sum_of_sample_mean

Routing Replay 与 OPSM

参数 类型 默认值 说明
--use-routing-replay flag False 启用 Routing Replay（论文）
--use-rollout-routing-replay flag False 启用 Rollout Routing Replay（论文）。启用后会自动开启 --use-routing-replay
--use-opsm flag False 启用 Off-Policy Sequence Masking (OPSM)
--opsm-delta float 1e-4 OPSM 阈值

其他训练选项

参数 类型 默认值 说明
--reset-optimizer-states flag False 每次 Rollout 后是否重置优化器状态
--use-rollout-entropy flag False 计算 logprobs 时是否同时计算熵。用于特殊 loss mask
--get-mismatch-metrics flag False 是否计算 mismatch 指标。需要同时设置 --custom-tis-function-path

参数冻结与选择性训练

参数 类型 默认值 说明
--only-train-params-name-list str (列表) None 要训练的参数名正则表达式列表。其余参数被冻结。不能与 --freeze-params-name-list 同时使用。示例：--only-train-params-name-list experts
--freeze-params-name-list str (列表) None 要冻结的参数名正则表达式列表。其余参数保持可训练。示例：--freeze-params-name-list embedding output_layer

SFT 配置

以下参数仅在 --loss-type sft 下生效。SFT 流水线由 SFTStreamingDataset producer（把 packed 样本推入 TransferQueue 的 sft_<rollout_id> 分区）和 MegatronTrainRayActor consumer（训练、周期性 PPL eval、可选生成式 predict）组成。

训练控制

参数 类型 默认值 说明
--eval-size float None 从 --prompt-data 切出一份 holdout eval 集，而不是另外指定 --eval-prompt-data。值 <1 视为训练集的占比（例如 0.05 → 末尾 5%）；值 ≥1 视为绝对样本数。被预留的尾部会从训练池里移除，所以训练样本和 eval 样本永不重叠。与 --eval-prompt-data 互斥。
--sft-predict-interval int None 每 N 个 rollout step 在 eval 集上跑一次生成式 predict，把生成结果写到 <save>/predict/predictions_step_<rollout_id>.jsonl。设置该参数后会自动拉起 Rollout 角色（SGLang 必须在线）。它是 always-on 的 PPL eval（--eval-interval）的生成式补充。必需：--save（写到 <save>/predict/ 下）以及至少一个 eval 数据源（--eval-prompt-data / --eval-config / --eval-size）。

流式数据集预取

SFT producer 用自己的 PrefetchBuffer，跟 rollout 数据源的 --prefetch-* 参数互相独立。

参数 类型 默认值 说明
--sft-prefetch-buffer-size int 256 SFT 流式数据集 PrefetchBuffer 缓存的最大预加载样本数。设为 0 禁用预取，producer 会回退到基于 ProcessorPool 的 asyncio.gather 路径做 batch 级并行。
--sft-prefetch-chunk-size int 32 每轮派发给 SFT 预取线程池的 chunk 大小。
--sft-prefetch-num-workers int 4 SFT PrefetchBuffer 内部用于 I/O 密集型媒体解码（视频/图像）的工作线程数。

超长样本处理

SFT producer 如何处理 tokenize + 多模态展开后长度超过单卡容量（--max-tokens-per-gpu × --context-parallel-size）的样本。所有分支都会给每个超长样本打一条 WARNING 日志。

参数 类型 默认值 可选值 说明
--sft-oversize-strategy str keep skip, keep, truncate_left, truncate_right, custom skip 丢弃样本；keep 原样返回（可能下游 OOM）；truncate_left 保留末尾 capacity 个 token；truncate_right 保留开头 capacity 个 token；custom 委托给 --sft-oversize-custom-function-path。⚠ 直接截多模态样本可能导致 multimodal_train_inputs 错位——需要同时裁剪媒体输入时请用 custom。
--sft-oversize-custom-function-path str None - 在 --sft-oversize-strategy custom 时必填。指向一个 Python 可导入函数，签名为 def truncate(tokens, loss_mask, capacity, idx) -> (tokens, loss_mask) | None。返回 None 等同于 skip。

::: tip 相关数据集参数 SFT 还会用到通用的数据配置参数，特别是 --input-key、--label-key、--conversation-key-map（sharegpt 风格数据集）、--multimodal-keys、--system-prompt、--tool-key。 :::

评估配置

参数 类型 默认值 说明
--eval-interval int None 评估间隔（Rollout 轮数）
--eval-prompt-data str (列表) None 评估数据集，格式：dataset_name /path/to/data.jsonl，可指定多对
--eval-config str None OmegaConf YAML/JSON 评估配置文件路径。设置时覆盖 --eval-prompt-data
--eval-function-path str None 评估生成函数路径。None 时使用 --rollout-function-path
--skip-eval-before-train flag False 是否跳过训练前的评估
--eval-input-key str None 评估数据中输入字段的 key。None 时使用 --input-key
--eval-label-key str None 评估数据中标签字段的 key
--eval-tool-key str None 评估数据中 tool 字段的 key
--n-samples-per-eval-prompt int 1 每个评估 Prompt 的采样数量
--eval-temperature float None 评估时采样温度
--eval-top-p float None 评估时 Top-p 参数
--eval-top-k int None 评估时 Top-k 参数
--eval-max-response-len int None 评估时最大响应长度
--eval-max-prompt-len int None 评估时最大 Prompt 长度
--eval-min-new-tokens int None 评估时最少新生成的 Token 数
--eval-max-context-len int None 评估时最大上下文长度。None 时等于 --rollout-max-context-len

Reward 配置

参数 类型 默认值 说明
--rm-type str None 内置 Reward 模型类型
--custom-rm-path str None 自定义 Reward 函数路径。函数签名：def custom_rm(args, sample) -> float
--reward-key str None Reward 函数返回 dict 时提取 reward 值的 key
--eval-reward-key str None 评估时的 reward key。None 时等于 --reward-key
--group-rm flag False 是否对整个 group 做 Reward 计算
--rm-url str None 远程 Reward 模型服务 URL（用于 --rm-type remote_rm）
--custom-reward-post-process-path str None 自定义 reward 后处理函数路径。默认是 GRPO 的归一化处理
--custom-convert-samples-to-train-data-path str None 自定义样本到训练数据的转换函数。签名：def convert_samples_to_train_data(args, samples) -> dict

GenRM（生成式奖励模型）

参数 类型 默认值 说明
--genrm-model-path str None GenRM 模型路径。设置后启用 GenRM
--genrm-num-gpus int 1 GenRM 使用的总 GPU 数
--genrm-num-gpus-per-engine int 1 每个 GenRM 引擎实例的 GPU 数
--genrm-engine-config json None GenRM 引擎初始化参数。示例：'{"dp_size": 1, "pp_size": 1, "max_total_tokens": 8192}'
--genrm-sampling-config json None GenRM 采样参数。可用 key：temperature（默认 0.1）、top_p（默认 1.0）、top_k（默认 -1）、max_response_len（默认 4096）

On-Policy Distillation（OPD）

参数 类型 默认值 可选值 说明
--use-opd flag False - 启用 On-Policy Distillation。需同时指定 --opd-type
--opd-type str None sglang, megatron OPD 类型。sglang：从外部 SGLang 服务器获取教师模型的 logprobs；megatron：通过 --opd-teacher-load 加载教师模型
--opd-kl-coef float 1.0 - OPD KL 惩罚系数
--opd-teacher-load str None - OPD 教师模型检查点路径。--opd-type=megatron 时必须设置
--opd-teacher-ckpt-step int None - OPD 教师模型检查点步数

容错配置

参数 类型 默认值 说明
--use-fault-tolerance flag False 是否启用 Rollout 期间的容错功能
--use-health-check flag False 是否启用全局健康检查系统。Controller 的 HealthManager 监控所有服务，故障时触发自动重启
--max-global-restart int 3 允许的最大全局重启次数。超过后训练终止。仅在 --use-health-check 启用时生效
--rollout-health-check-interval float 30.0 Rollout 引擎健康检查间隔（秒）
--rollout-health-check-timeout float 30.0 Rollout 引擎健康检查超时时间（秒）
--rollout-health-check-first-wait float 0 开始健康检查前的初始等待时间（秒）。使用 deepgemm 时需要增大此值

弹性扩缩容配置

Autoscaler

参数 类型 默认值 说明
--autoscaler-config str None Autoscaler YAML 配置文件路径。设置后启用自动扩缩容，未设置则禁用。示例：--autoscaler-config relax/utils/autoscaler/autoscaler.yaml

Autoscaler YAML 配置详情请参见 relax/utils/autoscaler/autoscaler.yaml。

Scale-Out 操作参数

参数 类型 默认值 可选值 说明
--scale-out-timeout float 300.0 - 所有扩容操作（引擎启动、连接、健康检查、权重同步等）的超时时间（秒）
--scale-out-partial-success-policy str rollback_all rollback_all, keep_partial 扩容部分成功时的策略。rollback_all 回滚所有引擎；keep_partial 保留成功的引擎

Scale-In 操作参数

参数 类型 默认值 说明
--scale-in-drain-timeout float 30.0 等待进行中请求排空的超时时间（秒），超时后强制终止
--scale-in-shutdown-timeout float 30.0 SGLang 引擎优雅关闭的超时时间（秒），超时后使用 ray.kill 强制终止

日志与监控配置

TensorBoard

参数 类型 默认值 说明
--use-tensorboard flag False 启用 TensorBoard 日志
--tb-project-name str None TensorBoard 日志目录。默认使用环境变量 TENSORBOARD_DIR
--tb-experiment-name str None TensorBoard 实验名称

ClearML

参数 类型 默认值 说明
--use-clearml flag False 启用 ClearML 日志

Metrics Service

参数 类型 默认值 说明
--use-metrics-service flag False 启用集中化指标收集和报告服务
--timeline-dump-dir str None 时间线 trace 事件导出目录（Chrome Trace 格式）。未设置则禁用时间线追踪

日志选项

参数 类型 默认值 说明
--log-passrate flag False 启用 pass@n 通过率日志
--log-multi-turn flag False 启用多轮 Rollout 信息日志
--log-correct-samples flag False 记录正确样本
--log-reward-category str None 记录 reward 分类统计。指定 reward dict 中的 key

通知

参数 类型 默认值 说明
--notify-urls str None Apprise 通知 URL 列表（逗号分隔）

Router 配置

参数 类型 默认值 说明
--use-slime-router flag False 使用 SlimeRouter 进行基于文本的路由而非 SGLang 的基于 Token 的路由
--slime-router-middleware-paths str (列表) "" 中间件路径列表
--slime-router-timeout float None SlimeRouter HTTP 请求超时时间（秒）
--slime-router-max-connections int None SlimeRouter HTTP 客户端最大连接数
--slime-router-health-check-failure-threshold int 3 连续失败多少次后标记 worker 为不健康
--slime-router-sticky flag False 启用 sticky 粘性会话路由：将路由 key（从 X-SMG-Routing-Key 请求头读取）钉定到固定 worker，使同一 key 的后续请求复用该 worker 的 prefix/KV 缓存。已钉定的存活绑定不会因新增 worker 而重分配（仅当其 worker 离开健康集合时才 remap）。需配合 --use-slime-router
--slime-router-sticky-idle-secs float 600.0 sticky 的 key→worker 绑定空闲（未被路由）超过该秒数后淘汰，避免路由 key 基数无界导致映射表膨胀。需配合 --slime-router-sticky

其他训练参数

参数 类型 默认值 说明
--train-env-vars json {} 训练进程的额外环境变量
--train-memory-margin-bytes int 1GB (1024³) 训练内存分配的预留空间
--disable-weights-backuper flag - 禁用权重备份以节省主机内存
--custom-model-provider-path str None 自定义模型 provider 函数路径
--recompute-loss-function flag False 是否重计算损失函数以节省显存
--log-probs-chunk-size int -1 分块计算 log probs 的大小。用于节省显存
--allgather-cp flag False -
--model-name str None 模型名称，用于 Megatron 到 HF 权重转换。未设置时从 AutoConfig.from_pretrained(hf_checkpoint) 推断
--only-load-weight flag False 参考模型和 actor fwd 仅加载权重
--rlsp-server-port int 8234 RLSP Server HTTP 端口
--custom-config-path str None 自定义参数 YAML 配置文件路径。文件中的 key-value 会覆盖已有参数

调试与性能分析参数

调试

参数 类型 默认值 说明
--debug-rollout-only flag False 仅运行 Rollout，不训练
--debug-train-only flag False 仅运行训练，不 Rollout
--load-debug-rollout-data str None 加载调试用 Rollout 数据。设置后自动启用 --debug-train-only
--load-debug-rollout-data-subsample float None 子采样部分调试 Rollout 数据以加速调试
--save-debug-rollout-data str None 保存 Rollout 数据，路径支持 {rollout_id} 占位符
--save-debug-train-data str None 保存训练数据，路径支持 {rollout_id} 占位符
--dump-details str None 导出所有训练细节用于事后分析
--check-weight-update-equal flag False 检查权重更新是否相等
--enable-cuda-memory-check flag False 在底层 NCCL 通信调用周围启用内存检查。在每次集合通信前记录可用 GPU 显存，通信失败时将内存信息附加到异常中

训练性能 Profiling

以下参数控制训练过程的 PyTorch Profiler 采集。Trace 文件默认保存到 traces/<tb_experiment_name>/train_trace/ 目录下。

参数 类型 默认值 说明
--use-pytorch-profiler flag False 启用 PyTorch 内置 profiler 记录训练步骤的 CUDA kernel、CPU op 和通信操作（来自 Megatron）
--profile-step-start int 10 开始 profiling 的步数偏移（inclusive，来自 Megatron）。指从本次训练启动后的第 N 步开始采集，非绝对 rollout ID；断点续训时计数从 0 重新开始
--profile-step-end int 12 停止 profiling 的步数偏移（inclusive，来自 Megatron）。含义同上。例如 start=10, end=12 会采集 step 10, 11, 12（共 3 步）
--profile-target str (列表) train_overall 性能分析目标：train_overall、train_actor、train_log_probs
--profile-with-stack flag False 在 profiler trace 中记录调用栈信息
--profile-with-memory flag False 在 profiler trace 中记录内存信息
--profile-with-flops flag False 在 profiler trace 中估算 FLOPs

GPU 内存 Profiling

以下参数控制 GPU 内存快照采集，用于诊断显存泄漏和 OOM 问题。Snapshot 文件可用 PyTorch Memory Viz 工具（torch.cuda.memory._viz）查看。

参数 类型 默认值 说明
--record-memory-history flag False 启用 CUDA 内存分配历史记录（来自 Megatron）。开启后会记录每次分配/释放的调用栈和张量信息，并在发生 OOM 时自动 dump snapshot
--memory-snapshot-path str snapshot.pickle 内存快照文件名（来自 Megatron）
--memory-snapshot-dir str None 内存快照保存目录。默认使用 traces/<tb_experiment_name>/memory_snapshot
--memory-snapshot-num-steps int None 在指定步数后主动 dump 内存快照（0-indexed，即设为 3 表示在第 2 步后 dump）
--memory-recorder str torch 内存记录器后端：torch（PyTorch 内置）、memray（需要 pip install memray）

网络

参数 类型 默认值 说明
--http-proxy str None HTTP 代理地址
--use-distributed-post flag False 使用分布式 POST 请求

环境配置

Relax 使用 configs/env.yaml配置运行时环境变量：

env_vars:
  TOKENIZERS_PARALLELISM: 'true'
  NCCL_DEBUG: 'WARN'
  CUDA_DEVICE_MAX_CONNECTIONS: '1'
  GLOO_SOCKET_IFNAME: "eth0"
  TP_SOCKET_IFNAME: "eth0"