参考手册与基准测试

• 1: SQL 参考手册
• 2: GUC 与索引参数
• 3: 性能与精度基准测试
• 4: 迁移到 0.4.0
• 5: 版本历史与 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）

postgresql.conf、ALTER DATABASE、ALTER ROLE 或客户端启动选项中的设置也会覆盖索引参数。RESET 会恢复这些配置默认值；只有 GUC 来源恢复为内置默认值时，才会回退到索引参数。

索引存储参数（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 - 迁移到 0.4.0

当前 pgsty/vchord_bm25 源码面向 0.4.0（尚未发布），使用 PostgreSQL 原生 tsvector 和新的索引存储引擎。历史 0.3.x 软件包与套件镜像使用 bm25vector，两者的 API 与索引格式均不兼容。

当前构建使用从 Rust 动态库生成的 vchord_bm25--0.4.0.sql。打包时会比对检入的 SQL 与编译后的接口，遇到不一致即报错。Git 中保留的旧版安装 SQL 对应旧版动态库；把控制文件版本改成 0.3.0 并不能让新引擎兼容旧接口。

安装与查询

使用 PG_CONFIG=/path/to/pg_config make build 与 PG_CONFIG=/path/to/pg_config make install 编译安装当前源码。将 vchord_bm25 加入 shared_preload_libraries 并重启 PostgreSQL。标准文本检索无需外部分词器：

CREATE EXTENSION vchord_bm25;
CREATE TABLE documents (
    id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    passage text NOT NULL,
    vector tsvector GENERATED ALWAYS AS (to_tsvector('english', passage)) STORED
);
INSERT INTO documents (passage) VALUES
    ('PostgreSQL supports full text search.'),
    ('BM25 ranks documents by relevance.');
CREATE INDEX documents_bm25 ON documents USING bm25 (vector bm25_ops)
WITH (limit = 100);

SELECT id, vector <&> to_bm25query(to_tsvector('english', 'PostgreSQL'), 'documents_bm25') AS rank
FROM documents ORDER BY rank LIMIT 10;

索引通过文档位置计算词频，strip(tsvector) 与 array_to_tsvector 无法提供这些信息。文档与查询应使用相同的分析器。整数词元 ID 不等于词素，因此没有自动的 bm25vector 到 tsvector 转换。

显式执行 SET "bm25.limit" = 100 会覆盖索引上限；RESET "bm25.limit" 才会恢复索引设置。显式零值会使扫描报错，不表示使用索引默认值或不限结果数。两层默认值均为零，因此必须设置一个正值。bm25.prefilter 同样根据设置来源决定优先级，显式 false 也会覆盖索引参数。SQL LIMIT 不会设置这些 GUC。

postgresql.conf、ALTER DATABASE、ALTER ROLE 或客户端启动选项中的设置也会覆盖索引参数。RESET 会恢复这些配置默认值；只有 GUC 来源恢复为内置默认值时，才会回退到索引参数。

模式访问权限

DBA 可以把扩展安装到为应用选择的模式中：

CREATE SCHEMA search;
CREATE EXTENSION vchord_bm25 WITH SCHEMA search;
GRANT USAGE ON SCHEMA search TO app_user;
ALTER ROLE app_user SET search_path = public, search;

这是安装到 public 的替代方案，不要在同一数据库执行两次安装。表的访问权限需要单独授予。PostgreSQL 默认向 PUBLIC 授予函数执行权限；若部署环境撤销了该默认授权，还需显式授予所需函数的权限。即使 search 不在 search_path 中，仍可通过 search.to_bm25query(...) 调用构造函数，迁移扩展模式后也如此。

迁移已有数据

从 0.3.0 执行 ALTER EXTENSION vchord_bm25 UPDATE TO '0.4.0' 会在修改对象前主动报错。该脚本不会重写旧索引，也不会删除依赖扩展的应用数据。

1. 保留旧数据库与旧动态库。盘点 bm25vector 列、索引、视图、函数和分词触发器；在旧类型仍可读取时导出原始文本与应用数据。
2. 在另一套 PostgreSQL 安装与新数据库中安装 0.4.0。同一套 PostgreSQL 下的数据库共享扩展动态库，不能在仍有数据库使用 0.3.x 时直接替换文件。
3. 恢复原始文本，生成 tsvector，重建所有 BM25 索引，并设置正值候选数上限。复制旧索引文件或对 bm25vector 列执行普通 REINDEX 均不能完成 API 迁移。
4. 更新构造函数参数顺序、数据类型、GUC 名称与分词触发器。比较排序质量与查询结果后再切换应用。

站点继续保留 0.3.x 的 pg_tokenizer 整数数组工作流。对于 0.4.0，在所部署的分词器明确支持兼容的 tsvector 输出前，请使用 to_tsvector。

5 - 版本历史与 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]$）。