4. GGUF格式转换

任务目标

将Hugging Face上的开源模型（以Qwen/Qwen2.5-0.5B-Instruct为例）转换为llama.cpp可加载的GGUF格式，并通过llama.cpp提供的CLI工具验证转换后的模型能够正常加载与推理。

环境与依赖

• 操作系统：Ubuntu 22.04（或WSL2），已安装git、python3、pip3
• Python依赖：transformers、torch、sentencepiece（用于加载HF模型）
• llama.cpp仓库（包含转换脚本与推理工具）

实现步骤

1. 克隆llama.cpp并安装依赖

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip3 install -r requirements.txt
# 编译llama-cli（用于最终验证）
make -j4 llama-cli

2. 下载HF模型（以Qwen2.5-0.5B-Instruct为例）

# 在llama.cpp目录外创建模型存放目录
mkdir -p ~/models/qwen2.5-0.5b-hf
cd ~/models/qwen2.5-0.5b-hf
# 使用huggingface_hub下载（需先安装：pip3 install huggingface_hub）
python3 -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='Qwen/Qwen2.5-0.5B-Instruct', local_dir='./')"

3. 执行格式转换（核心代码）

转换脚本位于llama.cpp仓库的convert_hf_to_gguf.py。以下命令将HF格式转换为Q8_0量化GGUF文件：

cd ~/llama.cpp
python3 convert_hf_to_gguf.py ~/models/qwen2.5-0.5b-hf \
    --outfile ~/models/qwen2.5-0.5b-q8_0.gguf \
    --outtype q8_0

转换完成后，终端会输出类似Model successfully exported to ...的提示，并显示最终文件路径。

4. 验证转换结果

使用编译好的llama-cli加载GGUF文件并执行一次推理，确认模型可运行：

cd ~/llama.cpp
./llama-cli -m ~/models/qwen2.5-0.5b-q8_0.gguf \
    -p "请用一句话介绍你自己。" \
    -n 64 \
    --no-display-prompt

验证方法与通过标准

• 转换成功标志：转换脚本无报错退出，且生成的.gguf文件大小约为原始FP16模型的一半（Q8_0量化），文件可通过ls -lh ~/models/qwen2.5-0.5b-q8_0.gguf查看。
• 运行成功标志：llama-cli正常加载模型并输出一段连贯的中文文本（例如自我介绍），无报错、无崩溃。若输出内容包含乱码或明显错误，则说明转换或加载存在问题。
• 附加检查（可选）：使用./llama-cli -m <gguf文件> --version确认模型加载时的参数信息（如n_vocab、n_ctx等）与Qwen2.5-0.5B的预期结构一致。

常见问题

• 转换时报KeyError: 'tokenizer'：通常因HF模型缓存不完整，删除~/models/qwen2.5-0.5b-hf后重新执行第2步下载。
• llama-cli加载慢或内存不足：Q8_0量化文件约500MB，需确保系统可用内存大于1GB；若仍不足，可改用--outtype q4_k_m重新转换以减小体积。
• 输出为英文或乱码：确认下载的HF模型为-Instruct版本，且转换时未指定--tokenizer参数（默认自动识别）。