命令行参数

Megatron参数

训练参数:

  • 🔥micro_batch_size: 每个device的批次大小，默认为1。

  • 🔥global_batch_size: 总批次大小，等价于micro_batch_size*数据并行大小*梯度累加步数。默认为16。

  • 🔥recompute_granularity: 重新计算激活的粒度，可选项为'full', 'selective'。其中full代表重新计算整个transformer layer，selective代表只计算transformer layer中的核心注意力部分。通常'selective'是推荐的。默认为'selective'。

    • 当你设置为'selective'时，你可以通过指定--recompute_modules来选择对哪些部分进行重新计算。

  • 🔥recompute_method: 该参数需将recompute_granularity设置为'full'才生效，可选项为'uniform', 'block'。默认为None。

  • 🔥recompute_num_layers: 该参数需将recompute_granularity设置为'full'才生效，默认为None。若recompute_method设置为uniform，该参数含义为每个均匀划分的重新计算单元的transformer layers数量。例如你可以指定为--recompute_granularity full --recompute_method uniform --recompute_num_layers 4。recompute_num_layers越大，显存占用越小，计算成本越大。注意：当前进程中的模型层数需能被recompute_num_layers整除。默认为None。

  • 🔥recompute_modules: 选项包括"core_attn", "moe_act", "layernorm", "mla_up_proj", "mlp", "moe"，默认值为["core_attn"]。该参数在--recompute_granularity selective时生效。例如在MoE训练时，你可以通过指定--recompute_granularity selective --recompute_modules core_attn moe降低显存。其中"core_attn"、"mlp" 和 "moe" 使用常规检查点，"moe_act"、"layernorm" 和 "mla_up_proj" 使用输出丢弃检查点。

    • "core_attn"：重新计算 Transformer 层中的核心注意力部分。

    • "mlp"：重新计算密集的 MLP 层。

    • "moe"：重新计算 MoE 层。

    • "moe_act"：重新计算 MoE 中的 MLP 激活函数部分。

    • "layernorm"：重新计算 input_layernorm 和 pre_mlp_layernorm。

    • "mla_up_proj"：重新计算 MLA 上投影和 RoPE 应用部分。

  • deterministic_mode: 确定性模式，这会导致训练速度下降，默认为False。

  • 🔥train_iters: 训练的总迭代次数，默认为None。

    • 提示：你可以通过设置--max_epochs来设置训练的epochs数。在使用非流式数据集时，会自动根据数据集数量计算train_iters（兼容packing）。

  • 🔥max_epochs: 指定训练的epochs数。当使用非流式数据集时，该参数会为你自动计算train_iters而不需要手动传入train_iters。当使用流式数据集时，该参数会在训练到max_epochs时强制退出训练，并对权重进行验证和保存。默认为None。

  • 🔥log_interval: log的时间间隔（单位：iters），默认为5。

  • tensorboard_dir: tensorboard日志写入的目录。默认None，即存储在f'{save}/runs'目录下。

  • no_masked_softmax_fusion: 默认为False。用于禁用query_key_value的scaling, masking, and softmax融合。

  • no_bias_dropout_fusion: 默认为False。用于禁用bias和dropout的融合。

  • no_bias_swiglu_fusion: 默认为False。指定--no_bias_dropout_fusion true，用于禁止bias和swiglu融合。

  • no_rope_fusion: 默认为False。指定--no_rope_fusion true用于禁止rope融合。

    • 当使用mrope等不支持rope_fusion的位置编码时，该参数会自动设置为True。

  • no_gradient_accumulation_fusion: 默认为False。指定--no_gradient_accumulation_fusion true用于禁用梯度累加融合。

  • 🔥cross_entropy_loss_fusion: 启动交叉熵损失计算融合。默认为False。

  • cross_entropy_fusion_impl: 交叉熵损失融合的实现。可选为'native'和'te'。默认为'native'。

  • calculate_per_token_loss: 根据全局批次中的非填充token数量来对交叉熵损失进行缩放。默认为True。

    • 注意：该参数在rlhf训练或者task_type不等于'causal_lm'时，默认为False。

  • 🔥attention_backend: 使用的注意力后端 (flash、fused、unfused、local、auto)。默认为 flash。

    • 注意：推荐flash_attn版本：2.7.4.post1/2.8.1。在"ms-swift<3.7"的版本中，该参数的默认为'auto'。

    • 如果安装'flash_attention_3'，--attention_backend flash则优先使用fa3。训练脚本参考这里。

  • optimizer: 优化器类型，可选为'adam'、'sgd'。默认为adam。

  • 🔥optimizer_cpu_offload: 将优化器状态卸载到 CPU，例如设置：--use_precision_aware_optimizer true --optimizer_cpu_offload true --optimizer_offload_fraction 0.7。默认为False。

    • 该参数可以显著降低显存占用（但增加内存占用）。若global_batch_size较大，则对训练速度的影响不大。

  • 🔥optimizer_offload_fraction: 卸载到 CPU 的优化器状态所占比例。默认为1.。

  • use_precision_aware_optimizer: 使用 TransformerEngine 中的精度感知优化器，该优化器允许将主参数和优化器状态设置为较低精度，例如 fp16 和 fp8。

  • main_grads_dtype: 启用 use_precision_aware_optimizer 时主梯度的 dtype。可选为'fp32', 'bf16'。默认为'fp32'。

  • main_params_dtype: 启用 use_precision_aware_optimizer 时主参数的 dtype。可选为'fp32', 'fp16'。默认为'fp32'。

  • exp_avg_dtype: 启用 use_precision_aware_optimizer 时，adam 优化器中 exp_avg（即一阶矩）的 dtype。该 dtype 用于在训练过程中将优化器状态存储在内存中，但不会影响内核计算时的精度。可选为'fp32', 'fp16', 'bf16', 'fp8'。默认为'fp32'。

  • exp_avg_sq_dtype: 启用 use_precision_aware_optimizer 时，adam 优化器中 exp_avg_sq（即二阶矩）的 dtype。该 dtype 用于在训练过程中将优化器状态存储在内存中，但不会影响内核计算的精度。可选为'fp32', 'fp16', 'bf16', 'fp8'。默认为'fp32'。

  • dataloader_type: 默认为'cyclic'，可选为'single', 'cyclic', 'external'。若开启--streaming，则设置为external。

  • manual_gc: 禁用默认垃圾回收器，手动触发垃圾回收。默认为False。

  • manual_gc_interval: 手动触发垃圾回收的间隔。默认为0。

  • seed: python、numpy、pytorch和cuda的随机种子，默认为42。

  • 🔥num_workers: dataloader的workers数量，默认为4。

    • 注意：若设置--streaming true，则设置为1。

  • seq_length: 默认为None，即设置为max_length。对数据集长度进行限制建议使用“基本参数”中的--max_length控制，无需设置此参数。

  • use_cpu_initialization: 在cpu上初始化权重，默认为False。在进行HF和MCore权重转换时会被使用。通常不需要修改该值。

  • 🔥extra_megatron_kwargs: 额外需要透传入megatron的其他参数，使用json传递。默认为None。

