vchord 文档

• 1: 快速入门
  • 1.1: 概览
  • 1.2: 安装指南
  • 1.3: Vchord 家族套件
• 2: 使用指南
  • 2.1: 索引构建
  • 2.2: 多向量检索
  • 2.3: 图索引
  • 2.4: 量化类型
  • 2.5: 相似度过滤
  • 2.6: PostgreSQL 调优
  • 2.7: 监控
  • 2.8: 回退参数
  • 2.9: 评估召回率
  • 2.10: 预热
  • 2.11: 预过滤
  • 2.12: 预取
  • 2.13: 表内重排序
  • 2.14: 分区调优
  • 2.15: 外部构建
• 3: 应用案例
  • 3.1: 基于 Postgres 原生 BM25 与 VectorChord 的混合检索
  • 3.2: 在 PostgreSQL 中使用 ColBERT 重排序为向量检索加速
  • 3.3: 超越纯文本：使用 Modal 与 VectorChord 在 PostgreSQL 中实现免 OCR RAG
• 4: 基准测试
  • 4.1: 价格基准测试
  • 4.2: 性能基准测试
  • 4.3: 与 pgvector 的基准测试对比
  • 4.4: 与 Elasticsearch 的基准测试对比
  • 4.5: 与 pgvectorscale 的基准测试对比
• 5: 运维管理
  • 5.1: 迁移指南
  • 5.2: 可扩展性
  • 5.3: Kubernetes
• 6: 客户案例
  • 6.1: 驾驭 30 亿 PostgreSQL 向量：Earth Genome 的 Earth Index 与 VectorChord 携手守护地球

1 - 快速入门

1.1 - 概览

vchord 是一款专为可扩展、高性能且磁盘高效的向量相似性检索而设计的 PostgreSQL 扩展。

借助 vchord，您仅需 1 美元即可存储 400,000 个向量，从而显著节省成本：在同等价格下，可存储的向量数量是 Pinecone 优化型存储的 6 倍，是 pgvector/pgvecto.rs 的 26 倍¹。欲了解更多详情，请参阅我们的发布博文。

核心特性

相较于 pgvecto.rs 和 pgvector，vchord 带来了显著的增强：

⚡ 性能大幅提升：与 pgvector 的 HNSW 实现相比，经过全面优化的操作可提供最高 5 倍的查询加速、16 倍的写入吞吐量提升，以及 16 倍的索引构建提速¹。

💰 高性价比向量检索：仅需 32GB 内存即可查询 1 亿条 768 维向量，在保持 Top-10 召回率达 95% 的同时实现 35ms 的 P50 延迟，助您在保障高质量检索的同时大幅降低基础设施成本。

🔌 无缝集成：完全兼容 pgvector 的数据类型与语法，并提供开箱即用的最优默认配置——无需手动调优参数。只需直接引入 vchord，即可获得性能跃升。

🔧 加速索引构建：支持利用 IVF 在外部（例如 GPU 上）构建索引以加快 KMeans 聚类速度，并结合 RaBitQ² 压缩算法高效存储向量，同时通过自适应重排序（reranking）确保检索质量。

📏 超长向量支持：支持存储和检索最高达 60,000³ 维的向量，让您轻松使用 text-embedding-3-large 等顶尖高维模型。

🌐 按需灵活扩展：基于水平扩展架构，针对 500 万或 1 亿条 768 维向量的查询可轻松扩展至 10,000+ QPS（Top-10 召回率达 90%），且具备极具竞争力的成本优势⁴。

快速开始

对于新用户，我们推荐使用 Docker 镜像快速上手。如果您倾向于不使用 Docker，请参阅安装指南了解其他安装方式。

docker run \
  --name vectorchord-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d tensorchord/vchord-postgres:pg18-v1.1.1

除了包含 VectorChord 扩展的基础镜像外，我们还提供了全合一镜像 tensorchord/vchord-suite:pg18-latest。该综合镜像包含了所有官方 TensorChord 扩展。开发者应根据支持矩阵选择与所需扩展版本兼容的镜像标签。

随后，您可以使用 psql 命令行工具连接到数据库。默认用户名为 postgres，默认密码为 mysecretpassword。

psql -h localhost -p 5432 -U postgres

现在，您可以开始体验 VectorChord 了！

VectorChord 依赖于 pgvector（包括其向量数据表示形式）。由于您可以直接使用它们，您的应用程序可以毫无痛点地轻松完成迁移！

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

与 pgvector 类似，您可以创建一张包含向量列的表，并向其中插入一些数据。

CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));
INSERT INTO items (embedding) SELECT ARRAY[random(), random(), random()]::real[] FROM generate_series(1, 1000);

借助 VectorChord，您可以创建 vchordrq 索引：

CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops);

然后使用 SELECT ... ORDER BY ... LIMIT ... 执行向量检索：

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

欲了解更多用法，请阅读：

• 构建索引
• 多向量检索
• 图索引
• 量化类型
• 相似度过滤
• PostgreSQL 调优
• 监控
• 回退参数
• 评估召回率
• 索引预热
• 预过滤
• 预取优化
• 表内重排序
• 分区调优
• 外部构建

开源许可

vchord 采用 GNU Affero 通用公共许可证 v3.0（AGPL-3.0-only） 发布。我们欢迎任何商业合作或支持咨询，如有任何问题或需求，请发送邮件至 rh@vonng.com。

1.2 - 安装指南

VectorChord 已在以下操作系统上通过测试：

• Ubuntu (x86_64, aarch64)
• macOS (x86_64, aarch64)
• Windows (x86_64)
• Alpine Linux (x86_64, aarch64) ¹
• Debian (powerpc64le, s390x, riscv64) ²

如果您在上述任何操作系统上遇到问题，请提交 Bug 报告；如果您需要更多平台支持，欢迎提交功能请求。

Docker

VectorChord 镜像

体验 VectorChord 最简便的方式是直接运行开箱即用的 Docker 镜像。

1. 在 Docker 中启动 VectorChord 容器。

docker run \
  --name vchord-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d tensorchord/vchord-postgres:pg18-v1.1.1

2. 使用 psql 命令行工具连接到数据库。默认用户名为 postgres。

psql postgresql://postgres:mysecretpassword@localhost:5432/postgres

3. 执行以下 SQL 语句以确保扩展已启用。

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

VectorChord Suite 镜像

除了仅包含 VectorChord 扩展的基础镜像外，我们还提供了全合一镜像 tensorchord/vchord-suite:pg18-latest。该综合镜像包含了所有官方 TensorChord 扩展。开发者应根据支持矩阵选择与所需扩展版本兼容的镜像标签。

1. 在 Docker 中启动 VectorChord 容器。

docker run \
  --name vchord-suite \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg18-latest
  # 如果您希望使用 ghcr 镜像，可以将镜像名改为 `ghcr.io/tensorchord/vchord-suite:pg18-latest`。
  # 如果您希望使用特定版本，可以使用如 `pg17-20250815` 的标签，受支持的版本可在支持矩阵中查看。

其余步骤与上文一致。

VectorChord Scratch 镜像

我们提供了一个仅包含 VectorChord 相关文件的 scratch 镜像。您可以使用 Docker 的 COPY 指令将 VectorChord 安装到任何镜像中，例如：

FROM tensorchord/vchord-scratch:pg18-v1.1.1 AS vchord_scratch
FROM postgres:18-bookworm
RUN apt-get update && apt-get install -y postgresql-18-pgvector
COPY --from=vchord_scratch / /
CMD ["postgres", "-c" ,"shared_preload_libraries=vchord,vector"]

该镜像同样可以作为 CloudNativePG 的镜像卷扩展（Image Volume Extension）使用。另请参阅：

• Image Volume Extensions
• Kubernetes

源码编译

如果您尚未安装 PostgreSQL，请先安装 PostgreSQL。如果您尚未安装 pgvector，可以在执行第 3 步之前安装 pgvector。

1. 下载源码，并使用 make 进行编译和安装。

curl -fsSL https://github.com/tensorchord/VectorChord/archive/refs/tags/1.1.1.tar.gz | tar -xz
cd VectorChord-1.1.1
make build
make install # 或者 `sudo make install`

2. 修改 shared_preload_libraries 以加载该扩展来配置 PostgreSQL，然后重启 PostgreSQL 集群。

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vchord"'

3. 执行以下 SQL 语句以确保扩展已启用。

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

编译调优

VectorChord 会针对 SIMD 代码执行运行时 CPU 指令集分发（runtime CPU dispatch）。如果您希望编译器针对特定 CPU 对整个程序进行优化，可以指示编译器为该特定 CPU 生成代码。

RUSTFLAGS="-Ctarget-cpu=icelake" make build

若要查看当前目标平台（target triple）支持的所有有效 CPU 选项及默认 CPU，请运行：

rustc --print target-cpus

若要针对当前宿主机生成优化代码，请运行：

RUSTFLAGS="-Ctarget-cpu=native" make build

请注意，指定特定 target-cpu 生成的二进制文件与其他型号的 CPU 不兼容。

您也可以通过 Cargo 配置文件来完成此设置：

cd VectorChord-1.1.1
mkdir -p .cargo
touch .cargo/config.toml
echo 'build.rustflags = ["-Ctarget-cpu=icelake"]' >> ./cargo/config.toml

Debian

如果您尚未安装 PostgreSQL，请参照 https://www.postgresql.org/download/linux/debian/ 进行安装。如果您尚未安装 pgvector，可以在执行第 3 步之前通过 apt install postgresql-18-pgvector 进行安装。

1. 在发布页面下载 Debian 软件包，并通过 apt 进行安装。

wget https://github.com/tensorchord/VectorChord/releases/download/1.1.1/postgresql-18-vchord_1.1.1-1_$(dpkg --print-architecture).deb
sudo apt install ./postgresql-18-vchord_1.1.1-1_$(dpkg --print-architecture).deb

2. 修改 shared_preload_libraries 以加载该扩展来配置 PostgreSQL，然后重启 PostgreSQL 集群。

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vchord"'
sudo systemctl restart postgresql.service

3. 执行以下 SQL 语句以确保扩展已启用。

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

Ubuntu

如果您尚未安装 PostgreSQL，请参照 https://www.postgresql.org/download/linux/ubuntu/ 进行安装。如果您尚未安装 pgvector，可以在执行第 3 步之前通过 apt install postgresql-18-pgvector 进行安装。

1. 在发布页面下载 Debian 软件包，并通过 apt 进行安装。

wget https://github.com/tensorchord/VectorChord/releases/download/1.1.1/postgresql-18-vchord_1.1.1-1_$(dpkg --print-architecture).deb
sudo apt install ./postgresql-18-vchord_1.1.1-1_$(dpkg --print-architecture).deb

2. 修改 shared_preload_libraries 以加载该扩展来配置 PostgreSQL，然后重启 PostgreSQL 集群。

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vchord"'
sudo systemctl restart postgresql.service

3. 执行以下 SQL 语句以确保扩展已启用。

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

PGXN

如果您尚未安装 PostgreSQL，请先安装 PostgreSQL。如果您尚未安装 pgvector，可以在执行第 3 步之前通过 pgrxclient install vector 进行安装。

1. 使用以下命令从 PostgreSQL Extension Network (PGXN) 安装 VectorChord：

pgxnclient install vchord # 或者 `pgxnclient install vchord --sudo`

