BlueWhale7510/qwen1.5-0.5b-legal_translate_lora-gguf

模型量化项目

本项目实现了 Qwen1.5-0.5B 法律领域模型的 LoRA 权重合并、GGUF 格式转换和量化工作流程。

📋 项目结构

model_quantization/
├── merge_lora_and_quantize.py      # 合并 LoRA 权重脚本
├── test_quantized.py                # 使用 llama-cli.exe 测试量化模型
├── test_quantized_llamacpp.py      # 使用 Python llama-cpp-python 测试量化模型
├── qwen1.5-0.5b-model/             # 基础模型（Qwen1.5-0.5B）
├── legal_translate_optimized/       # LoRA 适配器权重
├── qwen1.5-0.5b-legal-merged/      # 合并后的模型
├── qwen1.5-0.5b-legal.f16.gguf     # FP16 GGUF 格式模型
├── qwen1.5-0.5b-legal.q4_0.gguf    # Q4_0 量化模型
└── llama.cpp/                       # llama.cpp 工具集

🚀 快速开始

1. 环境准备

Python 依赖

pip install transformers peft torch

安装 llama-cpp-python（用于 Python 测试脚本）

# CPU 版本（推荐新手）
pip install llama-cpp-python

# CUDA 版本（需要根据你的 CUDA 版本选择）
# CUDA 12.1
pip install llama-cpp-python-cu121
# CUDA 12.0
pip install llama-cpp-python-cu120
# CUDA 11.8
pip install llama-cpp-python-cu118

编译 llama.cpp（可选，如果使用 llama-cli.exe）

cd llama.cpp
cmake -S . -B build -A x64
cmake --build build --config Release -j

2. 合并 LoRA 权重

python merge_lora_and_quantize.py

这将：

1. 加载基础模型 qwen1.5-0.5b-model
2. 加载 LoRA 适配器 legal_translate_optimized
3. 合并权重并保存到 qwen1.5-0.5b-legal-merged

3. 转换为 GGUF 格式

使用 llama.cpp 的转换脚本：

cd llama.cpp
python convert_hf_to_gguf.py ../qwen1.5-0.5b-legal-merged/ ../qwen1.5-0.5b-legal.f16.gguf --outtype f16

4. 量化模型

使用 llama-quantize.exe 进行量化：

# 在 llama.cpp 目录下
.\llama-quantize.exe ..\qwen1.5-0.5b-legal.f16.gguf ..\qwen1.5-0.5b-legal.q4_0.gguf Q4_0

注意：

• 量化类型必须使用大写，如 Q4_0、Q8_0 等
• 如果路径包含中文，建议将模型复制到 ASCII 路径（如 C:\models\）后再量化

5. 测试量化模型

方式一：使用 Python 脚本（推荐）

# 基本测试（CPU）
python test_quantized_llamacpp.py

# 启用 CUDA 加速
$env:USE_CUDA=1
$env:NGL=35  # GPU 层数，根据显存调整
python test_quantized_llamacpp.py

方式二：使用 llama-cli.exe

cd llama.cpp
.\llama-cli.exe -m ..\qwen1.5-0.5b-legal.q4_0.gguf -p "请解释法律术语：举证责任" -n 100 -c 1024 -ngl 0

参数说明：

• -m: 模型文件路径
• -p: 提示词
• -n: 生成 token 数量
• -c: 上下文大小
• -ngl: GPU 层数（0 表示仅使用 CPU，>0 表示使用 GPU）

🔧 常见问题

1. 量化时报错 "failed to open GGUF file"

原因：路径包含非 ASCII 字符（如中文），llama.cpp 无法正确打开文件。

解决方案：

• 将模型文件复制到 ASCII 路径（如 C:\models\）
• 或使用 test_quantized_llamacpp.py 脚本，它会自动处理中文路径

2. 测试时出现 "UnicodeDecodeError"

原因：llama-cli.exe 输出使用了非 UTF-8 编码。

解决方案：

• 使用 test_quantized_llamacpp.py 脚本（已处理编码问题）
• 或手动设置环境变量 PYTHONIOENCODING=utf-8

3. 量化后模型无法加载

可能原因：

• 量化类型不兼容（确保使用大写，如 Q4_0）
• 模型文件损坏（重新量化）
• CUDA DLL 缺失（使用 -ngl 0 强制 CPU 模式）

4. 显存不足

解决方案：

• 降低 -ngl 参数（GPU 层数）
• 减小 -c 参数（上下文大小）
• 使用更激进的量化（如 Q4_0 而不是 Q8_0）

📊 量化类型说明

量化类型	位宽	质量	速度	显存占用
F16	16	最高	慢	高
Q8_0	8	高	中	中
Q4_0	4	中	快	低
Q4_1	4	中	快	低

🎯 测试案例

项目包含 5 个法律术语测试案例：

1. 原告应承担举证责任，否则将面临败诉风险。
2. 本合同的不可抗力条款旨在规避缔约双方在无法预见、无法避免且无法克服的客观情况下的违约责任。
3. 担保人对主债务承担连带保证责任。
4. 该证据因取证程序违法而不具有证据能力。
5. 租赁期间，承租人应妥善保管租赁物。

📝 环境变量说明

test_quantized_llamacpp.py

• USE_CUDA: 启用 CUDA（设置为 1 或 true）
• NGL: GPU 层数（默认 35，CPU 模式为 0）
• CTX: 上下文大小（默认 1024）
• THREADS: CPU 线程数（默认自动检测）
• NPRED: 生成 token 数量（默认 64）

📄 许可证

本项目遵循原模型的许可证协议。

🙏 致谢

• llama.cpp - 高效的推理引擎
• Qwen - 优秀的开源语言模型
• transformers - Hugging Face 模型库