LLaMA-Factory框架参数全解析

LLaMA-Factory框架参数全解析

在当前大模型技术飞速演进的背景下，如何高效、灵活地对预训练语言模型进行微调，已成为AI研发团队的核心挑战。面对日益增长的定制化需求——从企业级知识问答系统到垂直领域的对话助手——开发者亟需一个既能降低使用门槛，又能保持高度灵活性与工程稳定性的工具链。

LLaMA-Factory 正是在这一背景下脱颖而出的一站式大模型微调框架。它不仅支持包括 LLaMA、Qwen、Baichuan、ChatGLM 在内的100+ 主流架构，更统一集成了全参数微调（Full Fine-tuning）、LoRA、QLoRA、Freeze Training 等多种主流高效微调方法，并提供从数据处理、训练、评估到部署的完整流水线。尤其值得一提的是，其内置的可视化 WebUI 极大地降低了上手成本，使得即便是非专业背景的研究人员或工程师也能快速完成高质量的模型定制。

但真正让 LLaMA-Factory 成为“生产级”解决方案的关键，在于其精细化且可组合的配置体系。数百个参数背后并非简单的功能堆砌，而是围绕实际工程问题构建的系统性设计。本文将深入剖析这些核心参数的技术含义与最佳实践路径，帮助你摆脱“盲目调参”的困境，实现精准控制与高效迭代。

训练阶段与基础行为控制

每个训练任务都始于明确的目标设定。stage参数决定了整个流程的方向：

stage: Literal["pt", "sft", "rm", "ppo", "dpo", "kto"]

• pt（Pre-training）适用于继续预训练场景，比如在特定领域语料上扩展语言理解能力；
• sft是最常见的监督微调模式，用于指令遵循、风格迁移等任务；
• rm和ppo构成强化学习对齐的标准流程：先训练奖励模型，再通过 PPO 优化策略；
• 而dpo和kto则代表了无需显式奖励建模的偏好对齐新范式，大幅简化了训练架构。

通常情况下，大多数用户会以stage=sft启动第一个实验。此时配合finetuning_type=lora可实现低资源下的快速验证。LoRA 因其极高的性价比成为首选——仅需更新千分之一的参数即可获得显著效果提升。

若追求极致性能且具备多卡环境，则可尝试finetuning_type=full进行全参数微调。不过需要注意，这往往需要梯度累积和更大的 batch size 支持，否则容易因 batch 太小导致优化不稳定。

其他几个通用开关也值得留意：
-pure_bf16=True可节省约 20% 显存，但要求硬件支持 bfloat16（如 A100/V100）；
-plot_loss=True会在训练结束后自动生成损失曲线图，便于直观判断收敛状态；
-disable_shuffling=True常用于调试阶段，确保每次运行结果一致，利于问题复现。

💡 实践建议：对于初学者，推荐使用sft + lora组合作为起点；待验证可行后，再逐步引入更复杂的设置。

LoRA 微调深度调优指南

LoRA 已成为现代大模型微调的事实标准，而 LLaMA-Factory 提供了业界最全面的 LoRA 配置选项，远超基础实现。

关键参数如下：

一个常被忽视的细节是additional_target。默认情况下，LoRA 不会影响词表嵌入层（embed_tokens）和输出头（lm_head），但如果目标任务涉及新词汇或特殊输出格式（如 JSON Schema），可以显式将其加入可训练范围：

additional_target="embed_tokens,lm_head"

此外，框架还支持多项前沿增强技术：

• use_dora=True：启用 DoRA（Decomposed LoRA），将权重分解为方向与幅值两部分独立更新，实测可在多数任务中加快收敛速度并提升最终性能。
• pissa_init=True：采用 PiSSA 初始化方案，基于 SVD 分解预训练权重生成高质量初始适配器，特别适合冷启动场景（即无参考适配器时）。
• use_rslora=True：启用 Rank-Stabilized LoRA，通过对缩放因子归一化来稳定训练动态。

🔍 技术洞察：
lora_alpha / lora_rank的比值本质上控制了适配器的学习率增益。过高可能导致灾难性遗忘；过低则学习不足。建议在 1~4 范围内调整，优先尝试 2。