2. 修改 shared_preload_libraries 以加载该扩展来配置 PostgreSQL，然后重启 PostgreSQL 集群。

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vchord"'

3. 执行以下 SQL 语句以确保扩展已启用。

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

预编译二进制文件

如果您尚未安装 PostgreSQL，请先安装 PostgreSQL。如果您尚未安装 pgvector，可以在执行第 3 步之前安装 pgvector。

1. 在发布页面下载预编译二进制文件，并参考您所用发行版的文档重新打包，然后通过系统包管理器进行安装。虽然我们不建议这样做，但如果您需要，也可以直接将文件手动复制到系统目录中：

cp -r ./pkglibdir/. $(pg_config --pkglibdir)
cp -r ./sharedir/. $(pg_config --sharedir)

2. 修改 shared_preload_libraries 以加载该扩展来配置 PostgreSQL，然后重启 PostgreSQL 集群。

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vchord"'

3. 执行以下 SQL 语句以确保扩展已启用。

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

1.3 - Vchord 家族套件

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

许多现有方案采用了复杂的架构，分别使用不同的专用数据库来处理向量检索、关键词检索和主数据存储。这往往会导致数据同步困难、基础设施复杂度上升以及运维成本居高不下。

如果能够直接在您信赖的 PostgreSQL 数据库中构建强大且达到生产级标准的 RAG 系统，会怎样呢？

为此，我们推出了 Vchord 家族套件（Vchord Suite）——这是一套专为将高性能向量检索、原生 BM25 排序以及灵活的分词能力直接引入 Postgres 而设计的 PostgreSQL 扩展套件。下面让我们一起探索其核心组件，以及它们如何赋能下一代 RAG 解决方案。

什么是 Vchord 家族套件？

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

1. vchord (pgsty/vchord)： 核心向量检索引擎，专为在 PostgreSQL 内部实现可扩展、高性能且高磁盘效率的向量相似性检索而设计。

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

3. pg_tokenizer (pgsty/pg_tokenizer)： 提供高效全文检索所需的核心文本分词能力，支持对全文检索中的文本处理流程进行细粒度控制。

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

如何使用 Vchord 家族套件

您可以使用 tensorchord/vchord-suite Docker 镜像来运行由 TensorChord 提供的多个扩展。该镜像基于 Docker 官方 PostgreSQL 镜像构建，并内置了以下扩展：

• vchord
• pg_tokenizer
• vchord_bm25
• vector

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

# 如果您希望使用 ghcr 镜像，可以将镜像名改为 `ghcr.io/tensorchord/vchord-suite:pg18-latest`。
docker run \
  --name vchord-suite \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg18-latest

# 如果您希望使用特定版本，可以使用如 `pg17-20250414` 的标签，受支持的版本可在支持矩阵中查看。
docker run \
  --name vchord-suite \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg17-20250414

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.1   | tokenizer_catalog | pg_tokenizer
vchord       | 1.1.1   | public            | vchord: Vector database plugin for Postgres, written in Rust, specifically designed for LLM
vchord_bm25  | 0.3.0   | bm25_catalog      | vchord_bm25: A postgresql extension for bm25 ranking algorithm
vector       | 0.8.1   | public            | vector data type and ivfflat and hnsw access methods

Vchord 家族套件的应用场景

场景 1：基于原生 BM25 与 vchord 的强大混合检索

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

• 关键词检索（如 BM25）： 擅长精确匹配，能够找出包含确切关键词的文档，非常适合结构化查询和特定术语检索。然而，它在处理同义词、改写表述以及理解潜在语义或意图方面表现欠佳。（基于 vchord_bm25 与 pg_tokenizer 实现）。

• 向量检索： 能够捕捉深层语义信息及概念间的关联，即使查询中未出现完全一致的关键词，也能找到相关信息。但在面对要求精确匹配特定术语的查询时，其精度有时会略显不足。（基于 vchord 实现）。

解决方案：混合检索（Hybrid Search）。 通过在 PostgreSQL 内部结合这两种方法的优势，Vchord 家族套件完美弥补了这一鸿沟。您可以在查询中同时利用：

• vchord_bm25（由 pg_tokenizer 驱动）实现关键词精确匹配。

• vchord 实现深层语义理解。

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

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

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

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

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

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

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

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

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

2. vchord 的多向量检索能力： vchord 可以在 PostgreSQL 中高效地为每篇文档存储和检索多个向量——允许您存储代表文档不同维度的嵌入表示（例如文本内容与视觉布局）。

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

为什么在 PostgreSQL 中构建 RAG？

在 PostgreSQL 中使用 Vchord 家族套件具有显著优势：

• 数据统一： 将源数据、文本、元数据和向量嵌入统一保存在同一个数据库中。

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

• 复用现有基础设施： 充分利用您现有的 PostgreSQL 专业经验、工具链和运维体系。

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

• 丰富的生态系统： 无缝接入 PostgreSQL 生态系统中种类繁多的工具与特性。

总结

Vchord 家族套件将 PostgreSQL 打造成了一个强大且达到生产级标准的平台，用于构建高级 RAG 解决方案。通过集成高性能向量检索（vchord）、成熟的关键词排序（vchord_bm25）以及灵活的文本处理（pg_tokenizer），您可以直接在数据库内部实现混合检索与免 OCR 多模态检索等前沿技术。在 PostgreSQL 中借助 Vchord 简化系统架构、提升检索精度，并充分释放 RAG 的全部潜能。

相关博文

在近期的博文中，我们分享了多个实际应用案例，其中所有的 Docker 镜像均可以直接替换为 VectorChord Suite 镜像：

• 在 PostgreSQL 中使用 ColBERT 重排序为向量检索加速

• 基于 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/

2 - 使用指南

2.1 - 索引构建

VectorChord 的索引类型 vchordrq 会将向量划分为多个列表（list），并仅搜索距离查询向量最近的一部分列表。它兼具极快的构建速度与低内存占用，同时在性能上显著优于 hnsw 和 ivfflat。

我们首先创建一个名为 items 的表，其中包含一个类型为 vector(n) 的 embedding 列，然后向其中填充示例数据。

CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));
INSERT INTO items (embedding) SELECT ARRAY[random(), random(), random()]::real[] FROM generate_series(1, 1000);

要创建 vchordrq 索引，可以使用以下 SQL 语句：

CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops);

索引构建完成后，您就可以使用它执行向量搜索，检索距离目标向量最近的 $10$ 个近邻。

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

您还可以根据需要为向量搜索查询添加过滤条件。

SELECT * FROM items WHERE id % 7 <> 0 ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

调优

当表中的行数少于 $100,000$ 时，通常不需要设置索引选项。

CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops);

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

然而，随着行数的增长，对向量空间进行分区变得十分必要，这可以通过索引选项进行配置。options 使用 TOML（Tom’s Obvious Minimal Language） 格式的字符串指定。更多信息请参阅 #索引选项。

CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops) WITH (options = $$
[build.internal]
lists = [1000]
$$);

SET vchordrq.probes TO '10';
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

参数 lists 应根据表中的行数进行调优。下表提供了选择合适取值的指导建议。在执行查询时，请相应地选择 vchordrq.probes。

构建索引的过程包含两个步骤：首先对向量空间进行分区，然后将行插入到索引中。第一步（划分向量空间）可以使用多线程进行加速。

CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops) WITH (options = $$
[build.internal]
lists = [1000]
build_threads = 8
$$);

SET vchordrq.probes TO '10';
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

第二步（插入数据行）可以使用多进程并行执行。详情请参阅 PostgreSQL 调优。

对于大多数使用余弦相似度的数据集，启用 residual_quantization 和 build.internal.spherical_centroids 可以同时提升 QPS 和召回率（recall）。

CREATE INDEX ON items USING vchordrq (embedding vector_cosine_ops) WITH (options = $$
residual_quantization = true
[build.internal]
lists = [1000]
spherical_centroids = true
build_threads = 8
$$);

SET vchordrq.probes TO '10';
SELECT * FROM items ORDER BY embedding <=> '[3,1,2]' LIMIT 10;

为了提高构建速度，您可以选择将 build.pin 设置为 2，通过使用更多共享内存来加速构建过程。

CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops) WITH (options = $$
residual_quantization = true
build.pin = 2
[build.internal]
lists = [1000]
spherical_centroids = true
build_threads = 8
$$);

对于大表而言，时间和内存开销主要由分区阶段主导。有关进一步的调优方法，请参阅分区调优。

您也可以参考外部构建，将分区阶段卸载到其他机器上执行。

参考

操作符类（vchordrq）

下表列出了 vchordrq 支持的所有可用操作符类（Operator Classes）。

<->、<#> 和 <=> 是由 pgvector 定义的操作符。

<<->>、<<#>>、<<=>> 是由 VectorChord 定义的操作符。有关 <<->>、<<#>>、<<=>> 的更多信息，请参阅相似度过滤。

@# 是由 VectorChord 定义的操作符。有关 @# 的更多信息，请参阅多向量检索。

rabitq8、rabitq4 是由 VectorChord 定义的数据类型。有关 rabitq8、rabitq4 的更多信息，请参阅量化类型。

MaxSim 相关的操作符类自 0.3.0 版本起可用。rabitq8 和 rabitq4 相关的操作符类自 1.1.0 版本起可用。

索引选项（vchordrq）

residual_quantization

• 说明：该选项决定是否使用残差量化（Residual Quantization）。如果您不熟悉残差量化，可以阅读这篇博客了解更多信息。简而言之，残差量化是一种通过对向量的残差进行量化来提高向量搜索精度的技术。
• 类型：布尔值（boolean）
• 默认值：false
• 示例：
  • residual_quantization = false 表示不使用残差量化。
  • residual_quantization = true 表示使用残差量化。
• 注意：该选项不支持 rabitq8 和 rabitq4。

degree_of_parallelism

• 说明：该选项是一个指定并行度的提示值。在大多数情况下，您无需更改它。如果您使用的 CPU 拥有超过 32 个线程，并且希望在 PostgreSQL 中利用更多线程，可以将其设置为线程数量以获得更好的性能。
• 类型：整数（integer）
• 默认值：32
• 取值范围：[1, 256]
• 示例：
  • degree_of_parallelism = 32 提示索引最多可能有 32 个进程并发访问该索引。
  • degree_of_parallelism = 64 提示索引最多可能有 64 个进程并发访问该索引。

build.pin

• 说明：该选项决定构建索引时是否使用共享内存。对于大表，您可以选择启用此选项以加速构建过程。
• 类型：整数与布尔值的联合类型（union of integer and boolean）
• 默认值：
  • -1 since v1.0.0
  • false until v0.5.3
• 取值范围：
  • {-1, 0, 1, 2, false, true} since v1.0.0
  • {false, true} until v0.5.3
• 示例：
  • build.pin = 2 表示将索引的热数据部分全部缓存在内存中。
  • build.pin = 1 表示将索引热数据部分的一个子集缓存在内存中，消耗较少内存。
  • build.pin = 0 表示启用该功能但实际上不缓存任何内容。此选项仅用于调试目的。
  • build.pin = -1 表示禁用该功能。
  • build.pin = false 是 build.pin = -1 的旧版写法。
  • build.pin = true 是 build.pin = 1 的旧版写法。

默认构建选项

这是索引构建的默认设置。索引将不会进行分区。从语义上讲，build.default = {} 类似于 build.internal.lists = []。

