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() 또는 Hugging Face Hub에 push_to_hub() / load_from_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 참조를 인용해 주세요.