学习率参数:

  • 🔥lr: 初始学习率，最终会根据学习率预热策略和衰减策略决定每个迭代的学习率。默认为None，全参数训练默认为1e-5，LoRA训练默认为1e-4。

  • lr_decay_style: 学习率衰减策略，默认为'cosine'。通常设置为'cosine', 'linear', 'constant'。

  • 🔥lr_decay_iters: 学习率衰减的迭代次数。默认为None，则设置为--train_iters。

  • lr_warmup_iters: 线性学习率预热的迭代次数，默认为0。

  • 🔥lr_warmup_fraction: 线性学习率预热阶段所占比例，默认为None。

  • 🔥min_lr: 学习率的最小值，将低于该阈值的学习率裁剪为该值，默认为0。

正则化参数:

  • 🔥weight_decay: 默认为0.1。

  • 🔥clip_grad: l2梯度裁剪，默认为1.0。

    • 日志中打印的grad_norm为未裁剪前的值。

  • adam_beta1: 默认0.9。

  • adam_beta2: 默认0.95。

  • adam_eps: 默认1e-8。

  • sgd_momentum: 设置--optimizer sgd时生效，默认为0.9。

checkpoint参数:

  • 🔥save: checkpoint的输出目录，默认None。在训练中，若未设置该参数，则默认为f'megatron_output/{model_suffix}'，例如'megatron_output/Qwen2.5-7B-Instruct'。

    • 注意：若在多机训练时，请确保每个节点的保存路径指向相同位置，否则你需要在训练后手动集中这些权重。

  • 🔥save_interval: checkpoint保存的间隔（steps），默认为500。

    • 注意：训练结束时一定会保存权重。

  • 🔥save_retain_interval: 保留检查点的迭代间隔。只有迭代步数是该间隔倍数的检查点才会被保留（最后一个检查点除外）。

  • 🔥no_save_optim: 不保存optimizer，默认为False。在全参数训练时，可以显著降低存储时间。

  • 🔥no_save_rng: 不保存rng，默认为False。

  • 🔥load: 加载的checkpoint目录，默认None。

    • 注意：若未使用ms-swift提供的swift export进行权重转换，你需要额外设置--model <hf-repo>用于加载config.json配置文件。

    • 对于断点续训的介绍，请查看--finetune参数的介绍。

  • 🔥no_load_optim: 不载入optimizer，默认为False。

    • 注意：断点续训时，设置--no_load_optim false读取优化器状态通常比--no_load_optim true不读取优化器状态消耗更大的显存资源。

  • 🔥no_load_rng: 不载入rng，默认为False。

  • 🔥finetune: 将模型加载并微调。不加载检查点的优化器和随机种子状态，并将迭代数设置为0。默认为False。

    • 注意：断点续训你需要设置--load（lora训练需要额外设置--adapter_load），若设置--finetune true，将不加载优化器状态和随机种子状态并将迭代数设置为0，不会进行数据集跳过；若设置--finetune false，将读取迭代数并跳过之前训练的数据集数量，优化器状态和随机种子状态的读取通过--no_load_optim和--no_load_rng控制。

    • 流式数据集--streaming，暂不支持跳过数据集。

  • ckpt_format: checkpoint的格式。可选为'torch', 'torch_dist', 'zarr'。默认为'torch_dist'。（暂时权重转换只支持'torch_dist'格式）

  • no_initialization: 不对权重进行初始化，默认为True。

  • auto_detect_ckpt_format: 自动检测ckpt format为legacy还是distributed格式。默认为True。

  • exit_on_missing_checkpoint: 如果设置了–-load，但找不到检查点，则直接退出，而不是初始化。默认为True。

  • 🔥async_save: 使用异步检查点保存。目前仅适用于torch_dist分布式检查点格式。默认为False。

  • use_persistent_ckpt_worker: 使用持久化检查点工作进程用于异步保存，即创建专门后台进程来处理异步保存。默认为False。

  • ckpt_fully_parallel_load: 跨 DP 对分布式检查点使用完全加载并行化，加速权重加载速度。默认为False。

  • ckpt_assume_constant_structure: 如果在单个训练中，模型和优化器状态字典结构保持不变，允许Megatron进行额外检查点性能优化。默认为False。

