跳到主要内容LLaMA-Factory 大模型 LoRA 微调实战指南 | 极客日志PythonAI算法
LLaMA-Factory 大模型 LoRA 微调实战指南
介绍使用 LLaMA-Factory 进行大模型微调的全流程，涵盖安装部署、数据集准备、LoRA 微调训练、效果评估及模型合并导出。通过 WebUI 和命令行操作，演示了基于 Qwen3-1.7B 模型的指令微调方法，并包含批量推理测试与 Ollama 部署方案，适合开发者快速上手大模型定制。
DebugKing1 浏览 LLaMA-Factory
Llama-Factory 是基于 transformers 库开发的训练、微调、推理一体化平台，支持预训练、指令监督微调、奖励模型训练、PPO 训练、DPO 训练、KTO 训练、ORPO 训练等多种训练范式。支持使用 Accelerate 或 DeepSpeed 作为训练加速后端。
使用 Llama-Factory 进行微调非常简单，因为其最大的优势在于强大的数据处理与训练配置能力。只要按照官方的文档配置好环境，直接运行对应的脚本即可。
LLaMA-Factory + Qwen3-7B + LoRA
安装部署
git clone https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
cd docker/docker-cuda/
docker build -f ./docker/docker-cuda/Dockerfile \
--build-arg PIP_INDEX=https://pypi.org/simple \
--build-arg EXTRAS=metrics \
-t llamafactory:latest
docker run -dit --ipc=host --gpus=all \
-p 7860:7860 \
-p 8000:8000 \
--name llamafactory \
llamafactory:latest
docker exec -it llamafactory bash
cd workspace
git clone https://github.com/hiyouga/LlamaFactory.git
docker run -d --network=host --restart=always --name=llamafactory-dev \
--gpus=all --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 \
-v "$PWD":/workspace -w /workspace \
nvcr.io/nvidia/pytorch:25.08-py3 \
tail -f /dev/null
docker exec -it -u root llamafactory-dev bash
mkdir -p ~/.pip
cat > ~/.pip/pip.conf <<EOF
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF
pip uninstall -y torch torchvision torchaudio nvidia-cublas nvidia-cudnn-cu12
pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple --index-url https://download.pytorch.org/whl/cu130
pip install --upgrade nvidia-cublas nvidia-cudnn-cu13
cd LlamaFactory
pip install -e
微信扫一扫，关注极客日志
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
相关免费在线工具
- 加密/解密文本
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
- RSA密钥对生成器
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
- Mermaid 预览与可视化编辑
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
- curl 转代码
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
- Base64 字符串编码/解码
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
- Base64 文件转换器
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
'.[torch,metrics]'
llamafactory-cli train -h
python
import torch
torch.cuda.current_device()
torch.cuda.get_device_name(0)
torch.__version__
pip install modelscope
modelscope download --model LLM-Research/Meta-Llama-3-8B-Instruct --local_dir /workspace/Meta-Llama-3-8B-Instruct
pip install -U bitsandbytes -i https://pypi.tuna.tsinghua.edu.cn/simple
vim test-inf.py
import torch
import warnings
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
warnings.filterwarnings('ignore', category=UserWarning, module='torch.cuda')
torch.cuda.set_device(0)
device = "cuda:0" if torch.cuda.is_available() else "cpu"
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
)
assert next(model.parameters()).device == torch.device(device), "模型加载失败！未使用 GPU！"
print(f"✅ 模型已 100% 加载到 GPU → {torch.cuda.get_device_name(0)}")
print(f"✅ PyTorch 版本：{torch.__version__} | CUDA 版本：{torch.version.cuda}")
print(f"✅ 运行模式：4bit 无损量化 | 显存占用≈8.5GB (减半)")
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)
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 的模型名称，如 meta-llama/Meta-Llama-3-8B-Instruct；或者是本地下载的绝对路径。
template：模型问答时所使用的 prompt 模板，不同模型使用各自的模版，否则会出现回答结果重复生成等奇怪现象。比如 Meta-Llama-3-8B 的 template 就是 llama3。
准备数据集
cd LlamaFactory/
export USE_MODELSCOPE_HUB=1
llamafactory-cli webui
魔搭社区集成了相当丰富的中文数据集，有很多分类可以选。
注意，Llama-Factory 目前只支持两种格式的数据集：Alpaca 和 ShareGPT 格式。
切换到数据集文件这边，打开 huanhuan.json 文件，看到它其实就是 Alpaca 格式的数据集，仅下载这一个文件即可。
在 Llama-Factory 添加数据集，不仅要把数据文件放到 data 目录下，还需要在配置文件 dataset_info.json 里面添加一条该数据集的记录。这样，新添加的数据集才能被 Llama-Factory 识别到。
这里保存之后，WebUI 那边会实时更新，不需要重启。
执行微调
微调 Qwen3-1.7B-Base 基础大模型，方法选用 LoRA。
-
Base 基础预训练模型。
-
没有经过指令微调。
-
适合继续预训练或指令微调。
-
Base 通常情况下输出质量不如 Instruct 版本。
-
使用 huanhuan 数据集。
-
先训练 1 轮看看效果，如果效果不理想再多训练几轮。如果 SFT 样本较少，可以设置较大 Epoch。较小 Epoch 的 loss 会不收敛，较大 Epoch 会容易导致过拟合，但过拟合要优于欠拟合。如果 SFT 样本数量较多，如在十万以上，一般 2 个 Epoch 即可收敛。
-
学习率控制模型权重更新步幅的参数，按照经验来讲，LoRA 选择在 1e-5 ~ 2e-5。
-
由于数据集都是一些短问答，可以把截断长度设置小一点，为 1024（默认是 2048）。
-
梯度累计设置为 4。
预热步数是学习率预热采用的步数，通常设置范围在 2-8 之间，这里配置为 4。
- LoRA 秩：可以看作学习的广度，越大学习的东西越多，微调之后的效果可能会越好，但是也不是越大越好。太大的话容易造成过拟合（书呆子，照本宣科，不知变通），这里设置为 8。
- LoRA 缩放系数：可以看作学习强度，越大效果可能会越好，对于一些用于复杂场景的数据集可以设置更大一些，简单场景的数据集可以稍微小一点。这里设置 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、pt、rm、ppo 等，这里我们是有监督指令微调，所以是 sft。do_train：是否是训练模式。dataset：使用的数据集。dataset_dir：数据集所在目录，这里是 data。finetuning_type：微调训练的类型，枚举值 lora、full、freeze 等，这里使用 lora。output_dir：训练 Checkpoint 保存的位置。cutoff_len：训练数据集的长度截断。per_device_train_batch_size：每个设备上的 batch size，最小是 1，如果 GPU 显存够大，可以适当增加。bf16：训练数据精度格式。max_samples：每个数据集采样多少数据。val_size：随机从数据集中抽取多少比例的数据作为验证集。logging_steps：定时输出训练日志，包含当前 loss，训练进度等。adapter_name_or_path：LoRA 适配器路径。
微调成功后，我们得到了一个 Checkpoint 记录，下拉可以选择刚刚微调好的模型。
Checkpoint 在后台的存储位置是 saves/Qwen3-1.7B-Base/lora/：
adapter 开头的是 LoRA 适配器结果，后续用于模型推理融合。training_loss 和 trainer_log 等记录了训练过程中的指标。- 其他是训练时各种参数的备份。
加载好之后就可以在输入框发送问题，测试微调模型的效果。
对 LoRA 微调模型进行推理，需要应用动态合并 LoRA 适配器的推理技术。需要通过 finetuning_type 参数告诉使用了 LoRA 训练，然后将 LoRA 的模型位置通过 adapter_name_or_path 参数即可。
如果想切换回微调之前的模型，只需先卸载模型，选择想要的 Checkpoint，然后再加载模型即可。
在经过 3 个 Epoch 的训练之后，效果也越好越好了。
批量推理和训练效果评估
上文中的人工交互测试实际上并不严谨，通常我们需要进行自动化的批量测试。例如：使用自动化的 BLEU 和 ROUGE 等常用的文本生成指标来做评估。
pip install jieba
pip install rouge-chinese
pip install nltk
do_predict：现在是预测模式。predict_with_generate：现在用于生成文本。max_samples：每个数据集采样多少用于预测对比。
llamafactory-cli train \
--stage sft \
--model_name_or_path Qwen/Qwen3-1.7B-Base \
--preprocessing_num_workers 16 \
--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，衡量模型生成文本的好坏、和标准答案的匹配度、内容质量优劣。
- BLEU-4（Bilingual Evaluation Understudy）：是一种常用的用于评估机器翻译质量的指标。BLEU-4 表示四元语法 BLEU 分数，它衡量模型生成文本与参考文本之间的 n-gram 匹配程度，其中 n=4。值越高表示生成的文本与参考文本越相似，最大值为 100%。
- predict_rouge-1（Recall-Oriented Understudy for Gisting Evaluation）：是一种用于评估自动摘要和文本生成模型性能的指标。ROUGE-1 表示一元 ROUGE 分数，衡量模型生成文本与参考文本之间的单个词序列的匹配程度，即：词汇层面的匹配度，看生成文本有没有用到标准答案里的核心词。值越高表示生成的文本与参考文本越相似，最大值为 100。
- predict_rouge-2：ROUGE-2 表示二元 ROUGE 分数，衡量模型生成文本与参考文本之间的双词序列的匹配程度，即：短语 / 短句层面的匹配度。同上，最大值为 100。
- predict_rouge-l：ROUGE-L 表示最长公共子序列匹配率，衡量模型生成文本与参考文本之间最长公共子序列（Longest Common Subsequence）的匹配程度，即：整句的语义连贯性和语序一致性。同上，最大值为 100。
如果是文本摘要任务，那么 rouge-1 一般 20-40，rouge-2 5-15，rouge-L 10-25；如果是开放问答 / 对话 / 指令遵循任务，那么 rouge-1 8-15，rouge-2 1-3，rouge-L 3-6。
性能类指标：耗时 / 吞吐量 / 加载时间，衡量模型推理速度、效率、硬件利用率。
- predict_model_preparation_time：表示模型加载和预热（显存初始化）的耗时。
- predict_runtime：本次批量推理的总耗时，单位为秒。
- predict_samples_per_second：每秒推理生成的样本数量，推理吞吐量核心指标的核心指标，表示模型每秒钟能够生成的样本数量。用于评估模型的推理速度。
- predict_steps_per_second：每秒执行的 step 数量，模型每秒钟能够执行的 step 数量。模型每生成一个 token 就是一个 step。
通过对比 1 Epoch 和 3 Epoch 微调的结果可以看出，多轮训练后的效果会更好一些。
训练后也会在 output_dir 下看到如下新文件：
generated_predictions.jsonl：输出了要预测的数据集的原始 label 和模型 predict 的结果。predict_results.json：给出了原始 label 和模型 predict 的结果，用自动计算的指标数据。
LoRA 模型合并导出
通过不断'炼丹'直到效果满意后就可以导出模型了。即：把训练的 LoRA 模型和原始 Base 模型进行融合，输出一个完整的模型文件。
检查点路径选择我们刚刚微调好的模型，切换到 Export，填写导出目录 output/qwen3-1.7b-huanhuan。
导出完成之后就可以在 output 目录下看到 qwen3-1.7b-huanhuan 目录了。
部署运行微调后的大模型
其中，GGUF 是大模型的存储格式，可以对模型进行高效的压缩，减少模型的大小与内存占用，从而提升模型的推理速度和效率。
git clone https://github.com/ggerganov/llama.cpp.git
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
