参考手册与基准测试

• 1: SQL 参考手册
• 2: GUC 与索引参数
• 3: 性能与精度基准测试
• 4: 版本历史与 API 演进

1 - SQL 参考手册

vchord_bm25 数据类型

bm25vector 字面量语法（v0.1 – v0.3）

-- 空 bm25vector
SELECT '{}'::bm25vector;

-- 显式指定 token_id:frequency 键值对
SELECT '{1:1, 2:3, 10:2}'::bm25vector;

-- 从 int[] 隐式转换（自动将重复的词元 ID 聚合为词频计数）
SELECT ARRAY[1, 2, 2, 2, 10, 10]::bm25vector;
-- 输出：{1:1, 2:3, 10:2}

vchord_bm25 操作符

vchord_bm25 函数

vchord_bm25 访问方法与操作符类

pg_tokenizer 函数（tokenizer_catalog）

所有 pg_tokenizer 函数均位于 tokenizer_catalog 模式中：

分词器管理与执行

文本分析器管理

模型管理

词典与预加载管理

内部触发器与辅助函数（tokenizer_catalog）

pg_tokenizer 元数据表（tokenizer_catalog）

pg_tokenizer TOML 配置参数参考

分词器配置项（create_tokenizer）

文本分析器配置项（create_text_analyzer）

自定义模型配置项（create_custom_model）

2 - GUC 与索引参数

稳定发布版（v0.1.0 – v0.3.0）：bm25_catalog.* GUC 参数

在 v0.1.0 至 v0.3.0 版本中，所有会话级 GUC 参数均使用 bm25_catalog. 前缀，任何普通用户均可在会话或事务级别修改（GucContext::Userset）：

配置示例（v0.1 – v0.3）

-- 为深度分页（例如 LIMIT 500）调大 Top-K 候选窗口
SET bm25_catalog.bm25_limit = 500;

-- 强制对索引中的所有倒排项执行全量暴力扫描
SET bm25_catalog.bm25_limit = -1;

-- 为包含高选择性 WHERE 子句的查询启用预过滤
SET bm25_catalog.enable_prefilter = true;

-- 禁用索引扫描，用于对比顺序扫描基线性能
SET bm25_catalog.enable_index = false;

新一代 main 分支：bm25.* GUC 参数与索引存储参数

在 main 分支重构版本中，会话级 GUC 参数改用 bm25. 前缀，并与每个索引独立的存储参数（WITH (...)）配合工作：

会话级 GUC 参数（main）

索引存储参数（main 中的 WITH (...)）

3 - 性能与精度基准测试

吞吐量基准测试（QPS 对比 Elasticsearch、Lucene、ParadeDB、PG GIN）

凭借结合 128 文档差分位打包块与单字节 Fieldnorm 量化的 Block-WeakAnd 算法实现，VectorChord-BM25 在 Top-10 排序查询上的 QPS 吞吐量最高可达基于 Tantivy 的 PostgreSQL 扩展（ParadeDB / pg_search）的 3 倍，并比 PostgreSQL 原生 GIN 索引高出一个数量级：

为什么 vchord_bm25 能实现极高的 QPS

1. 零跨引擎序列化开销：不同于外部数据包装器（FDW）或外挂 Tantivy/Lucene 桥接方案，vchord_bm25 将段数据直接存储在 PostgreSQL 缓冲池页面（PostgresRelation）中，彻底消除了跨引擎元组编组（Marshaling）开销。
2. 激进的块级上界剪枝（Block-Max Pruning）：在多词查询场景下，一旦 Top-10 阈值趋于稳定，Block-WeakAnd 即可直接跳过 80%–95% 以上的 128 文档倒排块，无需对其进行解压。
3. 256 项预计算 BM25 查找表：将文档长度量化为单字节 fieldnorm，使原本昂贵的逐文档浮点运算简化为单次数组查表。

检索精度基准测试（BEIR 与 LoTTE 上的 NDCG@10）

下表（摘自我们的 BEIR / LoTTE 混合检索与 ColBERT 重排序评测报告）对比了以下三种方案的检索精度（NDCG@10）：

• PostgreSQL vchord 稠密向量检索（Vector）
• PostgreSQL vchord_bm25 词法检索（BM25）
• 混合检索（vchord + vchord_bm25 配合 ColBERT 重排序）

4 - 版本历史与 API 演进

本页记录 vchord_bm25（pgsty/vchord_bm25 / supervc-stack/VectorChord-bm25）的版本发布历史与 SQL 模式演进。

版本演进总览矩阵

各版本升级变更详解

v0.3.0（sql/vchord_bm25--0.2.2--0.3.0.sql）

• 新增页面诊断函数：

  CREATE FUNCTION bm25_page_inspect(index regclass, blkno INT) RETURNS TEXT;

• 在 main / 0.3.x 后期版本中新增了直接接受 int[] 的便捷重载 to_bm25query(regclass, int[])。

v0.2.2（sql/vchord_bm25--0.2.1--0.2.2.sql）

• 在 Block-WeakAnd 中新增预过滤支持（bm25_catalog.enable_prefilter GUC 参数，在 0.3.0 中默认启用）。
• 改进索引扫描期间的 MVCC 可见性检查，防止死元组（Dead Tuples）或被过滤元组污染 Top-K 剪枝阈值。

v0.2.0（sql/vchord_bm25--0.1.1--0.2.0.sql）

• 为 bm25vector 新增 = 与 <> 操作符。
• 新增从 int[] 到 bm25vector 的隐式类型转换（_vchord_bm25_cast_array_to_bm25vector），允许将 tokenize(text, name) 的输出（INT[]）直接赋值给 bm25vector 列或传入任何接受 bm25vector 的位置。

v0.1.1（sql/vchord_bm25--0.1.0--0.1.1.sql）

• 将原本内置的 create_tokenizer / tokenize 函数抽离为独立的 pg_tokenizer 扩展（tokenizer_catalog），从而支持丰富的文本分析器、Snowball 词干提取、停用词、同义词、HuggingFace 模型、jieba 中文分词与 lindera 日文分词。
• 简化 to_bm25query(index_oid regclass, query_vector bm25vector) 签名，直接接受 bm25vector 参数。

新一代架构重写（main 分支）

• 用 PostgreSQL 原生 tsvector 替代自定义 bm25vector 类型（CREATE OPERATOR CLASS bm25_ops FOR TYPE tsvector USING bm25），允许用户直接使用 USING bm25 为 to_tsvector(...) 列建立索引。
• 新增基于外部归并排序（External Merge Sort）的并行索引构建（bm25_parallel_build_main），保证恒定的维护内存消耗。
• 支持通过 WITH (options = $$ k1 = 1.2, b = 0.75 $$) 配置索引级 BM25 超参数（$k_1 \in [1.2, 2.0]$，$b \in [0.0, 1.0]$）。