本地部署 LLaMA-Factory 全指南

本地部署 LLaMA-Factory 全指南

本文介绍如何在本地使用 LLaMA-Factory 进行大语言模型的微调与部署。

硬件与环境检查：你的设备准备好了吗？

虽然 LLaMA-Factory 支持 CPU 推理，但真正想跑通一次像样的微调任务，GPU 是必不可少的。

打开终端，先执行这条命令：

nvidia-smi 

如果能看到类似下面的信息，说明你的 NVIDIA 显卡驱动和 CUDA 环境基本正常：

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.86.05 Driver Version: 535.86.05 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 4090 Off | 00000000:01:00.0 Off | N/A |
| 30% 45C P8 25W / 450W | 1024MiB / 24576MiB | 5% Default |
+-------------------------------+----------------------+----------------------+

重点关注三点：

• CUDA 版本 ≥ 11.8：这是 PyTorch 训练的底线要求；
• 显存 ≥ 16GB：推荐用于 7B 模型的 QLoRA 微调；若只跑 3B 模型，12GB 显存勉强够用；
• 多卡支持：如果有多个 GPU，可以并行加速训练。

⚠️ 如果命令报错或显示'NVIDIA-SMI has failed'，那可能是驱动未安装。请先前往 NVIDIA 官网 下载对应驱动，并安装 CUDA Toolkit。

开始部署：从零搭建运行环境

克隆项目源码

我们先创建一个专属工作目录：

mkdir llama-factory-project && cd llama-factory-project 

接下来克隆仓库。考虑到国内网络情况，建议使用 Gitee 镜像源：

git clone https://gitee.com/hiyouga/LLaMA-Factory.git 

当然，如果你的 GitHub 访问稳定，也可以直接拉取官方仓库（带 --depth 1 可节省时间）：

git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git 

完成后你会看到 LLaMA-Factory 文件夹出现在当前路径下。

创建 Conda 虚拟环境

为了避免依赖冲突，强烈建议使用 Conda 管理 Python 环境：

conda create -n llama_factory python=3.10 -y conda activate llama_factory 

激活后，命令行提示符前应该会出现 (llama_factory) 标识。

安装核心依赖

进入项目根目录，执行安装命令：

cd LLaMA-Factory pip install --upgrade pip pip install -e ".[torch,metrics]" 

这个命令会自动安装一系列关键库：

• transformers, datasets, peft, accelerate
• trl（用于强化学习）
• sentencepiece, safetensors, bitsandbytes（支持量化训练）

安装完成后，验证是否成功：

llamafactory-cli version 

如果返回版本号（如 v0.9.0），恭喜你，核心组件已就位。

验证 GPU 可用性

最后一步，确认 PyTorch 是否识别到了你的 GPU：

import torch 
print("CUDA Available:", torch.cuda.is_available()) 
print("GPU Count:", torch.cuda.device_count()) 
print("Current Device:", torch.cuda.current_device()) 
print("Device Name:", torch.cuda.get_device_name(0)) 
print("PyTorch Version:", torch.__version__) 

预期输出示例：

CUDA Available: True 
GPU Count: 1 
Current Device: 0 
Device Name: NVIDIA GeForce RTX 4090 
PyTorch Version: 2.3.0+cu121 

只要 CUDA Available 为 True，就可以放心进入下一步了。

启动 WebUI：开启可视化操作时代

LLaMA-Factory 提供图形化界面，可以在浏览器里完成模型微调。

启动服务只需一条命令：

llamafactory-cli webui 

首次运行时会自动下载 Gradio 并启动本地服务器，默认地址是：

http://127.0.0.1:7860

打开浏览器访问该链接，你会看到一个功能完整的控制台：

• 左侧导航栏清晰划分出【模型加载】、【训练配置】、【数据集管理】等模块；
• 支持中英文切换，对中文用户非常友好；
• 实时展示 loss 曲线、GPU 利用率、训练日志等关键信息。

💡 小技巧：添加 --host 0.0.0.0 --port 8080 参数可以让局域网内的其他设备访问你的服务。

获取预训练模型：选择适合你的起点

LLaMA-Factory 本身不包含模型权重，你需要自行从 Hugging Face 或 ModelScope 下载。

以下是两个主流平台对比：

平台	地址	特点
🤗 Hugging Face	https://huggingface.co/models	国际主流平台，模型丰富，但需科学上网
🔧 魔搭社区（ModelScope）	https://modelscope.cn/models	国内高速访问，适合中文用户

我们以阿里云的 Qwen2.5-3B-Instruct 为例进行演示。

方法一：使用 Git LFS 下载（推荐）

git lfs install 
git clone https://www.modelscope.cn/qwen/Qwen2.5-3B-Instruct.git models/qwen2.5-3b-instruct 

注意：建议将模型统一放在项目下的 models/ 目录中，便于后续引用。

方法二：通过 ModelScope SDK 下载

先安装 SDK：

pip install modelscope 

再运行 Python 脚本：

from modelscope.hub.snapshot_download import snapshot_download 
model_dir = snapshot_download('qwen/Qwen2.5-3B-Instruct', cache_dir='./models') 
print(f"Model saved to {model_dir}") 

下载完成后，目录结构大致如下：

LLaMA-Factory/
├── models/
│   └── qwen2.5-3b-instruct/
│       ├── config.json
│       ├── model.safetensors
│       ├── tokenizer.model
│       └── ...

