如何把 Hugging Face 模型转成 GGUF?locate-anything.cpp 权重转换完整流程

原创2026-11-07 11:12:322,206 阅读

如何把 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 运行时。

locate-anything.cpp 模型转换后的开放词汇检测效果示例

准备工作:克隆仓库并安装依赖

先克隆仓库(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++ 加载器深处出错的残缺文件。

量化后模型体积与加速比的权衡:locate-anything.cpp 各量化档位对比

第三步:用 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> 分隔即可。

厨房场景输入图:用于 locate-anything.cpp GGUF 模型转换后的检测验证

此外,仓库还提供了开箱即用的 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 文件本身。

<输出文章>

登录后查看全文
locate-anything.cpp