内部构建选项（vchordrq）

build.internal.lists

• 说明：该选项决定向量空间分区的层次结构。
• 类型：整数列表（list of integers）
• 默认值：
  • [] since v0.3.0
  • [1000] until v0.2.2: implicit behavior is not ideal
• 示例：
  • build.internal.lists = [] 表示不对向量空间进行分区。
  • build.internal.lists = [4096] 表示将向量空间划分为 $4096$ 个单元（cell）。
  • build.internal.lists = [4096, 262144] 表示将向量空间划分为 $4096$ 个单元，并进一步将这些单元细分为 $262144$ 个更小的单元。
• 注意：索引会基于质心（centroid）将向量空间划分为多个 Voronoi 单元，通过迭代构建出一棵层次化的空间分区树。树中的每个叶子节点代表一个区域，并关联一个存储该区域内向量的列表。在插入时，向量会被放入其对应叶子节点的列表中。在查询时，索引通过排除叶子节点距离查询向量较远的列表来优化搜索，从而有效剪枝搜索空间。如果 lists 的长度为 $1$，则 lists 选项的值不应小于 $4\sqrt{N}$，其中 $N$ 是表中的向量数量。

build.internal.spherical_centroids

• 说明：该选项决定是否执行球面 K-means（spherical K-means）——即在每次迭代后对质心进行 L2 归一化，您可以参考此处的 spherical 选项。
• 类型：布尔值（boolean）
• 默认值：false
• 示例：
  • build.internal.spherical_centroids = false 表示不执行球面 K-means。
  • build.internal.spherical_centroids = true 表示执行球面 K-means。
• 注意：如果您的模型生成的嵌入向量使用余弦相似度作为度量标准，请将此项设置为 true。

build.internal.sampling_factor

• 说明：该选项决定 K-means 算法为每个聚类采样的向量数量。该值越高，构建速度越慢，构建时的内存消耗越大，但搜索性能越好。
• 类型：整数（integer）
• 取值范围：[0, 1024]
• 默认值：256
• 示例：
  • build.internal.sampling_factor = 256 表示 K-means 算法采样 $256 C$ 个向量，其中 $C$ 是 build.internal.lists 中的最大值。
  • build.internal.sampling_factor = 32 表示 K-means 算法采样 $32 C$ 个向量，其中 $C$ 是 build.internal.lists 中的最大值。这会将 K-means 的时间和内存开销降低至默认值 256 时的约 $\frac{1}{8}$。

build.internal.kmeans_iterations

• 说明：该选项决定 K-means 算法的迭代次数。该值越高，构建速度越慢。
• 类型：整数（integer）
• 取值范围：[0, 1024]
• 默认值：10
• 示例：
  • build.internal.kmeans_iterations = 10 表示 K-means 算法执行 $10$ 次迭代。
  • build.internal.kmeans_iterations = 100 表示 K-means 算法执行 $100$ 次迭代。

build.internal.build_threads

• 说明：该选项决定 K-means 算法使用的线程数。该值越高，构建速度越快，同时构建期间服务器的负载也越高。
• 类型：整数（integer）
• 取值范围：[1, 255]
• 默认值：1
• 示例：
  • build.internal.build_threads = 1 表示 K-means 算法使用 $1$ 个线程。
  • build.internal.build_threads = 4 表示 K-means 算法使用 $4$ 个线程。

build.internal.kmeans_algorithm

• 说明：该选项决定所使用的 K-means 算法。
• 类型：对象（object）
• 示例：
  • build.internal.kmeans_algorithm.lloyd = {}：使用劳埃德算法（Lloyd’s algorithm）。这是默认值。
  • build.internal.kmeans_algorithm.hierarchical = {}：使用层次聚类（hierarchical clustering）。与劳埃德算法相比，这种方法速度要快得多，但可能会导致一定的精度损失。

build.internal.kmeans_dimension

• 说明：该选项决定用于 K-means 输入和输出的维度。该特性通过重采样实现降维与升维，从而有效降低 K-means 的时间和内存消耗，但可能会导致一定的精度损失。
• 类型：整数与空值的联合类型（union of integer and null）
• 默认值：null
• 示例：
  • 如果未设置此选项，则禁用该特性。
  • build.internal.kmeans_dimension = 100 表示 K-means 将处理 $100$ 维的向量。对于原始维度为 $900$ 的向量，这会将 K-means 的时间和内存开销降低至未启用该特性时的约 $\frac{1}{9}$。

搜索参数（vchordrq）

vchordrq.enable_scan

• 说明：启用或禁用查询规划器对 vchordrq 索引扫描的使用。该参数仅用于测试目的。
• 类型：布尔值（boolean）
• 默认值：on
• 示例：
  • vchordrq.enable_scan = off 禁用查询规划器使用 vchordrq 索引扫描。
  • vchordrq.enable_scan = on 启用查询规划器使用 vchordrq 索引扫描。

vchordrq.probes

• 说明：GUC 参数 vchordrq.probes 控制如何利用向量空间分区来辅助查询剪枝。探测数（probes）越多，搜索结果越精确，但速度也越慢。
• 类型：整数列表（list of integers）
• 默认值：
  • since v0.3.0
  • 10 until v0.2.2: the default value was 10 before `lists` defaulted to empty
  • 该参数支持回退参数（fallback）。
• 示例：
  • SET vchordrq.probes = 1 表示仅使用 1 个探测分区。
  • SET vchordrq.probes = 10 表示使用 10 个探测分区。
• 注意：默认值为空列表。该选项的长度必须与 lists 的长度相匹配。
  • 如果 lists = []，则 probes 必须为 。
  • 如果 lists = [11, 22]，则 probes 可以是 2,4 或 4,8。其形状不能不匹配，例如不能是 、3、7,8,9 或 5,5,5,5。

vchordrq.epsilon

• 说明：即使经过剪枝，检索出的候选向量数量依然可观。索引采用 RaBitQ 算法将向量量化为位向量（bit vector），其内存占用仅为单精度浮点向量的 $\frac{1}{32}$。由于大部分计算基于整数完成，处理速度得以大幅提升。与传统量化算法不同，RaBitQ 不仅估算距离，还会估算距离的下界（lower bound）。索引会计算每个向量的距离下界，并根据查询需求动态调整需要重新计算精确距离的向量数量，从而在性能与精度之间取得平衡。GUC 参数 vchordrq.epsilon 控制距离下界估算的保守程度。该值越高，精度越高，但性能越差。对于大多数应用场景而言，默认值倾向于提供高于实际所需的精度，因此您可以尝试调低此参数以获得更好的性能。
• 类型：实数（real）
• 默认值：
  • 1.9
  • 该参数支持回退参数（fallback）。
• 取值范围：[0.0, 4.0]
• 示例：
  • SET vchordrq.epsilon = 0.1 表示您正在使用非常乐观的下界估算。这样设置是因为在您所需的精度下，您的数据集对下界估算不敏感。
  • SET vchordrq.epsilon = 4.0 表示您正在使用非常悲观的下界估算。这样设置是因为在您所需的精度下，您的数据集对下界估算较为敏感。

vchordrq.prewarm_dim

• 说明：GUC 参数 vchordrq.prewarm_dim 用于为指定维度预计算 RaBitQ 投影矩阵。这有助于降低 PostgreSQL 集群启动后首次查询的延迟。
• 类型：整数列表（list of integers）
• 默认值：64,128,256,384,512,768,1024,1536
• 示例：
  • ALTER SYSTEM SET vchordrq.prewarm_dim = '64,128' 表示将为维度 64 和 128 预计算投影矩阵。
• 注意：
  • 此设置需要重启数据库才能生效。
  • 自 v0.4.0 起，新算法已使该选项不再需要。

vchordrq.max_scan_tuples

• 说明：GUC 参数 vchordrq.max_scan_tuples 控制在一次向量搜索中最多可以扫描的元组（tuple）数量。在大多数情况下，您不需要设置此参数，因为 LIMIT 子句起到了类似的作用。然而，当存在 WHERE 子句时，LIMIT 子句在过滤之后生效，而此 GUC 参数在过滤之前生效。该参数旨在防止过滤选择率极低时出现性能下降。
• 类型：整数（integer）
• 默认值：-1
• 取值范围：[-1, 2147483647]
• 示例：
  • SET vchordrq.max_scan_tuples = 999 表示索引扫描最多返回 $999$ 个元组。
  • SET vchordrq.max_scan_tuples = -1 表示对元组数量没有限制。
• 注意：当设置为 -1 时，此参数不起作用。

2.2 - 多向量检索

多向量检索（Multi-Vector Retrieval）是检索增强生成（RAG）系统中使用的一项高级技术，通过为每个文档关联多个向量来增强文档检索效果。

与单向量检索不同，使用 MaxSim 操作符的多向量检索能够捕捉细粒度的语义关系。

关于如何构建端到端的多向量检索应用，请参阅我们的博客了解更多细节。

快速上手

晚期交互（Late interaction）模型会将文档和查询分别嵌入为向量数组，并通过名为 MaxSim 的操作符计算相似度。MaxSim 操作符的定义为 $\sum_i \max_j q_i \cdot d_j$，即对于查询向量数组中的每个向量，在文档向量数组中找到最接近的向量，计算它们的点积，最后将所有结果求和。

在 VectorChord 中，该操作符的符号为 @#。左操作数是文档向量数组，右操作数是查询向量数组。原始的 MaxSim 操作符基于相似度，而 VectorChord 中的操作符则基于距离：VectorChord 的实现通过对相似度得分取反，将其解释为一种距离度量。

要为向量数组构建索引，首先创建一个名为 items 的表，其中包含一个类型为 vector(n)[] 的 embeddings 列，然后向表中填充生成的数据。

CREATE TABLE items (id bigserial PRIMARY KEY, embeddings vector(3)[]);

INSERT INTO items (embeddings) 
SELECT
    ARRAY[
        ARRAY[random(), random(), random()]::vector,
        ARRAY[random(), random(), random()]::vector,
        ARRAY[random(), random(), random()]::vector
    ]
FROM generate_series(1, 1000);

与其他向量操作符一样，使用 MaxSim 操作符的查询也可以通过索引进行加速。

CREATE INDEX ON items USING vchordrq (embeddings vector_maxsim_ops);

随后，您便可以使用该索引执行向量搜索。

SELECT * FROM items
ORDER BY embeddings @# 
    ARRAY[
        '[3,1,2]'::vector,
        '[2,2,2]'::vector
    ] LIMIT 5;

参考

vchordg 不支持此功能。

操作符类

请参阅：

• 操作符类（vchordrq）。

搜索参数（vchordrq）

MaxSim 操作符的索引机制与其他向量操作符类似。当在向量数组列上构建索引时，数组中的每个向量都会被单独插入到索引数据结构中。在查询期间，索引会对查询数组中的每个向量分别执行一次独立的向量搜索。默认情况下，索引不会对结果进行重排序（rerank），而是使用 RaBitQ 的估算距离代替实际距离。随后，索引会将所有独立向量搜索的结果进行合并，以生成最终输出。

MaxSim 索引还使用了以下几个额外参数：

vchordrq.maxsim_refine

• 说明：GUC 参数 vchordrq.maxsim_refine 会让索引对结果进行重排序，用实际距离替换 RaBitQ 的估算距离，直到前 k 个（top-k）最近向量的距离全部重新计算完毕。
• 类型：整数（integer）
• 取值范围：[0, 2147483647]
• 默认值：
  • 0
  • 该参数支持回退参数（fallback）。
