如何快速上手?10分钟教程:从安装到首次运行locate-anything.cpp-gguf开放词汇目标检测
如何快速上手?10分钟教程:从安装到首次运行locate-anything.cpp-gguf开放词汇目标检测
🎯 想在自己电脑上跑开放词汇目标检测(Open-Vocabulary Detection),又不想被 Python 环境、CUDA 依赖折腾一番?那么 locate-anything.cpp-gguf 就是为你准备的。本仓库提供 NVIDIA LocateAnything-3B 模型的 GGUF 量化权重,搭配 locate-anything.cpp(C++/ggml 推理引擎)使用,推理时零 Python 依赖,检测效果与官方 PyTorch 实现完全一致,且在 CPU 和 GPU 上更快。本教程带你 10 分钟内完成从获取仓库到首次运行检测的全过程。
📦 这个仓库是什么?5 个 GGUF 权重文件一览
本仓库 README.md 说明了全部文件:这是一组可直接用于目标检测与视觉定位(Visual Grounding)的 GGUF 模型文件,覆盖 f16 到 q4_k 共 5 种量化档位。
| 文件 | 精度(LM 部分) | 大小 | 特点 |
|---|---|---|---|
| locate-anything-f16.gguf | f16 | ~9.2 GB | LM 矩阵乘法为 f16,其余 f32 |
| 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 | 体积最小,速度最快 |
量化策略很聪明:只有 Qwen2 语言模型的矩阵乘法被量化,MoonViT 视觉塔、投影层、所有 norm 和 bias 都保持 f32——因此视觉路径不受影响,量化后仍能保持与原始模型对齐的检测精度。
🚀 10分钟快速上手:从安装到首次运行
第1步:获取仓库与模型权重
只需一条命令即可克隆本仓库(含全部 GGUF 权重文件):
git clone https://gitcode.com/hf_mirrors/mudler/locate-anything.cpp-gguf
💡 建议优先下载
q8_0版本:体积约 6.3 GB,检测框与 f32 完全一致,是速度与精度的最佳平衡点。
第2步:构建 locate-anything-cli
按照 locate-anything.cpp 主仓库 README 的说明构建 CLI 工具即可。如果你要用 GPU 加速,构建时加上参数 -DLA_GGML_CUDA=ON:
# GPU 构建示例
cmake -DLA_GGML_CUDA=ON .. && make
构建完成后,你会得到一个 locate-anything-cli 可执行文件——整个推理过程无需 Python 环境。
第3步:首次运行检测命令
将 GGUF 模型文件、一张测试图片准备好,然后执行:
locate-anything-cli detect \
--model locate-anything-q8_0.gguf \
--input image.jpg \
--prompt "Locate all the instances that matches the following description: person</c>car." \
--annotated out.png
命令会输出两部分结果:
- 一段 JSON 检测结果,形如
{"detections":[{"label":"person","box":[...]}, ...]} - 一张标注好检测框的输出图片
out.png
第4步:常用参数说明
| 参数 | 作用 |
|---|---|
--model |
指定 GGUF 模型文件路径 |
--input |
待检测的图片路径 |
--prompt |
描述要检测的内容,多个类别用 </c> 分隔 |
--annotated |
输出带标注框的图片 |
--mode |
解码模式:hybrid(默认)、slow、fast |
⚠️ 小提示:在 prompt 中用 </c> 分隔不同类别(如 person</c>car),模型才能分别输出带标签的检测框。
⚡ 性能有多快?量化版本如何选择?
CPU 场景(Ryzen 9 9950X3D,slow 模式):相比官方 PyTorch f32 实现(23.65 s),q8_0 版仅需 6.07 s(3.9 倍加速),q4_k 版更是达到 4.29 s(5.5 倍)。
GPU 场景(NVIDIA GB10):f16 版比官方 bf16 模型快约 1.7 倍,推荐的 q8_0 版快 1.9~2.1 倍,且检测框完全一致。
选择建议:
- 内存/显存充足、追求极致稳定 →
q8_0(默认推荐) - 内存紧张、想跑得更快 →
q4_k/q5_k - 精度对齐验证场景 →
f16
❓ 常见问题(FAQ)
Q1:必须用 GPU 吗?
不用。纯 CPU 也能高效推理,q8_0 版在高端 CPU 上单张图仅需约 6 秒。想用 GPU 则构建时加 -DLA_GGML_CUDA=ON,运行时设置 LA_DEVICE= 即可自动使用 GPU。
Q2:检测结果和官方 PyTorch 版本一样吗? 是的。引擎经过与官方实现的对齐校验(parity-gated),q8_0 和 q6_k 版本的检测框与 f32 完全一致;更低位宽(q5_k/q4_k)只有亚像素级的微小漂移。
Q3:模型文件从哪里来? 模型权重来自 NVIDIA 的 LocateAnything-3B,本仓库以 GGUF 形式重新分发,配合 MIT 许可的 locate-anything.cpp 引擎使用。
Q4:想要完整 f32 精度版本怎么办?
README 中说明了可用主仓库的转换脚本 scripts/convert_locateanything_to_gguf.py 从 HF 权重自行复现(约 15 GB)。
📚 延伸阅读
- 完整说明与性能测试数据:README.md
- 各量化档位文件:locate-anything-q8_0.gguf、locate-anything-q4_k.gguf
- 量化权衡与 GPU 加速实测图:quant_tradeoff.png、gpu_speedup.png
✨ 从克隆仓库到看到第一张标注好的检测图,10 分钟绰绰有余——无需 Python、开箱即用的开放词汇目标检测,现在就开始吧!

