工程实践与深度解析

• 1: 在 PostgreSQL 上将向量搜索扩展至 10 亿规模
• 2: 我们如何在 PostgreSQL 上实现 20 分钟构建 1 亿向量索引
• 3: 借助 VectorChord-BM25 将搜索引擎级排序引入 PostgreSQL
• 4: VectorChord：在 AWS 上高性价比地上传与搜索 4 亿向量
• 5: 在 PostgreSQL 中利用上下文检索优化 RAG
• 6: 一站式 VectorChord 套件：直接在 PostgreSQL 中构建生产就绪的 RAG 解决方案
• 7: 推出 Vechord：以 Pythonic 的方式将 PostgreSQL 打造成你的搜索引擎
• 8: 超越文本：使用 Modal 与 VectorChord 在 PostgreSQL 中解锁免 OCR 的 RAG
• 9: 在 PostgreSQL 中用 30 亿向量守护地球
• 10: PostgreSQL 向量搜索：内存与磁盘方案对比分析
• 11: PostgreSQL 全文检索：用对方法其实很快（打破“慢”的迷思）
• 12: VectorChord-BM25：推出独立的多语言高级搜索分词器 pg_tokenizer
• 13: 基于 Postgres 原生 BM25 与 VectorChord 的混合搜索
• 14: 使用 VectorChord 在 PostgreSQL 中实现 10,000 QPS 的向量搜索
• 15: VectorChord-BM25：用 BM25 排序彻底革新 PostgreSQL 搜索——速度比 ElasticSearch 快 3 倍
• 16: 我们真的需要专门的向量数据库吗？(2023)
• 17: 在 PostgreSQL 中使用 ColBERT 重排序为向量搜索赋能
• 18: ARM + VectorChord：高性价比的快速向量搜索
• 19: 为什么 HNSW 不是终极答案
• 20: VectorChord 外部聚类中心构建的优势与操作步骤
• 21: VectorChord：在 PostgreSQL 中仅花 $1 存储 40 万向量
• 22: 推出 PGVecto.rs Cloud：PostgreSQL 可扩展向量搜索现已上云
• 23: 为 PGVecto.rs Cloud 引入 Terraform 支持
• 24: 释放稀疏向量的强大潜能
• 25: pg_bestmatch.rs：用 BM25 全面提升 PostgreSQL 文本查询能力
• 26: 我的二值向量搜索比你的 FP32 向量更强
• 27: 2024 年 pgvector vs. pgvecto.rs：PostgreSQL 向量搜索全方位对比
• 28: 使用 LlamaIndex 与 pgvecto.rs 构建 RAG 流水线
• 29: 使用 pgvecto.rs 在 LangChain 中构建大语言模型应用
• 30: 我们真的需要专门的向量数据库吗？

1 - 在 PostgreSQL 上将向量搜索扩展至 10 亿规模

对于希望自行部署十亿级规模向量搜索的团队而言，真正的挑战往往不在于原始性能，而在于实用性。许多专为十亿级规模、低延迟向量搜索而设计的解决方案都伴随着诸多现实约束，需要在各种权衡中做出妥协，从而影响了落地的难易程度。

现有的大多数方案通常属于以下几类之一：

• 运维复杂：依赖多节点分布式系统，长期管理、运维和维护的难度较高。

• 构建耗时过长：需要漫长的索引构建时间，导致重建索引成本高昂，且极易影响生产环境负载。

• 内存开销巨大：单机往往需要高达 1 TB 的内存，高昂的硬件成本让大多数团队望而却步。

这些权衡在现有的公开基准测试中清晰可见。例如，ScyllaDB 报告在 DEEP-1B 数据集上实现了高达 98% 的召回率和 12.3 ms 的 P99 延迟，但这一结果依赖于多台大型实例。而在相同数据集和规模下，YugabyteDB 报告的长尾延迟明显更高，P99 达到了 0.319 秒。

在单节点部署方面，Scalable Vector Search (SVS) 此前的研究表明，使用 HNSWlib 为 DEEP-1B 构建索引通常需要 800 GiB 内存；尽管 SVS 或 FAISS-IVFPQs 可以将其降低至约 300 GiB，但这依然是一笔可观的硬件开销。

这使得希望坚持自托管的团队很难实现平滑扩展。从 100 万向量扩展到 10 亿向量，往往需要重新思考架构：要么改变硬件假设，要么重构业务工作流。

借助 VectorChord 1.0.0，规模扩展变得前所未有地简单。得益于全新的层次化 K-means（Hierarchical K-means）及其他优化，构建 10 亿向量索引与构建 100 万向量索引的流程完全一致。这也是我们实际使用它的方式：只需迁移到一台配置稍高一点的机器，例如从 AWS i7i.xlarge 升级到 i7i.4xlarge。

DEEP-1B 基准测试

为了验证 VectorChord 在十亿级向量规模下的能力，我们采用了来自 BIGANN 的 Yandex DEEP-1B 数据集。DEEP-1B 是大规模向量搜索领域广泛采用的基准数据集，包含由自然图像训练的深度学习模型生成的 10 亿条 96 维向量嵌入（embeddings）。

由于其庞大的规模，DEEP-1B 被广泛用作评估大规模向量搜索系统的基准数据集。其广泛的普及度使得测试结果易于复现和对比，尤其是在评估十亿级向量规模下的索引构建性能、查询延迟和资源效率时。

面对如此庞大的数据集，构建 VectorChord 索引需要：

• 存储：约 900 GB 的高性能 SSD

• 内存（shared_buffers）：不低于 60 GB，由 PostgreSQL 管理

• 内存（额外开销）：索引构建期间至少需要 60 GB 额外内存

基于上述要求，AWS i7i.4xlarge 是该规模下构建索引的最低配置。我们的测试在一台 AWS i7ie.6xlarge 上运行，这反映了实际生产部署中的常见做法——通过配置更多内存来减少磁盘访问并保持稳定的查询延迟。

所有实验均在 PostgreSQL 17 上使用 VectorChord 1.0.0 运行。下方 SQL 是我们用于构建索引的完整命令：

CREATE INDEX ON deep USING vchordrq (embedding vector_l2_ops) WITH (options = $$
build.pin = 2
residual_quantization = true
[build.internal]
build_threads = 24
lists = [800, 640000]
kmeans_algorithm.hierarchical = {}
$$);

构建配置中各个选项的作用如下：

• build.pin：启用构建期内存固定（pinning），将索引的热点部分缓存在共享内存中，从而加速大规模数据集上的索引构建。

• residual_quantization：在 DEEP-1B 上，我们发现启用**残差量化（residual quantization）**能够提升查询性能，因此在本基准测试中保持开启。

• build.internal.build_threads：在 K-means 构建阶段使用 24 个线程，充分跑满实例上的可用 CPU 资源。

• build.internal.lists：根据我们的经验，应根据数据行数选择合适的聚类列表大小。在大规模场景下，使用**双层列表（two-level list）**效果显著，能同时提升索引构建效率与查询性能。

• build.internal.kmeans_algorithm.hierarchical：启用 VectorChord 1.0 引入的**层次化 K-means（Hierarchical K-means）**路径，大幅加快大规模索引的构建速度。

测试结果

在单台 AWS i7ie.6xlarge 机器上使用 24 个 CPU 核心时，索引构建仅耗时 **6,408 秒（约 1.8 小时）**即告完成，证明十亿级规模的索引构建完全可以在切实可行的维护窗口内完成。

下图展示了在缓存预热（warm cache）状态下，使用单搜索线程在 Deep1B 数据集上评估 Top-10 和 Top-100 查询时的查询吞吐量（QPS）与召回率（Recall）关系。

对于 Top-10 查询，吞吐量从约 0.91 召回率下的超过 117 QPS，变化至约 0.95 召回率下的约 69 QPS。Top-100 查询也遵循相同的规律，随着召回率的提高，吞吐量相应下降。

下表列出了每个数据点对应的具体搜索参数（固定 epsilon = 1.9，改变探测聚类数 probes）。综合图表数据可以看出，即使在 10 亿向量规模下，VectorChord 依然能在单机上提供稳定且可调优的查询性能。

这些结果表明，即便在十亿级规模下，单机上的向量查询性能依然可以做到实用且可预测。

总结

VectorChord 1.0.0 证明了实时向量搜索可以从 100 万向量平滑扩展至 10 亿向量，而无需强迫用户改变架构、工作流或使用方式。无论您是在构建以图搜图、AI 驱动的应用，还是 RAG 流水线，VectorChord 都旨在成为运行在您自己机器上的可靠向量引擎，随数据增长而自然扩展。

准备好扩展规模了吗？您可以立即开始使用，也可以通过 GitHub 或 Discord 联系我们，了解更多信息并获取社区支持。

2 - 我们如何在 PostgreSQL 上实现 20 分钟构建 1 亿向量索引

1. 引言

在过去几个月里，我们收到了来自用户和合作伙伴的一致反馈：尽管我们提供可扩展、高性能 pgvector 替代方案的目标广受好评，但在十亿级规模下，索引构建时间和内存占用仍然是大家关注的主要痛点。

现在，VectorChord 可以在一台仅配备 12 GB 内存的 16 vCPU 机器上，在 20 分钟内为 1 亿个 768 维向量构建索引。相比之下，使用 pgvector 为相同规模的数据构建索引，在 16 核实例上需要大约 200 GB 内存和约 40 小时。而且当内存不足时，pgvector 往往会频繁触发页面交换（page swapping），导致构建速度进一步恶化。

简而言之，内存占用和构建时间已成为大规模部署向量检索的关键障碍。通过一系列有针对性的优化，我们将构建时间缩短至 20 分钟，内存占用降低了 7 倍，而精度损失微乎其微。

借助这些改进，我们现在可以使用内存小得多、价格低廉得多的机器（且无需 GPU），依然能够承载 1 亿个 768 维向量：

在接下来的章节中，我们将介绍如何优化各个阶段，使索引构建更快、更省内存。各项优化按阶段划分如下，每项优化分别针对一个阶段：

2. 背景

VectorChord 中使用的索引类型 vchordrq 在逻辑上是一棵高度为 \(n+1\) 的树。树的前 \(n\) 层是不可变的，纯粹作为检索时的路由结构；第 \((n+1)\) 层则存储所有实际数据。

如果 \(n=1\)，索引是一个扁平的、无分区的结构；如果 \(n=2\)，它就是一个倒排文件（IVF）索引；如果 \(n=3\)，则会多出一层路由结构。

索引构建过程可以分为 3 个阶段：初始化（Initialization）、插入（Insertion） 和 压缩（Compaction）。

• 初始化阶段（Initialization Phase）
  在此阶段，树的前 \(n\) 层被写入索引。首先，索引对表中的向量进行采样；然后，通过对样本进行聚类、对聚类中心再聚类，以此类推构建 \(n\) 层树结构；最后将这棵树写入索引。

• 插入阶段（Insertion Phase）
  索引将表中的向量插入到树的最底层。

• 压缩阶段（Compaction Phase）

  索引将所有已插入的向量从非紧凑布局（non-compact layout）转换为紧凑布局（compact layout）。

3. 让聚类更快、更省内存

过去，虽然我们可以在小规格实例上为 1 亿向量构建索引，但通常需要借助 GPU 来加速聚类计算。

初始化阶段的主要瓶颈在于聚类，它既耗时又消耗大量内存。事实上，正是聚类决定了构建索引的最低内存需求。如果我们能在 CPU 上以既快速又省内存的方式实现聚类，那么在没有大内存和 GPU 的小规格实例上构建索引就变得切实可行了。

设 \(n\) 为向量数量，\(c\) 为聚类中心（质心）数量，\(d\) 为向量维度，\(l\) 为迭代次数。K-means 的时间复杂度为 \(O(ncdl)\)，空间复杂度为 \(O(nd + cd)\)。设 \(f\) 为采样系数，即 \(n=fc\)。此时 K-means 的时间复杂度为 \(O(fc^2dl)\)，空间复杂度为 \(O(fcd)\)。

在接下来的小节中，我们将解释如何降低算法复杂度，并减小 \(d\) 和 \(f\) 以获得更好的性能。

层次化 K-means

受限于时间复杂度，无论应用何种工程优化，标准 K-means 都无法突破线性加速的上限。即使在 GPU 上，这一过程也需要 30 分钟。因此我们必须从算法层面降低时间复杂度。

一个直观的思路是将样本划分为多个互不相交的子集，在每个子集上分别运行 K-means，然后再合并各个子集生成的聚类中心。为了平衡子集的大小与子集的数量，我们选择 \(\sqrt{c}\) 作为子集数量。为了生成这 \(\sqrt{c}\) 个子集，我们先执行一次小规模的 K-means，然后利用得到的 \(\sqrt{c}\) 个质心将 \(n\) 个向量分配到 \(\sqrt{c}\) 个互不相交的子集中。

假设各子集大小均匀，这一步的时间复杂度为 \(O(f\sqrt{c}\sqrt{c}dl) \times \sqrt{c} = O(fc^{1.5}dl)\)。如果 f = 64 且 c = 160,000，该算法的理论速度将提升约 400 倍。

这里还有一个小问题：每个子集应该分配多少个质心？如果忽略质心数量必须为整数的约束，答案是 \(\frac{n}{|s|}c\)。考虑到整数约束后，这个问题就类似于比例代表制中的席位分配问题，其中圣拉古法（Sainte-Laguë method）是一种能够最小化平均席位与选票比例偏差的算法。其工作原理如下：

在统计完所有选票后，依次为每个政党计算商数。商数的计算公式为 \(\frac{V}{s_i+0.5}\)，其中 \(V\) 是该政党获得的总票数，\(s_i\) 是目前为止已分配给该政党的席位数（所有政党初始值均为 \(0\)）。得数最高的政党获得下一个席位，随后重新计算其商数，重复此过程直至所有席位分配完毕。

现在，在 CPU 上进行聚类已经切实可行了。然而，这一算法本身并没有降低内存占用。

降维

现在让我们回过头来看 K-means 样本所占用的 140 GB 内存。在一台 128 GB 内存的机器上，这必然会导致内存溢出（OOM）。考察空间复杂度 \(O(fcd)\)，我们有两种降低内存占用的途径：减小 \(f\)，以及减小 \(d\)。

我们先来减小 \(d\)。虽然听起来有些不可思议，但我们确实可以先对向量进行降维，再执行聚类，而且不会损害最终的精度。Christos 的研究成果表明，在低维投影上运行 K-means 依然能够保持良好的聚类精度。

Johnson–Lindenstrauss 引理指出，高维空间中的一组点可以嵌入到维度低得多的空间中，且点与点之间的距离基本保持不变。在该引理的经典证明中，这种嵌入是通过随机正交投影实现的。

根据该定理，\(n\) 个向量可以降维到 \(O(\lg n)\) 维。具体而言，我们只需要构造一个随机高斯矩阵，通过矩阵乘法将高维向量降维为低维向量，然后在低维空间上执行 K-means。

由于我们的目标是降低内存占用，因此在采样阶段我们就直接应用 Johnson-Lindenstrauss 变换。最终我们会得到低维空间下的质心。我们并不尝试进行逆变换；相反，我们会再次对表进行采样，在经过 Johnson-Lindenstrauss 变换后的低维空间中找到最近的聚类簇，从而恢复出高维空间下的质心。

将维度从 768 降至 100 后，实例的常驻内存集大小（RSS）降至 23 GB，使我们能够在 i4i.xlarge 实例上完成索引构建。此外，理论上这也会让聚类速度提升 7 倍。结合层次化 K-means 与降维技术后，初始化阶段的耗时降至 24 分钟。

减小 \(f\) 则非常简单。它对应配置项 build.internal.sampling_factor，因此我们只需修改配置即可。将 \(f\) 设为 \(64\) 后，实例的常驻内存集大小进一步降至 6 GB，聚类速度也大约提升了 2 倍。

采样

为了执行聚类，我们需要从表中对向量进行采样。我们此前采用的方法是水塘抽样（reservoir sampling），它虽然可靠但速度较慢。之前之所以使用该方法，是因为如果不进行全表扫描，我们无法预知表中的总行数；然而水塘抽样本身仍然需要执行全表扫描。

为了避免全表扫描，我们利用了 PostgreSQL 表访问方法（Table Access Method）的采样接口。该接口接收一个函数，该函数在给定最大块号（block number）时生成一个块号迭代器，随后接口会返回这些数据块中元组（tuple）的迭代器。为了生成这样一个随机块号迭代器，我们可以先生成一个有序序列，再对其执行 Fisher–Yates 洗牌算法，但这会消耗可观的内存。事实上，我们有一种更巧妙的方法：在密码学中，伪随机置换（pseudorandom permutation）是一种在统计上无法与真正随机置换区分开来的函数。