分布式参数: 并行技术的选择请参考训练技巧文档。

  • distributed_backend: 分布式后端，可选为'nccl', 'gloo'。默认为nccl。

  • 🔥use_distributed_optimizer: 使用分布式优化器（即zero1）。默认为True。

  • 🔥tensor_model_parallel_size: tp数，默认为1。

  • 🔥pipeline_model_parallel_size: pp数，默认为1。

  • 🔥decoder_first_pipeline_num_layers: decoder第一个流水线阶段所包含的Transformer层数。默认为 None，表示将Transformer层数平均分配到所有流水线阶段。

    • 该参数通常用于Transformer层数无法被PP整除，或者多模态模型第0个pp阶段显存占用过高的情况。

  • 🔥decoder_last_pipeline_num_layers: decoder最后一个流水线阶段所包含的Transformer层数。默认为 None，表示将Transformer层数平均分配到所有流水线阶段。

  • 🔥sequence_parallel: 启动序列并行优化，该参数需要设置tensor_model_parallel_size才生效。默认为False。

  • 🔥context_parallel_size: cp数，默认为1。

  • tp_comm_overlap: 启用张量并行通信与GEMM（通用矩阵乘法）内核的重叠（降低通信耗时）。默认为False。

  • 🔥overlap_grad_reduce: 启用DDP中grad reduce操作的重叠（降低DP通信耗时）。默认为False。

  • 🔥overlap_param_gather: 启用分布式优化器中参数all-gather的重叠（降低DP通信耗时）。默认为False。

  • distributed_timeout_minutes: torch.distributed的timeout时间（单位为分钟），该参数失效，使用基础参数中的ddp_timeout控制，默认为300000分钟。

  • num_layers_per_virtual_pipeline_stage: 每个虚拟流水线阶段的层数。默认为None。该参数和--num_virtual_stages_per_pipeline_rank参数都可以用来设置vpp并行。

  • num_virtual_stages_per_pipeline_rank: 每个流水线并行 rank 的虚拟流水线阶段数量。默认为None。vpp并行，用于减少pp并行的计算空泡，提高GPU利用率，但会略微提高通信量。

  • microbatch_group_size_per_virtual_pipeline_stage: 每个虚拟流水线阶段处理的连续微批次数量。默认为None，等于pipeline_model_parallel_size。

  • 🔥pipeline_model_parallel_layout: 一个描述自定义流水线（pp/vpp）模型并行布局的字符串。例如："E|(t|)*3,m|m||L"。其中 E、L、t、m 分别表示嵌入层（embedding）、损失层（loss）、Transformer 解码器层和 MTP 层。阶段之间用 "|" 分隔。重复的阶段或层可以通过乘法表示。逗号仅用于提升可读性（无实际语法作用）。默认值为 None，表示不使用此参数设置布局。

    • 该参数通常在异构GPU集群上使用。

