LLaMA-Factory框架参数详解

优质文章学习记录

07 Apr 2026 — 10 min read

LLaMA-Factory框架参数详解

在大模型落地进入“工业化”阶段的今天，一个核心挑战浮出水面：如何让复杂的微调流程不再依赖专家级的手动调参和脚本拼接？当研究团队需要快速迭代多个LoRA适配器、产品部门希望将SFT与DPO对齐无缝衔接上线时，传统基于Hugging Face Transformers的自由组合方式开始显得力不从心——配置碎片化、复现困难、部署断层等问题接踵而至。

正是在这种背景下，LLaMA-Factory 应运而生。它不像简单的训练脚本那样只解决单一环节，而是试图构建一条端到端的“模型生产线”。从数据预处理、多阶段训练、自动评估到量化导出，所有模块都被统一抽象为可配置项，通过一套标准化接口串联起来。更关键的是，它支持超过 100+ 主流架构模型，无论是 LLaMA、Qwen、Baichuan 还是 ChatGLM、Phi、Mistral，都可以用同一套参数体系进行操作。

这种设计带来的直接好处是：一次学会，处处可用。你不再需要为每个新模型重写训练逻辑，也不必在不同项目间复制粘贴yaml文件。更重要的是，它的双模式交互（命令行 + WebUI）使得研究员可以精细控制每项参数，而工程师则能通过可视化界面快速验证想法。

但这也引出了一个问题：这套系统究竟提供了多少可控维度？它们又该如何协同工作？下面我们就深入其内部机制，逐层拆解那些真正影响训练质量与效率的关键参数。

参数体系的设计哲学

LLaMA-Factory 的参数组织并非随意堆砌，而是遵循“分层分类、职责清晰”的工程原则。整体来看，这些参数像齿轮一样咬合在一起，分别控制着训练的不同层面：

微调策略层：决定你是做全量微调、LoRA，还是强化学习对齐；
数据流动层：管理数据集加载、prompt模板应用、样本混合方式；
模型结构层：涉及模型加载、量化、多模态处理及推理后端选择；
优化执行层：包括分布式训练、显存优化技术如GaLore/BAdam等；
监控与输出层：实验追踪、日志记录、生成解码行为控制。

理解这一点至关重要——不是所有参数都同等重要，也不是所有组合都有意义。比如你在使用 stage=dpo 时去设置 lora_rank 是合理的，但若同时启用 use_galore=True 和 pure_bf16=True，就需要格外注意数值稳定性问题。

接下来我们不按传统章节顺序展开，而是围绕几个典型场景来解析参数之间的联动关系。

场景一：资源有限下的高效微调（LoRA实战）

假设你手头只有一张24GB显存的消费级GPU，想对 Qwen-7B 进行领域适配。显然全参数微调不可行，那么 LoRA 成为首选方案。此时最关键的参数组合如下：

finetuning_type: lora lora_rank: 64 lora_alpha: 128 lora_dropout: 0.1 lora_target: q_proj,v_proj,k_proj,o_proj

这里有几个经验性建议：
- lora_rank=64 而非默认的8，是因为小rank容易成为性能瓶颈；
- lora_alpha 设为 rank 的两倍（即缩放因子 α/r = 2），有助于保持原始模型的表达能力；
- 显式列出 q_proj,v_proj,... 比使用 "all" 更安全，避免误触不兼容模块；
- 若发现训练不稳定，可尝试开启 use_dora: true，它通过分离方向与幅值更新提升了收敛性。

此外，为了进一步降低显存占用，你可以考虑：

pure_bf16: true # 使用纯bfloat16训练（需硬件支持） disable_gradient_checkpointing: false # 保留梯度检查点以节省显存

但要注意，pure_bf16 对某些老型号GPU（如V100以下）并不友好，可能会导致NaN loss。此时应退回到AMP混合精度模式。

另一个常被忽视的细节是 additional_target。例如，在微调多模态模型时，若希望额外训练视觉投影层，可设置：

additional_target: mm_projector

这样即使该模块不在LoRA目标列表中，也会被纳入可训练范围。

场景二：偏好对齐训练（DPO/PPO流程）

当你已经完成SFT并拥有成对的人类偏好数据时，下一步通常是执行DPO或PPO来进行对齐优化。这类任务的核心在于对比学习信号的建模，因此相关参数尤为关键。

以 DPO 为例，最核心的配置包括：

stage: dpo pref_beta: 0.1 pref_loss: sigmoid ref_model: path/to/sft/model

其中：
- pref_beta 控制偏好强度，太大会导致过度拟合偏好数据，太小则对齐效果弱；
- pref_loss 支持多种变体，如 simpo 引入了动态margin机制，适合高质量标注数据；
- ref_model 可指向原始SFT模型路径；若未指定，则默认使用当前训练模型自身作为参考，这在增量训练中很常见。

如果你还想保留一定的监督信号，可以通过 pref_ftx 添加SFT loss：

pref_ftx: 0.1 # 给SFT loss分配10%权重

而对于 PPO，复杂度更高，因为它涉及奖励模型和KL控制：

stage: ppo reward_model: path/to/rm/model ppo_target: 6.0 ppo_score_norm: true

这里的 ppo_target 是自适应KL惩罚的目标值，通常设为5~10之间。过低会导致输出过于保守，过高则可能引发语言漂移。实践中建议先固定KL系数观察变化趋势，再启用自适应调节。

值得注意的是，LLaMA-Factory 允许你将多个适配器拼接使用。例如，你可以加载一个预训练好的LoRA用于主干，再挂载一个新的适配器专门训练PPO策略网络，只需设置：

