This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,191 @@
|
||||
# Ascend NPU
|
||||
|
||||
关于Megatron-SWIFT在Ascend NPU上的环境准备，请参考[NPU最佳实践](../BestPractices/NPU-support.md)。
|
||||
|
||||
## NPU 性能数据采集
|
||||
|
||||
NPU性能采集通过`torch_npu.profiler.profile`接口进行采集，创建torch_npu.profiler.profile对象，通过start和stop接口控制采集性能数据，采集过程需要修改ms-swift源码，修改swift/megatron/trainers/base.py文件中的train函数，采集示例如下：
|
||||
```python
|
||||
import torch_npu
|
||||
...
|
||||
|
||||
experimental_config = torch_npu.profiler._ExperimentalConfig(
|
||||
profiler_level=torch_npu.profiler.ProfilerLevel.Level1,
|
||||
aic_metrics=torch_npu.profiler.AiCMetrics.PipeUtilization,
|
||||
)
|
||||
|
||||
prof = torch_npu.profiler.profile(
|
||||
activities=[
|
||||
torch_npu.profiler.ProfilerActivity.CPU,
|
||||
torch_npu.profiler.ProfilerActivity.NPU
|
||||
],
|
||||
schedule=torch_npu.profiler.schedule(wait=0, warmup=0, active=1, repeat=1, skip_first=6),
|
||||
on_trace_ready=torch_npu.profiler.tensorboard_trace_handler("./result"),
|
||||
profile_memory=False, # 关闭采集内存信息
|
||||
with_stack=False, # 关闭采集堆栈信息
|
||||
experimental_config=experimental_config)
|
||||
prof.start()
|
||||
# ms-swift 逻辑
|
||||
while state.iteration < args.train_iters:
|
||||
...
|
||||
metric, grad_norm, update_successful = train_step(train_data_iterator)
|
||||
# 性能数据采集
|
||||
prof.step()
|
||||
...
|
||||
prof.stop()
|
||||
```
|
||||
|
||||
## NPU 精度数据采集
|
||||
### 安装msprobe
|
||||
```shell
|
||||
pip install mindstudio-probe
|
||||
```
|
||||
|
||||
### 代码修改
|
||||
为了支持 msprobe 工具进行精度调试，我们需要修改 `swift/megatron/model/mm_gpt_model.py` 文件中的 `_patch_word_embeddings` 函数。主要改动是调整函数参数和内部实现逻辑，使其能够正确地对嵌入层进行patch
|
||||
|
||||
下面是具体的修改内容：
|
||||
|
||||
修改前：
|
||||
```python
|
||||
def _patch_word_embeddings(self, kwargs):
|
||||
origin_forward = VocabParallelEmbedding.forward
|
||||
|
||||
def forward(_self, input_):
|
||||
args = get_args()
|
||||
reduce_scatter_embeddings = _self.reduce_scatter_embeddings
|
||||
_self.reduce_scatter_embeddings = False
|
||||
input_ = torch.masked_fill(input_, input_ < 0, 0)
|
||||
res = origin_forward(_self, input_)
|
||||
_self.reduce_scatter_embeddings = reduce_scatter_embeddings
|
||||
packed_seq_params = kwargs.get('packed_seq_params')
|
||||
# ...其他逻辑...
|
||||
return res
|
||||
VocabParallelEmbedding.forward = forward
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
VocabParallelEmbedding.forward = origin_forward
|
||||
|
||||
def forward(
|
||||
self,
|
||||
input_ids: torch.Tensor,
|
||||
position_ids: torch.Tensor,
|
||||
attention_mask: torch.Tensor = None,
|
||||
decoder_input: torch.Tensor = None,
|
||||
labels: torch.Tensor = None,
|
||||
inference_params: InferenceParams = None,
|
||||
packed_seq_params: PackedSeqParams = None,
|
||||
**kwargs,
|
||||
) -> torch.Tensor:
|
||||
if decoder_input is not None:
|
||||
pass
|
||||
elif self.pre_process:
|
||||
kwargs.update({'input_ids': input_ids, 'packed_seq_params': packed_seq_params})
|
||||
with self._patch_word_embeddings(kwargs):
|
||||
decoder_input = self.language_model.embedding(input_ids=input_ids, position_ids=position_ids)
|
||||
|
||||
# ...其他逻辑...
|
||||
```
|
||||
|
||||
修改后：
|
||||
```python
|
||||
def _patch_word_embeddings(self, kwargs, emb): # 修改1
|
||||
origin_forward = emb.word_embeddings.forward # 修改2
|
||||
|
||||
def forward(input_): # 修改3
|
||||
args = get_args()
|
||||
_self = emb.word_embeddings # 修改4
|
||||
reduce_scatter_embeddings = _self.reduce_scatter_embeddings
|
||||
_self.reduce_scatter_embeddings = False
|
||||
input_ = torch.masked_fill(input_, input_ < 0, 0)
|
||||
res = origin_forward(input_) # 修改5
|
||||
_self.reduce_scatter_embeddings = reduce_scatter_embeddings
|
||||
packed_seq_params = kwargs.get('packed_seq_params')
|
||||
# ...其他逻辑...
|
||||
return res
|
||||
|
||||
emb.word_embeddings.forward = forward # 修改6
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
emb.word_embeddings.forward = origin_forward # 修改7
|
||||
|
||||
def forward(
|
||||
self,
|
||||
input_ids: torch.Tensor,
|
||||
position_ids: torch.Tensor,
|
||||
attention_mask: torch.Tensor = None,
|
||||
decoder_input: torch.Tensor = None,
|
||||
labels: torch.Tensor = None,
|
||||
inference_params: InferenceParams = None,
|
||||
packed_seq_params: PackedSeqParams = None,
|
||||
**kwargs,
|
||||
) -> torch.Tensor:
|
||||
if decoder_input is not None:
|
||||
pass
|
||||
elif self.pre_process:
|
||||
kwargs.update({'input_ids': input_ids, 'packed_seq_params': packed_seq_params})
|
||||
with self._patch_word_embeddings(kwargs, self.language_model.embedding): # 修改8
|
||||
decoder_input = self.language_model.embedding(input_ids=input_ids, position_ids=position_ids)
|
||||
|
||||
# ...其他逻辑...
|
||||
```
|
||||
|
||||
主要变化包括：
|
||||
1. `_patch_word_embeddings` 方法增加了 `emb` 参数，用于接收 embedding 模块实例
|
||||
2. 直接获取 `emb.word_embeddings.forward` 而不是 `VocabParallelEmbedding.forward`
|
||||
3. 内部 `forward` 函数签名从 `(_self, input_)` 改为 `(input_)`
|
||||
4. 在函数内部通过 `emb.word_embeddings` 获取 `_self`
|
||||
5. 调用原始 forward 时直接传入 `input_`
|
||||
6. 使用 `emb.word_embeddings.forward` 进行替换和恢复操作（修改6、7）
|
||||
7. 在调用 `_patch_word_embeddings` 时传入 `self.language_model.embedding` 实例
|
||||
|
||||
对文件swift/megatron/trainers/base.py中的train_step函数进行修改
|
||||
修改前：
|
||||
```python
|
||||
def train_step(self, forward_step_func, data_iterator, model, optimizer, opt_param_scheduler, config, *args,
|
||||
**kwargs):
|
||||
new_data_iterator = self._replace_data_iterator(data_iterator, model)
|
||||
return self._origin_train_step(forward_step_func, new_data_iterator, model, optimizer, opt_param_scheduler,
|
||||
config, *args, **kwargs)
|
||||
|
||||
```
|
||||
修改后：
|
||||
```python
|
||||
def train_step(self, forward_step_func, data_iterator, model, optimizer, opt_param_scheduler, config, *args,
|
||||
**kwargs):
|
||||
new_data_iterator = self._replace_data_iterator(data_iterator, model)
|
||||
from msprobe.pytorch import PrecisionDebugger
|
||||
debugger = PrecisionDebugger(dump_path='./dump_path', level='mix', model=model)
|
||||
debugger.start()
|
||||
try:
|
||||
origin_train_step_out = self._origin_train_step(
|
||||
forward_step_func, new_data_iterator, model, optimizer, opt_param_scheduler,config, *args, **kwargs)
|
||||
finally:
|
||||
debugger.stop()
|
||||
debugger.step()
|
||||
return origin_train_step_out
|
||||
```
|
||||
|
||||
|
||||
### 使能
|
||||
|
||||
另外，由于msprobe不支持融合计算，需要在启动脚本添加`--bias_dropout_fusion false`、`--bias_swiglu_fusion false`、`--cross_entropy_loss_fusion false`
|
||||
|
||||
#### 示例
|
||||
```shell
|
||||
PYTORCH_NPU_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--mcore_model Qwen2.5-7B-Instruct-mcore \
|
||||
--dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \
|
||||
'AI-ModelScope/alpaca-gpt4-data-en#500' \
|
||||
'swift/self-cognition#500' \
|
||||
--tensor_model_parallel_size 2 \
|
||||
...
|
||||
--bias_dropout_fusion false \
|
||||
--bias_swiglu_fusion false \
|
||||
--cross_entropy_loss_fusion false
|
||||
```
|
||||
@@ -0,0 +1,439 @@
|
||||
# 命令行参数
|
||||
|
||||
## Megatron参数
|
||||
|
||||
**训练参数**:
|
||||
- 🔥micro_batch_size: 每个DP组的批次大小，默认为1。
|
||||
- 🔥global_batch_size: 总批次大小，等价于`micro_batch_size*数据并行大小*梯度累加步数`。默认为16。
|
||||
- 其中，`数据并行大小 (DP) = 总GPU数 / (TP × PP × CP)`。
|
||||
- 🔥recompute_granularity: 重新计算激活的粒度，可选项为'full', 'selective' and 'none'。其中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 应用部分。
|
||||
- 🔥train_iters: 训练的总迭代次数，默认为None。
|
||||
- 提示：你可以通过设置`--num_train_epochs`来设置训练的epochs数。在使用非流式数据集时，会自动根据数据集数量计算`train_iters`（兼容packing）。
|
||||
- 🔥num_train_epochs: 指定训练的epochs数。当使用非流式数据集时，该参数会为你自动计算train_iters而不需要手动传入`train_iters`。当使用流式数据集时，该参数会在训练到`num_train_epochs`时强制退出训练，并对权重进行验证和保存。默认为None。
|
||||
- masked_softmax_fusion: 默认为True。用于开启query_key_value的scaling, masking, and softmax融合。
|
||||
- bias_dropout_fusion: 默认为True。用于开启bias和dropout的融合。
|
||||
- bias_activation_fusion: 如果为True，则在可能的情况下融合偏置加法和激活函数。默认为True。
|
||||
- apply_rope_fusion: 默认为False。用于开启rope融合。该参数为megatron-core参数透传。注意：并不是所有情况都支持rope融合，例如：MLA、mrope等不支持。
|
||||
- gradient_accumulation_fusion: 默认为True。用于开启梯度累加融合。
|
||||
- 🔥cross_entropy_loss_fusion: 启动交叉熵损失计算融合。默认为True。
|
||||
- cross_entropy_fusion_impl: 交叉熵损失融合的实现。可选为'native'和'te'。默认为'native'。
|
||||
- **"ms-swift>=4.3.1"默认值从"te"修改为"native"**，原因查看[这个PR](https://github.com/NVIDIA/Megatron-LM/pull/5115)，这可能会导致更多的显存占用。
|
||||
- calculate_per_token_loss: 根据全局批次中的非填充token数量来对交叉熵损失进行缩放。默认为None，`task_type`为'causal_lm'且为预训练/微调时，默认为True，否则默认为False。
|
||||
- 🔥attention_backend: 使用的注意力后端 (flash、fused、unfused、local、auto、flash_2、flash_3、flash_4)。默认为 flash。
|
||||
- 如果安装'flash_attention_4/3'，`--attention_backend flash`则优先使用fa4/fa3。如果要显式设置，你可以设置`--attention_backend flash_2/3/4`。训练脚本参考[这里](https://github.com/modelscope/ms-swift/tree/main/examples/train/flash_attention_3)。多模态模型的vit部分要使用flash_attention_4/3，请设置`--attn_impl flash_attention_4/3`。
|
||||
- 有些模型可能不支持flash，你需要手动设置`--attention_backend unfused/fused --padding_free false`，例如：Llama4、GPT-OSS。
|
||||
- optimizer: 优化器类型，可选为'adam'、'sgd'、'muon'和'dist_muon'。默认为adam。
|
||||
- 注意：此'adam'为'adamw'，参考[这里](https://github.com/NVIDIA/TransformerEngine/blob/d8f1e68f7c414f3e7985a8b41de4443b2f819af3/transformer_engine/pytorch/optimizers/fused_adam.py#L69-L70)。
|
||||
- 其中'muon'和'dist_muon'需要"megatron-core>=0.16"。
|
||||
- 🔥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.。
|
||||
- optimizer_cuda_graph: 是否为优化器步骤启用 CUDA 计算图，传递给 Megatron 的 `--optimizer-cuda-graph`。默认为False。该参数需要"megatron-core>=0.17"。
|
||||
- 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'。
|
||||
- manual_gc: 禁用默认垃圾回收器，手动触发垃圾回收。默认为False。
|
||||
- manual_gc_steps: 手动触发垃圾回收的间隔（steps）。默认为0。
|
||||
- manual_gc_eval: 当使用手动垃圾回收时（`--manual_gc true`），在每次评估运行的开始和结束时禁用垃圾回收。默认为True。
|
||||
|
||||
**数据参数**:
|
||||
- seed: python、numpy、pytorch和cuda的随机种子，默认为42。
|
||||
- dataset_shuffle: 是否对dataset进行随机操作。默认为True。
|
||||
- 注意：**Megatron-SWIFT的随机包括两个部分**：数据集的随机，由`dataset_shuffle`控制；train_dataloader中的随机，由`train_dataloader_shuffle`控制。
|
||||
- train_dataloader_shuffle: 是否对train_dataloader使用随机，默认为True。val_dataset不进行随机操作。
|
||||
- 🔥dataloader_num_workers: dataloader的workers数量，默认为4。
|
||||
- 注意：若设置`--streaming true`，则设置为1。
|
||||
- dataloader_pin_memory: 默认为True。
|
||||
- dataloader_persistent_workers: 默认为False。
|
||||
- 注意：该参数在"ms-swift<4.3"默认为True，为避免内存泄漏问题修改为False。
|
||||
- dataloader_prefetch_factor: 默认为2。
|
||||
- data_sharding: 当`--train_dataloader_shuffle true`时对 train_dataloader 生效，默认为False。该参数控制数据集随机的范围。若设置为True，则先对数据集进行分片，然后对每个分片进行随机处理（略节约内存）；若设置为False，则先对数据集进行随机，再进行分片（更好的随机效果）。
|
||||
- 🔥group_by_length: 是否在训练数据集中将长度大致相同的样本分组在一起（有随机因素），以最小化填充并确保各节点与进程的负载均衡以提高效率。默认为False。具体算法参考`transformers.trainer_pt_utils.get_length_grouped_indices`。
|
||||
- te_rng_tracker: 使用 Transformer Engine 版本的随机数生成器。默认为False。
|
||||
- data_parallel_random_init: 在数据并行的各个 rank 之间启用不同的随机初始化。默认为False。
|
||||
- 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的同时，提升训练速度和减少显存占用。（暂时与CP不兼容）
|
||||
|
||||
|
||||
**学习率参数**:
|
||||
- lr_warmup_init: 学习率warmup的初始值。学习率调度器从这个值开始进行预热。默认为0。
|
||||
- 🔥lr: 初始学习率，最终会根据学习率预热策略和衰减策略决定每个迭代的学习率。默认为None，**全参数训练默认为1e-5，LoRA训练默认为1e-4**。
|
||||
- lr_decay_style: 学习率衰减策略，默认为'cosine'。通常设置为'constant', 'linear', 'cosine', 'inverse-square-root', 'WSD'。
|
||||
- 🔥lr_decay_iters: 学习率衰减的迭代次数。默认为None，则设置为`--train_iters`。
|
||||
- lr_warmup_iters: 线性学习率预热的迭代次数，默认为0。
|
||||
- 🔥lr_warmup_fraction: 线性学习率预热阶段所占比例，默认为None。
|
||||
- 🔥min_lr: 学习率的最小值，将低于该阈值的学习率裁剪为该值，默认为0。
|
||||
- 注意：`vit_lr`的`min_lr`为`vit_lr * min_lr / lr`，`aligner_lr`的`min_lr同理。
|
||||
- lr_wsd_decay_style: WSD 退火阶段的衰减方式。默认为'exponential'。
|
||||
- lr_wsd_decay_iters: 学习率衰减的迭代次数。默认为 None。
|
||||
|
||||
**正则化参数**:
|
||||
- 🔥weight_decay: 默认为0.1。
|
||||
- weight_decay_incr_style: 权重衰减的递增函数。可选为'constant', 'linear', 'cosine'。默认为'constant'。
|
||||
- start_weight_decay: L2 正则化的初始权重衰减系数。
|
||||
- end_weight_decay: 训练结束时 L2 正则化的权重衰减系数。
|
||||
- 🔥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。
|
||||
|
||||
|
||||
**muon参数**:
|
||||
- muon_momentum: Muon 优化器的动量因子。默认为0.9。
|
||||
- muon_split_qkv: 是否为 Muon 优化器拆分 QKV 参数，默认为True。
|
||||
- muon_use_nesterov: 是否在内部 SGD 中使用 Nesterov 风格的动量，默认为False。
|
||||
- muon_scale_mode: Muon 优化器的缩放模式。可选为'spectral', 'unit_rms_norm', 'shape_scaling'。默认为'spectral'。
|
||||
- muon_fp32_matmul_prec: Newton-Schulz 迭代的 FP32 矩阵乘法精度，可选为'low', 'medium', 'high'。默认为'medium'。
|
||||
- muon_coefficient_type: Muon 优化器 Newton-Schulz 迭代的系数类型，传递给 Megatron 的 `--muon-coefficient-type`。可选值取决于所安装的 emerging_optimizers 版本（如'quintic', 'polar_express', 'simple', 'cans', 'aol', 'deepseekv4', 'cubic5', 'custom'）。默认为'quintic'。
|
||||
- muon_num_ns_steps: Muon 优化器的 Newton-Schulz 步数。默认为5。
|
||||
- muon_tp_mode: 张量模型并行权重的 NS 计算方式。可选为'blockwise', 'duplicated', 'distributed'。默认为'blockwise'。
|
||||
- muon_extra_scale_factor: Muon 更新的额外缩放因子，默认为1。
|
||||
- muon_scalar_optimizer: 使用 Muon 时非线性参数（embeddings、biases、norms）的优化器，可选为'adam'或'lion'。默认为'adam'。
|
||||
|
||||
|
||||
**checkpoint参数**:
|
||||
- 🔥output_dir: checkpoint的输出目录，默认None。在训练中，若未设置该参数，则默认为`f'megatron_output/{model_suffix}'`，例如`'megatron_output/Qwen2.5-7B-Instruct'`。
|
||||
- 注意：**若在多机训练时，请确保每个节点的保存路径指向相同位置**，否则你需要在训练后手动集中这些权重。
|
||||
- 🔥save_steps: checkpoint保存的间隔（steps），默认为500。
|
||||
- 注意：训练结束时一定会保存权重。
|
||||
- 🔥no_save_optim: 不保存optimizer，默认为False。在全参数训练时，可以显著降低存储时间。
|
||||
- 🔥no_save_rng: 不保存rng，默认为False。
|
||||
- 🔥mcore_model: 加载的checkpoint目录（mcore存储格式），默认None。对于断点续训的介绍，请查看`--finetune false`参数的介绍。
|
||||
- megatron-swift推荐直接加载和存储safetensors权重，参考[mcore-bridge文档](./Mcore-Bridge.md)。
|
||||
- `--model`与`--mcore_model`的区别：`--model/--adapters/--ref_model/--ref_adapters`后加safetensors权重目录，`--mcore_model/--mcore_adapter/--mcore_ref_model/--mcore_ref_adapter`后加mcore权重目录。
|
||||
- `--model/--adapters`不支持加载断点续训状态，因此若设置`--no_save_optim false`，将额外存储mcore权重格式用于断点续训，你需要使用`--mcore_model/--mcore_adapter`来加载断点续训的状态。例如：`--model <hf-model> --mcore_adapter <mcore-adapter-ckpt>`。（使用`--model/--adapters`断点续训也可以，只是不读取优化器状态。）
|
||||
- 🔥no_load_optim: 不载入optimizer，默认为False。
|
||||
- 注意：断点续训时，设置`--no_load_optim false`读取优化器状态通常比`--no_load_optim true`不读取优化器状态消耗更大的显存资源。
|
||||
- 🔥no_load_rng: 不载入rng，默认为False。
|
||||
- 🔥finetune: 将模型加载并微调。**不加载检查点的优化器和随机种子状态，并将迭代数设置为0**。默认为True。
|
||||
- 注意：**断点续训**你需要设置`--mcore_model`（lora训练需要额外设置`--mcore_adapter`），若设置`--finetune true`，将不加载优化器状态和随机种子状态并将迭代数设置为0，不会进行数据集跳过；若设置`--finetune false`，将读取迭代数并跳过之前训练的数据集数量，优化器状态和随机种子状态的读取通过`--no_load_optim`和`--no_load_rng`控制。
|
||||
- 流式数据集`--streaming`，暂不支持跳过数据集。
|
||||
- perform_initialization: 对权重进行初始化，默认为False。
|
||||
- use_cpu_initialization: 在cpu上初始化权重，默认为False。在进行HF和MCore权重转换时会被使用。通常不需要修改该值。
|
||||
- 🔥async_save: 使用异步检查点保存。目前仅适用于`torch_dist`分布式检查点格式。默认为False。
|
||||
- 🔥save_total_limit: 最多保存的checkpoint数，会将过期的checkpoint进行删除。默认为None，保存所有的checkpoint。该参数需设置为`>=2`的数，若设置为2，则保存best checkpoint和last checkpoint。该参数暂不兼容`async_save`。
|
||||
- metric_for_best_model: 默认为None，GRPO默认为'reward'，其他情况默认为'loss'。
|
||||
- greater_is_better: 默认为None，即当`metric_for_best_model`含'loss'时，设置为False，否则设置为True。
|
||||
- use_persistent_ckpt_worker: 为异步保存启动持久化检查点工作进程。默认为False。
|
||||
- dist_ckpt_save_pre_mcore_014: 使用 Megatron-Core 0.14 之前的格式存储。默认为False。
|
||||
- dist_ckpt_optim_fully_reshardable: 使优化器分布式检查点完全可重分片（TP/PP/EP/DP），而不是仅支持普通的DP重分片。默认为False。
|
||||
- distrib_optim_fully_reshardable_mem_efficient: 在分布式优化器检查点保存和加载过程中，通过使用Gloo（而非NCCL），并仅使用单个rank进行保存，以尽可能减少内存使用。仅在遇到主机或设备内存问题时启用，仅在设置了`--dist-ckpt-optim-fully-reshardable`标志时生效。默认为False。
|
||||
|
||||
|
||||
**分布式参数**:
|
||||
并行技术的选择请参考[训练技巧文档](Quick-start.md#训练技巧)。
|
||||
|
||||
- ddp_backend: 分布式后端，可选为'nccl', 'gloo'。默认为nccl。
|
||||
- ddp_timeout: 默认为18000000，单位为秒。
|
||||
- 🔥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层数平均分配到所有流水线阶段。
|
||||
- overlap_p2p_comm: 在 1F1B 中将流水线并行通信与前向和反向块重叠，默认为True。
|
||||
- batch_p2p_comm: 使用 batch_isend_irecv 代替单独的 isend/irecv 调用。默认为None，设置为`not args.overlap_p2p_comm`。
|
||||
- 如果出现PP并行卡住的情况，可以设置为False。
|
||||
- align_param_gather: 设置为True，所有 PP 阶段将同时启动参数全收集（all-gather）操作。否则，每个 PP 阶段将根据需要独立启动。默认为True。
|
||||
- 🔥sequence_parallel: 启动序列并行优化，该参数需要设置`tensor_model_parallel_size`才生效。默认为False。
|
||||
- 🔥context_parallel_size: cp数，默认为1。
|
||||
- cp_partition_mode: THD 序列行如何在上下文并行（context-parallel）ranks 之间进行划分。可选为"zigzag", "contiguous"，默认为"zigzag"。
|
||||
- sequence_packing_scheduler: 用于序列打包和动态上下文并行的调度器。可选为"dp_balanced"，"default_dynamic_cp"。dp_balanced：用于序列打包的 DP 均衡调度器。default_dynamic_cp：用于打包序列均衡的动态 CP 调度器。默认为None。
|
||||
- tp_comm_overlap: 启用张量并行通信与GEMM（通用矩阵乘法）内核的重叠（降低通信耗时）。默认为False。
|
||||
- 🔥overlap_grad_reduce: 启用DDP中grad reduce操作的重叠（降低DP通信耗时）。默认为False。
|
||||
- 🔥overlap_param_gather: 启用分布式优化器中参数all-gather的重叠（降低DP通信耗时）。默认为False。
|
||||
- virtual_pipeline_model_parallel_size: 每个流水线并行 rank 的虚拟流水线阶段数量。默认为None。vpp并行，用于减少pp并行的计算空泡，提高GPU利用率，但会略微提高通信量。
|
||||
- microbatch_group_size_per_vp_stage: 每个虚拟流水线阶段处理的连续微批次数量。默认为None，等于pipeline_model_parallel_size。
|
||||
- 🔥pipeline_model_parallel_layout: 一个描述自定义流水线（pp/vpp）模型并行布局的字符串。例如：`"Et*4|(tttt|)*14tmL"`。其中 E、L、t、m 分别表示嵌入层（embedding）、损失层（loss）、Transformer 解码器层和 MTP 层。阶段之间用 "|" 分隔。重复的阶段或层可以通过乘法表示。逗号仅用于提升可读性（无实际语法作用）。默认值为 None，表示不使用此参数设置布局。
|
||||
- 该参数通常在异构GPU集群上使用。
|
||||
- 🔥expert_model_parallel_size: 专家并行数，默认为1。
|
||||
- 🔥expert_tensor_parallel_size: 专家TP并行度。默认值为1。
|
||||
|
||||
|
||||
**日志参数**:
|
||||
- report_to: 启用的日志后端。默认为`['tensorboard']`。可选项为'tensorboard', 'wandb'和'swanlab'。'wandb'和'swanlab'登陆可以使用`WANDB_API_KEY`、`SWANLAB_API_KEY`环境变量。
|
||||
- 🔥logging_steps: 日志记录的间隔（steps），默认为5。
|
||||
- tensorboard_dir: tensorboard日志写入的目录。默认None，即存储在`f'{output_dir}/runs'`目录下。
|
||||
- tensorboard_queue_size: 用于暂存事件和摘要的 TensorBoard 队列大小；当队列中待处理的事件和摘要数量达到该大小时，下一次调用 "add" 相关方法会触发将数据刷新写入磁盘。默认为50。
|
||||
- wandb_project: wandb项目名称，默认为'megatron-swift'。
|
||||
- wandb_exp_name: wandb 实验名称。默认为`--output_dir`的值。
|
||||
- swanlab_project: swanlab项目名称，默认为'megatron-swift'。
|
||||
- swanlab_exp_name: swanlab 实验名称。默认为`--output_dir`的值。
|
||||
|
||||
**评估参数**:
|
||||
- 🔥eval_iters: 评估的迭代次数，默认为`-1`，根据验证数据集的数量设置合适的值。**若验证集数量少于global_batch_size，则不进行评估**。若使用流式数据集，该值需要手动设置。
|
||||
- 🔥eval_steps: 评估的间隔（steps），即每训练多少steps进行评估。默认为None，即设置为`save_steps`。
|
||||
|
||||
**fp8参数**:
|
||||
- fp8_format: 用于前向和反向传播中FP8张量的FP8格式方案。可选为'e4m3'，'hybrid'。默认为None。
|
||||
- fp8_recipe: 用于前向和反向传播中 FP8 张量的 FP8 算法方案。可选为'tensorwise', 'delayed', 'mxfp8', 'blockwise'。默认为'delayed'。其中blockwise fp8需要 cuda129 以上版本。
|
||||
- fp8_param_gather: 保持计算参数为 fp8（不使用任何其他中间数据类型），并在 fp8 格式下执行参数的 all-gather 操作。默认为False。
|
||||
- 提示：若想导出FP8权重格式，设置为True；否则设置为False。
|
||||
- fp8_amax_history_len: 每个张量记录 amax 历史的步数。默认为1024。
|
||||
- fp8_amax_compute_algo: 用于根据历史记录计算 amax 的算法。可选为'most_recent', 'max'。默认为'max'。
|
||||
|
||||
**fp4参数**:
|
||||
- fp4_format: 用于前向和反向传播中FP4张量的FP4格式方案，可选为'e2m1'。默认为None。
|
||||
- fp4_recipe: 若设置此参数，则通过 Transformer Engine 启用 FP4 精度。目前仅支持 'nvfp4'，该选项使用适用于 Blackwell+ 架构的 NVFP4BlockScaling 方案。默认为'nvfp4'。
|
||||
- fp4_param_gather: 若设置此参数，则将参数保持为 FP4 精度以节省内存。注意并非所有参数都会被转换为 FP4，例如偏置项将保持不变。默认为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。
|
||||
- accumulate_allreduce_grads_in_fp32: 在 fp32 精度下进行梯度累积和全规约操作。如果开启`--bf16`且`main_params_dtype`为'fp32'，则设置为True。否则默认设置为False。
|
||||
|
||||
**MoE参数**:
|
||||
- moe_router_load_balancing_type: 确定路由器的负载均衡策略。可选项为"aux_loss"、"seq_aux_loss"、"global_aux_loss"、"sinkhorn"、"none"。支持单/多种策略的列表（如 `--moe_router_load_balancing_type seq_aux_loss global_aux_loss`）。默认值为 None。从config.json中读取。
|
||||
- 🔥moe_router_dtype: 用于路由计算和专家输出加权平均的数据类型。可选为'none', 'fp32'、'fp64'，这增强了数值稳定性，尤其是在专家数量较多时。与`moe_permute_fusion`一起使用时，性能影响可以忽略不计。默认为'fp32'。'none'代表不改变数据类型。
|
||||
- moe_token_dispatcher_type: 要使用的token分发器类型。可选选项包括 'allgather'、'alltoall'、'flex'和'alltoall_seq'。默认值为'alltoall'。
|
||||
- moe_enable_deepep: 启用 DeepEP 以实现 MoE 模型中的高效 token 调度和合并。仅在通过设置 `--moe_token_dispatcher_type flex` 使用弹性 token 调度器时有效。
|
||||
- 🔥moe_grouped_gemm: 当每个rank包含多个专家时，通过在多个流中启动多个本地 GEMM 内核，利用 TransformerEngine中的GroupedLinear提高利用率和性能。默认为True。
|
||||
- 🔥moe_permute_fusion: 在令牌分发过程中融合令牌重排操作。默认为False。
|
||||
- 🔥moe_aux_loss_coeff: 默认为0，不使用aux_loss。支持单/多个浮点数的列表 ，对应`moe_router_load_balancing_type` 中各策略。通常情况下，该值设置的越大，训练效果越差，但MoE负载越均衡，请根据实验效果，选择合适的值。
|
||||
- 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'。
|
||||
|
||||
**DSA参数**
|
||||
- dsa_indexer_loss_coeff: DSA 索引器 KL 散度损失的系数。设置为 0 可禁用索引器损失。默认为`0.`。
|
||||
- dsa_indexer_use_sparse_loss: 是否使用稀疏 DSA 索引器损失。如果为 True，索引器损失将使用 top-k 索引进行计算。默认为False。
|
||||
- apply_dsa_kernel_fusion: 是否启用融合 DSA 稀疏注意力内核（FlashMLA + cuDNN DSA）。设为 False 将回退到未融合的 PyTorch 实现。需要安装 flash_mla 和 nvidia-cudnn-frontend >= 1.24.0。默认为False。（需使用Megatron-LM dev分支）
|
||||
|
||||
**Deepseek-V4**
|
||||
- csa_dense_mode: 是否对压缩稀疏注意力使用密集模式。若为 `True`，CSA 索引器将被禁用。默认为False。
|
||||
- use_fused_mhc: 对 mHC 操作使用 cuTile 融合内核。若为 True，将尝试用融合的 cuda.tile（cuTile）自动微分函数替换参考
|
||||
mHC 模块以在支持的 GPU 上获得更好的性能。需要安装 cuTile；若 cuTile 不可用，该标志将被静默重置为 False 并发出警告。默认为False。
|
||||
- mhc_recompute_layer_num: 每个 MHC 重计算块的层数。设置后，每 `mhc_recompute_layer_num` 层构成一个重计算块。若为 None，Transformer 块中的所有层共享单个重计算块。默认为None。
|
||||
|
||||
**MTP参数**
|
||||
- mtp_num_layers: 多token预测（MTP）层的数量。MTP将每个位置的预测范围扩展到多个未来token。此MTP实现使用D个顺序模块依次预测D个额外的token。默认为None。
|
||||
- 注意：mtp_num_layers的值，将不自动从config.json获取，需手动设置。你可以参考config.json中的`num_nextn_predict_layers`, `mtp_num_hidden_layers`字段填写该值。使用mcore-bridge时，将优先从safetensors文件中加载MTP权重，若无法找到，则进行随机初始化。
|
||||
- mtp_loss_scaling_factor: 多token预测（MTP）损失的缩放因子。我们计算所有深度上MTP损失的平均值，然后乘以该缩放因子得到总体MTP损失，它将作为一个额外的训练目标。默认为0.1。
|
||||
- mtp_decoder_input_detach: 用来控制 MTP 分支里的 decoder_input 是否停止梯度。默认为False。开启后，MTP loss 不会直接通过 decoder_input 回传到 embedding/vit，但仍会通过 hidden_states 路径更新主干。
|
||||
- mtp_shared_weights: MTP层之间共享权重，采用GLM-5使用的mtp方案。默认为False。例如你可以设置`--mtp_num_layers 3 --mtp_shared_weights true`。
|
||||
|
||||
**Tuner参数**:
|
||||
- tuner_type: 可选为'lora', 'full'和'lora_llm'。默认为'full'。
|
||||
- 其中'lora_llm'代表对llm部分进行lora，vit/aligner部分使用'full'。你可以使用`vit_lr/aligner_lr`设置各自的学习率。
|
||||
- 🔥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，你可以修改[这里的代码](https://github.com/modelscope/ms-swift/blob/a5d4c0a2ce0658cef8332d6c0fa619a52afa26ff/swift/llm/model/model_arch.py#L544-L554)。
|
||||
- 🔥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训练：
|
||||
- mcore_adapter: 加载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`。
|
||||
- transformers和Megatron的Linear层后缀名称不同，在Megatron中，`linear_proj`代表`o_proj`，`linear_qkv`代表`q_proj, k_proj, v_proj`的拼接，`linear_fc1`代表`gate_proj`, `up_proj`的拼接，`linear_fc2`代表`down_proj`。
|
||||
- 🔥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`。
|
||||
|
||||
**Mcore-Bridge参数**
|
||||
- model: safetensors权重的model_id或者model_path。默认为None。
|
||||
- model_type: 模型类型。介绍参考[ms-swift命令行参数文档](../Instruction/Command-line-parameters.md)。
|
||||
- 🔥save_safetensors: 默认为True，是否直接保存成safetensors权重。若设置了`--no_save_optim false`则额外mcore格式权重和优化器权重（也保存在output_dir中）。断点续训时使用`--mcore_model/--mcore_adapter/--no_load_optim/--no_load_rng`参数加载mcore格式权重。
|
||||
- adapters: safetensors格式的LoRA增量权重的adapter_id或者adapter_path。默认为`[]`。
|
||||
- ref_model: ref_model safetensors权重的model_id或者model_path。采用grpo、dpo、kto算法且使用全参数训练时需要传入。默认为None，设置为`--model`。
|
||||
- ref_adapters: ref_adapters safetensors权重的adapter_id或者adapter_path的列表（目前只支持长度为1），默认为`[]`。
|
||||
- use_hf: 控制模型下载、数据集下载、模型推送使用[ModelScope](https://modelscope.cn/)还是[HuggingFace](https://huggingface.co/)。默认为False，使用ModelScope。
|
||||
- 提示：如果你想在国外访问ModelScope，可以尝试使用[ModelScope国际版](https://modelscope.ai/home)，设置环境变量`MODELSCOPE_DOMAIN='www.modelscope.ai'`即可。
|
||||
- hub_token: hub token. modelscope的hub token可以查看[这里](https://modelscope.cn/my/myaccesstoken)。默认为None。
|
||||
- merge_lora: 是否存储合并后的权重。默认为None，若`save_safetensors`设置为True，该参数默认值为`True`，否则为False。即默认情况下，存储为safetensors格式时会合并LoRA；存储为torch_dist格式时，不会合并LoRA。
|
||||
- max_shard_size: safetensors格式存储文件最大大小，默认'5GB'。
|
||||
- 🔥offload_bridge: Megatron导出的用于vLLM更新HF格式权重使用CPU主存存放，以降低 GPU 显存占用。默认为 False。（在GRPO/GKD算法中生效）
|
||||
|
||||
**多模态参数**:
|
||||
- vit_gradient_checkpointing: 多模态模型训练时，是否对vit部分开启gradient_checkpointing。默认为None，即当`--freeze_vit`为`false`时开启。（**Megatron-SWIFT的vit实现使用transformers实现**）
|
||||
- vit_gradient_checkpointing_kwargs: 传入`torch.utils.checkpoint`中的参数。例如设置为`--vit_gradient_checkpointing_kwargs '{"use_reentrant": false}'`。默认为None。该参数只对`vit_gradient_checkpointing`生效。
|
||||
- vit_attn_impl: 多模态模型训练时，设置vit部分的attn_impl实现。默认为'flash_attn'。
|
||||
- vit_lr: 当训练多模态大模型时，该参数指定vit的学习率，默认为None，等于learning_rate。通常与`--freeze_vit`、`--freeze_aligner`参数结合使用。
|
||||
- 提示：在日志中打印的"learning rate"为llm的学习率。
|
||||
- aligner_lr: 当训练多模态大模型时，该参数指定aligner的学习率，默认为None，等于learning_rate。
|
||||
|
||||
|
||||
**其他参数**:
|
||||
- megatron_extra_kwargs: 透传入Megatron的其他参数（透传入[mcore-bridge](https://github.com/modelscope/mcore-bridge/blob/78cb9be33ebad69a0d940a2bc4e198f866084b70/src/mcore_bridge/config/model_config.py#L116)的 `ModelConfig` 类，继承自 megatron-core 的 TransformerConfig），也可用于覆盖自动读取的`config.json`参数。传入json字符串。默认为None。
|
||||
- language_model_only: 只训练多模态模型的语言模型部分，并且只会加载和保存语言模型部分。默认为False。（需"mcore-bridge>=1.4.3"）
|
||||
- check_model: 检查本地模型文件有损坏或修改并给出提示，默认为True。**如果是断网环境，请设置为False**。
|
||||
- rope_scaling: rope_scaling相关参数，默认为None。格式参考[llama3.1 config.json](https://modelscope.cn/models/LLM-Research/Meta-Llama-3.1-8B-Instruct/file/view/master?fileName=config.json&status=1)，传入json字符串。
|
||||
- **目前rope_scaling模块使用transformers实现，支持transformers支持的所有rope_scaling。**
|
||||
- apply_wd_to_qk_layernorm: 用于Qwen3-Next/Qwen3.5全参数训练，对 qk layernorm 应用权重衰减。默认为False。
|
||||
- linear_decoupled_in_proj: 将linear-attention（即 GatedDeltaNet）中的`in_proj`解耦为`in_proj_qkvz`, `in_proj_ba`，以适配FP8训练，其中`in_proj_ba`仍使用原始精度训练。参考[这个例子](https://github.com/modelscope/ms-swift/blob/main/examples/models/qwen3_5/fp8.sh)。
|
||||
- enable_dft_loss: 是否在SFT训练中使用[DFT](https://arxiv.org/abs/2508.05629) (Dynamic Fine-Tuning) loss，默认为False。
|
||||
- enable_channel_loss: 启用channel loss，默认为`False`。你需要在数据集中准备"channel"字段，ms-swift会根据该字段分组统计loss（若未准备"channel"字段，则归为默认`None` channel）。数据集格式参考[channel loss](../Customization/Custom-dataset.md#channel-loss)。channel loss兼容packing/padding_free/loss_scale等技术。
|
||||
- 🔥task_type: 默认为'causal_lm'。可选为'causal_lm'、'seq_cls'、'embedding'和'generative_reranker'。
|
||||
- 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'。
|
||||
- mrl_dims: Embedding训练的[Matryoshka表征学习（MRL）](https://arxiv.org/abs/2205.13147)维度配置，默认为None。格式为`Dict[int, float]`或Json字符串，key为截断的embedding维度，value为该维度对应的loss权重，例如`'{"32": 1.0, "64": 1.0, "128": 1.0}'`。开启后，trainer会对`last_hidden_state`分别截断到每个维度并做L2归一化，再调用`loss_type`对应的loss加权累加。仅在`task_type='embedding'`下生效。
|
||||
- 注意：可支持的最大embedding维度由模型`config.json`中的`hidden_size`决定，key大于`hidden_size`的KV对将被自动忽略。
|
||||
- 🔥save_strategy: 保存策略，可选项为'steps'和'epoch'。默认为'steps'。当设置为'epoch'时，会根据数据集大小自动计算`save_steps`和`eval_steps`以实现每个epoch保存一次，用户传入的`save_steps`和`eval_steps`参数值将被忽略。
|
||||
- callbacks: 自定义trainer callback，默认为`[]`。
|
||||
|
||||
## 训练参数
|
||||
|
||||
Megatron训练参数继承自Megatron参数和基本参数（**与ms-swift共用dataset、template等参数，也支持ms-swift中的特定模型参数**）。基本参数的内容可以参考[这里](../Instruction/Command-line-parameters.md#基本参数)。此外还包括以下参数：
|
||||
|
||||
- add_version: 在`output_dir`上额外增加目录`'<版本号>-<时间戳>'`防止权重覆盖，默认为True。
|
||||
- 🔥create_checkpoint_symlink: 额外创建checkpoint软链接，方便书写自动化训练脚本。best_model和last_model的软链接路径分别为f'{output_dir}/best'和f'{output_dir}/last'。
|
||||
- 🔥packing: 使用`padding_free`的方式将不同长度的数据样本打包成**近似**统一长度的样本（packing能保证不对完整的序列进行切分），实现训练时各节点与进程的负载均衡（避免长文本拖慢短文本的训练速度），从而提高GPU利用率，保持显存占用稳定。当使用 `--attention_backend flash` 时，可确保packed样本内的不同序列之间相互独立，互不可见。该参数默认为`False`。注意：**packing会导致数据集样本数减少，请自行调节梯度累加数和学习率**。
|
||||
- linear-attention的场景：Qwen3.5, Qwen3-Next也支持padding_free/packing，参考[Qwen3.5最佳实践](../BestPractices/Qwen3_5-Best-Practice.md)。
|
||||
- packing_length: packing的长度。默认为None，设置为max_length。
|
||||
- packing_num_proc: packing的进程数，默认为1。需要注意的是，不同的`packing_num_proc`，最终形成的packed数据集是不同的。（该参数在流式packing时不生效）。通常不需要修改该值，packing速度远快于tokenize速度。
|
||||
- streaming: 流式读取并处理数据集，默认False。（流式数据集的随机并不彻底，可能导致loss波动剧烈。）
|
||||
- 注意：因为流式数据集无法获得其长度，因此需要设置`--train_iters`参数。设置`num_train_epochs`参数确保训练到对应epochs时退出训练，并对权重进行验证和保存。
|
||||
- 注意：流式数据集可以跳过预处理等待，将预处理时间与训练时间重叠。流式数据集的预处理只在rank0上进行，并通过数据分发的方式同步到其他进程，**其通常效率不如非流式数据集采用的数据分片读取方式**。当训练的world_size较大时，预处理和数据分发将成为训练瓶颈。
|
||||
- lazy_tokenize: 是否使用lazy_tokenize。若该参数设置为False，则在训练之前对所有的数据集样本进行tokenize（多模态模型则包括从磁盘中读取图片）。该参数默认为None，在LLM训练中默认为False，而MLLM训练默认为True，节约内存。
|
||||
- new_special_tokens: 需要新增的特殊tokens。默认为`[]`。例子参考[这里](https://github.com/modelscope/ms-swift/blob/main/examples/megatron/lora/new_special_tokens.sh)。
|
||||
- 注意：你也可以传入以`.txt`结尾的文件路径，每行为一个special token。
|
||||
|
||||
## RLHF参数
|
||||
除了继承训练参数外，还支持以下参数：
|
||||
- 🔥rlhf_type: 默认为'dpo'。目前可选择为'dpo'、'grpo'、'kto'、'rm'和'gkd'。
|
||||
- loss_scale: 覆盖[基本参数](../Instruction/Command-line-parameters.md)中的loss_scale。默认为'last_round'。
|
||||
- calculate_per_token_loss: 覆盖Megatron参数，默认为False。
|
||||
|
||||
|
||||
### DPO参数
|
||||
- mcore_ref_model: ref_model的加载路径。采用DPO/GRPO/KTO算法且使用全参数训练时需要传入。默认为None，即设置为`mcore_model`。
|
||||
- mcore_ref_adapter: 加载ref_adapter的权重路径，默认为None。若你要使用SFT产生的LoRA权重进行DPO，，请在训练时设置`--mcore_adapter sft_ckpt --mcore_ref_adapter sft_ckpt --finetune true`。若是此场景的断点续训，则设置`--mcore_adapter rlhf_ckpt --mcore_ref_adapter sft_ckpt --finetune false`。
|
||||
- beta: 含义与[TRL](https://huggingface.co/docs/trl/main/en/dpo_trainer#trl.DPOConfig)相同。控制与参考模型偏差程度的参数。beta值越高，表示与参考模型的偏差越小。对于 IPO 损失函数 (loss_type="ipo")，beta是[论文](https://huggingface.co/papers/2310.12036)中所指的正则化参数。默认为0.1。
|
||||
- 🔥rpo_alpha: 来自[RPO 论文](https://huggingface.co/papers/2404.19733)中的参数，用于控制损失函数中NLL项的权重（即SFT损失），`loss = dpo_loss + rpo_alpha * sft_loss`，论文中推荐设置为`1.`。默认为`None`，即默认不引入sft_loss。
|
||||
- reference_free: 是否忽略提供的参考模型，并隐式地使用一个对所有响应赋予相等概率的参考模型。默认为False。
|
||||
- label_smoothing: 默认为0.。
|
||||
- f_divergence_type: 默认为`reverse_kl`。可选值参考[TRL文档](https://huggingface.co/docs/trl/main/en/dpo_trainer)。
|
||||
- loss_type: 默认为'sigmoid'。可选值参考[TRL文档](https://huggingface.co/docs/trl/main/en/dpo_trainer#loss-functions)。
|
||||
|
||||
### KTO参数
|
||||
- mcore_ref_model: 含义同DPO。
|
||||
- mcore_ref_adapter: 含义同DPO。
|
||||
- beta: 控制与 ref_model 偏离程度的参数。较高的 beta 表示与 ref_model 偏离更小。默认为`0.1`。
|
||||
- loss_type: 默认为'kto'。可选值参考[TRL文档](https://huggingface.co/docs/trl/main/en/kto_trainer#trl.KTOConfig.loss_type)。
|
||||
- desirable_weight: 抵消 desirable 和 undesirable 数量不均衡的影响，对 desirable 损失按该系数进行加权，默认为`1.`。
|
||||
- undesirable_weight: 抵消 desirable 和 undesirable 数量不均衡的影响，对 undesirable 损失按该系数进行加权，默认为`1.`。
|
||||
|
||||
### RM参数
|
||||
- center_rewards_coefficient: 用于激励奖励模型输出均值为零的奖励的系数，具体查看这篇[论文](https://huggingface.co/papers/2312.09244)。推荐值：0.01。
|
||||
|
||||
### GRPO参数
|
||||
- mcore_ref_model: 含义同DPO。
|
||||
- mcore_ref_adapter: 含义同DPO。
|
||||
- beta: KL正则系数，默认为0.04，设置为0时不加载ref model。
|
||||
- micro_batch_size: 每个device的批次大小，默认为1。
|
||||
- global_batch_size: 总批次大小，等价于`micro_batch_size*数据并行大小*梯度累加步数`。默认为16。
|
||||
- steps_per_generation: 每轮生成的优化步数，即采样批量大小相对global_batch_size的倍数，默认为1。
|
||||
- generation_batch_size: 采样批量大小，需要是global_batch_size的倍数，默认等于`global_batch_size*steps_per_generation`。
|
||||
- num_generations: 每个prompt采样的数量，论文中的G值，默认为8。
|
||||
- num_generations_eval: 评估阶段每个prompt采样的数量。允许在评估时使用较少的生成数量以节省计算资源。如果为 None，则使用 num_generations 的值。默认为 None。
|
||||
- reward_funcs: GRPO算法奖励函数，可选项为`accuracy`、`format`、`cosine`、`repetition`和`soft_overlong`，见swift/rewards/orm.py。你也可以在plugin中自定义自己的奖励函数。默认为`[]`。
|
||||
- reward_weights: 每个奖励函数的权重。必须与奖励函数和奖励模型的总数量匹配。默认为 None，即所有奖励的权重都相等，为`1.0`。
|
||||
- 提示：如果GRPO训练中包含`--reward_model`，则其加在奖励函数的最后位置。
|
||||
- truncation_strategy: 对输入长度超过 `max_length`的处理方式，支持`delete`和`left`，代表删除、左侧裁剪，默认为`left`。注意对于多模态模型，左裁剪可能会裁剪掉多模态token导致模型前向报错shape mismatch。使用`delete`方式，对于超长数据和编码失败的样例会在原数据集中重采样其他数据作为补充。
|
||||
- loss_type: loss 归一化的类型，可选项为['grpo', 'bnpo', 'dr_grpo'], 默认为'grpo', 具体查看该[pr](https://github.com/huggingface/trl/pull/3256#discussion_r2033213348)。
|
||||
- log_completions: 是否记录训练中的模型生成内容，默认为False。
|
||||
- vllm_mode: vLLM 集成模式，可选项为 `server` 和 `colocate`。server 模式使用 `swift rollout` 拉起的 vLLM 服务器进行采样，colocate 模式在程序内部署 vLLM。使用server端时，
|
||||
- vllm_mode server 参数
|
||||
- vllm_server_host: vLLM server host地址，默认为None。
|
||||
- vllm_server_port: vLLM server 服务端口，默认为8000。
|
||||
- vllm_server_base_url: vLLM server的Base URL(比如 http://local_host:8000), 默认为None。设置后，忽略host和port设置。
|
||||
- vllm_server_timeout: 连接vLLM server的超时时间，默认为 240s。
|
||||
- vllm_server_pass_dataset: 透传额外的数据集信息到vLLM server，用于多轮训练。
|
||||
- async_generate: 异步rollout以提高训练速度，注意开启时采样会使用上一轮更新的模型进行采样，不支持多轮场景。默认`false`.
|
||||
- SWIFT_UPDATE_WEIGHTS_BUCKET_SIZE: 环境变量，用于控制权重同步时的传输桶大小（bucket size），适用于 Server Mode 下的全参数训练，单位为 MB，默认值为 512 MB。
|
||||
- vllm_mode colocate 参数（更多参数支持参考[vLLM参数](#vLLM参数)。）
|
||||
- vllm_gpu_memory_utilization: vllm透传参数，默认为0.9。
|
||||
- vllm_max_model_len: vllm透传参数，默认为None。
|
||||
- vllm_enforce_eager: vllm透传参数，默认为False。
|
||||
- vllm_limit_mm_per_prompt: vllm透传参数，默认为None。
|
||||
- vllm_enable_prefix_caching: vllm透传参数，默认为True。
|
||||
- vllm_tensor_parallel_size: tp并行数，默认为`1`。
|
||||
- vllm_enable_lora: 支持vLLM Engine 加载 LoRA adapter，默认为False。用于加速LoRA训练的权重同步，具体参考[文档](../Instruction/GRPO/GetStarted/GRPO.md#权重同步加速)。
|
||||
- sleep_level: 训练时释放 vLLM 显存，可选项为[0, 1, 2], 默认为0，不释放。
|
||||
- offload_optimizer: 是否在vLLM推理时offload optimizer参数，默认为False。
|
||||
- offload_model: 是否在vLLM推理时 offload 模型，默认为False。
|
||||
- num_iterations: 每条数据的更新次数，[GRPO论文](https://arxiv.org/abs/2402.03300)中的 $\mu$ 值，默认为1。
|
||||
- epsilon: clip 系数，默认为0.2。
|
||||
- epsilon_high: upper clip 系数，默认为None，设置后与epsilon共同构成[epsilon, epsilon_high]裁剪范围。
|
||||
- dynamic_sample: 筛除group内奖励标准差为0的数据，额外采样新数据，默认为False。
|
||||
- max_resample_times: dynamic_sample设置下限制重采样次数，默认3次。
|
||||
- overlong_filter: 跳过超长截断的样本，不参与loss计算，默认为False。
|
||||
- delta: [INTELLECT-2 tech report](https://huggingface.co/papers/2505.07291)中双侧 GRPO 上界裁剪值。若设置，建议大于 1 + epsilon。默认为None。
|
||||
- importance_sampling_level: 控制重要性采样比计算，可选项为 `token` 和 `sequence`，`token` 模式下保留原始的每个 token 的对数概率比，`sequence` 模式下则会对序列中所有有效 token 的对数概率比进行平均。[GSPO论文](https://arxiv.org/abs/2507.18071)中使用sequence级别计算来稳定训练，默认为`token`。
|
||||
- scale_rewards: 指定奖励的缩放策略。可选值包括 `group`（按组内标准差缩放）、`batch`（按整个批次的标准差缩放）、`none`（不进行缩放）、`gdpo`（对每个奖励函数分别进行组内归一化后加权聚合，参考 [GDPO 论文](https://arxiv.org/abs/2601.05242)）。默认值与 `advantage_estimator` 绑定：`grpo` 对应 `group`，`rloo` 对应 `none`，`reinforce_plus_plus` 对应 `batch`。
|
||||
- 注意：`gdpo` 模式不支持 `kl_in_reward=True`，若同时设置会自动将 `kl_in_reward` 设为 `False`。
|
||||
- GDPO 适用于多奖励优化场景：当使用多个奖励函数时，GDPO 会对每个奖励函数分别在组内进行标准化（减均值、除标准差），然后使用 `reward_weights` 进行加权求和，最后再进行批次级别的标准化。这种方式可以更好地保留各个奖励的相对差异，避免不同奖励组合坍塌成相同的 advantage 值。
|
||||
- rollout_importance_sampling_mode: 训推不一致校正模式，可选项为 `token_truncate`、`token_mask`、`sequence_truncate`、`sequence_mask`。默认为None，不启用校正。具体参考[文档](../Instruction/GRPO/AdvancedResearch/training_inference_mismatch.md)。
|
||||
- rollout_importance_sampling_threshold: 重要性采样权重的阈值，用于截断或屏蔽极端权重。默认为2.0。
|
||||
- log_rollout_offpolicy_metrics: 当 `rollout_importance_sampling_mode` 未设置时，是否记录训推不一致诊断指标（KL、PPL、χ²等）。当设置了 `rollout_importance_sampling_mode` 时，指标会自动记录。默认为False。
|
||||
- off_policy_sequence_mask_delta: Off-Policy Sequence Masking 阈值，来自 DeepSeek-V3.2 论文。当设置此值时，会计算每个序列的 `mean(old_policy_logps - policy_logps)`，若该值大于阈值且该序列的优势为负，则 mask 掉该序列不参与损失计算。默认为None，不启用。具体参考[文档](../Instruction/GRPO/AdvancedResearch/training_inference_mismatch.md#off-policy-sequence-masking)。
|
||||
- router_replay_mode: 路由重放模式，可选项为`disabled`、`R2`、`R3`。默认为disabled，不启用路由重放。
|
||||
- teacher_kl_coef: OPD-RL中teacher_kl的系数，即 `adv_t = base_adv + teacher_kl_coef * teacher_kl`。默认为 1.0。
|
||||
|
||||
内置奖励函数参数参考[文档](../Instruction/Command-line-parameters.md#奖励函数参数)
|
||||
|
||||
### GKD参数
|
||||
|
||||
- beta: JSD 散度插值系数。0.0 代表 Forward KL，0.5 代表对称 JSD，1.0 代表 Reverse KL。默认为0.5。
|
||||
- lmbda: On-Policy 学习触发概率。0.0 代表纯 Off-Policy，1.0 代表纯 On-Policy。默认为0.5。
|
||||
- temperature: 用于采样和损失计算的温度参数。默认为0.9。
|
||||
- sft_alpha: SFT 损失的混合系数，`loss = jsd_loss + sft_alpha * sft_loss`。当使用数据集响应（Off-Policy）时生效。默认为0。
|
||||
- max_completion_length: 生成时的最大 token 数。默认为512。
|
||||
- vllm_mode: 同 GRPO 参数，用于 On-Policy 生成。colocate 模式下在程序内部署 vLLM。
|
||||
- 注意：On-Policy 生成需要启用 vLLM（`--use_vllm true --vllm_mode colocate/server`）。
|
||||
- 当 `lmbda > 0` 但未启用 vLLM 时，将自动回退到 Off-Policy 模式。
|
||||
|
||||
### teacher 参数
|
||||
在GKD与GRPO中使用
|
||||
|
||||
- teacher_model: 教师模型的路径或模型 ID，必需参数。
|
||||
- teacher_model_type: 教师模型类型，默认为None，自动检测。
|
||||
- teacher_model_revision: 教师模型版本，默认为None。
|
||||
- teacher_model_server: 教师模型服务地址，通过 `swift deploy` 部署后用于获取 logprobs，与 `teacher_model` 互斥。支持单 URL 或多 teacher JSON（`'[{"url":"...","tags":["..."]}, ...]'`）。详见[蒸馏文档](../Instruction/Distillation.md#multi-teacher多教师路由)。
|
||||
- teacher_tag_key: 多 teacher 路由时样本匹配 teacher `tags` 的字段名，默认为 `"dataset"`。
|
||||
- offload_teacher_model: 是否将教师模型卸载到 CPU 以节省 GPU 显存。默认为False。
|
||||
|
||||
|
||||
## 导出参数
|
||||
这里介绍`megatron export`的参数，若要使用`swift export`导出命令，请参考[ms-swift命令行参数文档](../Instruction/Command-line-parameters.md#导出参数)。`megatron export`相比`swift export`，支持分布式和多机导出。Megatron导出参数继承自Megatron参数和基本参数。
|
||||
- 🔥to_mcore: HF格式权重转成Megatron格式。默认为False。
|
||||
- 🔥to_hf: Megatron格式权重转成HF格式。默认为False。
|
||||
- 🔥merge_lora: 默认为None，若`to_hf`设置为True，该参数默认值为`True`，否则为False。即默认情况下，存储为safetensors格式时会合并LoRA；存储为torch_dist格式时，不会合并LoRA。合并后的权重存储在`--output_dir`目录下。
|
||||
- 注意：transformers 5.0对Moe的模型组织结构进行了重构，该结构不支持Moe LoRA的推理，可能造成推理异常。**建议对Moe模型进行Merge LoRA**（vLLM不受影响）。
|
||||
- 注意：由于transformers和Megatron模型专家结构并不一定一致（例如transformers的Qwen3-VL-Moe的专家部分并不是Linear实现，而是Parameters），因此部分模型无法转换（若Qwen3-VL-Moe只设置linear_proj和linear_qkv训练LoRA也支持转换）。但大多数的模型支持LoRA转换，例如：Qwen3-Moe，Qwen3-Omni-Moe，GLM4.5-V等。
|
||||
- 🔥test_convert_precision: 测试HF和Megatron格式权重转换的精度误差。默认为False。
|
||||
- test_convert_dtype: 转换精度测试使用的dtype，默认为'float32'。
|
||||
- exist_ok: 如果`args.output_dir`存在，不抛出异常，进行覆盖。默认为False。
|
||||
- device_map: 设置`--test_convert_precision true`时生效，控制HF模型的加载位置，默认为'auto'。你可以设置为'cpu'节约显存资源。
|
||||
@@ -0,0 +1,270 @@
|
||||
# 自定义Megatron模型
|
||||
|
||||
|
||||
这里介绍如何在[Mcore-Bridge](https://github.com/modelscope/mcore-bridge)中注册模型，以支持新模型在Megatron-SWIFT中的训练。我们将以MiniMax-M2.7为例子介绍。
|
||||
|
||||
## 下载模型
|
||||
|
||||
首先，你需要下载模型配置。
|
||||
|
||||
```python
|
||||
from swift import safe_snapshot_download
|
||||
|
||||
model_dir = safe_snapshot_download('MiniMax/MiniMax-M2.7', download_model=False)
|
||||
print(f'model_dir: {model_dir}')
|
||||
```
|
||||
|
||||
由于模型权重很大，为了加速支持模型的效率，我们采用懒下载的方式，并只下载`num_layers`层的权重，构建mini版本的模型，用于做接入测试。以MiniMax-M2.7为例，我们构建了一层的BF16版本的权重。若有些模型出现前3层为Dense，之后为MoE，则你可以构建4层的权重。若出现Attention交替的情况，例如Qwen3.5采用linear-attention和full-attention交替，你也需要更多的层数。
|
||||
|
||||
```python
|
||||
import os
|
||||
import torch
|
||||
from modelscope.hub.file_download import model_file_download
|
||||
from safetensors.torch import safe_open
|
||||
from swift import safe_snapshot_download
|
||||
|
||||
from mcore_bridge.utils import Fp8Dequantizer, SafetensorLazyLoader, StreamingSafetensorSaver
|
||||
|
||||
model_id = 'MiniMax/MiniMax-M2.7'
|
||||
# 有些模型会出现前几层为dense，后面为moe的情况，需合理设置该值
|
||||
num_layers = 1 # 只下载`num_layers`层，节约磁盘占用和运行时显存占用
|
||||
model_dir = safe_snapshot_download(model_id, download_model=False)
|
||||
|
||||
loader = SafetensorLazyLoader(model_dir)
|
||||
state_dict = loader.get_state_dict()
|
||||
saver = StreamingSafetensorSaver(save_dir=model_dir)
|
||||
new_state_dict = {}
|
||||
fp8_dequantizer = Fp8Dequantizer() # 用于将fp8权重转成bf16
|
||||
|
||||
|
||||
def _open_file(self, filename: str):
|
||||
if filename not in self._file_handles:
|
||||
file_path = os.path.join(self.hf_model_dir, filename)
|
||||
tmp_dir = os.path.join(self.hf_model_dir, 'tmp')
|
||||
if not os.path.exists(file_path):
|
||||
file_path = os.path.join(tmp_dir, filename)
|
||||
if not os.path.exists(file_path):
|
||||
file_path = model_file_download(
|
||||
model_id=model_id,
|
||||
file_path=filename,
|
||||
local_dir=tmp_dir,
|
||||
)
|
||||
self._file_handles[filename] = safe_open(file_path, framework='pt')
|
||||
return self._file_handles[filename]
|
||||
|
||||
|
||||
SafetensorLazyLoader._open_file = _open_file # monkey patch (懒下载)
|
||||
|
||||
for k, v in state_dict.items():
|
||||
if k.startswith('model.layers.'):
|
||||
idx = int(k[len('model.layers.'):].split('.', 1)[0])
|
||||
if idx >= num_layers:
|
||||
continue
|
||||
if k.endswith('.weight_scale_inv'):
|
||||
continue
|
||||
elif k.endswith('.weight'):
|
||||
weight_scale_inv = k.replace('.weight', '.weight_scale_inv')
|
||||
if weight_scale_inv in state_dict:
|
||||
v = fp8_dequantizer.convert(v.load(), state_dict[weight_scale_inv].load()).to(torch.bfloat16)
|
||||
new_state_dict[k] = v if isinstance(v, torch.Tensor) else v.load()
|
||||
|
||||
for k, v in new_state_dict.items():
|
||||
saver.add_tensor(k, v)
|
||||
saver.finalize()
|
||||
```
|
||||
|
||||
保存完权重后，你需要修改'config.json'，将`num_hidden_layers`修改为1（与上面的代码对应），并删除`quantization_config`配置（因为权重为BF16的，而不是FP8）。FP8的训练大多数模型会自动适配，但有些模型可能需要额外适配，例如：Qwen3.5的FP8的适配参考[这个PR](https://github.com/modelscope/mcore-bridge/pull/30)。
|
||||
|
||||
|
||||
## 注册模型
|
||||
|
||||
以下提供debug代码，你需要修改代码，以确保huggingface transformers库的forward与megatron的forward对齐。
|
||||
```python
|
||||
import os
|
||||
os.environ['CUDA_VISIBLE_DEVICES'] = '0,1,2,3'
|
||||
os.environ['SWIFT_TEST_CONVERT_PRECISION'] = '1'
|
||||
|
||||
from swift import export_main, ExportArguments, safe_snapshot_download
|
||||
|
||||
model_id = 'MiniMax/MiniMax-M2.7'
|
||||
|
||||
model_dir = safe_snapshot_download(model_id, download_model=False)
|
||||
|
||||
export_main(
|
||||
ExportArguments(
|
||||
model=model_dir,
|
||||
to_mcore=True,
|
||||
exist_ok=True,
|
||||
test_convert_precision=True,
|
||||
torch_dtype='bfloat16',
|
||||
))
|
||||
```
|
||||
|
||||
'minimax_m2'的注册可以查看[这个文件](https://github.com/modelscope/mcore-bridge/blob/main/src/mcore_bridge/model/gpts/minimax_m2.py)。我们注册时指定了模型对应的GPTBridge类和模型加载器loader。
|
||||
|
||||
```python
|
||||
register_model(ModelMeta(
|
||||
ModelType.minimax_m2,
|
||||
['minimax_m2'],
|
||||
bridge_cls=MinimaxM2Bridge,
|
||||
loader=MinimaxM2Loader,
|
||||
))
|
||||
```
|
||||
|
||||
参数的总和对齐：
|
||||
```
|
||||
[INFO:swift] n_parameter: 522
|
||||
[INFO:swift] total_sum: 106747128.72671509
|
||||
[INFO:swift] zero_count: 0
|
||||
[INFO:swift] n_parameter: 780
|
||||
[INFO:swift] total_sum: 106747129.32046509
|
||||
[INFO:swift] zero_count: 0
|
||||
```
|
||||
|
||||
模型forward的logits对齐。（当然我们还需要对模型进行训练，训练后再测试forward的精度，避免出现这里输出tokens都是同一个的情况）。
|
||||
```
|
||||
mean_diff: 2.8353377274470404e-05, max_diff: 0.0015382766723632812
|
||||
mean_diff (with loss): 2.1664049199898727e-05, max_diff (with loss): 0.00021076202392578125 (Please check that mean_diff (with loss) is less than 0.1).
|
||||
hf_tokens: [190962, 103239, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367]
|
||||
mg_tokens: [190962, 103239, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367, 367]
|
||||
token_diff: 0
|
||||
token_diff (with loss): 0
|
||||
```
|
||||
|
||||
通常在参数总数对齐和输出logits对齐后，模型就基本接入成功了。此外你可能还需要适配TP/CP的情况。你可以使用以下代码debug：
|
||||
```python
|
||||
import os
|
||||
|
||||
os.environ['CUDA_VISIBLE_DEVICES'] = '0,1'
|
||||
os.environ['SWIFT_TEST_CONVERT_PRECISION'] = '1'
|
||||
|
||||
from swift.megatron import MegatronExportArguments, megatron_export_main
|
||||
from swift import safe_snapshot_download
|
||||
model_id = 'MiniMax/MiniMax-M2.7'
|
||||
|
||||
model_dir = safe_snapshot_download(model_id, download_model=False)
|
||||
|
||||
if __name__ == '__main__':
|
||||
megatron_export_main(
|
||||
MegatronExportArguments(
|
||||
model=model_dir,
|
||||
to_mcore=True, # 也可以修改成 `to_hf=True` 测试
|
||||
tensor_model_parallel_size=2,
|
||||
sequence_parallel=True,
|
||||
expert_model_parallel_size=2,
|
||||
test_convert_precision=True,
|
||||
))
|
||||
```
|
||||
|
||||
我们需要用torchrun启动，vscode配置：
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "torchrun2",
|
||||
"type": "debugpy",
|
||||
"request": "launch",
|
||||
"program": "-m",
|
||||
"console": "integratedTerminal",
|
||||
"justMyCode": false,
|
||||
"args": [
|
||||
"torch.distributed.run",
|
||||
"--nproc_per_node",
|
||||
"2",
|
||||
"--master_port", "29501",
|
||||
"${file}"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
其他模型的注册例子，可以查看对应PR：[hy_v3](https://github.com/modelscope/mcore-bridge/pull/53)、[kimi_25](https://github.com/modelscope/mcore-bridge/pull/52)。在2026年4月之前的接入PR可以在ms-swift库中寻找。
|
||||
|
||||
|
||||
## 测试准确性
|
||||
|
||||
我们对mini版本的模型进行训练，我们只使用自我认知数据集，并训练到过拟合。
|
||||
|
||||
```shell
|
||||
# 2 * 80GiB
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--model /root/.cache/modelscope/models/MiniMax/MiniMax-M2.7 \
|
||||
--save_safetensors true \
|
||||
--dataset 'swift/self-cognition#500' \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--sequence_parallel true \
|
||||
--micro_batch_size 16 \
|
||||
--global_batch_size 16 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 2e-5 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-5 \
|
||||
--num_train_epochs 10 \
|
||||
--output_dir megatron_output \
|
||||
--save_steps 500 \
|
||||
--max_length 2048 \
|
||||
--system 'You are a helpful assistant.' \
|
||||
--dataloader_num_workers 4 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--moe_permute_fusion true \
|
||||
--expert_model_parallel_size 2 \
|
||||
--moe_grouped_gemm true \
|
||||
--moe_shared_expert_overlap true \
|
||||
--moe_aux_loss_coeff 1e-3 \
|
||||
--dataset_num_proc 4 \
|
||||
--model_author swift \
|
||||
--model_name swift-robot
|
||||
```
|
||||
|
||||
进行推理，查看训练效果：
|
||||
```shell
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--model megatron_output/v3-20260430-143926/checkpoint-310 \
|
||||
--max_new_tokens 64 \
|
||||
--enable_thinking false \
|
||||
--temperature 0
|
||||
```
|
||||
|
||||
```
|
||||
<<< 你是谁
|
||||
我是一个由swift开发的人工智能助手，被称为swift-robot。我主要的目的是通过文本交流为用户提供帮助、信息和娱乐。如果您有任何疑问或需要帮助，请随时提出，我会尽力协助您。
|
||||
--------------------------------------------------
|
||||
<<< clear
|
||||
<<< who are you
|
||||
I am a language model developed by swift, you can call me swift-robot. How can I assist you?
|
||||
--------------------------------------------------
|
||||
```
|
||||
|
||||
|
||||
再次测试forward精度对齐：
|
||||
```
|
||||
mean_diff: 0.0005969047779217362, max_diff: 0.013172879815101624
|
||||
mean_diff (with loss): 0.0005803848034702241, max_diff (with loss): 0.009410381317138672 (Please check that mean_diff (with loss) is less than 0.1).
|
||||
hf_tokens: [190962, 190962, 367, 44, 46, 2362, 5129, 6415, 75827, 343, 10, 1497, 71151, 11915, 1497, 44, 3003, 44, 46, 46, 4387, 10, 32, 10, 258, 1497, 44, 46, 46, 258, 18268, 44, 692, 13268, 42047, 3764, 46, 46, 46, 94454, 46, 46, 275, 296, 3786, 46, 46, 275, 46, 46, 3786, 46, 2329, 10, 722]
|
||||
mg_tokens: [190962, 190962, 367, 44, 46, 2362, 5129, 6415, 75827, 343, 10, 1497, 71151, 11915, 1497, 44, 3003, 44, 46, 46, 4387, 10, 32, 10, 258, 1497, 44, 46, 46, 258, 18268, 44, 692, 13268, 42047, 3764, 46, 46, 46, 94454, 46, 46, 275, 296, 3786, 46, 46, 275, 46, 46, 3786, 46, 2329, 10, 722]
|
||||
token_diff: 0
|
||||
token_diff (with loss): 0
|
||||
```
|
||||
|
||||
至此，模型接入成功啦！
|
||||
|
||||
|
||||
## 提交PR
|
||||
|
||||
如果你想给ms-swift/mcore-bridge提交PR，你需要额外运行以下命令，对代码进行整理：
|
||||
|
||||
```shell
|
||||
pip install pre-commit
|
||||
pre-commit run --all-files
|
||||
```
|
||||
@@ -0,0 +1,48 @@
|
||||
# GKD
|
||||
|
||||
如果你是首次使用 GKD/OPD-RL，请先参考 [蒸馏文档](../Instruction/Distillation.md)。
|
||||
|
||||
GKD（Generalized Knowledge Distillation，广义知识蒸馏）是一种将教师模型的知识迁移到学生模型的训练方法，通过计算两个模型输出分布之间的 Jensen-Shannon 散度（JSD）损失来实现知识蒸馏。
|
||||
|
||||
## 功能支持
|
||||
|
||||
Megatron GKD 当前已支持以下功能：
|
||||
|
||||
- **训练模式**：全参数训练与 LoRA 微调
|
||||
- **并行策略**：支持上下文并行（CP）、流水线并行（PP）、张量并行（TP）和专家并行（EP）
|
||||
- **模型支持**：兼容 Megatron-SWIFT 中的 LLM 及 MLLM
|
||||
- **Teacher Offload**：支持将教师模型卸载到 CPU 以节省 GPU 显存
|
||||
- **在线生成**：支持使用 vLLM 进行学生模型的 on-policy 生成
|
||||
|
||||
## 参数说明
|
||||
|
||||
### GKD 参数
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `--teacher_model` | str | - | 教师模型路径或模型 ID<br>*使用 `teacher_model_server` 时可省略 |
|
||||
| `--teacher_model_server` | str | None | 教师 API 地址；支持单 URL 或多 teacher JSON，详见[蒸馏文档](../Instruction/Distillation.md#multi-teacher多教师路由) |
|
||||
| `--teacher_tag_key` | str | `"dataset"` | 多 teacher 路由时样本匹配 teacher `tags` 的字段名 |
|
||||
| `--gkd_logits_topk` | int | None | Top-K logits 数量，使用外部教师 API 时必须设置 |
|
||||
| `--beta` | float | 0.5 | JSD 散度插值系数：<br>• 0.0: Forward KL<br>• 0.5: 对称 JSD<br>• 1.0: Reverse KL |
|
||||
| `--lmbda` | float | 0.5 | On-Policy 学习触发概率：<br>• 0.0: 纯 Off-Policy<br>• 1.0: 纯 On-Policy |
|
||||
| `--temperature` | float | 0.9 | 温度参数，用于采样和损失计算 |
|
||||
| `--sft_alpha` | float | 0 | 混合一定比例的sft loss，对非student生成结果生效 |
|
||||
| `--max_completion_length` | int | 512 | 生成时的最大 token 数 |
|
||||
|
||||
### 批量相关参数
|
||||
|
||||
与 Megatron SFT 相同，使用以下参数控制批量大小：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--micro_batch_size` | 每个DP组的训练批次大小 |
|
||||
| `--global_batch_size` | 全局批次大小：`micro_batch_size × dp_size × gradient_accumulation_steps` |
|
||||
|
||||
## 参考
|
||||
|
||||
更多参数请参考[命令行文档](./Command-line-parameters.md)
|
||||
|
||||
训练脚本请参考 [Megatron GKD 脚本](https://github.com/modelscope/ms-swift/blob/main/examples/megatron/rlhf/gkd)
|
||||
|
||||
使用 Teacher Server 的训练脚本请参考 [这里](https://github.com/modelscope/ms-swift/blob/main/examples/megatron/rlhf/gkd/teacher_server.sh)
|
||||
@@ -0,0 +1,42 @@
|
||||
# GRPO
|
||||
|
||||
|
||||
如果你是首次使用 GRPO，请先参考 [GRPO文档](../Instruction/GRPO/GetStarted/GRPO.md)。
|
||||
|
||||
Megatron GRPO 当前已支持以下功能：
|
||||
|
||||
- **训练模式**：全参数训练与 LoRA 微调
|
||||
- **并行策略**：支持上下文并行（CP）、流水线并行（PP）、张量并行（TP）和专家并行（EP）
|
||||
- **推理加速**：支持 vLLM 的 colocate 模式和 server 模式
|
||||
- **模型支持**：兼容 Megatron Swift 中的 LLM 及 MLLM（多模态大模型）
|
||||
- **算法支持**：涵盖 swift GRPO 的大部分功能
|
||||
|
||||
与 ms-swift GRPO 相同，Megatron GRPO batch size 相关的参数均以 **completion-level** 为单位，即表示模型生成的 completion 数量，而非 prompt 数量。
|
||||
|
||||
#### 参数对比
|
||||
|
||||
下表对比了 ms-swift 和 Megatron-SWIFT 中批量相关参数的对应关系：
|
||||
|
||||
| ms-swift 参数 | Megatron-SWIFT 参数 | 说明 |
|
||||
|---------------|---------------------|------|
|
||||
| `per_device_train_batch_size` | `micro_batch_size` | 每个DP组的训练批次大小（completion-level） |
|
||||
| `gradient_accumulation_steps` | - | 梯度累积步数，在 Megatron-SWIFT 中已包含在 `global_batch_size` 的计算中 |
|
||||
| - | `global_batch_size` | 全局批次大小（completion-level）<br/>**Megatron-SWIFT**: `micro_batch_size × dp_size × gradient_accumulation_steps`<br/>**ms-swift**: `per_device_train_batch_size × world_size × gradient_accumulation_steps` |
|
||||
| `num_generations` | `num_generations` | 每个 prompt 生成的 completion 数量 |
|
||||
| `steps_per_generation` | `steps_per_generation` | Rollout 批次大小相对于训练批次大小的倍数<br/>**注意**：在 ms-swift 中需为 `gradient_accumulation_steps` 的整数倍 |
|
||||
| `generation_batch_size` | `generation_batch_size` | Rollout 阶段的批次大小（completion-level），需为 `global_batch_size` 的整数倍 |
|
||||
|
||||
以下公式用于计算 Megatron GRPO 中的批量：
|
||||
|
||||
- **数据并行大小**：`dp_size = world_size / (TP × PP × CP)`
|
||||
- **全局批次大小**：`global_batch_size = micro_batch_size × dp_size × gradient_accumulation_steps`
|
||||
- **生成批次大小**：`generation_batch_size = global_batch_size × steps_per_generation`
|
||||
- **Rollout Prompt 数量**：`num_rollout_prompts = generation_batch_size / num_generations`
|
||||
- **训练 Prompt 数量**：`num_train_prompts = global_batch_size / num_generations`
|
||||
- **每个 DP group 的训练 Prompt 数量**：`num_prompts_per_dp_group = global_batch_size / num_generations / dp_size`
|
||||
|
||||
注意：在 Megatron GRPO 中，每个 DP group 的训练 Prompt 数量须满足 `num_prompts_per_dp_group` 是 `micro_batch_size`的整数倍，以确保训练批次能够正确分配。
|
||||
|
||||
更多参数请参考[命令行文档](./Command-line-parameters.md#grpo参数)
|
||||
|
||||
训练脚本请参考[Megatron GRPO 脚本](https://github.com/modelscope/ms-swift/blob/main/examples/megatron/grpo)
|
||||
@@ -0,0 +1,215 @@
|
||||
# LoRA训练
|
||||
|
||||
Qwen3-235B-A22B-Instruct-250718 单机8卡H20 LoRA训练的最佳实践参考：[https://github.com/modelscope/ms-swift/pull/5033](https://github.com/modelscope/ms-swift/pull/5033)。
|
||||
|
||||
环境准备请参考Megatron-SWIFT的[快速开始文档](./Quick-start.md)。
|
||||
|
||||
## 传统方式
|
||||
|
||||
### HF转换Mcore
|
||||
|
||||
以下，我们分别介绍使用`swift export`和`megatron export`命令进行权重转换。相比于`swift export`，`megatron export`支持多机和LoRA增量权重转换，但也更加复杂，需要在导出时额外指定并行参数，例如`--tensor_model_parallel_size`, `--export_model_parallel_size`，具体参考[Mcore-Bridge文档](./Mcore-Bridge.md)。若要使用`swift export`命令，参考[快速开始文档](./Quick-start.md)。
|
||||
- `swift export`使用单进程，将HF权重放置在gpu中，并使用device_map并行；mcore权重放置在cpu中，且不开启并行。这种方式非常易于debug，并测试HF和mcore的精度对齐情况。
|
||||
- `megatron export`使用torchrun启动多进程，mcore权重放置在gpu中，支持开启各种并行、fp8和mtp等功能。如果需测试精度对齐情况，会在第一个rank加载HF权重，并放置在cpu中。
|
||||
|
||||
```shell
|
||||
# megatron export
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron export \
|
||||
--model Qwen/Qwen2.5-7B-Instruct \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--to_mcore true \
|
||||
--torch_dtype bfloat16 \
|
||||
--output_dir Qwen2.5-7B-Instruct-mcore \
|
||||
--test_convert_precision true
|
||||
|
||||
# swift export
|
||||
# CUDA_VISIBLE_DEVICES=0 \
|
||||
# swift export \
|
||||
# --model Qwen/Qwen2.5-7B-Instruct \
|
||||
# --to_mcore true \
|
||||
# --torch_dtype bfloat16 \
|
||||
# --output_dir Qwen2.5-7B-Instruct-mcore \
|
||||
# --test_convert_precision true
|
||||
```
|
||||
|
||||
### LoRA训练
|
||||
|
||||
训练脚本：
|
||||
```bash
|
||||
# full: 2 * 70GiB 0.61s/it
|
||||
# lora: 2 * 14GiB 0.45s/it
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--mcore_model Qwen2.5-7B-Instruct-mcore \
|
||||
--save_safetensors false \
|
||||
--dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \
|
||||
'AI-ModelScope/alpaca-gpt4-data-en#500' \
|
||||
'swift/self-cognition#500' \
|
||||
--tuner_type lora \
|
||||
--lora_rank 8 \
|
||||
--lora_alpha 32 \
|
||||
--target_modules all-linear \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--sequence_parallel true \
|
||||
--micro_batch_size 16 \
|
||||
--global_batch_size 16 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 1e-4 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-5 \
|
||||
--num_train_epochs 1 \
|
||||
--output_dir megatron_output/Qwen2.5-7B-Instruct \
|
||||
--save_steps 100 \
|
||||
--max_length 2048 \
|
||||
--system 'You are a helpful assistant.' \
|
||||
--dataloader_num_workers 4 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--dataset_num_proc 4 \
|
||||
--model_author swift \
|
||||
--model_name swift-robot
|
||||
```
|
||||
- MoE模型的LoRA训练脚本参考[这里](https://github.com/modelscope/ms-swift/tree/main/examples/megatron/lora)。
|
||||
|
||||
### MCore转换HF
|
||||
|
||||
```bash
|
||||
# megatron export
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron export \
|
||||
--mcore_adapter megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
--to_hf true \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--merge_lora false \
|
||||
--torch_dtype bfloat16 \
|
||||
--output_dir megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx-hf \
|
||||
--test_convert_precision true
|
||||
|
||||
# swift export
|
||||
# CUDA_VISIBLE_DEVICES=0 \
|
||||
# swift export \
|
||||
# --mcore_adapter megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
# --to_hf true \
|
||||
# --torch_dtype bfloat16 \
|
||||
# --output_dir megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx-hf \
|
||||
# --test_convert_precision true
|
||||
```
|
||||
- 注意：`--mcore_adapter`文件夹中包含`args.json`文件，转换过程会读取文件中`--model/--mcore_model`以及LoRA相关的参数信息。`swift export`暂不支持LoRA增量权重的转换。`megatron export`你可以使用`--merge_lora`参数控制是否进行权重合并。
|
||||
|
||||
### 推理
|
||||
```shell
|
||||
# 如果是全量权重，请将`--adapters`替换为`--model
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--adapters megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx-hf \
|
||||
--stream true
|
||||
```
|
||||
|
||||
### Merge-LoRA
|
||||
|
||||
如果只想merge-lora，而不希望转成HF格式权重，用于后续DPO训练，可以使用以下脚本：
|
||||
```shell
|
||||
# megatron export
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron export \
|
||||
--mcore_adapter megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--to_mcore true \
|
||||
--merge_lora true \
|
||||
--torch_dtype bfloat16 \
|
||||
--output_dir megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx-mcore \
|
||||
--test_convert_precision true
|
||||
|
||||
# swift export
|
||||
# CUDA_VISIBLE_DEVICES=0 \
|
||||
# swift export \
|
||||
# --mcore_adapter megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
# --to_mcore true \
|
||||
# --torch_dtype bfloat16 \
|
||||
# --output_dir megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx-mcore \
|
||||
# --test_convert_precision true
|
||||
```
|
||||
|
||||
## Mcore-Bridge【推荐】
|
||||
|
||||
### 训练
|
||||
|
||||
```shell
|
||||
# full: 2 * 70GiB 0.61s/it
|
||||
# lora: 2 * 14GiB 0.45s/it
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--model Qwen/Qwen2.5-7B-Instruct \
|
||||
--save_safetensors true \
|
||||
--merge_lora false \
|
||||
--dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \
|
||||
'AI-ModelScope/alpaca-gpt4-data-en#500' \
|
||||
'swift/self-cognition#500' \
|
||||
--tuner_type lora \
|
||||
--lora_rank 8 \
|
||||
--lora_alpha 32 \
|
||||
--target_modules all-linear \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--sequence_parallel true \
|
||||
--micro_batch_size 16 \
|
||||
--global_batch_size 16 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 1e-4 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-5 \
|
||||
--num_train_epochs 1 \
|
||||
--output_dir megatron_output/Qwen2.5-7B-Instruct \
|
||||
--save_steps 100 \
|
||||
--max_length 2048 \
|
||||
--system 'You are a helpful assistant.' \
|
||||
--dataloader_num_workers 4 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--dataset_num_proc 4 \
|
||||
--model_author swift \
|
||||
--model_name swift-robot
|
||||
```
|
||||
|
||||
### 推理
|
||||
|
||||
```shell
|
||||
# 如果是全量权重，请将`--adapters`替换为`--model
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--adapters megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
--stream true
|
||||
```
|
||||
|
||||
|
||||
### Merge-LoRA
|
||||
|
||||
由于训练的时候设置了`--merge_lora false`，后续如果想将lora权重合并成全量safetensors权重，可以使用以下脚本：
|
||||
```shell
|
||||
# 由于lora权重是safetensors格式，你需要使用`--adapters`而不是`--mcore_adapter`
|
||||
# megatron export
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron export \
|
||||
--adapters megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--to_hf true \
|
||||
--merge_lora true \
|
||||
--torch_dtype bfloat16 \
|
||||
--output_dir megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx-merged
|
||||
```
|
||||
@@ -0,0 +1,247 @@
|
||||
# Mcore-Bridge
|
||||
Megatron 以其卓越的训练速度和丰富的并行技术而著称，但也因此带来了较高的使用门槛。因此[mcore-bridge](https://github.com/modelscope/mcore-bridge) 应运而生，旨在让 Megatron 训练像 transformers 一样简单易用。通过 Mcore-Bridge，用户可以：
|
||||
|
||||
1. 直接加载 safetensors 格式的模型权重，无缝使用 Megatron 进行高效训练。直接保存 训练权重为 safetensors 格式，无需额外转换。
|
||||
2. 兼容 LoRA 增量权重的双向转换。
|
||||
3. 兼容GRPO/GKD等算法的`Megatron->vLLM`权重同步。
|
||||
4. 支持多机转换超大规模模型。
|
||||
|
||||
Mcore-Bridge 兼容 Dense/MoE/多模态等多种模型架构。训练完成后，转换后的模型可直接使用 transformers、vLLM、SGLang 等主流推理框架部署。
|
||||
|
||||
## 无缝训练
|
||||
目前Mcore-Bridge已支持TP/PP/EP/ETP/VPP等并行技术，支持的模型参考[支持的模型文档](../Instruction/Supported-models-and-datasets.md)。以下介绍Mcore-Bridge的无缝训练能力。
|
||||
|
||||
- 使用`--model/--adapters/--ref_model/--ref_adapters`参数读取模型时，将使用mcore-bridge来读取safetensors格式的模型权重。若使用`--mcore_model/--mcore_adapter/--mcore_ref_model/--mcore_ref_adapter`参数，则使用mcore默认方式读取。
|
||||
- `save_safetensors`参数决定存储权重为safetensors格式还是mcore格式。如果设置`--no_save_optim false`则总会额外存储一份mcore权重用于断点续训。
|
||||
- 提示：在GKD/GRPO训练期间，如果在vLLM权重更新时遇到 GPU OOM 问题，您可以设置 `--offload_bridge true` 将张量卸载到 CPU 减少 GPU 内存使用量。
|
||||
|
||||
### 全参数
|
||||
|
||||
以下为多模态模型Qwen3-VL模型训练的例子:
|
||||
```shell
|
||||
# 2 * 76GiB
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
IMAGE_MAX_TOKEN_NUM=1024 \
|
||||
VIDEO_MAX_TOKEN_NUM=128 \
|
||||
FPS_MAX_FRAMES=16 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--model Qwen/Qwen3-VL-8B-Instruct \
|
||||
--save_safetensors true \
|
||||
--dataset 'AI-ModelScope/LaTeX_OCR:human_handwrite#5000' \
|
||||
--load_from_cache_file true \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--sequence_parallel true \
|
||||
--packing true \
|
||||
--freeze_llm false \
|
||||
--freeze_vit true \
|
||||
--freeze_aligner true \
|
||||
--split_dataset_ratio 0.01 \
|
||||
--micro_batch_size 1 \
|
||||
--global_batch_size 4 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 1e-5 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-6 \
|
||||
--num_train_epochs 1 \
|
||||
--output_dir megatron_output/Qwen3-VL-8B-Instruct \
|
||||
--save_steps 200 \
|
||||
--max_length 2048 \
|
||||
--dataloader_num_workers 4 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--dataset_num_proc 8
|
||||
```
|
||||
|
||||
然后我们对验证集部分进行推理：
|
||||
```shell
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
IMAGE_MAX_TOKEN_NUM=1024 \
|
||||
VIDEO_MAX_TOKEN_NUM=128 \
|
||||
FPS_MAX_FRAMES=16 \
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--model megatron_output/Qwen3-VL-8B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
--load_data_args true \
|
||||
--stream true
|
||||
```
|
||||
|
||||
### LoRA
|
||||
|
||||
Mcore-Bridge除了支持全参数训练，还支持LoRA训练。
|
||||
|
||||
以下为纯文本模型Qwen3-Moe模型使用LoRA自我认知训练的例子：
|
||||
- 若你希望导出merge后的权重，而不是LoRA增量权重，请设置`--merge_lora true`。设置`--merge_lora true`的兼容性更好，支持所有系列模型。
|
||||
- 注意：（transformers>5.0的情况）transformers 5.0对Moe的模型组织结构进行了重构，该结构不支持Moe LoRA的推理，可能造成推理异常。**建议对Moe模型进行Merge LoRA**（vLLM不受影响，看vLLM的支持情况）。
|
||||
- 注意：（transformers<5.0的情况）由于transformers和Megatron模型专家结构并不一定一致（例如transformers的Qwen3-VL-Moe的专家部分并不是Linear实现，而是Parameters），因此部分模型无法转换LoRA增量权重（若Qwen3-VL-Moe只设置linear_proj和linear_qkv训练LoRA也支持转换）。但大多数的模型支持LoRA转换，例如：Qwen3-Moe，Qwen3-Omni-Moe，GLM4.5-V等。
|
||||
|
||||
```shell
|
||||
# 50GiB
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--model Qwen/Qwen3-30B-A3B-Instruct-2507 \
|
||||
--save_safetensors true \
|
||||
--merge_lora false \
|
||||
--dataset 'swift/Chinese-Qwen3-235B-2507-Distill-data-110k-SFT#2000' \
|
||||
'swift/self-cognition#1000' \
|
||||
--load_from_cache_file true \
|
||||
--tuner_type lora \
|
||||
--lora_rank 8 \
|
||||
--lora_alpha 32 \
|
||||
--target_modules all-linear \
|
||||
--split_dataset_ratio 0.01 \
|
||||
--moe_permute_fusion true \
|
||||
--expert_model_parallel_size 2 \
|
||||
--moe_grouped_gemm true \
|
||||
--moe_shared_expert_overlap true \
|
||||
--moe_aux_loss_coeff 1e-3 \
|
||||
--micro_batch_size 8 \
|
||||
--global_batch_size 16 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--num_train_epochs 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 1e-4 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-5 \
|
||||
--output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507 \
|
||||
--eval_steps 200 \
|
||||
--save_steps 200 \
|
||||
--max_length 2048 \
|
||||
--dataloader_num_workers 8 \
|
||||
--dataset_num_proc 8 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--sequence_parallel true \
|
||||
--moe_expert_capacity_factor 2 \
|
||||
--attention_backend flash \
|
||||
--model_author swift \
|
||||
--model_name swift-robot
|
||||
```
|
||||
|
||||
|
||||
对导出的LoRA权重进行推理，这里使用vLLM推理引擎：
|
||||
```shell
|
||||
# 具体模型vLLM的LoRA的支持情况请参考vLLM文档。
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--model Qwen/Qwen3-30B-A3B-Instruct-2507 \
|
||||
--adapters megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx \
|
||||
--infer_backend vllm \
|
||||
--vllm_max_model_len 8192 \
|
||||
--stream true
|
||||
```
|
||||
|
||||
如果你需要手动进行**Merge-LoRA**，你可以使用`megatron export`命令。注意：请不要使用`swift export`导出命令Merge-LoRA，因为Megatron与transformers的**Moe模型结构**并不一定一致。
|
||||
|
||||
```shell
|
||||
# 如果是mcore格式的adapter，请使用`--mcore_adapter`
|
||||
# 如果最终格式需要是mcore格式，则使用`--to_mcore true`
|
||||
CUDA_VISIBLE_DEVICES=0,1,2,3 \
|
||||
NPROC_PER_NODE=4 \
|
||||
megatron export \
|
||||
--model Qwen/Qwen3-30B-A3B-Instruct-2507 \
|
||||
--adapters megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx \
|
||||
--output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-merged \
|
||||
--merge_lora true \
|
||||
--to_hf true \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--expert_model_parallel_size 2 \
|
||||
--pipeline_model_parallel_size 2
|
||||
```
|
||||
|
||||
对Merge的全量权重进行推理，这里使用transformers推理引擎：
|
||||
|
||||
```shell
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--model megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-merged \
|
||||
--stream true
|
||||
```
|
||||
|
||||
## `megatron export` 与 转换精度测试
|
||||
|
||||
Mcore-Bridge除了支持在训练中进行safetensors的转换和保存，也支持了`megatron export`命令用于单独的权重导出。`megatron export`支持在权重转换时，对转换精度进行测试，这在接入新模型时验证接入准确性很有帮助。通常，Megatron-SWIFT已经接入的模型不会出现精度不对齐的情况，你可以放心设置`--test_convert_precision false`。
|
||||
- 提示：多模态模型请关注`mean_diff (with loss)`字段，`mean_diff`因包含图像tokens且该部分不计算损失，有较大的diff。
|
||||
|
||||
|
||||
全参数权重：
|
||||
```shell
|
||||
# safetensors -> torch_dist
|
||||
CUDA_VISIBLE_DEVICES=0,1,2,3 \
|
||||
NPROC_PER_NODE=4 \
|
||||
megatron export \
|
||||
--model Qwen/Qwen3-30B-A3B-Instruct-2507 \
|
||||
--output_dir Qwen3-30B-A3B-Instruct-2507-mcore \
|
||||
--to_mcore true \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--expert_model_parallel_size 2 \
|
||||
--pipeline_model_parallel_size 2 \
|
||||
--test_convert_precision true
|
||||
```
|
||||
|
||||
```shell
|
||||
# torch_dist -> safetensors
|
||||
CUDA_VISIBLE_DEVICES=0,1,2,3 \
|
||||
NPROC_PER_NODE=4 \
|
||||
megatron export \
|
||||
--mcore_model Qwen3-30B-A3B-Instruct-2507-mcore \
|
||||
--output_dir Qwen3-30B-A3B-Instruct-2507-hf \
|
||||
--to_hf true \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--expert_model_parallel_size 2 \
|
||||
--pipeline_model_parallel_size 2 \
|
||||
--test_convert_precision true
|
||||
```
|
||||
|
||||
|
||||
|
||||
LoRA权重：
|
||||
```shell
|
||||
# torch_dist -> safetensors
|
||||
# 若你需要进行merge-lora，并测试merge-lora后的精度对齐，你只需要设置`--merge_lora true`即可
|
||||
# 你也可以将`--model safetensors-path`修改为`--mcore_model torch-dist-path`。这两种方式是等价的，mcore-bridge会自动处理。
|
||||
CUDA_VISIBLE_DEVICES=0,1,2,3 \
|
||||
NPROC_PER_NODE=4 \
|
||||
megatron export \
|
||||
--model Qwen/Qwen3-30B-A3B-Instruct-2507 \
|
||||
--mcore_adapter megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx \
|
||||
--output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-lora \
|
||||
--merge_lora false \
|
||||
--to_hf true \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--expert_model_parallel_size 2 \
|
||||
--pipeline_model_parallel_size 2 \
|
||||
--test_convert_precision true
|
||||
```
|
||||
|
||||
```shell
|
||||
# safetensors -> torch_dist
|
||||
CUDA_VISIBLE_DEVICES=0,1,2,3 \
|
||||
NPROC_PER_NODE=4 \
|
||||
megatron export \
|
||||
--model Qwen/Qwen3-30B-A3B-Instruct-2507 \
|
||||
--adapters megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-lora \
|
||||
--output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-mcore \
|
||||
--merge_lora false \
|
||||
--to_mcore true \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--expert_model_parallel_size 2 \
|
||||
--pipeline_model_parallel_size 2 \
|
||||
--test_convert_precision true
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 使用代码
|
||||
|
||||
请查看[mcore-bridge github](https://github.com/modelscope/mcore-bridge/blob/main/README_zh.md#-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B)
|
||||
@@ -0,0 +1,191 @@
|
||||
# 多模态模型
|
||||
|
||||
ms-swift引入了Megatron的并行技术来加速多模态大模型的训练。目前支持Qwen3-VL, Qwen3-Omni, InternVL3.5, GLM4.5v, Kimi-VL等模型的CPT/SFT/GRPO/DPO/KTO/RM。完整支持的模型可以参考[支持的模型与数据集文档](../Instruction/Supported-models-and-datasets.md)。
|
||||
|
||||
环境准备请参考Megatron-SWIFT的[快速开始文档](./Quick-start.md)。
|
||||
|
||||
## Dense模型
|
||||
|
||||
这里介绍使用2卡80GiB A100对Qwen2.5-VL-7B-Instruct模型进行Latex-OCR的微调，分别使用全参数和LoRA的方式，以下最佳实践可以在10分钟内完成。
|
||||
|
||||
### Full
|
||||
|
||||
全参数训练脚本如下：
|
||||
```shell
|
||||
# 2 * 72GiB; 4.1s/it
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
MAX_PIXELS=1003520 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--model Qwen/Qwen2.5-VL-7B-Instruct \
|
||||
--save_safetensors true \
|
||||
--dataset 'AI-ModelScope/LaTeX_OCR:human_handwrite#5000' \
|
||||
--load_from_cache_file true \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--sequence_parallel true \
|
||||
--packing true \
|
||||
--freeze_llm false \
|
||||
--freeze_vit true \
|
||||
--freeze_aligner true \
|
||||
--split_dataset_ratio 0.01 \
|
||||
--micro_batch_size 1 \
|
||||
--global_batch_size 4 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 1e-5 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-6 \
|
||||
--num_train_epochs 1 \
|
||||
--output_dir megatron_output/Qwen2.5-VL-7B-Instruct \
|
||||
--save_steps 200 \
|
||||
--max_length 2048 \
|
||||
--dataloader_num_workers 4 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--dataset_num_proc 8
|
||||
```
|
||||
|
||||
|
||||
### LoRA
|
||||
|
||||
LoRA训练脚本如下：
|
||||
```shell
|
||||
# 2 * 23GiB; 2.3s/it
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
MAX_PIXELS=1003520 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--model Qwen/Qwen2.5-VL-7B-Instruct \
|
||||
--save_safetensors true \
|
||||
--merge_lora false \
|
||||
--dataset 'AI-ModelScope/LaTeX_OCR:human_handwrite#5000' \
|
||||
--load_from_cache_file true \
|
||||
--tuner_type lora \
|
||||
--lora_rank 8 \
|
||||
--lora_alpha 32 \
|
||||
--target_modules all-linear \
|
||||
--tensor_model_parallel_size 1 \
|
||||
--sequence_parallel true \
|
||||
--freeze_llm false \
|
||||
--freeze_vit true \
|
||||
--freeze_aligner true \
|
||||
--packing true \
|
||||
--split_dataset_ratio 0.01 \
|
||||
--micro_batch_size 1 \
|
||||
--global_batch_size 4 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 1e-4 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-5 \
|
||||
--num_train_epochs 1 \
|
||||
--output_dir megatron_output/Qwen2.5-VL-7B-Instruct \
|
||||
--save_steps 200 \
|
||||
--max_length 2048 \
|
||||
--dataloader_num_workers 4 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--dataset_num_proc 8
|
||||
```
|
||||
|
||||
|
||||
最后，我们使用生成的HF格式权重对验证集进行推理：
|
||||
```shell
|
||||
MAX_PIXELS=1003520 \
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--adapters megatron_output/Qwen2.5-VL-7B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
--attn_impl flash_attn \
|
||||
--stream true \
|
||||
--load_data_args true \
|
||||
--temperature 0 \
|
||||
--max_new_tokens 512
|
||||
```
|
||||
|
||||
推理结果如下：
|
||||
```
|
||||
[QUERY] Using LaTeX to perform OCR on the image.
|
||||
[LABELS] \forall x \in X , ( \alpha f ) ( x ) = \alpha f ( x )
|
||||
[RESPONSE] \forall x \in X , ( \alpha f ) ( x ) = \alpha f ( x )
|
||||
--------------------------------------------------
|
||||
[QUERY] Using LaTeX to perform OCR on the image.
|
||||
[LABELS] \pi \int _ { c } ^ { d } \{ g ( y ) \} ^ { 2 } d y
|
||||
[RESPONSE] \pi \int _ { c } ^ { d } \{ g ( y ) \} ^ { 2 } d y
|
||||
--------------------------------------------------
|
||||
[QUERY] Using LaTeX to perform OCR on the image.
|
||||
[LABELS] [ \frac 2 3 x ^ { \frac 3 2 } ] _ { 0 } ^ { 1 }
|
||||
[RESPONSE] [ \frac 2 3 x ^ { \frac 3 2 } ] _ { 0 } ^ { 1 }
|
||||
```
|
||||
|
||||
|
||||
## Moe模型
|
||||
|
||||
|
||||
训练脚本：
|
||||
```bash
|
||||
# 2 * 43GiB, 8s/it
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--model OpenGVLab/InternVL3_5-30B-A3B \
|
||||
--save_safetensors true \
|
||||
--merge_lora false \
|
||||
--dataset 'AI-ModelScope/LaTeX_OCR:human_handwrite#5000' \
|
||||
--load_from_cache_file true \
|
||||
--tuner_type lora \
|
||||
--lora_rank 8 \
|
||||
--lora_alpha 32 \
|
||||
--target_modules all-linear \
|
||||
--sequence_parallel true \
|
||||
--freeze_llm false \
|
||||
--freeze_vit true \
|
||||
--freeze_aligner true \
|
||||
--packing true \
|
||||
--split_dataset_ratio 0.01 \
|
||||
--expert_model_parallel_size 2 \
|
||||
--moe_permute_fusion true \
|
||||
--moe_grouped_gemm true \
|
||||
--moe_shared_expert_overlap true \
|
||||
--moe_aux_loss_coeff 1e-3 \
|
||||
--micro_batch_size 1 \
|
||||
--global_batch_size 4 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 1e-4 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-5 \
|
||||
--num_train_epochs 1 \
|
||||
--output_dir megatron_output/InternVL3_5-30B-A3B \
|
||||
--eval_steps 200 \
|
||||
--save_steps 200 \
|
||||
--max_length 2048 \
|
||||
--dataloader_num_workers 8 \
|
||||
--dataset_num_proc 8 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--attention_backend flash
|
||||
```
|
||||
|
||||
训练结束后，我们使用生成的HF格式权重对验证集进行推理：
|
||||
```shell
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--adapters megatron_output/InternVL3_5-30B-A3B/vx-xxx/checkpoint-xxx \
|
||||
--attn_impl flash_attn \
|
||||
--stream true \
|
||||
--load_data_args true \
|
||||
--temperature 0 \
|
||||
--max_new_tokens 512
|
||||
```
|
||||
@@ -0,0 +1,267 @@
|
||||
|
||||
# 快速开始
|
||||
|
||||
ms-swift引入了Megatron的并行技术来加速大模型的训练，包括数据并行、张量并行、流水线并行、序列并行，上下文并行，专家并行。支持Qwen3、Qwen3.5、Deepseek-R1、GLM4.5、GPT-OSS等模型的CPT/SFT/GRPO/DPO/KTO/RM。完整支持的模型可以参考[支持的模型与数据集文档](../Instruction/Supported-models-and-datasets.md)。
|
||||
|
||||
|
||||
| 方法 | 全参数 | LoRA | MoE | 多模态 | FP8 |
|
||||
| ------ | ------ | ---- | ----- | ----- | ----- |
|
||||
| 预训练 | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
| [指令监督微调](https://github.com/modelscope/ms-swift/tree/main/examples/megatron) | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
| [GRPO](https://github.com/modelscope/ms-swift/tree/main/examples/megatron/grpo) | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
| [GKD](https://github.com/modelscope/ms-swift/tree/main/examples/megatron/rlhf/gkd) | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
| [DPO](https://github.com/modelscope/ms-swift/tree/main/examples/megatron/rlhf/dpo) | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
| [KTO](https://github.com/modelscope/ms-swift/tree/main/examples/megatron/rlhf/kto) | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
| [RM](https://github.com/modelscope/ms-swift/tree/main/examples/megatron/rlhf/rm) | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
| [Embedding](https://github.com/modelscope/ms-swift/tree/main/examples/megatron/embedding) | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
| [Reranker](https://github.com/modelscope/ms-swift/tree/main/examples/megatron/reranker) | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
| [序列分类](https://github.com/modelscope/ms-swift/tree/main/examples/megatron/seq_cls) | ✅ | ✅| ✅ | ✅ | ✅ |
|
||||
|
||||
|
||||
## 环境准备
|
||||
使用Megatron-SWIFT，除了安装swift依赖外，还需要安装以下内容：
|
||||
|
||||
```shell
|
||||
# transformer_engine
|
||||
# 若出现安装错误，可以参考该issue解决: https://github.com/modelscope/ms-swift/issues/3793
|
||||
pip install --no-build-isolation transformer-engine[pytorch] --no-cache-dir
|
||||
# cuda13
|
||||
pip install pybind11
|
||||
pip install git+https://github.com/NVIDIA/TransformerEngine.git@stable --no-build-isolation
|
||||
|
||||
# apex
|
||||
# 提示：Megatron-SWIFT可以在不含apex的环境下运行，额外设置`--gradient_accumulation_fusion false`即可。
|
||||
git clone https://github.com/NVIDIA/apex
|
||||
cd apex
|
||||
pip install -v --disable-pip-version-check --no-cache-dir --no-build-isolation --config-settings "--build-option=--cpp_ext" --config-settings "--build-option=--cuda_ext" ./
|
||||
|
||||
# mcore-bridge
|
||||
pip install mcore-bridge -U
|
||||
# 安装main分支
|
||||
# pip install git+https://github.com/modelscope/mcore-bridge.git
|
||||
|
||||
# 若使用多机训练，请额外设置`MODELSCOPE_CACHE`环境变量为共享存储路径
|
||||
# 这将确保数据集缓存共享，而加速预处理速度。
|
||||
# 注意：这步很关键，不然多机训练可能因随机性问题导致数据不一致而训练卡住。
|
||||
export MODELSCOPE_CACHE='/xxx/shared'
|
||||
|
||||
# flash_attn
|
||||
# 选择合适的版本进行安装：https://github.com/Dao-AILab/flash-attention/releases/tag/v2.8.3
|
||||
# 注意：请勿安装高于transformer_engine限制的最高版本：https://github.com/NVIDIA/TransformerEngine/blob/release_v2.10/transformer_engine/pytorch/attention/dot_product_attention/utils.py#L118
|
||||
MAX_JOBS=8 pip install "flash-attn==2.8.3" --no-build-isolation
|
||||
```
|
||||
|
||||
或者你也可以使用镜像：（历史镜像查看[这里](../GetStarted/SWIFT-installation.md#镜像)）
|
||||
```
|
||||
# cu128
|
||||
modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.10.0-vllm0.17.1-modelscope1.34.0-swift4.0.3
|
||||
modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.10.0-vllm0.17.1-modelscope1.34.0-swift4.0.3
|
||||
modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.10.0-vllm0.17.1-modelscope1.34.0-swift4.0.3
|
||||
|
||||
# cu129 (fp8 training)
|
||||
modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3
|
||||
modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3
|
||||
modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3
|
||||
|
||||
# cu130 (fp8 training)
|
||||
modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.37.1-swift4.3.2
|
||||
modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.37.1-swift4.3.2
|
||||
modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.37.1-swift4.3.2
|
||||
```
|
||||
|
||||
推荐运行环境：
|
||||
| | 范围 | 推荐 | 备注 |
|
||||
|--------------|--------------|-------------|--------------------|
|
||||
| python | >=3.10 | 3.12 | |
|
||||
| cuda | | cuda12.8/13.0 | |
|
||||
| torch | >=2.0 | 2.8.0/2.11.0 | |
|
||||
| transformer-engine | >=2.3 | 2.16.0 | |
|
||||
| apex | | 0.1 | |
|
||||
| megatron-core | >=0.16,<0.20 | 0.17.1 | |
|
||||
| mcore-bridge | >=1.3.0 | 1.5.0 | |
|
||||
| flash-attn | | 2.8.3/4.0.0b15 | |
|
||||
| transformers | >=4.33 | 4.57.6/5.12.1 | |
|
||||
| modelscope | >=1.23 | | |
|
||||
| peft | >=0.11,<0.20 | | LoRA |
|
||||
| trl | >=0.15,<1.0 | | RLHF |
|
||||
|
||||
|
||||
## 快速入门案例
|
||||
|
||||
这里介绍使用2卡80GiB A100对Qwen2.5-7B-Instruct模型进行自我认知微调的快速入门案例，以下最佳实践可以在10分钟内完成。
|
||||
|
||||
### 传统方式
|
||||
|
||||
首先，我们需要将HF格式的权重转为Megatron格式：
|
||||
- 多卡权重转换：将`CUDA_VISIBLE_DEVICES=0`删除即可使用多卡权重转换。
|
||||
- 转换精度测试：`--test_convert_precision true`将测试转换精度。在MoE大型模型的转换时，该参数所需时间较长，且需要更多的内存消耗，可酌情去除。
|
||||
|
||||
```shell
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift export \
|
||||
--model Qwen/Qwen2.5-7B-Instruct \
|
||||
--to_mcore true \
|
||||
--torch_dtype bfloat16 \
|
||||
--output_dir Qwen2.5-7B-Instruct-mcore \
|
||||
--test_convert_precision true
|
||||
```
|
||||
|
||||
然后，使用以下脚本进行训练，训练所需显存资源为2*80GiB：
|
||||
- 若使用多机训练，建议共享磁盘，并将`--output_dir`指定为相同的路径。
|
||||
```shell
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--mcore_model Qwen2.5-7B-Instruct-mcore \
|
||||
--save_safetensors false \
|
||||
--dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \
|
||||
'AI-ModelScope/alpaca-gpt4-data-en#500' \
|
||||
'swift/self-cognition#500' \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--sequence_parallel true \
|
||||
--micro_batch_size 16 \
|
||||
--global_batch_size 16 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 1e-5 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-6 \
|
||||
--num_train_epochs 1 \
|
||||
--output_dir megatron_output/Qwen2.5-7B-Instruct \
|
||||
--save_steps 100 \
|
||||
--max_length 2048 \
|
||||
--system 'You are a helpful assistant.' \
|
||||
--dataloader_num_workers 4 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--dataset_num_proc 4 \
|
||||
--model_author swift \
|
||||
--model_name swift-robot
|
||||
```
|
||||
|
||||
最后，将Megatron格式权重转为HF格式：
|
||||
- 注意：`--mcore_model`请指向`iter_xxx`的上级目录。默认会使用`latest_checkpointed_iteration.txt`中对应的checkpoint。
|
||||
- 若出现OOM，将`CUDA_VISIBLE_DEVICES=0`删除。若出现内存不足，请将`--test_convert_precision true`删除。
|
||||
```shell
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift export \
|
||||
--mcore_model megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
--to_hf true \
|
||||
--torch_dtype bfloat16 \
|
||||
--output_dir megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx-hf \
|
||||
--test_convert_precision true
|
||||
```
|
||||
|
||||
我们对生成的HF格式权重进行推理：
|
||||
```shell
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--model megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx-hf \
|
||||
--stream true \
|
||||
--temperature 0 \
|
||||
--max_new_tokens 2048
|
||||
```
|
||||
|
||||
推理结果如下：
|
||||
```
|
||||
<<< who are you?
|
||||
I am a language model developed by swift, you can call me swift-robot. How can I assist you?
|
||||
```
|
||||
|
||||
Megatron Ray 训练，参考[Ray 文档](../Instruction/Ray.md)
|
||||
|
||||
### Mcore-Bridge【推荐】
|
||||
|
||||
Mcore-Bridge去除模型转换的繁琐过程。具体参考[Mcore-Bridge文档](./Mcore-Bridge.md)。
|
||||
|
||||
训练脚本：
|
||||
```bash
|
||||
PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
|
||||
NPROC_PER_NODE=2 \
|
||||
CUDA_VISIBLE_DEVICES=0,1 \
|
||||
megatron sft \
|
||||
--model Qwen/Qwen2.5-7B-Instruct \
|
||||
--save_safetensors true \
|
||||
--dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \
|
||||
'AI-ModelScope/alpaca-gpt4-data-en#500' \
|
||||
'swift/self-cognition#500' \
|
||||
--tensor_model_parallel_size 2 \
|
||||
--sequence_parallel true \
|
||||
--micro_batch_size 16 \
|
||||
--global_batch_size 16 \
|
||||
--recompute_granularity full \
|
||||
--recompute_method uniform \
|
||||
--recompute_num_layers 1 \
|
||||
--finetune true \
|
||||
--cross_entropy_loss_fusion true \
|
||||
--lr 1e-5 \
|
||||
--lr_warmup_fraction 0.05 \
|
||||
--min_lr 1e-6 \
|
||||
--num_train_epochs 1 \
|
||||
--output_dir megatron_output/Qwen2.5-7B-Instruct \
|
||||
--save_steps 100 \
|
||||
--max_length 2048 \
|
||||
--system 'You are a helpful assistant.' \
|
||||
--dataloader_num_workers 4 \
|
||||
--no_save_optim true \
|
||||
--no_save_rng true \
|
||||
--dataset_num_proc 4 \
|
||||
--model_author swift \
|
||||
--model_name swift-robot
|
||||
```
|
||||
|
||||
我们对生成的safetensors格式权重进行推理：
|
||||
```shell
|
||||
CUDA_VISIBLE_DEVICES=0 \
|
||||
swift infer \
|
||||
--model megatron_output/Qwen2.5-7B-Instruct/vx-xxx/checkpoint-xxx \
|
||||
--stream true \
|
||||
--temperature 0 \
|
||||
--max_new_tokens 2048
|
||||
```
|
||||
|
||||
- 若要进行预训练，你可以使用`megatron pt`替代`megatron sft`，这将会使用生成式的template进行训练。
|
||||
- Megatron-SWIFT使用与ms-swift相同的dataset和template处理模块，因此同样支持packing、loss_scale、agent训练等技术。自定义数据集格式参考[自定义数据集文档](../Customization/Custom-dataset.md)。
|
||||
- **更多案例**：包括packing、多机、32K上下文、DPO、MoE模型、预训练，可以查看[这里](https://github.com/modelscope/ms-swift/tree/main/examples/megatron)。
|
||||
|
||||
|
||||
## 训练技巧
|
||||
- 增加训练吞吐量方法：使用packing（不要开启流式）、增加DP、减少重计算、增加计算通信overlap。MoE还可以通过丢弃tokens加速。
|
||||
- 并行技术选择：
|
||||
- Megatron-SWIFT的并行技术采用zero1（默认开启use_distributed_optimizer）+各种并行技术的组合。
|
||||
- DP的速度最快，但显存占用较多，使用其他并行技术以降低显存占用。
|
||||
- TP/EP通信量较大，尽量不跨节点（NVLink域内），跨节点建议使用PP/DP；专家层建议使用EP而不是ETP，ETP更节约显存，但速度较慢。
|
||||
- MoE 并行折叠：MoE 相关的并行组与 Dense 组分离。Attention使用 tp-cp-dp-pp 组，MoE 使用 etp-ep-dp-pp 组。
|
||||
- 权重转换并行数的选择：Megatron-SWIFT在mcore端使用torch_dist存储格式，训练时可以调整并行数，不需要在权重转化时指定并行数。
|
||||
- 关于日志打印：Megatron-SWIFT的日志在last rank进行打印，因为在PP并行中，只有last pp_rank拥有完整的信息。
|
||||
|
||||
## Benchmark
|
||||
|
||||
使用`megatron sft`和`swift sft`在单机八卡A800环境下进行Dense模型全参数8K上下文训练的速度对比如下：（[shell](https://github.com/modelscope/ms-swift/blob/main/examples/megatron/benchmark/deepspeed.sh)）
|
||||
|
||||
**Dense** Qwen2.5-14B:
|
||||
|
||||
| | Megatron-LM | Deepspeed-ZeRO2 | Deepspeed-ZeRO3 |
|
||||
| -------- | ----------- | ---------- | ---------- |
|
||||
| 训练速度 | 9.04s/it | 10.32s/it | 10.56s/it |
|
||||
| 显存占用 | 8\*64GB | 8\*80GB | 8\*58GB |
|
||||
|
||||
使用`megatron sft`和`swift sft`在双机16卡A800环境下进行MoE模型全参数8K上下文训练的速度对比如下：
|
||||
|
||||
**MoE** Qwen3-30B-A3B:
|
||||
|
||||
- 注意：其中，DeepSpeed测试结果在"transformers<5.0"环境下进行。在"transformers>5.0"，可以通过`--experts_impl grouped_mm`加速训练。
|
||||
|
||||
| | Megatron-LM | DeepSpeed-ZeRO2 | DeepSpeed-ZeRO3 |
|
||||
| -------- | ----------- | --------------- | --------------- |
|
||||
| 训练速度 | 9.6s/it | - | 91.2s/it |
|
||||
| 显存使用 | 16 * 60GiB | OOM | 16 * 80GiB |
|
||||
|
||||
|
||||
## Megatron-SWIFT微信群
|
||||
|
||||
<img src="https://raw.githubusercontent.com/modelscope/ms-swift/main/docs/resources/wechat/megatron.png" width="250">
|
||||
Reference in New Issue
Block a user