Feistel 网络（Feistel network）可以用作伪随机置换。其定义为 \(L_{i + 1} = R_{i}, R_{i + 1} = L_{i} \oplus F(R_i, K_i)\)，其中 \(F\) 是哈希函数，\(K_i\) 是随机种子。该函数的输入为 \((L_0, R_0)\)，输出为 \((L_n, R_n)\)。因此它是一个从 \([0, 2^n) \times [0, 2^n)\) 到 \([0, 2^n) \times [0, 2^n)\) 的映射。巧妙之处在于，由于 \(R_{i} = L_{i + 1}, L_{i} = R_{i + 1} \oplus F(L_{i + 1}, K_i)\)，该函数是可逆的。可逆函数必然是双射（bijective）的，而 \([0, 2^n) \times [0, 2^n)\) 等价于 \([0, 4^n)\)，因此它构成了 \([0, 4^n)\) 上的一个置换。现在，只需过滤掉该置换中所有大于最大块号的元素，我们就得到了所需的惰性求值随机置换（lazy random permutation）。

基于该接口和这一置换函数，我们实现了块级采样（block sampling），从而只需访问被采样命中的向量数据块。

综合以上所有优化，初始化阶段现在的总耗时仅需 8 分钟。

4. 减少锁竞争

在早期的实验中，如果在 Amazon i7i.16xlarge（64 vCPU）实例上使用 \(n=2\) 为 LAION-100m 数据集构建索引，插入阶段大约需要 420 分钟，且完全受限于计算瓶颈（computation-bound）。

从 0.1 版本开始，VectorChord 允许将 \(n\) 设置为不大于 \(8\) 的正整数。在我们看来，这对于十亿级规模的数据是必不可少的。不过在当时，我们并不清楚它具体能带来多大的加速效果。

在规格更小的 i7i.4xlarge（16 vCPU）实例上尝试 \(n=3\) 后，我们观察到插入阶段仅需 40–60 分钟即可完成。此时 CPU 利用率保持在 40% 左右，IO 吞吐量在 300 MB/s 到 800 MB/s 之间波动，这表明其中存在巨大的优化空间。

减少链表竞争

插入阶段耗时 40–60 分钟。令人惊讶的是，我们的测试显示使用 8 个工作进程（worker）耗时 40 分钟，而使用 16 个工作进程反而耗时 55 分钟。这表明工作进程在插入过程中存在潜在的锁竞争。

在具体实现中，索引除了树结构之外，还维护了一个单链表用于存储全精度向量，而树中仅存储量化后的向量。这使得树节点体积小得多，从而能将整棵树放入内存中。

将 \(n\) 从 \(2\) 改为 \(3\) 后，插入阶段的计算量大幅减少，导致向该链表插入向量的操作变得更加频繁。并行工作进程在向同一个链表插入数据时产生了严重竞争，因此增加工作进程反而拖慢了插入速度，导致性能表现难以预测。

为了解决这个问题，我们将单个链表替换为 \(1+k\) 个链表。第一个链表存储树的前 \(n\) 层所用的全精度向量，其余 \(k\) 个链表存储最底层节点的向量。在构建索引期间，第 \(i\) 个工作进程将向量插入到第 \((i\ \text{mod}\ k)\) 个链表中。我们将默认值设为 \(k=32\)，这足以应对大多数场景。

完成这一改动后，CPU 利用率稳定在 54% 左右，插入阶段耗时缩短至约 30 分钟。

减少页面扩展锁竞争

此时的 CPU 利用率仍然暗示还有进一步优化的潜力。但瓶颈究竟在哪里？我们首先使用 htop 检查了 PostgreSQL 的工作进程状态。

许多进程的标题显示为 waiting，表明 PostgreSQL 内部存在严重的锁竞争。通过在源码中搜索，我们追踪到设置 waiting 状态的代码位于 lock.c。为了测量进程脱离 CPU（off-CPU）的时间，我们使用了 BCC 工具集中的 offcputime。随后，借助 Brendan Gregg 的 FlameGraph 中的 stackcollapse.pl 和 flamegraph.pl，我们生成了进程 off-CPU 时间的火焰图。

结果令人意外：罪魁祸首竟然是 LockRelationForExtension，它在扩展索引文件时负责获取索引的扩展锁。

为什么获取这个锁会成为瓶颈？检索 PostgreSQL 邮件列表后，我们找到了这篇讨论。

简而言之，PostgreSQL 会对每个索引加锁，以防止该索引被并发扩展，但这个锁的粒度过于粗放。感谢 Andres Freund 提交的补丁，它缩小了临界区（critical section）并修复了这一问题，但该优化需要使用 PostgreSQL 16 引入的新 API。

由于 VectorChord 支持 PostgreSQL 13 至 18，我们在早期开发中使用了旧版 API，不幸因此错过了这项优化。

切换到新 API 后，插入阶段的耗时缩短到了 22 分钟。

批量页面扩展

然而，新一轮的性能剖析显示，瓶颈依然停留在同一区域。

既然锁的临界区已经缩小，我们就需要加快页面扩展本身的速度来缓解瓶颈。在文件系统中，使用 fallocate 扩展文件非常快。如果使用 fallocate 来扩展索引，扩展单个页面的平均耗时就会大幅缩短。那么问题来了：我们能否使用 fallocate 来扩展索引？

答案是肯定的。如果单次扩展索引的页面数超过 8 页，PostgreSQL 会自动从 pwrite 切换到 fallocate。通过每次一次性申请 16 个页面，我们显著提升了页面扩展的速度。

完成这一改动后，插入阶段耗时骤降至 9 分钟，CPU 利用率稳定在 90%，写入吞吐量保持在 1.8 GB/s 左右。iostat 报告的 IO 利用率达到 0.75–0.85，表明我们终于充分利用了硬件资源。

这里仍然存在进一步调优的空间，但就目前而言，插入阶段已不再有任何明显的瓶颈。

5. 并行化压缩

在树的最底层，量化向量以两种布局形式存在：

• 非紧凑布局（面向插入）：每个量化向量独立存储为一个元组，因此可以直接追加数据，而无需修改现有元组。

• 紧凑布局（面向检索）：每 32 个量化向量打包存储为一个元组。该布局针对 SIMD 指令集进行了优化，能够大幅提升检索速度。

所有向量在最初插入时都采用非紧凑布局，并在最后一个阶段统一转换为紧凑布局。值得注意的是，此前这一阶段是串行执行的，在索引构建过程中大约耗时 8 分钟。

由于前两个阶段的速度已经大幅提升，优化压缩阶段变得愈发重要。因此我们将这一阶段并行化：假设有 \(k\) 个工作进程，树的第 \(n\) 层有 \(m\) 个节点，那么第 \(i\) 个节点的子节点将由第 \((i\ \text{mod}\ k)\) 个工作进程负责压缩。得益于并行化，压缩阶段现在的耗时不到 1 分钟。

你可能会注意到，为了维持检索性能，高效索引在日常运行中也需要定期执行这种压缩操作。PostgreSQL 提供了 VACUUM 机制来承担此类维护任务，因此该压缩阶段也会在 VACUUM 过程中定期对索引执行。遗憾的是，我们无法在 VACUUM 中将其并行化：PostgreSQL 不允许索引使用嵌套并行（nested parallelism）。如果 VACUUM 本身是并行执行的，索引就无法再次启动并行工作进程。

6. 总结

在此之前，使用 VectorChord 0.5.3 在 Amazon i7i.4xlarge 实例上为 LAION-100M 数据集构建索引是不可行的，因为会发生内存溢出（OOM）错误。将聚类卸载到 GPU 使得索引构建成为可能，在查询 Top 10 结果时，可在 120 QPS 下达到 95.6% 的召回率（recall），但需要在 GPU 上耗时 30 分钟，并在 i7i.4xlarge 上耗时 420 分钟。

凭借 VectorChord 1.0.0 引入的一系列优化，现在完全可以在单台 i7i.4xlarge 实例上用仅仅 18 分钟完成整个索引构建，并在相同 QPS 下达到 94.9% 的召回率。

CREATE INDEX ON laion USING vchordrq (embedding vector_ip_ops) WITH (options = $$
build.pin = 2
[build.internal]
lists = [400, 160000]
build_threads = 16
spherical_centroids = true
kmeans_algorithm.hierarchical = {}
kmeans_dimension = 100
sampling_factor = 64
$$);

我们的目标是让 VectorChord 成为 PostgreSQL 上最优秀的检索方案之一，无论你是在构建第一个原型，还是在应对十亿级规模的数据集。如果你已经在使用 pgvector，我们非常欢迎你在真实工作负载上试用 VectorChord 1.0，并告诉我们它在哪些地方帮到了你，又在哪些地方还可以做得更好。

3 - 借助 VectorChord-BM25 将搜索引擎级排序引入 PostgreSQL

现代应用普遍依赖 PostgreSQL 完全符合 ACID 的事务特性、表达力丰富的 SQL 以及繁荣的扩展生态系统。虽然 PostgreSQL 在处理关系型负载方面表现得无与伦比，但许多项目同样需要在庞大的文本集合（如商品描述、客服工单、技术文档）中进行搜索，并将最相关的行优先呈现给用户。PostgreSQL 的原生工具为此提供了一定基础，但其默认的排序逻辑往往会让最理想的匹配结果被淹没在不太有用的结果之下。VectorChord‑BM25 通过将 BM25 相关性评分算法直接引入 PostgreSQL，彻底改变了这一局面。

什么是 PostgreSQL？

PostgreSQL 是一款开源的企业级关系型数据库管理系统（RDBMS），以高可靠性、数据完整性和标准合规性而闻名。它支持窗口函数、物化视图、JSONB 存储等高级特性，并拥有强大的扩展机制，允许开发者按需扩展新功能。点击此处了解更多关于 PostgreSQL 的信息。

基于 tsvector 的全文搜索

PostgreSQL 内置了名为 tsvector 的基础文本搜索工具。你可以把它想象成一种特殊的列，以数据库能够快速检索的格式存储每篇文档中的重要词汇（词位，lexemes）。当你在该列上添加 GIN 或 GiST 索引后，PostgreSQL 几乎可以瞬间找到匹配某个关键词的行。你可以使用 @@ 操作符编写搜索查询，完整细节可参阅 PostgreSQL 手册的这一章节。

原生排序的不足之处

虽然 ts_rank 函数可以对匹配结果进行排序，但它的评分方法非常基础。仅提及一次某词汇的长篇文档，其排名可能会高于完全围绕该查询主题展开的短篇文档；而且罕见但重要的关键词也几乎没有额外的权重加成。在大规模数据集中，这往往会导致搜索结果的实际感知相关性大打折扣。

全新突破：VectorChord 引入 BM25

VectorChord‑BM25 是一款轻量级的 PostgreSQL 扩展，它使用行业标准的 BM25 排序公式增强了现有的文本搜索技术栈。你无需将数据导出到外部搜索引擎，而是可以把所有数据留在单一数据库内部，同时获得以下优势：

• 奖励高区分度词汇并惩罚冗长无关内容的精准排序

• 索引内评分（In-index scoring），显著降低查询延迟

• 无缝的 SQL 工作流——文档依然是表中的行，搜索依然是标准的 SQL 查询

什么是 BM25？

BM25（Best Matching 25）是一种被搜索引擎和学术界广泛采用的概率检索模型。它综合评估查询词在文档中出现的频率、该词在整个语料库中的罕见程度，以及每篇文档的长度。关于该算法的详细讨论可参见其维基百科页面，但其核心思想非常直观：

• 词频（Term Frequency, TF）——某个词在文档中出现的次数越多，相关性越高，但边际收益递减。

• 逆文档频率（Inverse Document Frequency, IDF）——罕见词比常见词包含更多有效信息。

• 文档长度归一化（Document Length Normalisation）——聚焦于查询主题的短文档不会因为篇幅短而受到不公平的惩罚。

VectorChord 通过全新的索引类型和操作符（<&>）实现了 BM25，使 PostgreSQL 能够在扫描索引的同时直接计算出相关性得分。

两个实用示例

下面通过两个简明的演示，展示如何结合预训练分词器使用 VectorChord‑BM25，以及如何针对特定专业领域使用自定义模型。

示例 1：使用预训练模型快速上手

# Spin up a pre‑configured PostgreSQL instance
docker run --name vchord-suite \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg17-latest

-- Inside psql
CREATE EXTENSION pg_tokenizer CASCADE;
CREATE EXTENSION vchord_bm25  CASCADE;

-- Register the LLMLingua‑2 tokenizer
SELECT create_tokenizer('llm_tok', $$ model = "llmlingua2" $$);

CREATE TABLE articles (
    id   SERIAL PRIMARY KEY,
    body TEXT,
    emb  bm25vector
);

INSERT INTO articles(body) VALUES
('PostgreSQL is a powerful open‑source database system.'),
('BM25 is a ranking function used by search engines.');

-- Tokenise each row
UPDATE articles SET emb = tokenize(body, 'llm_tok');

-- Build the BM25 index
CREATE INDEX articles_emb_bm25 ON articles USING bm25 (emb bm25_ops);

-- Query with relevance ordering
SELECT id,
       body,
       emb <&> to_bm25query('articles_emb_bm25',
                            tokenize('open source database', 'llm_tok')) AS score
FROM   articles
ORDER  BY score         -- lower (more negative) = higher relevance
LIMIT  10;

该查询直接返回按 BM25 排好序的行，呈现出比默认 ts_rank 更符合直觉的结果。

示例 2：面向领域特定词汇表的自定义模型

特定领域的文本——如医疗记录、法律文书、技术日志——通常包含通用模型中缺失的专业术语。VectorChord 允许你直接在 SQL 中训练自定义分词器。

-- 1. Create a text analyzer with Unicode segmentation, lowercasing,
--    stop‑word removal, and stemming.
SELECT create_text_analyzer('tech_analyzer', $$
pre_tokenizer = "unicode_segmentation"
[[character_filters]]
to_lowercase = {}
[[token_filters]]
stopwords = "nltk_english"
[[token_filters]]
stemmer = "english_porter2"
$$);

-- 2. Train a model on your own corpus and set up automatic embedding
SELECT create_custom_model_tokenizer_and_trigger(
    tokenizer_name     => 'tech_tok',
    model_name         => 'tech_model',
    text_analyzer_name => 'tech_analyzer',
    table_name         => 'tickets',
    source_column      => 'issue_text',
    target_column      => 'embedding');

-- 3. Insert support tickets; embeddings are generated via trigger
INSERT INTO tickets(issue_text)
VALUES ('Kubernetes pod fails with ExitCode 137 after OOM kill.'),
       ('Network latency spikes to 250ms during peak hours.');

-- 4. Build an index and query as before
CREATE INDEX tickets_emb_bm25 ON tickets USING bm25 (embedding bm25_ops);

SELECT issue_text,
       embedding <&> to_bm25query('tickets_emb_bm25',
                                  tokenize('OOM kill ExitCode 137', 'tech_tok')) AS score
FROM   tickets
ORDER  BY score
LIMIT  5;

借助量身定制的词汇表，数据库能够准确识别“OOM”和“Kubernetes”等专有缩写与术语，从而为技术支持工单场景提供更加精准的排序结果。

结语

VectorChord‑BM25 在不引入额外服务层的前提下，将搜索引擎级别的相关性排序带入了 PostgreSQL 生态系统。通过将灵活的分词器、高效的 BM25 索引以及熟悉的 SQL 相结合，它让开发者能够在保持单一数据库系统运维简洁性的同时，交付显著更优的搜索体验。如果你的应用基于 PostgreSQL 构建且需要精准的文本排序，VectorChord‑BM25 绝对值得一试。

4 - VectorChord：在 AWS 上高性价比地上传与搜索 4 亿向量

在本文中，我们将介绍一种利用真实世界的 LAION-400M 数据集和 PostgreSQL 中的 VectorChord 扩展，以高性价比方式上传、构建索引并搜索大规模向量数据的方法。

我们将向您展示需要什么样的硬件配置，才能使用 VectorChord 在这一海量数据集上进行搜索，并确保您获得既准确又快速的搜索体验。

VectorChord 是一款 PostgreSQL 扩展，能够将高性能向量数据库能力直接引入您的 PostgreSQL 数据库中，并尽可能高度兼容热门的 pgvector 扩展接口。

本教程所使用的 VectorChord 版本必须为 v0.3.0 或更高版本。虽然 VectorChord 兼容大多数近期版本的 pgvector，但我们在测试中主要针对 pgvector 0.8.0 进行了全面验证。

数据集

本实验使用的数据集是 LAION-400M，这是一个包含约 4 亿条图像衍生向量的数据集。每条向量均为 512 维，由 CLIP 模型生成。

向量数据总量约为 400 GB。这些向量已经过归一化处理，因此可以使用多种距离度量方式（L2、余弦距离、点积）。为了与该数据集上的其他基准测试保持一致，并遵循 CLIP 嵌入本身的特性，我们在本实验中采用了余弦距离（cosine distance）度量。

