【AI】基于 Qwen2.5 模型进行 LoRA 微调
in 博客目录
本文介绍了Lora训练的相关知识和实操记录
前言：什么是 LoRA？为什么选它？
LoRA（Low-Rank Adaptation） 是一种参数高效微调（PEFT）技术。想象你有一个预训练好的大模型（如 Qwen2.5），它已经在海量数据上学会了语言规律。现在你想让它学会特定任务（如数学题推理），但有两个问题：
- 算力问题：全参数微调需要巨大的 GPU 内存和训练时间
- 存储问题：每次微调都保存一个完整模型（3GB+），成本高昂
LoRA 的解决方案：冻结原模型参数，只训练少量”低秩矩阵”（Adapter）。这就像给手机装插件，而不是重写整个操作系统。
本文目标：在 Apple Silicon（M1/M2/M3）Mac 上，使用 MLX 框架对 Qwen2.5-1.5B 进行 LoRA 微调，让模型学会”分步思考”的推理能力。
第一章：环境准备与工具链搭建
1.1 为什么选择 MLX？
MLX 是 Apple 专为自家芯片设计的机器学习框架，相比 PyTorch 有以下优势：
| 特性 | MLX | PyTorch (MPS) |
|---|---|---|
| 内存效率 | ⭐⭐⭐ 极高，统一内存架构优化 | ⭐⭐ 较好，但显存管理较粗 |
| 训练速度 | ⭐⭐⭐ 针对 Metal 深度优化 | ⭐⭐ 通用实现，非 Apple 最优 |
| 量化支持 | ⭐⭐⭐ 原生支持 4-bit/8-bit | ⭐⭐ 需额外配置 |
| 生态成熟度 | ⭐⭐ 较新，文档在完善中 | ⭐⭐⭐ 成熟，社区庞大 |
决策建议：如果你主要在 Mac 上做训练/推理，MLX 是首选；如果需要跨平台部署，PyTorch 更通用。
1.2 安装 Miniconda（环境隔离）
# 下载 ARM64 版本（适配 Apple Silicon）
curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
# 执行安装脚本
bash Miniconda3-latest-MacOSX-arm64.sh
# 安装完成后，重启终端或执行以下命令使配置生效
source ~/.zshrc # 或 ~/.bashrc
⚠️ 注意事项：
- 安装过程中会询问是否初始化 conda，建议选 yes（自动配置 PATH）
- 如果之前安装过 Anaconda，建议先完全卸载，避免环境冲突
- 安装路径建议保持默认（
~/miniconda3），避免权限问题
1.3 创建隔离的 Python 环境
# 创建 Python 3.11 环境（MLX 对 3.9-3.11 支持最好）
conda create -n mlx-train python=3.11 -y
# 激活环境
conda activate mlx-train
# 验证 Python 版本
python --version # 应显示 Python 3.11.x
为什么用 3.11 而非最新版？ MLX 和许多 ML 库对 Python 版本敏感，3.11 是目前稳定性与性能的最佳平衡点。
1.4 安装核心依赖包
# 核心：MLX 语言模型工具包
pip install mlx-lm
# 辅助工具（用于后续验证和格式转换）
pip install torch transformers accelerate safetensors
# 分词器依赖（Qwen 系列必需）
pip install sentencepiece protobuf tiktoken
# 数据处理
pip install datasets # HuggingFace 数据集工具
pip install jsonlines # 高效处理 JSONL 文件
依赖冲突排查：
# 如果安装后出现问题，检查版本兼容性
pip list | grep -E "(mlx|torch|transformers)"
第二章：模型获取与本地部署
2.1 安装 HuggingFace CLI 工具
# 使用 Homebrew 安装（推荐）
brew install huggingface-cli
# 验证安装
hf --version
重要变更提醒：旧版命令 huggingface-cli 已简化为 hf，但部分文档可能仍使用旧命令，注意区分。
2.2 配置 HuggingFace 访问权限
# 登录（需要 HuggingFace 账号和 Access Token）
hf login
# 或者设置环境变量（自动化脚本推荐）
export HF_TOKEN="your_token_here"
获取 Token 步骤：
- 访问 https://huggingface.co/settings/tokens
- 创建 New Token（选择
read权限即可下载模型） - 复制并妥善保存（Token 只显示一次）
2.3 下载 Qwen2.5 模型
# 创建模型存储目录
mkdir -p ./models
# 下载 1.5B 指令版（适合 Mac 本地训练）
hf download Qwen/Qwen2.5-1.5B-Instruct --local-dir ./models/Qwen2.5-1.5B-Instruct
模型选择指南：
| 模型版本 | 参数量 | 磁盘占用 | 内存需求 | 适用场景 |
|---|---|---|---|---|
| Qwen2.5-0.5B | 5亿 | ~1GB | 4GB+ | 快速测试、边缘设备 |
| Qwen2.5-1.5B | 15亿 | ~3GB | 8GB+ | Mac 本地训练推荐 |
| Qwen2.5-7B | 70亿 | ~14GB | 24GB+ | 高性能 Mac/云端 |
| Qwen2.5-14B | 140亿 | ~28GB | 48GB+ | 专业工作站 |
下载优化技巧：
# 如果下载中断，使用 resume 继续
hf download Qwen/Qwen2.5-1.5B-Instruct --local-dir ./models --resume-download
# 仅下载特定文件（如只需要 safetensors）
hf download Qwen/Qwen2.5-1.5B-Instruct --include "*.safetensors" "*.json"
2.4 模型完整性验证
下载完成后，验证文件结构：
ls -lh ./models/Qwen2.5-1.5B-Instruct/
# 应包含：config.json, model.safetensors, tokenizer.json 等
第三章：模型推理能力基线测试
3.1 编写验证脚本
在正式训练前，必须测试基础模型是否能正常运行，这将成为后续对比的基线。
# verify_base_model.py
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
import time
def test_model():
# 配置路径（根据实际下载路径调整）
model_path = "./models/Qwen2.5-1.5B-Instruct"
print("🔄 正在加载分词器...")
tokenizer = AutoTokenizer.from_pretrained(
model_path,
trust_remote_code=True,
padding_side="left" # 生成任务建议左填充
)
print(f"✅ 分词器加载成功 | 词表大小: {len(tokenizer)}")
print("\n🔄 正在加载模型（约 3GB，请耐心等待）...")
start_time = time.time()
model = AutoModelForCausalLM.from_pretrained(
model_path,
torch_dtype=torch.float16, # 半精度节省内存
device_map={"": "mps"}, # 强制使用 Mac GPU
trust_remote_code=True,
low_cpu_mem_usage=True # 优化加载内存峰值
)
load_time = time.time() - start_time
print(f"✅ 模型加载成功 | 耗时: {load_time:.1f}s | 设备: {model.device}")
# 测试用例：观察基础模型的推理能力
test_cases = [
"你好，请介绍一下你自己。",
"1+1等于几？请详细解释。",
"有3只兔子，每只4条腿，一共有多少条腿？请分步思考。"
]
print("\n" + "="*50)
print("🧪 开始推理测试")
print("="*50)
for i, prompt in enumerate(test_cases, 1):
print(f"\n--- 测试 {i} ---")
print(f"输入: {prompt}")
# 构建对话格式（Qwen chat template）
messages = [{"role": "user", "content": prompt}]
text = tokenizer.apply_chat_template(
messages,
tokenize=False,
add_generation_prompt=True
)
inputs = tokenizer(text, return_tensors="pt").to("mps")
# 生成参数调优
with torch.no_grad():
outputs = model.generate(
**inputs,
max_new_tokens=200,
temperature=0.7, # 控制创造性
top_p=0.9, # 核采样
repetition_penalty=1.1, # 抑制重复
do_sample=True
)
response = tokenizer.decode(outputs[0], skip_special_tokens=True)
# 提取助手回复部分
if "assistant" in response:
response = response.split("assistant")[-1].strip()
print(f"输出: {response[:200]}...")
print(f"生成长度: {len(outputs[0])} tokens")
if __name__ == "__main__":
test_model()
3.2 关键参数解析
| 参数 | 作用 | 建议值 |
|---|---|---|
torch_dtype | 权重精度 | float16（Mac 推荐）或 bfloat16 |
device_map | 设备分配 | {"": "mps"} 强制 GPU，"auto" 自动分配 |
low_cpu_mem_usage | 分片加载 | True（大模型必需） |
temperature | 采样随机性 | 0.1-0.3（确定性任务），0.7-0.9（创造性） |
⚠️ 常见问题：
- MPS 后端报错：如果遇到
MPS backend out of memory，尝试重启 Python 进程释放显存 - 结果不一致：MPS 的确定性不如 CUDA，相同输入可能有细微差异，属正常现象
第四章：训练数据准备与格式化
4.1 理解数据格式要求
MLX LoRA 训练要求数据为 JSON Lines 格式（.jsonl），每行一个 JSON 对象，必须包含 text 字段：
{"text": "User: 问题\n\nAssistant: <|thought|>\n思考过程\n<|solution|>\n最终答案"}
4.2 原始数据结构分析
你的原始数据包含以下关键字段：
problem: 问题描述thinking: 详细思考过程（CoT - Chain of Thought）solution: 结构化答案
训练目标：让模型学会在看到问题时，先输出 <|thought|> 标记，然后展示思考过程，最后给出答案。
4.3 数据转换脚本（增强版）
# convert_dataset.py
import json
import random
import argparse
from pathlib import Path
from typing import List, Dict
def validate_data(data: Dict) -> bool:
"""验证数据完整性"""
required_fields = ["problem", "thinking", "solution"]
return all(field in data and data[field] for field in required_fields)
def format_prompt(problem: str, thinking: str, solution: str,
template_type: str = "default") -> str:
"""
支持多种提示词模板
"""
templates = {
"default": (
f"User: {problem}\n\n"
f"Assistant: <|thought|>\n{thinking}\n"
f"<|solution|>\n{solution}"
),
"chatml": (
f"<|im_start|>user\n{problem}<|im_end|>\n"
f"<|im_start|>assistant\n<|thought|>\n{thinking}\n"
f"<|solution|>\n{solution}<|im_end|>"
),
"raw": f"{problem}\n\n思考：{thinking}\n\n答案：{solution}"
}
return templates.get(template_type, templates["default"])
def split_dataset(data: List[Dict], train_ratio: float = 0.9,
seed: int = 42) -> tuple:
"""划分训练集和验证集"""
random.seed(seed)
random.shuffle(data)
split_idx = int(len(data) * train_ratio)
return data[:split_idx], data[split_idx:]
def convert_dataset(input_path: str, output_dir: str,
template_type: str = "default",
train_ratio: float = 0.9):
"""
主转换函数
"""
input_file = Path(input_path)
output_path = Path(output_dir)
output_path.mkdir(parents=True, exist_ok=True)
# 读取原始数据
raw_data = []
with open(input_file, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f, 1):
try:
data = json.loads(line.strip())
if validate_data(data):
raw_data.append(data)
else:
print(f"⚠️ 跳过第 {line_num} 行：字段缺失")
except json.JSONDecodeError:
print(f"❌ 解析错误第 {line_num} 行")
print(f"📊 有效数据: {len(raw_data)} 条")
# 划分数据集
train_data, valid_data = split_dataset(raw_data, train_ratio)
print(f"📦 训练集: {len(train_data)} 条 | 验证集: {len(valid_data)} 条")
# 转换并保存
def save_split(data: List[Dict], filename: str):
output_file = output_path / filename
with open(output_file, 'w', encoding='utf-8') as f:
for item in data:
formatted = format_prompt(
item["problem"],
item["thinking"],
item["solution"],
template_type
)
# 统计长度（用于后续分析）
token_len = len(formatted) // 4 # 粗略估算
record = {
"text": formatted,
"metadata": {
"original_id": item.get("id", ""),
"token_estimate": token_len
}
}
json.dump(record, f, ensure_ascii=False)
f.write('\n')
print(f"✅ 已保存: {output_file}")
save_split(train_data, "train.jsonl")
if valid_data:
save_split(valid_data, "valid.jsonl")
# 生成数据报告
lengths = [len(item["text"]) for item in raw_data]
print(f"\n📈 数据统计:")
print(f" 平均长度: {sum(lengths)/len(lengths):.0f} 字符")
print(f" 最大长度: {max(lengths)} 字符")
print(f" 最小长度: {min(lengths)} 字符")
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("--input", required=True, help="输入 JSONL 文件")
parser.add_argument("--output", default="./data", help="输出目录")
parser.add_argument("--template", default="default",
choices=["default", "chatml", "raw"])
parser.add_argument("--train-ratio", type=float, default=0.9)
args = parser.parse_args()
convert_dataset(args.input, args.output, args.template, args.train_ratio)
运行命令：
python convert_dataset.py \
--input ./raw_data/dataset.jsonl \
--output ./data \
--template default \
--train-ratio 0.95 # 留 5% 做验证
4.4 数据质量检查清单
执行转换后，务必检查：
# 1. 检查文件格式
head -n 1 ./data/train.jsonl | python -m json.tool
# 2. 统计行数（应与原始数据匹配）
wc -l ./data/train.jsonl ./data/valid.jsonl
# 3. 检查文本长度分布（避免过长数据）
python -c "
import json
lengths = []
with open('./data/train.jsonl') as f:
for line in f:
data = json.loads(line)
lengths.append(len(data['text']))
print(f'Max: {max(lengths)}, Min: {min(lengths)}, Avg: {sum(lengths)/len(lengths):.0f}')
"
⚠️ 关键警告：
- 序列长度：MLX 默认
max_seq_length=2048，超过会被截断 - 截断风险：如果截断发生在答案部分，模型将学不到完整输出
- 建议：预处理阶段过滤掉 >3000 字符的样本，或手动截断到合理长度
第五章：LoRA 训练实战
5.1 训练参数详解
python -m mlx_lm.lora \
--model ./models/Qwen2.5-1.5B-Instruct \
--train \
--data ./data \
--iters 1000 \
--batch-size 1 \
--steps-per-report 10 \
--adapter-path ./output/qwen_reasoning_adapter \
--learning-rate 1e-5 \
--lora-rank 8 \
--lora-alpha 16 \
--lora-dropout 0.05 \
--max-seq-length 2048 \
--save-every 100
参数深度解析：
| 参数 | 含义 | 调参建议 |
|---|---|---|
--lora-rank | 低秩矩阵维度 | 8-64，越大表达能力越强，但易过拟合 |
--lora-alpha | 缩放系数 | 通常设为 rank 的 2 倍 |
--learning-rate | 学习率 | 1e-5 到 5e-5，过大导致不稳定 |
--batch-size | 批次大小 | Mac 上保持 1，显存充足可增大 |
--max-seq-length | 最大序列长度 | 根据数据长度调整，需留余量 |
5.2 训练过程监控
正常训练日志解读：
Iter 10: Train loss 1.435, Learning Rate 1.000e-05, It/sec 0.326...
关键指标：
- Train loss：应持续下降，最终稳定在 0.5-1.5 之间
- It/sec：迭代速度，Mac M3 约 0.3-0.5 it/s
- Peak mem：内存峰值，超过物理内存会触发 SWAP 导致极慢
危险信号：
loss = nan：学习率过大或梯度爆炸，立即停训loss不降反升：学习率过高或数据有问题loss降到 0.01 以下：严重过拟合，模型变成复读机
5.3 内存优化策略
如果训练时内存不足：
# 方案 1：开启梯度检查点（牺牲速度换内存）
--gradient-checkpointing
# 方案 2：使用量化模型作为基础
--model Qwen/Qwen2.5-1.5B-Instruct-4bit
# 方案 3：减小序列长度（确保覆盖 90% 数据即可）
--max-seq-length 1024
第六章：模型评估与推理测试
6.1 使用 Adapter 进行推理
python -m mlx_lm.generate \
--model ./models/Qwen2.5-1.5B-Instruct \
--adapter-path ./output/qwen_reasoning_adapter \
--prompt "User: 一个水池有两个进水管，A管单独注满需6小时，B管单独注满需4小时，同时打开两管需几小时注满？\n\nAssistant: <|thought|>" \
--max-tokens 500 \
--temperature 0.3
对比测试建议：
- 先用基础模型（不加
--adapter-path）测试同一问题 - 再用微调后的模型测试
- 记录两者差异，评估微调效果
6.2 批量评估脚本
# evaluate_model.py
import subprocess
import json
def evaluate(test_cases: list, adapter_path: str = None):
results = []
base_cmd = [
"python", "-m", "mlx_lm.generate",
"--model", "./models/Qwen2.5-1.5B-Instruct",
"--max-tokens", "500",
"--temperature", "0.3"
]
if adapter_path:
base_cmd.extend(["--adapter-path", adapter_path])
for case in test_cases:
prompt = f"User: {case}\n\nAssistant: <|thought|>"
cmd = base_cmd + ["--prompt", prompt]
result = subprocess.run(cmd, capture_output=True, text=True)
output = result.stdout.strip()
results.append({
"input": case,
"output": output,
"has_thought": "<|thought|>" in output,
"has_solution": "<|solution|>" in output
})
return results
# 运行对比
test_cases = [
"鸡兔同笼，头共35，脚共94，鸡兔各几只？",
"计算 125 × 32 的简便方法"
]
base_results = evaluate(test_cases)
lora_results = evaluate(test_cases, "./output/qwen_reasoning_adapter")
# 分析：lora_results 应显示更规范的思考步骤
6.3 模型融合（可选）
如果希望部署独立模型（无需每次加载 adapter）：
python -m mlx_lm.fuse \
--model ./models/Qwen2.5-1.5B-Instruct \
--adapter-path ./output/qwen_reasoning_adapter \
--save-path ./models/Qwen-1.5B-Reasoning-Fused \
--de-quantize # 如果需要恢复为 FP16 精度
融合 vs Adapter 对比：
| 方式 | 优点 | 缺点 |
|---|---|---|
| Adapter 分离 | 体积小（~50MB）、可多版本切换 | 加载时需合并，略慢 |
| 融合模型 | 单一文件、部署简单 | 体积大（~3GB）、版本管理难 |
第七章：生产环境部署建议
7.1 模型量化（优化推理速度）
# 将融合后的模型量化为 4-bit（适合移动端部署）
python -m mlx_lm.convert \
--hf-path ./models/Qwen-1.5B-Reasoning-Fused \
--mlx-path ./models/Qwen-1.5B-Reasoning-4bit \
--quantize --q-bits 4
7.2 持续迭代流程
原始数据 → 清洗过滤 → 格式转换 → 训练 → 评估 → bad cases 回流 → 数据增强 → 重新训练
↑___________________________________________________________|
7.3 关键检查点总结
| 阶段 | 必做检查 | 常见问题 |
|---|---|---|
| 环境准备 | mlx-lm 版本 >= 0.8 | 旧版本 API 不兼容 |
| 数据转换 | 验证 JSONL 格式正确性 | 特殊字符未转义导致解析失败 |
| 训练启动 | 确认加载了验证集 | 过拟合无法及时发现 |
| 训练过程 | 监控 loss 曲线 | 学习率过大导致 nan |
| 推理测试 | 对比基线模型 | 模板格式与训练时不一致 |
附录：故障排查速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
RuntimeError: MPS out of memory | 序列过长或 batch size 过大 | 减小 --max-seq-length 或 --batch-size |
KeyError: 'text' | 数据格式错误 | 检查 JSONL 是否包含 text 字段 |
| Loss 不下降 | 学习率过低或数据质量问题 | 增大 lr 至 5e-5，检查数据标签 |
| 生成结果乱码 | 分词器不匹配 | 确保使用与训练时相同的 tokenizer |
| 模型不遵循指令 | 模板格式不一致 | 推理 prompt 必须与训练模板完全匹配 |
