LLaMA-Factory微调实战：从环境搭建到模型部署
LLaMA-Factory微调实战：从环境搭建到模型部署
在大语言模型（LLM）快速渗透各行各业的今天，一个现实问题摆在开发者面前：通用模型虽然强大，但在垂直场景中往往“说不到点子上”。比如客服系统需要精准响应商品政策，医疗助手必须避免模糊表达——这些都要求模型具备领域专精能力。而实现这一目标的关键，正是微调。
但传统微调流程复杂得令人望而却步：数据清洗、显存优化、分布式训练、评估验证……每一环都需要深厚的技术积累。对于个人开发者或资源有限的小团队来说，这几乎是一道难以逾越的门槛。
好在开源社区给出了优雅解法——LLaMA-Factory。它不仅支持包括 Qwen、Baichuan、ChatGLM、Mistral 在内的上百种主流架构，还集成了 LoRA、QLoRA 等高效参数微调技术，并通过统一接口打通了从训练到部署的全链路。更关键的是，它提供了基于 Gradio 的可视化界面，让非专业用户也能完成模型定制。
本文将以 Qwen-7B-Chat 模型 为例，在单张 RTX 3090（24GB 显存）环境下，带你完整走通一次基于 LoRA 的指令微调实战。我们将不依赖任何预设脚本，手把手完成环境配置、数据构建、训练推理、效果评估与服务部署全过程。
环境准备：打好地基才能盖高楼
再强大的框架也离不开稳定的运行环境。尤其在 GPU 计算密集的大模型任务中，一步配置出错就可能导致后续全流程失败。
先确认你的“武器”是否就绪
第一件事是检查 GPU 是否被系统正确识别：
nvidia-smi 你应该能看到类似输出：
+-----------------------------------------------------------------------------+ | NVIDIA-SMI 535.129.03 Driver Version: 535.129.03 CUDA Version: 12.2 | |-------------------------------+----------------------+----------------------+ | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. | |===============================+======================+======================| | 0 NVIDIA RTX 3090 Off | 00000000:01:00.0 Off | Off | | 30% 45C P2 80W / 350W | 2000MiB / 24576MiB | 5% Default | +-------------------------------+----------------------+----------------------+ 重点关注三项信息：
- CUDA 版本：建议使用 12.1 或以上版本；
- 显存容量：24GB 足以支撑 7B 模型的 LoRA 微调；
- 驱动状态：确保无报错且温度正常。
📌 实践建议：如果你正在使用云服务器，推荐选择 A10G/A100/V100 等具备大显存的专业卡；本地开发可优先考虑 RTX 3090/4090。
根据官方硬件需求表，不同规模模型对显存的要求如下：
| 模型规模 | 全参微调 | LoRA 微调 | QLoRA 微调 |
|---|---|---|---|
| 7B | ≥ 80GB | ≥ 24GB | ≥ 10GB |
| 13B | ≥ 160GB | ≥ 40GB | ≥ 16GB |
由此可见，单卡 3090 用户应果断放弃全参数微调，转而采用 LoRA 或 QLoRA。我们本次将采用 LoRA，兼顾性能与稳定性。
安装核心依赖：Python + PyTorch + LLaMA-Factory
创建独立环境，避免依赖冲突：
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 .[metrics] 安装完成后，务必做三重验证：
- PyTorch 是否可用 GPU
import torch print(torch.__version__) # 输出如 2.3.0+cu121 print(torch.cuda.is_available()) # 应返回 True print(torch.cuda.get_device_name(0)) # 应显示 RTX 3090 - 命令行工具是否注册成功
llamafactory-cli -h 若能打印帮助文档，则说明主包安装成功。
- 评估库是否就位
pip install jieba rouge-chinese nltk 这些是中文任务常用的评测工具，后续批量预测会用到。
下载并验证基础模型
尽管 LLaMA-Factory 支持自动拉取 Hugging Face 模型，但国内网络环境下常出现超时问题。因此我们推荐通过 ModelScope 手动下载：
from modelscope import snapshot_download model_dir = snapshot_download('qwen/Qwen-7B-Chat') print(model_dir) # 输出路径，例如 /root/.cache/modelscope/hub/qwen/Qwen-7B-Chat 或者使用 Git 方式克隆：
git clone https://www.modelscope.cn/qwen/Qwen-7B-Chat.git 下载完成后，先进行一次本地推理测试，确认模型完整性：
from transformers import AutoModelForCausalLM, AutoTokenizer import torch model_path = "/root/.cache/modelscope/hub/qwen/Qwen-7B-Chat" tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( model_path, device_map="auto", torch_dtype=torch.bfloat16, trust_remote_code=True ) prompt = "你是一个AI助手，请介绍一下你自己。" inputs = tokenizer(prompt, return_tensors="pt").to("cuda") outputs = model.generate( **inputs, max_new_tokens=200, do_sample=True, temperature=0.7, top_p=0.9 ) response = tokenizer.decode(outputs[0], skip_special_tokens=True) print(response) 如果顺利输出一段自我介绍，说明模型加载无误。这是后续所有操作的前提。
构建专属数据集：教会模型“说行话”
微调的本质是“教模型学会某种说话方式”，而这完全取决于你给它的训练数据。
LLaMA-Factory 支持两种主流格式：alpaca 和 sharegpt。前者适合单轮指令生成任务，后者适用于多轮对话。我们以电商文案生成为例，采用 alpaca 格式构建数据集。
数据结构定义
每条样本包含三个字段：
{ "instruction": "根据商品标签生成一段吸引人的文案", "input": "类型#连衣裙*风格#优雅*材质#雪纺*颜色#浅蓝", "output": "这款浅蓝色雪纺连衣裙，轻盈飘逸，尽显女性优雅气质..." } 将 500~1000 条此类样本保存为 JSON 文件：
mkdir data && vim data/adgen_custom.json 注册数据集以便框架识别
编辑 data/dataset_info.json，添加新条目：
"adgen_custom": { "file_name": "adgen_custom.json", "columns": { "instruction": "instruction", "input": "input", "output": "output" } } ⚠️ 注意：如果字段名一致，columns 可省略。但显式声明有助于后期维护。至此，你就可以在训练时通过 --dataset adgen_custom 引用该数据集，就像引用内置数据一样自然。
启动 LoRA 微调：用最小代价定制大模型
现在进入核心环节——启动训练。我们将使用命令行方式执行 SFT（Supervised Fine-Tuning），这是最常见也是最有效的微调范式。
以下是一套经过实测可在 3090 上稳定运行的配置：
CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \ --stage sft \ --do_train \ --model_name_or_path /root/.cache/modelscope/hub/qwen/Qwen-7B-Chat \ --dataset alpaca_en,adgen_custom \ --dataset_dir ./data \ --template qwen \ --finetuning_type lora \ --lora_target c_attn,c_proj \ --output_dir ./saves/Qwen-7B/lora/sft \ --overwrite_cache \ --overwrite_output_dir \ --cutoff_len 1024 \ --preprocessing_num_workers 8 \ --per_device_train_batch_size 2 \ --per_device_eval_batch_size 1 \ --gradient_accumulation_steps 8 \ --lr_scheduler_type cosine \ --logging_steps 10 \ --warmup_steps 20 \ --save_steps 50 \ --eval_steps 25 \ --evaluation_strategy steps \ --load_best_model_at_end \ --learning_rate 1e-4 \ --num_train_epochs 3.0 \ --max_samples 1000 \ --val_size 0.1 \ --plot_loss \ --fp16 参数设计背后的工程考量
--lora_target c_attn,c_proj：这是 Qwen 模型官方推荐的注入层。不要随意更改，否则可能影响效果。--per_device_train_batch_size 2+--gradient_accumulation_steps 8：等效于全局 batch size = 16，在显存和收敛速度之间取得平衡。--fp16：启用半精度训练，显著降低显存占用，同时加速计算。--val_size 0.1：自动划分 10% 训练数据作为验证集，无需手动拆分。--plot_loss：训练结束后自动生成损失曲线图，便于直观分析。
训练过程中，loss 应呈现稳步下降趋势。理想情况下，最终 loss < 1.5 表示模型已较好拟合数据。
动态加载 LoRA 进行推理测试
训练完成后，你不需要立即合并模型。LLaMA-Factory 支持动态加载 adapter 权重，实现“热插拔”式推理。
图形化交互测试
启动 WebChat 界面：
llamafactory-cli webchat \ --model_name_or_path /root/.cache/modelscope/hub/qwen/Qwen-7B-Chat \ --adapter_name_or_path ./saves/Qwen-7B/lora/sft \ --template qwen \ --finetuning_type lora 访问 http://localhost:7860 即可打开聊天窗口。输入原始模型无法很好处理的商品描述任务，观察其是否学会了新的表达风格。
命令行快速验证
也可以直接进入 CLI 模式：
llamafactory-cli chat \ --model_name_or_path /root/.cache/modelscope/hub/qwen/Qwen-7B-Chat \ --adapter_name_or_path ./saves/Qwen-7B/lora/sft \ --template qwen \ --finetuning_type lora 这种方式更适合调试 prompt 模板或测试边缘 case。
批量预测与量化评估：别只靠感觉判断好坏
人工测试只能定性判断，真正衡量模型提升需要定量指标。
执行批量预测
llamafactory-cli train \ --stage sft \ --do_predict \ --model_name_or_path /root/.cache/modelscope/hub/qwen/Qwen-7B-Chat \ --adapter_name_or_path ./saves/Qwen-7B/lora/sft \ --dataset adgen_custom \ --dataset_dir ./data \ --template qwen \ --finetuning_type lora \ --output_dir ./saves/Qwen-7B/lora/predict \ --per_device_eval_batch_size 1 \ --max_samples 50 \ --predict_with_generate 运行结束后，会在输出目录生成两个关键文件：
generated_predictions.jsonl：每条样本的输入、真实输出与模型生成结果，可用于人工复查；predict_results.json：自动计算的评估分数。
如何解读评估指标？
| 指标 | 含义 |
|---|---|
eval_bleu_4 | n-gram 匹配度，越高越好（0~100） |
eval_rouge-1, eval_rouge-2 | 单词/双词召回率 |
eval_rouge-l | 最长公共子序列匹配程度 |
predict_samples_per_second | 推理吞吐量，反映响应速度 |
你可以对比微调前后在同一测试集上的得分变化，从而客观判断训练效果。
合并 LoRA 模型：为部署做准备
当确认微调有效后，下一步通常是将 adapter 权重合并进基础模型，生成一个独立的 .bin 文件，方便跨平台部署。
执行导出命令：
llamafactory-cli export \ --model_name_or_path /root/.cache/modelscope/hub/qwen/Qwen-7B-Chat \ --adapter_name_or_path ./saves/Qwen-7B/lora/sft \ --template qwen \ --finetuning_type lora \ --export_dir ./merged_models/qwen-7b-adgen \ --export_device cpu \ --export_legacy_format false --export_device cpu：在 CPU 上执行合并，节省 GPU 显存；--export_legacy_format false：导出为现代 Safetensors 格式，更安全高效。
合并后的模型可像普通 HuggingFace 模型一样加载：
from transformers import AutoModelForCausalLM model = AutoModelForCausalLM.from_pretrained("./merged_models/qwen-7b-adgen") 使用 WebUI 提升效率：图形化不是“玩具”
虽然命令行更灵活，但 LLaMA-Factory 的 WebUI 并非摆设。它特别适合快速实验、教学演示或非技术人员协作。
启动面板：
llamafactory-cli webui 访问 http://localhost:7860/ui，你会看到五大功能模块：
- Train：可视化配置训练参数，支持导出 YAML；
- Evaluate：一键运行 MMLU、C-Eval 等 benchmark；
- Inference：在线聊天测试；
- Export：模型合并向导；
- API：服务部署配置。
⚠️ 当前 WebUI 仅支持单机单卡训练。多卡训练仍建议使用 CLI + YAML 配置。
一个实用技巧是：在 Train 页面填写参数后，点击 “Preview Command” 可实时查看对应命令行，方便迁移至生产脚本。
启动 API 服务：让模型真正“活”起来
最终目标往往是将模型接入外部系统，如前端应用、LangChain 工具链或企业后台。
LLaMA-Factory 内置了兼容 OpenAI API 协议的服务端，极大简化集成成本。
启动标准 API 服务
API_PORT=8000 llamafactory-cli api \ --model_name_or_path /root/.cache/modelscope/hub/qwen/Qwen-7B-Chat \ --adapter_name_or_path ./saves/Qwen-7B/lora/sft \ --template qwen \ --finetuning_type lora 服务启动后，即可使用标准 OpenAI 客户端调用：
from openai import OpenAI client = OpenAI( base_url="http://localhost:8000/v1", api_key="none" ) response = client.completions.create( model="qwen-7b-chat", prompt="请写一段关于夏日海滩的浪漫文案", max_tokens=200 ) print(response.choices[0].text) 使用 vLLM 加速高并发推理
若追求更高吞吐（如上线产品），建议结合 vLLM 推理引擎（需提前合并模型）：
API_PORT=8000 llamafactory-cli api \ --model_name_or_path ./merged_models/qwen-7b-adgen \ --infer_backend vllm \ --vllm_enforce_eager vLLM 支持连续批处理（Continuous Batching）和 PagedAttention，能在相同硬件下支撑数倍于原生 Transformers 的请求量。
评测模型通用能力：防止“学专了却变傻了”
一个常见的微调陷阱是“灾难性遗忘”——模型学会了新技能，却忘了原本的知识。
为此，LLaMA-Factory 提供了多种 benchmark 工具，用于评估微调前后在标准任务上的表现。
中文综合知识测试（C-Eval）
llamafactory-cli eval \ --model_name_or_path ./merged_models/qwen-7b-adgen \ --template qwen \ --task ceval \ --split test \ --lang zh \ --n_shot 3 涵盖人文、社科、理工等多个学科，全面检验模型知识保留情况。
英文常识理解测试（MMLU）
llamafactory-cli eval \ --model_name_or_path /root/.cache/modelscope/hub/qwen/Qwen-7B-Chat \ --adapter_name_or_path ./saves/Qwen-7B/lora/sft \ --template qwen \ --task mmlu \ --split validation \ --lang en \ --n_shot 5 \ --batch_size 1 输出示例：
Average: 62.1 STEM: 58.3 Humanities: 65.2 Social Sciences: 60.8 Other: 64.0 这些数字是你判断微调策略成败的重要依据。理想状态下，领域任务性能提升的同时，通用能力不应大幅下滑。
LLaMA-Factory 的价值远不止于“能跑起来”。它代表了一种工程化思维：把复杂的模型定制过程标准化、模块化、可复现化。无论你是想快速验证一个想法的产品经理，还是深耕 NLP 的研究员，这套工具链都能显著压缩试错周期。
更重要的是，它持续吸纳最新研究成果——从 QLoRA 到 NAS，从多模态到 RLHF，都在逐步集成中。这意味着你今天掌握的技能，在未来依然具有延展性。
如果你正站在通往大模型应用落地的路上，那么 LLaMA-Factory 绝不是一个可选项，而是必经之路。
