Voyager 是一个用于在内存中的向量集合上执行快速近似最近邻搜索的库。

Voyager 同时提供了 Python 和 Java 的绑定，两种语言的功能对等且索引兼容。它基于 开源 hnswlib 包，使用了 HNSW 算法，并添加了许多便捷性和速度方面的功能。Voyager 在 Spotify 的生产环境中被广泛使用，每天会被查询数亿次，以支持众多面向用户的功能。

可以将 Voyager 看作是针对向量/嵌入数据的 Sparkey，或者说是 Annoy 的升级版，但具有 更高的召回率。它的名字来源于其在（嵌入）空间中进行搜索的方式，类似于 NASA 于 1977 年发射的 旅行者号星际探测器。

安装

Python

pip install voyager

Java

将以下依赖项添加到你的 pom.xml 文件中：

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

你可以在 Voyager 的发布页面 上找到最新版本。

Scala

将以下依赖项添加到你的 build.sbt 文件中：

"com.spotify" % "voyager" % "2.1.0"

你同样可以在 Voyager 的发布页面 上找到最新版本。

兼容性

操作系统	语言	版本	x86_64 (Intel)	arm64 (ARM)
Linux	Python	3.9	✅	✅
Linux	Python	3.10	✅	✅
Linux	Python	3.11	✅	✅
Linux	Python	3.12	✅	✅
Linux	Python	3.13	✅	✅
Linux	Java	8-16+	✅	✅
macOS	Python	3.9	✅	✅
macOS	Python	3.10	✅	✅
macOS	Python	3.11	✅	✅
macOS	Python	3.12	✅	✅
macOS	Python	3.13	✅	✅
macOS	Java	8-16+	✅	✅
Windows	Python	3.9	✅	❌
Windows	Python	3.10	✅	❌
Windows	Python	3.11	✅	❌
Windows	Python	3.12	✅	❌
Windows	Python	3.13	✅	❌
Windows	Java	8-16+	✅	❌

贡献

欢迎为 voyager 做出贡献！ 详细信息请参阅 CONTRIBUTING.md。

许可证

Voyager 版权所有 © 2022–2024 Spotify AB。

Voyager 根据 Apache 2 许可证 进行授权。

Voyager 快速上手指南

Voyager 是由 Spotify 开源的高性能近似最近邻（ANN）搜索库，基于 HNSW 算法构建。它支持 Python 和 Java，专为内存中的向量/嵌入数据设计，具有极高的查询速度和召回率，广泛应用于生产环境。

1. 环境准备

系统要求

Voyager 支持以下操作系统和架构：

• Linux: 支持 x86_64 (Intel) 和 arm64 (ARM/Apple Silicon)。
• macOS: 支持 x86_64 (Intel) 和 arm64 (Apple Silicon)。
• Windows: 仅支持 x86_64 (Intel)，不支持 ARM 架构。

语言版本兼容性

• Python: 3.9, 3.10, 3.11, 3.12, 3.13
• Java: 8 - 16+

2. 安装步骤

Python 安装

使用 pip 直接安装。国内用户推荐使用清华或阿里云镜像源以加速下载：

pip install voyager -i https://pypi.tuna.tsinghua.edu.cn/simple

或者使用默认源：

pip install voyager

Java 安装

在 pom.xml 中添加以下依赖：

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

Scala 安装

在 build.sbt 中添加以下依赖：

"com.spotify" % "voyager" % "2.1.0"

注意：请前往 Voyager Releases 页面 获取最新版本号。

3. 基本使用 (Python 示例)

以下是最简单的使用流程：创建索引、添加向量、执行搜索。

import numpy as np
from voyager import Index, Space

# 1. 初始化索引
# Space.Euclidean 表示欧几里得距离，也可使用 Space.Cosine
index = Index(space=Space.Euclidean, num_dimensions=3)

# 2. 准备数据 (例如 5 个 3 维向量)
data = np.random.rand(5, 3).astype('float32')
ids = [0, 1, 2, 3, 4]

# 3. 将向量添加到索引中
index.add_items(data, ids)

# 4. 执行查询
# 查询一个随机向量，返回最近的 2 个邻居
query_vector = np.random.rand(3).astype('float32')
labels, distances = index.query(query_vector, k=2)

print(f"最近邻 ID: {labels}")
print(f"对应距离: {distances}")

核心概念简述

• Index: 索引对象，负责存储向量和构建图结构。
• Space: 距离度量空间，常用 Space.Euclidean (欧氏距离) 或 Space.Cosine (余弦相似度)。
• add_items: 批量添加向量数据。
• query: 输入查询向量，返回最近邻的 ID 列表和距离列表。