强化学习与人类偏好对齐

当需要让模型更好地匹配人类价值观或交互偏好时，PPO、DPO 等对齐算法便派上了用场。LLaMA-Factory 对这些先进方法提供了原生支持。

DPO 配置要点

DPO（Direct Preference Optimization）因其无需训练奖励模型而广受欢迎。核心参数包括：

• pref_beta=0.1：控制 KL 正则强度，值越大模型越保守，偏离原始策略的程度越小；
• pref_loss=sigmoid：主流选择，也可尝试hinge或ipo在某些任务上表现更鲁棒；
• dpo_label_smoothing=0.1：缓解标注噪声的有效手段，推荐开启以增强泛化能力。

值得注意的是，SimPO 提出了全新的视角——用固定 margin 替代 beta 控制，提出simpo_gamma=0.5作为理想边界。该方法在多个基准测试中超越传统 DPO，值得关注。

PPO 与 KTO 设置

对于经典的 PPO 流程：
-ppo_epochs=4决定了每个样本重复优化的轮数，太少易欠拟合，太多可能导致过拟合；
-ppo_target=6.0设定自适应 KL 控制目标，防止策略漂移过大；
-reward_model必须指定有效的奖励模型路径，类型可通过reward_model_type设置为lora、full或远程 API。

KTO 则采用二元偏好信号直接优化行为倾向：
-kto_chosen_weight=1.0与rejected_weight=1.0控制正负样本的损失权重，可根据数据分布适当倾斜。

⚠️ 注意事项：若未指定ref_model，系统将默认使用主模型自身作为参考策略。虽然方便，但在差异较大的任务中可能导致训练不稳定，建议尽可能提供独立参考模型。

Freeze 微调：低成本试错利器

当你仅有单张消费级 GPU（如 3090/4090）时，全参数微调几乎不可行。此时，Freeze 微调是一种极具性价比的选择。

其核心思想是冻结大部分模型参数，仅解冻少数关键层进行训练。主要配置项为：

freeze_trainable_layers=2 # 解冻最后2层 freeze_trainable_modules="all" # 所有模块均可训练 freeze_extra_modules="lm_head" # 额外训练输出头

这种策略尤其适合以下场景：
- 指令微调任务，只需轻微调整高层语义表达；
- 输出格式迁移，如从自由文本转为结构化输出；
- 快速原型验证，避免长时间训练带来的高成本。

经验表明，仅训练最后 2~3 层即可在多数任务中取得不错效果，同时显存占用仅为全量微调的 30% 左右。

高级优化器：突破显存瓶颈的新路径

随着模型规模扩大，优化器状态（如 Adam 的 momentum 和 variance）成为显存消耗的主要来源。LLaMA-Factory 引入了三种前沿优化技术，专为低资源环境设计。

GaLore：梯度低秩投影

GaLore 的核心思想是将高维梯度投影到低秩子空间中进行更新，从而大幅压缩 optimizer state。

se_galore=True galore_rank=16 galore_update_interval=200

实测显示，在 7B 模型上使用 GaLore + LoRA 可将显存降低至 12GB 以内，甚至可在笔记本 GPU 上运行。

BAdam：块状动态更新

BAdam 将模型划分为若干“块”，按时间顺序轮流更新。这种方式不仅能节省显存，还能观察不同网络区域的重要性变化。

use_badam=True badam_mode=ratio badam_update_ratio=0.05 # 每步更新5%参数

非常适合用于分析模型敏感区域或渐进式微调。

APOLLO：低秩自适应预 conditioner

APOLLO 是一种新型实验性优化器，结合低秩结构改进 Adam 的 preconditioning 过程。

use_apollo=True apollo_rank=16 apollo_scale=32.0

目前仍处于探索阶段，建议在研究项目中谨慎使用。

✅ 使用建议：
- 极低显存场景优先考虑 GaLore；
- BAdam 更适合调试与分析；
- APOLLO 暂不推荐用于生产环境。

数据处理：质量决定上限

无论模型多强大，垃圾输入只会产出垃圾输出。因此，数据预处理环节至关重要。

关键参数包括：

