MinishLab/vicinity

Vicinity – 拡張可能なバックエンドを備えた軽量近似最近傍検索ストア

何であるか – Vicinity は、ベクトル（例えば言語モデルからの埋め込み）を格納し、高速な最近傍検索を実行できる Python ライブラリです。FAISS、HNSW-lib、Annoy、Usearch など、多数の人気 ANN エンジンを、単一で依存が少ない API の背後にラップしており、コードを変更せずにインデックスのバックエンドを切り替えることができます。

なぜ重要か – 検索拡張生成（RAG）、意味検索、推薦、クラスタリングなどの多くの 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 の参照を引用してください。