• 示例：
  • SET vchordrq.maxsim_refine = 0 表示索引始终使用 RaBitQ 的估算距离。
  • SET vchordrq.maxsim_refine = 1024 表示索引会对结果进行重排序，用实际距离替换 RaBitQ 的估算距离，直到前 1024 个最近向量的距离全部重新计算完毕。

vchordrq.maxsim_threshold

• 说明：GUC 参数 vchordrq.maxsim_threshold 启用对缺失值更激进的估算策略。启用该设置后，索引会在最底层列表中找到累积大小达到或超过 vchordrq.maxsim_threshold 的第一个聚类（cluster），并使用其与查询向量的距离来估算缺失值。
• 类型：整数（integer）
• 取值范围：[0, 2147483647]
• 默认值：
  • 0
  • 该参数支持回退参数（fallback）。
• 示例：
  • SET vchordrq.maxsim_threshold = 0 表示不启用更激进的估算策略。
  • SET vchordrq.maxsim_threshold = 1024 表示索引会在最底层列表中找到累积大小达到或超过 1024 的第一个聚类，并使用其与查询向量的距离来估算缺失值。

2.3 - 图索引

VectorChord 的索引类型 vchordg 是一种基于磁盘的图索引，具有低内存占用的特点。

我们首先创建一个名为 items 的表，其中包含一个类型为 vector(n) 的 embedding 列，然后向其中填充示例数据。

要创建 vchordg 索引，可以使用以下 SQL 语句：

CREATE INDEX ON items USING vchordg (embedding vector_l2_ops);

调优

在构建索引时，通常需要对两个选项进行调优：m 和 ef_construction。m 是每个顶点的最大邻居数，ef_construction 是插入期间包含最近邻的动态列表大小。

在搜索时，需要对 ef_search 进行调优。ef_search 是搜索期间包含最近邻的动态列表大小。

CREATE INDEX ON items USING vchordg (embedding vector_l2_ops) WITH (options = $$
m = 64
ef_construction = 128
$$);

SET vchordg.ef_search TO '128';
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

作为一种基于磁盘的索引，vchordg 通常只需要将量化后的向量保存在缓冲池（buffer pool）中即可维持良好性能。默认情况下，vchordg 会将一个 $D$ 维向量量化为 $2D$ 比特。设行数为 $N$，则该索引所需的总内存为 $2DN$ 比特。如果您的内存非常有限且正在使用超高维向量，可以考虑将向量量化为 $D$ 比特，此时索引所需的总内存为 $DN$ 比特。

CREATE INDEX ON items USING vchordg (embedding vector_l2_ops) WITH (options = $$
bits = 1
m = 64
ef_construction = 128
$$);

索引构建可以通过使用多进程来加速。详情请参阅 PostgreSQL 调优。

参考

操作符类（vchordg）

下表列出了 vchordg 支持的所有可用操作符类。

<<->>、<<#>>、<<=>> 是由 VectorChord 定义的操作符。有关 <<->>、<<#>>、<<=>> 的更多信息，请参阅相似度过滤。

rabitq8、rabitq4 是由 VectorChord 定义的数据类型。有关 rabitq8、rabitq4 的更多信息，请参阅量化类型。

前 6 个操作符类自 0.5.0 版本起可用，后 6 个操作符类自 1.1.0 版本起可用。

索引选项（vchordg）

bits

• 说明：RaBitQ 量化后比特数与维度的比值。bits = 2 可提供更好的召回率和 QPS，而 bits = 1 则消耗更少的内存。
• 类型：整数（integer）
• 默认值：2
• 示例：
  • bits = 2 表示将 $D$ 维向量量化为 $2D$ 比特。
  • bits = 1 表示将 $D$ 维向量量化为 $D$ 比特。

m

• 说明：每个顶点的最大邻居数。m 越大，性能越好，但存储需求也越高。m 对应于 HNSW 中的 $m_0$ 和 DiskANN 中的 $m$。
• 类型：整数（integer）
• 默认值：32
• 示例：
  • m = 32 表示每个顶点最多有 $32$ 个邻居。
  • m = 64 表示每个顶点最多有 $64$ 个邻居。

ef_construction

• 说明：插入期间包含最近邻的动态列表大小。ef_construction 越大，搜索性能越好，但插入速度越慢。ef_construction 对应于 HNSW 中的 $\text{ef}_\text{construction}$ 和 DiskANN 中的 $\text{ef}_C$。
• 类型：整数（integer）
• 默认值：64
• 示例：
  • ef_construction = 64 表示在插入期间包含最近邻的动态列表大小为 $64$。
  • ef_construction = 128 表示在插入期间包含最近邻的动态列表大小为 $128$。

alpha

• 说明：剪枝期间所选用的 alpha 值。alpha 对应于 DiskANN 中的 $\alpha$。该选项必须是一个升序列表，其中第一个元素为 1.0，最后一个元素小于 2.0。
• 类型：浮点数列表（list of floats）
• 默认值：[1.0, 1.2]
• 示例：
  • alpha = [1.0, 1.2] 等价于在 DiskANN 中设置 alpha = 1.2。
  • alpha = [1.0] 等价于 HNSW 中的默认剪枝策略。
• 注意：当距离度量为负内积时，此选项无效。

beam_construction

• 说明：插入期间使用的束宽（beam width）。束宽是指一次同时访问的顶点数量。由于从 SSD 随机读取少量扇区的时间与读取单个扇区几乎相同，较大的束宽可以有效减少对 SSD 的往返访问次数，从而获得更好的性能。但由于它会增加计算量，因此对于完全放入内存的索引而言反而不利。
• 类型：整数（integer）
• 默认值：1
• 示例：
  • beam_construction = 8 表示索引在插入期间一次同时访问 8 个顶点。
  • beam_construction = 1 表示索引在插入期间一次访问 1 个顶点。

搜索参数（vchordg）

vchordg.enable_scan

• 说明：启用或禁用查询规划器对 vchordg 索引扫描的使用。该参数仅用于测试目的。
• 类型：布尔值（boolean）
• 默认值：on
• 示例：
  • vchordg.enable_scan = off 禁用查询规划器使用 vchordg 索引扫描。
  • vchordg.enable_scan = on 启用查询规划器使用 vchordg 索引扫描。

vchordg.ef_search

• 说明：搜索期间包含最近邻的动态列表大小。vchordg.ef_search 越大，召回率越好，但 QPS 越低。vchordg.ef_search 对应于 HNSW 和 DiskANN 中的 $\text{ef}$。
• 类型：整数（integer）
• 默认值：
  • 64
  • 该参数支持回退参数（fallback）。
• 取值范围：[1, 65535]
• 示例：
  • SET vchordg.ef_search = 64 表示在搜索期间包含最近邻的动态列表大小为 $64$。
  • SET vchordg.ef_search = 128 表示在搜索期间包含最近邻的动态列表大小为 $128$。

vchordg.beam_search

• 说明：搜索期间使用的束宽（beam width）。束宽是指一次同时访问的顶点数量。由于从 SSD 随机读取少量扇区的时间与读取单个扇区几乎相同，较大的束宽可以有效减少对 SSD 的往返访问次数，从而获得更好的性能。但由于它会增加计算量，因此对于完全放入内存的索引而言反而不利。
• 类型：整数（integer）
• 默认值：1
• 取值范围：[1, 65535]
• 示例：
  • SET vchordg.beam_search = 8 表示索引在搜索期间一次同时访问 8 个顶点。
  • SET vchordg.beam_search = 1 表示索引在搜索期间一次访问 1 个顶点。

vchordg.max_scan_tuples

• 说明：GUC 参数 vchordg.max_scan_tuples 控制在一次向量搜索中最多可以扫描的元组数量。在大多数情况下，您不需要设置此参数，因为 LIMIT 子句起到了类似的作用。然而，当存在 WHERE 子句时，LIMIT 子句在过滤之后生效，而此 GUC 参数在过滤之前生效。该参数旨在防止过滤选择率极低时出现性能下降。
• 类型：整数（integer）
• 默认值：-1
• 取值范围：[-1, 2147483647]
• 示例：
  • SET vchordg.max_scan_tuples = 999 表示索引扫描最多返回 $999$ 个元组。
  • SET vchordg.max_scan_tuples = -1 表示对元组数量没有限制。
• 注意：当设置为 -1 时，此参数不起作用。

2.4 - 量化类型

量化不仅可以应用于索引，还可以直接应用于向量本身。为此，VectorChord 提供了专门用于量化向量的数据类型。

rabitq8 是量化向量的数据类型。在相同维度下，它的存储开销约为全精度向量（vector）的 $\frac{1}{4}$，半精度向量（halfvec）的 $\frac{1}{2}$。该类型以其所使用的量化算法命名。¹

CREATE TABLE items (id bigserial PRIMARY KEY, embedding rabitq8(3));
INSERT INTO items (embedding) VALUES (quantize_to_rabitq8('[0,0,0]'::vector));
INSERT INTO items (embedding) VALUES (quantize_to_rabitq8('[1,1,1]'::vector));
INSERT INTO items (embedding) VALUES (quantize_to_rabitq8('[2,2,2]'::vector));
--- ...
SELECT id FROM items ORDER BY embedding <-> quantize_to_rabitq8('[0.9,0.9,1.1]'::vector) LIMIT 100;

与普通向量类型一样，也可以在 rabitq8 类型的列上创建索引。

CREATE INDEX ON items USING vchordrq (embedding rabitq8_l2_ops);

通过使用 rabitq8，表大小和索引大小都将缩小为使用 vector 类型时的 $\frac{1}{4}$。其代价是量化会明显折损性能与精度。因此，它适用于检索大量候选结果的场景。

此外，VectorChord 还提供了 rabitq4 类型。rabitq8 量化向量在每个维度上使用 $8$ 比特，而 rabitq4 量化向量在每个维度上仅使用 $4$ 比特。它专为在受限环境下优先追求低存储开销而非高精度的场景而设计。

参考

操作符类

请参阅：

• 操作符类（vchordrq）。
• 操作符类（vchordg）。

数据类型

rabitq8

• 说明：使用 uint8 进行内部存储的量化向量数据类型。基于扩展版 RaBitQ 算法。¹
• 文本表示：与 vector/halfvec 不同，rabitq8 的文本表示更为复杂。假设维度为 $d$，它由括在圆括号中的 $4$ 个浮点数数组与括在方括号中的 $d$ 个 uint8 整数数组拼接而成。例如 (2.999999, 160.63234, 647, 2.8498733)[255, 205, 187]。其内部解释无需手动处理，但您可以通过 dequantize_to_vector(rabitq8) / dequantize_to_halfvec(rabitq8) 获取它所代表的近似向量。

rabitq4

• 说明：使用 uint4 进行内部存储的量化向量数据类型。基于扩展版 RaBitQ 算法。¹
• 文本表示：与 vector/halfvec 不同，rabitq4 的文本表示更为复杂。假设维度为 $d$，它由括在圆括号中的 $4$ 个浮点数数组与括在方括号中的 $d$ 个 uint4 整数数组拼接而成。例如 (2.999999, 9.420722, 38, 2.8498733)[15, 12, 11]。其内部解释无需手动处理，但您可以通过 dequantize_to_vector(rabitq4) / dequantize_to_halfvec(rabitq4) 获取它所代表的近似向量。