• template=chatml：适配 OpenAI 格式的对话模板，兼容广泛的数据集；
• cutoff_len=2048：截断长度，应根据任务特点调整，长文本任务可设为 4096 或更高；
• train_on_prompt=False：默认只在 response 部分计算 loss，避免 prompt 干扰；
• packing=True：启用 sequence packing，将多个短样本拼接成一条长序列，显著提升 GPU 利用率；
• mix_strategy=interleave_under：多数据集混合策略，避免某一数据集主导训练过程。

对于超大规模数据集，建议启用streaming=True以避免内存溢出，并配合preprocessing_batch_size=1000加快处理速度。

💬 提示：使用packing=True可使吞吐量提升 30%~50%，尤其适合 Causal LM 类任务。

模型加载与量化加速

模型相关配置直接影响推理效率与训练稳定性。

基础设置

model_name_or_path=meta-llama/Llama-3-8b-instruct use_fast_tokenizer=True # 启用 Rust 加速 tokenizer flash_attn=fa2 # 使用 FlashAttention-2，速度提升显著 rope_scaling=yarn # 支持上下文外推，适用于长文本扩展 device_map=auto # 自动分配 GPU 张量 infer_backend=vllm # 推理时使用 vLLM，提高吞吐

其中flash_attn=fa2需要 CUDA ≥ 11.8，但能带来高达 30% 的训练加速；rope_scaling=yarn则允许模型在超过原生上下文长度（如 32k）时仍保持良好性能。

量化配置

对于资源受限场景，量化是必选项：

quantization_bit=4 quantization_method=bitsandbytes quantization_type=nf4 double_quantization=True

上述配置即为典型的 QLoRA 方案，可在单卡 24GB 显存下微调 7B 模型。启用use_unsloth=True还可进一步提速达 2x（仅限 LoRA）。

模型导出与一键发布

训练完成后，可通过以下参数导出模型用于部署：

export_dir=./my_lora_model export_quantization_bit=4 export_hub_model_id=myorg/my-awesome-model export_legacy_format=False # 默认保存为 .safetensors

支持自动分片（export_size=5GB/片）、量化校准数据指定（export_quantization_dataset）等功能，满足工业级交付需求。

🚀 示例命令：

bash llamafactory-cli export \ --export_dir ./output \ --export_quantization_bit 4 \ --export_hub_model_id myrepo/my-model

一键推送至 Hugging Face Hub，便于团队共享与版本管理。

日志监控与可视化追踪

良好的可观测性是工程落地的关键。LLaMA-Factory 支持 SwanLab、WandB 等主流平台。

use_swanlab=True swanlab_project=llama-finetune swanlab_run_name=exp-lora-v1 logging_steps=5 save_steps=100

搭配plot_loss=True可实时查看训练动态，及时发现异常波动或收敛停滞。

容器化部署时，可通过环境变量灵活控制行为：

CUDA_VISIBLE_DEVICES=0,1 WANDB_DISABLED=true GRADIO_SERVER_PORT=7860 GRADIO_SHARE=true USE_MODELSCOPE_HUB=true LLAMAFACTORY_VERBOSITY=INFO

🐳 Docker 启动示例：

bash docker run -d --gpus all -p 7860:7860 \ -e GRADIO_SERVER_PORT=7860 \ -e GRADIO_SHARE=false \ llamafactory/llamafactory:latest

LLaMA-Factory 不只是一个微调工具，更是面向生产级大模型定制的工程化底座。它的价值不仅体现在功能丰富性上，更在于其模块化设计、清晰的参数命名体系以及强大的可复现性保障。

无论是用 LoRA 快速验证一个新想法，还是计划打造行业专用的全参数模型，这套参数体系都能为你提供坚实支撑。更重要的是，它让每一次实验都变得透明可控，极大提升了研发效率与工程可靠性。

未来，随着 MoE、Streaming Transformer 等新技术的持续集成，LLaMA-Factory 有望继续引领开源大模型微调生态的发展方向。

立即开启你的大模型定制之旅吧！

🔗项目地址：https://github.com/hiyouga/LLaMA-Factory
📘文档中心：https://llamafactory.readthedocs.io