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

基于 Qwen2.5 与 LLaMA-Factory 的 LoRA 微调实战：打造专属 AI 助手 Elaine

文章目录

[基于 Qwen2.5 与 LLaMA-Factory 的 LoRA 微调实战：打造专属 AI 助手 Elaine](#基于 Qwen2.5 与 LLaMA-Factory 的 LoRA 微调实战：打造专属 AI 助手 Elaine)
- [1. 准备数据集 (Data Preparation)](#1. 准备数据集 (Data Preparation))
- - [1.1 下载原始数据集（两种方式）](#1.1 下载原始数据集（两种方式）)
  - - [方式 A：手动下载 (Manual Download)](#方式 A：手动下载 (Manual Download))
    - [方式 B：自动化下载（推荐）](#方式 B：自动化下载（推荐）)
  - [1.2 预处理与人物替换 (Preprocessing & Identity Swap)](#1.2 预处理与人物替换 (Preprocessing & Identity Swap))
  - [1.3 数据集注册 (Registration)](#1.3 数据集注册 (Registration))
- [2. 下载基座模型 (Base Model Download)](#2. 下载基座模型 (Base Model Download))
- - [方式 A：代码自动下载（推荐方式）](#方式 A：代码自动下载（推荐方式）)
  - [方式 B：手动下载（备选方式）](#方式 B：手动下载（备选方式）)
- [3. 下载工具 LLaMA-Factory (Tools Setup)](#3. 下载工具 LLaMA-Factory (Tools Setup))
- - [3.1 工具简介](#3.1 工具简介)
  - [3.2 下载与安装步骤](#3.2 下载与安装步骤)
  - - [步骤 1：克隆源代码](#步骤 1：克隆源代码)
    - [步骤 2：安装核心依赖](#步骤 2：安装核心依赖)
    - [步骤 3：验证安装](#步骤 3：验证安装)
- [4. 修改配置文件 (Configuration)](#4. 修改配置文件 (Configuration))
- - [4.1 添加数据集定义文件 (Add Dataset Info)](#4.1 添加数据集定义文件 (Add Dataset Info))
  - [4.2 修改训练参数配置文件 (Modify Training Config)](#4.2 修改训练参数配置文件 (Modify Training Config))
  - [4.3 关键点解释](#4.3 关键点解释)
- [5. 开始微调训练 (Start Training)](#5. 开始微调训练 (Start Training))
- - [5.1 执行训练命令](#5.1 执行训练命令)
  - [5.2 训练过程关键指标](#5.2 训练过程关键指标)
  - [5.3 产出物检查](#5.3 产出物检查)
  - [5.4 验证与对话测试 (Validation)](#5.4 验证与对话测试 (Validation))
  - - [方式 A：官方 WebUI 验证（标准路径）](#方式 A：官方 WebUI 验证（标准路径）)
    - [方式 B：Python 脚本流式调用（稳定路径 / 本项目采用）](#方式 B：Python 脚本流式调用（稳定路径 / 本项目采用）)
    - 验证标准 (Checklist)
- [6. 打包与 Ollama 部署测试 (Export & Deployment)](#6. 打包与 Ollama 部署测试 (Export & Deployment))
- - [6.1 模型权重合并 (Export & Merge)](#6.1 模型权重合并 (Export & Merge))
  - [6.2 注册至 Ollama](#6.2 注册至 Ollama)
  - [6.3 最终成果验证](#6.3 最终成果验证)
  - [🔗 源码与资源 (Repository)](#🔗 源码与资源 (Repository))

本文将详细介绍如何在 Windows 环境下（单卡 8G 显存），利用 LLaMA-Factory 框架对 Qwen2.5-1.5B 模型进行 LoRA 微调，并通过 Ollama 实现本地部署。我们将通过人设注入（Identity Injection） ，把通用的 AI 模型训练成一位名为 Elaine 的专属助手。
⚠️ 实验环境警告
本教程涉及 PyTorch、ModelScope 及 LLaMA-Factory 等多个深度学习框架，依赖关系较为复杂。为了避免污染您的系统 Python 环境或引发版本冲突，强烈建议在 Anaconda / Miniconda 虚拟环境中进行本实验。
说明：
本文档默认读者已具备基础的 Python 开发环境配置能力。
关于 Anaconda 的安装、CUDA 驱动的更新及系统环境变量的配置，不在本文讨论范围内，请自行查阅相关基础教程。

1. 准备数据集 (Data Preparation)

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

阿里云 ModelScope 平台:ModelScope 是一个开源的数据集平台，提供了丰富的 AI 训练数据集。

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

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

访问 ModelScope 数据集页面或 Hugging Face 搜索 alpaca_zh。
在文件列表中找到 alpaca_zh.json，手动点击下载按钮。
将下载的文件保存至 D:\Code\LoRA\yuki_identity_sft\ 目录下。

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

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

python 复制代码

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):

python 复制代码

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 中添加配置，使工具能够识别处理后的新数据：

最终完整内容如下

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 显存环境）实现流畅运行，更在中文指令遵循与逻辑推理方面展现出卓越性能。

为确保模型权重的完整性与下载稳定性，本项目优先选用国内主流开源社区 ModelScope (魔搭社区) 作为托管源。通过该平台，我们可以高效地获取预训练权重，为后续的 LoRA 微调奠定坚实基础。

模型名称 ：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 脚本可以确保模型文件的完整性，并能自动处理断点续传。这种方式最适合开发者环境。

安装依赖库：

powershell 复制代码

pip install modelscope

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

python 复制代码

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 获取最新版本的工具包：

powershell 复制代码

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

文件内容示例：

步骤 2：安装核心依赖

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

powershell 复制代码

# 安装基础包及常用库（metrics计算、bitsandbytes量化、qwen模型支持）
pip install -e .[metrics,bitsandbytes,qwen]

# 针对 Windows 环境，通常还需要额外安装以下库以确保加速正常
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

步骤 3：验证安装

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

powershell 复制代码

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 的描述：

json 复制代码

{
  "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 目录下修改/创建训练脚本：

yaml 复制代码

### 模型路径 (已修正为深层路径)
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 目录，执行以下命令：

powershell 复制代码

# 设置环境变量防止 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 下降曲线图，方便你回顾训练是否健康。

这一部分的补充非常关键，因为它记录了你在遇到环境适配问题（WebUI 无法使用）时，如何通过底层代码调用实现更稳定验证的实操路径。

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):

python 复制代码

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 权重注入到基座模型中，生成一个完整、独立、可以直接加载的模型文件夹。

操作命令：

powershell 复制代码

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 优化的"出生证明"。

操作步骤：

powershell 复制代码

cd D:\Code\LoRA\models\Elaine_Final_Model

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

powershell 复制代码

ollama create Elaine -f Modelfile

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

powershell 复制代码

ollama run Elaine

6.3 最终成果验证

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

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

过本次实验，我们成功地在消费级显卡（8G 显存）环境下，完成了一个专属垂直领域大模型的全链路开发。从数据清洗到模型部署，我们不仅构建了名为
Elaine 的 AI 助手，更掌握了一套可复用的低成本微调方案。

🔗 源码与资源 (Repository)

本项目的完整代码、配置文件及数据集处理脚本已同步至 GitHub，欢迎 Star 或 Fork 进行二次开发：
GitHub仓库 ：Elaine-one/Qwen2.5-LoRA
主要内容：包含全套微调脚本、环境变量配置等。