日志参数:

  • log_params_norm: 记录参数的norm。默认为False。

  • log_throughput: 记录每个GPU的吞吐量（理论值）。默认为False。

    • 注意：在非packing情况下，log_throughput并不准确，因为seq_length并不等于真实序列长度。

  • tensorboard_log_interval: 记录到tensorboard的间隔（steps），默认为1。

  • tensorboard_queue_size: 队列长度（与磁盘IO相关），类似于写入的间隔。默认为50。

  • log_timers_to_tensorboard: 记录timers到tensorboard。默认为True。

  • no_log_learning_rate_to_tensorboard: 不记录学习率到tensorboard。默认为False。

  • log_validation_ppl_to_tensorboard: 将验证困惑度写入tensorboard。默认为True。

  • log_memory_to_tensorboard: 将内存日志写入tensorboard。默认为True。

  • logging_level: 日志级别。默认为None。

  • wandb_project: wandb 项目名称。默认为''，即忽略wandb。

  • wandb_exp_name: wandb 实验名称。默认为''。

  • wandb_save_dir: 本地保存 wandb 结果的路径。默认为''。

评估参数:

  • 🔥eval_iters: 评估的迭代次数，默认为-1，根据验证数据集的数量设置合适的值。若验证集数量少于global_batch_size，则不进行评估。若使用流式数据集，该值需要手动设置。

  • 🔥eval_interval: 评估的间隔（steps），即每训练多少steps进行评估，默认为None，即设置为save_interval。

fp8参数:

  • fp8_format: 用于前向和反向传播中FP8张量的FP8格式方案。可选为'e4m3'，'hybrid'。默认为None。

  • fp8_recipe: 用于前向和反向传播中 FP8 张量的 FP8 算法方案。可选为'tensorwise', 'delayed', 'mxfp8', 'blockwise'。默认为'delayed'。

  • fp8_amax_history_len: 每个张量记录 amax 历史的步数。默认为1024。

  • fp8_amax_compute_algo: 用于根据历史记录计算 amax 的算法。可选为'most_recent', 'max'。默认为'max'。

  • fp8_param_gather: 保持计算参数为 fp8（不使用任何其他中间数据类型），并在 fp8 格式下执行参数的 all-gather 操作。默认为False。

混合精度参数:

  • fp16: fp16模式。默认为None，会根据模型的torch_dtype进行设置，即torch_dtype为float16或者float32则fp16设置为True。torch_dtype默认读取config.json。

  • bf16: bf16模式。默认为None，会根据模型的torch_dtype进行设置，即torch_dtype为bfloat16则bf16设置为True。

  • apply_query_key_layer_scaling: 将Q * K^T 缩放为 1 / 层数（例如：第layer_num层则除以layer_num）。这对fp16训练很有帮助。默认为None，即若使用--fp16，则设置为True。

  • 🔥attention_softmax_in_fp32: 在attention_mask和softmax中使用fp32进行计算。默认为True。

