一、官方验证基线
| 项目 | 版本 / 说明 |
|---|---|
| GPU | MTT S5000 |
| MUSA Driver | 4.3.7 |
| 训练镜像 | registry.mthreads.com/mcctest/training-suite:v2.1.5-musa-4.3.7 |
| 镜像内置 | MUSA SDK 4.3.7、MT Megatron-LM 0.14.0、MT DeepSpeed 0.17.2、Torch-MUSA 2.7.0 |
| LLaMA-Factory | v0.9.3，通过 musify 脚本适配 |
来源为 模型微调：基于 Llama-Factory（MTT S5000 实战）。LLaMA-Factory 入门（摩尔线程文档中心） 特别说明：v0.9.3 是“项目已验证基线，不代表上游最新版本”；升级 LLaMA-Factory 或 Transformers 后，需要重新验证模型实现、MUSA patch、DeepSpeed/TRL/PEFT 依赖和 YAML 参数名。
mcctest 命名空间。同页还提到另一个镜像 musa-train:4.3.4_kuae2.1_20260106_alinux，其 transformers 为 4.49，需要升级到 >=4.51 才能良好支持 Qwen3（官方命令：pip install transformers==4.51.3）。生产环境请向厂商确认可用的正式镜像。二、创建训练容器
sudo docker create \
--privileged \
--env MTHREADS_VISIBLE_DEVICES=all \
--net host \
-v /data/:/data/ \
--name llamafactory \
registry.mthreads.com/mcctest/training-suite:v2.1.5-musa-4.3.7 \
sleep infinity
sudo docker start llamafactory
sudo docker exec -it llamafactory bash
# 容器内检查（官方）
mthreads-gmi
python3 -c "import torch, torch_musa; print(torch.__version__)"三、安装 LLaMA-Factory v0.9.3
官方页面中克隆目录名（LLaMA-Factory）与后续 cd LlamaFactory 不一致。下面显式指定目录名，使三步保持一致（本站修正）。musify.sh 的路径是官方环境中的路径，请确认文件在你的环境中存在：
cd /data
git clone -b v0.9.3 --depth 1 https://github.com/hiyouga/LLaMA-Factory.git LlamaFactory
bash /data/playground/tool/musify.sh LlamaFactory # 生成 LlamaFactory_MUSA
cd LlamaFactory_MUSA
pip install -e .
llamafactory-cli version四、准备并注册数据集
LLaMA-Factory 通过 dataset_info.json 引用数据。--dataset train 指的是注册名为 train 的数据集，不是名为 train 的文件。ShareGPT 风格示例（单条记录来自官方入门页；外层数组为本站补充，使其成为合法的数据文件）：
[
{
"conversations": [
{"from": "human", "value": "你好"},
{"from": "gpt", "value": "你好，有什么可以帮助你？"}
]
}
]保存为 /data/datasets/llama_factory/train.json，并在同目录的 dataset_info.json 中注册：
{
"train": {
"file_name": "train.json",
"formatting": "sharegpt",
"columns": {"messages": "conversations"},
"tags": {"role_tag": "from", "content_tag": "value", "user_tag": "human", "assistant_tag": "gpt"}
}
}五、下载模型
pip install modelscope
modelscope download --model Qwen/Qwen3-0.6B --local_dir /data/models/Qwen3-0.6B六、单卡全参数 SFT：Qwen3-0.6B
官方页面用一长串命令行参数；为方便复现，这里把同样的参数整理为 YAML（除 output_dir 改为简短路径外，参数值与官方一致）：
# qwen3_0.6b_full_sft.yaml
stage: sft
do_train: true
model_name_or_path: /data/models/Qwen3-0.6B
trust_remote_code: true
finetuning_type: full
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: 2
gradient_accumulation_steps: 8
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-0.6B-Thinking/full/sftMUSA_VISIBLE_DEVICES=0 llamafactory-cli train qwen3_0.6b_full_sft.yaml官方页面展示的一次训练结果为 train_runtime = 0:00:28.84、train_loss = 2.2287。这是厂商环境与示例数据下的结果，本站未复现；另外该输出显示 epoch = 2.0，与命令中的 3 个 epoch 不一致，可能来自不同的运行，仅作数量级参考。
七、多卡训练
MUSA_VISIBLE_DEVICES=0,1,2,3 FORCE_TORCHRUN=1 llamafactory-cli train qwen3_0.6b_full_sft.yaml可见设备数量必须与实际 GPU 数一致。有效 batch = 单卡 batch × 梯度累积步数 × 数据并行进程数；从单卡换到 4 卡时，若想保持有效 batch 不变，可把 gradient_accumulation_steps 从 8 改为 2。显存不足时再考虑 DeepSpeed ZeRO 或 FSDP（第 4 模块第 4 课）。
八、验证微调效果
- 检查输入格式：先抽查经 tokenize 后的样本，确认 system/user/assistant 角色、EOS 与 label mask 正确。官方提醒：模板选错往往不会报错，但会让训练输入格式错误。
- 小样本对话：用训练产物做推理，与原始模型对比同一组问题。
- 看损失曲线：
plot_loss: true会在输出目录生成损失图。
# chat_full.yaml —— 用法参考上游 inference 示例
model_name_or_path: saves/Qwen3-0.6B-Thinking/full/sft
template: qwen3
infer_backend: huggingface
trust_remote_code: trueMUSA_VISIBLE_DEVICES=0 llamafactory-cli chat chat_full.yaml九、WebUI
llamafactory-cli webui 默认监听 7860 端口。官方建议远程服务器通过 SSH 本地端口转发访问，不要把管理页面直接暴露到公网；正式任务仍以 YAML 保存配置。
十、常见问题
| 现象 | 排查方向（来自官方入门页） |
|---|---|
| 找不到数据集 | dataset_dir 是否指向包含 dataset_info.json 的目录；dataset 是否为注册名称 |
| 训练能跑但结果异常 | 打印 tokenized 样本，检查角色、EOS、mask 与 template |
| 多卡报 MCCL timeout | 先找第一条异常；常见是某个 rank 先 OOM，其他 rank 才超时 |
| 显存不足 | 依次降低 batch、cutoff_len，开启 gradient checkpointing 或改用 LoRA（下一课） |
十一、回滚
训练不改动基础模型目录，产物都在 output_dir 中。回滚只需停用新产物，继续使用原模型。若安装依赖时破坏了容器环境，删除容器后用同一镜像重建即可（数据在挂载的 /data 中，删除容器前请确认）。