MinishLab/vicinity

Vicinity – 支持可插拔后端的轻量级最近邻存储库

是什么 – Vicinity 是一个 Python 库，允许你存储向量（例如语言模型的嵌入）并执行快速的最近邻查询。它将多种流行的 ANN 引擎（FAISS、HNSW-lib、Annoy、Usearch 等）封装在单一、低依赖的 API 之后，让你无需更改代码即可切换底层索引。

为何重要 – 在许多 AI 应用（检索增强生成、语义搜索、推荐、聚类）中，你需要快速找到最相似的向量。现有库各自拥有独立的 Python 接口和配置特性，导致基准测试和切换非常痛苦。Vicinity 通过以下方式解决此问题：

统一的 Vicinity 类，
通用的度量标准（余弦、欧几里得等），
内置的查询每秒（QPS）和召回率评估，以及
通过 Hugging Face Hub 实现的简易持久化与共享。

核心功能

统一 API：支持多种后端（基础精确、FAISS、HNSW、Annoy、PyNNDescent、Usearch、Voyager）。
低依赖性：核心包依赖极少；可选扩展仅安装你需要的后端。
序列化：支持 save() / load() 本地磁盘保存，或 push_to_hub() / load_from_hub() 推送到 Hugging Face Hub。
评估辅助工具：在保留的查询集上报告 QPS 和召回率。
灵活配置：每个后端暴露其最相关的参数（例如 HNSW 的 ef_construction，FAISS IVF 的 nlist）。

典型工作流

import numpy as np
from vicinity import Vicinity, Backend, Metric

# 1️⃣ 准备数据
items   = ["triforce", "master sword", "hylian shield"]
vectors = np.random.rand(len(items), 128)

# 2️⃣ 构建索引（此处使用基础精确后端）
vic = Vicinity.from_vectors_and_items(
    vectors=vectors,
    items=items,
    backend_type=Backend.BASIC,
    metric=Metric.COSINE,
)

# 3️⃣ 查询 – top-k 或阈值
query = np.random.rand(128)
print(vic.query(query, k=3))               # → [(item, score), …]
print(vic.query_threshold(query, 0.9))    # → 相似度 ≥ 0.9 的项

# 4️⃣ 持久化 / 共享
vic.save('my_store')
# 或推送到 HuggingFace Hub
vic.push_to_hub(repo_id='my-username/my-vicinity')

安装 – 核心包非常轻量：

pip install vicinity          # 仅核心
pip install vicinity[all]    # 核心 + 所有可选后端及集成

你也可以只安装所需部分，例如 pip install vicinity[faiss]。

谁应该使用它

为新嵌入模型比较 ANN 算法的研究人员。
构建语义搜索或 RAG 流水线，希望在不重写代码的情况下尝试不同索引的工程师。
需要一个简单、可序列化、可通过 Hugging Face Hub 版本控制的向量存储的任何人。

许可与引用 – MIT 许可。若用于学术工作，请引用提供的 Zenodo 参考文献。

MinishLab/vicinity

Vicinity – 支持可插拔后端的轻量级最近邻存储库

相关