模型参数: （以下参数通常不需要进行设置，会根据HF模型的config.json进行配置，用户无需关心）

  • num_layers: transformer layers的层数，默认为None。

  • hidden_size: transformer hidden size，默认为None。

  • ffn_hidden_size: transformer FFN层的hidden size。默认为None，设置为4*hidden_size。

  • num_attention_heads: transformer attention heads的个数，默认为None。

  • group_query_attention: 默认为None。若num_query_groups>1，group_query_attention设置为True，否则为False。

  • num_query_groups: 默认为1。

  • max_position_embeddings: 位置编码的最大长度，默认为None。

  • position_embedding_type: 位置编码的类型，可选为'learned_absolute'、'rope'、'mrope'、'relative'和'none'，默认为'rope'。

  • rotary_base: 默认为10000。

  • rotary_percent: 默认为1.。

  • normalization: 可选为'LayerNorm', 'RMSNorm'，默认为RMSNorm。

  • norm_epsilon: 默认为1e-5。

  • swiglu: 使用swiglu替代默认的gelu。默认为True。

  • untie_embeddings_and_output_weights: 解开embedding和输出权重的绑定，默认为True。

  • disable_bias_linear: 禁用linear层的bias。默认为True。

  • add_qkv_bias: 仅在QKV的linear中增加bias，默认为True。

  • attention_dropout: 默认为0.。

  • hidden_dropout: 默认为0.。

  • kv_channels: 默认为None，设置为args.hidden_size // args.num_attention_heads。

  • qk_layernorm: 是否对Q和K进行层归一化。

  • transformer_impl: 使用哪种transformer实现，可选项为'local'和'transformer_engine'。默认为transformer_engine。

  • padded_vocab_size: 完整词表大小，默认为None。

  • rope_scaling: rope_scaling相关参数，默认为None。格式参考llama3.1 config.json，传入json字符串。

    • 目前rope_scaling模块使用transformers实现，支持transformers支持的所有rope_scaling。

MoE参数:

  • num_experts: MoE的专家数，默认为None。自动从config.json读取。

  • moe_layer_freq: MoE 层与 Dense 层之间的分布频率。默认为None。从config.json中读取。

  • moe_ffn_hidden_size: 每个专家的前馈网络（ffn）的隐藏层大小。默认为None，自动从config.json读取。若未读取到且num_experts不为None，则设置为ffn_hidden_size。

  • moe_shared_expert_intermediate_size: 共享专家的总FFN隐藏层大小。如果有多个共享专家，它应等于 num_shared_experts * ffn_size_of_each_shared_expert。 默认为None。自动从config.json读取。

  • moe_router_topk: 每个token路由到的专家数量。默认为None。自动从config.json读取。

  • moe_router_pre_softmax: 为MoE启用预softmax路由，这意味着softmax会在top-k选择之前进行。默认为None。自动从config.json读取。

  • 🔥moe_router_dtype: 用于路由计算和专家输出加权平均的数据类型。可选为'none', 'fp32'、'fp64'，这增强了数值稳定性，尤其是在专家数量较多时。与moe_permute_fusion一起使用时，性能影响可以忽略不计。默认为'fp32'。'none'代表不改变数据类型。

  • moe_router_score_function: MoE TopK 路由的评分函数。可以为 "softmax" 或 "sigmoid"。默认为None，从config.json中读取。

  • moe_router_bias_update_rate: 在无辅助损失负载均衡策略中，专家偏置的更新速率。专家偏置根据每个专家在全局批次中被分配的 token 数量进行更新，对于分配到的 token 较少的专家，偏置会增加；对于分配到的 token 较多的专家，偏置会减少。默认值 1e-3，与 DeepSeekV3 中使用的值相同。

  • moe_router_enable_expert_bias: 在无辅助损失负载均衡策略中，带有动态专家偏置的 TopK 路由。路由决策基于路由分数与专家偏置之和。详情请参见：https://arxiv.org/abs/2408.15664。默认为None，自动从config.json读取。

  • moe_router_topk_scaling_factor: 默认为None。从config.json中读取。

  • moe_router_load_balancing_type: 确定路由器的负载均衡策略。可选项为"aux_loss"、"seq_aux_loss"、"sinkhorn"、"none"。默认值为 None。从config.json中读取。

  • 🔥expert_model_parallel_size: 专家并行数，默认为1。

  • 🔥expert_tensor_parallel_size: 专家TP并行度。默认值为1。

    • 在"ms-swift<3.9"，其默认值为None，即等于--tensor_model_parallel_size 的数值，该默认值将在"ms-swift>=3.9"被修改。

  • moe_token_dispatcher_type: 要使用的token分发器类型。可选选项包括 'allgather'、'alltoall'、'flex'和'alltoall_seq'。默认值为'alltoall'。

  • 🔥moe_grouped_gemm: 当每个rank包含多个专家时，通过在多个流中启动多个本地 GEMM 内核，利用 TransformerEngine中的GroupedLinear提高利用率和性能。默认为False。

  • 🔥moe_permute_fusion: 在令牌分发过程中融合令牌重排操作。默认为False。

  • 🔥moe_aux_loss_coeff: 默认为0，不使用aux_loss。通常情况下，该值设置的越大，训练效果越差，但MoE负载越均衡，请根据实验效果，选择合适的值。

    • 注意：在"ms-swift<3.7.1"，其默认为None，自动从config.json读取。

  • moe_z_loss_coeff: z-loss 的缩放系数。默认为None。

  • 🔥moe_shared_expert_overlap: 启用共享专家计算与调度器通信之间的重叠。如果不启用此选项，共享专家将在路由专家之后执行。仅在设置了moe_shared_expert_intermediate_size时有效。默认为False。

  • 🔥moe_expert_capacity_factor: 每个专家的容量因子，None表示不会丢弃任何token。默认为None。通过设置 --moe_expert_capacity_factor，超出专家容量的 token 会基于其被选中的概率被丢弃。可以令训练负载均匀，提升训练速度（例如设置为1或2）。

  • moe_pad_expert_input_to_capacity: 对每个专家（expert）的输入进行填充，使其长度与专家容量（expert capacity length）对齐，默认为False。该操作仅在设置了 --moe_expert_capacity_factor 参数后才生效。

  • moe_token_drop_policy: 可选为'probs', 'position'。默认为'probs'。

