LLaMA-Factory微调训练快速入门指南

LLaMA-Factory 微调实战：从零构建你的专属大模型

在生成式 AI 浪潮席卷各行各业的今天，越来越多企业和开发者不再满足于通用大模型“千人一面”的回答风格。无论是打造一个懂行业术语的客服助手，还是训练一款能写复古风商品文案的营销工具，定制化的大语言模型（LLM）已成为实现业务差异化的关键一步。

然而，微调一个像 LLaMA-3 这样的 8B 级别模型，听起来就像一场资源与耐心的双重考验——动辄上百 GB 显存、复杂的依赖配置、晦涩难懂的训练脚本……这些门槛让许多团队望而却步。

有没有一种方式，能让这个过程变得像搭积木一样简单？

答案是肯定的。LLaMA-Factory 正是为此而生。它不是另一个实验性项目，而是一个真正开箱即用、支持超百种主流架构的高效微调框架。更重要的是，它把原本需要写几百行代码才能完成的任务，封装成了几条命令甚至图形界面操作。

本文将以Meta-Llama-3-8B-Instruct模型为例，在一台配备 RTX 4090 的本地机器上，带你完整走通一条 LoRA 指令微调的落地路径——从环境准备到最终部署为 Ollama 可运行的服务，全程无跳步，适合所有希望快速验证想法的技术人员。

环境准备：稳扎稳打的第一步

再强大的框架也离不开稳固的基础。在开始任何训练之前，我们必须确保系统处于“Ready”状态。

显卡与 CUDA 是否就绪？

如果你用的是 NVIDIA 显卡，第一步永远是确认驱动和 CUDA 是否正常工作：

nvidia-smi

这条命令应该清晰地列出你的 GPU 型号、显存容量和当前驱动版本。对于 LLaMA-3-8B 这类中等规模模型，我们推荐至少24GB 显存的消费级卡起步，比如 RTX 3090 / 4090 或 A10G。这类硬件足以支撑 LoRA 微调，同时保留足够的余量应对突发负载。

如果输出为空或报错，请先安装官方驱动和 CUDA Toolkit，并确保 PyTorch 安装时匹配对应的 CUDA 版本（例如torch==2.3.0+cu121）。

构建独立 Python 环境

为了避免依赖冲突，强烈建议使用 Conda 创建隔离环境：

git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory conda create -n llama_factory python=3.10 conda activate llama_factory pip install -e '.[torch,metrics]'

这行pip install -e不仅安装了核心库（如 transformers、datasets、accelerate），还注册了一个全局命令llamafactory-cli，后续所有操作都将围绕它展开。

验证安装是否成功

两个简单的检查可以帮你排除大部分前期问题：

1. PyTorch 能否识别 GPU？

import torch print(torch.cuda.is_available()) # 应输出 True print(torch.cuda.get_device_name(0)) # 显示 GPU 名称

2. CLI 工具是否生效？

llamafactory-cli train -h

如果看到一长串参数说明，恭喜你，基础环境已经搭建完毕。

模型下载与本地验证

虽然 LLaMA-Factory 支持自动拉取 Hugging Face 模型，但为了稳定性和复现性，手动管理模型路径是更优选择。

以Meta-Llama-3-8B-Instruct为例，国内用户可通过 ModelScope 快速获取：

from modelscope import snapshot_download model_dir = snapshot_download('LLM-Research/Meta-Llama-3-8B-Instruct')

或者直接克隆仓库：

git clone https://www.modelscope.cn/LLM-Research/Meta-Llama-3-8B-Instruct.git

下载完成后，务必进行一次完整性测试，避免因文件缺失导致训练中途失败：

import transformers import torch model_path = "/path/to/Meta-Llama-3-8B-Instruct" pipeline = transformers.pipeline( "text-generation", model=model_path, model_kwargs={"torch_dtype": torch.bfloat16}, device_map="auto" ) messages = [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "介绍一下你自己"} ] prompt = pipeline.tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True) outputs = pipeline(prompt, max_new_tokens=128) print(outputs[0]["generated_text"][len(prompt):])

能正常生成回复，说明模型可用。

数据集构建：让模型学会“你是谁”

数据决定模型的行为边界。LLaMA-Factory 支持两种主流格式：alpaca和sharegpt。本例采用前者。

alpaca 格式详解

每个样本包含以下字段：