函数

quantize_to_rabitq8(vector)

• 说明：将向量量化为 rabitq8。请注意，在不同的 VectorChord 版本或不同的机器上，该函数对相同输入可能会产生略有差异的结果。
• 返回值：rabitq8，量化后的向量
• 参数：
  • vector，待量化的向量
• 示例：
  • SELECT quantize_to_rabitq8('[1,1,1]'::vector)
• 注意：该函数没有对应的默认类型转换（CAST）。如有需要，您可以使用 CREATE CAST (vector AS rabitq8) WITH FUNCTION quantize_to_rabitq8(vector) AS ASSIGNMENT 手动创建。

quantize_to_rabitq8(halfvec)

• 说明：将半精度向量量化为 rabitq8。请注意，在不同的 VectorChord 版本或不同的机器上，该函数对相同输入可能会产生略有差异的结果。
• 返回值：rabitq8，量化后的向量
• 参数：
  • halfvec，待量化的向量
• 示例：
  • SELECT quantize_to_rabitq8('[1,1,1]'::halfvec)
• 注意：该函数没有对应的默认类型转换（CAST）。如有需要，您可以使用 CREATE CAST (halfvec AS rabitq8) WITH FUNCTION quantize_to_rabitq8(halfvec) AS ASSIGNMENT 手动创建。

dequantize_to_vector(rabitq8)

• 说明：将量化向量反量化为 vector。请注意，在不同的 VectorChord 版本或不同的机器上，该函数对相同输入可能会产生略有差异的结果。使用此函数无法精确重建原始向量。
• 返回值：vector，反量化后的向量
• 参数：
  • rabitq8，待反量化的量化向量
• 示例：
  • SELECT dequantize_to_vector(quantize_to_rabitq8('[1,1,1]'::vector))
• 注意：该函数没有对应的默认类型转换（CAST）。如有需要，您可以使用 CREATE CAST (rabitq8 AS vector) WITH FUNCTION dequantize_to_vector(rabitq8) AS ASSIGNMENT 手动创建。

dequantize_to_halfvec(rabitq8)

• 说明：将量化向量反量化为 halfvec。请注意，在不同的 VectorChord 版本或不同的机器上，该函数对相同输入可能会产生略有差异的结果。使用此函数无法精确重建原始向量。
• 返回值：halfvec，反量化后的向量
• 参数：
  • rabitq8，待反量化的量化向量
• 示例：
  • SELECT dequantize_to_halfvec(quantize_to_rabitq8('[1,1,1]'::halfvec))
• 注意：该函数没有对应的默认类型转换（CAST）。如有需要，您可以使用 CREATE CAST (rabitq8 AS halfvec) WITH FUNCTION dequantize_to_halfvec(rabitq8) AS ASSIGNMENT 手动创建。

quantize_to_rabitq4(vector)

• 说明：将向量量化为 rabitq4。请注意，在不同的 VectorChord 版本或不同的机器上，该函数对相同输入可能会产生略有差异的结果。
• 返回值：rabitq4，量化后的向量
• 参数：
  • vector，待量化的向量
• 示例：
  • SELECT quantize_to_rabitq4('[1,1,1]'::vector)
• 注意：该函数没有对应的默认类型转换（CAST）。如有需要，您可以使用 CREATE CAST (vector AS rabitq4) WITH FUNCTION quantize_to_rabitq4(vector) AS ASSIGNMENT 手动创建。

quantize_to_rabitq4(halfvec)

• 说明：将半精度向量量化为 rabitq4。请注意，在不同的 VectorChord 版本或不同的机器上，该函数对相同输入可能会产生略有差异的结果。
• 返回值：rabitq4，量化后的向量
• 参数：
  • halfvec，待量化的向量
• 示例：
  • SELECT quantize_to_rabitq4('[1,1,1]'::halfvec)
• 注意：该函数没有对应的默认类型转换（CAST）。如有需要，您可以使用 CREATE CAST (halfvec AS rabitq4) WITH FUNCTION quantize_to_rabitq4(halfvec) AS ASSIGNMENT 手动创建。

dequantize_to_vector(rabitq4)

• 说明：将量化向量反量化为 vector。请注意，在不同的 VectorChord 版本或不同的机器上，该函数对相同输入可能会产生略有差异的结果。使用此函数无法精确重建原始向量。
• 返回值：vector，反量化后的向量
• 参数：
  • rabitq4，待反量化的量化向量
• 示例：
  • SELECT dequantize_to_vector(quantize_to_rabitq4('[1,1,1]'::vector))
• 注意：该函数没有对应的默认类型转换（CAST）。如有需要，您可以使用 CREATE CAST (rabitq4 AS vector) WITH FUNCTION dequantize_to_vector(rabitq4) AS ASSIGNMENT 手动创建。

dequantize_to_halfvec(rabitq4)

• 说明：将量化向量反量化为 halfvec。请注意，在不同的 VectorChord 版本或不同的机器上，该函数对相同输入可能会产生略有差异的结果。使用此函数无法精确重建原始向量。
• 返回值：halfvec，反量化后的向量
• 参数：
  • rabitq4，待反量化的量化向量
• 示例：
  • SELECT dequantize_to_halfvec(quantize_to_rabitq4('[1,1,1]'::halfvec))
• 注意：该函数没有对应的默认类型转换（CAST）。如有需要，您可以使用 CREATE CAST (rabitq4 AS halfvec) WITH FUNCTION dequantize_to_halfvec(rabitq4) AS ASSIGNMENT 手动创建。

操作符

<->(rabitq8, rabitq8)

• 说明：计算两个量化向量之间的 L2 距离。
• 返回值：real，两个量化向量的 L2 距离
• 参数：
  • rabitq8
  • rabitq8

<#>(rabitq8, rabitq8)

• 说明：计算两个量化向量之间的负点积距离。
• 返回值：real，两个量化向量的负点积距离
• 参数：
  • rabitq8
  • rabitq8

<=>(rabitq8, rabitq8)

• 说明：计算两个量化向量之间的余弦距离。
• 返回值：real，两个量化向量的余弦距离
• 参数：
  • rabitq8
  • rabitq8

<->(rabitq4, rabitq4)

• 说明：计算两个量化向量之间的 L2 距离。
• 返回值：real，两个量化向量的 L2 距离
• 参数：
  • rabitq4
  • rabitq4

<#>(rabitq4, rabitq4)

• 说明：计算两个量化向量之间的负点积距离。
• 返回值：real，两个量化向量的负点积距离
• 参数：
  • rabitq4
  • rabitq4

<=>(rabitq4, rabitq4)

• 说明：计算两个量化向量之间的余弦距离。
• 返回值：real，两个量化向量的余弦距离
• 参数：
  • rabitq4
  • rabitq4

2.5 - 相似度过滤

通常，我们会使用 ORDER BY 和 LIMIT 子句来执行向量搜索。但在某些情况下，您可能希望使用 WHERE 子句过滤掉距离查询向量太远的向量。很自然地，您可能会写出如下 SQL：

EXPLAIN (COSTS FALSE) 
SELECT * FROM items WHERE embedding <-> '[0, 0, 0]' < 0.1 ORDER BY embedding <-> '[0, 0, 0]' LIMIT 10;
                                  QUERY PLAN                                   
-------------------------------------------------------------------------------
 Limit
   ->  Index Scan using items_embedding_idx on items
         Order By: (embedding <-> '[0,0,0]'::vector)
         Filter: ((embedding <-> '[0,0,0]'::vector) < '0.1'::double precision)

返回的结果虽然符合预期，但这种写法的性能却很差。这是因为如果落在距离阈值内的向量少于 $10$ 个，PostgreSQL 会强制索引继续搜索以凑够 $10$ 条结果，从而遍历耗尽整个搜索空间。

为了避免这种情况，您可以使用特定语法将过滤条件直接下推（push down）到向量索引中，使索引一旦发现搜索区域超出指定距离便立即停止搜索。我们将这种可以下推到索引中的基于距离的过滤条件称为相似度过滤（similarity filter）。

EXPLAIN (COSTS FALSE) 
SELECT * FROM items WHERE embedding <<->> sphere('[0, 0, 0]'::vector, 0.1) ORDER BY embedding <-> '[0, 0, 0]' LIMIT 10;
                               QUERY PLAN                               
------------------------------------------------------------------------
 Limit
   ->  Index Scan using items_embedding_idx on items
         Index Cond: (embedding <<->> '("[0,0,0]",0.1)'::sphere_vector)
         Order By: (embedding <-> '[0,0,0]'::vector)

当且仅当两个向量之间的 L2 距离小于 0.1 时，embedding <<->> sphere('[0, 0, 0]'::vector, 0.1) 的求值结果为 true。对于负内积请使用 <<#>> 操作符，对于余弦距离请使用 <<=>> 操作符。

此外，如果您只指定 WHERE 子句而不使用 ORDER BY，索引依然能够被有效利用。

EXPLAIN (COSTS FALSE) 
SELECT * FROM items WHERE embedding <<->> sphere('[0, 0, 0]'::vector, 0.1);
                            QUERY PLAN                            
------------------------------------------------------------------
 Index Scan using items_embedding_idx on items
   Index Cond: (embedding <<->> '("[0,0,0]",0.1)'::sphere_vector)

参考

操作符类

请参阅：

• 操作符类（vchordrq）。
• 操作符类（vchordg）。

数据类型

sphere_vector

• 说明：球体（Sphere）。
• 定义：(center vector, radius REAL)。

sphere_halfvec

• 说明：球体（Sphere）。
• 定义：(center halfvec, radius REAL)。

sphere_rabitq8

• 说明：球体（Sphere）。
• 定义：(center rabitq8, radius REAL)。

sphere_rabitq4

• 说明：球体（Sphere）。
• 定义：(center rabitq4, radius REAL)。

函数

sphere(vector, real)

• 说明：通过球心和半径创建一个球体。
• 定义：SELECT ROW($1, $2)。
• 返回值：sphere_vector
• 参数：
  • vector，球体的球心
  • real，球体的半径
• 示例：
  • SELECT sphere('[0,0,0]'::vector, 1.0)

sphere(halfvec, real)

• 说明：通过球心和半径创建一个球体。
• 定义：SELECT ROW($1, $2)。
• 返回值：sphere_halfvec
• 参数：
  • halfvec，球体的球心
  • real，球体的半径
• 示例：
  • SELECT sphere('[0,0,0]'::halfvec, 1.0)

sphere(rabitq8, real)

• 说明：通过球心和半径创建一个球体。
• 定义：SELECT ROW($1, $2)。
• 返回值：sphere_rabitq8
• 参数：
  • rabitq8，球体的球心
  • real，球体的半径
• 示例：
  • SELECT sphere(quantize_to_rabitq8('[0,0,0]'::vector), 1.0)

sphere(rabitq4, real)

• 说明：通过球心和半径创建一个球体。
• 定义：SELECT ROW($1, $2)。
• 返回值：sphere_rabitq4
• 参数：
  • rabitq4，球体的球心
  • real，球体的半径
• 示例：
  • SELECT sphere(quantize_to_rabitq4('[0,0,0]'::vector), 1.0)

操作符

<<->>(vector, sphere_vector)

• 说明：使用 L2 度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • vector，待检测的向量
  • sphere_vector，球体

