内容
# 定位任意对象 - CoreML
[](https://github.com/devin-lai/locateanything-coreml/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
[](https://huggingface.co/devin-lai/LocateAnything-3B-CoreML)
**NVIDIA 的 [LocateAnything-3B](https://huggingface.co/nvidia/LocateAnything-3B) 在 Apple Silicon 上原生运行 — 纯 CoreML，无 PyTorch 运行时。**
在 Mac 上进行开放词汇对象检测、视觉定位和点击。适用于数据集预注释、本地视觉工具和标注工作流，需要强大的定位能力，无需 PyTorch 运行时。
源代码位于此 GitHub 仓库。模型文件位于 [Hugging Face](https://huggingface.co/devin-lai/LocateAnything-3B-CoreML)。
## 亮点
- **原生 Mac 运行时**：CoreML 软件包加上 numpy；推理时无需 PyTorch 依赖。
- **灵活的提示**：定位自由文本类别并返回原始图像像素坐标的边界框或点。
- **有用的接口**：CLI、Python API、localhost REST 服务器和 MCP stdio 工具共享相同的确定性管道。
- **适用于注释的导出**：写入 JSON、COCO、YOLO 和 Label Studio 输出，以便在现有的标注工具中快速审查。
- **跟踪进展**：星标仓库以跟踪基准更新、量化工作和原生 Mac 示例。
## 快速开始
```bash
pip install locateanything-coreml
locateanything photo.jpg --categories person,car --temperature 0
```
或者在不安装到环境的情况下运行 - 模型缓存会被共享：
```bash
uvx --from locateanything-coreml locateanything photo.jpg --categories person,car
pipx install locateanything-coreml # 独立安装，`locateanything` 在 PATH 中
```
首次运行会从 [devin-lai/LocateAnything-3B-CoreML](https://huggingface.co/devin-lai/LocateAnything-3B-CoreML) 下载模型快照（约 7.2 GB）并缓存。默认推理是确定性的（`temperature=0`）；如果需要采样输出，请设置 `--temperature 0.7`。
### Python API
```python
from locateanything_coreml import LocateAnything
model = LocateAnything.from_pretrained()
detections = model.detect("photo.jpg", ["person", "car"])
```
边界框和点以原始图像像素坐标返回。
## 性能
在 Apple M5 / 32 GB 上测量（1536×1024 输入，类别 `person,car`），比较加载后推理与 PyTorch MPS bf16 参考：
| 指标 | CoreML 优化 | PyTorch MPS bf16 | 改进 |
|---|---:|---:|---:|
| 加载后推理时间 | 11.7 秒 | 12.7 秒 | 约 1.1 倍更快 |
| 生成时间 | 7.64 秒 | 12.56 秒 | 约 1.6 倍更快 |
| 预填充时间 | 1.72 秒 | 7.97 秒 | 约 4.6 倍更快 |
| 每秒令牌数 | 17.55 TPS | 10.35 TPS | 约 1.7 倍更高吞吐量 |
模型加载在首次调用时是一次性约 35 秒；之后软件包保持温暖（参见 [服务器](#运行为本地服务器) 和 [MCP](#用作MCP工具) 模式，以支付一次每会话的费用）。
完整的基准测试注释位于 [Hugging Face 模型卡](https://huggingface.co/devin-lai/LocateAnything-3B-CoreML)。
## 准确性
与 PyTorch（MPS，bf16）参考验证：
- 平均 IoU **0.988**（6/6 边界框）和 **0.963** 贪婪（20/20 边界框）在验证图像上；
- 与 fp32 基准运行相比，CoreML 管道的总边界框坐标增量（11 像素）*小于* bf16 参考的自身增量（12 像素）- 即转换噪声低于参考自身的精度噪声。
## 为什么选择这个而不是 GroundingDINO / OWLv2 / YOLO-World？
所有四个都进行开放词汇检测。区别在于它们在运行时需要什么以及它们返回的内容：
| | locateanything-coreml | GroundingDINO / OWLv2 | YOLO-World |
|---|---|---|---|
| Mac 上的运行时栈 | CoreML + numpy，**无 PyTorch** | PyTorch（MPS） | PyTorch / ONNX |
| 开放词汇边界框 | ✅ | ✅ | ✅（提示调整） |
| 点击 + 视觉定位 | ✅（基于 VLM） | ❌ | ❌ |
| 通过语言计数 | ✅ | ❌ | ❌ |
| 实时视频速率 | ❌（~12 秒/图像） | ❌ 在 Mac 上 | ✅ |
| 内置 MCP / REST / 注释导出 | ✅ | ❌ | ❌ |
选择 YOLO-World 时，您需要实时速度。选择此选项时，您希望从 3B VLM 获得 **质量** 定位能力，而无需在 Mac 上引入 PyTorch 栈 - 例如预注释数据集、添加本地 MCP 视觉或使用自由文本类别批量检查图像。
## 工作原理
- **固定画布视觉**：每个输入都被拉伸到 1036×1036 画布（74×74 补丁网格），因此一个转换的视觉软件包涵盖任何源分辨率；边界框解码在 0-1000 归一化坐标中取消拉伸。
- **状态解码器**：Qwen2 36 层解码器使用 CoreML `StateType` KV-cache 状态转换；注意力掩码作为输入传递，使参考的混合 MTP（并行边界框解码）/ AR 回退生成在图外。
- **fp16 with fp32 岛**：软件包为 fp16，RMSNorm / softmax / lm_head 固定为 fp32 以匹配参考数值。
- **纯 numpy 生成**：掩码、top-p 采样、重复惩罚和并行边界框解码是参考推理代码的逐字 numpy 端口。
## CLI 参考
```
locateanything INPUT --categories CATS [-o OUT.png] [--out-json OUT.json]
[--format {json,coco,yolo,labelstudio}]
[--models-dir DIR] [--repo-id REPO] [--revision REV]
[--compute-units {cpu_and_gpu,cpu_only,all}]
[--generation-mode {fast,slow,hybrid}]
[--temperature T] [--top-p P] [--repetition-penalty R]
[--seed N] [--max-new-tokens N]
locateanything serve [--port 8765] [--models-dir DIR] [--repo-id REPO] [--revision REV]
locateanything mcp [--models-dir DIR] [--repo-id REPO] [--revision REV]
```
`--temperature 0` 提供确定性贪婪解码。`--revision` 固定一个 Hugging Face 分支、标签或提交。
## 用作 MCP 工具
```bash
pip install 'locateanything-coreml[mcp]'
locateanything mcp
```
客户端配置：
```json
{
"mcpServers": {
"locateanything": {"command": "locateanything", "args": ["mcp"]}
}
}
```
或通过 `uvx` 零安装：
```json
{
"mcpServers": {
"locateanything": {
"command": "uvx",
"args": ["--from", "locateanything-coreml[mcp]", "locateanything", "mcp"]
}
}
}
```
一个工具被公开 - `detect_objects(image_path, categories, temperature=0, save_annotated=false)` - 返回具有像素坐标检测结果的结构化结果，并可选地写入注释图像，以便客户端查看结果。
首次调用加载模型（~35 秒）；它们在会话中保持温暖。
## 运行为本地服务器
支付约 35 秒的模型加载费用，然后每秒检测请求：
```bash
locateanything serve --port 8765
```
```bash
curl -s localhost:8765/detect \
-d '{"image_path": "/abs/path/photo.jpg", "categories": ["person", "car"]}'
```
`GET /openapi.json` 公开本地 API 模式。`image_b64`（base64 图像字节）代替 `image_path`; `"format"` 选择 `json`（默认）/ `coco` / `yolo` / `labelstudio`; 生成参数（`temperature`, `seed`, ...）与 CLI 匹配。绑定 `127.0.0.1` 仅作为本地单用户工具，而不是生产服务器。
## 为注释工具导出
```bash
locateanything photo.jpg --categories person,car --format coco
locateanything photo.jpg --categories person,car --format yolo
locateanything photo.jpg --categories person,car --format labelstudio
```
Label Studio 输出是可直接导入的预测（边界框**和**点）；COCO 和 YOLO 仅限边界框（跳过点并带有警告）。YOLO 编写 `<input>.detections.txt`; 其他编写 `<input>.detections.json`。使用它来预注释数据集，然后手动纠正。
更多 MCP 客户端、REST 调用者、Label Studio、CVAT 和 Roboflow 的集成说明位于 [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)。
## 要求
- Apple Silicon 上的 macOS（CoreML 执行）
- Python ≥ 3.10
- 模型快照的磁盘空间约 8 GB；推荐 32 GB RAM
## 项目布局
- `src/locateanything_coreml/`：Python 软件包、CLI、REST 服务器、MCP 服务器、预处理、生成和导出适配器。
- `examples/`：演示图像和小型客户端代码段。
- `docs/`：发布和集成说明。
- 模型权重故意从 GitHub 中排除，并在首次使用时从 Hugging Face 下载。
## 路线图
- [ ] 视频推理
- [x] MCP 客户端和注释管道的标准检测器接口 - MCP 服务器、本地 REST 服务器、COCO / YOLO / Label Studio 导出（v0.2）
- [x] 本地集成公开 OpenAPI 模式
- [ ] 量化（int8/int4）解码器变体
- [ ] 批量数据集推理
- [ ] Swift / 原生示例应用
## 许可证
代码在 [MIT](LICENSE) 下开源。CoreML 模型权重 **不** 受 MIT 许可保护；它们是 NVIDIA 的 LocateAnything-3B 的衍生品，在 [NVIDIA 许可](https://huggingface.co/devin-lai/LocateAnything-3B-CoreML/blob/main/LICENSE) 下仅用于研究和评估。参见 [NOTICE](NOTICE)。
## 引用
```bibtex
@article{locateanything2026,
title={LocateAnything: Fast and High-Quality Vision-Language Grounding with Parallel Box Decoding},
journal={arXiv preprint arXiv:2605.27365},
year={2026}
}
```