LAION-400M 被划分为 409 个数据分块（chunks），每个分块包含约 100 万条向量。我们将按顺序处理并上传这些分块。

算法

在 4 亿条向量中进行搜索是一项巨大的挑战，尤其是庞大的数据量意味着绝大部分数据必须存储在磁盘而非内存中。我们需要专为这种规模量身定制的算法！处理大规模磁盘向量数据的一种流行且高效的方法是基于图的 DiskANN，它以低内存和低资源开销而闻名。

然而，由于衍生自 HNSW，DiskANN 也继承了一些固有缺点：

• 索引构建缓慢：对于大规模数据集，众所周知，使用 DiskANN 构建索引往往需要耗费漫长的时间。

• 插入性能不佳：对于流式插入的向量，更新基于图的索引需要遍历局部图结构。由于 DiskANN 的磁盘图必须加载到内存中，这一操作的代价更加高昂。

VectorChord 通过其 VChordRQ 索引解决了这些问题。VChordRQ 将基于聚类的索引（IVF）与巧妙的数据压缩方案 RaBitQ 结合在一起。除了在内存和磁盘场景下均具备更优的精度和更低的延迟外，RaBitQ 的核心优势还在于它拥有严谨的准确度理论下界保证——这与传统的启发式压缩技术截然不同，帮助我们在准确度与效率之间实现了绝佳的平衡！

硬件配置

根据我们的实验，以下云实例规格足以在可接受的延迟下完成该数据集的索引构建与查询：

• 实例类型：AWS EC2 i8g.2xlarge（$501.0720 / 月）

• CPU：8 vCPUs (ARM64)

• 内存：64GB

• 存储：1875 GB NVMe SSD

该配置提供了必要的计算能力以及充裕的高速本地 NVMe 存储。64GB 内存则作为缓存以加速搜索查询。

在该实例的 PostgreSQL 配置中，我们调整了 shared_buffers 参数：

• 在索引构建过程中设置为 48GB。

• 在搜索评估阶段上调至 54GB，以便缓存更多数据，提升搜索性能。

数据上传与索引构建

VectorChord 的 VChordRQ 索引采用倒排文件（IVF）结构。虽然 VChordRQ 可以在索引构建过程中计算所需的聚类质心（centroids），但面对如此庞大的规模（4 亿向量），在系统外部预先计算好质心能够大幅加快索引构建速度。

针对 LAION-400M，我们在配备 A10 GPU 的实例上执行了外部 k-means 聚类步骤来确定这些质心，以加快计算速度：

• 聚类配置为 nlist = 160000 个聚类簇。

• 聚类共执行 25 次迭代，每次迭代耗时约 220 秒，总计约 1.5 小时。

计算出质心后，我们开始部署启用了 VectorChord 的 PostgreSQL 数据库。为了方便起见，我们使用了预构建的 Docker 镜像：

-- Mount PGDATA path to the NVMe SSD
-- sudo mount /dev/nvme1n1 /data
docker run --name vchord-pg17 \
-e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -v /data/pg:/var/lib/postgresql/data \
-d tensorchord/vchord-postgres:pg17-v0.3.0

该 Docker 镜像包含 PostgreSQL 17，并预装了 pgvector 0.8.0 和 VectorChord 0.3.0。

上传流程的核心在于：先将预计算的质心插入到一张专用表中，随后将 LAION 数据集分块中的向量插入主数据表。可以使用 Python 中的 psycopg 等客户端库，通过批量插入（batched inserts）高效完成这一操作。

首先，将质心插入质心表（例如 laion_centroids）：

-- The centroids table we created is:
-- CREATE TABLE laion_centroids (id SERIAL PRIMARY KEY, vector vector(512));
INSERT INTO laion_centroids (vector) VALUES ('[...centroid vector...]'); -- Insert all 160000 centroids

接着，将数据集中的向量插入主数据表（例如 laion）：

-- The data table we created is:
-- CREATE TABLE laion (id BIGINT PRIMARY KEY, embedding vector(512));
-- Note: VectorChord is compatible with pgvector's vector insert syntax.
INSERT INTO laion (id, embedding) VALUES (0, '[...vector data...]'); -- Batch inserts for chunks

插入所有数据后，我们构建 VectorChord 索引（vchordrq）。vchordrq 代表 RaBitQ，这是 VectorChord 基于 IVF 结构并结合量化与高效重排序打造的高度优化索引类型。

-- Note: The metric operator vector_cosine_ops is specified here, similar to pgvector. 
-- The $$ syntax is used to pass build options as a text block.
CREATE INDEX laion_embedding_idx ON laion USING vchordrq (embedding vector_cosine_ops) WITH (options = $$
[build.external]
table = 'public.laion_centroids' -- Link to the pre-computed centroids
$$);

下图展示了在数据上传和索引构建过程中，实例上的系统资源利用率（CPU、内存和磁盘占用）。磁盘占用曲线展示了数据写入阶段（初期陡增）以及随后的索引构建阶段（平稳增长），最终总占用略超 1TB。CPU 和内存曲线则反映了整个过程中消耗的计算与内存资源。

基准真值数据（Ground Truth）

为了准确衡量搜索性能和精度，与真值数据（ground truth）进行比对至关重要。LAION 数据集本身并未附带现成的真值数据。我们非常感谢 Qdrant 团队公开了他们为该数据集教程所准备的真值数据。

他们的方法是对数据集中的前 100 条向量执行全表扫描最近邻搜索，找出每条查询向量的前 50 个真实最近邻。我们使用了完全相同的真值文件来评估 VectorChord 的搜索精度。

搜索查询

VectorChord 搜索采用两个主要参数来控制性能与精度之间的权衡：nprobe 和 epsilon。

• nprobe：通过 vchord.probes 参数进行配置。该参数决定了在初始阶段搜索 IVF 索引中的多少个聚类簇（分区）。较高的 nprobe 会扩大搜索范围，有助于找到更优的结果，但也会增加延迟。

• epsilon：通过 vchord.epsilon 参数进行配置。该参数控制重排序的精度。从探测的 nprobe 个聚类簇中获取初始候选集后，VectorChord 会使用更精确的向量数据执行重排序。较大的 epsilon 意味着会考虑更多候选向量并进行重排序以获得更高的召回率，但同样会增加延迟。

在执行搜索查询之前，将这些参数设置为 PostgreSQL 会话变量：

-- Example settings
SET vchord.probes = 100; -- Configure nprobe
SET vchord.epsilon = 0.8; -- Configure epsilon

-- The search query itself uses the standard pgvector distance operator
SELECT id FROM laion ORDER BY embedding <=> '[...query_vector...]' LIMIT 50;

ORDER BY embedding <=> '[...]' 子句利用索引，根据指定的距离度量（与 CLIP 一致的余弦距离）查找近似最近邻。LIMIT 50 则返回前 50 条结果。

执行搜索请求

索引构建完成后，我们使用不同的 nprobe 和 epsilon 设置，在 100 条真值查询向量上运行了查询，以测试性能与精度之间的权衡关系。

我们以毫秒（ms）为单位表示搜索延迟。“冷缓存（Cold）”延迟是指目标向量数据需要从磁盘读取的情况，而“热缓存（Warm）”延迟则代表数据已经缓存在内存中。

以下是跨 100 条查询的平均延迟以及对应的 Precision@50 得分：

上表清晰地展示了这种权衡关系：

• 增大 nprobe 和 epsilon 通常会带来更高的 Precision@50。

• 然而，这是以增加搜索延迟为代价的，在冷缓存场景下尤为明显——因为需要更多的磁盘 I/O 来从更多聚类簇中读取数据，并执行更广泛的重排序。

• 热缓存性能明显快得多，凸显了配备足够内存以缓存热点数据的重要性。

• 在热缓存下，可以在 50ms 以内的延迟下实现超过 90% 的精度；而若要在此基础上进一步追求极致召回率，则会根据所选参数带来数百毫秒甚至超过一秒的延迟。

下图展示了 VectorChord（冷缓存与热缓存）与 Qdrant 在每秒查询数（QPS）和 Precision@50 之间的权衡对比，其中 Qdrant 的数据引自其在同级别 8 vCPU、64 GB 机器上公开发布的基准测试结果，而非在同一台物理机器上重跑。

结论

在本教程中，我们展示了如何将 VectorChord 作为 PostgreSQL 扩展，在配备高速 NVMe SSD 的中小型硬件上，高性价比地上传、构建索引并搜索多达 4 亿条向量的庞大数据集。

通过结合使用 VectorChord 的 VChordRQ 索引与外部质心构建，我们成功从容应对了这一海量数据规模。在查询时合理设置 nprobe 和 epsilon，可以精确控制搜索速度与准确度之间的关键权衡，让用户能够根据自身业务需求灵活调优系统。

VectorChord 对 pgvector 接口的良好兼容性降低了现有 pgvector 用户的迁移门槛，而其 vchordrq 索引则在稳健、熟悉的 PostgreSQL 环境中直接提供了强大的大规模向量搜索能力。

5 - 在 PostgreSQL 中利用上下文检索优化 RAG

在标准的检索增强生成（RAG）方案中，一种常见做法是将长篇文档切分为更小、更易于管理的文本块（chunk）。这样做主要是为了结合句子嵌入（sentence embedding）与关键词 BM25 评分来提升检索效率，使系统能够快速定位并提取出相关的信息片段。虽然这种方法在许多场景下行之有效，但它也带来了一个显著的挑战：单个文本块很可能会丢失其原本所处的上下文语境。

不妨以历史文献集合为例。如果用户询问某个特定历史事件，而检索出的文本块写着：“条约正式签署，敌对状态宣告结束。”

脱离了前后的文本，这段分块就缺失了至关重要的背景信息：签署的是哪一份条约、缔约双方是谁，以及这一重大事件发生在何时何地。如果仅依赖这样一个脱离上下文的片段，提供给大语言模型（LLM）的信息将是残缺甚至可能产生误导的，从而妨碍其针对该历史事件生成全面、准确的回答。

这个例子清楚地说明：虽然分块（chunking）有助于提升检索效率，但它可能会无意间剥离赋予信息片段具体含义和相关性的必要上下文。这种上下文缺失会严重影响 RAG 系统中 LLM 生成回答的质量与准确性。

为了解决这一问题，Anthropic 探索并提出了一种名为上下文检索（Contextual Retrieval）的方法。

简而言之，可以将它视为利用整篇文档的上下文对分块进行增强（chunk augmentation）。

本文将带你一步步借助上下文信息来提升检索准确率。我们使用了与 Anthropic 教程中相同的提示词（prompt）、数据集和评估指标。需要注意的是，我们在本次实验中使用了不同的嵌入模型和 LLM，因此具体数值会有所不同；但这并不反映模型本身的优劣，因为该数据集主要由代码而非自然语言构成。

我们主要使用 Gemini 模型来生成分块上下文和文本嵌入，其他模型也同样适用。嵌入质量对向量检索指标影响很大，建议参考 MTEB 排行榜挑选最契合你业务场景的模型。在关键词分词方面，我们使用默认的 BERT 分词器，你也可以尝试其他分词方案。

重排序（rerank）并非本文的重点；如果你想深入了解重排序方法，欢迎阅读我们关于 Cross-Encoder 重排序以及词元级延迟交互重排序的专题文章。顺便提一句，由于我们已经支持多向量 MaxSim 索引，词元级延迟交互重排序现在可以更加高效地执行。

准备环境

我们在 VectorChord-suite Docker 镜像中同时提供了向量搜索和关键词搜索功能。

docker run --rm -d --name vdb -e POSTGRES_PASSWORD=postgres -p 5432:5432 ghcr.io/tensorchord/vchord-suite:pg17-20250414

我们将使用 vechord Python 库来减少样板代码并简化开发流程。

pip install 'vechord[gemini]'

定义 RAG 相关表结构

让我们先从基础的 RAG 流程开始。

from vechord.spec import (
    ForeignKey,
    Keyword,
    PrimaryKeyAutoIncrease,
    Table,
    UniqueIndex,
    Vector,
)

DenseVector = Vector[768]

class Document(Table, kw_only=True):
    uid: Optional[PrimaryKeyAutoIncrease] = None
    uuid: Annotated[str, UniqueIndex()]
    content: str

class Chunk(Table, kw_only=True):
    uid: Optional[PrimaryKeyAutoIncrease] = None
    doc_uuid: Annotated[str, ForeignKey[Document.uuid]]
    index: int
    content: str
    vector: DenseVector
    keyword: Keyword

class Query(Table, kw_only=True):
    uid: Optional[PrimaryKeyAutoIncrease] = None
    content: str
    answer: str
    doc_uuids: list[str]
    chunk_index: list[int]
    vector: DenseVector

上述定义已经自动包含了向量嵌入索引和关键词索引。

加载数据集的代码如下：

from vechord.embedding import GeminiDenseEmbedding
from vechord.registry import VechordRegistry

emb = GeminiDenseEmbedding()
vr = VechordRegistry("anthropic", "postgresql://postgres:[email protected]:5432/")

vr.register([Document, Chunk, Query])

def load_data(filepath: str):
    with open(filepath, "r", encoding="utf-8") as f:
        docs = json.load(f)
        for doc in docs:
            vr.insert(
                Document(
                    uuid=doc["original_uuid"],
                    content=doc["content"],
                )
            )
            for chunk in doc["chunks"]:
                vr.insert(
                    Chunk(
                        doc_uuid=doc["original_uuid"],
                        index=chunk["original_index"],
                        content=chunk["content"],
                        vector=emb.vectorize_chunk(chunk["content"]),
                        keyword=Keyword(chunk["content"]),
                    )
                )

def load_query(filepath: str):
    queries = []
    with open(filepath, "r", encoding="utf-8") as f:
        for line in f:
            query = json.loads(line)
            queries.append(
                Query(
                    content=query["query"],
                    answer=query["answer"],
                    doc_uuids=[x[0] for x in query["golden_chunk_uuids"]],
                    chunk_index=[x[1] for x in query["golden_chunk_uuids"]],
                    vector=emb.vectorize_query(query["query"]),
                )
            )
    vr.copy_bulk(queries)

评估

现在我们已经具备了基础 RAG 流程所需的全部组件。接下来定义评估指标 Pass@k，它表示检索出的 Top-K 文本块中包含了多少比例的标准答案（ground truth）文本块。

def evaluate(topk=5, search_func=vector_search):
    print(f"TopK={topk}, search by: {search_func.__name__}")
    queries: list[Query] = vr.select_by(Query.partial_init())
    total_score = 0
    start = perf_counter()
    for query in queries:
        chunks: list[Chunk] = search_func(query, topk)
        count = 0
        for doc_uuid, chunk_index in zip(
            query.doc_uuids, query.chunk_index, strict=True
        ):
            for chunk in chunks:
                if chunk.doc_uuid == doc_uuid and chunk.index == chunk_index:
                    count += 1
                    break
        score = count / len(query.doc_uuids)
        total_score += score

    print(
        f"Pass@{topk}: {total_score / len(queries):.4f}, total queries: {len(queries)}, QPS: {len(queries) / (perf_counter() - start):.3f}"
    )

我们可以尝试不同的检索策略，例如向量搜索、关键词搜索、结合融合（fusion）或重排序（rerank）的混合搜索。

这些检索策略可定义如下：

from vechord.rerank import CohereReranker, ReciprocalRankFusion

def vector_search(query: Query, topk: int) -> list[Chunk]:
    return vr.search_by_vector(Chunk, query.vector, topk=topk)

def keyword_search(query: Query, topk: int) -> list[Chunk]:
    return vr.search_by_keyword(Chunk, query.content, topk=topk)

def hybrid_search_fuse(query: Query, topk: int) -> list[Chunk]:
    rrf = ReciprocalRankFusion()
    return rrf.fuse([vector_search(query, topk), keyword_search(query, topk)])[:topk]

def hybrid_search_rerank(query: Query, topk: int, boost=3) -> list[Chunk]:
    ranker = CohereReranker()
    vecs = vector_search(query, topk * boost)
    keys = keyword_search(query, topk * boost)
    chunks = list({chunk.uid: chunk for chunk in vecs + keys}.values())
    indices = ranker.rerank(query.content, [chunk.content for chunk in chunks])
    return [chunks[i] for i in indices[:topk]]

上下文检索（Contextual Retrieval）

LLM 使用如下提示词生成上下文信息：

prompt = (
    "<document>\n{whole_document}\n</document>"
    "Here is the chunk we want to situate within the whole document \n"
    "<chunk>\n{chunk}\n</chunk>\n"
    "Please give a short succinct context to situate this chunk within "
    "the overall document for the purposes of improving search retrieval "
    "of the chunk. Answer only with the succinct context and nothing else."
)

