基于 LLaMA-Factory 的大模型 LoRA 微调实战指南

import torch
import warnings
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig

# 屏蔽警告并强制锁定 GPU
warnings.filterwarnings('ignore', category=UserWarning, module='torch.cuda')
torch.cuda.set_device(0)
device = "cuda:0" if torch.cuda.is_available() else "cpu"

# 4bit 量化配置
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4"
)

model_id = "/workspace/Meta-Llama-3-8B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token

# 加载量化模型
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    quantization_config=bnb_config,
    torch_dtype=torch.bfloat16,
    device_map=device,
    trust_remote_code=True,
    low_cpu_mem_usage=True
)

# 验证 GPU 加载
assert next(model.parameters()).device == torch.device(device), "模型加载失败！未使用 GPU！"
print(f"✅ 模型已 100% 加载到 GPU → {torch.cuda.get_device_name(0)}")

# 简单对话测试
messages = [
    {"role": "system", "content": "You are a pirate chatbot who always responds in pirate speak!"},
    {"role": "user", "content": "Who are you?"}
]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(prompt, return_tensors="pt").to(device)
terminators = [tokenizer.eos_token_id, tokenizer.convert_tokens_to_ids("<|eot_id|>")]
outputs = model.generate(
    **inputs,
    max_new_tokens=256,
    eos_token_id=terminators,
    do_sample=True,
    temperature=0.6,
    top_p=0.9,
    pad_token_id=tokenizer.eos_token_id
)
response = tokenizer.decode(outputs[0][len(inputs["input_ids"][0]):], skip_special_tokens=True)
print("===== 🏴‍☠️ 海盗机器人回答 🏴‍☠️ =====")
print(response)

WebUI 测试

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
    --model_name_or_path /workspace/Meta-Llama-3-8B-Instruct \
    --template llama3

注意： model_name_or_path 可以是 HuggingFace 或 ModelScope 的模型名称，也可以是本地绝对路径。template 参数至关重要，不同模型必须使用对应的 Prompt 模板（如 Meta-Llama-3-8B 对应 llama3），否则容易出现重复生成等问题。

准备数据集

打开 WebUI 界面后，可以在数据管理模块添加数据集。魔搭社区（ModelScope）集成了丰富的中文数据集，分类清晰。

LLaMA-Factory 目前主要支持两种格式的数据集：Alpaca 和 ShareGPT。你需要将数据文件放到 data 目录下，并在配置文件 dataset_info.json 中添加一条记录，这样新数据集才能被识别。

以角色扮演类数据集为例，下载 huanhuan.json 文件放入 data 目录，并在配置文件中注册该数据集。保存后 WebUI 会自动刷新，无需重启服务。

执行微调

本次实战以 Qwen3-1.7B-Base 为基础模型，采用 LoRA 方式进行指令微调。

Base 模型特点：

• 基础预训练模型，未经过指令微调。
• 适合继续预训练或指令微调。
• 通常输出质量不如 Instruct 版本，但灵活性更高。

关键参数配置思路：

• Epochs： 先训练 1 轮看效果。样本少时 Epoch 可设大些，样本多（十万级以上）一般 2 个 Epoch 即可收敛。过拟合虽不好，但比欠拟合更容易调整。
• 学习率： LoRA 经验值通常在 1e-5 ~ 2e-5。
• 截断长度： 短问答数据集可将 cutoff_len 设为 1024（默认 2048）。
• 梯度累计： 设置为 4 以平衡显存与 Batch Size。
• 计算类型： 选择 BF16，暂不支持 FP4。
• LoRA 秩 (Rank)： 视为学习广度，设为 8 即可，过大易过拟合。
• LoRA Alpha： 视为学习强度，设为 256。

训练命令示例：

llamafactory-cli train \
    --stage sft \
    --do_train True \
    --model_name_or_path Qwen/Qwen3-1.7B-Base \
    --preprocessing_num_workers 16 \
    --finetuning_type lora \
    --template qwen3 \
    --flash_attn auto \
    --dataset_dir data \
    --dataset huanhuan \
    --cutoff_len 1024 \
    --learning_rate 5e-05 \
    --num_train_epochs 4.0 \
    --max_samples 100000 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 4 \
    --lr_scheduler_type cosine \
    --max_grad_norm 1.0 \
    --logging_steps 5 \
    --save_steps 100 \
    --warmup_steps 4 \
    --packing False \
    --enable_thinking True \
    --report_to none \
    --output_dir saves/Qwen3-1.7B-Base/lora/train_2026-01-02-06-40-31 \
    --bf16 True \
    --plot_loss True \
    --trust_remote_code True \
    --ddp_timeout 180000000 \
    --include_num_input_tokens_seen True \
    --optim adamw_torch \
    --adapter_name_or_path saves/Qwen3-1.7B-Base/lora/train_2026-01-02-06-01-20 \
    --lora_rank 8 \
    --lora_alpha 256 \
    --lora_dropout 0 \
    --lora_target all

