跳到主要内容

JVector

https://github.com/jbellis/jvector

JVector 是一个纯 Java 的嵌入式向量搜索引擎，使用基于图的索引提供高性能近似最近邻（ANN）搜索。它融合了 DiskANN 与 HNSW 算法族，在可配置的精度/性能权衡下提供快速相似度搜索。

Maven 依赖​

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-jvector</artifactId>
    <version>1.18.1-beta28</version>
</dependency>

注意：这是一个社区集成模块。你可能需要将 langchain4j-community 仓库添加到项目配置中。

API​

  • JVectorEmbeddingStore

功能​

  • 纯 Java 实现：无需原生依赖，凡是能运行 Java 的地方都能运行
  • 基于图的索引：使用带 Vamana 算法的 HNSW 层次结构进行高性能 ANN 搜索
  • 默认内存模式：搜索速度快，可选磁盘持久化
  • 可配置性能：通过 maxDegree 和 beamWidth 等参数调节精度/速度权衡
  • 多种相似度函数：支持 DOT_PRODUCT（默认）、COSINE 和 EUCLIDEAN 距离度量
  • 线程安全：非阻塞并发控制允许安全的并发访问
  • 磁盘持久化：可选的索引保存/加载功能
  • 动态更新：索引创建后仍可添加和删除 embedding

基本用法​

内存存储​

创建一个简单的内存 embedding store：

EmbeddingStore<TextSegment> store = JVectorEmbeddingStore.builder()
    .dimension(384)                    // Must match your embedding model's dimension
    .build();

持久化存储​

创建带磁盘持久化的 embedding store：

EmbeddingStore<TextSegment> store = JVectorEmbeddingStore.builder()
    .dimension(384)
    .persistencePath("/path/to/index") // Base path for index files
    .build();

// Add embeddings...
store.add(embedding, textSegment);

// Save to disk
((JVectorEmbeddingStore) store).save();

当你使用 persistencePath 创建 store 时，如果该位置已存在文件，索引会自动从磁盘加载。

配置选项​

JVector 提供多个构建器选项来调节性能：

EmbeddingStore<TextSegment> store = JVectorEmbeddingStore.builder()
    .dimension(384)                    // Required: embedding dimension
    .maxDegree(16)                     // Graph connectivity (default: 16)
    .beamWidth(100)                    // Index construction quality (default: 100)
    .neighborOverflow(1.2f)            // Overflow during construction (default: 1.2)
    .alpha(1.2f)                       // Diversity parameter (default: 1.2)
    .similarityFunction(VectorSimilarityFunction.DOT_PRODUCT) // Default
    .persistencePath("/path/to/index") // Optional: enable persistence
    .build();

参数指南​

  • dimension：必须与 embedding 模型的输出维度匹配（必需）
  • maxDegree：控制每个节点的图连接数。更高的值可提高召回率但会占用更多内存。推荐：16（默认）
  • beamWidth：控制索引构建质量。更高的值能构建更好的索引但耗时更长。推荐：100（默认）
  • neighborOverflow：内存索引推荐 1.2（默认），基于磁盘的索引推荐 1.5
  • alpha：控制边距离与多样性之间的权衡。高维向量推荐 1.2（默认），低维（2D/3D）向量推荐 2.0
  • similarityFunction：
    • DOT_PRODUCT - 对归一化向量最快（默认）
    • COSINE - 用于余弦相似度
    • EUCLIDEAN - 用于欧氏距离

持久化​

JVector 支持将索引保存到磁盘以及从磁盘加载：

// Create store with persistence enabled
JVectorEmbeddingStore store = JVectorEmbeddingStore.builder()
    .dimension(384)
    .persistencePath("/path/to/index")
    .build();

// Add embeddings
store.add(embeddings, textSegments);

// Save to disk (creates .graph and .metadata files)
store.save();

// Later: Load automatically when creating with same path
JVectorEmbeddingStore loadedStore = JVectorEmbeddingStore.builder()
    .dimension(384)
    .persistencePath("/path/to/index")
    .build();
// All previous embeddings and index structure are restored

持久化会创建两个文件：

  • {path}.graph - 带向量的图索引结构
  • {path}.metadata - Embedding ID、文本片段和元数据

当前限制​

  • 无元数据过滤：JVector 不支持在搜索操作期间按元数据过滤搜索结果。所有过滤必须在搜索后进行。
  • 修改时重建索引：添加或删除 embedding 会使索引失效，并在下次搜索时重建。为获得最佳性能，请尽可能批量添加。
  • 维度必须匹配：所有 embedding 的维度必须与创建 store 时指定的维度相同。

性能特征​

JVector 针对以下场景进行了优化：

  • 快速相似度搜索：搜索具有对数时间复杂度
  • 线性可扩展性：索引构建随 CPU 核心数线性扩展
  • 内存效率：仅使用内存索引，可选磁盘持久化
  • 高召回率：基于图的方法在适当调优下通常可达到 >98% 的召回率

理想用例：

  • 需要向量搜索但不想引入外部依赖的嵌入式应用
  • 开发与测试环境
  • 希望完全控制索引的生产部署
  • 需要磁盘持久化但不想使用独立数据库的应用

示例​