{ "instruction": "用户指令（必填）", "input": "上下文输入（选填）", "output": "期望输出（必填）", "system": "系统提示词（选填）", "history": [["上一轮问题", "上一轮回复"]] }

例如，定义模型身份的认知数据：

{ "instruction": "Who are you?", "output": "Hello! I am MyBot, an AI assistant developed by MyTeam." }

保存为data/identity.json，并在data/dataset_info.json中注册：

"identity": { "file_name": "identity.json" }

无需额外字段映射，因为默认命名一致。

自定义任务数据：商品文案生成

假设我们要训练一个电商文案生成器，原始数据可能是 CSV 或 JSON 形式：

{ "content": "风格#复古*材质#棉麻*适用季节#春秋", "summary": "这款棉麻混纺衬衫采用复古剪裁..." }

转换为标准格式并保存为data/adgen_local.json：

[ { "instruction": "根据描述生成一段商品文案", "input": "风格#复古*材质#棉麻*适用季节#春秋", "output": "这款棉麻混纺衬衫采用复古剪裁..." } ]

然后在dataset_info.json中添加注册项：

"adgen_local": { "file_name": "adgen_local.json", "columns": { "instruction": "instruction", "input": "input", "output": "output" } }

至此，两个数据集均已就绪，可在训练中通过名称引用。

开始训练：LoRA 指令微调实战

现在进入核心环节。我们将使用 LoRA（Low-Rank Adaptation）技术对模型进行轻量级微调。相比全参数训练，LoRA 仅更新少量新增参数，显存占用可降低 70% 以上。

执行如下命令：

llamafactory-cli train \ --stage sft \ --do_train \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --dataset identity,adgen_local \ --dataset_dir ./data \ --template llama3 \ --finetuning_type lora \ --output_dir ./saves/llama3-lora-sft \ --overwrite_cache \ --overwrite_output_dir \ --cutoff_len 1024 \ --preprocessing_num_workers 8 \ --per_device_train_batch_size 2 \ --gradient_accumulation_steps 8 \ --learning_rate 2e-4 \ --num_train_epochs 3.0 \ --max_samples 1000 \ --val_size 0.1 \ --logging_steps 10 \ --save_steps 50 \ --eval_steps 25 \ --evaluation_strategy steps \ --load_best_model_at_end \ --plot_loss \ --fp16

几个关键点值得强调：

• --finetuning_type lora：启用 LoRA 微调
• --output_dir：保存的是适配器权重（adapter），通常只有几十到几百 MB
• --gradient_accumulation_steps：当单卡 batch size 受限于显存时，可通过累积梯度模拟更大 batch
• --fp16：半精度训练显著节省显存，且对性能影响极小

训练过程中会实时绘制 loss 曲线。理想情况下，loss 应稳步下降至 1.0 以下。若出现震荡或不降反升，可能需调整学习率或检查数据质量。

推理测试：动态加载 LoRA 权重

训练完成后，无需立即合并模型，即可通过动态加载方式进行推理测试：

llamafactory-cli webchat \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --adapter_name_or_path ./saves/llama3-lora-sft \ --template llama3 \ --finetuning_type lora

访问http://localhost:7860即可进入交互界面。尝试提问 “你是谁？” 或输入商品特征字符串，观察模型是否按预期生成内容。

也可以使用命令行模式快速调试：

llamafactory-cli chat \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --adapter_name_or_path ./saves/llama3-lora-sft \ --template llama3 \ --finetuning_type lora

这种“热插拔”式的推理方式非常适合多任务切换或多版本对比实验。

效果评估：不只是看生成结果

人工判断固然直观，但要科学比较不同训练策略的效果，还需量化指标支持。

LLaMA-Factory 内置了 BLEU、ROUGE 等文本生成评估方法，可通过批量预测自动计算：

llamafactory-cli train \ --stage sft \ --do_predict \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --adapter_name_or_path ./saves/llama3-lora-sft \ --eval_dataset adgen_local \ --dataset_dir ./data \ --template llama3 \ --finetuning_type lora \ --output_dir ./saves/llama3-lora-predict \ --per_device_eval_batch_size 1 \ --max_samples 50 \ --predict_with_generate

运行结束后，会在输出目录生成两个重要文件：

• generated_predictions.jsonl：每条样本的真实 label 与模型生成结果
• predict_results.json：包含 BLEU-4、ROUGE-1/2/L 等自动评分

