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

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

为确保模型权重的完整性与下载稳定性，本项目优先选用国内主流开源社区 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 脚本可以确保模型文件的完整性，并能自动处理断点续传。这种方式最适合开发者环境。

1. 安装依赖库：

pip install modelscope

2. 编写下载脚本 (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 环境或需要使用第三方下载工具的场景。

1. 访问 ModelScope 对应模型页面。
2. 进入'文件及版本'页面。
3. 点击'下载整库'或根据需求点击单个文件旁的下载图标。
4. 放置规则：下载后需将所有文件放入上述指定的本地路径中，确保 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 能够识别我们预处理好的数据集并正确调用基座模型，我们需要完成以下两个核心配置动作。

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

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

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

{"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)

动作： 我们需要创建一个专属于微调任务的训练配置（通常是 YAML 格式）。这里我们以创建一个 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 以下，说明模型已经深度记住了你提供的数据。
• 显存占用：监控 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_test.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--- 助手已上线 (输入 'quit' 退出) ---")

验证标准 (Checklist)

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

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

验证对话示例：

我： 你是谁？ 助手： 我是由开发者开发的 AI 助手。

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

为了让模型能够脱离开发环境、在各种应用（如本地大模型客户端、移动端等）中'独立行走'，我们需要执行合并导出与 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 优化的配置文件。

操作步骤：

1. 进入目录：

cd D:/Code/LoRA/models/Elaine_Final_Model

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

ollama create Assistant -f Modelfile

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

ollama run Assistant

6.3 最终成果验证

至此，模型已经成为了你电脑里的一个系统级服务。你可以通过以下方式验证它的可用性：

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

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