<<#>>(vector, sphere_vector)

• 说明：使用负点积度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • vector，待检测的向量
  • sphere_vector，球体

<<=>>(vector, sphere_vector)

• 说明：使用余弦度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • vector，待检测的向量
  • sphere_vector，球体

<<->>(halfvec, sphere_halfvec)

• 说明：使用 L2 度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • halfvec，待检测的向量
  • sphere_halfvec，球体

<<#>>(halfvec, sphere_halfvec)

• 说明：使用负点积度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • halfvec，待检测的向量
  • sphere_halfvec，球体

<<=>>(halfvec, sphere_halfvec)

• 说明：使用余弦度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • halfvec，待检测的向量
  • sphere_halfvec，球体

<<->>(rabitq8, sphere_rabitq8)

• 说明：使用 L2 度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • rabitq8，待检测的向量
  • sphere_rabitq8，球体

<<#>>(rabitq8, sphere_rabitq8)

• 说明：使用负点积度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • rabitq8，待检测的向量
  • sphere_rabitq8，球体

<<=>>(rabitq8, sphere_rabitq8)

• 说明：使用余弦度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • rabitq8，待检测的向量
  • sphere_rabitq8，球体

<<->>(rabitq4, sphere_rabitq4)

• 说明：使用 L2 度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • rabitq4，待检测的向量
  • sphere_rabitq4，球体

<<#>>(rabitq4, sphere_rabitq4)

• 说明：使用负点积度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • rabitq4，待检测的向量
  • sphere_rabitq4，球体

<<=>>(rabitq4, sphere_rabitq4)

• 说明：使用余弦度量检测向量是否位于球体内部。
• 返回值：布尔值（boolean）
• 参数：
  • rabitq4，待检测的向量
  • sphere_rabitq4，球体

2.6 - PostgreSQL 调优

索引构建可以并行化执行。由于并行化会增加服务器负载，PostgreSQL 默认并未启用。如需启用并行构建，请参考以下 SQL 配置：

-- 设置数据库集群可支持的最大后台进程数。
-- 建议将其设置为至少等于您期望的并行度加上 8。
-- 例如，如果您希望使用 16 个线程进行并行处理，请将该值至少设置为 24。
-- 根据您的实际工作负载，将该值设置得更高可能会更有帮助。
-- 注意：此设置需要重启数据库才能生效。
ALTER SYSTEM SET max_worker_processes = 24;

-- 设置数据库集群可用于并行操作的最大工作进程数。
-- 建议将其设置为您期望的并行度减 1。
-- 例如，如果您希望使用 16 个线程进行并行处理，请将该值设置为 15。
SET max_parallel_workers = 15;

-- 设置单个维护命令（如 CREATE INDEX）可启动的最大并行工作进程数。
-- 建议将其设置为您期望的并行度减 1。
-- 例如，如果您希望使用 16 个线程进行并行处理，请将该值设置为 15。
SET max_parallel_maintenance_workers = 15;

并行工作进程的数量还取决于表本身的配置。默认情况下，该值由 PostgreSQL 自动计算决定。如果 PostgreSQL 判定不启用并行，那么并行索引构建就不会生效。您可以通过调整表的 parallel_workers 存储参数来覆盖 PostgreSQL 的默认行为，强制启用并行索引构建。

ALTER TABLE items set (parallel_workers = 15);

您还需要调整以下几个设置以提升 I/O 性能：

-- 设置 PostgreSQL 预期可同时执行的并发磁盘 I/O 操作数。
-- 使用 SSD 存储时，建议将其设置为 20。
SET effective_io_concurrency = 20;
SET maintenance_io_concurrency = 20;

我们观察到在某些情况下，工作异常的 JIT（即时编译）可能会对性能产生负面影响。如果您并不依赖它，可以选择将其禁用。

SET jit = off;

最后，您需要设置 PostgreSQL 共享缓冲区（shared buffers）的大小。

-- 设置数据库服务器用于共享内存缓冲区的内存量。
-- 根据您的工作负载，通常建议将该值设置为总内存的 25%~40%。
-- 对于向量数据库工作负载，将该值设置为总内存的 80% 往往更有优势。
-- 注意：此设置需要重启数据库才能生效。
ALTER SYSTEM SET shared_buffers = '16GB';

异步 I/O

PostgreSQL 17 首次引入了流式 I/O（streaming I/O）API。在此基础上，PostgreSQL 18 引入了异步 I/O（Asynchronous I/O）。借助异步 I/O，PostgreSQL 可以同时发起多个读取操作，并在等待结果返回的同时继续处理其他任务。这能够显著提升需要从磁盘读取大量数据的查询性能。PostgreSQL 提供了多种异步 I/O 方式，您可以根据需要进行调整。

本节内容仅适用于 PostgreSQL 18。

io_uring

io_uring 方式使用 Linux 内核的 io_uring 接口，能够减少上下文切换的开销。该接口在 Linux 内核 5.1 及更高版本中可用。您可以通过 GUC 参数 io_method 启用此方式。

-- 注意：此设置需要重启数据库才能生效。
ALTER SYSTEM SET io_method = 'io_uring';

由于 io_uring 会使用额外的文件描述符和锁定内存（locked memory），PostgreSQL 可能会触及系统的 RLIMIT_NOFILE 和 RLIMIT_MEMLOCK 限制。您可能需要在操作系统层面调高这些限制。另请参阅：

• limits.conf (PAM)
• Process Properties (systemd)
• Set ulimits in container (Docker)

出于安全考虑，容器运行时、云服务商或系统管理员可能会禁用 io_uring。如果遇到此类情况，请向您的服务提供商咨询详情。另请参阅：

• Consider removing io_uring syscalls in from RuntimeDefault (containerd)

通常推荐使用 io_uring，但实际性能表现仍取决于您的具体工作负载。另请参阅：

• Tuning AIO in PostgreSQL 18 (Tomas Vondra)
• Benchmarking Postgres 17 vs 18 (planetscale)

本小节仅适用于 Linux 系统。

worker

这是 PostgreSQL 18 中的默认设置。PostgreSQL 通过将 I/O 请求发送到专门的进程池来避免阻塞后端进程。您可以通过 GUC 参数 io_method 显式启用此方式。

-- 注意：此设置需要重启数据库才能生效。
ALTER SYSTEM SET io_method = 'worker';

-- 选择要使用的 I/O 工作进程数量。
-- 建议将其设置为您的并行度与参数上限值之间的较小者。
-- 例如，如果您的并行度为 16，请将该值设置为 16。
-- 该参数的最大值为 32，因此不能设置超过 32 的值。
-- 注意：此设置需要重启数据库才能生效。
ALTER SYSTEM SET io_workers = 16;

sync

sync 方式的工作机制与 PostgreSQL 17 相同：读取操作是同步且阻塞的，并使用 posix_fadvise 向操作系统提供即将发生的读取提示。通常只有在调试时才会使用此方式。您可以通过 GUC 参数 io_method 启用此方式。

-- 注意：此设置需要重启数据库才能生效。
ALTER SYSTEM SET io_method = 'sync';

2.7 - 监控

您可以通过查询 pg_stat_progress_create_index 视图来监控 PostgreSQL 索引的构建进度。

SELECT command, phase, round(100.0 * blocks_done / nullif(blocks_total, 0), 1) AS "%" FROM pg_stat_progress_create_index;

参考

构建阶段（vchordrq）

vchordrq 的索引构建过程包含 5 个步骤，每个步骤的阶段名称（phase）如下：

第 4 步 inserting tuples from table to index 占据了索引构建过程中的大部分时间。tuples_done、blocks_done 和 blocks_total 列可用于指示该步骤的当前进度。

构建阶段（vchordg）

vchordg 的索引构建过程包含 2 个步骤，每个步骤的阶段名称（phase）如下：

第 2 步 inserting tuples from table to index 占据了索引构建过程中的大部分时间。tuples_done、blocks_done 和 blocks_total 列可用于指示该步骤的当前进度。

2.8 - 回退参数

搜索参数通常通过 GUC 进行配置。VectorChord 还提供了另一种方式，允许将这些参数直接绑定到索引上，而不是绑定到会话（session）或事务（transaction）上。换句话说，您可以将它们作为索引存储参数（storage parameters）的一部分保存下来。

在构建索引时，您可以使用以下语法设置 probes：

CREATE INDEX items_embedding_idx ON items USING vchordrq (embedding vector_l2_ops) WITH (options = $$
build.internal.lists = [1000]
$$, probes = '10');

现在，您无需设置 GUC 即可直接执行搜索：

--- probes = '10'
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

如果索引已经构建完成，您可以像这样修改 probes：

ALTER INDEX items_embedding_idx SET (probes = '100');

您仍然可以通过 GUC 设置搜索参数。当设置了 GUC 时，GUC 的优先级高于索引存储参数。这使您能够在不锁定索引的情况下，在当前会话或事务中临时覆盖这些设置。

SET vchordrq.probes TO '100';
--- probes = '100'
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

这种语法在以下场景中非常有用：

• 当存在多个索引且需要不同参数时。
• 当您不希望设置 GUC 时。
• 当您希望离线配置搜索参数时。

只要设置了 GUC（哪怕是在系统级别或数据库级别设置的），它都会覆盖索引上的存储参数设置。因此，为了避免难以排查的问题，我们建议仅使用一种方式来设置搜索参数：要么统一通过 GUC 设置，要么统一通过索引存储参数设置。

并非所有参数都支持此功能。有关支持此功能的全部参数，请参阅参考。

参考

索引存储参数（vchordrq）

probes

• 说明：vchordrq.probes 的回退值。
• 类型：整数列表（list of integers）
• 默认值：

epsilon

• 说明：vchordrq.epsilon 的回退值。
• 类型：实数（real）
• 默认值：1.9
• 取值范围：[0.0, 4.0]

maxsim_refine

• 说明：vchordrq.maxsim_refine 的回退值。
• 类型：整数（integer）
• 默认值：0
• 取值范围：[0, 2147483647]

maxsim_threshold

• 说明：vchordrq.maxsim_threshold 的回退值。
• 类型：整数（integer）
• 默认值：0
• 取值范围：[0, 2147483647]

索引存储参数（vchordg）

ef_search

• 说明：vchordg.ef_search 的回退值。
• 类型：整数（integer）
• 默认值：64
• 取值范围：[1, 65535]

2.9 - 评估召回率

在向量搜索中，召回率（recall）是指索引返回的近似最近邻中真实最近邻所占的比例。例如，如果索引检索出 $100$ 个近似最近邻，其中有 $97$ 个属于真实最近邻，那么召回率就是 $\frac{97}{100} = 0.97$。

召回率评估

召回率衡量的是搜索返回的相关结果占全部应返回真实结果的比例。在使用索引时，您通常希望了解不同参数配置所对应的召回率和 QPS。vchordrq_evaluate_query_recall 函数正是为评估召回率而设计的：它接收一条返回行标识符的查询语句，并返回对应的召回率。

vchordrq_evaluate_query_recall 函数内部依赖 ctid 将查询结果与基准真相（ground truth）进行比对。因此，传入的 query 参数必须以 SELECT ctid 开头。

SET vchordrq.probes = '100';
SET vchordrq.epsilon = 1.0;
SELECT vchordrq_evaluate_query_recall(query => $$
  SELECT ctid FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10
$$);