上面的提示词是专为通用检索任务设计的。针对你的具体业务场景，定制更专门的提示词往往能取得更好的效果。

这一功能已经内置在 vechord 库中。

GeminiAugmenter 同样支持类似 Claude 的提示词缓存（prompt caching）功能，但它要求缓存内容至少达到 32768 个 token，而本实验所用的数据集未达到该长度阈值。

from vechord.augment import GeminiAugmenter

class ContextualChunk(Table, kw_only=True):
    uid: Optional[PrimaryKeyAutoIncrease] = None
    doc_uuid: Annotated[str, ForeignKey[Document.uuid]]
    index: int
    content: str
    context: str
    vector: DenseVector
    keyword: Keyword

def load_contextual_chunks(filepath: str):
    augmenter = GeminiAugmenter()

    with open(filepath, "r", encoding="utf-8") as f:
        docs = json.load(f)
        for doc in docs:
            augmenter.reset(doc["content"])
            chunks = doc["chunks"]
            augments = augmenter.augment_context([chunk["content"] for chunk in chunks])
            if len(augments) != len(chunks):
                print(f"augments length not match for uuid: {doc['original_uuid']}, {len(augments)} != {len(chunks)}")
            for chunk, context in zip(chunks, augments, strict=False):
                contextual_content = f"{chunk['content']}\n\n{context}"
                vr.insert(
                    ContextualChunk(
                        doc_uuid=doc["original_uuid"],
                        index=chunk["original_index"],
                        content=chunk["content"],
                        context=context,
                        vector=emb.vectorize_chunk(contextual_content),
                        keyword=Keyword(contextual_content),
                    )
                )

随后，我们可以将检索策略扩展为如下形式：

def vector_contextual_search(query: Query, topk: int) -> list[ContextualChunk]:
    return vr.search_by_vector(ContextualChunk, query.vector, topk=topk)

def keyword_contextual_search(query: Query, topk: int) -> list[ContextualChunk]:
    return vr.search_by_keyword(ContextualChunk, query.content, topk=topk)

def hybrid_contextual_search_fuse(query: Query, topk: int) -> list[ContextualChunk]:
    rrf = ReciprocalRankFusion()
    return rrf.fuse(
        [vector_contextual_search(query, topk), keyword_contextual_search(query, topk)]
    )[:topk]

def hybrid_contextual_search_rerank(
    query: Query, topk: int, boost=3
) -> list[ContextualChunk]:
    ranker = CohereReranker()
    vecs = vector_contextual_search(query, topk * boost)
    keys = keyword_contextual_search(query, topk * boost)
    chunks = list({chunk.uid: chunk for chunk in vecs + keys}.values())
    indices = ranker.rerank(
        query.content, [f"{chunk.content}\n{chunk.context}" for chunk in chunks]
    )
    return [chunks[i] for i in indices[:topk]]

基准测试结果

• topk=5

• topk=10

所有代码均可在我们的 vechord 仓库中找到。

6 - 一站式 VectorChord 套件：直接在 PostgreSQL 中构建生产就绪的 RAG 解决方案

检索增强生成（Retrieval-Augmented Generation, RAG）正在彻底改变我们与海量数据集及语言模型的交互方式。通过在生成回答之前先检索相关信息，RAG 系统能够提供更准确、更具上下文感知能力且实时更新的答案。然而，构建稳健、可扩展且高效的 RAG 流水线依然面临诸多挑战，在生产环境中更是如此。

许多解决方案采用了复杂的架构，分别为向量搜索、关键词搜索和主数据存储使用不同的数据库。这通常会导致数据同步难题、更高的基础设施复杂度以及高昂的运维成本。

如果可以直接在你信赖的 PostgreSQL 数据库内部构建一套强大且生产就绪的 RAG 系统，会怎样呢？

为此，我们推出了 VectorChord 套件（VectorChord Suite）——这是一组旨在将高性能向量搜索、原生 BM25 排序以及灵活的分词能力直接引入 Postgres 的 PostgreSQL 扩展集合。下面让我们一起探索它的各个组件，看看它们如何赋能下一代 RAG 解决方案。

什么是 VectorChord 套件？

该套件由三个协同工作的核心 PostgreSQL 扩展组成：

1. VectorChord：核心向量搜索引擎。专为在 PostgreSQL 内部实现可扩展、高性能且磁盘高效的向量相似度搜索而设计。

2. VectorChord-bm25：该扩展利用高效的 Block-WeakAnd 算法，直接在 PostgreSQL 内部实现了成熟的 BM25 排序算法。BM25 是基于关键词频率和文档特征进行相关性排序的行业标准。

3. pg_tokenizer.rs：提供高效全文搜索所必需的文本分词（Tokenization）能力，支持对全文搜索的文本处理方式进行细粒度控制。

通过组合这些扩展，你可以完全在 PostgreSQL 内部解锁构建高级 RAG 系统的强大能力。

如何使用 VectorChord 套件

你可以使用 tensorchord/vchord-suite 镜像来运行 TensorChord 提供的多个扩展。该镜像基于官方 Postgres 镜像构建，包含以下扩展：

docker run   \           
  --name vchord-suite  \
  -e POSTGRES_PASSWORD=postgres  \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg17-latest
  # If you want to use ghcr image, you can change the image to `ghcr.io/tensorchord/vchord-suite:pg17-latest`.
  # if you want to use the specific version, you can use the tag `pg17-20250414`, supported version can be found in the support matrix.

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;
CREATE EXTENSION IF NOT EXISTS pg_tokenizer CASCADE;
CREATE EXTENSION IF NOT EXISTS vchord_bm25 CASCADE;
\dx
pg_tokenizer | 0.1.0   | tokenizer_catalog | pg_tokenizer
vchord       | 0.3.0   | public            | vchord: Vector database plugin for Postgres, written in Rust, specifically designed for LLM
vchord_bm25  | 0.2.0   | bm25_catalog      | vchord_bm25: A postgresql extension for bm25 ranking algorithm
vector       | 0.8.0   | public            | vector data type and ivfflat and hnsw access methods

VectorChord 套件的应用场景

场景 1：结合原生 BM25 与 VectorChord 的强大混合搜索

在 RAG 时代，高效的检索至关重要。无论是单纯的关键词搜索还是单纯的向量搜索，都并非十全十美：

• 关键词搜索（如 BM25）：擅长精准匹配，能够找出包含精确关键词的文档，非常适合结构化查询和特定术语搜索。但它在处理同义词、改写表达以及理解深层含义或语义意图方面表现欠佳。（利用 VectorChord-bm25 和 pg_tokenizer）。

• 向量搜索：擅长捕捉深层语义和概念之间的关联，即使文档中没有出现完全一致的关键词，也能找到相关信息。但在面对要求精确匹配特定术语的查询时，有时会缺乏精准度。（利用 VectorChord）。

解决方案：混合搜索（Hybrid Search）。通过在 Postgres 内部结合这两种方法的优势，VectorChord 套件弥合了这一差距。你可以运行一条同时利用以下两者的查询：

• 使用 VectorChord-bm25（由 pg_tokenizer 驱动）保证关键词精准匹配。

• 使用 VectorChord 实现深层语义理解。

两者的检索结果可以进行智能融合（例如使用倒数排序融合 RRF 或基于模型的重排序 Rerank），从而生成比任何单一方法都更准确、上下文更相关且更具语义感知能力的最终排序。这将为你的 RAG 应用带来显著更优的检索表现。

场景 2：超越纯文本——基于 ColQwen2 与 VectorChord 的免 OCR RAG

为 PDF 或扫描图像等文档构建 RAG 系统，通常涉及繁琐的预处理流水线。传统方法高度依赖光学字符识别（OCR）和版面分析来提取文本。这一过程往往存在以下问题：

• 速度慢：OCR 的计算开销可能非常高昂。

• 容易出错：OCR 的准确率受文档质量影响很大。

• 信息有损：在提取纯文本的过程中，表格、图表、格式以及相对位置等关键视觉上下文信息往往会丢失。

解决方案：免 OCR、具备视觉感知能力的 RAG。如果可以直接根据文档的外观版式及其内容进行查询，而无需显式执行 OCR，会怎样呢？

现在，通过结合以下两项技术即可实现这一目标：

1. 多模态视觉语言模型（VLM）：像 ColQwen2 这样的模型可以直接处理图像（文档页面），并生成同时捕捉文本内容和视觉版面信息的向量嵌入。

2. VectorChord 的多向量能力：VectorChord 可以在 Postgres 内部高效地为每篇文档存储和搜索多个向量——允许你存储代表不同维度特征（如文本内容、视觉布局）的嵌入向量。

借助这套方案，你可以直接在 PostgreSQL 中使用引用视觉元素的提示词（例如“查找包含对比销售数据的柱状图的文档”）或结合文本与视觉线索的查询来检索文档数据库。这不仅简化了你的 RAG 技术栈，通过保留视觉上下文提升了检索准确率，还彻底消除了传统 OCR 流水线带来的性能瓶颈。

为什么要在 PostgreSQL 中构建 RAG？

在 Postgres 内部使用 VectorChord 套件具有诸多显著优势：

• 数据统一：将源数据、文本、元数据和向量嵌入全部保存在同一个地方。

• 降低复杂度：无需再维护独立的向量数据库和数据同步流水线。

• 复用现有基础设施：充分利用你现有的 Postgres 专业知识、工具链和运维实践。

• 事务完整性：受益于 PostgreSQL 强大的 ACID 事务保障。

• 丰富的生态系统：无缝使用 Postgres 生态系统中极其丰富的工具与功能特性。

总结

VectorChord 套件将 PostgreSQL 打造成了一个强大且生产就绪的高级 RAG 解决方案构建平台。通过集成高性能向量搜索（VectorChord）、成熟的关键词排序（VectorChord-bm25）以及灵活的文本处理（pg_tokenizer），你可以直接在数据库内部实现混合搜索和免 OCR 多模态检索等前沿技术。立即在 PostgreSQL 中使用 VectorChord，简化系统架构、提升检索精度，充分释放 RAG 的全部潜力。

往期博客文章

在此前的博客中，我们分享过一些实际应用案例，其中的所有镜像现在都可以直接替换为 VectorChord Suite 镜像：

• 在 PostgreSQL 中利用 ColBERT Rerank 为向量搜索加速

• 使用 Postgres 原生 BM25 与 VectorChord 实现混合搜索

• 超越文本：使用 Modal 与 VectorChord 在 PostgreSQL 中解锁免 OCR 的 RAG

参考资料

• https://vchord.pgsty.com/zh/blog/post/vectorchord-store-400k-vectors-for-1-in-postgresql/

• https://vchord.pgsty.com/zh/blog/post/vectorchord-bm25-revolutionize-postgresql-search-with-bm25-ranking-3x-faster-than-elasticsearch/

• https://vchord.pgsty.com/zh/blog/post/vectorchord-bm25-introducing-pgtokenizera-standalone-multilingual-tokenizer-for-advanced-search/

7 - 推出 Vechord：以 Pythonic 的方式将 PostgreSQL 打造成你的搜索引擎

今天，我们非常激动地宣布发布 Vechord——一个全新的 Python 库，旨在大幅简化直接在 PostgreSQL 数据库之上构建稳健搜索基础设施的流程。

在人工智能与大语言模型（LLM）飞速发展的今天，检索增强生成（RAG）和语义搜索已成为不可或缺的核心组件。然而，搭建所需的向量搜索基础设施往往意味着学习全新的数据库技术、管理复杂的系统集成，或是与繁琐的框架搏斗。这不仅增加了研发摩擦，还会拖慢开发进度，对于已经熟悉 PostgreSQL 的团队而言尤为如此。

挑战：混合搜索的复杂性

构建搜索能力通常意味着：

1. 选型与运维专用数据库：评估、部署和维护专用的向量数据库（如 Pinecone、Weaviate、Milvus 等）以及全文检索框架（如 ElasticSearch、Solr 等）会带来额外的运维开销。

2. 复杂的数据处理：需要管理源数据与向量表征之间的同步。

3. 陡峭的学习曲线：需要理解那些面向广泛 LLM 任务的庞大框架中的各种 API 与抽象概念。

Vechord：构建于 PostgreSQL 之上的简洁、Pythonic 解决方案

Vechord 通过充分发挥 PostgreSQL 的强大能力与可扩展性，并结合强大的 VectorChord 和 VectorChord-bm25 扩展，正面解决了这些挑战。我们的核心设计理念是简洁与专注。

Vechord 提供了一套干净、Pythonic 的接口，助你轻松完成：

• 初始化（Initialize）：使用 Python 结构体和类型注解轻松配置表结构（Schema）。

• 数据写入（Ingest Data）：配合转换工具，轻松导入文档、PDF 或任何其他类型的数据。

• 执行混合搜索（Perform Hybrid Search）：通过友好的 API 高效执行向量相似度搜索与关键词搜索，并对检索结果进行重排序（rerank）。

• 指标评估（Evaluate Metrics）：无论是对比标准答案（ground truth）还是使用基于 LLM 的评分，都能无缝评估检索指标。

• 化繁为简（Makes Simple Tasks Simple）：提供类 ORM 的接口，方便地对 PostgreSQL 数据库执行查询、插入和删除操作。

Vechord 有何不同？

1. 高度专注于 PostgreSQL 向量 + 关键词搜索：Vechord 专门致力于让 PostgreSQL + VectorChord 套件的组合在搜索场景下简单易用。如果你的首要目标是在现有的 PostgreSQL 生态中实现高效的向量搜索与关键词搜索，Vechord 提供了一条更精简、更直接的路径。

2. 定位为库，而非庞大平台：Vechord 被设计为一个库（Library）——一个可以集成到你应用代码中的专注构建块。它为你提供基于 PostgreSQL 的核心存储与混合搜索能力，而将更宏观的应用架构与工作流设计完全交还给你。

3. 复用现有基础设施：Vechord 的核心前提是赋能已经在使用 PostgreSQL 的团队。如果你的数据规模和业务需求能够通过 VectorChord 套件得到良好满足，就无需再引入和维护一套独立的专用向量数据库或文档数据库，从而大幅降低运维复杂度和成本。

4. 把简洁当作核心特性：Vechord 优先追求极简的 API 表面积以及特定任务下的易用性，旨在让你以最少的样板代码和心智负担在 Postgres 上实现混合搜索。

快速上手 Vechord

• 定义表结构（Schema）

from typing import Annotated, Optional
from vechord.spec import Table, Vector, PrimaryKeyAutoIncrease, ForeignKey, Keyword

# use 768 dimension vector
DenseVector = Vector[768]

class Document(Table, kw_only=True):
    uid: Optional[PrimaryKeyAutoIncrease] = None  # auto-increase id, no need to set
    link: str = ""
    text: str

class Chunk(Table, kw_only=True)
    uid: Optional[PrimaryKeyAutoIncrease] = None
    doc_id: Annotated[int, ForeignKey[Document.uid]]  # reference to `Document.uid` on DELETE CASCADE
    vec: DenseVector  # this comes with a default vector index
    keyword: Keyword  # this comes with a default tokenizer and text index
    text: str

• 使用 Python 装饰器注入数据

import httpx
from vechord.registry import VechordRegistry
from vechord.extract import SimpleExtractor
from vechord.embedding import GeminiDenseEmbedding

vr = VechordRegistry(namespace="test", url="postgresql://postgres:[email protected]:5432/")
# ensure the table and index are created if not exists
vr.register([Document, Chunk])
extractor = SimpleExtractor()
emb = GeminiDenseEmbedding()

@vr.inject(output=Document)  # dump to the `Document` table
# function parameters are free to define since `inject(input=...)` is not set
def add_document(url: str) -> Document:  # the return type is `Document`
    with httpx.Client() as client:
        resp = client.get(url)
        text = extractor.extract_html(resp.text)
        return Document(link=url, text=text)

@vr.inject(input=Document, output=Chunk)  # load from the `Document` table and dump to the `Chunk` table
# function parameters are the attributes of the `Document` table, only defined attributes
# will be loaded from the `Document` table
def add_chunk(uid: int, text: str) -> list[Chunk]:  # the return type is `list[Chunk]`
    chunks = text.split("\n")
    return [Chunk(doc_id=uid, vec=emb.vectorize_chunk(t), keyword=Keyword(t), text=t) for t in chunks]

if __name__ == "__main__":
    add_document("https://paulgraham.com/best.html")  # add arguments as usual
    add_chunk()  # omit the arguments since the `input` is will be loaded from the `Document` table
    vr.insert(Document(text="hello world"))  # insert manually
    print(vr.select_by(Document.partial_init()))  # select all the columns from table `Document`

• 在单个事务中运行多个步骤以保证数据一致性

pipeline = vr.create_pipeline([add_document, add_chunk])
pipeline.run("https://paulgraham.com/best.html")  # only accept the arguments for the first function

