如何把 Hugging Face 模型转成 GGUF?locate-anything.cpp 权重转换完整流程
如何把 Hugging Face 模型转成 GGUF?locate-anything.cpp 权重转换完整流程
本文带你走通 locate-anything.cpp 的 GGUF 权重转换完整流程:从下载 Hugging Face 上的 NVIDIA LocateAnything-3B 原始权重,到转换出 f32 全精度 GGUF,再到量化出推荐的 q8_0 小体积文件。全程只需三步命令,推理阶段完全不需要 Python。
为什么要转成 GGUF 格式?
locate-anything.cpp 是 NVIDIA 开源的 LocateAnything-3B(开放词汇目标检测 / 视觉接地 VLM 模型)的 C++17 推理移植版,构建在 ggml 之上。它的模型由三部分组成:
- Qwen2.5-3B(语言模型 LM)
- MoonViT(视觉编码器 ViT)
- 2 层 MLP projector(投影层)
官方权重以 safetensors 分片形式发布,无法被 C++ 引擎直接加载。通过转换脚本把它们打包成一个自包含的 GGUF 文件后,就能用 locate-anything-cli 在纯 CPU(或 GPU)上跑推理,无需 Python 运行时。
准备工作:克隆仓库并安装依赖
先克隆仓库(ggml 已作为子模块内置在 third_party/ggml):
git clone --recursive https://gitcode.com/gh_mirrors/lo/locate-anything.cpp
cd locate-anything.cpp
cmake -B build -DLA_BUILD_CLI=ON && cmake --build build -j
权重转换需要 Python 依赖(仅转换阶段用,推理不需要),按 scripts/requirements.txt 安装,核心是 torch、safetensors、gguf、huggingface_hub:
pip install -r scripts/requirements.txt
第一步:下载 Hugging Face 模型权重
使用仓库自带的下载脚本 scripts/download_model.py,它会把 nvidia/LocateAnything-3B 的 safetensors 权重、config.json、分词器文件等拉到本地 models/LocateAnything-3B 目录:
python scripts/download_model.py
脚本只拉取转换必需的文件(*.safetensors、*.json、vocab.json、merges.txt 等),避免下载无关的大文件。
第二步:safetensors 转换为 f32 GGUF
运行转换脚本 scripts/convert_locateanything_to_gguf.py:
python scripts/convert_locateanything_to_gguf.py
# 输出 models/locate-anything-f32.gguf(约 15 GB)
这个脚本在幕后做了四件关键的事:
| 环节 | 说明 |
|---|---|
| 写入超参数 | 从 config.json 读取 LM / ViT 的层数、隐层维度、RoPE 参数等,并断言 13 个特殊 token id 与配置一致 |
| 内嵌分词器 | 把 Qwen2 的 BPE 词表(vocab.json + merges.txt + added_tokens.json)直接写进 GGUF |
| 重命名张量 | 通过 scripts/gguf_keys.py 把每个 safetensors 张量映射到 GGUF 命名空间(lm.* / vit.* / proj.*) |
| 精度转换 | bf16 → f32 无损转换(f32 是 bf16 的严格超集) |
脚本会拒绝写出不完整的 GGUF:只要有张量无法映射到 GGUF 名称,就会直接报错终止,而不是留下一个会在 C++ 加载器深处出错的残缺文件。
第三步:用 CLI 量化出小体积 GGUF
Python 的 gguf 写库无法可靠输出 K-quant(q6_k/q5_k/q4_k),所以量化这一步用编译好的 C++ CLI 完成,核心实现在 src/quantize.hpp:
locate-anything-cli quantize models/locate-anything-f32.gguf models/locate-anything-q8_0.gguf q8_0
支持的量化类型:f16、q8_0、q6_k、q5_k、q4_k。
⚠️ 注意:只有 Qwen2 LM 的 matmul 权重会被量化;ViT、projector、norms、biases,以及两个在主机侧按 f32 读取的张量(lm.tok_embd、vit.pos_emb)始终保持 f32——这是保证检测结果与官方模型逐字节一致的关键(Python 版 scripts/quantize_gguf.py 头部注释也明确列出了这份"必须保持 f32"的清单)。
如何选择合适的量化档位?
各档位的体积与效果实测数据(摘自 benchmarks/BENCHMARK.md):
| 文件 | 量化档位 | 体积 | 特点 |
|---|---|---|---|
locate-anything-q8_0.gguf |
q8_0 | ~6.3 GB | 近乎无损,检测框与 f32 完全一致,✅ 官方推荐 |
locate-anything-q6_k.gguf |
q6_k | ~5.5 GB | 与 f32 框完全一致 |
locate-anything-q5_k.gguf |
q5_k | ~5.1 GB | 亚像素级框漂移 |
locate-anything-q4_k.gguf |
q4_k | ~4.7 GB | 最小,亚像素级漂移 |
locate-anything-f16.gguf |
f16 | ~9.2 GB | 仅供特定 GPU 后端使用 |
结论很直接:q8_0 是甜蜜点——体积不到 f32 的一半,检测框逐字节一致,推理速度约为官方 f32 PyTorch 的 3.9 倍。f16 在 CPU 上只比 f32 快 6%,体积却还有 9 GB,性价比不高。
验证转换结果:跑一张检测图
转换完成后,用 CLI 对一张图做开放词汇检测来验证:
locate-anything-cli detect --model models/locate-anything-q8_0.gguf \
--input benchmarks/media/coco_kitchen_in.png \
--prompt "Locate all the instances that matches the following description: knife</c>bowl." \
--annotated out.png
终端会输出 JSON 格式的检测结果(label + box 坐标),--annotated 参数额外生成一张带标注框的 PNG。多类别之间用 </c> 分隔即可。
此外,仓库还提供了开箱即用的 tests/test_cli.sh 和离线一致性测试套件(tests/ 下通过 ctest 运行),可以逐张量比对转换产物与官方模型参考值的差异。
常见问题
Q1:转换需要多大的磁盘空间? 原始权重约 15 GB(bf16),f32 GGUF 约 15 GB,q8_0 约 6.3 GB,建议预留 40 GB 以上。
Q2:一定要量化吗? 不一定要。直接用 f32 GGUF 也能推理,只是体积大、速度慢;GPU 显存充裕时也可直接使用 f16 版本。
Q3:Python 依赖之后还需要保留吗? 不需要。转换完成后,推理全程只依赖 C++ 运行时和 GGUF 文件本身。
<输出文章>


