LLaMA-Factory 配置文件详解：YAML 参数调优指南

针对不同场景，可以参考以下推荐配置矩阵：

注意：当使用 QLoRA 时，需确保量化参数与方法配置匹配，避免加载失败。

数据集配置（dataset）

数据集配置控制数据加载和预处理流程，对模型效果有直接影响。核心参数包括：

dataset: identity,alpaca_en_demo
template: llama3
cutoff_len: 2048
max_samples: 1000
preprocessing_num_workers: 16

关键技巧：

• 模板选择必须与模型匹配，如 Llama3 使用 llama3 模板，Qwen 使用 qwen 模板。
• 多轮对话数据建议设置 cutoff_len: 4096，并启用 packing: true 以提升训练效率。
• 可通过 dataset_dir 参数指定本地数据集路径。

训练过程配置（train）

训练过程配置直接影响训练效率和模型收敛质量，需要根据硬件条件仔细调整：

per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 1.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true

关于有效批大小的计算逻辑：

• 有效批大小 = per_device_train_batch_size × gradient_accumulation_steps × 设备数
• 推荐有效批大小：7B 模型为 32-128，13B 模型为 64-256
• 学习率设置指南：
  • LoRA 微调：1e-4 ~ 2e-4
  • 全参数微调：2e-5 ~ 5e-5
  • 预热步数通常设为总步数的 5%-10%

高级调优策略

内存优化配置

针对显存受限场景，可通过以下参数组合实现高效训练：

# 基础内存优化
load_in_4bit: true
gradient_checkpointing: true

# 高级优化（适合 12GB 以下显存）
use_unsloth: true
unsloth_cache_dir: ./cache/unsloth
shift_attn: true

这些参数在项目的特殊优化配置中有更详细示例，FSDP+QLoRA 的组合能进一步降低显存占用。

训练稳定性优化

训练不稳定时，可尝试以下调优参数：

# 解决梯度爆炸
max_grad_norm: 1.0
# 解决训练波动
adam_beta2: 0.95
# 数据不平衡处理
class_weight: true
# 学习率预热
warmup_steps: 100

配置案例与最佳实践

场景 1：Llama3-8B LoRA 快速微调

model:
  model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
  trust_remote_code: true
  flash_attn: true

method:
  stage: sft
  do_train: true
  finetuning_type: lora
  lora_rank: 16
  lora_alpha: 32
  lora_dropout: 0.05

dataset:
  dataset: alpaca_zh_demo,identity
  template: llama3
  cutoff_len: 2048
  max_samples: 5000

output:
  output_dir: saves/llama3-8b/lora/sft
  logging_steps: 10
  save_steps: 200
  plot_loss: true

train:
  per_device_train_batch_size: 2
  gradient_accumulation_steps: 4
  learning_rate: 1.5e-4
  num_train_epochs: 3.0
  lr_scheduler_type: cosine
  warmup_ratio: 0.1
  bf16: true

场景 2：低资源量化微调（8GB 显存）

model:
  model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
  trust_remote_code: true
  quantization_method: BNB
  quantization_bit: 4
  quantization_type: nf4

method:
  stage: sft
  do_train: true
  finetuning_type: lora
  lora_rank: 8
  lora_target: q_proj,v_proj

dataset:
  dataset: alpaca_en_demo
  template: llama3
  cutoff_len: 1024
  max_samples: 2000

train:
  per_device_train_batch_size: 1
  gradient_accumulation_steps: 8
  learning_rate: 2e-4
  num_train_epochs: 5.0
  gradient_checkpointing: true
  use_unsloth: true

配置文件调试与常见问题

配置验证工具

LLaMA-Factory 提供了配置验证功能，可在启动训练前检查配置文件合法性：

python src/train.py --config examples/train_lora/llama3_lora_sft.yaml --dry_run

常见错误与解决方法

1. 模型加载失败
   • 检查 model_name_or_path 是否正确
   • 私有模型需配置 hf_hub_token
   • 添加 trust_remote_code: true（自定义模型）
2. 显存溢出
   • 降低 per_device_train_batch_size
   • 启用梯度检查点 gradient_checkpointing: true
   • 切换到 QLoRA 量化训练
3. 训练 loss 异常
   • 检查 template 是否与模型匹配
   • 调整学习率（通常降低 1-2 个数量级）
   • 验证数据集格式是否正确

总结与进阶资源

本文详细介绍了 LLaMA-Factory 配置文件的核心结构和关键参数调优方法，包括模型设置、微调方法、数据集处理和训练过程优化。通过合理配置这些参数，可显著提升微调效率和模型性能。

为进一步提升配置水平，建议参考官方配置示例库及高级调优指南。掌握 YAML 配置文件的优化技巧是 LLM 微调的基础，建议结合实际任务反复实验不同参数组合，形成适合特定场景的最佳配置方案。