Megatron Bridge 是 NVIDIA 提供的 Hugging Face ↔ Megatron-Core 桥梁。LlamaFactory 用它走独立的 PT / SFT 训练路径,而不是 Hugging Face Trainer。
启用方式:设置环境变量 USE_MEGATRON_BRIDGE=1。启动器会强制 FORCE_TORCHRUN=1。
USE_MEGATRON_BRIDGE=1
FORCE_TORCHRUN=1
警告
这与 USE_MCA=1 是两个后端,不要同时开启。MCA 详见 mcore_adapter。
USE_MCA=1
当前范围
pt
sft
full
lora
支持的 Hugging Face model_type:
model_type
deepseek_v3、deepseek_v4、llama、mistral、qwen2、qwen3、qwen3_5、qwen3_5_moe、qwen3_5_moe_text、qwen3_5_text、qwen3_moe、qwen3_next
deepseek_v3
deepseek_v4
llama
mistral
qwen2
qwen3
qwen3_5
qwen3_5_moe
qwen3_5_moe_text
qwen3_5_text
qwen3_moe
qwen3_next
未在上表中的模型(包括 VL / Omni)会在启动时报错。
安装
推荐先装 PyTorch 与 TransformerEngine,再安装 Megatron Bridge:
pip install --no-build-isolation transformer-engine[pytorch] pip install --no-build-isolation megatron-bridge
也可以使用 NeMo Framework 容器,或构建本仓库的 CUDA 镜像:
docker build -f docker/docker-cuda/Dockerfile.mbridge \ -t llamafactory-megatron-bridge:latest .
验证导入:
python - <<'PY' from megatron.bridge import AutoBridge print("megatron-bridge import ok") PY
APEX 的 fused_weight_gradient_mlp_cuda 是可选依赖。未安装时,LlamaFactory 会自动关闭 gradient_accumulation_fusion,训练仍可继续。
fused_weight_gradient_mlp_cuda
gradient_accumulation_fusion
快速开始
在仓库根目录执行:
USE_MEGATRON_BRIDGE=1 llamafactory-cli train examples/megatron_bridge/llama3_sft.yaml
多卡示例(8 GPU,TP=2):
CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 USE_MEGATRON_BRIDGE=1 \ llamafactory-cli train examples/megatron_bridge/llama3_sft.yaml \ tensor_model_parallel_size=2 \ sequence_parallel=true
多机与普通 llamafactory-cli train 相同,继续使用 NNODES、NODE_RANK、MASTER_ADDR、MASTER_PORT。
llamafactory-cli train
NNODES
NODE_RANK
MASTER_ADDR
MASTER_PORT
完整配置见 examples/megatron_bridge/llama3_sft.yaml。
examples/megatron_bridge/llama3_sft.yaml
并行与批大小
并行度必须整除 world_size:
world_size
TP * PP * CP * EP <= world_size world_size % (TP * PP * CP * EP) == 0 DP = world_size / (TP * PP * CP * EP)
sequence_parallel=true 要求 tensor_model_parallel_size > 1。
sequence_parallel=true
tensor_model_parallel_size > 1
全局 batch 按 Megatron 语义计算:
global_batch_size = per_device_train_batch_size * gradient_accumulation_steps * DP
训练步数:max_steps > 0 时直接作为 train_iters;否则按 num_train_epochs 和样本数推算。
max_steps > 0
train_iters
num_train_epochs
context_parallel_size > 1 时,SFT 会强制 calculate_per_token_loss=true。若同时开启 use_packed_sequences,packed 序列会按 CP * 2 对齐。
context_parallel_size > 1
calculate_per_token_loss=true
use_packed_sequences
CP * 2
配置字段
Megatron Bridge 专用参数定义在 MegatronBridgeArguments,与普通训练 YAML 写在一起即可。
MegatronBridgeArguments
并行
tensor_model_parallel_size
1
pipeline_model_parallel_size
expert_model_parallel_size
context_parallel_size
virtual_pipeline_model_parallel_size
None
sequence_parallel
false
重计算与融合
recompute_granularity
selective
recompute_method
uniform
block
recompute_num_layers
account_for_embedding_in_pipeline_split
account_for_loss_in_pipeline_split
bias_activation_fusion
apply_rope_fusion
masked_softmax_fusion
cross_entropy_loss_fusion
优化器与精度
use_distributed_optimizer
true
overlap_param_gather
overlap_grad_reduce
mixed_precision
bf16_mixed
fp8
moe_grouped_gemm
moe_token_dispatcher_type
allgather
alltoall
flex
学习率、warmup、adam_beta1 / adam_beta2、weight_decay、max_grad_norm 仍使用标准 TrainingArguments。lr_scheduler_type 仅映射 cosine、linear、constant、constant_with_warmup;其余会回退到 cosine。full / lora 的 min_lr 为 0.0。
adam_beta1
adam_beta2
weight_decay
max_grad_norm
TrainingArguments
lr_scheduler_type
cosine
linear
constant
constant_with_warmup
min_lr
0.0
数据与 checkpoint
megatron_pretrained_checkpoint
export_hf_on_finish
extra_config
extra_config: '{"train.train_iters": 5, "logger.log_interval": 1}' # 或 # extra_config: /path/to/overrides.json
数据流
LlamaFactory 仍负责数据集加载与 template。训练开始前,rank 0 会把对齐后的样本导出到 output_dir/mb_dataset/:
template
output_dir/mb_dataset/
training.jsonl
{"text": "..."}
validation.jsonl
messages
{% generation %}
SFT 会尽量使用与 Hugging Face Trainer 相同的 chat template,并为 assistant 回复注入 {% generation %},以便只对回答计算 loss。
Checkpoint
SFT 首次运行会把 Hugging Face 权重转换成 Megatron 格式,默认目录为 output_dir/megatron_pretrained/。已转换过的目录会复用。若已有 Megatron checkpoint,直接设置 megatron_pretrained_checkpoint。
output_dir/megatron_pretrained/
训练过程写入 Megatron distributed checkpoint(torch_dist):
torch_dist
output_dir/ latest_checkpointed_iteration.txt iter_XXXXXXX/ run_config.yaml ... mb_dataset/ megatron_pretrained/ # SFT 自动转换 hf_export/ # export_hf_on_finish=true
续训:保持相同 output_dir,并设置 overwrite_output_dir: false。存在 latest_checkpointed_iteration.txt 或 latest_train_state.pt 时会从该目录恢复。不要依赖 Hugging Face 的 resume_from_checkpoint 路径语义。
output_dir
overwrite_output_dir: false
latest_checkpointed_iteration.txt
latest_train_state.pt
resume_from_checkpoint
export_hf_on_finish: true 时:
export_hf_on_finish: true
output_dir/hf_export/
短跑、只对比 loss 时建议关掉导出,避免额外 checkpoint 显存开销。
LoRA
finetuning_type: lora lora_rank: 8 lora_alpha: 16
Megatron Bridge 固定作用在 linear_qkv、linear_proj、linear_fc1、linear_fc2。自定义 lora_target 会被忽略并打 warning。lora_rank / lora_alpha 会映射到 Megatron LoRA 的 dim / alpha;lora_dropout 不会传入。
linear_qkv
linear_proj
linear_fc1
linear_fc2
lora_target
lora_rank
lora_alpha
dim
alpha
lora_dropout
与 MCA 的区别
mcore_adapter
megatron-bridge
mcore-adapter
dpo
examples/megatron_bridge/
examples/megatron/
Dockerfile.mbridge
Dockerfile.megatron
限制与排障
USE_MEGATRON_BRIDGE
USE_MCA
megatron-core
helpers_cpp
make
更多上游概念见 Megatron Bridge 文档。