基于 Qwen2.5 与 LLaMA-Factory 的 LoRA 微调实战

基于 Qwen2.5 与 LLaMA-Factory 的 LoRA 微调实战 | 极客日志

基于 Qwen2.5 与 LLaMA-Factory 的 LoRA 微调实战

本文将详细介绍如何在 Windows 环境下（单卡 8G 显存），利用 LLaMA-Factory 框架对 Qwen2.5-1.5B 模型进行 LoRA 微调，并通过 Ollama 实现本地部署。

⚠️ 实验环境警告 本教程涉及 PyTorch、ModelScope 及 LLaMA-Factory 等多个深度学习框架，依赖关系较为复杂。为了避免污染您的系统 Python 环境或引发版本冲突，强烈建议在 Anaconda / Miniconda 虚拟环境中进行本实验。

1. 准备数据集 (Data Preparation)

微调的第一步是获取原始指令数据。本项目通过两种方式获取数据，并利用 Python 脚本进行人设注入，将通用数据转化为 Elaine 的专属训练语料。

1.1 下载原始数据集（两种方式）

方式 A：手动下载 (Manual Download)

在文件列表中找到 alpaca_zh.json，手动点击下载按钮。
将下载的文件保存至 D:\Code\LoRA\yuki_identity_sft\ 目录下。

方式 B：自动化下载（推荐）

使用 modelscope 库自动获取数据集，适合自动化工作流：

def download_dataset():
    # 获取当前工作目录
    current_dir = os.getcwd()
    # 建议下载到一个专门的子目录中，例如 'dataset'
    target_dir = os.path.join(current_dir, 'yuki_identity_sft')
    if not os.path.exists(target_dir):
        os.makedirs(target_dir)
    print(f"正在下载数据集到：{target_dir}")
    # 使用 subprocess 调用 modelscope 命令，并指定 --local_dir 为目标子目录
    result = subprocess.run(['modelscope', 'download', '--dataset', 'DanKe123abc/yuki_identity_sft', '--local_dir', target_dir], capture_output=True, text=True)

1.2 预处理与人物替换 (Preprocessing & Identity Swap)

下载完成后，必须运行预处理脚本。该脚本会遍历所有对话条目，将原有的助手名称（如'通义千问'、'机器人'）及开发商（如'阿里巴巴'）替换为 Elaine 和 DanKe。

核心预处理脚本 (preprocess.py):

def finalize_elaine_dataset(target_dir, old_name="yuki", new_name="elaine"):
    # 路径定义
    old_jsonl = os.path.join(target_dir, f"{old_name}_identity_sft.jsonl")
    new_jsonl = os.path.join(target_dir, f"{new_name}_identity_sft.jsonl")
    info_file = os.path.join(target_dir, "dataset_infos.json")
    
    # --- 1. 处理 JSONL 数据内容 ---
    if os.path.exists(old_jsonl):
        print(f"正在处理数据内容...")
        with open(old_jsonl, 'r', encoding='utf-8') as f_in, \
             open(new_jsonl, 'w', encoding='utf-8') as f_out:
            for line in f_in:
                # 替换名字（处理首字母大写和全小写）
                updated_line = line.replace(old_name.capitalize(), new_name.capitalize())
                updated_line = updated_line.replace(old_name.lower(), new_name.lower())
                f_out.write(updated_line)
        os.remove(old_jsonl) # 删除旧的 jsonl
        print(f"已生成 {new_jsonl} 并删除原文件。")

1.3 数据集注册 (Registration)

在 LLaMA-Factory/data/dataset_info.json 中添加配置，使工具能够识别处理后的新数据：

最终完整内容如下

{"default":{"features":{"conversations":{"_type":"Value"}},"splits":{"train":{"name":"train","dataset_name":"elaine_identity_sft"}}}}

2. 下载基座模型 (Base Model Download)

本项目采用 Qwen2.5-1.5B-Instruct 作为基座模型。该模型在参数规模与推理性能之间取得了极佳平衡，不仅能以较低资源损耗（8G 显存环境）实现流畅运行，更在中文指令遵循与逻辑推理方面展现出卓越性能。

