本地部署LLaMA-Factory全指南

Ne0inhk

22 Mar 2026 — 10 min read

本地部署LLaMA-Factory全指南

在大模型技术飞速发展的今天，如何让普通人也能轻松定制属于自己的AI助手？这曾是一个遥不可及的梦想。但随着 LLaMA-Factory 这类开源项目的出现，微调一个大语言模型不再只是顶级实验室的专利。它把复杂的训练流程封装成可点击的操作，甚至不需要写一行代码，就能完成从数据准备到模型部署的全过程。

如果你有一块消费级显卡，比如 RTX 3060 或更高，那么你已经具备了动手实践的基础条件。本文将带你一步步搭建环境、加载模型、配置训练参数，并最终生成一个能理解中文指令的个性化 Qwen 模型——整个过程就像使用图形化软件一样自然流畅。

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

再强大的框架也离不开硬件支撑。虽然 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 创造的门槛——无论是研究人员、开发者，还是普通爱好者，都可以基于自己的数据和需求，定制专属的语言模型。

更重要的是，这种“低代码 + 高性能”的设计思路，正在成为下一代 AI 工具的标准范式。未来，我们或许会看到更多类似框架出现在图像生成、语音合成等领域。

🌟 下一步你可以尝试：
- 升级到 Qwen-7B 模型，挑战全参数微调；
- 接入企业客服对话数据，构建专属智能助手；
- 结合 RAG 架构，打造知识增强型问答系统。

别再观望，立即动手吧。属于每个人的 AI 定制时代，已经到来。

本地部署LLaMA-Factory全指南

Ne0inhk