Chroma HNSWlib

Warnings

• breaking Direct installation fails for Python 3.13 due to a lack of pre-built wheels and potential compilation issues. Additionally, there are no pre-built wheels for Python 3.12 on Windows.
  Fix: Use Python versions up to 3.12. On Windows for Python 3.12, or for Python 3.13 on any OS, you may need to compile from source, which requires C++ build tools.
• gotcha Building `chroma-hnswlib` from source (e.g., if a wheel is not available for your OS/Python version, or using `--no-binary`) requires C++ build tools (e.g., Microsoft Visual C++ 14.0 or greater on Windows). This can lead to build errors if dependencies are not met.
  Fix: Ensure that the necessary C++ compiler and build tools are installed and configured on your system before attempting a source build. For Windows, install 'Microsoft C++ Build Tools'.
• gotcha For maximum performance, especially leveraging Advanced Vector Extensions (AVX) if your hardware supports it, you may need to force recompilation of the library by installing with `--no-binary chroma-hnswlib`. Pre-built wheels are compiled for broader compatibility and might not use AVX.
  Fix: Uninstall the pre-built version if present (`pip uninstall chroma-hnswlib`) and then reinstall with `pip install --no-binary chroma-hnswlib`.
• gotcha HNSWlib's memory usage is typically higher compared to some other Approximate Nearest Neighbor (ANN) libraries because it needs to store the graph structure in memory, which scales with the number of elements and the `M` parameter.
  Fix: Monitor memory consumption, especially with large datasets or high `M` values. Adjust `M` or consider on-disk solutions for extremely large datasets.
• gotcha Optimal performance (trade-off between query speed, index build time, and recall) depends on tuning parameters like `M`, `ef_construction`, and `ef_search`. Incorrect settings can lead to poor search accuracy or slow operations.
  Fix: Experiment with different parameter values based on your dataset size, dimensionality, and performance requirements. Higher `M` and `ef_construction` generally improve recall at the cost of slower build/higher memory. Higher `ef_search` improves recall at the cost of slower queries.

Install

• pip install chroma-hnswlib Install latest version

Imports

• Index

  import hnswlib
  index = hnswlib.Index(space='l2', dim=128)

  The `chroma-hnswlib` package provides the `hnswlib` module for direct use, mimicking the upstream hnswlib API.

Quickstart

This quickstart demonstrates how to initialize an HNSW index, add random 128-dimensional vectors to it, and then perform an approximate k-nearest neighbor search. Key parameters like `ef_construction` and `M` are set during index initialization to tune performance and accuracy.

import hnswlib
import numpy as np

dim = 128
num_elements = 10000

# Generate random data
data = np.float32(np.random.random((num_elements, dim)))
data_labels = np.arange(num_elements)

# Initialize and configure the index
# 'l2' for Euclidean distance, 'ip' for inner product, 'cosine' for cosine similarity
index = hnswlib.Index(space='l2', dim=dim)
index.init_index(max_elements=num_elements, ef_construction=200, M=16)

# Add elements to the index
index.add_items(data, data_labels)

# Perform a search
num_queries = 5
query_data = np.float32(np.random.random((num_queries, dim)))
k = 10 # Number of nearest neighbors to return

labels, distances = index.knn_query(query_data, k=k)

print("Query Results (labels, distances):")
for i in range(num_queries):
    print(f"  Query {i}: {labels[i]}, {distances[i]}")