参数解读：

• stage: 训练阶段，此处为 SFT（有监督指令微调）。
• finetuning_type: 微调类型，选用 lora。
• output_dir: Checkpoint 保存位置。
• adapter_name_or_path: LoRA 适配器路径。

训练开始后，系统会启动独立进程。若本地无模型，会自动从 ModelScope 下载。训练过程中可查看 Loss 曲线监控进度。当看到'训练完毕'提示即代表成功。

Checkpoint 结构： 训练结果保存在 output_dir 下，主要包括：

• adapter_model.safetensors: LoRA 权重文件。
• training_loss.png: 损失曲线图。
• trainer_state.json: 训练状态记录。

效果评估： 微调完成后，可在 Chat 页面加载模型进行测试。初次训练效果可能不佳，增加 Epoch 数（如 3 轮）通常能显著提升表现。加载时需指定 --finetuning_type lora 及 --adapter_name_or_path 路径。

批量推理和训练效果评估

人工交互测试不够严谨，建议使用自动化指标进行评估，如 BLEU 和 ROUGE。

pip install jieba rouge-chinese nltk

预测命令： 与训练命令类似，主要区别在于开启预测模式：

• do_predict: 启用预测。
• predict_with_generate: 生成文本。
• eval_dataset: 指定用于评估的数据集。

llamafactory-cli train \
    --stage sft \
    --model_name_or_path Qwen/Qwen3-1.7B-Base \
    --finetuning_type lora \
    --quantization_method bnb \
    --template qwen3 \
    --flash_attn auto \
    --dataset_dir data \
    --eval_dataset huanhuan \
    --cutoff_len 1024 \
    --max_samples 100000 \
    --per_device_eval_batch_size 4 \
    --predict_with_generate True \
    --report_to none \
    --max_new_tokens 512 \
    --top_p 0.7 \
    --temperature 0.95 \
    --output_dir saves/Qwen3-1.7B-Base/lora/eval_2026-01-02-19-59-30 \
    --trust_remote_code True \
    --ddp_timeout 180000000 \
    --do_predict True \
    --adapter_name_or_path saves/Qwen3-1.7B-Base/lora/train_2026-01-02-06-40-31

指标解读：

• BLEU-4: 衡量四元语法匹配度，越高越相似。
• ROUGE-1/2/L: 分别衡量一元、二元词序列及最长公共子序列匹配度。对于开放问答任务，ROUGE-1 在 8-15 之间属标准水平。
• 性能指标: 关注 predict_runtime（总耗时）和 predict_samples_per_second（吞吐量）。

对比 1 Epoch 和 3 Epoch 的结果，通常多轮训练后的各项指标会更优。

LoRA 模型合并导出

训练满意后，需将 LoRA 权重与原始 Base 模型融合，生成完整模型文件。

在 WebUI 切换到 Export 页面，选择微调好的 Checkpoint，填写导出目录（如 output/qwen3-1.7b-huanhuan）。导出完成后，目录下会包含完整的模型文件（model.safetensors 等），可直接用于部署。

部署运行微调后的大模型

最终模型可转换为 GGUF 格式，配合 Ollama 进行高效部署。

转换 GGUF：

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp/gguf-py
pip install --editable .
cd ../.. # 回到 llama.cpp 根目录
python convert_hf_to_gguf.py /workspace/LlamaFactory/output/Qwen3-1.7B-huanhuan/

Ollama 部署：

curl -fsSL https://ollama.com/install.sh | sh
ollama serve
ollama create qwen3-huanhuan -f /workspace/LlamaFactory/output/Qwen3-1.7B-huanhuan/Modelfile
ollama run qwen3-huanhuan

GGUF 格式能有效压缩模型体积，降低内存占用，提升推理速度；Ollama 则是轻量级且高效的推理框架，非常适合个人环境使用。