本地部署 LLaMA-Factory 实现大模型微调与推理
在智能应用日益个性化的今天，通用大模型虽然强大，但在特定领域——比如医疗咨询、法律问答或企业客服中——往往'说得漂亮却不够专业'。要让 AI 真正理解行业语境、输出精准内容，关键在于领域适配的微调。然而，从环境配置到训练部署，传统流程动辄几十行命令、层层依赖冲突，对开发者极不友好。
有没有一种方式，能让开发者不用写代码、不必深究底层细节，就能完成从模型加载、数据准备到训练和推理的全流程？答案是：有。LLaMA-Factory 正是为此而生。
它被称为'大模型微调的一站式工厂'，不仅支持包括 Qwen、Llama、Baichuan、ChatGLM 等数十种主流架构，还统一了全参数微调、LoRA、QLoRA 等多种高效训练方法，并通过一个直观的 WebUI 界面，把复杂的操作变成点选配置。哪怕你是第一次接触模型微调，也能在一个下午内跑通整个流程。
下面我们就以 Qwen2.5-3B-Instruct 模型为例，带你从零开始，在本地完成一次完整的微调实验，并最终启动 API 服务，让你的专属模型对外提供能力。
环境准备：硬件与软件双管齐下
显卡不是越贵越好，但显存一定要够
大模型训练最吃资源的是显存。如果你打算做全参数微调，那至少得上 A100 或 RTX 4090 这类 24GB 显存的卡；但如果是做 QLoRA 微调或者只是推理，一张 RTX 3090（24GB）甚至 RTX 3060（12GB） 都能胜任中小模型。
我们推荐的最低配置如下：
- GPU 显存 ≥ 8GB（QLoRA/推理可用）
- 内存 ≥ 32GB
- 存储空间 ≥ 100GB（模型文件动辄几个 GB）
先确认你的 GPU 是否已被系统识别：
nvidia-smi
如果能看到类似 GeForce RTX 3090 和显存使用情况，说明驱动已就绪。否则请前往 NVIDIA 官网 安装对应驱动。
⚠️ 注意：CUDA 驱动版本需与 PyTorch 兼容。建议安装 CUDA Toolkit 11.8 或 12.1，避免版本错配导致
torch.cuda.is_available()返回False。
Python 环境隔离：用 Conda 避免'依赖地狱'
LLaMA-Factory 基于 Python 构建，核心依赖包括：
- Python ≥ 3.9（推荐 3.10）
- PyTorch + CUDA 支持
- Hugging Face 生态库（Transformers, Datasets, Accelerate）
- Peft（用于 LoRA/QLoRA）
- Bitsandbytes（4-bit 量化支持）
- Gradio（WebUI）
为了避免与其他项目冲突，强烈建议使用 Conda 创建独立环境：
conda create -n llama_factory python=3.10 conda activate llama_factory
激活后终端前缀会显示 (llama_factory)，表示已进入专属环境。
安装 LLaMA-Factory：一条命令搭建完整流水线
克隆源码并安装依赖
LLaMA-Factory 开源在 GitHub 上，国内用户可选择 Gitee 镜像加速下载：
# 主源（需科学上网） git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git # 国内镜像 git clone https://gitee.com/qzl9999/LLaMA-Factory.git cd LLaMA-Factory
接着安装所有必要组件：
pip install -e ".[torch,metrics]"
这个命令会自动安装： - 支持 CUDA 的 PyTorch - Transformers 和 Accelerate - Peft 和 Bitsandbytes - Gradio 及评估工具
安装过程可能持续 10~20 分钟，取决于网络速度。
验证是否成功：
llamafactory-cli version
若输出如 v0.8.0，说明安装成功。
测试 GPU 是否可用
进入 Python 交互环境，快速校验 CUDA 状态：
import torch print("CUDA Available:", torch.cuda.is_available()) print("Device Name:", torch.cuda.get_device_name(0)) print("PyTorch Version:", torch.__version__)
理想输出应为：
CUDA Available: True Device Name: NVIDIA GeForce RTX 3090 PyTorch Version: 2.1.0+cu118
如果 CUDA Available 是 False，常见原因有三个：
- 没装 CUDA Toolkit
- PyTorch 安装的是 CPU 版本
- 显卡驱动过旧
解决后即可继续。
启动 WebUI：可视化操作让微调不再神秘
LLaMA-Factory 最大的亮点之一就是它的图形界面。只需一条命令：
llamafactory-cli webui
稍等片刻，终端会提示：
Running on local URL: http://127.0.0.1:7860
打开浏览器访问该地址，你会看到一个简洁清晰的控制台界面，左侧是功能菜单栏，右侧是参数配置区。
💡 小技巧：如果你想从其他设备访问这台机器上的 WebUI，可以加参数开放绑定：
bash llamafactory-cli webui --server-name 0.0.0.0 --server-port 7860
这样局域网内的手机、平板也能连上来操作。
加载模型：选择适合你硬件的起点
LLaMA-Factory 本身不包含模型权重，你需要自行从 Hugging Face 或 ModelScope 下载。
以下是几个适合本地实验的推荐模型：
| 模型名称 | 参数量 | QLoRA 显存需求 | 特点 |
|---|---|---|---|
| Qwen2.5-3B-Instruct | 3B | ~6GB | 中文强，体积小，入门首选 |
| Baichuan2-7B-Base | 7B | ~10GB | 中文任务表现稳定 |
| Llama-3-8B-Instruct | 8B | ~12GB | 英文通用性强 |
| Phi-3-mini-4k-instruct | 3.8B | ~6GB | 微软出品，推理效率高 |
以 Qwen2.5-3B 为例，执行以下命令下载：
git lfs install git clone https://huggingface.co/Qwen/Qwen2.5-3B-Instruct
将模型文件夹放在 LLaMA-Factory 同级目录下，后续引用路径更方便。
配置训练任务：无需代码，点选即走
回到 WebUI 页面，点击左侧 Train 标签页，开始配置。
基础设置
- Model Type: 选择
qwen - Model Name or Path: 输入
./Qwen2.5-3B-Instruct - Language: 切换为
zh更易理解
微调策略选择
对于大多数本地用户，QLoRA 是最优解。它结合了 LoRA 的低秩适配和 4-bit 量化技术，在仅增加几百 MB 显存开销的情况下，就能实现接近全参数微调的效果。
配置如下：
- Finetuning Type:
qlora - Quantization Bit:
4 - LoRA Rank:
64（秩越高表达能力越强，但也更耗显存） - LoRA Dropout:
0.1（防过拟合）
🧠 工程经验分享：初学者建议固定 LoRA Rank 为 64，Dropout 设为 0.1。待流程跑通后再尝试调整这些参数进行效果对比。
数据集准备：内置 vs 自定义
快速上手：用内置数据集验证流程
LLaMA-Factory 内建多个常用数据集，非常适合新手练手：
alpaca_zh：中文指令遵循数据集sharegpt_zh：真实对话记录dolly-15k：多任务指令集合
在 WebUI 中直接选择 alpaca_zh，系统会自动下载并预处理。首次使用时数据会被缓存到本地，下次无需重复下载。
模板（Template）会根据模型类型自动匹配为 qwen，无需手动修改。
进阶玩法：上传自己的领域数据
如果你想训练客服机器人、法律助手或医学顾问，就需要用自己的数据。
支持格式包括 JSONL、CSV、Parquet，结构示例如下：
{"instruction": "解释什么是糖尿病", "input": "", "output": "糖尿病是一种慢性代谢疾病……"}
操作步骤：
- 将文件放入项目根目录下的
data文件夹 - 在 WebUI 中选择 Custom Dataset
- 填写路径（如
data/my_medical_data.jsonl） - 映射字段：instruction → instruction, output → output
注意：每条样本不宜过长，建议控制在 512 token 以内，避免显存溢出。
训练超参数设置：平衡性能与资源
在 WebUI 中进一步配置以下关键参数：
| 参数 | 推荐值 | 说明 |
|---|---|---|
| Number of Epochs | 3 | 多轮容易过拟合，3 足够 |
| Learning Rate | 2e-4 | QLoRA 经验值，太大易震荡 |
| Batch Size per Device | 1 | 单卡批量大小 |
| Gradient Accumulation Steps | 8 | 累积 8 步相当于 batch=8 |
| Max Sequence Length | 512 | 影响显存占用，可调至 1024 若显存允许 |
| Save Total Limit | 3 | 只保留最新 3 个检查点，节省空间 |
点击 Preview Command，可以看到对应的 CLI 命令：
CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \ --model_name_or_path ./Qwen2.5-3B-Instruct \ --dataset alpaca_zh \ --finetuning_type qlora \ --lora_rank 64 \ --per_device_train_batch_size 1 \ --gradient_accumulation_steps 8 \ --learning_rate 2e-4 \ --num_train_epochs 3.0 \ --max_seq_length 512 \ --output_dir ./output/qwen2.5-3b-alpaca-zh
你可以复制保存，未来用于脚本化批量训练。
开始训练：实时监控进度与资源消耗
一切就绪后，点击 Start 按钮，训练进程将在后台启动。
WebUI 实时展示： - 当前 epoch / step - Loss 曲线变化 - GPU 显存占用 - 日志输出（含错误信息）
训练过程中可随时暂停或终止任务，模型检查点会自动保存到 output/ 目录下。
📊 提示：日志也保存在
runs/目录，可通过 TensorBoard 查看更详细的训练曲线：
bash tensorboard --logdir runs
推理测试：看看你的模型学会了什么
训练完成后，切换到 Inference 标签页，加载微调后的模型进行测试。
- Model Name or Path: 选择最佳 checkpoint，如
output/qwen2.5-3b-alpaca-zh/checkpoint-100 - 输入一句指令：'请写一首关于春天的诗'
你会发现，相比原始模型，微调后的版本在语气、风格和结构上更贴近指令要求。
值得一提的是，LLaMA-Factory 支持动态合并 LoRA 权重，无需导出即可直接推理，极大简化了调试流程。
导出融合模型：为部署做准备
如果你希望将模型集成到生产系统中，建议将其导出为独立的融合模型。
执行以下命令：
llamafactory-cli export \ --model_name_or_path ./Qwen2.5-3B-Instruct \ --adapter_name_or_path ./output/qwen2.5-3b-alpaca-zh \ --export_dir ./merged_model \ --export_quantization_bit 4 \ --export_device cuda
导出后的模型位于 ./merged_model，可通过标准 Hugging Face 方式加载：
from transformers import AutoModelForCausalLM, AutoTokenizer model = AutoModelForCausalLM.from_pretrained("./merged_model") tokenizer = AutoTokenizer.from_pretrained("./merged_model")
启动 API 服务：让你的模型对外提供能力
LLaMA-Factory 支持一键启动 RESTful 接口：
llamafactory-cli api \ --model_name_or_path ./merged_model \ --template qwen \ --port 8080
服务启动后，可通过 curl 发起请求：
curl -X POST "http://127.0.0.1:8080/generate" \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "你好，请介绍一下你自己"}] }'
返回 JSON 格式的响应结果，便于前端调用或接入业务系统。
你也可以将其部署在云服务器上，配合 Nginx 做反向代理，打造私有的 AI 对话接口。
总结：完成全流程闭环
通过这次实践，我们完成了从环境搭建、模型加载、数据配置、训练监控到推理部署的完整闭环。整个过程几乎不需要写一行代码，WebUI 的设计大大降低了大模型定制的门槛。
LLaMA-Factory 的价值不仅在于'能用'，更在于'好用'——它把原本分散在十几个脚本中的流程整合成一个统一入口，让开发者能把精力集中在数据质量和应用场景本身，而不是被环境问题拖累。
未来你可以尝试： - 使用更大的模型（如 Llama-3-8B）提升生成质量 - 结合 RAG 技术构建知识增强型问答系统 - 将微调模型封装成企业内部的知识助手 - 参与社区贡献新的模板或数据集支持
常见问题排查指南
| 问题 | 解决方案 |
|---|---|
CUDA out of memory | 降低 batch size，启用梯度检查点（Gradient Checkpointing） |
Module not found | 确保在正确的 conda 环境中运行 |
WebUI 打不开 | 检查端口是否被占用，尝试更换端口 --server-port 7861 |
模型加载失败 | 检查路径是否正确，文件权限是否可读 |
借助 LLaMA-Factory 这样的开源工具，开发者可以独立完成大模型微调与部署。建议立即开始本地微调实践。