默认情况下，该函数通过执行另一次高精度索引扫描来生成估算的基准真相，并据此评估召回率。如果您希望通过全表扫描（table scan）生成精确的基准真相来评估召回率，请将函数参数 exact_search 设置为 true。

SET vchordrq.probes = '100';
SET vchordrq.epsilon = 1.0;
SELECT vchordrq_evaluate_query_recall(query => $$
  SELECT ctid FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10
$$, exact_search => true);

查询采样

为了方便评估生产或测试中的查询召回率，VectorChord 内置了查询采样方法。

SET vchordrq.query_sampling_enable = on;
SET vchordrq.query_sampling_max_records = 1000;
SET vchordrq.query_sampling_rate = 1;

假设您已经执行了一条示例向量搜索：SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10。

在查询执行并被采样后，您可以检查捕获到的查询要素，包括模式名（schema）、索引名、表名、列名、操作符以及目标向量。

SELECT * from vchordrq_sampled_queries('items_embedding_idx');
-- schema_name | index_name          | table_name | column_name | operator |    value
---------------+---------------------+------------+-------------+----------+--------------
-- public      | items_embedding_idx | items      | embedding   | <->      | [0.5,0.25,1]

要测量已记录查询的平均召回率，您可以构造目标查询语句并调用评估函数：

SELECT AVG(recall_value) FROM (
    SELECT vchordrq_evaluate_query_recall(
            format(
                'SELECT ctid FROM %I.%I ORDER BY %I OPERATOR(%s) %L LIMIT 10',
                lq.schema_name,
                lq.table_name,
                lq.column_name,
                lq.operator,
                lq.value
            )
    ) AS recall_value
    FROM vchordrq_sampled_queries('items_embedding_idx') AS lq
) AS eval_results;

如果您正在使用包含主库（primary）和备库（standby）的流复制（replication）功能，请注意：采样到的查询不会通过复制或备份进行同步。相反，每台服务器都会根据自己实际处理的查询独立维护各自的采样查询集合。

参考

vchordg 和多向量检索不支持此功能。

搜索参数（vchordrq）

vchordrq.query_sampling_enable

• 说明：启用或禁用 vchordrq 索引扫描的查询采样。
• 类型：布尔值（boolean）
• 默认值：off

vchordrq.query_sampling_max_records

• 说明：控制每个索引最多记录的查询数量。该设置仅在 vchordrq.query_sampling_enable 开启时生效。
• 类型：整数（integer）
• 默认值：0
• 取值范围：[0, 10000]
• 示例：
  • vchordrq.query_sampling_max_records = 0 将为每个索引保留 0 条查询。
  • vchordrq.query_sampling_max_records = 1000 将为每个索引最多保留最近 1000 条查询。

vchordrq.query_sampling_rate

• 说明：控制记录查询的采样率。该设置仅在 vchordrq.query_sampling_enable 开启时生效。
• 类型：实数（real）
• 默认值：0
• 取值范围：[0, 1]
• 示例：
  • vchordrq.query_sampling_rate = 0 不记录任何查询。
  • vchordrq.query_sampling_rate = 0.01 记录约 1% 的查询。
  • vchordrq.query_sampling_rate = 1 记录每一条查询（仅用于测试目的）。

函数（vchordrq）

vchordrq_sampled_queries

• 说明：检索指定 vchordrq 索引已记录的查询集合。
• 返回值：table
  • schema_name: text，查询中表的模式名
  • index_name: text，查询中使用的索引名称
  • table_name: text，查询中的表名
  • column_name: text，参与索引扫描的列名
  • operator: text，查询中使用的距离操作符
  • value: text，查询中目标向量的文本表示
• 参数：
  • regclass，vchordrq 索引的对象标识符
• 示例：
  • SELECT vchordrq_sampled_queries('items_embedding_idx');

vchordrq_sampled_values

• 说明：检索指定 vchordrq 索引已记录查询中的目标向量。
• 返回值：text，查询中目标向量的文本表示。
• 参数：
  • regclass，vchordrq 索引的对象标识符
• 示例：
  • SELECT vchordrq_sampled_values('items_embedding_idx');
• 注意：该函数仅用于调试目的。

vchordrq_evaluate_query_recall

• 说明：评估给定 vchordrq 查询的召回率。
• 返回值：real
• 参数：
  • query: text，待评估召回率的查询语句
  • exact_search: boolean，是否使用精确基准真相代替估算的基准真相
  • accu_probes: text，用于生成估算基准真相的 vchordrq.probes
  • accu_epsilon: real，用于生成估算基准真相的 vchordrq.epsilon
• 示例：
  • SELECT vchordrq_evaluate_query_recall(query => $$ SELECT ctid FROM t ORDER BY val <-> '[0.5, 0.25, 1.0]' LIMIT 10 $$);
  • SELECT vchordrq_evaluate_query_recall(query => $$ SELECT ctid FROM t ORDER BY val <-> '[0.5, 0.25, 1.0]' LIMIT 10 $$, exact_search => true);
  • SELECT vchordrq_evaluate_query_recall(query => $$ SELECT ctid FROM t ORDER BY val <-> '[0.5, 0.25, 1.0]' LIMIT 10 $$, accu_probes => '9999', accu_epsilon => 4.0);

视图（vchordrq）

vchordrq_sampled_queries

• 说明：检索所有 vchordrq 索引已记录的查询集合。
• 示例：
  • SELECT * from vchordrq_sampled_queries;
• 注意：该视图仅用于调试目的。

2.10 - 预热

PostgreSQL 启动后，表和索引只有在首次被访问时才会从存储加载到缓冲池（buffer pool）中。随着查询的不断执行，索引中被频繁访问的部分会自然地缓存在缓冲池里。然而，在执行最初的几批查询时，由于缓冲池为空，查询速度往往较慢。

PostgreSQL 扩展 pg_prewarm 提供了 pg_prewarm 函数，可以在一定程度上解决这一问题。在 PostgreSQL 启动后，您只需向该函数传入索引名称，它就会将索引从存储加载到缓冲池中。

SELECT pg_prewarm('items_pkey');

不过，这种方法只有在缓冲池远大于索引大小时才有效。对于向量索引而言，索引大小往往远超内存容量。向量索引在设计上将索引数据分为两部分：体量较小的热数据部分（hot portion）和体量庞大的冷数据部分（cold portion）。向量索引只需要将热数据部分保留在内存中即可获得理想的性能。因此，VectorChord 提供了专用的预热函数，仅将索引的热数据部分加载到内存中。

SELECT vchordrq_prewarm('items_embedding_idx');

即使索引大小远大于内存容量，该函数依然能够很好地发挥作用。

参考

函数（vchordrq）

vchordrq_prewarm

• 说明：该函数通过将 vchordrq 索引的热数据加载到缓冲池中来预热索引。
• 返回值：text
• 参数：
  • regclass，vchordrq 索引的对象标识符
• 示例：
  • SELECT vchordrq_prewarm('items_embedding_idx')

函数（vchordg）

vchordg_prewarm

• 说明：该函数通过将 vchordg 索引的热数据加载到缓冲池中来预热索引。
• 返回值：text
• 参数：
  • regclass，vchordg 索引的对象标识符
• 示例：
  • SELECT vchordg_prewarm('items_embedding_idx')

2.11 - 预过滤

在带过滤条件的索引扫描中，通常索引会先执行扫描，然后由 PostgreSQL 检查返回行是否满足过滤条件。在本页中，“过滤条件（filter）”是指 PostgreSQL 查询计划中索引扫描节点上的 Filter，它通常由 SQL 语句中的 WHERE 子句构造而成，并且不需要具备特定的形式。

EXPLAIN (COSTS FALSE)
SELECT * FROM items WHERE id <= 5000 AND vector_norm(embedding) < 0.5;
                          QUERY PLAN                          
--------------------------------------------------------------
 Index Scan using items_pkey on items
   Index Cond: (id <= 5000)
   Filter: (vector_norm(embedding) < '0.5'::double precision)

然而，对于向量搜索而言，这种方式并不总是最高效的。请看下面这个查询：

EXPLAIN (COSTS FALSE) 
SELECT * FROM items WHERE id % 97 = 0 ORDER BY embedding <-> '[0, 0, 0]' LIMIT 10;
                     QUERY PLAN                      
-----------------------------------------------------
 Limit
   ->  Index Scan using items_embedding_idx on items
         Order By: (embedding <-> '[0,0,0]'::vector)
         Filter: ((id % '97'::bigint) = 0)

为了检索出 $10$ 个满足过滤条件的向量，索引大约返回了 $970$ 行数据。这意味着索引执行了大量冗余计算。如果索引能够利用过滤条件进行剪枝，计算量将会大幅减少。为此，向量索引提供了 GUC 参数 vchordrq.prefilter，允许根据过滤条件对搜索空间进行剪枝。

SET vchordrq.prefilter = on;

预过滤（Prefilter）使向量索引能够在搜索过程中结合过滤条件进行判断，从而剪枝搜索空间；更小的搜索空间意味着更高的搜索效率。不过，检查过滤条件是否满足本身也会引入额外开销。因此，仅当过滤条件严格（能够排除大量行）且轻量（计算开销远低于计算向量距离）时，才推荐使用预过滤。为了便于理解，这里给出两个不适合使用预过滤的反例：

• id % 97 > 0：该过滤条件过于宽松
• email ~ '^([a-zA-Z]+)*$'：该过滤条件计算开销过高

根据我们的实验结果，在不同选择率（selectivity）下启用预过滤带来的 QPS 加速比如下：

• 在 1% 选择率下，QPS 提升 200%
• 在 10% 选择率下，QPS 提升 5%

参考

vchordg 不支持此功能。

搜索参数（vchordrq）

vchordrq.prefilter

• 说明：GUC 参数 vchordrq.prefilter 允许在计算距离之前先对过滤条件进行求值。例如，在查询 SELECT * FROM items WHERE id % 2 = 0 ORDER BY embedding <-> '[3,1,2]' LIMIT 5 中，正常情况下索引会先计算所有候选行的 embedding <-> '[3,1,2]' 距离，然后将行传递给 PostgreSQL，由 PostgreSQL 过滤掉 id % 2 != 0 的行。启用该参数后，索引可以在计算距离之前预先评估过滤条件并丢弃不匹配的行，从而提高查询效率。
• 类型：布尔值（boolean）
• 默认值：false

2.12 - 预取

预取（Prefetch）能够大幅加速涉及 I/O 操作的查询。它的工作原理是根据索引的实际访问需求，主动将缓冲区预读到操作系统页缓存（page cache）或 PostgreSQL 的缓冲池（buffer pool）中。

预取有助于将 I/O 与计算重叠执行，以及将不同的 I/O 操作相互重叠执行，从而显著减少查询执行期间等待缓冲区的时间，进而提升整体查询性能。

在 0.4.0 版本之前，VectorChord 使用 PostgreSQL 的同步 I/O 接口。从 0.4.0 版本开始，VectorChord 在较新版本的 PostgreSQL 上使用异步 I/O 接口。VectorChord 所使用的 I/O 接口可以通过 GUC 参数进行控制。

在 GUC 参数中，同步 I/O 接口被称为 read_buffer，异步 I/O 接口被称为 read_stream，而 VectorChord 的模拟异步接口被称为 prefetch_buffer。