mla参数

  • multi_latent_attention: 是否使用MLA。默认为False。

  • q_lora_rank: Query 张量低秩表示的rank值。默认为None，自动从config.json读取。

  • kv_lora_rank: Key 和 Value 张量低秩表示的秩（rank）值。默认为None，自动从config.json读取。

  • qk_head_dim: QK 投影中 head 的维度。 q_head_dim = qk_head_dim + qk_pos_emb_head_dim。默认为None，自动从config.json读取。

  • qk_pos_emb_head_dim: QK 投影中位置嵌入的维度。默认为None，自动从config.json读取。

Tuner参数:

  • train_type: 可选为'lora'和'full'。默认为'full'。

  • 🔥freeze_llm: 该参数只对多模态模型生效，可用于全参数训练和LoRA训练，但会产生不同的效果。若是全参数训练，将freeze_llm设置为True会将LLM部分权重进行冻结；若是LoRA训练且target_modules设置为'all-linear'，将freeze_llm设置为True将会取消在LLM部分添加LoRA模块。该参数默认为False。

  • 🔥freeze_vit: 该参数只对多模态模型生效，可用于全参数训练和LoRA训练，但会产生不同的效果。若是全参数训练，将freeze_vit设置为True会将vit部分权重进行冻结；若是LoRA训练且target_modules设置为'all-linear'，将freeze_vit设置为True将会取消在vit部分添加LoRA模块。该参数默认为True。

    • 注意：这里的vit不仅限于vision_tower, 也包括audio_tower。若是Omni模型，若你只希望对vision_tower加LoRA，而不希望对audio_tower加LoRA，你可以修改这里的代码。

  • 🔥freeze_aligner: 该参数只对多模态模型生效，可用于全参数训练和LoRA训练，但会产生不同的效果。若是全参数训练，将freeze_aligner设置为True会将aligner（也称为projector）部分权重进行冻结；若是LoRA训练且target_modules设置为'all-linear'，将freeze_aligner设置为True将会取消在aligner部分添加LoRA模块。该参数默认为True。