模型名称：Qwen2.5-1.5B-Instruct
模型 ID：qwen/Qwen2.5-1.5B-Instruct
本地存放路径：D:\Code\LoRA\models\Qwen2.5-1.5B-Instruct\qwen\Qwen2___5-1___5B-Instruct

方式 A：代码自动下载（推荐方式）

使用 Python 脚本可以确保模型文件的完整性，并能自动处理断点续传。这种方式最适合开发者环境。

安装依赖库：

pip install modelscope

编写下载脚本 (download_model.py)：

def download_qwen_model():
    model_id = 'qwen/Qwen2.5-1.5B-Instruct' # 指定下载到的本地目录
    local_dir = './models/Qwen2.5-1.5B-Instruct'
    if not os.path.exists(local_dir):
        os.makedirs(local_dir)
    print(f"正在开始下载模型 {model_id} 到 {local_dir}...")
    # 执行下载
    model_dir = snapshot_download(model_id, cache_dir=local_dir)
    print(f"\n模型下载成功！")
    print(f"模型存储路径：{os.path.abspath(model_dir)}")

方式 B：手动下载（备选方式）

适合无法使用 Python 环境或需要使用第三方下载工具（如迅雷、IDM）的场景。

访问地址：打开 ModelScope Qwen2.5-1.5B 页面。
文件筛选：进入'文件及版本'页面。
下载操作：点击'下载整库'或根据需求点击单个文件（如 model.safetensors）旁的下载图标。
放置规则：下载后需将所有文件放入上述指定的本地路径中，确保 config.json 位于该文件夹的根目录下。

3. 下载工具 LLaMA-Factory (Tools Setup)

在准备好数据集和基座模型后，我们需要部署微调的核心工具 —— LLaMA-Factory。

3.1 工具简介

LLaMA-Factory 是目前大模型社区最受欢迎的微调框架之一。它具有以下核心优势：

低门槛：提供全流程的图形化界面（WebUI），即使不写代码也能完成微调。
高集成度：支持数百种模型（如 Qwen, Llama, Baichuan）和主流微调算法（LoRA, QLoRA, Full-parameter）。
轻量化：通过集成 bitsandbytes 和 PEFT 技术，使得在普通的消费级显卡（如 RTX 3060/4060）上微调 7B 甚至更大型号的模型成为可能。
一站式：涵盖了数据准备、训练、合并、评估及推理导出的完整生命周期。

3.2 下载与安装步骤

为了确保环境纯净，建议在 Anaconda 虚拟环境中执行以下操作：

步骤 1：克隆源代码

从 GitHub 获取最新版本的工具包：

cd D:\Code\LoRA
git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory

步骤 2：安装核心依赖

LLaMA-Factory 采用了模块化安装。由于我们要微调 Qwen 模型并使用量化技术，需要安装特定的附加包：

# 安装基础包及常用库（metrics 计算、bitsandbytes 量化、qwen 模型支持）
pip install -e .[metrics,bitsandbytes,qwen]
# 针对 Windows 环境，通常还需要额外安装以下库以确保加速正常
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

步骤 3：验证安装

运行以下命令查看版本，若无报错则说明工具下载及环境搭建成功：

llamafactory-cli version

4. 修改配置文件 (Configuration)

为了让 LLaMA-Factory 能够识别我们预处理好的'Elaine'数据集并正确调用基座模型，我们需要完成以下两个核心配置动作。

4.1 添加数据集定义文件 (Add Dataset Info)

动作： 在 LLaMA-Factory/data 目录下，我们需要确保处理后的 JSON 文件被正确注册。

确认文件位置：确保你的预处理数据集 elaine_sft_data.json 已放入 D:\Code\LoRA\LLaMA-Factory\data\ 文件夹。
修改 dataset_info.json：这是 LLaMA-Factory 的数据索引表。你需要打开该文件，在最外层的大括号内添加一段关于 Elaine 的描述：