对于远小于内存大小的索引，这三种预取模式之间几乎没有差异。read_stream 可以加速所有基于磁盘的索引，但它仅在 PostgreSQL 17 和 18 上可用。为了解决这个问题，VectorChord 提供了一个名为 prefetch_buffer 的模拟异步 I/O 接口，在所有 PostgreSQL 版本上均可用，作为旧版本 PostgreSQL 的回退方案。prefetch_buffer 的效果略逊于 read_stream。

要在 PostgreSQL 18 上通过 read_stream 充分发挥此功能的威力，您需要启用异步 I/O。另请参阅 PostgreSQL 调优。

参考

搜索参数（vchordrq）

vchordrq.io_search

• 说明：该 GUC 参数控制在向量搜索中读取位向量（bit vector）时的 I/O 预取策略，会影响基于磁盘向量的搜索性能。
• 类型：字符串（string）
• 取值范围：取决于 PostgreSQL 版本
  • PostgreSQL 13, 14, 15, 16：{"read_buffer", "prefetch_buffer"}
  • PostgreSQL 17, 18：{"read_buffer", "prefetch_buffer", "read_stream"}
• 默认值：取决于 PostgreSQL 版本
  • PostgreSQL 13, 14, 15, 16：prefetch_buffer
  • PostgreSQL 17, 18：read_stream
• 注意：
  • read_buffer 表示优先使用 ReadBuffer。
  • prefetch_buffer 表示优先结合使用 PrefetchBuffer 和 ReadBuffer。
  • read_stream 表示优先使用 read_stream。

vchordrq.io_rerank

• 说明：该 GUC 参数控制在向量搜索中读取全精度向量时的 I/O 预取策略，会显著影响基于磁盘向量的搜索性能。
• 类型：字符串（string）
• 取值范围：取决于 PostgreSQL 版本
  • PostgreSQL 13, 14, 15, 16：{"read_buffer", "prefetch_buffer"}
  • PostgreSQL 17, 18：{"read_buffer", "prefetch_buffer", "read_stream"}
• 默认值：取决于 PostgreSQL 版本
  • PostgreSQL 13, 14, 15, 16：prefetch_buffer
  • PostgreSQL 17, 18：read_stream
• 注意：
  • read_buffer 表示优先使用 ReadBuffer。
  • prefetch_buffer 表示优先结合使用 PrefetchBuffer 和 ReadBuffer。
  • read_stream 表示优先使用 read_stream。

搜索参数（vchordg）

vchordg.io_search

• 说明：该 GUC 参数控制在向量搜索中读取位向量（bit vector）时的 I/O 预取策略，会影响基于磁盘向量的搜索性能。
• 类型：字符串（string）
• 取值范围：取决于 PostgreSQL 版本
  • PostgreSQL 13, 14, 15, 16：{"read_buffer", "prefetch_buffer"}
  • PostgreSQL 17, 18：{"read_buffer", "prefetch_buffer", "read_stream"}
• 默认值：取决于 PostgreSQL 版本
  • PostgreSQL 13, 14, 15, 16：prefetch_buffer
  • PostgreSQL 17, 18：read_stream
• 注意：
  • read_buffer 表示优先使用 ReadBuffer。
  • prefetch_buffer 表示优先结合使用 PrefetchBuffer 和 ReadBuffer。
  • read_stream 表示优先使用 read_stream。

vchordg.io_rerank

• 说明：该 GUC 参数控制在向量搜索中读取全精度向量时的 I/O 预取策略，会显著影响基于磁盘向量的搜索性能。
• 类型：字符串（string）
• 取值范围：取决于 PostgreSQL 版本
  • PostgreSQL 13, 14, 15, 16：{"read_buffer", "prefetch_buffer"}
  • PostgreSQL 17, 18：{"read_buffer", "prefetch_buffer", "read_stream"}
• 默认值：取决于 PostgreSQL 版本
  • PostgreSQL 13, 14, 15, 16：prefetch_buffer
  • PostgreSQL 17, 18：read_stream
• 注意：
  • read_buffer 表示优先使用 ReadBuffer。
  • prefetch_buffer 表示优先结合使用 PrefetchBuffer 和 ReadBuffer。
  • read_stream 表示优先使用 read_stream。

2.13 - 表内重排序

PostgreSQL 索引会存储行标识符（row identifier）以及被索引列的值。通常情况下，被索引的列具有简单的数据类型，例如整数或长度有限的短字符串。

然而，如果被索引的列是向量类型，那么表和索引都会存储向量，这意味着您需要为这些向量支付双倍的存储成本。如果您希望降低这部分开销，可以在构建索引时启用 rerank_in_table。启用后，索引将采用一种巧妙的方式：它自身不再存储原始向量，而是在需要时直接从表中读取它们。

CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops) WITH (options = $$
rerank_in_table = true
residual_quantization = true
$$);

启用该选项会导致查询性能下降，并且在启用 rerank_in_table 时，预取（prefetch）功能将无法生效。

这是一种以时间换空间的折中方案，通常不推荐使用，仅适用于需要解决磁盘存储空间极度紧张的特定场景。

参考

vchordg 不支持此功能。

索引选项（vchordrq）

rerank_in_table

• 说明：该选项决定是否从表中读取向量进行重排序。如果启用，索引所需的存储空间将减少，但查询延迟会显著增加。仅当磁盘空间极其有限时才应启用此选项。
• 类型：布尔值（boolean）
• 默认值：false
• 示例：
  • rerank_in_table = false 表示向量同时存储在索引和表中，搜索时从索引中读取向量。
  • rerank_in_table = true 表示向量仅存储在表中，搜索时从表中读取向量。

2.14 - 分区调优

对于大表而言，分区阶段主导了整个索引构建的时间与内存消耗。

分区阶段的时间复杂度为 $O(FC^{2}DL)$，内存消耗（以字节为单位）可以近似表示为 $4DC(F + T + 1)$，

其中：

• $D$ 是向量维度（如果设置了 build.internal.kmeans_dimension，则为该参数的值）。
• $F$ 是 build.internal.sampling_factor。
• $C$ 是 build.internal.lists[-1]。
• $T$ 是 build.internal.build_threads。
• $L$ 是 build.internal.kmeans_iterations。

本页介绍几种用于优化构建时间和内存消耗的调优技巧。

层次 K-means

层次 K-means（Hierarchical K-means）是一种比劳埃德算法（Lloyd’s algorithm）更快的聚类算法。应用该算法后，渐近时间复杂度将降低至 $O(FC^{1.5}DL)$。作为折中，它会对搜索性能和召回率产生轻微的负面影响。

用法：

build.internal.kmeans_algorithm.hierarchical = {}

降低采样因子

降低采样因子（sampling factor）可以线性地改善构建时间和内存消耗。作为折中，它会对搜索性能和召回率产生中等程度的负面影响。

用法：

build.internal.sampling_factor = 64

降维

降维功能使用快速约翰逊-林登施特劳斯变换（Fast Johnson–Lindenstrauss transform），将参与聚类的向量维度降低至原始维度以下，从而线性地改善构建时间和内存消耗。作为折中，它会对搜索性能和召回率产生轻微的负面影响。

用法：

build.internal.kmeans_dimension = 100

参考配置

LAION 100M

数据集：

• 来源：https://sisap-challenges.github.io/2024/datasets/
• 度量方式：内积（Inner Product）
• 维度：768
• 向量数量：100,000,000
• 测试向量数量：1,000

测试机器（AWS EC2 i7i.4xlarge）：

• CPU：Intel Xeon Platinum 8559C
• vCPU 数量：16
• 内存：128 GiB
• 存储：3750 GiB NVMe SSD

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

测试结果：

• 总构建时间：18 分钟
• 峰值内存：6 GiB
• 测试用例 1
  • 参数
    • vchordrq.probes = '40,140'
    • vchordrq.epsilon = 1.4
  • QPS @ Top10：120
  • Recall @ Top10：0.949

DEEP 1B

数据集：

• 来源：https://big-ann-benchmarks.com/neurips21.html
• 度量方式：欧氏距离（Euclidean）
• 维度：96
• 向量数量：1,000,000,000
• 测试向量数量：10,000

测试机器（AWS EC2 i7ie.6xlarge）：

• CPU：Intel Xeon Platinum 8559C
• vCPU 数量：24
• 内存：192 GiB
• 存储：7500 GiB NVMe SSD

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

测试结果：

• 总构建时间：107 分钟
• 峰值内存：64 GiB
• 测试用例 1
  • 参数
    • vchordrq.probes = '40,250'
  • QPS @ Top10：68
  • Recall @ Top10：0.951

2.15 - 外部构建

除了使用分区调优中的方法（以牺牲一定 QPS 和召回率为代价来缩短构建时间并降低内存消耗）之外，您还可以选择在其他机器或 GPU 上离线运行分区阶段。由于 vchordg 没有分区阶段，因此该特性不支持 vchordg。

假设表名为 t，待建索引的列名为 val。

CREATE TABLE t (val vector(3));

具体而言，您需要先对待建索引的列进行采样。

CREATE EXTENSION IF NOT EXISTS tsm_system_rows;
SELECT val FROM t TABLESAMPLE SYSTEM_ROWS(1000);

基于这些样本，您可以将向量空间划分为多个 Voronoi 单元（Voronoi cells）。完成划分后，创建一张表并将分区质心插入其中。

CREATE TABLE public.t_build (id INTEGER NOT NULL UNIQUE, parent INTEGER, vector vector NOT NULL);
INSERT INTO public.t_build (id, parent, vector) VALUES (0, NULL, '{0.1, 0.2, 0.3}');
INSERT INTO public.t_build (id, parent, vector) VALUES (1, 0, '{0.1, 0.2, 0.3}');
INSERT INTO public.t_build (id, parent, vector) VALUES (2, 0, '{0.4, 0.5, 0.6}');
INSERT INTO public.t_build (id, parent, vector) VALUES (3, 0, '{0.7, 0.8, 0.9}');

随后可以使用以下语法创建索引：

CREATE INDEX ON t USING vchordrq (embedding vector_l2_ops) WITH (options = $$
build.external.table = 'public.t_build'
$$);

表结构格式

存储分区信息的表必须严格遵循以下表结构（Schema）：

• 第一列必须为 id，类型为 integer，不可为 null（NOT NULL），且必须唯一（UNIQUE）。
• 第二列必须为 parent，类型为 integer，允许为 null（根节点为 NULL）。
• 第三列必须为 vector，类型为 vector，不可为 null（NOT NULL）。目前尚不支持 halfvec 或其他类型。

在逻辑上，这些数据构成了一棵树。从根节点到每个叶子节点的距离（深度）必须完全相同。

如果上述任何属性未得到满足，系统都会报错。

分区示例

为了帮助您快速上手，下面给出一个使用 faiss 执行向量空间分区的最小代码示例。

from typing import List
from faiss import Kmeans
import numpy

def partition(
    samples: List[numpy.Array[float]], lists: List[int]
) -> List[numpy.Array[float]]:
    dim = dataset.shape[1]
    results = []
    for i in range(len(lists) + 1):
        kmeans = Kmeans(
            dim,
            lists[len(lists) - 1 - i] if len(lists) - 1 - i >= 0 else 1,
            gpu=False,
            verbose=True,
            niter=10,
            seed=42,
            spherical=False,
        )
        kmeans.train(samples)
        results.push(kmeans.centroids)
        samples = kmeans.centroids
    return results