别再调远程接口！把 jVector 嵌入式向量搜索引擎装进 Java 服务

---

一、向量检索为什么要「本地」化

1. 网络抖动不可控，高并发场景下长尾延迟被无限放大
2. 按量计费 + 出口带宽 = 隐形成本，业务越火账单越贵
3. 医疗、工业、车载等场景对「数据不离域」有硬性合规要求
4. 无状态微服务潮流下，Sidecar 需要「带脑子」——搜索能力随实例漂移

→ jVector 给出一条新路径：
把索引当成资源文件打进 Jar，随进程启停，不依赖 GPU、不额外开端口、不写 C++。

---

二、jVector 技术底座速览

1. 分层可导航小世界（HNSW）
   上层「高速」节点少、跳数少 → 毫秒级定位候选区；下层「街道」精细连通 → 保证召回
2. Vamana（DiskANN 内核）
   长边+贪婪搜索，避免局部最优；磁盘邻接表 + mmap → 内存只占热点页
3. 两级量化
   ① NVQ：非均匀量化，Recall 损失 < 1%，内存再降 30%
   ② Fused ADC：码本与图邻接表同页存储，CPU 缓存命中率 +15%
4. 并发构建
   非阻塞多线程建图，线程数与 CPU 核数成正比，小时级数据也可「边写边查」

---

三、整体使用思路（七步法）

1. 选维度
   文本 50~100 维、图像 256~512 维、音频 128 维常见；维数越高，量化收益越大
2. 选相似度函数
   内积（IP）适合归一化向量，欧氏（L2）适合绝对距离，余弦可直接转 IP
3. 离线建码本（可选）

   10 万条样本即可训练出稳定 PQ/NVQ 码本，后续复用同一个码本不断追加向量

4. 离线建图
   内存 or 磁盘两种方式；磁盘模式支持 TB 级、增量模式支持小时级实时写入
5. 资源文件随包发布
   索引、*.codebook、词典统一放入 src/main/resources/vector/；Docker 镜像无需额外 Dockerfile
6. 运行期 mmap 加载
   启动即加载，多实例共享同一物理页；查询阶段零拷贝、零 GC
7. 线上热更新
   新版本索引写入 *.idx.new，应用捕获外部信号或配置中心事件，原子切换 ReaderSupplier

---

四、Step-by-Step 实战：从原始数据到线上查询

① 训练码本（一次即可）

List<VectorFloat<?>> sample = SampleLoader.randomSubset(fullSet, 128_000);
ProductQuantization pq = ProductQuantization.compute(sample, 16, 256, true);
pq.write(Files.newOutputStream(Paths.get("codebook.pq")));

② 磁盘增量建图（流式）

ReaderSupplier codeIn = ReaderSupplierFactory.open(Paths.get("codebook.pq"));
PQVectors pqv = PQVectors.load(codeIn.get());

Path idx = Paths.get("embed.idx");
BuildScoreProvider bsp = BuildScoreProvider.pqBuildScoreProvider(IP, pqv);

try (GraphIndexBuilder builder = new GraphIndexBuilder(bsp, 128, 24, 128, 1.5f, 1.2f, true);
     OnDiskGraphIndexWriter w = new OnDiskGraphIndexWriter.Builder(builder.getGraph(), idx)
             .with(new InlineVectors(128))
             .build()) {

    // 逐条消费 Kafka 流
    stream.forEach(vec -> {
        int ord = pqv.size();
        pqv.add(pq.encode(vec));          // 压缩
        w.writeInline(ord, vec);          // 原向量落盘
        builder.addGraphNode(ord, vec);   // 图节点
    });

    builder.cleanup();
    w.write(Map.of());
}

③ 应用内加载与查询

@Component
public class VectorSearchService {
    private final GraphIndex index;
    private final PQVectors pqv;
    private final ProductQuantization pq;

    public VectorSearchService() throws IOException {
        this.index = OnDiskGraphIndex.load(ReaderSupplierFactory.open(Paths.get("embed.idx")));
        this.pq  = ProductQuantization.load(Files.newInputStream(Paths.get("codebook.pq")));
        this.pqv = PQVectors.load(ReaderSupplierFactory.open(Paths.get("embed.idx")).get());
    }

    public List<Result> search(float[] q, int k) {
        VectorFloat<?> vf = new ArrayVectorFloat(q);
        Function<VectorFloat<?>, SearchScoreProvider> factory =
                query -> {
                    ApproximateScoreFunction asf = pqv.precomputedScoreFunctionFor(query, IP);
                    Reranker rerank = index.getView().rerankerFor(query, IP);
                    return new SearchScoreProvider(asf, rerank);
                };
        try (GraphSearcher searcher = new GraphSearcher(index)) {
            SearchResult sr = searcher.search(factory.apply(vf), k, Bits.ALL);
            return Arrays.stream(sr.getNodes())
                         .map(n -> new Result(idMap[n.node], n.score))
                         .collect(toList());
        }
    }
}

---

五、四种常见业务落地模板

场景	维数	数据量	压缩	更新策略
输入法补全	50	300 万 3-gram	NVQ	每日增量 addGraphNode()
车载 POI	100	20 万兴趣点	PQ	月度整包替换
工业网关	128	1 秒 1 条振动	PQ	循环写满后滚动删除
微服务 Sidecar	256	1000 万商品	NVQ	双指针热切换

---

六、性能与资源估算（经验公式）

• 查询延迟 ≈ 2 × 层数 + 邻居数 × 0.05 ms（单核 2.4 GHz）
• 内存占用 ≈ 压缩向量大小 + 图边列表 + mmap 页缓存（冷页自动回收）
• 索引大小 ≈ 原始向量 × 压缩比 + 图边 × 4 B（M=24 时约 1.3 倍原大小）

举例：
100 万条 128 维向量，NVQ 16∶1，M=24 → 索引文件 ≈ 130 MB，查询 P99 < 5 ms，内存 < 200 MB

---

七、上线 checklist

1. 索引文件放 CDN → 应用启动多线程下载，防止本地解压失败
2. 信号量热切换 → 下载完成触发 SIGUSR1 或配置中心事件，原子替换 ReaderSupplier
3. 监控埋点 → 记录 QPS、P99、异常召回率，低于阈值自动回滚索引版本
4. 灾备 → 保留上一版本索引文件，秒级回切
5. 版权与合规 → 训练码本与向量数据需在同一授权域内，避免跨域复制

---

八、小结

jVector 把「重量级向量数据库」转化为「随包发布的轻量文件」——
无需 GPU、无需后台、无需网络，Java 服务启动即拥有毫秒级、高召回、易扩展的本地语义检索能力。
从边缘网关到车载终端，从微服务 Sidecar 到离线安卓，一次打包，随处运行，让向量搜索真正「嵌入」到你的每一次 Java 调用中。