LLaMA-Factory MoE微调实战指南：3种配置跑通Qwen3-30B-A3B

LLaMA-Factory MoE微调实战指南：3种配置跑通Qwen3-30B-A3B

【免费下载链接】LlamaFactoryUnified Efficient Fine-Tuning of 100+ LLMs & VLMs (ACL 2024)项目地址: https://gitcode.com/GitHub_Trending/ll/LlamaFactory

想在单卡上微调 Qwen3-30B-A3B，第一步 forward 就 OOM？这篇指南给你 LLaMA-Factory 跑 MoE 指令微调的 3 套真实配置：1×80GB 单卡 LoRA、8×78GB 全量专家并行、昇腾 NPU 全量——同一份数据集，硬件需求从 16 张卡压到 1 张卡。路线：先跑通 → 看懂原理 → 按你的硬件对号入座。

⚡ 3分钟跑通：不写任何 MoE 专属代码

MoE 模型在 LLaMA-Factory 里没有独立入口——改一行model_name_or_path就行，框架检测到 MoE 类型的model_type后会自动处理路由参数。先装环境：

git clone https://gitcode.com/GitHub_Trending/ll/LLaMA-Factory cd LLaMA-Factory pip install -e .

装完直接复用官方 LoRA 示例把流程跑通（这个配置基于 Qwen3-4B 稠密模型，目的是先验证环境）：

python src/train.py --config examples/train_lora/qwen3_lora_sft.yaml

看到 loss 稳定下降后，把配置里的模型换成 MoE 版本即可：

### model model_name_or_path: Qwen/Qwen3-30B-A3B-Instruct-2507 trust_remote_code: true moe_aux_loss_coef: 0.01 # 专家路由辅助损失系数，下面细讲 ### method stage: sft do_train: true finetuning_type: lora lora_rank: 8 lora_target: all ### train per_device_train_batch_size: 1 gradient_accumulation_steps: 8 learning_rate: 1.0e-4 bf16: true

上面这份是在 examples/train_lora/qwen3_lora_sft.yaml 基础上改出来的。关键点：MoE 模型的lora_target直接写all，不用手动去数专家层叫什么名字；新增的moe_aux_loss_coef是 MoE 训练唯一必看的参数。

🧩 背后原理：路由器分活，辅助损失防偏科

MoE 把 FFN 层拆成 N 个专家，每个 token 只由路由器（一个线性层 + softmax）挑出 top-k 个专家处理——Qwen3-30B-A3B 的 30B 参数里每次只激活约 3B，这就是它"大参数、小算力"的来源。但路由器会偷懒：训练久了总想把 token 都塞给少数几个专家，最后负载失衡、其他专家"饿死"。

LLaMA-Factory 的做法很直接：你在配置里写的moe_aux_loss_coef，会被 src/llamafactory/model/model_utils/moe.py 里的configure_moe按模型家族映射到对应位置——Mixtral、Qwen2/3-MoE、Llama4 写到router_aux_loss_coef，DeepSeek 写到aux_loss_alpha，JetMoe 写到aux_loss_coef，你不用关心每个模型的字段差异。同一文件里的add_z3_leaf_module还会把专家块注册成 DeepSpeed ZeRO-3 的 leaf module，避免专家参数被过度切分拖慢速度。

🎛 核心配置：4个键决定成败

逐个说人话：

• moe_aux_loss_coef：给路由器的"负载均衡罚分"，太小专家会偏科，太大会压制正常学习，0.01 是安全起点。
• lora_target: all：稠密模型常只打 q_proj/v_proj，但 MoE 的专家 MLP 才是知识所在，必须全部注入。
• expert_model_parallel_size：30B 模型的 128 个专家塞不进一张卡，EP=2 就是把专家两两拆开分摊。
• moe_grouped_gemm：把多个小专家矩阵拼成一次分组 GEMM，比逐专家串行快很多，全量训练不开它 GPU 利用率会很难看。

📉 三种硬件，三套打法

