使用 LLaMA-Factory 微调 Qwen2.5 并转换为 GGUF 格式部署

2. 配置微调参数

LLaMA-Factory 支持通过命令行或 YAML 文件配置。这里我们使用命令行进行 LoRA 微调：

CUDA_VISIBLE_DEVICES=0 python src/train_bash.py \
  --stage sft \
  --model_name_or_path Qwen/Qwen2.5-7B-Instruct \
  --dataset my_dataset \
  --dataset_dir ./data \
  --finetuning_type lora \
  --lora_target q_proj,v_proj \
  --output_dir ./output/qwen2.5-lora \
  --overwrite_cache \
  --per_device_train_batch_size 4 \
  --gradient_accumulation_steps 4 \
  --lr_scheduler_type cosine \
  --logging_steps 10 \
  --save_steps 500 \
  --learning_rate 1e-4 \
  --num_train_epochs 3 \
  --fp16

训练完成后，微调的 LoRA 权重保存在 ./output/qwen2.5-lora 目录中。

3. 合并 LoRA 权重

如果希望得到一个完整的 HuggingFace 格式模型（而非仅 LoRA 适配器），可以使用 export_model.py 脚本合并：

python src/export_model.py \
  --model_name_or_path Qwen/Qwen2.5-7B-Instruct \
  --adapter_name_or_path ./output/qwen2.5-lora \
  --template default \
  --finetuning_type lora \
  --export_dir ./output/qwen2.5-merged

合并后的完整模型将保存在 ./output/qwen2.5-merged 中，包含所有必要的配置文件、分词器和权重文件。

将微调后的模型转换为 GGUF 格式

1. 准备转换环境

为了转换，我们需要一个独立的 conda 环境，以免与 LLaMA-Factory 的依赖冲突。创建一个新环境并安装必要工具：

conda create -n llama.cpp python=3.10 -y
conda activate llama.cpp
pip install torch transformers sentencepiece protobuf

2. 执行转换命令

进入 llama.cpp 目录，执行转换命令（假设合并后的模型位于 /mnt/workspace/output/qwen2.5-merged）：

cd /path/to/llama.cpp
python convert_hf_to_gguf.py /mnt/workspace/output/qwen2.5-merged \
  --outtype f16 \
  --verbose \
  --outfile /mnt/workspace/qwen2.5-7B-instruct.gguf

3. 遇到的经典错误及解决

在执行上述命令时，可能会遇到转换脚本加载 tokenizer.json 文件时的解析错误。转换脚本运行时会输出大量权重映射信息，这里省略中间过程，直接展示关键报错：

Traceback (most recent call last):
  ...
  raise FileNotFoundError(f"File not found: {tokenizer_path}")
FileNotFoundError: File not found: /mnt/workspace/.cache/modelscope/models/Qwen/Qwen2.5-7B-Instruct-lora/tokenizer.model
...
Exception: data did not match any variant of untagged enum ModelWrapper

该错误通常由两个原因引起：

1. tokenizer.json 文件损坏：可能是下载不完整或微调过程中被意外修改。
2. transformers 版本不兼容：某些较新的 tokenizer.json 格式需要特定版本的 transformers 才能正确解析。

经过排查，发现是 transformers 版本问题。当前环境中的 transformers 为旧版（如 4.36.0），而 Qwen2.5 的 tokenizer 需要更新版本支持。我们通过强制安装 transformers==4.45.0 解决了问题：

pip install --force-reinstall transformers==4.45.0

重新运行转换命令，成功导出 GGUF 文件！

注意：如果模型目录中的 tokenizer.json 确实损坏，可以从 HuggingFace 官方仓库重新下载覆盖。

4. 验证转换结果

转换完成后，检查输出文件：

ls -lh /mnt/workspace/qwen2.5-7B-instruct.gguf

可以使用 llama.cpp 提供的简单测试工具验证模型加载：

./main -m /mnt/workspace/qwen2.5-7B-instruct.gguf -p "你好，请介绍一下你自己。" -n 100

如果正常输出，说明转换成功。

总结

通过实践，完成了以下工作：

• 使用 LLaMA-Factory 对 Qwen2.5-7B-Instruct 进行了 LoRA 微调，并合并为完整模型。
• 利用 llama.cpp 的转换工具将微调后的模型转换为 GGUF 格式，以便高效部署。
• 解决了转换过程中遇到的 tokenizer.json 解析错误，关键在于确保 transformers 版本与模型兼容。

关键点总结：

• 版本兼容性：转换脚本对 transformers 版本敏感，建议使用较新稳定版（如 4.45.0）。
• 文件完整性：微调后务必检查 tokenizer.json 是否完好，必要时从官方源补充。
• 路径命名：转换命令中的输出文件名建议与模型对应，避免混淆。
• GGUF 格式的模型可以轻松在 llama.cpp、Ollama、LM Studio 等推理后端运行，极大地方便了本地部署。