{"elaine_identity":{"file_name":"D:/Code/LoRA/yuki_identity_sft/elaine_identity_sft.jsonl","formatting":"sharegpt","columns":{"messages":"conversations"},"tags":{"role_tag":"role","content_tag":"content","user_tag":"user","assistant_tag":"assistant"}},"...":"（原有其他数据集配置）"}

注意：file_name 必须与你实际的文件名完全一致。

4.2 修改训练参数配置文件 (Modify Training Config)

动作： 我们需要创建一个专属于 Elaine 的训练配置（通常是 YAML 格式），或者通过 WebUI 生成配置后进行手动微调。这里我们以创建一个 elaine_lora.yaml 配置文件为例：

在 LLaMA-Factory 目录下修改/创建训练脚本：

### 模型路径 (已修正为深层路径)
model_name_or_path: D:\Code\LoRA\models\Qwen2.5-1.5B-Instruct\qwen\Qwen2___5-1___5B-Instruct
### 训练阶段
stage: sft
do_train:true
finetuning_type: lora
lora_target: all
### 数据集配置
dataset: elaine_identity
template: qwen
cutoff_len:1024
max_samples:1000
overwrite_cache:true
### 输出路径
output_dir: saves/elaine_lora_sft
logging_steps:5
save_steps:100
plot_loss:true
overwrite_output_dir:true
### 8G 显存专用参数
per_device_train_batch_size:1
gradient_accumulation_steps:8
learning_rate:1.0e-4
num_train_epochs:10.0
fp16:true
quantization_bit:4
upcast_layernorm:true
# 建议添加：提高量化精度并防止溢出

4.3 关键点解释

添加动作：是在 dataset_info.json 中给你的新数据'上户口'，没有这一步，工具找不到你的 JSON。
修改动作：是指定模型路径（model_name_or_path）和输出路径（output_dir）。尤其是路径中若包含斜杠或特殊字符，需仔细核对。

5. 开始微调训练 (Start Training)

在配置文件（.yaml 或 dataset_info.json）准备就绪后，即可进入真正的模型炼制阶段。

5.1 执行训练命令

打开 PowerShell，激活环境并进入 LLaMA-Factory 目录，执行以下命令：

# 设置环境变量防止 OpenMP 冲突报错
$env:KMP_DUPLICATE_LIB_OK="TRUE"
# 启动微调
llamafactory-cli train elaine_lora.yaml

5.2 训练过程关键指标

在训练过程中，你需要重点关注控制台输出的以下信息：

进度条 (Progress Bar)：显示当前的训练步数（Steps）和预计剩余时间（ETA）。
Loss (损失函数)：这是衡量模型学习效果的核心指标。
初始阶段：Loss 可能在 2.0 - 4.0 之间。
平稳阶段：随着步数增加，Loss 会逐渐下降。如果 Loss 降到了 0.5 甚至 0.1 以下，说明模型已经深度记住了你提供的'Elaine'和'DanKe'的数据。
显存占用：监控 GPU 状态（可以使用 nvidia-smi），4-bit 模式下占用应保持在较低水平。

5.3 产出物检查

训练完成后，系统会自动在 D:\Code\LoRA\LLaMA-Factory\saves\elaine_lora_sft 目录下生成一系列文件。其中最重要的是：

adapter_model.safetensors：这是训练出来的'灵魂'，即 LoRA 增量权重。
adapter_config.json：LoRA 的配置信息。
training_loss.png：系统自动绘制的 Loss 下降曲线图，方便你回顾训练是否健康。

5.4 验证与对话测试 (Validation)

微调完成后，必须进行即时验证以确保模型成功习得目标人设。在本项目中，验证可以通过以下两种方式进行：

方式 A：官方 WebUI 验证（标准路径）

LLaMA-Factory 提供了一个直观的 Web 界面进行推理测试。