1×80GB 单卡：KTransformers 把专家甩到 CPU

显存只够放"非专家权重 + 激活值"时，用 KTransformers 把 INT8 量化后的专家权重放 CPU，LoRA 只更新 GPU 上的小参数：

use_kt: true kt_weight_path: /path/to/routed-int8-experts kt_non_expert_weight_path: /path/to/bf16-non-expert-cache kt_config: kt_expert_weight_format: int8 kt_backend: auto kt_num_threads: 96 kt_tp_enabled: true

这段取自 examples/ktransformers/train_lora/deepseek_v3_int8_lora_sft_kt.yaml，DeepSeek-V3 这种 671B 级模型也是同一套方案。配套文档见 docs/zh/advanced/ktransformers.md。

8×78GB 多卡：Megatron 专家并行全量

要动全部参数就上 examples/megatron/qwen3_moe_full.yaml 的组合，核心几行：

model_name_or_path: Qwen/Qwen3-30B-A3B-Instruct-2507 stage: sft finetuning_type: full tensor_model_parallel_size: 1 pipeline_model_parallel_size: 4 expert_model_parallel_size: 2 # 专家均分到2组卡 moe_grouped_gemm: true # 分组GEMM提速专家计算 moe_token_dispatcher_type: alltoall recompute_granularity: full # 全重算换显存

这是官方给出的 8×78GB 全量微调基准配置，注释里写明了目标显存档位。学习率给到 3e-6，全量微调 MoE 别用稠密模型的 1e-5 起步。

昇腾 NPU 或普通多卡：FSDP 全量

没有 Megatron 环境就退一档，参考 examples/ascend/qwen3moe_full_sft_fsdp.yaml：finetuning_type: full配 FSDP 启动，保留梯度检查点，cutoff_len 从 1024 起步先验证再拉长。

📊 显存与吞吐对照（Qwen3-30B-A3B SFT，cutoff 2048）

数据为典型参考值，实际以你的数据和卡型实测为准。规律很直白：同样能力档位，MoE 把"全量微调"的硬件门槛从 16 卡拉回到 8 卡，LoRA 路线再砍到 1 卡。

🔍 卡住了先查这三处

第一步 forward 就 OOM

• 症状：loss 还没打出来，显存直接爆
• 原因：MoE 专家参数大，普通 ZeRO-3 没切分专家块
• 解法：挂--deepspeed examples/deepspeed/ds_z3_config.json，或直接切到上面 Megatron / KTransformers 路线

loss 先降后升，训到一半飞掉

• 症状：几百步后 loss 跳涨、grad_norm 飙升
• 原因：没加moe_aux_loss_coef，路由偏科导致个别专家梯度爆炸
• 解法：加moe_aux_loss_coef: 0.01；仍不稳就把learning_rate降到 5e-6 并保留warmup_ratio: 0.1

GPU 利用率在 0~30% 之间抖

• 症状：显存够但 step 时间远超预期
• 原因：全量训练时专家串行计算 + 数据加载瓶颈
• 解法：开moe_grouped_gemm: true，dataloader_num_workers提到 4、preprocessing_num_workers提到 16，参考官方示例的默认值

收尾

一句话：MoE 微调在 LLaMA-Factory 里就是"换一行模型名 + 一个路由系数"，剩下的按硬件选 KTransformers、ZeRO-3 或 Megatron 三条路之一。关键入口都在仓库里：src/llamafactory/model/model_utils/moe.py、examples/megatron/qwen3_moe_full.yaml、examples/ktransformers/train_lora/deepseek_v3_int8_lora_sft_kt.yaml。新加的 v1 训练管线也已内置 Triton 分组 GEMM 与 CUDA 融合 MoE 核，跑通基础流程后值得切过去试试吞吐。

【免费下载链接】LlamaFactoryUnified Efficient Fine-Tuning of 100+ LLMs & VLMs (ACL 2024)项目地址: https://gitcode.com/GitHub_Trending/ll/LlamaFactory