这套标准化结构能让 LLaMA-Factory 自动识别模型类型和分词器配置。

配置并启动 QLoRA 微调任务

现在进入重头戏：通过 WebUI 完成一次完整的微调流程。

设置模型参数

打开 WebUI 的【训练】页面，填写以下内容：

字段	值
模型名称	qwen/Qwen2.5-3B-Instruct
模型路径	./models/qwen2.5-3b-instruct
适配器名称	lora_rank_8
微调方法	LoRA
量化等级	bitsandbytes-int4

✅ 使用 int4 量化能显著降低显存占用（约减少 60%），非常适合消费级显卡用户。

点击【加载模型】按钮，等待模型初始化完成。

选择训练数据集

LLaMA-Factory 内置了多个常用数据集模板，例如 alpaca_zh, firefly, dolly-chinese 等。

本次我们选用 alpaca_zh 中文指令数据集：

• 包含 instruction, input, output 三字段；
• 来源于 Hugging Face 上的 Chinese-Alpaca-Data。

如果你想上传自定义数据：

1. 把 .json 或 .csv 文件放入 data/ 目录；
2. 在 WebUI 中选择【自定义数据集】；
3. 配置字段映射规则即可。

配置超参数：平衡性能与资源消耗

设置一组典型的 QLoRA 参数：

参数	值	说明
学习率	2e-4	AdamW 默认初始值
批大小	16	Global batch size
梯度累积步数	4	提升有效批大小
训练轮数	3	防止过拟合
LoRA 秩 (r)	8	控制新增参数规模
LoRA Alpha	16	一般设为 2×r
Dropout	0.1	正则化防止过拟合
最大序列长度	512	平衡上下文长度与显存占用

还可以启用一些高级优化选项：

• ✅ 使用 FlashAttention-2 加速注意力计算
• ✅ 开启梯度检查点（Gradient Checkpointing）节省显存
• ✅ 启用 WANDB 日志记录，便于实验追踪

这些配置组合起来，能在有限资源下实现高效训练。

启动训练

点击【预览命令】，系统会自动生成对应的 CLI 指令，例如：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
 --model_name_or_path ./models/qwen2.5-3b-instruct \
 --do_train \
 --dataset alpaca_zh \
 --finetuning_type lora \
 --lora_rank 8 \
 --output_dir output/qwen_lora_3b \
 --per_device_train_batch_size 4 \
 --gradient_accumulation_steps 4 \
 --learning_rate 2e-4 \
 --num_train_epochs 3.0 \
 --max_seq_length 512 \
 --quantization_bit 4 \
 --fp16 

确认无误后，点击【开始】按钮，训练正式开始。

实时监控：掌控每一步进展

训练启动后，WebUI 会实时更新以下信息：

• Loss 曲线图：观察是否平稳下降；
• GPU 显存与利用率：确保没有爆显存；
• 实时日志输出：查看每步状态；
• 预估剩余时间：动态更新 ETA。

通常情况下，每 100 步保存一次 checkpoint，文件位于 output/ 目录下。

📌 强烈建议定期备份 output/ 文件夹！一旦断电或程序崩溃，未合并的 LoRA 权重可能丢失。

模型合并与导出：打造独立可用的新模型

训练结束后，LoRA 权重只是附加在原模型上的'补丁'。要想独立部署，必须将其与基础模型融合。

使用 WebUI 合并

进入【合并适配器】页面：

• 基础模型路径：./models/qwen2.5-3b-instruct
• 输出路径：merged_models/qwen2.5-3b-instruct-lora-merged
• 点击【开始合并】

系统会自动执行权重融合，最终生成标准 Hugging Face 格式的模型目录。

命令行方式（备用）

llamafactory-cli export \
 --model_name_or_path ./models/qwen2.5-3b-instruct \
 --adapter_name_or_path output/qwen_lora_3b \
 --export_dir merged_models/qwen2.5-3b-instruct-lora-merged \
 --export_quantization_bit 4 \
 --export_device cuda 

合并后的模型可用于：

• 本地交互测试
• 部署为 API 服务
• 上传至 Hugging Face 分享给社区

推理与部署：让你的模型真正'说话'

本地交互式推理

快速测试微调效果：

llamafactory-cli chat \
 --model_name_or_path merged_models/qwen2.5-3b-instruct-lora-merged 

输入问题，比如'请写一首关于春天的诗'，看看它的回答是否有'个性'提升。

启动 API 服务

将模型暴露为 RESTful 接口：

llamafactory-cli api \
 --model_name_or_path merged_models/qwen2.5-3b-instruct-lora-merged \
 --port 8080 

然后通过 curl 测试：

curl -X POST "http://127.0.0.1:8080" \
-H "Content-Type: application/json" \
-d '{ "messages": [{"role": "user", "content": "请介绍一下你自己"}] }' 

响应示例：

{
 "response": "我是经过指令微调的 Qwen 模型，能够更好地理解和回答中文问题……"
}

这意味着你的模型已经准备好接入前端应用、聊天机器人或知识库系统。

总结

完成上述步骤后，即可实现本地模型的微调与推理部署。LLaMA-Factory 提供了从环境搭建到模型部署的一站式解决方案，降低了 AI 创造的门槛。开发者可以基于自己的数据和需求，定制专属的语言模型。