全参数训练：

  • freeze_parameters: 需要被冻结参数的前缀，默认为[]。

  • freeze_parameters_regex: 需要被冻结参数的正则表达式，默认为None。

  • freeze_parameters_ratio: 从下往上冻结的参数比例，默认为0。可设置为1将所有参数冻结，结合trainable_parameters设置可训练参数。除了设置为0/1，该参数不兼容pp并行。

  • trainable_parameters: 额外可训练参数的前缀，默认为[]。

  • trainable_parameters_regex: 匹配额外可训练参数的正则表达式，默认为None。

lora训练：

  • adapter_load: 加载adapter的权重路径，用于lora断点续训，默认为None。lora断点续训方式与全参数一致，请关注--finetune参数的含义。

  • 🔥target_modules: 指定lora模块的后缀，例如：你可以设置为--target_modules linear_qkv linear_proj。默认为['all-linear']，代表将所有的linear设置为target_modules。

    • 注意：在LLM和多模态LLM中，'all-linear'的行为有所不同。若是LLM则自动寻找除lm_head外的linear并附加tuner；若是多模态LLM，则默认只在LLM上附加tuner，该行为可以被freeze_llm、freeze_vit、freeze_aligner控制。

    • 注意：若需要将所有的router设置为target_modules, 你可以额外设置--target_modules all-router ...，例如：--target_modules all-router all-linear。

  • 🔥target_regex: 指定lora模块的regex表达式，默认为None。如果该值传入，则target_modules参数失效。

  • 🔥modules_to_save: 在已附加tuner后，额外指定一部分原模型模块参与训练和存储。默认为[]。例如设置为--modules_to_save word_embeddings output_layer，在LoRA训练中解开word_embeddings和output_layer层进行训练，这两部分的权重信息最终会进行保存。

  • 🔥lora_rank: 默认为8。

  • 🔥lora_alpha: 默认为32。

  • lora_dropout: 默认为0.05。

  • lora_bias: 默认为'none'，可以选择的值: 'none'、'all'。如果你要将bias全都设置为可训练，你可以设置为'all'。

  • use_rslora: 默认为False，是否使用RS-LoRA。

DPO参数:

  • ref_load: ref_model的加载路径。采用DPO/KTO算法且使用全参数训练时需要传入。默认为None，即设置为load。

  • ref_adapter_load: 加载ref_adapter的权重路径，默认为None。若你要使用SFT产生的LoRA权重进行DPO，请使用"ms-swift>=3.8"，并在训练时设置--adapter_load sft_ckpt --ref_adapter_load sft_ckpt --finetune true。若是此场景的断点续训，则设置--adapter_load rlhf_ckpt --ref_adapter_load sft_ckpt --finetune false。

  • beta: 含义与TRL相同。控制与参考模型偏差程度的参数。beta值越高，表示与参考模型的偏差越小。对于 IPO 损失函数 (loss_type="ipo")，beta是论文中所指的正则化参数。默认为0.1。

  • 🔥rpo_alpha: 来自RPO 论文中的参数，用于控制损失函数中NLL项的权重（即SFT损失），loss = dpo_loss + rpo_alpha * sft_loss，论文中推荐设置为1.。默认为None，即默认不引入sft_loss。

    • 注意：在"ms-swift<3.8"，其默认值为1.。在"ms-swift>=3.8"该默认值修改为None。

  • reference_free: 是否忽略提供的参考模型，并隐式地使用一个对所有响应赋予相等概率的参考模型。默认为False。

  • label_smoothing: 默认为0.。

  • f_divergence_type: 默认为reverse_kl。可选值参考TRL文档。

  • loss_type: 默认为'sigmoid'。可选值参考TRL文档。

KTO参数:

  • ref_load: 含义同DPO。

  • ref_adapter_load: 含义同DPO。

  • beta: 控制与 ref_model 偏离程度的参数。较高的 beta 表示与 ref_model 偏离更小。默认为0.1。

  • loss_type: 默认为'kto'。可选值参考TRL文档。

  • desirable_weight: 抵消 desirable 和 undesirable 数量不均衡的影响，对 desirable 损失按该系数进行加权，默认为1.。

  • undesirable_weight: 抵消 desirable 和 undesirable 数量不均衡的影响，对 undesirable 损失按该系数进行加权，默认为1.。

RM参数:

  • center_rewards_coefficient: 用于激励奖励模型输出均值为零的奖励的系数，具体查看这篇论文。推荐值：0.01。

训练参数

