spotify/voyager

🛰️ An approximate nearest-neighbor search library for Python and Java with a focus on ease of use, simplicity, and deployability.

🎯 What is Voyager?

Voyager is an open‑source library that lets you search quickly through large collections of vectors (e.g., embeddings) using an approximate nearest‑neighbor (ANN) algorithm. It implements the HNSW (Hierarchical Navigable Small World) graph method, building on the popular hnswlib project but adding a number of performance and usability improvements. The library is available for Python, Java, and Scala, and the two language bindings share the same index format, so you can build an index once and query it from any of those runtimes.

🚀 Core Features (as described in the README)

Feature	Details
Fast ANN search	Uses HNSW, known for high recall and low query latency.
Cross‑language bindings	Identical index format and feature set for Python, Java, and Scala.
Production‑grade	Deployed at Spotify, handling hundreds of millions of queries per day.
In‑memory only	Index lives in RAM for ultra‑fast look‑ups (no on‑disk persistence).
Broad platform support	macOS, Linux, Windows; both x86_64 and ARM (Apple Silicon) for Python, ARM for Java on Linux/macOS.
Easy installation	`pip install voyager` for Python; Maven/Gradle or SBT coordinates for Java/Scala.
Apache 2.0 license	Free for commercial and non‑commercial use.

📦 Getting Started

Python

pip install voyager

import voyager as vg
# Example (pseudo‑code, see docs for exact API)
index = vg.Index(dim=128)
index.add(vectors, ids)
neighbors = index.search(query_vector, k=10)

Java (Maven)

<dependency>
  <groupId>com.spotify</groupId>
  <artifactId>voyager</artifactId>
  <version>2.1.0</version>
</dependency>

import com.spotify.voyager.Index;
// Build and query the index – see Java docs for exact calls

Scala (SBT)

libraryDependencies += "com.spotify" % "voyager" % "2.1.0"

🎯 Typical Use‑Cases

Semantic search over text embeddings (e.g., finding similar documents, FAQs, or product descriptions).
Recommendation systems that need to retrieve nearest items in embedding space.
Clustering / deduplication pipelines where fast similarity look‑ups are required.
Any AI/ML application that produces high‑dimensional vectors and needs real‑time nearest‑neighbor queries.

📚 Documentation & Resources

Python docs: https://spotify.github.io/voyager/python
Java docs: https://spotify.github.io/voyager/java
GitHub repo: https://github.com/spotify/voyager (includes CI status badge, contribution guide, and license).

🛡️ License

Voyager is released under the Apache 2.0 License (a permissive open‑source license). This allows free use, modification, and distribution, even in commercial products.

🙋‍♀️ Contributing

Contributions are welcomed. See the CONTRIBUTING.md file in the repo for guidelines on how to report bugs, propose enhancements, or submit pull requests.