LLaMA-Factory 微调 DeepSeek-R1 指南

在大模型应用落地的浪潮中，如何快速、低成本地定制一个具备特定风格或领域知识的对话模型，已成为开发者最关心的问题之一。与其从零训练一个千亿参数巨兽，不如借助现代微调框架，在预训练模型基础上“点石成金”。而 LLaMA-Factory 正是这一理念的最佳实践者。

它像一座自动化程度极高的“微调工厂”，把原本复杂繁琐的 LoRA、QLoRA 训练流程封装成可视化的操作界面。哪怕你对 transformers 或 peft 不甚了解，也能通过点击完成从数据准备到模型导出的全流程。更关键的是，它对 DeepSeek-R1-Distill-Qwen-1.5B 这类轻量级高性能蒸馏模型支持良好，非常适合个人开发者和中小团队上手。

下面我们就以打造一个“个性化助手”为目标，一步步走通这条端到端的技术路径。

---

项目获取与本地部署

首先从 GitHub 获取源码：

git clone https://github.com/hiyouga/LLaMA-Factory.git

建议将项目放在纯英文路径下（如 E:\Model\LLaMA-Factory），避免某些依赖因路径含中文报错。项目结构清晰，核心模块集中在 src/ 目录，而 data/ 和 saves/ 分别用于存放数据集与训练产出。

虽然可以直接运行，但为了环境隔离，强烈建议使用 Anaconda 创建独立虚拟环境：

conda create -n llamafactory python=3.10
conda activate llamafactory
cd E:\Model\LLaMA-Factory

Python 3.10 是目前兼容性最好的选择，能避开不少库冲突问题。

---

环境配置：CUDA、PyTorch 与量化支持

进入项目根目录后，先确认显卡驱动和 CUDA 版本：

nvidia-smi

假设输出显示 CUDA Version: 12.1，则安装对应 PyTorch：

conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

如果你用的是旧卡（如 RTX 3060），可能只能支持到 CUDA 11.8，那就换成：

conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

验证是否可用 GPU：

import torch
print(torch.cuda.is_available())  # 应返回 True

接下来是 QLoRA 的关键组件 —— bitsandbytes。这个库实现了 4-bit 量化矩阵运算，能让 1.5B 模型在 8GB 显存上跑起来。

Windows 用户推荐安装预编译 wheel，否则容易编译失败：

pip install https://github.com/jllllll/bitsandbytes-windows-webui/releases/download/wheels/bitsandbytes-0.41.2.post2-py3-none-win_amd64.whl

Linux 用户则简单得多：

pip install bitsandbytes

最后安装主依赖：

pip install -r requirements.txt
pip install -e ".[torch,metrics]"

其中 -e 表示开发模式安装，便于后续调试源码。

---

启动 WebUI 并解决常见连接问题

一切就绪后，启动可视化界面：

llamafactory-cli webui

默认会打开 http://127.0.0.1:7860，但如果页面空白或无法加载，很可能是 Gradio 的 share 参数未开启公网访问。

此时需要手动修改源码文件：

LLaMA-Factory/src/llamafactory/webui/interface.py

找到 run_web_ui() 和 run_web_demo() 函数中的这行：

demo.queue().launch(share=gradio_share, ...)

改为强制开启共享链接：

demo.queue().launch(share=True, ...)

再次启动即可获得类似 https://xxxx.gradio.live 的外网可访问地址。不过要注意，科学上网工具可能会干扰本地服务，建议临时关闭代理。

---

数据采集：从微信聊天记录构建训练语料

高质量的微调效果，七分靠数据，三分靠调参。我们不妨设想这样一个场景：你想让 AI 助手学会你的说话风格、常用表达甚至幽默感 —— 最直接的方式就是拿自己的历史对话来训练。

这里推荐一款本地运行的微信聊天记录提取工具：留痕 MemoTrace。它无需上传云端，解析速度快，输出格式规范，非常适合隐私敏感的数据收集任务。