• 按向量和关键词进行检索，并使用交叉编码器（Cross-Encoder）模型重排序

from vechord.rerank import CohereReranker

reranker = CohereReranker()
text = vr.search_by_vector(Chunk, emb.vectorize_query("startup"))
vec = vr.search_by_keyword(Chunk, "startup")
chunks = list({chunk.uid: chunk for chunk in text_retrieves + vec_retrievse}.values())
indices = reranker.rerank(query, [chunk.text for chunk in chunks])
print([chunks[i] for i in indices[:topk]])

加入社区！

Vechord 是开源且由社区驱动的项目。我们相信它为那些希望获得强大搜索能力、却不想引入不必要复杂度的开发者填补了一个关键空白。

• 在 GitHub 上查看源码：https://github.com/tensorchord/vechord

• 阅读文档：https://tensorchord.github.io/vechord/

• 在 Discord 上与我们交流：https://discord.gg/KqswhpVgdU

%[https://github.com/tensorchord/vechord]

8 - 超越文本：使用 Modal 与 VectorChord 在 PostgreSQL 中解锁免 OCR 的 RAG

为文档构建高效的检索增强生成（RAG）系统，往往让人感觉像是在与杂乱复杂的流水线搏斗。尤其是在处理 PDF 或扫描图像时，传统方法高度依赖光学字符识别（OCR）和版面分析。这些步骤不仅耗时、容易出错，而且经常会丢失表格、图表和排版格式等至关重要的视觉上下文信息。但如果可以直接根据文档的“视觉外观”进行查询，而不仅仅依赖提取出来的纯文本呢？

本文将手把手带你构建这样一个系统：直接在你熟悉的 PostgreSQL 数据库中构建一套免 OCR 的 RAG 系统。我们将结合 ColQwen2 视觉语言模型（VLM）的强大理解力、VectorChord 在 Postgres 中进行多向量搜索的高效性，以及 Modal 用于 GPU 加速向量生成的弹性扩展能力。准备好简化你的 RAG 技术栈并大幅提升检索精度吧——这一切都无需复杂的预处理流水线。

本文将涵盖以下内容：

• 什么是 ColQwen2，以及为什么它是改变游戏规则的利器。

• VectorChord 如何让高级向量搜索在 Postgres 中成为可能。

• 从零构建并评估该系统的分步实战教程。

什么是 ColQwen2？视觉理解的力量

要理解 ColQwen2，我们先来看看它的基础：ColPali。正如论文《ColPali: Efficient Document Retrieval with Vision Language Models》中所介绍的，ColPali 代表了一种利用视觉语言模型（VLM）的全新范式。它不再依赖不完美的 OCR，而是直接利用文档丰富的视觉特征——文本、图像、表格、版面布局，乃至肉眼可见的一切元素——来建立索引。

回想一下传统 OCR 的局限性：复杂的版面被拆得七零八落，表格变成一堆乱码，而图像则往往被完全忽略。这就像试图仅通过阅读一份错漏百出的速记稿来理解整本书。ColPali 则避开了这一陷阱，它使用强大的 VLM（最初为 PaliGemma）生成能够捕捉文档整体视觉特征的嵌入向量。有两大核心理念使其脱颖而出：

1. 融合上下文的视觉嵌入（Contextualized Vision Embeddings）：使用 VLM 直接从文档图像生成信息丰富的嵌入向量。

2. 晚期交互（Late Interaction）：这一巧妙的技术允许查询的文本语义在搜索时直接与文档的精细视觉特征进行交互。它不仅仅是匹配文本摘要，而是将查询概念与文档页面内的视觉证据逐一比对。

ColPali 架构示意图（图片源自 ColPali 论文）

ColQwen2 建立在强大的 ColPali 架构之上，但将底层 VLM 替换为了更新的 Qwen2-VL-2B。它生成 ColBERT 风格的多向量表示，能够同时从文本和图像中捕捉细粒度细节。正如在 vidore-leaderboard 榜单上所看到的那样，ColQwen2 以非常实用的模型体积实现了令人惊艳的检索性能。

VectorChord 如何在 Postgres 中赋能 ColQwen2？

这正是 VectorChord 成为关键拼图的地方——它将这一前沿的 VLM 能力直接引入了你的 PostgreSQL 数据库。ColQwen2（以及 ColPali）高度依赖多向量表示和晚期交互机制，特别是需要高效的 **MaxSim（最大相似度）**运算支持。

计算 MaxSim——即找出查询向量集合中的任意向量与文档向量集合中的任意向量之间的最高相似度得分——在计算上极其繁重，当面对数百万个文档向量时更是如此。VectorChord 正面攻克了这一难题：

• 原生多向量支持：从底层设计之初就支持在 Postgres 内部高效处理多向量数据。

• 深度优化的 MaxSim：受 WARP 论文启发，VectorChord 采用动态相似度插补（dynamic similarity imputation）等技术大幅加速 MaxSim 计算，使大规模视觉文档检索真正切实可行。

• 支持混合搜索：除了多向量检索，它还支持稠密向量、稀疏向量和混合搜索（欢迎查看我们的上一篇文章！）。

• 可扩展且对磁盘友好：专为高性能设计，无需消耗过多的内存与硬件资源。

简而言之，VectorChord 将 PostgreSQL 变成了一个强大的引擎，能够轻松应对 ColQwen2 或 ColPali 等模型所需的高级向量搜索技术。

实战教程：构建你的免 OCR RAG 系统

理论已经讲得很清楚了，现在让我们挽起袖子亲手构建这个系统！我们将依次完成环境搭建、使用 Modal 进行可扩展的向量嵌入生成、将数据索引到 Postgres 内的 VectorChord 中，最后对我们全新的免 OCR RAG 系统进行评估。

前提条件

在开始之前，请确保你已具备：

• 一个安装了 VectorChord 扩展的 PostgreSQL 实例（推荐使用 Docker）或一个 VectorChord Cloud 集群。

• 一个 Modal 账号（提供免费额度）。Modal 快速的 GPU 调配与弹性扩缩容能力非常适合生成向量嵌入这一步骤。为了使用 ColQwen2 模型高效处理海量文档，充分利用 Modal 的快速启动和 GPU 扩展特性至关重要，这将大幅缩短本地处理所需的时间。

如果你想快速复现本教程，可以使用 tensorchord/vchord-suite 镜像来运行 TensorChord 提供的多个扩展。

运行以下命令即可构建并启动包含 VectorChord-BM25 和 VectorChord 的 Postgres：

docker run   \           
  --name vchord-suite  \
  -e POSTGRES_PASSWORD=postgres  \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg17-latest

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;
CREATE EXTENSION IF NOT EXISTS pg_tokenizer CASCADE;
CREATE EXTENSION IF NOT EXISTS vchord_bm25 CASCADE;
\dx
pg_tokenizer | 0.1.0   | tokenizer_catalog | pg_tokenizer
vchord       | 0.3.0   | public            | vchord: Vector database plugin for Postgres, written in Rust, specifically designed for LLM
vchord_bm25  | 0.2.0   | bm25_catalog      | vchord_bm25: A postgresql extension for bm25 ranking algorithm
vector       | 0.8.0   | public            | vector data type and ivfflat and hnsw access methods

配置 Modal：

$ pip install modal
$ python3 -m modal setup  # click the link to authorize

步骤 1：加载数据（使用 Modal Volumes）

我们将使用 ViDoRe Benchmark 数据集。为了在可能分布式运行的 Modal 函数之间高效处理这些数据，我们将其下载到一个 Modal Volume 中。Volume 提供了持久化的共享存储，非常适合这种“一次下载，多次处理”的场景。

image = modal.Image.debian_slim().pip_install("datasets","huggingface_hub","Pillow")
DATASET_DIR = "/data"
DATASET_VOLUME  = modal.Volume.from_name(
    "colpali-dataset", create_if_missing=True
)
app = modal.App(image=image)

@app.function(volumes={DATASET_DIR: DATASET_VOLUME}, timeout=3000)
def download_dataset(cache=False) -> None:
    from datasets import load_dataset
    from tqdm import tqdm
    
    collection_dataset_names = get_collection_dataset_names("vidore/vidore-benchmark-667173f98e70a1c0fa4db00d") 
    for dataset_name in tqdm(collection_dataset_names, desc="vidore benchmark dataset(s)"):
        dataset = load_dataset(dataset_name, split="test",num_proc=10)
        unique_indices = dataset.to_pandas().drop_duplicates(subset="image_filename", keep="first").index #to remove repeating PDF pages with different queries
        dataset = dataset.select(unique_indices)
        dataset.save_to_disk(f"{DATASET_DIR}/{dataset_name}")

Modal 提供了直观的 Python API 来与其平台交互。通过 modal.Image，你可以为 Modal App 设置基础镜像，而 function 装饰器则用于定义要在 Modal 应用中执行的函数。要将数据集下载到 Modal Volume，请执行以下命令。Modal 会自动构建 Docker 镜像并立即启动容器来运行你的函数。

运行下载函数：

$ modal run dataset.py::download_dataset

Modal 会自动在云端完成环境构建和脚本运行。

步骤 2：处理数据并生成向量嵌入（使用 Modal 与 ColQwen2）

这是计算最繁重的部分：将文档图像转换为 ColQwen2 多向量嵌入。如果在本地对大量文档执行此操作会非常缓慢。Modal 在这里展现了强大的优势：

• 便捷的 GPU 访问与自动扩缩容：在 Modal 上启动一个 ColQwen2 模型服务，并用它为数据集生成图像嵌入和查询嵌入。之所以选择实现 HTTP 服务而不是直接调用 SDK，是为了确保在大规模向量生成期间能够实现无缝的自动扩缩容（Auto-scaling）。如果你想将该嵌入服务部署为持久化的 Web 端点，可以直接将 ColPaliServer 的 modal.cls 改为 modal.web_server 并运行 modal deploy。

• 断点恢复：我们将处理进度保存（Checkpoint）到另一个独立的 Modal Volume 中，以便在任务中断时能够从断点处继续生成向量。

# embedding.py (Illustrative - keep original code)
# ... imports, volumes setup ...
modal_app = modal.App() # Define app

# Function to coordinate embedding generation
@modal_app.function(...)
def embed_dataset(down_scale: float = 1.0, batch_size: int = BATCH_SIZE):
    # ... (logic for loading dataset names, handling checkpoints) ...
    colpali_server = ColPaliServer() # Get handle to our GPU class
    # ... (loop through datasets, batch items, call server for embeddings) ...
    # ... (save embeddings and update checkpoint) ...
    print("Embedding generation complete.")

# server.py (Illustrative - keep original code)
# Class running on GPU to serve embedding requests
@modal_app.cls(gpu=GPU_CONFIG, ...)
class ColPaliServer:
    @modal.enter()
    def load_model_and_start_server(self):
        # ... (Load ColQwen2 model, start internal FastAPI server) ...
        self.client = httpx.AsyncClient(...) # Client to talk to internal server

    @modal.exit()
    def shutdown_server(self):
        # ... (Cleanup) ...

    # Method called by embed_dataset function
    @modal.method()
    async def embed_images(self, images: List[str]) -> np.ndarray:
        # ... (Prepare batch, send request to internal server via self.client) ...
        # ... (Decode response using msgspec for speed) ...
        return embeddings_numpy_array

    # ... (Potentially add embed_queries method too) ...

# colpali.py
class ColPaliModel:
    def __init__(self, model_name: str = "vidore/colqwen2-v1.0", cache_dir: str="/model"):
        # ...
        if self.model_name == "vidore/colqwen2-v1.0":
            from colpali_engine.models import ColQwen2, ColQwen2Processor
            from transformers.utils.import_utils import is_flash_attn_2_available
            
            # load model
            model = ColQwen2.from_pretrained(
                self.model_name,
                torch_dtype=torch.bfloat16,
                device_map="cuda:0", 
                attn_implementation="flash_attention_2" if is_flash_attn_2_available() else None,
                cache_dir=self.cache_dir,
            ).eval()

            colpali_processor = ColQwen2Processor.from_pretrained(
                self.model_name,
                cache_dir=self.cache_dir,
            )
    # ... functions for embedding images and queries
    # @modal.method()
    # async def batch_embed_images(self, images_base64: List[str]) -> np.ndarray:
    # @modal.method()
    # async def batch_embed_queries(self, queries: List[str]) -> np.ndarray:

生成向量嵌入：

$ modal run embedding.py::embed_dataset

步骤 3：在 VectorChord 中创建索引（使用 Vechord SDK）

向量嵌入生成并保存在 Modal Volume 中之后，我们首先需要将它们下载到本地：

$ modal volume get colpali-embedding-checkpoint /path/to/local/vidore_embeddings

现在，我们将使用 vechord SDK 把这些嵌入加载到 PostgreSQL 数据库中，并创建所需的多向量索引。vechord 提供了一种符合 Python 习惯、类似 ORM 的方式来与 Postgres 中的 VectorChord 进行交互。

%[https://github.com/tensorchord/vechord]

MultiVector = List[Vector[128]] # Assuming 128 dimensions for ColQwen2

lists = 2500 # lists is the number of the cluster
# Define the database table schema using vechord
class Image(Table, kw_only=True):
    uid: Optional[PrimaryKeyAutoIncrease] = None
    image_embedding: Annotated[MultiVector, MultiVectorIndex(lists=lists)] # Stores the document's visual embeddings 
    query_embedding: Annotated[MultiVector, MultiVectorIndex(lists=lists)]  # Stores the query's embeddings 
    query: str = None
    dataset: Optional[str] = None
    dataset_id: Optional[int] = None

# Connect to your PostgreSQL database
# Ensure the URL points to your local Docker or VectorChord Cloud instance
DB_URL = "postgresql://postgres:[email protected]:5432/postgres" # Default DB
vr = VechordRegistry("colpali", DB_URL)
vr.register([Image]) # Creates the table and multi-vector index if they don't exist

# Function to load embeddings from disk and yield Image objects
@vr.inject(output=Image)
def load_image_embeddings(path: str) -> Iterator[Image]:
    # ... (logic to load numpy arrays from disk, convert to List[Vector]) ...
    # ... (yield Image(...) instances) ...
    print(f"Loaded embeddings from {path}")

if __name__ == "__main__":
    # Path where you downloaded the embeddings from Modal
    embedding_dir = "/path/to/local/vidore_embeddings"
    load_image_embeddings(embedding_dir) # This triggers vechord to insert data
    print("Data loaded and indexed into VectorChord.")

运行索引脚本后，vechord 会自动处理建表、创建索引以及数据插入。

步骤 4：评估——效果究竟如何？

最后一步至关重要：评估检索性能。这套免 OCR 系统能否提供准确的结果？速度够快吗？我们将使用 vechord 在已建立索引的数据上运行查询，并重点考察 NDCG@10 和 Recall@10 指标。同时，我们还将测试 VectorChord 用于加速 MaxSim 计算的 WARP 优化的实际效果。在本教程中，我们将使用 vidore/arxivqa_test_subsampled 数据集进行评估查询，数据示例如下所示：

TOP_K = 10

# Define structure for results (optional but good practice)
class Evaluation(msgspec.Struct):
    map: float
    ndcg: float
    recall: float

TOP_K = 10
def evaluate(queries: list[Image], probes: int, max_maxsim_tuples: int) -> list[Evaluation]:
    result  = []
    for query in queries:
        vector = query.query_embedding
        docs: list[Image] = vr.search_by_multivec(
            Image, vector, topk=TOP_K, probe=probes, max_maxsim_tuples=max_maxsim_tuples
        )
        score = BaseEvaluator.evaluate_one(query.uid, [doc.uid for doc in docs])
        result.append(Evaluation(
            map=score.get("map"),
            ndcg=score.get("ndcg"),
            recall=score.get(f"recall_{TOP_K}"),
        ))
    return result

if __name__ == "__main__":
    # Select some queries from the benchmark dataset stored in the DB
    # Example: Get 100 queries from a specific subset
    test_queries: list[Image] = vr.select_by(
        Image.partial_init(dataset="vidore/arxivqa_test_subsampled"), limit=100
    )

    # ... optimize the param ...
    res: list[Evaluation] = evaluate(queries, probes=probes, maxsim_refine=maxsim_refine)
    print("ndcg@10", sum(r.ndcg for r in res) / len(res))
    print("recall@10", sum(r.recall for r in res) / len(res))
    print(f"Total execution time: {total_time:.4f} seconds")

运行评估脚本后，我们得到了令人印象深刻的结果：

# Disable WARP
ndcg@10 0.8615
recall@10 0.92
Total execution time: 810 seconds # Baseline accuracy and time

# Enable WARP
# There is no need to focus on specific times, 
# only relative times need to be taken into account, 
# as the tests were performed on a local model with poor performance.
ndcg@10 0.8353
recall@10 0.90
Total execution time: 41 seconds # Dramatic WARP Speed Boost

结果分析：

• 高基线精度：首先看未开启 WARP 优化时的基线表现。系统取得了 0.8615 的出色 NDCG@10 和 0.92 的 Recall@10。这证实了 ColQwen2 嵌入配合 VectorChord 精确 MaxSim 搜索的根本有效性——即便不启用速度优化，也能在视觉文档检索上交出顶尖答卷。

• WARP 带来的惊人加速：再来看启用 VectorChord WARP 优化后的效果。总执行时间从漫长的 810 秒骤降至仅需 41 秒！在整个评估查询集上实现了高达 约 18.7 倍的加速。这清晰地展示了 WARP 在加速 ColQwen2 等晚期交互模型所需的计算密集型 MaxSim 运算方面的强大威力。

• 微乎其微的精度折衷：令人赞叹的是，如此大幅度的速度提升仅以极小的检索精度下降为代价：NDCG@10 略微降至 0.8353（差距不到 0.03），Recall@10 仅微降至 0.90（差距仅 0.02）。

总结：在 Postgres 中让视觉 RAG 变得更简单

在本教程中，我们将 ColQwen2 的视觉理解能力、PostgreSQL 内 VectorChord 的可扩展多向量搜索能力，以及 Modal 的高效 GPU 处理能力融为一体，成功构建了一套高性能的免 OCR RAG 系统。我们看到了这套技术栈如何让我们直接根据文档的视觉内容进行查询，从而绕开传统 OCR 流水线的重重陷阱。

直接在 Postgres 内部将这一视觉维度无缝集成到 RAG 系统中，为处理科学论文、发票、产品手册、历史档案等视觉信息丰富的文档应用打开了激动人心的可能性。

准备好亲自试试了吗？

• 探索完整代码： https://github.com/xieydd/vectorchord-colqwen2

• 深入了解 VectorChord： 查阅 VectorChord 文档，或体验省心的 VectorChord Cloud。

• 动手实验： 尝试接入不同的 VLM 模型或数据集。

• 分享你的想法： 欢迎在下方评论区告诉我们你的使用体验或问题！

这一方法标志着我们向更简洁、更稳健且具备视觉感知能力的文档检索系统迈出了重要一步。

参考资料

• https://huggingface.co/vidore/colqwen2-v1.0

• https://huggingface.co/blog/manu/colpali

• https://blog.vespa.ai/scaling-colpali-to-billions/

9 - 在 PostgreSQL 中用 30 亿向量守护地球

监测地球的健康状况是我们这个时代最严峻的挑战之一。我们的星球正面临巨大的环境压力，而要理解这些变化，就必须筛选超乎想象的海量卫星数据——持续不断捕获的 PB 级像素图像。从追踪亚马逊雨林的森林砍伐，到识别偏远地区的非法采矿作业，再到监测农业活动对敏感生态系统的影响，将这些原始数据转化为可落地的行动情报至关重要。

Earth Genome 打造的 Earth Index 平台正在正面迎击这一挑战。如今，它已实现全球覆盖，利用 AI 的力量让地球上的每一寸陆地表面都变得可搜索。这不仅是一项技术成就，更是一款旨在通过从卫星数据中提取易用、可操作的情报来赋能环境保护的全新工具。

%[https://www.earthgenome.org/]

在 VectorChord 团队，我们无比自豪地看到我们的 PostgreSQL 向量搜索扩展正在为这一宏伟而至关重要的使命提供核心动力。

Earth Index 在做什么？将像素转化为地球洞察

试想一下，要在覆盖数百万平方公里的卫星图像中，找出某种特定类型的小规模环境影响——比如一处未申报的采石场或一片新出现的森林砍伐区。传统上，分析这些数据需要深厚的专业知识和庞大的计算资源，这使得在广阔偏远的地区追踪特定威胁变得极其困难，对于预算有限的环保组织、调查记者和监管机构而言更是如此。下面的动画展示了 Earth Index 是如何高效地在亚马逊雨林中精准定位非法贩毒简易机场的——这无异于在足球场上找出一根牙签。

那么，Earth Index 是如何让在全球范围内寻找特定环境特征成为可能的呢？其中的奥秘在于一种前沿方法：使用通过对比学习（Contrastive Learning）训练的 AI 基础模型及其生成的向量嵌入（Vector Embeddings）。

以下是其创新工作流程的简要解析：

1. 全球网格切片（Tiling the Globe）：Earth Index 将地球的全部陆地表面划分为超过 32 亿个相互重叠的网格切片（Tiles），每个切片约占 10 公顷。

2. 通过对比自监督学习“地球 DNA”：Earth Index 利用了 AI 领域的突破性进展，特别是使用自监督对比学习方法（如 DINO 目标函数）针对地球观测（Earth Observation, EO）训练的基础模型。该基础模型（例如 SSL4EO Vision Transformer）通过区分来自同一地理位置的图像对（正样本对）和来自不同地理位置的图像对（负样本对），学习卫星图像的基础视觉语言。这一过程在多样化的全球数据集（如 Harmonized Landsat Sentinel-2、Sentinel-1 雷达图像）上进行，无需人工显式标注“森林”或“城市”等特征。

3. 生成向量嵌入（Generating Vector Embeddings）：预训练完成后，该模型即作为编码器运行。将每个切片的图像输入其中，就会生成一个向量嵌入——这是一种丰富的数值表示或“数字指纹”，以高度压缩的格式（压缩率超过 10,000 倍）捕捉该切片的核心视觉与结构特征。这个高维向量就像是那片土地独一无二的“地球 DNA”。

4. 打造可搜索的地球（Creating a Searchable Planet）：这 32 亿个向量嵌入构成了 Earth Index 的核心。它们需要存储在一个专为快速查找数值相似向量而优化的系统中。用户只需提供一个想要查找的目标示例（例如在地图上点击一个已知的非法矿场或某种特定类型的农业基础设施），Earth Index 就会在这个海量数据集中进行搜索，找出全球（或特定区域内）具有相似向量指纹的其他位置。

真实世界的影响力：Earth Index 赋能环境保护实战

这一技术底座直接转化为了理解和保护环境的强大工具。它赋予了调查记者（如 Mongabay 和自由欧洲电台的记者）、原住民社区、环保及国际组织（如世界银行）以及研究人员前所未有的便捷与速度，去揭露隐蔽的环境变化、监测工业足迹，并为生态保护行动收集证据。下图展示了丰塞卡湾（Gulf of Fonseca）的养虾场分布。

以下是 Earth Index 在实际应用中的几个典型案例：

• 打击森林砍伐与非法活动：在与 Mongabay 的合作中，Earth Index 穿透茂密的树冠层，成功识别出亚马逊雨林中隐蔽的非法贩毒简易机场。同样地，该平台还能快速定位非法采金留下的地表伤痕（例如正在破坏亚诺马米原住民领地的非法采矿点），帮助量化问题规模并指导执法行动。

• 监测资源开采：**自由欧洲电台（Radio Free Europe）**利用 Earth Index 在巴尔干半岛识别出 1,300 多个采石场，揭露其中约有一半缺乏合法许可证，凸显了潜在的环境破坏和无序开采问题。同样的方法也可用于监测水力压裂井场、橡胶加工厂或其他工业设施。

• 保护水质与生态系统：Earth Index 可以定位敏感水道附近的集中型动物饲养场（CAFO），以评估径流污染风险，或识别向关键红树林生态系统扩张的养虾场。

• 追踪农业扩张：通过搜索与新开垦土地或特定作物类型相关的特征模式，该工具能够帮助监测自然栖息地向农业用地的转化过程。

基础设施挑战：以可承受的成本搜索数十亿向量

生成 32 亿个高维向量只是挑战之一；如何高效地托管并搜索这些向量则是另一道巨大的难关。Earth Index 需要一套能够满足以下要求的解决方案：

• 应对超大规模：搜索数十亿向量需要专门的索引和查询能力。

• 与地理空间数据无缝集成：Earth Index 高度依赖地理空间操作（例如在特定行政边界内过滤结果，或筛选靠近河流的区域）。这使得配备 PostGIS 的 PostgreSQL 成为其核心数据库自然且不可或缺的选择。而独立的专用向量数据库通常缺乏所需的丰富地理空间特性。

• 保持高性能：用户需要相对快速地获得搜索结果，平台才能在调查和监测工作中发挥实效。

• 控制成本：存储和搜索数十亿向量（尤其是当纯内存索引需要海量 RAM 时）对于许多组织——特别是非营利组织——而言，硬件成本往往高得令人望而却步。

因此，Earth Index 需要一种原生运行在其选定的 PostgreSQL 环境中、能够大规模扩展、性能卓越，同时不会在硬件成本上超出预算的向量搜索解决方案。

为什么 PostgreSQL 是地球级规模向量搜索的理想之选

尽管市面上存在专用的向量数据库，但 Earth Index 面临着一个核心诉求：将向量相似度搜索与丰富的地理空间数据及操作无缝集成。这正是 PostgreSQL 结合扩展生态真正大放异彩的地方：

• 统一的数据平台：PostgreSQL（尤其是配合强大的 PostGIS 扩展）使 Earth Index 能够将向量嵌入与关键的地理空间元数据（切片位置、行政边界、与河流等地物的距离）保存在一起。这避免了为向量搜索和关系型/地理空间数据分别维护独立数据库所带来的复杂性以及潜在的数据同步问题。

• 充分发挥 SQL 与 PostGIS 的威力：Earth Index 可以在单一查询接口中，将向量相似度搜索与标准 SQL 过滤条件以及复杂的 PostGIS 空间查询（例如，“在此特定国家公园边界内或靠近该水系的范围内，查找与此示例相似的向量”）无缝结合。独立的向量数据库通常缺乏这种成熟的地理空间查询能力。

• 成熟度与生态系统：基于 PostgreSQL 构建意味着继承其数十年的研发积淀、享誉业界的稳定性、强大的工具链以及广泛的社区支持——这对于像 Earth Index 这样的关键任务平台至关重要。

然而，要高效地搜索 32 亿个向量，仅靠标准的 PostgreSQL 能力是远远不够的。

为什么 Earth Index 为了性能与性价比选择 VectorChord

虽然 PostgreSQL 生态系统提供了理想的底座，但在 32 亿向量的庞大规模下同时实现所需的性能与可承受的成本，依然是一项巨大的挑战。Earth Index 需要一种既能提供极速体验、又不会让预算爆表的解决方案。

要在性能、成本和集成度之间找到最佳平衡点并非易事。Earth Genome 首席技术官 Hutch Ingold 解释了他们的考量过程：

当我们为这 32 亿个向量评估解决方案时——充分考虑到日新月异的技术版图——标准 pgvector 在这一规模下无法满足我们的性能要求。像 Qdrant 这样的专用方案也面临困难：托管版本过于昂贵，而在我们的 Kubernetes 基础设施上自建集群部署在当时看来还不够成熟。我们也考察了云服务（例如 Google 的 Vertex AI Vector Search），但针对我们的数据集，每月高达 237,000 美元的目录报价实在令人望而却步。

这正是 VectorChord 成为关键赋能技术的原因：

• 超越原版 PGVector 的卓越性能：VectorChord 带来了亟需的速度提升——查询速度最高提升 5 倍、插入吞吐量提升 16 倍、索引构建速度提升 16 倍——彻底解决了标准 pgvector 在如此庞大规模下遇到的性能瓶颈。

• 基于磁盘索引实现高性价比扩展：至关重要的是，VectorChord 经过深度优化的磁盘索引（Disk-Based Indexing）（充分利用高性价比的 SSD）直接化解了 CTO 提到的高昂成本难题。它既避免了纯内存方案对海量 RAM 的苛刻需求，也避开了托管云向量服务天价的月度账单，使 32 亿向量的索引在财务上真正具备可行性。

• 原生集成与可扩展性：作为一款 PostgreSQL 扩展，VectorChord 直接在他们选定的数据库内部提供了这些优势，无需改动现有基础设施架构。它专为高效扩展而构建，在轻松应对 Earth Index 全球监测平台所需的数十亿向量的同时，依然保持了流畅的交互式性能。

VectorChord 在 Earth Index 所熟悉且强大的 PostgreSQL 环境中，直接提供了高性能、大规模可扩展性与高性价比的完美结合。

Earth Index：技术架构与部署配置

为了高效且经济地管理其地球级数据集，Earth Index 在由三台强大的 AWS EC2 i8g.16xlarge 实例组成的集群上构建了后端系统，这些实例搭载了最新的 Graviton4 ARM 处理器和 Nitro SSD。每台实例提供 512 GB 内存、64 个 vCPU 和 15 TB 的 NVMe 存储，为计算和磁盘 I/O 奠定了坚实的基础。这套架构每月成本约为 12,000 美元，相比同类托管云向量服务预计每月 237,000 美元的费用节省了巨额开支，使整个项目在经济上得以持续运转。这些实例运行着由 VectorChord 和 PostGIS 增强的 PostgreSQL，高效地同时承载向量数据和其他应用组件。

核心数据驻留在跨三个节点的分区表结构中。主表 globe24 存储了每个切片的唯一 ID、其地理空间点几何信息（geometry(Point, 4326)）、分区键（partkey），以及至关重要的、以 halfvec(384) 高效存储的 384 维 AI 生成嵌入向量。这种分片设计将 32 亿行数据分布在集群中，支持高效的并行处理。

该架构的一大核心优势在于能够执行复杂的综合查询。Earth Index 经常执行的 SQL 语句，能够将 VectorChord 的快速向量搜索（embedding <=> '{vector}'::vector）与 PostGIS 地理空间过滤（st_within(geom, '{geom}')）以及分区裁剪（partkey IN (...)）无缝结合。这让用户能够在特定地理边界内高效地查找视觉相似的位置。即便面对数十亿向量，这种一体化方法依然展现出了实用的高性能：对于返回前 500 个结果的典型搜索，中位查询延迟（p50）约为 761 毫秒。

赋能大规模环保行动

通过在 PostgreSQL 内部提供高性价比、可扩展且紧密集成的向量搜索解决方案，VectorChord 助力 Earth Index 开展了这项极具突破性的工作。它使团队能够以可承受的成本管理庞大的“地球 DNA”数据库，确保这一强大的环境监测工具能够真正惠及最需要它的组织与社区。

立即加入 Earth Index 候补名单，探索你周边的环境挑战，了解你的生态足迹，并成为守护地球全球行动的一份子。

看到 Earth Index 利用 VectorChord 将卫星数据转化为可落地的环境情报，我们感到无比振奋。他们的成功充分证明了将前沿 AI、稳健的数据库技术与高效的向量搜索相结合，在应对全球重大挑战时所能迸发出的巨大能量。

有兴趣将大规模向量搜索引入你的 PostgreSQL 数据库吗？欢迎进一步了解 VectorChord 或立即开始体验！

%[https://github.com/tensorchord/VectorChord]

10 - PostgreSQL 向量搜索：内存与磁盘方案对比分析

引言：真实场景中的挑战

并非所有场景都需要专用的向量数据库。借助 pgvector、pgvectorscale、VectorChord（演进自 pgvecto.rs）等 PostgreSQL 扩展，您可以在无需额外基础设施的情况下同时获得向量搜索与关系型数据库的能力。但实际落地并非总是顺风顺水，以下是真实用户的反馈：

• 首次查询耗时 30 秒，而重复查询只需 100 毫秒。问题出在极其缓慢的 I/O 上。

• 为 1,200 万行 75 维向量构建索引需要 3 个小时，这正常吗？

• 在为 2 亿条 75 维向量构建索引 13 个小时后，我注意到进度到 30% 时内存占用高达 100GB/124GB，最终服务器直接崩溃了。

• 我们遇到了一些挑战，特别是频繁的索引更新需求、吞吐量瓶颈、缺乏并行索引扫描以及没有内置量化支持。

在本文中，我们将深入探讨这些问题，帮助您不仅了解这些工具“是什么”，更理解其背后的“为什么”，从而做出明智的决策。让我们一起探索如何应对这些复杂挑战，并挑选最适合您需求的解决方案。

我们在向量数据库中最看重什么？

在 PostgreSQL 中，shared_buffers 是一个关键的内存区域，充当数据页（包括表数据和索引）的主缓存。通过将频繁访问的向量索引块存储在该内存缓冲区中，PostgreSQL 可以大幅减少缓慢的磁盘 I/O。当查询需要数据时，PostgreSQL 首先检查 shared_buffers。如果数据已在其中，即可直接快速读取而无需访问磁盘；如果不在，则从磁盘读取数据并加载到 shared_buffers 中以供后续查询使用。要配置此参数，可在 psql 中执行 ALTER SYSTEM SET shared_buffers = 'xGB' 并重启服务器。

假设您的表中已经存储了一些向量，索引构建完成后，就可以开始执行查询了。即便您已经为 PostgreSQL 配置了足够大的 shared_buffers，在执行首次查询（first query）时，系统仍然需要从磁盘读取索引。然而，对于重复查询（repeated query），由于向量可以直接从 shared_buffers 中获取，查询速度会快得多。

虽然冷启动或索引变更后的首次查询表现很重要，但系统的持续性能往往取决于索引中“热点”或频繁访问的部分被缓存到内存（shared_buffers）之后的查询执行速度——这正是重复查询所模拟的场景。因此，针对缓存命中的性能进行优化，对于许多真实生产应用而言至关重要。

在本文中，我们将对比各向量相似度搜索扩展在以下两种场景下的性能表现：

• 内存充足时的查询性能

• 内存受限且磁盘成为瓶颈时的查询性能

我们还将探讨与索引构建相关的其他维度，例如：

• 索引构建速度（Index build speed）：构建索引需要多长时间？如果实例拥有多个 CPU 核心，能否充分利用多核来加速构建？

• 内存占用（Memory usage）：创建索引需要预留多少内存？这是选择云实例规格时最重要的考量因素。

• 磁盘占用（Disk usage）：给定磁盘空间可以容纳多少向量？在选择配备不可扩展本地 NVMe SSD（一种高性能固态硬盘）的实例时，这也是一个重要考量。

• 易用性（Ease of use）：能否使用一条简单的 CREATE INDEX 命令创建索引？针对查询性能进行调优有多难？

最后，我们将讨论索引构建完成后的插入性能（insertion performance）。如果用户的业务包含流式数据并会触发频繁的索引更新，这一指标就显得尤为关键。

实验环境设置

下表展示了后续所有实验所使用的硬件配置与数据集信息：

下表列出了我们在实验中使用的各个扩展的版本信息：

内存中的向量：面向小规模数据

对于向量搜索系统而言，如果追求最佳性能，确保整个索引缓存在 shared_buffers 中至关重要，这通常更适合运行在内存优化型实例上。在这种情况下，shared_buffers 的大小理想情况下应当足以容纳整个索引。

在本次实验中，我们选择了一个中等规模的数据集 LAION-5m，其中包含 500 万条 768 维向量。为了将 LAION-5m 容纳在 shared_buffers 中，我们选用了配备 937GB NVMe SSD 和 32GB 内存的 AWS I4I Extra Large 实例。

在这台机器上，我们将 shared_buffers 设置为 24GB，先后测量首次查询和重复查询的性能。以下是 pgvector、pgvectorscale 和 VectorChord 在重复查询下的性能对比结果。

下图展示了查询速度（QPS）与搜索质量（Recall@10/100）之间的权衡关系。Recall@10 衡量在返回的前 10 个结果中找到真实最近邻的比例。通常来说，可以通过牺牲一定的召回率来换取更高的 QPS，反之亦然。更优秀的系统能够在相同 QPS 下实现更高的召回率，或者在相同召回率水平下提供更高的 QPS。我们的目标通常是在保持高召回率目标（例如 95%）的前提下最大化 QPS。

为了测量首次查询性能，我们在顺序执行 10,000 条测试查询之前清空了 shared_buffers。尽管缓冲区初始为空，但在同一次测试运行中，前序查询加载到缓存中的索引/数据页有时会被后续查询复用，这会导致瞬时 QPS 在运行过程中逐步上升。因此，我们报告全部 10,000 条查询的平均 QPS，以此作为冷缓存下性能的代表性指标。

总而言之，与其他扩展相比，VectorChord 在高召回率水平（例如 >95% Recall@10）下始终能实现更高的 QPS。至于另外两款扩展，pgvectorscale 在首次查询时表现更好，但一旦数据被缓存到内存中，pgvector 的表现则会反超。

磁盘中的向量：面向大规模数据

但在某些场景下情况会截然不同。面对数十亿规模的向量，单台机器的内存根本无法容纳整个索引。当待读取向量的体积超过内存大小时，shared_buffers 的加速效果会大幅减弱，绝大部分数据都必须从磁盘读取。

虽然此时 shared_buffers 的作用下降，但操作系统的页缓存（page cache）仍能提供一定的缓存加速，不过其性能通常低于 shared_buffers。

为了模拟这种场景，我们将 LAION-5m 部署在一台配置小得多的 C6ID Large 机器上（仅配备 4GB 内存，并将 shared_buffers 设为 2GB）。这一配置确保内存处于不足状态，迫使绝大多数查询访问磁盘。

在这种情况下，由于内存不足，首次查询与重复查询之间的性能差异会小得多。因此，仅评估各扩展的重复查询性能即可反映真实水平。

一如既往，在高召回率水平（例如 >95% Recall@10）下，VectorChord 依然取得了远高于其他扩展的 QPS，而 pgvector 和 pgvectorscale 的 QPS 则较为接近。

索引构建体验

正如前文所述，用户同样十分关注索引构建阶段的各项指标：索引构建耗时、内存占用、磁盘占用以及易用性。我们在上述 LAION-5m 数据集实验的 CREATE INDEX 阶段测量了这些指标：

• CPU 核心利用率（Core utilization）：索引创建期间有效利用的可用 CPU 核心百分比。数值越高表明并行度越好。

• 索引构建耗时（Index build time）：SQL 命令构建索引所花费的时间。如果索引构建需要额外步骤（如 VectorChord 外部构建），该步骤耗时也计入其中。

• 内存占用（Memory usage）：索引构建期间的峰值内存使用量，包含分配给 PostgreSQL 的 1GB shared_buffers。

• 磁盘占用（Disk usage）：索引构建完成后磁盘上 PGDATA 的总大小（包含向量表数据和索引）。

前文所有查询性能均是在使用配备 A10 GPU 的独立机器完成外部构建后测得的。如果您坚持使用同一台 I4I Extra Large 实例进行外部构建，索引构建耗时将增加至 50 分钟，但这依然极具竞争力。

在本测试中，我们将 shared_buffers 设置为 1GB，并记录了各扩展的峰值内存占用。VectorChord 的内部构建与外部构建均将 K-means 聚类迭代次数设置为 25 次（25 iters）。在易用性方面，pgvector、pgvectorscale 和 VectorChord 的内部构建语法相似，只需一条 SQL 语句即可完成索引构建；而 VectorChord 的外部构建则相对复杂一些。

在大多数指标上，VectorChord 的外部构建均处于领先地位，但这在一定程度上牺牲了易用性，因为开发者需要在 PostgreSQL 外部实现额外的 K-means 聚类步骤并管理生成的质心。

如果您希望通过一条简单的 CREATE INDEX 命令直接上手，那么 VectorChord 的外部构建可能不是最省心的选择，您可以根据需求转向其他扩展或方式：

• 选择 VectorChord 的内部构建 以获得更快的单命令索引构建速度

• 如果您的内存确实非常捉襟见肘，可以选择 pgvector

• 选择 pgvectorscale 以降低磁盘空间需求或获得更高的存储容量效率

插入性能：面向流式生成数据

面对流式生成的向量数据，插入速度会成为新的关注焦点。在实时数据分析系统中，每秒新写入的向量数量可能非常庞大。每当新向量添加到索引中时，索引自身也必须同步更新。这种能力通常被称为插入性能（insertion performance）。

为此，我们设计了一项实验来检验各扩展的插入表现。在为 500 万条向量构建好索引之后，我们逐条向表中连续插入另外 100,000 条随机生成的向量，并统计全部插入完成所需的总时间。

可以看到，在插入数据时，VectorChord（1565 Insert/Sec）的表现远优于 pgvector（246 Insert/Sec）和 pgvectorscale（107 Insert/Sec）。对于大多数工作负载而言，每秒 100 次插入已经绰绰有余；但如果您发现生产环境中存在大量持续写入的向量（例如达到 500 Insert/Sec），这就可能成为系统瓶颈。

总结

基于上述实验结果，下表汇总了三款扩展在各个维度的差异。我们可以看到，VectorChord 的核心优势集中在性能上，而 pgvector 和 pgvectorscale 则分别在易用性和存储容量效率方面各有千秋。

如果您希望了解更详尽的对比，下表展示了三款扩展在各个具体维度的表现：

想了解更多关于 VectorChord 与其他扩展的对比吗？在未来的博客中，我们将探索 PostgreSQL 向量扩展在更多场景下的差异，例如 BM25 混合搜索（将传统关键词搜索与向量相似度搜索相结合）以及带过滤条件的向量搜索（filtered vector search）。准备好在您的向量搜索场景中试用 VectorChord 了吗？欢迎下载扩展，加入我们的 Discord 社区，或通过 [email protected] 联系我们。

%[https://github.com/tensorchord/VectorChord]

11 - PostgreSQL 全文检索：用对方法其实很快（打破“慢”的迷思）

你可能在一些技术讨论或博客文章中看到过这样的观点：与专用搜索引擎或特定扩展相比，PostgreSQL 内置的全文检索（Full-Text Search，简称 FTS）在性能上表现不佳。近期一个典型的例子是 Neon 发布的博客文章《Performance Benchmark: pg_search on Neon》（链接）。

在这项基准测试中，Neon 将其数据库平台上搭载 pg_search 扩展（基于 Rust 的 Tantivy 库并通过 pgrx 构建）的查询性能，与使用 tsvector 和 GIN 索引的 Postgres 内置全文检索进行了对比。值得肯定的是，他们声明已通过在适当位置添加 GIN 索引对标准配置进行了优化（基准测试代码见此处）。

然而，虽然添加 GIN 索引是必要的第一步，但测试结果中“标准”配置表现出的显著慢速表明，PostgreSQL FTS 几个至关重要的额外优化步骤很可能被遗漏了。所谓“标准 FTS 天生比 pg_search 慢得多”的结论，很可能是建立在一个无意间被严重拖累的基线（baseline）之上的。

接下来，让我们深入探讨如何正确配置和使用标准 PostgreSQL FTS 以发挥其最佳性能，剖析 Neon 基准测试基线中很可能存在的具体配置缺陷，并展示内置 FTS 的真实速度。我们将通过翔实的数据证明：只需对基线配置应用这些标准优化，就能直接带来约 50 倍的性能提升。

基准测试环境回顾（来自 Neon 的分析）

该测试使用了一个包含 1000 万条日志记录的表，表结构类似如下：

CREATE TABLE benchmark_logs (
    id SERIAL PRIMARY KEY,
    message TEXT,
    country VARCHAR(255),
    severity INTEGER,
    timestamp TIMESTAMP,
    metadata JSONB
);

他们测试了多种查询类型，其中许多涉及检索 message 文本字段。在其“标准 Postgres”示例中，查询结构如下：

-- Create index on to_tsvector('english', message)
CREATE INDEX message_gin ON benchmark_logs USING gin (to_tsvector('english', message));
-- Example problematic query structure (likely used in Neon's baseline)
SELECT country, COUNT(*)
FROM benchmark_logs
WHERE to_tsvector('english', message) @@ to_tsquery('english', 'research')
GROUP BY country
ORDER BY country;

即便 message 上已经创建了函数 GIN 索引，这种查询写法以及很可能保留了默认值的 GIN 索引配置，正是导致标准 FTS 基线出现性能问题的根源。

我们的测试环境详情（复现基线场景）

为了展示正确优化对标准 FTS 的实际影响，我们使用了以下环境：

• 实例规格：配备本地 NVMe SSD 的 AWS EC2 i7ie.xlarge（将磁盘 I/O 干扰降至最低）。

• CPU：4 vCPU。

• PostgreSQL 配置：通过 Docker 运行 PostgreSQL 16，并根据硬件资源进行了如下配置：

  docker run -d \
    --name my-postgres \
    --network=host \
    -v /mnt/localssd/pgdata:/var/lib/postgresql/data \
    -e POSTGRES_PASSWORD=mysecretpassword \
    postgres:latest \
    -c shared_buffers=8GB \
    -c maintenance_work_mem=8GB \
    -c max_parallel_workers=4 \
    -c max_worker_processes=4

• 关于并行度的说明：上述配置默认提供 max_parallel_workers_per_gather = 2。Neon 的文章提到由于实例规格较大，其测试环境使用了 8 个并行工作进程，意味着其查询并行度（max_parallel_workers_per_gather 最高可达 8）高于我们的测试环境。换言之，我们对标准 FTS 的优化结果是在更低的查询并行度下取得的。

误区 #1：在查询时实时计算 tsvector（主要问题）

Neon 博客中展示的示例查询（在初级 FTS 教程中也很常见）在 WHERE 子句中实时计算 tsvector：

WHERE to_tsvector('english', message) @@ to_tsquery('english', 'research')

这会迫使 PostgreSQL：

1. 执行高开销的重复计算：在查询执行期间，针对大量数据行反复运行 to_tsvector()（包括解析、词干提取等操作）。

2. 限制索引效率：阻碍对 GIN 索引最直接、最高效的利用，即便基础 message 列上已经创建了表达式索引。

修复方法（构建合理的标准 FTS 基线）：预计算并持久化存储 tsvector。

1. 添加独立的 tsvector 列：

   ALTER TABLE benchmark_logs ADD COLUMN message_tsvector tsvector;

2. 填充该列数据：

   UPDATE benchmark_logs SET message_tsvector = to_tsvector('english', message);

3. 在该 tsvector 列上创建索引（并设置 fastupdate=off）：（详见下方误区 #2 的修复）

4. 改写查询语句：

   -- Optimized standard FTS query
   SELECT country, COUNT(*)
   FROM benchmark_logs
   WHERE message_tsvector @@ to_tsquery('english', 'research') -- Use the indexed column!
   GROUP BY country
   ORDER BY country;

误区 #2：忽略 GIN 索引的 fastupdate 参数（次要问题）

虽然 Neon 的基准测试正确地选择了 GIN 作为标准 FTS 的索引类型，但它很可能使用了默认设置：fastupdate=on。

• fastupdate=on（默认）：通过使用待处理列表（pending list）优先保障索引的更新速度。随着时间推移，这会显著拖慢搜索速度——尤其是在基准测试所用的大型静态数据集上，因为查询时必须同时扫描主索引和不断增长的待处理列表。此外，它还会导致索引膨胀和页面结构效率下降。

• fastupdate=off：优先保障搜索速度。虽然索引写入更新会变慢，但生成的索引结构更加紧凑，且由于无需扫描待处理列表，查询速度会快得多。对于读密集型工作负载或测试检索性能的基准测试而言，这一设置必不可少。

为了围绕搜索速度进行公平对比，标准 FTS 基线应当使用 fastupdate=off。

修复方法（构建合理的标准 FTS 基线）：

-- Create the GIN index correctly for search speed
CREATE INDEX idx_gin_logs_message_tsvector
ON benchmark_logs USING GIN (message_tsvector) -- Index the dedicated tsvector column
WITH (fastupdate = off);

性能影响：标准 FTS 获得约 50 倍加速

当我们将这些标准优化措施应用到标准 PostgreSQL FTS 配置上时，会发生什么？我们在 1000 万行数据集上测试了 Neon 示例中的同一条查询：

• 未优化的标准 FTS（Neon 基线配置）：~41301 ms（41.3 秒）

• 优化后的标准 FTS（应用上述修复后）：~877 ms（0.88 秒）

这证明仅需应用业界公认的最佳实践，就能让标准 PostgreSQL FTS 获得约 50 倍的速度提升。这彻底改变了基线性能表现，说明 Neon 基准测试中所用的参照点可能并未反映出内置 FTS 的真实潜力。而且，这一加速效果还是在可用查询并行度低于 Neon 测试环境的情况下实现的。

客观事实：相关性排序（ts_rank）的性能局限

不过，Neon 的分析在排序速度方面确实指出了一个切中要害的问题。与单纯找出匹配行相比，标准 PostgreSQL 中的 ts_rank 或 ts_rank_cd 等排序函数确实相对较慢。这是因为在执行 LIMIT 截断之前，排序函数需要获取并处理所有匹配行的数据，这会带来可观的 I/O 和 CPU 开销。

超越标准 FTS：使用 VectorChord-BM25 实现高性能排序

虽然标准 FTS 非常擅长快速过滤出匹配文档，但如果业务对精细、高性能的*相关性排序（ranking）*有严格要求，通常就需要借助专门的工具了。与其仅依赖内置排序函数，不如考虑使用 VectorChord-BM25。

VectorChord-BM25 是一款专为基于广受认可的 BM25 算法进行快速相关性排序而设计的 PostgreSQL 扩展。BM25 超越了简单的词项匹配，通过综合词项在文档内的词频（TF）以及在整个文档集合中的逆文档频率（IDF）来精准评估相关性。

VectorChord-BM25 的核心优势包括：

• 极致性能：专为速度打造，在排序任务中表现优于 Elasticsearch（最高快 3 倍）及 pg_search 等同类方案。

• 标准 BM25 算法：实现了经典、高效的相关性排序模型。

• 专用索引结构：采用专用的 bm25 索引类型（结合了 Block-WeakAnd 等算法优化），这对于实现极速跳过非Top-K候选以及计算 BM25 评分所需的全局统计信息至关重要。

• 专用数据类型：引入了 bm25vector 类型，专门用于存储适配 BM25 计算的分词表征。

如果你的应用高度依赖相关性排序的质量与速度，且标准 ts_rank 难以满足需求，VectorChord-BM25 在 PostgreSQL 内部提供了一个强大、原生集成的替代方案。

总结：标准 FTS 比你想象的要快得多

只要通过持久化的 tsvector 列和正确配置的 GIN 索引（针对读场景设置 fastupdate=off）进行合理优化，标准 PostgreSQL FTS 在查找匹配文档方面完全具备极其出色的性能。那些声称它很慢的基准测试，往往是在与未经妥善优化的基线进行对比。

而对于标准 ts_rank 力有未逮的高级相关性排序场景，像 VectorChord-BM25 这样的专用扩展通过专用数据类型和优化索引策略实现了 BM25 算法，能够带来数量级的性能飞跃。

请为你的任务选择合适的工具：首先正确优化标准 FTS；如果高性能相关性排序至关重要，不妨探索专为该目标打造的扩展方案。

%[https://github.com/tensorchord/VectorChord-bm25]

12 - VectorChord-BM25：推出独立的多语言高级搜索分词器 pg_tokenizer

我们很高兴地宣布发布 VectorChord-BM25 0.2 版本！这款 PostgreSQL 扩展旨在将先进的基于 BM25 的全文检索排序能力直接引入您的数据库中。

借助 VectorChord-BM25，您无需依赖外部搜索引擎，即可直接利用信息检索领域的标准算法——BM25 的强大能力。本次发布迈出了重要一步，重点强化了核心文本处理组件：分词（tokenization），从而带来了更高的灵活性以及显著提升的多语言支持能力。

重磅消息：推出 pg_tokenizer.rs

VectorChord-BM25 0.2 的核心基石是一个完全重构并解耦的独立分词器扩展：pg_tokenizer.rs。

为什么要做出这一改变？我们意识到，分词（即将文本切分为有意义的最小单元 token 的过程）极其复杂，且高度依赖于具体的语言和业务场景。在单一庞大的扩展中同时支持多种语言的独特规则、自定义词典、词干提取（stemming）、停用词（stop words）以及不同的分词策略，正变得越来越笨重。

通过将分词器拆分到遵循宽松 Apache 许可证的独立项目（pg_tokenizer.rs）中，我们实现了以下几项核心优势：

1. 模块化与灵活性：开发者现在可以独立于核心 BM25 排序逻辑来使用或定制分词器。

2. 更易于社区贡献：pg_tokenizer.rs 职责更加聚焦，使社区能够更轻松地贡献新语言支持、分词技术或自定义过滤器。

3. 更快的迭代速度：我们现在可以更快速地开发和发布分词器改进，而无需等待完整的 VectorChord-BM25 发布周期。

4. 更强大的定制能力：无论处理何种语言，用户都能对排序前的文本处理流程获得更精细的控制权。

分词功能有哪些新特性（得益于 pg_tokenizer.rs）

这一全新架构在 v0.2 中解锁了多项强大特性：

• 更广泛的语言支持：通过专用分词器（如针对中文的 Jieba 和针对日文的 Lindera），以及在海量多语言数据集上训练的强大多语言大模型分词器（如 Gemma2 和 LLMLingua2），直接满足多样化的语言处理需求。

• 更丰富的分词特性：现在您可以对分词流水线进行更细粒度的控制：

  • 自定义停用词（Custom Stop Words）：定义您自己的停用词列表，在索引和搜索期间忽略这些词。

  • 自定义词干提取器（Custom Stemmers）：应用多种受支持语言的词干提取规则，甚至定义自定义规则。

  • 自定义同义词（Custom Synonyms）：定义同义词列表，将不同的词视为等价词（例如 "postgres"、"postgresql"、"pgsql"）。

  • 语言专属选项（Language-Specific Options）：在需要时利用特定分词器（如 Lindera 或 Jieba）内部提供的细粒度控制选项。

代码示例！

下面来看看使用全新的分词器特性有多么简单。

1. 使用预训练的多语言 LLM 分词器（LLMLingua2）

基于大语言模型（LLM）的分词器非常适合处理包含多种不同语言的文本。

-- Enable the extensions (if not already done)
CREATE EXTENSION IF NOT EXISTS vchord_bm25;
CREATE EXTENSION IF NOT EXISTS pg_tokenizer;

-- Update search_path for the first time
ALTER SYSTEM SET search_path TO "$user", public, tokenizer_catalog, bm25_catalog;
SELECT pg_reload_conf();

-- Create a tokenizer configuration using the LLMLingua2 model
SELECT create_tokenizer('llm_tokenizer', $$
model = "llmlingua2"
$$);

-- Tokenize some English text
SELECT tokenize('PostgreSQL is a powerful, open source database.', 'llm_tokenizer');
-- Output: {2795,7134,158897,83,10,113138,4,9803,31344,63399,5} -- Example token IDs

-- Tokenize some Spanish text (LLMLingua2 handles multiple languages)
SELECT tokenize('PostgreSQL es una potente base de datos de código abierto.', 'llm_tokenizer');
-- Output: {2795,7134,158897,198,220,105889,3647,8,13084,8,55845,118754,5} -- Example token IDs

-- Integrate with a table
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    passage TEXT,
    embedding bm25vector
);

INSERT INTO documents (passage) VALUES ('PostgreSQL is a powerful, open source database.');

UPDATE documents
SET embedding = tokenize(passage, 'llm_tokenizer')
WHERE id = 1; -- Or process the whole table

2. 创建带过滤器的自定义分词器（示例：英文）

本示例定义了一条自定义流水线，包括转小写、Unicode 规范化、跳过非字母数字词元、使用 NLTK 英文停用词表以及 Porter2 词干提取器。随后，它会自动训练模型并设置触发器，以便在插入或更新时自动对文本进行分词。

CREATE TABLE articles (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding bm25vector
);

-- Define a custom text analysis pipeline
SELECT create_text_analyzer('english_analyzer', $$
pre_tokenizer = "unicode_segmentation"  # Basic word splitting
[[character_filters]]
to_lowercase = {}                       # Lowercase everything
[[character_filters]]
unicode_normalization = "nfkd"          # Normalize Unicode
[[token_filters]]
skip_non_alphanumeric = {}              # Remove punctuation-only tokens
[[token_filters]]
stopwords = "nltk_english"              # Use built-in English stopwords
[[token_filters]]
stemmer = "english_porter2"             # Apply Porter2 stemming
$$);

-- Create tokenizer, custom model based on 'articles.content', and trigger
SELECT create_custom_model_tokenizer_and_trigger(
    tokenizer_name => 'custom_english_tokenizer',
    model_name => 'article_model',
    text_analyzer_name => 'english_analyzer',
    table_name => 'articles',
    source_column => 'content',
    target_column => 'embedding'
);

-- Now, inserts automatically generate tokens
INSERT INTO articles (content) VALUES
('VectorChord-BM25 provides advanced ranking features for PostgreSQL users.');

SELECT embedding FROM articles WHERE id = 1;
-- Output: {1:1, 2:1, 3:1, 4:1, 5:1, 6:1, 7:1, 8:1}
-- Bm25vector based on the custom model and pipeline

3. 使用 Jieba 处理中文文本

CREATE TABLE chinese_docs (
    id SERIAL PRIMARY KEY,
    passage TEXT,
    embedding bm25vector
);

-- Define a text analyzer using the Jieba pre-tokenizer
SELECT create_text_analyzer('jieba_analyzer', $$
[pre_tokenizer.jieba]
# Optional Jieba configurations can go here
$$);

-- Create tokenizer, custom model, and trigger for Chinese text
SELECT create_custom_model_tokenizer_and_trigger(
    tokenizer_name => 'chinese_tokenizer',
    model_name => 'chinese_model',
    text_analyzer_name => 'jieba_analyzer',
    table_name => 'chinese_docs',
    source_column => 'passage',
    target_column => 'embedding'
);

-- Insert Chinese text
INSERT INTO chinese_docs (passage) VALUES
('红海早过了，船在印度洋面上开驶着。'); -- Example sentence

SELECT embedding FROM chinese_docs WHERE id = 1;
-- Output: {1:1, 2:1, 3:1, 4:1, 5:1, 6:1, 7:1, 8:1, 9:1, 10:1, 11:1, 12:1}
-- Bm25vector based on Jieba segmentation

（有关包括自定义停用词和同义词在内的完整示例，请参阅 pg_tokenizer.rs 文档。）

深入理解分词器配置

全新的分词器系统围绕两个核心概念构建：

1. 文本分析器（Text Analyzer）：定义如何将原始文本处理为词元序列。它由以下部分组成：

   • character_filters（字符过滤器）：在切分之前修改文本（例如转小写、Unicode 规范化）。

   • pre_tokenizer（预分词器）：将文本切分为初始词元（例如基于 Unicode 规则、Jieba、Lindera）。

   • token_filters（词元过滤器）：在切分之后修改或过滤词元（例如移除停用词、词干提取、同义词替换）。

2. 模型（Model）：定义从处理后的词元到 BM25 最终使用的整数词元 ID 的映射关系。模型可以分为：

   • pre-trained（预训练模型）：使用现成的词表和规则（如 bert-base-uncased、llmlingua2），非常适合通用场景及多语言使用。

   • custom（自定义模型）：根据您自己的数据动态构建词表，专门针对您的语料库和语言量身定制。

您可以在 SQL 中以字符串形式传入简洁的 TOML 配置格式，将这些组件分开定义，也可以在创建分词器时直接内联定义。

立即上手 VectorChord-BM25 0.2！

本次发布大幅提升了 VectorChord-BM25 的灵活性与功能深度，特别是对于需要处理多语言或对文本处理有细粒度控制需求的用户。

• GitHub 仓库：https://github.com/tensorchord/VectorChord-bm25

• 分词器文档：https://vchord.pgsty.com/bm25/tokenizer/

我们诚邀您试用 0.2 版本并探索全新的分词能力。您的反馈至关重要——欢迎在我们的 GitHub 仓库中报告任何问题或提出功能建议。

立即使用 VectorChord-BM25 0.2 与 pg_tokenizer.rs，以强大的多语言灵活性升级您的 PostgreSQL 全文检索体验！

13 - 基于 Postgres 原生 BM25 与 VectorChord 的混合搜索

在 RAG（检索增强生成）时代，如何从海量数据集中高效检索相关数据，对企业和开发者而言至关重要。传统的基于关键词的检索方法（例如使用 BM25 作为评分机制的方法）擅长根据词频和精确关键词匹配对文档进行排序，因此对于结构化查询和关键词密集型内容非常有效。然而，它们在理解同义词、上下文细微差别和语义意图方面往往力不从心。相反，基于向量的检索能够捕捉深层语义，在多样化查询上具备更好的泛化能力，但有时会在精确关键词匹配上牺牲准确性。混合搜索（Hybrid Search）通过将 BM25 的精确性与向量搜索的上下文理解能力相结合，弥合了这一差距，从而提供更快、更准确且具备语义感知的检索结果。

本文将探讨如何使用 VectorChord-bm25 进行关键词检索、使用 VectorChord 进行语义搜索，在 Postgres 中实现混合搜索。借助 VectorChord-bm25 基于 Block-WeakAnd 算法的 BM25 排序，以及 VectorChord 先进的向量相似度检索能力，你可以构建一个将关键词精确性与语义理解无缝融合的强大搜索系统。无论你是在构建推荐引擎、文档检索系统还是企业级搜索解决方案，本指南都将带你一步步释放混合搜索的全部潜力。

所有相关的基准测试代码均可在这里找到。

混合搜索解析

混合搜索将向量搜索和关键词搜索的结果加以合并。向量搜索基于查询与文档之间的语义相似度，而关键词搜索则依赖 BM25 排序算法。不过需要注意的是，BM25 本身只负责对文档进行打分，而广义的关键词搜索流程还包括分词（tokenization）、索引构建（indexing） 和查询解析（query parsing） 等步骤。混合搜索会使用重排序器（reranker）或对两种方法的结果进行融合（fusion）。常见的融合方法包括针对多路召回策略的 RRF（Reciprocal Rank Fusion，倒数排名融合）或加权评分；基于模型的重排序则包括交叉编码器（Cross-Encoder）模型（如 bge-reranker-v2-m3）以及多向量表征模型 ColBERT。

%[https://github.com/tensorchord/VectorChord]

什么是 VectorChord？

你可能已经熟悉 pgvector——一个开源的 Postgres 向量相似度搜索扩展。然而，面对大规模或性能敏感的场景，往往需要更先进的向量搜索解决方案，VectorChord 正是一个绝佳选择。

欢迎阅读博客文章《VectorChord：在 PostgreSQL 中以 $1 存储 40 万个向量》，深入了解它的设计初衷与架构。

%[https://github.com/tensorchord/VectorChord-bm25]

什么是 VectorChord-BM25

VectorChord-BM25 是一个用于关键词搜索的 PostgreSQL 扩展。它不仅实现了 BM25 排序算法，还内置了分词器和用于提升检索速度的 Block-WeakAnd 索引。

什么是 BM25？

BM25（Best Matching 25）是信息检索中常用的一种概率排序函数，用于评估文档与查询的匹配程度。它基于词频（TF）和逆文档频率（IDF）计算相关性得分，同时引入了文档长度归一化。该公式确保在文档内部频繁出现的词项（TF）以及在整个语料库中罕见的词项（IDF）获得合理的权重，从而提升搜索的准确性和相关性。IDF 衡量一个词在整个文档集合中出现的频率，出现次数越少，其权重越高；TF 则表示查询中的特定词项在给定文档中出现的频率，TF 越高，说明查询与该文档的相关性越强。

为什么需要 Postgres 原生的 BM25 排序实现？

在我们此前的博客文章《VectorChord-BM25：用 BM25 排序革新 PostgreSQL 搜索——比 Elasticsearch 快 3 倍》中，我的同事 Allen 已经给出了详尽而充分的阐述，欢迎参考。

教程：使用 VectorChord-BM25 与 VectorChord 实现混合搜索

在本教程中，我们将一步步指导你在 PostgreSQL 中使用 VectorChord-BM25 和 VectorChord 实现混合搜索。我们将涵盖以下内容：

• 使用 VectorChord 进行语义搜索

• 使用 VectorChord-BM25 进行关键词搜索

• 重排序（Rerank）

前置条件

1. 安装了 VectorChord-BM25 和 VectorChord 的 Postgres

如果你想快速复现本教程，可以使用 tensorchord/vchord-suite 镜像来运行 TensorChord 提供的多个扩展。

运行以下命令即可启动包含 VectorChord-BM25 和 VectorChord 的 Postgres 容器：

docker run   \           
  --name vchord-suite  \
  -e POSTGRES_PASSWORD=postgres  \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg17-latest

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;
CREATE EXTENSION IF NOT EXISTS pg_tokenizer CASCADE;
CREATE EXTENSION IF NOT EXISTS vchord_bm25 CASCADE;
\dx
pg_tokenizer | 0.1.0   | tokenizer_catalog | pg_tokenizer
vchord       | 0.3.0   | public            | vchord: Vector database plugin for Postgres, written in Rust, specifically designed for LLM
vchord_bm25  | 0.2.0   | bm25_catalog      | vchord_bm25: A postgresql extension for bm25 ranking algorithm
vector       | 0.8.0   | public            | vector data type and ivfflat and hnsw access methods

2. 准备嵌入模型与数据

在嵌入生成方面，我们可以使用预训练嵌入模型（如 BGE-M3）为文档生成向量嵌入。BGE-M3 是一款高质量的嵌入模型，以多功能、多语言和多粒度能力著称。

在评估验证方面，我们使用 BEIR 数据集——一个异构的信息检索基准测试集。它非常易于使用，支持在 15 个以上的多样化 IR 数据集上评估模型表现。

首先，你需要将数据加载到 PostgreSQL 中，并生成文档嵌入写入表中：

with self.conn.cursor() as cursor:
    cursor.execute(
        f"CREATE TABLE IF NOT EXISTS {self.dataset}_corpus (id TEXT, text TEXT, emb vector({self.vector_dim}), bm25 bm25vector);"
    )

    for did, doc in tqdm(zip(doc_ids, docs), desc="insert corpus"):
        emb = self.sentence_encoder.encode_doc(doc)
        cursor.execute(
            f"INSERT INTO {self.dataset}_corpus (id, text, emb) VALUES (%s, %s, %s)",
            (did, doc, emb),
        )