Megatron训练参数继承自Megatron参数和基本参数（与ms-swift共用dataset、template等参数，也支持ms-swift中的特定模型参数）。基本参数的内容可以参考这里。此外还包括以下参数：

  • add_version: 在save上额外增加目录'<版本号>-<时间戳>'防止权重覆盖，默认为True。

  • padding_free: 将一个batch中的数据进行展平而避免数据padding，从而降低显存占用并加快训练。默认为True。

    • 若要自定义attention_mask，你可以设置--padding_free false。

    • 注意：Megatron-SWIFT训练特性优先支持padding_free格式，若非特殊情况，请勿修改该值。

  • mlp_padding_free: 默认为False。用于padding_free设置为false时，对mlp进行padding_free优化。这可以在自定义attention_mask的同时，提升训练速度和减少显存占用。

  • vit_gradient_checkpointing: 多模态模型训练时，是否对vit部分开启gradient_checkpointing。默认为True。（Megatron-SWIFT的vit实现使用transformers实现）

  • gradient_checkpointing_kwargs: 传入torch.utils.checkpoint中的参数。例如设置为--gradient_checkpointing_kwargs '{"use_reentrant": false}'。默认为None。该参数只对vit_gradient_checkpointing生效。

  • 🔥packing: 是否使用序列packing提升计算效率（不同节点与进程更负载均衡，GPU利用率更高；但需要额外的预处理时间）并稳定显存占用，默认为False。当前支持CPT/SFT/DPO/KTO/RM。

    • 注意：同一batch的不同序列之间依旧是不可见的，除了Qwen3-Next。

    • 注意：packing会导致数据集样本数减少，请自行调节梯度累加数和学习率。

  • packing_length: packing的长度。默认为None，设置为max_length。

  • streaming: 流式读取并处理数据集，默认False。

    • 注意：因为流式数据集无法获得其长度，因此需要设置--train_iters参数。设置max_epochs参数确保训练到对应epochs时退出训练，并对权重进行验证和保存。

    • 注意：流式数据集可以跳过预处理等待，将预处理时间与训练时间重叠。流式数据集的预处理只在rank0上进行，并通过数据分发的方式同步到其他进程，其通常效率不如非流式数据集采用的数据分片读取方式。当训练的world_size较大时，预处理和数据分发将成为训练瓶颈。

  • lazy_tokenize: 是否使用lazy_tokenize。若该参数设置为False，则在训练之前对所有的数据集样本进行tokenize（多模态模型则包括从磁盘中读取图片）。该参数默认为None，在LLM训练中默认为False，而MLLM训练默认为True，节约内存。

  • cached_dataset: 训练中使用缓存数据集（使用swift export --to_cached_dataset true ...命令产生），避免大型数据集训练时，tokenize过程占用gpu时间。默认为[]。例子参考这里。

    • 注意：cached_dataset支持--packing，但不支持--lazy_tokenize和--streaming。cached_dataset暂不支持CP。

  • enable_dft_loss: 是否在SFT训练中使用DFT (Dynamic Fine-Tuning) loss，默认为False。

  • enable_channel_loss: 启用channel loss，默认为False。你需要在数据集中准备"channel"字段，ms-swift会根据该字段分组统计loss（若未准备"channel"字段，则归为默认None channel）。数据集格式参考channel loss。channel loss兼容packing/padding_free/loss_scale等技术。

  • new_special_tokens: 需要新增的特殊tokens。默认为[]。例子参考这里。

    • 注意：你也可以传入以.txt结尾的文件路径，每行为一个special token。

  • 🔥task_type: 默认为'causal_lm'。可选为'causal_lm'、'seq_cls'。

  • num_labels: 分类模型（即--task_type seq_cls）需要指定该参数。代表标签数量，默认为None。

  • problem_type: 分类模型（即--task_type seq_cls）需要指定该参数。可选为'regression', 'single_label_classification', 'multi_label_classification'。默认为None，若模型为 reward_model 或 num_labels 为1，该参数为'regression'，其他情况，该参数为'single_label_classification'。

RLHF参数

除了继承训练参数外，还支持以下参数：

  • 🔥rlhf_type: 默认为'dpo'。目前可选择为'dpo'、'kto'和'rm'。

  • loss_scale: 覆盖基本参数中的loss_scale。默认为'last_round'。

  • calculate_per_token_loss: 覆盖Megatron参数，默认为False。