本地部署 LLaMA-Factory 全指南

⚠️ 如果命令报错或显示'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 下载。

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

我们以阿里云的 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 的【训练】页面，填写以下内容：

✅ 使用 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 参数：

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

• ✅ 使用 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 定制时代，已经到来。