这些数值可用于横向对比不同超参组合的表现，帮助你选出最优模型。

模型合并：生成独立部署包

当你确认某个 LoRA 版本表现良好，就可以将其与基础模型融合为一个完整的.bin文件，便于后续部署或二次训练。

使用 export 命令完成合并：

llamafactory-cli export \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --adapter_name_or_path ./saves/llama3-lora-sft \ --template llama3 \ --finetuning_type lora \ --export_dir ./merged-llama3-bot \ --export_size 2 \ --export_device cpu \ --export_legacy_format false

合并后的模型位于./merged-llama3-bot，可像普通 Hugging Face 模型一样加载。

⚠️ 小贴士：某些情况下合并后可能出现 tokenizer 异常，导致重复输出。解决方案是将原始模型的tokenizer_config.json和special_tokens_map.json复制覆盖到新目录中。

图形化操作：WebUI 让一切更直观

并不是每个人都喜欢敲命令。LLaMA-Factory 提供了名为LlamaBoard的 WebUI 界面，类似 Stable Diffusion 的操作体验，极大降低了使用门槛。

启动方式极其简单：

llamafactory-cli webui

打开浏览器访问http://localhost:7860，你会看到五个主要模块：

• Train：可视化配置训练参数，实时查看 loss 曲线
• Evaluate：一键运行 MMLU、C-Eval 等权威 benchmark
• Inference：内置聊天窗口，支持多轮对话
• Export：图形化完成模型合并
• API：快速启动 OpenAI 兼容接口

所有设置均可导出为 YAML 文件，方便复现实验或迁移到服务器环境。

服务化部署：通过 API 对外提供能力

训练好的模型最终要服务于应用。LLaMA-Factory 内置了一个兼容 OpenAI API 协议的服务端，只需一条命令即可启动：

API_PORT=8000 llamafactory-cli api \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --adapter_name_or_path ./saves/llama3-lora-sft \ --template llama3 \ --finetuning_type lora

服务启动后，任何支持 OpenAI SDK 的客户端都可以无缝接入：

from openai import OpenAI client = OpenAI( api_key="0", base_url="http://localhost:8000/v1" ) response = client.chat.completions.create( model="default", messages=[{"role": "user", "content": "你是谁？"}] ) print(response.choices[0].message.content)

💡 进阶技巧：若已合并模型，可结合 vLLM 加速推理：

llamafactory-cli api \ --model_name_or_path ./merged-llama3-bot \ --infer_backend vllm \ --vllm_enforce_eager

vLLM 能显著提升吞吐量，尤其适合高并发场景。

边缘部署：导出 GGUF 并运行于 Ollama

为了让模型走出实验室，跑在笔记本甚至树莓派上，我们需要将其转换为轻量化格式。

GGUF 是 llama.cpp 使用的二进制格式，支持 CPU 推理和多种量化等级（如 q4_k_m），非常适合边缘设备。

转换流程

1. 安装 gguf-py 工具

git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp/gguf-py pip install --editable .

2. 执行转换

cd .. python convert-hf-to-gguf.py ../merged-llama3-bot

生成如merged-llama3-bot-q4_k_m.gguf的文件。

3. 安装 Ollama

Linux 用户：

curl -fsSL https://ollama.com/install.sh | sh

4. 创建 Modelfile

FROM ./merged-llama3-bot-q4_k_m.gguf

注册模型：

ollama create mybot -f Modelfile

5. 运行模型

ollama run mybot

从此，你的定制 AI 助手就能脱离高性能 GPU，在任意设备上自由运行。

写在最后：为什么 LLaMA-Factory 值得关注？

在过去，微调一个大模型意味着组建专门团队、投入大量算力、编写复杂脚本。而现在，借助 LLaMA-Factory，一个人、一台消费级显卡、半天时间，就能完成从训练到部署的全流程。

它的价值不仅在于功能全面——支持 LoRA、QLoRA、全参数微调、多模态扩展；更在于其设计理念：降低认知成本，提升工程效率。

无论是想快速验证产品原型的创业者，还是希望深入研究微调机制的研究者，LLaMA-Factory 都提供了足够灵活又足够稳定的平台。

下一步，不妨尝试 QLoRA 量化训练，在 24GB 显存下挑战 70B 模型；或是探索 DeepSpeed 和 RLHF 对齐训练，让你的模型更具人类偏好。

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