Vicinity is the lightest-weight vector store. Just put in some vectors, calculate query vectors, and off you go. It provides a simple and intuitive API for nearest neighbor search, with support for different backends.
Install the package with:
pip install vicinityThe following code snippet demonstrates how to use Vicinity for nearest neighbor search:
import numpy as np
from vicinity import Vicinity
from vicinity.datatypes import Backend
# Create some dummy data
items = ["triforce", "master sword", "hylian shield", "boomerang", "hookshot"]
vectors = np.random.rand(len(items), 128)
# Initialize the Vicinity instance (using the basic backend)
vicinity = Vicinity.from_vectors_and_items(vectors=vectors, items=items, backend_type=Backend.BASIC)
# Query for nearest neighbors with a top-k search
query_vector = np.random.rand(128)
results = vicinity.query([query_vector], k=3)
# Query for nearest neighbors with a threshold search
results = vicinity.query_threshold([query_vector], threshold=0.9)
# Save the vector store
vicinity.save('my_vector_store')
# Load the vector store
vicinity = Vicinity.load('my_vector_store')Vicinity provides the following features:
- Lightweight: Minimal dependencies and fast performance.
- Flexible Backend Support: Use different backends for vector storage and search.
- Dynamic Updates: Insert and delete items in the vector store.
- Serialization: Save and load vector stores for persistence.
- Easy to Use: Simple and intuitive API.
The following backends are supported:
BASIC: A simple flat index for vector storage and search.HNSW: Hierarchical Navigable Small World Graph for approximate nearest neighbor search.PYNNDescent: Approximate nearest neighbor search using PyNNDescent.
Creating a Vector Store
You can create a Vicinity instance by providing items and their corresponding vectors:
from vicinity import Vicinity
import numpy as np
items = ["triforce", "master sword", "hylian shield", "boomerang", "hookshot"]
vectors = np.random.rand(len(items), 128)
vicinity = Vicinity.from_vectors_and_items(vectors=vectors, items=items)Querying
Find the k nearest neighbors for a given vector:
query_vector = np.random.rand(128)
results = vicinity.query([query_vector], k=3)Find all neighbors within a given threshold:
query_vector = np.random.rand(128)
results = vicinity.query_threshold([query_vector], threshold=0.9)Inserting and Deleting Items
Insert new items:
new_items = ["ocarina", "bow"]
new_vectors = np.random.rand(2, 128)
vicinity.insert(new_items, new_vectors)Delete items:
vicinity.delete(["hookshot"])Saving and Loading
Save the vector store:
vicinity.save('my_vector_store')Load the vector store:
vicinity = Vicinity.load('my_vector_store')MIT