本地部署LLaMA-Factory全指南
本地部署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 并启动本地服务器，默认地址是：
打开浏览器访问该链接，你会看到一个功能完整的控制台：
- 左侧导航栏清晰划分出【模型加载】、【训练配置】、【数据集管理】等模块；
- 支持中英文切换，对中文用户非常友好；
- 实时展示 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 定制时代，已经到来。
