在本地环境部署 LLaMA-Factory 框架的完整流程。内容包括硬件环境检查（CUDA、显存）、Conda 虚拟环境搭建、依赖安装及 WebUI 启动。演示了从 Hugging Face 或 ModelScope 下载预训练模型（如 Qwen），配置 QLoRA 参数进行微调，以及权重合并与 API 服务部署。旨在帮助开发者利用消费级显卡完成大语言模型的定制化训练与推理。
本文介绍如何在本地使用 LLaMA-Factory 进行大语言模型的微调与部署。
虽然 LLaMA-Factory 支持 CPU 推理，但真正想跑通一次像样的微调任务，GPU 是必不可少的。
打开终端，先执行这条命令：
nvidia-smi
如果能看到类似下面的信息，说明你的 NVIDIA 显卡驱动和 CUDA 环境基本正常：
+-----------------------------------------------------------------------------+
||
|| -M|| . || - ||
|===============================+======================+======================|| || N/A || % 45C 25W / 450W || % |重点关注三点：
⚠️ 如果命令报错或显示'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 管理 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, acceleratetrl（用于强化学习）sentencepiece, safetensors, bitsandbytes（支持量化训练）安装完成后，验证是否成功：
llamafactory-cli version
如果返回版本号（如 v0.9.0），恭喜你，核心组件已就位。
最后一步，确认 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，就可以放心进入下一步了。
LLaMA-Factory 提供图形化界面，可以在浏览器里完成模型微调。
启动服务只需一条命令：
llamafactory-cli webui
首次运行时会自动下载 Gradio 并启动本地服务器，默认地址是：
打开浏览器访问该链接，你会看到一个功能完整的控制台：
💡 小技巧：添加
--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 install
git clone https://www.modelscope.cn/qwen/Qwen2.5-3B-Instruct.git models/qwen2.5-3b-instruct
注意：建议将模型统一放在项目下的
models/目录中，便于后续引用。
先安装 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 自动识别模型类型和分词器配置。
现在进入重头戏：通过 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 三字段；如果你想上传自定义数据：
.json 或 .csv 文件放入 data/ 目录；设置一组典型的 QLoRA 参数：
| 参数 | 值 | 说明 |
|---|---|---|
| 学习率 | 2e-4 | AdamW 默认初始值 |
| 批大小 | 16 | Global batch size |
| 梯度累积步数 | 4 | 提升有效批大小 |
| 训练轮数 | 3 | 防止过拟合 |
| LoRA 秩 (r) | 8 | 控制新增参数规模 |
| LoRA Alpha | 16 | 一般设为 2×r |
| Dropout | 0.1 | 正则化防止过拟合 |
| 最大序列长度 | 512 | 平衡上下文长度与显存占用 |
还可以启用一些高级优化选项：
这些配置组合起来，能在有限资源下实现高效训练。
点击【预览命令】，系统会自动生成对应的 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 会实时更新以下信息：
通常情况下，每 100 步保存一次 checkpoint，文件位于 output/ 目录下。
📌 强烈建议定期备份
output/文件夹！一旦断电或程序崩溃，未合并的 LoRA 权重可能丢失。
训练结束后，LoRA 权重只是附加在原模型上的'补丁'。要想独立部署，必须将其与基础模型融合。
进入【合并适配器】页面：
./models/qwen2.5-3b-instructmerged_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
合并后的模型可用于：
快速测试微调效果：
llamafactory-cli chat \
--model_name_or_path merged_models/qwen2.5-3b-instruct-lora-merged
输入问题，比如'请写一首关于春天的诗'，看看它的回答是否有'个性'提升。
将模型暴露为 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 创造的门槛。开发者可以基于自己的数据和需求，定制专属的语言模型。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online