使用流程如下：
1. 下载解压 MemoTrace.exe
2. 登录微信账号并授权访问
3. 选择目标联系人或群聊
4. 导出为 JSON 格式，保存至 D:\MemoTrace\data\聊天记录

每个对话会被存为单独的 .json 文件，内容包含时间戳、角色（user/assistant）、文本等字段。

---

数据清洗与合并：编写脚本统一处理

原始数据分散在多个文件中，必须先合并再标准化。为此创建一个 merge.py 脚本：

import os
import json

folder_path = r'D:\MemoTrace\data\聊天记录'
json_files = []
for root, dirs, files in os.walk(folder_path):
    for file in files:
        if file.endswith('.json'):
            json_files.append(os.path.join(root, file))

merged_data = []
for file in json_files:
    with open(file, 'r', encoding='utf-8') as f:
        try:
            data = json.load(f)
            merged_data.append(data)
        except json.JSONDecodeError:
            print(f"解析失败：{file}，跳过...")

output_path = os.path.join(folder_path, 'merged_data.json')
with open(output_path, 'w', encoding='utf-8') as out_file:
    json.dump(merged_data, out_file, indent=2, ensure_ascii=False)

print(f"✅ 合并完成！总文件数：{len(json_files)}")
print(f"💾 输出路径：{output_path}")

在聊天记录目录下打开命令行执行：

python merge.py

得到一个统一的 merged_data.json，为下一步格式转换做好准备。

---

格式化为 ShareGPT 结构：适配 LLaMA-Factory 输入规范

LLaMA-Factory 支持多种数据格式，但对于多轮对话任务，sharegpt 是最优选。其标准结构如下：

[
  {
    "conversations": [
      { "from": "human", "value": "你好吗？" },
      { "from": "gpt", "value": "我很好，谢谢！" }
    ]
  }
]

我们需要将原始消息中的 role: user/assistant 映射为 from: human/gpt，同时清理噪声和敏感信息。创建 Data_Preprocessing.py：

import json
import re

with open('merged_data.json', 'r', encoding='utf-8') as f:
    raw_data = json.load(f)

converted_data = []

def clean_text(text):
    text = re.sub(r'\s+', ' ', text)              # 压缩空白字符
    text = re.sub(r'http[s]?://\S+', '[URL]', text)     # 脱敏链接
    text = re.sub(r'\d{11}', '[PHONE]', text)           # 手机号替换
    text = re.sub(r'\S+@\S+', '[EMAIL]', text)         # 邮箱脱敏
    return text.strip()

for item_list in raw_data:
    for item in item_list:
        if 'messages' not in item:
            continue

        conv = {"conversations": []}
        for msg in item['messages']:
            role = msg.get("role")
            content = clean_text(msg.get("content", ""))

            if not content:
                continue

            if role == "user":
                from_role = "human"
            elif role == "assistant":
                from_role = "gpt"
            else:
                continue  # 忽略 system 等非对话角色

            conv["conversations"].append({
                "from": from_role,
                "value": content
            })

        if len(conv["conversations"]) > 0:
            converted_data.append(conv)

with open('converted_data.json', 'w', encoding='utf-8') as f:
    json.dump(converted_data, f, ensure_ascii=False, indent=2)

print("✅ 数据转换完成：converted_data.json")

运行后生成符合要求的 converted_data.json，将其移至 LLaMA-Factory/data/ 目录备用。

---

注册自定义数据集：配置 dataset_info.json

为了让框架识别新数据，需编辑 data/dataset_info.json 添加条目：

"my_deepseek_finetune": {
  "file_name": "converted_data.json",
  "formatting": "sharegpt",
  "columns": {
    "messages": "conversations"
  }
}

字段说明：
- file_name：相对 data/ 目录的路径
- formatting：指定为 sharegpt 多轮对话格式
- columns.messages：告诉框架从哪个字段读取对话内容

这个配置机制非常灵活，即使你的数据字段名不一致，也可以通过映射解决。

---

开始训练：WebUI 参数设置实战建议

启动 WebUI 后进入 Train 标签页，填写以下关键参数：