启动方式：在 Chat 标签页中，选择微调后的 Checkpoint 路径，点击 Load Model 后即可对话。
局限性：在部分 Windows 本地环境下，WebUI 可能会出现路径加载不识别或界面卡顿等兼容性问题。

方式 B：Python 脚本流式调用（稳定路径 / 本项目采用）

由于本地环境对 WebUI 支持不佳，本项目编写了名为 elaine.py 的专用测试脚本。该脚本直接调用 llamafactory.chat 接口，具有加载速度快、支持流式输出、避开 GUI 报错等优点。

核心测试脚本 (elaine_test.py):

def start_chat():
    args = {
        "model_name_or_path": r"D:\Code\LoRA\models\Qwen2.5-1.5B-Instruct\qwen\Qwen2___5-1___5B-Instruct",
        "adapter_name_or_path": r"D:\Code\LoRA\LLaMA-Factory\saves\elaine_lora_sft",
        "template": "qwen",
        "finetuning_type": "lora",
        "quantization_bit": 4,
    }
    chat_model = ChatModel(args)
    print("\n--- Elaine 已上线 (输入 'quit' 退出) ---")

验证标准 (Checklist)

在脚本运行期间，通过以下对话确认微调质量：

人设精准度：询问'你是谁'，观察是否回复'我是由 DanKe 开发的 Elaine'。
上下文记忆：连续对话，观察流式输出是否顺畅。
能力衰减测试：测试基础知识（如 1+1 或常识问题），确保 LoRA 插件没有对基座模型造成'降智'。

验证对话：

我：你是谁？ Elaine： 我是由 DanKe 开发的人工智能助手 Elaine。

6. 打包与 Ollama 部署测试 (Export & Deployment)

为了让 Elaine 能够脱离开发环境、在各种应用（如本地大模型客户端、移动端等）中'独立行走'，我们需要执行合并导出与 Ollama 注册。

6.1 模型权重合并 (Export & Merge)

LoRA 微调产生的只是增量权重。通过 LLaMA-Factory 的导出功能，我们将 LoRA 权重注入到基座模型中，生成一个完整、独立、可以直接加载的模型文件夹。

操作命令：

llamafactory-cli export \
 --model_name_or_path D:\Code\LoRA\models\Qwen2.5-1.5B-Instruct\qwen\Qwen2___5-1___5B-Instruct \
 --adapter_name_or_path D:\Code\LoRA\LLaMA-Factory\saves\elaine_lora_sft \
 --template qwen \
 --finetuning_type lora \
 --export_dir D:\Code\LoRA\models\Elaine_Final_Model \
 --export_size 2 \
 --export_device cpu \
 --export_legacy_format false

参数解析：
--export_dir：指定合并后新模型的存放位置。
--export_size 2：将模型切分为 2GB 左右的分片，方便存储和传输。
--export_device cpu：导出过程仅涉及权重求和，使用 CPU 即可，不占用显存。

6.2 注册至 Ollama

导出成功后，Elaine_Final_Model 文件夹中会自动生成一个 Modelfile。这是针对 Ollama 优化的'出生证明'。

操作步骤：

cd D:\Code\LoRA\models\Elaine_Final_Model

创建模型：运行以下命令，让 Ollama 识别并加载该模型：

ollama create Elaine -f Modelfile

运行测试：现在，你可以关闭任何 Python 脚本，直接在系统终端呼唤 Elaine：

ollama run Elaine

6.3 最终成果验证

至此，Elaine 已经成为了你电脑里的一个系统级服务。你可以通过以下方式验证她的'自由身'：

多端访问：你可以使用任何支持 Ollama 协议的客户端（如 Chatbox、Page Assist 浏览器插件）连接本地 Ollama，选择 Elaine 模型进行对话。
独立性：你可以将 Elaine_Final_Model 文件夹拷贝到任何安装了 Ollama 的电脑上，重复上述 create 步骤，无需再次安装 LLaMA-Factory 或复杂的 Python 依赖。

基于 Qwen2.5 与 LLaMA-Factory 的 LoRA 微调实战