本课说明（2026-11-14 新编）
适用范围：与上一课相同的官方基线（Driver 4.3.7、training-suite:v2.1.5-musa-4.3.7、LLaMA-Factory v0.9.3）。环境搭建请先完成上一课。 本课依据官方文档与正式 Release 整理，未在真实 MUSA GPU 上实测；标注“官方”的命令与数值来自原文，标注“本站补充”的脚本由本站编写用于检查与教学，使用前请在自己的环境中验证。
一、怎样选择微调方式
| 方式 | 训练内容 | 特点 |
|---|---|---|
| 全参数（full） | 全部参数 | 效果上限高，显存、通信与 checkpoint 成本最大 |
| LoRA | 低秩 adapter | 显存较低、产物小、兼容性通常较好 |
| QLoRA | 量化基础模型 + LoRA | 显存更低，但依赖量化后端与硬件兼容 |
| Freeze | 只训练部分原有层 | 需要直接更新部分权重时使用 |
表格整理自 LLaMA-Factory 入门（摩尔线程文档中心）。官方建议先用少量数据和 LoRA 打通模型、模板和数据链路，再扩大数据或切换全参数。
二、LoRA：Qwen3-32B，8 卡 S5000
除 output_dir 改为简短路径外，参数与官方实战页一致，整理为 YAML：
yaml
# qwen3_32b_lora_sft.yaml
stage: sft
do_train: true
model_name_or_path: /data/models/Qwen3-32B
trust_remote_code: true
finetuning_type: lora
lora_rank: 16
lora_alpha: 32
lora_dropout: 0.05
lora_target: all
template: qwen3
enable_thinking: true
flash_attn: auto
dataset_dir: /data/datasets/llama_factory
dataset: train
cutoff_len: 2048
max_samples: 100000
preprocessing_num_workers: 16
packing: false
per_device_train_batch_size: 1
gradient_accumulation_steps: 16
learning_rate: 5.0e-5
num_train_epochs: 3.0
lr_scheduler_type: cosine
max_grad_norm: 1.0
warmup_steps: 0
optim: adamw_torch
bf16: true
logging_steps: 5
save_steps: 100
plot_loss: true
report_to: none
ddp_timeout: 180000000
include_num_input_tokens_seen: true
output_dir: saves/Qwen3-32B-Thinking/lora/sft
bash
modelscope download --model Qwen/Qwen3-32B --local_dir /data/models/Qwen3-32B
MUSA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 FORCE_TORCHRUN=1 \
llamafactory-cli train qwen3_32b_lora_sft.yaml官方原始命令没有写可见设备和 FORCE_TORCHRUN；这里按官方入门页“多卡训练用可见设备加 FORCE_TORCHRUN=1 启动”的说明补上（本站补充）。官方页面展示的运行时间为 0:02:24.90，本站未复现。
LoRA 参数怎么调
| 参数 | 含义 | 建议 |
|---|---|---|
lora_rank | adapter 的秩，决定容量 | 从 8 或 16 开始；任务差异大时再增大 |
lora_alpha | 缩放系数 | 常设为 rank 的 2 倍（官方示例 16 / 32） |
lora_target | 注入的模块 | all 覆盖全部线性层；显存紧张时可只选注意力投影 |
lora_dropout | adapter 的 dropout | 数据量小时可适当保留（如 0.05） |
“建议”一列是通用经验，不是官方要求。
三、加载 adapter 推理
yaml
# chat_lora.yaml —— 结构参考上游 inference 示例
model_name_or_path: /data/models/Qwen3-32B
adapter_name_or_path: saves/Qwen3-32B-Thinking/lora/sft
template: qwen3
infer_backend: huggingface
trust_remote_code: true
bash
llamafactory-cli chat chat_lora.yaml四、合并与导出
结构参考 LLaMA-Factory v0.9.3 merge_lora 示例。上游明确提示：合并 LoRA 时不要使用量化模型，也不要设置 quantization_bit。
yaml
# merge_lora.yaml
model_name_or_path: /data/models/Qwen3-32B
adapter_name_or_path: saves/Qwen3-32B-Thinking/lora/sft
template: qwen3
trust_remote_code: true
export_dir: /data/models/Qwen3-32B-sft-merged
export_size: 5
export_device: cpu
export_legacy_format: false
bash
llamafactory-cli export merge_lora.yaml官方入门页提醒：合并后的模型要单独验证，基础模型、adapter 与 tokenizer 路径不匹配都会导致结果异常。用同一组问题分别询问“基础模型 + adapter”与合并后模型，回答应基本一致。
五、QLoRA
官方提供的是脚本形式：下载 llmtutorial.zip，其中 llamafactory/ 目录包含 qwen2_qlora.yaml 和 run_qlora_test.sh。官方步骤要点：
bash
cd /data
wget https://mt-ai-infra.tos-cn-beijing.volces.com/llmtutorial.zip
unzip llmtutorial.zip && cd llmtutorial/llamafactory
python -m pip install bitsandbytes==0.50.2 -i https://mirrors.aliyun.com/pypi/simple
bash run_qlora_test.sh- 官方说明：QLoRA 必须加载权重，可以使用前面 CP Ulysses 测试保存的权重。官方未公开脚本内容，运行前请检查脚本中的模型路径。
- 官方页面没有公开
qwen2_qlora.yaml的内容。上游 LLaMA-Factory 的 QLoRA 配置核心是quantization_bit: 4与quantization_method: bnb（见 LLaMA-Factory v0.9.3 train_qlora 示例），本站未确认官方 YAML 是否相同。 - 官方入门页说明：QLoRA 是否可用取决于当前 MUSA 量化算子和依赖版本。请先跑通官方脚本，再换成自己的模型。
六、部署前的建议
vLLM-MUSA v0.28.0 Release 的发布说明中没有在线加载 LoRA adapter 的内容。本站建议先合并为完整权重，再按第 10 模块的方法用 vLLM-MUSA 部署；直接在线加载 adapter 属于未经官方说明的用法，需要自行验证。
七、常见问题
| 现象 | 处理 |
|---|---|
| 显存不足 | 降低 batch / cutoff_len → 开 gradient checkpointing → 减小 lora_target → 再考虑 DeepSpeed 或 QLoRA |
| QLoRA 报 bitsandbytes 错误 | 确认版本为官方指定的 0.50.2，并先用官方脚本验证 |
| 合并后回答变差 | 检查合并时是否误用量化模型；基础模型路径是否与训练时一致 |
| 某个 rank 报 MCCL timeout | 先找最早的报错，通常是另一个 rank 已 OOM |
八、回滚
LoRA 不修改基础模型；回滚只需停止加载 adapter，或切回原模型目录。合并导出写在新的 export_dir，不要覆盖原模型目录。