JVector的ReadMe讲解

这个文件是 JVector 项目的完整文档，详细介绍了它的架构、使用方式、性能优势和构建方法。JVector 是一个基于图的 近似最近邻搜索（ANN）索引库，结合了 HNSW 和 DiskANN 的优点，适用于 高维向量检索场景，比如大语言模型生成的向量搜索、图像/音频/文本匹配等。

---

🔍 背景：什么是 JVector？

在高维空间中，传统的 KNN（最近邻）算法效率低下，因此发展出 近似最近邻（ANN） 技术。

JVector 就是一个用于 ANN 的 图索引（graph-based index）库，它：

• 采用 HNSW 的分层结构
• 每一层用 DiskANN 的 Vamana 算法 构建
• 支持 磁盘存储 + 两阶段搜索，降低内存占用
• 支持增量构建、压缩、以及构建超大规模索引

---

⚙️ 核心架构

JVector 架构如下：

层级	描述
上层	存在于内存，快速跳转，无 IO
底层	存储在磁盘，每个节点有邻接表；使用压缩版本进行第一阶段粗搜索，然后使用完整向量精细搜索
压缩方式	支持 PQ（Product Quantization）、BQ（Binary Quantization）、Fused ADC
高效构建	构建过程中也使用两阶段搜索，因此可构建超过内存容量的大型索引

---

🛠️ 关键步骤说明（每个步骤 Java 示例都有）：

✅ Step 1：在内存中构建并搜索索引

• 使用 GraphIndexBuilder 构建索引
• 使用 GraphSearcher 进行搜索
• 搜索中使用的是欧几里得距离（Euclidean）

✅ Step 2：更灵活的搜索控制

• 通过自定义 SearchScoreProvider 控制搜索策略（可用于 PQ/BQ）

✅ Step 3：评估搜索准确率（Recall）

• 内置 testRecall 方法支持评估准确率（返回约 99% recall）

✅ Step 4：写入/读取磁盘索引

• OnDiskGraphIndex.write 持久化索引
• 使用 ReaderSupplier 和 OnDiskGraphIndex.load 重新加载

✅ Step 5：使用压缩向量（PQ）

• PQ 进行向量压缩（减少内存）
• 采用两阶段搜索（PQ 粗排 + 原始向量精排）
• PQ 向量保存为 .pq 文件

✅ Step 6：增量构建大型索引（适用于无法全量放入内存的情况）

• 支持逐条写入向量并更新图结构
• 使用 OnDiskGraphIndexWriter 构建磁盘索引

---

📌 额外说明 & 高级特性

• PQ codebook 可复用：只要 embedding 模型不变，可重复使用 PQ 编码簇
• 支持线程池调度：使用 PhysicalCoreExecutor 限制线程
• 支持删除节点：支持标记删除并在 cleanup 中修复图结构
• 支持多层级构建：参数设置中设置 useHierarchy = true
• 支持向量模块加速（SIMD）：JDK 20+ 会启用 Vector API

---

🧪 开发与测试

项目是多模块 Maven 构建，兼容 Java 11 到 20+。使用 mvn compile exec:exec@sift 可以运行 Sift 示例。

你可以选择不同的数据集测试（如 glove、nytimes）：

mvn compile exec:exec@bench -DbenchArgs="glove nytimes"

---

📚 背后研究文献

• HNSW
• DiskANN
• Anisotropic PQ
• Quicker ADC

---

✅ 总结

JVector 是一个高性能、可扩展的 Java 向量搜索库，适合用在：

• 大规模检索系统（语义搜索、推荐系统等）
• 内存受限场景（支持增量构建与磁盘存储）
• 多线程环境（非阻塞构建，线程池优化）

如果你正在开发或研究 ANN 系统，JVector 是一个结构清晰、文档丰富、性能优良的 Java 实现。

---

如需我帮你运行示例代码、可视化架构、或者解释某一段代码实现逻辑，请告诉我！