adapter_name_or_path: path/to/lora_sft,path/to/lora_ppo

系统会自动识别并合并参数，极大简化了多阶段pipeline的构建。

场景三：多模态与长上下文扩展

随着模型能力边界不断拓展，越来越多的应用涉及图像、视频或多轮对话。LLaMA-Factory 在这方面也做了充分支持。

对于图文输入场景，如MiniGPT-4类架构，关键参数集中在多模态部分：

freeze_vision_tower: true freeze_multi_modal_projector: false train_mm_proj_only: false image_max_pixels: 589824 # 约768x768

通常做法是冻结视觉编码器（CLIP-ViT），仅训练连接文本空间的投影层。但如果数据量足够大，也可以放开部分ViT块进行微调。

而在处理超长文本时，RoPE外推技术变得必不可少：

rope_scaling: dynamic cutoff_len: 8192 flash_attn: fa2

dynamic 类型的RoPE能在推理时动态调整位置编码，有效缓解外推失真；
配合 FlashAttention-2 (fa2) 可显著加速长序列计算；
若仍显存不足，还可启用 shift_attn: true，减少KV Cache存储开销。

此外，packing 参数值得特别关注。当设置 packing: true 时，系统会将多个短样本打包进同一个序列，提升吞吐量。但需注意：若任务依赖完整对话历史（如chatbot），则必须关闭此功能，否则会导致上下文错乱。

数据与训练流程的精细化控制

数据永远是微调成败的关键。LLaMA-Factory 提供了丰富的选项来精确操控数据流。

首先是 template 参数，它决定了prompt如何构造。例如使用 alpaca 模板时，输入会被格式化为：

Below is an instruction that describes a task. Write a response that appropriately completes the request. ### Instruction: {instruction} ### Response:

而 qwen 则采用ChatML风格：

<|im_start|>system You are a helpful assistant.<|im_end|> <|im_start|>user {query}<|im_end|> <|im_start|>assistant

选错模板可能导致模型无法理解任务意图，因此务必确保与训练数据一致。

其次，mix_strategy 决定了多数据集的融合方式：
- concat：先拼接再打乱，适合同分布数据；
- interleave_under：交替采样，适用于异构任务平衡训练；
- 结合 interleave_probs 可实现加权混合，例如 [0.7, 0.3] 表示主任务占七成。

还有一个实用技巧：利用 tokenized_path 缓存已处理的数据集。尤其在反复调试超参时，避免重复tokenization能节省大量时间：

tokenized_path: ./data/tokenized/alpaca_en overwrite_cache: false

一旦缓存生成，后续运行将直接加载，除非显式清除或设置 overwrite_cache: true。

推理与部署：从训练到服务的最后一公里

很多人忽略了这样一个事实：训练完成只是第一步，真正的挑战在于稳定高效的推理服务。LLaMA-Factory 在这方面同样提供了完整链条。

首先，infer_backend 决定了推理引擎：

infer_backend: vllm

vLLM 相比原生 Hugging Face 实现，具备 PagedAttention、连续批处理等优势，吞吐量可提升数倍。配合以下参数可进一步优化：

vllm_maxlen: 4096 vllm_gpu_util: 0.9 vllm_enforce_eager: false

特别是 vllm_gpu_util，它控制block分配策略，过高可能导致内存碎片，一般建议设置在0.8~0.9之间。

生成阶段的参数则直接影响用户体验。例如：

do_sample: true temperature: 0.7 top_p: 0.9 repetition_penalty: 1.2 max_new_tokens: 512

温度不宜过高（>1.0），否则易产生无意义内容；
repetition_penalty > 1.0 有助于抑制循环重复；
若希望生成更连贯的回答，可启用 length_penalty: 1.2 鼓励更长输出。

最后，模型导出环节也不能掉以轻心：

export_dir: ./exports/qwen-7b-lora-dpo export_quantization_bit: 4 export_size: 2 # 分片大小2GB export_legacy_format: false # 使用.safetensors

导出后的模型可直接上传至 Hugging Face Hub（通过 export_hub_model_id），或集成进API服务。结合环境变量如 API_HOST, API_PORT, MAX_CONCURRENT，即可快速搭建高并发在线接口。

实验管理与可观测性

任何严肃的研发都离不开实验追踪。LLaMA-Factory 原生集成 SwanLab 和 Weights & Biases，只需简单配置即可开启：

use_swanlab: true swanlab_project: my-dpo-experiments swanlab_run_name: qwen7b-dpo-v1

训练过程中，损失曲线、学习率变化、GPU利用率等指标都会实时同步。这对于排查异常（如loss震荡、梯度爆炸）极为有用。

同时，日志级别可通过环境变量精细控制：

LLAMAFACTORY_VERBOSITY=DEBUG

在调试阶段设为 DEBUG 可查看详细模块初始化信息；生产环境中则推荐 INFO 或 WARN，避免日志冗余。

当我们将视线拉远，会发现 LLaMA-Factory 的真正价值不仅在于功能丰富，而在于它推动了一种新的工作范式：配置即代码，实验可复现。每一个 .yaml 文件都是一个完整的训练蓝图，包含了模型、数据、优化器、评估指标等全部要素。这让团队协作变得更加透明，也让自动化流水线成为可能。

未来，随着 MoE 架构、Long Context 推理、多模态Agent等方向的发展，这套参数体系还将持续演进。但其核心理念不会改变：降低门槛，提升效率，让开发者专注于创造本身。

📌 官网地址：https://github.com/hiyouga/LLaMA-Factory
📘 文档中心：https://llamafactory.readthedocs.io/

LLaMA-Factory框架参数详解

优质文章学习记录