参数	推荐值	实践建议
模型名称	DeepSeek-R1-1.5B-Distill	HuggingFace ID 或本地路径
模型路径	E:\Model\DeepSeek-R1-1.5B	提前下载好模型权重
数据集	my_deepseek_finetune	刚注册的数据集名
微调方法	LoRA	新手首选，显存占用低
LoRA 秩 (rank)	8	一般够用，追求性能可试 16
学习率	2e-4	AdamW 默认推荐值，稳定有效
训练轮数	3	防止过拟合，2~5 足够
批量大小	4	视显存调整，RTX 3060 可设 2
最大长度	1024	平衡上下文与显存
梯度累积	4	提升有效 batch size，提升稳定性
输出目录	saves/deepseek-lora	权重保存位置

特别提醒：不要盲目增大 batch size。小批量 + 梯度累积往往比单步大 batch 更稳定，尤其在显存受限时。

点击「预览命令」还能看到底层实际执行的 Trainer 参数，方便进阶用户做进一步优化。

---

训练监控与 Loss 曲线分析

启动后终端会实时输出训练日志：

Epoch 1/3: 100%|██████████| 250/250 [15:32<00:00,  3.73s/it]
loss: 1.8746e-01, grad_norm: 0.321, lr: 2.00e-04

WebUI 页面同步提供图形化监控：
- 实时 loss 曲线
- GPU 显存占用
- 当前进度与剩余时间估算

理想情况下，loss 应随 epoch 稳定下降。如果出现剧烈震荡，可能原因包括：
- 学习率过高 → 尝试降至 1e-4
- 数据质量差 → 检查是否有乱码或异常长句
- batch size 太小 → 增加梯度累积步数

通常 3 个 epoch 足以让模型初步掌握对话模式，不必贪多。

---

对话测试：验证微调效果

训练结束后切换至 Inference 页面进行交互测试。

配置要点：
- Base Model：指向原始 DeepSeek-R1 模型
- Adapter：选择你保存的 LoRA 权重目录（如 checkpoint-500）
- 推理参数：temperature=0.7, top_p=0.9, max_new_tokens=512

尝试提问：

👤 用户：你能帮我写一封辞职信吗？
🤖 模型：当然可以，以下是为您定制的辞职信草稿……

你会发现回复不仅语法通顺，还隐约带有你在历史对话中表现出的语言风格 —— 这正是微调的价值所在。

---

模型导出：合并 LoRA 权重用于独立部署

LoRA 训练结果只是增量权重（通常几十 MB），不能单独运行。要真正部署，必须将其合并到底层模型中。

在 WebUI 的 Export 页面填写：
- Base Model Path: deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B
- Adapter Path: saves/deepseek-lora/checkpoint-500
- Export Directory: model/exported-deepseek-v1
- Export Device: auto

点击「导出」后，系统会自动执行权重融合，并生成完整的模型文件夹，包含：
- 合并后的 FP16 模型（也可选 INT4 量化）
- tokenizer 配置
- generation_config.json 等推理所需元数据

导出后的模型可用于 FastAPI 服务、本地 CLI 调用或集成进前端应用。

---

部署打包：生成可复现的依赖清单

为确保模型可在其他机器顺利运行，建议生成一份精简的 requirements.txt：

transformers>=4.41.2,<4.49.0
datasets>=2.16.0
accelerate>=0.34.0
peft>=0.11.1
trl>=0.8.6
tokenizers>=0.19.0
gradio>=4.38.0
torch>=2.3.0
sentencepiece
tiktoken
protobuf
fastapi
uvicorn
matplotlib
numpy<2.0.0

放入发布包中，使用者只需一条命令即可安装全部依赖：

pip install -r requirements.txt

---

这种“采集→清洗→训练→导出”的闭环工作流，正代表着当前轻量化 AI 应用开发的新范式。LLaMA-Factory 的价值不仅在于技术实现，更在于它降低了创造力的门槛 —— 每个人都可以用自己的语言数据，训练出独一无二的智能体。

未来已来，只待你按下那个“开始训练”的按钮。