ms-swift Megatron-SWIFT 实战：DeepSeek-V4 微调训练、精度对齐与 FP8/vLLM 部署全流程

ms-swift Megatron-SWIFT 实战DeepSeek-V4 微调训练、精度对齐与 FP8/vLLM 部署全流程【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift本文基于 ms-swift 官方最佳实践文档 deepseek-v4.md完整讲解如何在 Megatron-SWIFT 中完成 DeepSeek-V4 模型的 SFT/LoRA 微调与强化学习训练含 MTP、FP8 特性覆盖训练前的环境装配、transformers 与 Megatron 双引擎 forward 精度对齐验证、BF16/FP8 训练参数配置、量化导出到 vLLM 推理部署的完整链路。读完本文你可以按图索骥地在单机 8 卡乃至 64 卡集群上复现 DeepSeek-V4 的 LoRA/全参数训练并产可在 vLLM 上线的 FP8 权重。1. 版本前提与环境装配Megatron-SWIFT 已支持 DeepSeek-V4 的微调与 RL 训练特性包括MTPMulti-Token Prediction与FP8训练。需要特别注意两个前置约束FP4 blockwise 训练暂不支持。加载 FP4 权重时框架会自动将其转换为 FP8/BF16因此文档中所有训练脚本实际以 FP8/BF16 数值精度运行必须使用特定分支组合Megatron-Core 的dev分支配合mcore-bridge与ms-swift的main分支。官方给出的安装命令如下文档注明 Megatron-LM 在 commitfd1121b8ff7e3a4f83a28d35aed172d7bc0260e1下完成过测试可用固定 commit 代替dev分支安装以保证可复现性pip install githttps://github.com/NVIDIA/Megatron-LM.gitdev pip install githttps://github.com/modelscope/mcore-bridge.git pip install githttps://github.com/modelscope/ms-swift.git # Megatron-LM 在该 commit hash 下经过测试验证 # pip install githttps://github.com/NVIDIA/Megatron-LM.gitfd1121b8ff7e3a4f83a28d35aed172d7bc0260e1安装后训练/导出相关的megatron命令行入口定义于 setup.py 的console_scripts中megatronswift.cli._megatron.main:cli_main。其中megatron sft最终调用 sft.py 中的megatron_sft_main()megatron export调用 export.py 中的megatron_export_main()。Megatron 相关依赖另见 requirements/megatron.txt。1.1 仓库中已注册的 DeepSeek-V4 模型从 swift/model/models/deepseek.py 的模型注册代码看当前仓库已内置以下 DeepSeek-V4 权重组architectures 为DeepseekV4ForCausalLM默认对话模板为deepseek_v4-0731/-0813版本组使用deepseek_v4_flash模板deepseek-ai/DeepSeek-V4-Flash、deepseek-ai/DeepSeek-V4-Flash-Basedeepseek-ai/DeepSeek-V4-Pro、deepseek-ai/DeepSeek-V4-Pro-Basedeepseek-ai/DeepSeek-V4-Flash-0731、deepseek-ai/DeepSeek-V4-Pro-0813本文的训练示例以DeepSeek-V4-Flash对话版与DeepSeek-V4-Flash-Base基座版为主。2. 训练前的精度对齐验证在进入正式训练之前官方文档强烈建议先做一次transformers 与 Megatron 两条推理路径的 forward 精度对齐测试。对于 DeepSeek-V4 这类采用稀疏注意力DSA变体与混合 dense/MoE 结构的模型权重转换Hugging Face safetensors → Megatron-Core 格式涉及大量重排与量化反量化任何一处 key 映射错位都会在训练初期表现为 loss 异常。2.1 解除 FP32 对齐测试的限制对齐测试需要以 FP32 精度前向。文档指出需注释掉 Megatron-LMdev分支中megatron/core/transformer/experimental_attention_variant/dsa.py文件第 4143 行该位置为 DSA 注意力路径中阻碍 FP32 前向的语句。修改的是你本地安装的 Megatron-LM 源码不影响 ms-swift 仓库本身。2.2 构造 4 层 mini 模型为加速对齐测试官方脚本会把原始权重裁剪为只含前 4 个 transformer 层的 mini 模型。脚本基于mcore_bridge.utils提供的SafetensorLazyLoader、Fp8Dequantizer、StreamingSafetensorSaver三个工具类实现要点如下SafetensorLazyLoader懒加载 safetensors配合下方 monkey patch 后的_open_file支持按需懒下载文件不在本地时回落到model_file_download逐文件拉取到tmp/目录遍历 state_dict 时丢弃layers.下索引 4的张量只保留前 4 层丢弃所有.scale量化 scale 张量对存在对应.scale的.weight即 FP8 量化权重用Fp8Dequantizer.convert(...)反量化并转成 BF16最终通过StreamingSafetensorSaver流式写回模型目录。完整脚本与文档一致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 deepseek-ai/DeepSeek-V4-Flash-Base # 部分模型前几层是 dense、其余是 MoE按实际结构设置该值 model_dir safe_snapshot_download(model_id, download_modelFalse) loader SafetensorLazyLoader(model_dir) state_dict loader.get_state_dict() saver StreamingSafetensorSaver(save_dirmodel_dir) 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_idmodel_id, file_pathfilename, local_dirtmp_dir, ) self._file_handles[filename] safe_open(file_path, frameworkpt) return self._file_handles[filename] SafetensorLazyLoader._open_file _open_file # monkey patch懒下载 new_state_dict {} for k, v in state_dict.items(): if k.startswith(layers.): idx int(k[len(layers.):].split(., 1)[0]) if idx 4: continue if k.endswith(.scale): continue elif k.endswith(.weight): weight_scale_inv k.replace(.weight, .scale) 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.jsonnum_hidden_layers改为4compress_ratios改为[0, 0, 4, 128, 0]删除quantization_config字段mini 模型以 BF16 运行与对齐测试的 FP32 前向保持一致。2.3 运行对齐测试创建test.py以 4 卡并行运行CUDA_VISIBLE_DEVICES0,1,2,3 torchrun --nproc_per_node4 test.py并行拓扑刻意设置为 PP2、EP2 的组合同时覆盖 pipeline 切分pipeline_model_parallel_layout与 MTP 层的权重转换import os os.environ[SWIFT_TEST_CONVERT_PRECISION] 1 from swift.megatron import MegatronExportArguments, megatron_export_main from swift import safe_snapshot_download model_id deepseek-ai/DeepSeek-V4-Flash-Base model_dir safe_snapshot_download(model_id, download_modelFalse) if __name__ __main__: megatron_export_main( MegatronExportArguments( modelmodel_dir, to_mcoreTrue, attention_backendflash, tensor_model_parallel_size1, pipeline_model_parallel_layoutEt*3|t*1mL, pipeline_model_parallel_size2, expert_model_parallel_size2, mtp_num_layers1, test_convert_precisionTrue, ))pipeline_model_parallel_layout与mtp_num_layers两个参数定义于 megatron_args.py其中 layout 字符串由PipelineParallelLayerLayout.get_num_stages_from_str解析其阶段数必须能被pipeline_model_parallel_size整除见 参数校验逻辑。在源码层面该测试的落点是 convert.py导出流程会读取环境变量SWIFT_TEST_CONVERT_PRECISION这也是test.py中os.environ注入的原因并在权重转换完成后调用 convert_utils.py 中的test_convert_precision()。该函数以训练模板对同一批样例分别编码先令 Hugging Face 模型以 FP32 前向CPU offload 上下文得到 logits再令 Megatron 模型前向逐层比对输出——当看到文档给出的对齐通过截图结果时即说明 HF 与 Megatron 两条路径数值一致可以进入正式训练。需要注意 convert_utils.py 中的显式约束FP8 模型不支持 convert_precision 测试会直接抛出ValueError因此对齐验证必须在未开启 FP8 的 BF16 mini 模型上完成这也解释了第 2.2 节中“删除quantization_config、FP8 权重反量化为 BF16”的必要性。3. BF16 LoRA 训练验证对齐通过后即可启动 LoRA SFT。官方给出的 BF16 精度脚本会在训练结束后同时产出LoRA 增量权重与Merge-LoRA 后的 BF16 完整权重。单机 8 卡完整命令如下PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True \ NPROC_PER_NODE8 \ CUDA_VISIBLE_DEVICES0,1,2,3,4,5,6,7 \ megatron sft \ --model deepseek-ai/DeepSeek-V4-Flash \ --save_safetensors true \ --dataset AI-ModelScope/alpaca-gpt4-data-zh#1000 \ AI-ModelScope/alpaca-gpt4-data-en#1000 \ swift/self-cognition#1000 \ --model_author swift \ --model_name swift-robot \ --merge_lora true \ --load_from_cache_file true \ --add_non_thinking_prefix true \ --loss_scale ignore_empty_think \ --split_dataset_ratio 0.01 \ --tuner_type lora \ --lora_rank 16 \ --lora_alpha 32 \ --tensor_model_parallel_size 1 \ --expert_model_parallel_size 8 \ --micro_batch_size 4 \ --global_batch_size 32 \ --padding_free false \ --group_by_length true \ --recompute_granularity full \ --recompute_method uniform \ --recompute_num_layers 1 \ --moe_permute_fusion true \ --moe_grouped_gemm true \ --moe_shared_expert_overlap true \ --moe_aux_loss_coeff 1e-3 \ --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/DeepSeek-V4-Flash \ --eval_steps 200 \ --save_steps 200 \ --max_length 4096 \ --dataloader_num_workers 8 \ --dataset_num_proc 8 \ --no_save_optim true \ --no_save_rng true \ --sequence_parallel true \ --mtp_num_layers 1 \ --attention_backend flash关键参数按功能分组解读参数组参数说明数据与思考模型适配--dataset ...#1000、--split_dataset_ratio 0.01三个数据集各采样 1000 条1% 切分作验证集#1000为 ms-swift 数据集采样语法--add_non_thinking_prefix、--loss_scale ignore_empty_think针对 DeepSeek-V4 思考thinking机制前缀标记非思考回复loss 计算时忽略空思考内容--model_author、--model_name配合 self-cognition 数据集注入模型自我认知作者/名称调优器--tuner_type lora、--lora_rank 16、--lora_alpha 32LoRA rank 16、alpha 32--merge_lora true使训练结束后额外产出合并后的 BF16 完整权重--no_save_optim、--no_save_rng微调场景无需保存优化器/RNG 状态减小 checkpoint 体积并行策略--tensor_model_parallel_size 1、--expert_model_parallel_size 8TP1当前暂不支持 TP见第 4 节8 卡全部用于专家并行--sequence_parallel true降低序列维显存--mtp_num_layers 1开启 1 层 MTPMulti-Token Prediction联合训练批与序列--micro_batch_size 4、--global_batch_size 328 卡下全局批 4×8梯度累积 1--max_length 4096、--padding_free false、--group_by_length true单条最大 4096 token关闭 padding-free 后按长度分桶减少 padding 浪费显存优化--recompute_granularity full、--recompute_method uniform、--recompute_num_layers 1全重计算且每 1 层重算一次用算力换显存PYTORCH_CUDA_ALLOC_CONFexpandable_segments:TruePyTorch 可扩展内存段缓解碎片化MoE 优化--moe_permute_fusion、--moe_grouped_gemm、--moe_shared_expert_overlap路由 permute 融合、分组 GEMM、共享专家通信重叠--moe_aux_loss_coeff 1e-3MoE 负载均衡辅助 loss 系数数值/其他--cross_entropy_loss_fusion true、--attention_backend flash融合 CE lossflash 注意力后端--lr 1e-4、--lr_warmup_fraction 0.05、--min_lr 1e-5LoRA 典型学习率区间1e-5~1e-4--finetune true以微调语义初始化优化器训练完成后产出位于megatron_output/DeepSeek-V4-Flash/vx-xxx/下既有checkpoint-xxxLoRA 增量也有checkpoint-xxx-merged合并后 BF16 权重可直接用于后续推理见第 6 节。官方文档同时给出了该配置的显存占用截图与训练 loss 曲线可参考原文档 deepseek-v4.md 中的插图作为复现对照。4. 进阶配置PP 切分、全参数训练与 Packing/CP文档在 LoRA 章节后给出了四条重要的边界与进阶提示逐条对应源码中的参数语义4.1 流水线并行PP必须显式给出 layout启用 PP 时除--pipeline_model_parallel_size外还需设置pipeline_model_parallel_layout该参数为Optional[str]默认为空见 megatron_args.py。文档示例--pipeline_model_parallel_size 2 \ --pipeline_model_parallel_layout Et*22|t*21mL \layout 语法以|分隔各 pipeline 阶段t表示 transformer 层、E表示嵌入层、m表示 MTP 层、末尾L为输出logit/loss阶段t*22表示该阶段连续放置 22 个 transformer 层。以 8 卡 64 层规模的 Flash 模型为例2 阶段 layoutEt*22|t*21mL即把 43 个 transformer 层按 22/21 分摊到两个 stage并把 MTP 与输出头放在第二级。4.2 全参数训练64 卡参考配置全参数训练同样受支持但需要调低学习率并提高并行度。官方 64 卡示例的差异化参数--lr 1e-5 \ --min_lr 1e-6 \ --tensor_model_parallel_size 1 \ --expert_model_parallel_size 8 \ --pipeline_model_parallel_size 8 \ --pipeline_model_parallel_layout Et*5|t*5|t*6|t*6|t*6|t*5|t*5|t*5mL \即 EP8 × PP8 64 卡layout 将 44 个 transformer 层在 8 个阶段间做 5/5/6/6/6/5/5/5 的非均匀切分结合 MTP 与输出头共 45 个单元位学习率从 LoRA 的 1e-4 降一个数量级至 1e-5。4.3 Packing / 上下文并行CPPacking 与 CP 的支持依赖mcore-bridge/ms-swift的main分支对应上游 PRms-swift#9705 与 mcore-bridge#140。若使用 CP需额外设置--sequence_packing_scheduler dp_balanced \ --cp_partition_mode contiguous \前者让 packed 序列在各 DP rank 间按长度均衡分配后者指定 CP 的切分模式。4.4 TP 支持现状当前版本暂不支持张量并行TP需等待 Megatron-Core 上游支持——这正是示例中--tensor_model_parallel_size 1的原因也解释了为何 64 卡全参数方案采用 EP×PP 的并行组合而非引入 TP。5. FP8 训练与量化导出5.1 开启 FP8 训练追加以下三个参数即可开启 FP8 训练并将最终权重保存为 FP8--fp8_recipe blockwise \ --fp8_format e4m3 \ --fp8_param_gather true \fp8_recipe blockwise采用块级blockwise缩放方案与 DeepSeek-V4 原生 FP8 权重的量化粒度对齐fp8_format e4m3权重数值格式取 e4m3fp8_param_gather true参数收集阶段保留 FP8 数值。官方推荐 FP8 走全参数训练。若确实要 LoRA FP8 组合必须遵守 examples/megatron/fp8/lora.sh 头部注释所述约束FP8 精度有限LoRA delta 直接合并进 FP8 底模会被舍入为 0因此要设置--merge_lora false只保存 LoRA 权重之后基于 BF16 权重执行 Merge-LoRA该示例中的megatron export --adapters ...流程BF16 底模 --merge_lora true即为标准做法。5.2 训练后量化导出 FP8 权重对已合并的 BF16 checkpoint可用megatron export做离线量化产出 vLLM 可加载的 FP8 权重文档特别提示对 LoRA 增量做此量化会丢失增量信息此处仅为链路示例生产建议直接采用 5.1 节的 FP8 全参数训练并导出 FP8 权重CUDA_VISIBLE_DEVICES0,1,2,3,4,5,6,7 \ NPROC_PER_NODE8 \ megatron export \ --model megatron_output/DeepSeek-V4-Flash/vx-xxx/checkpoint-xxx-merged \ --output_dir megatron_output/DeepSeek-V4-Flash/vx-xxx/checkpoint-xxx-merged-FP8 \ --to_hf true \ --fp8_recipe blockwise \ --fp8_format e4m3 \ --fp8_param_gather true \ --mtp_num_layers 1 \ --expert_model_parallel_size 8其中--to_hf true表示导出为 Hugging Face safetensors 格式--mtp_num_layers 1、--expert_model_parallel_size 8必须与训练时的权重布局保持一致否则 Megatron 侧的权重切分/重排无法正确对应。6. 训练后推理与 vLLM 部署6.1 transformers 后端快速验证训练产物合并后 BF16 权重可直接用 ms-swift 推理入口验证无需量化CUDA_VISIBLE_DEVICES0,1,2,3,4,5,6,7 \ swift infer \ --model megatron_output/DeepSeek-V4-Flash/vx-xxx/checkpoint-xxx-merged \ --infer_backend transformers \ --enable_thinking false \ --max_new_tokens 2048--enable_thinking false关闭思考模式便于快速得到直接答案文档中给出的推理结果截图可作为输出形态对照self-cognition 数据集注入后模型会自称swift-robot。6.2 vLLM 上线FP4/FP8 权重文档给出 vLLM 部署的四个注意事项vLLM 侧需参考官方针对 DeepSeek-V4-Flash 的 recipe 文档且要求FP4/FP8 精度权重即 5.2 节导出的产物必须复制原始的config.json并修改expert_dtype字段与训练后 config 保持一致。原因是 transformers 的config.save_pretrained写出的文件与原文件存在差异vLLM 不兼容保存后的文件因此要以原始文件为底本仅补expert_dtype若遇到 tilelang 相关报错可参考上游 issuems-swift#9494mcore-bridge 针对 DeepSeek-V4 FP8 的修复见其上游 PRmcore-bridge#133升级 mcore-bridge main 分支可规避。vLLM 启动命令8 卡 TP 专家并行含 DeepSeek-V4 专属 tokenizer/parser 配置vllm serve megatron_output/DeepSeek-V4-Flash/vx-xxx/checkpoint-xxx-merged-FP8 \ --trust-remote-code \ --kv-cache-dtype fp8 \ --block-size 256 \ --enable-expert-parallel \ --tensor-parallel-size 8 \ --max-model-len 8192 \ --tokenizer-mode deepseek_v4 \ --tool-call-parser deepseek_v4 \ --enable-auto-tool-choice \ --reasoning-parser deepseek_v4其中--kv-cache-dtype fp8与 FP8 权重配套--tokenizer-mode deepseek_v4、--tool-call-parser deepseek_v4、--reasoning-parser deepseek_v4分别启用 DeepSeek-V4 分词器、自动工具调用与推理内容解析--enable-auto-tool-choice使服务默认开启工具选择能力。7. 小结与仓库索引整条链路可以概括为分支装配Megatron-Core dev mcore-bridge/ms-swift main→ FP32 精度对齐验证4 层 mini 模型 test_convert_precision→ BF16 LoRA 训练EP8MTP1→ 按需 FP8 全参数训练/离线量化 → transformers 验证 vLLM FP8 部署。关键能力边界TP 暂不支持、FP4 blockwise 训练不支持加载时自动转 FP8/BF16、LoRAFP8 需走 BF16 底模合并。主要仓库索引便于按图索骥深入源码模型注册swift/model/models/deepseek.pyCLI 入口swift/cli/_megatron/sft.py、swift/cli/_megatron/export.py、setup.py精度对齐实现swift/megatron/utils/convert_utils.py、swift/megatron/convert.py并行参数定义与校验swift/megatron/arguments/megatron_args.py、layout 校验FP8 LoRA 参考脚本examples/megatron/fp8/lora.sh原文档含显存/loss/对齐/推理截图docs/source_en/BestPractices/deepseek-v4.md【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考