pgvecto.rs 是一个 PostgreSQL 扩展，提供了向量相似性搜索功能。它使用 Rust 语言编写，并基于 pgrx 构建。

[!NOTE] 我们推出了新的实现 VectorChord，具有更好的稳定性和性能。建议用户迁移到 VectorChord。请查看迁移指南。

与 pgvector 的比较

更多详细信息，请参阅 pgvecto.rs 与 pgvector 的比较。

特性	pgvecto.rs	pgvector
过滤	引入 VBASE 方法，支持向量搜索与关系查询（例如：单向量 TopK + 过滤 + 联接）。	应用过滤条件时，结果可能不完整。例如，原本计划限制结果为 10 条，但在应用过滤后可能只得到 5 条结果。
向量维度	支持高达 65535 维度。	最多支持 2000 维度。
SIMD	在运行时动态调度 SIMD 指令，以根据具体机器的硬件能力最大化性能。	在 0.7.0 版本中，为 Linux x86-64 平台的距离函数添加了 CPU 分派功能。
数据类型	引入了额外的数据类型：二进制向量、FP16（16 位浮点数）和 INT8（8 位整数）。	-
索引	将索引的存储和内存管理与 PostgreSQL 分开处理。	依赖 PostgreSQL 的原生存储引擎。
WAL 支持	提供数据的预写日志（WAL）支持，索引的 WAL 支持仍在开发中。	提供索引和数据的预写日志（WAL）支持。

文档

• 入门
  • 概述
  • 安装
• 使用
  • 索引
  • 搜索
• 管理
  • 配置
  • 从旧版本升级
• 开发者
  • 开发教程

快速入门

对于新用户，我们推荐使用 Docker 镜像，以便快速上手。

docker run \
  --name pgvecto-rs-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d ghcr.io/tensorchord/pgvecto-rs:pg17-v0.4.0

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

psql -h localhost -p 5432 -U postgres

运行以下 SQL 语句以确保扩展已启用。

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;

pgvecto.rs 引入了一种新的数据类型 vector(n)，表示 n 维向量。括号中的 n 表示向量的维度。

您可以通过以下 SQL 创建一张包含向量列的表：

-- 创建包含向量列的表

CREATE TABLE items (
  id bigserial PRIMARY KEY,
  embedding vector(3) NOT NULL -- 3 维
);

[!TIP] vector(n) 只有在 $1 \leq n \leq 65535$ 时才是有效的数据类型。由于 PostgreSQL 的限制，有可能创建一个 $5$ 维的 vector(3) 类型值，且 vector 也是有效数据类型。然而，您仍然不能将 $0$ 个标量或超过 $65535$ 个标量放入向量中。如果某列使用 vector 类型，而某些值与该列所声明的维度不符，则无法为其创建索引。

接下来，您可以按如下方式填充表中的向量数据：

-- 插入值

INSERT INTO items (embedding)
VALUES ('[1,2,3]'), ('[4,5,6]');

-- 或通过数组到向量的转换插入值

INSERT INTO items (embedding)
VALUES (ARRAY[1, 2, 3]::real[]), (ARRAY[4, 5, 6]::real[]);

我们支持三种运算符来计算两个向量之间的距离：

• <->: 平方欧几里得距离，定义为 $\Sigma (x_i - y_i) ^ 2$。
• <#>: 负点积，定义为 $- \Sigma x_iy_i$。
• <=>: 余弦距离，定义为 $1 - \frac{\Sigma x_iy_i}{\sqrt{\Sigma x_i^2 \Sigma y_i^2}}$。

-- 通过运算符调用距离函数

-- 平方欧几里得距离
SELECT '[1, 2, 3]'::vector <-> '[3, 2, 1]'::vector;
-- 负点积
SELECT '[1, 2, 3]'::vector <#> '[3, 2, 1]'::vector;
-- 余弦距离
SELECT '[1, 2, 3]'::vector <=> '[3, 2, 1]'::vector;

您可以这样简单地搜索向量：

-- 查询相似的嵌入
SELECT * FROM items ORDER BY embedding <-> '[3,2,1]' LIMIT 5;

一个简单的问答应用

请查看 问答应用 教程。

半精度浮点数

vecf16 类型除了标量类型不同外，其他方面都与 vector 相同。它存储 16 位浮点数。如果您希望减少内存占用以获得更好的性能，可以尝试将 vector 类型替换为 vecf16 类型。

路线图 🗂️

请查看 路线图。想参与其中吗？欢迎讨论和贡献！

• 在 💬 Discord 上与我们交流
• 查看 good first issue 💖 问题！

贡献 😊

我们欢迎来自开源社区、个人和合作伙伴的各种形式的贡献。

• 加入我们的 Discord 社区!
• 如果您想从源代码构建，请阅读我们的 贡献文档 和 开发教程。

贡献者 ✨

感谢以下各位优秀的贡献者（emoji key）：

Alex Chi 💻	AuruTus 💻	Avery 💻 🤔	Ben Ye 📖	Ce Gao 💼 🖋 📖	Jinjing Zhou 🎨 🤔 📆	Joe Passanante 💻
Keming 🐛 💻 📖 🤔 🚇	Mingzhuo Yin 💻 ⚠️ 🚇	Usamoi 💻 🤔	cutecutecat 💻	odysa 📖 💻	yi wang 💻	yihong 💻
盐粒 Yanli 💻
添加您的贡献

本项目遵循 all-contributors 规范。欢迎任何形式的贡献！

致谢

感谢以下项目：

• pgrx - 使用 Rust 编写的 PostgreSQL 扩展框架
• pgvector - 使用 C 语言编写的用于向量相似性搜索的 PostgreSQL 扩展

pgvecto.rs 快速上手指南

pgvecto.rs 是一个基于 Rust 开发的 PostgreSQL 扩展，提供高效的向量相似度搜索功能。它支持高达 65535 维的向量，并引入了 VBASE 方法以在过滤条件下实现更精准的查询。

注意：官方已推出新一代实现 VectorChord，具有更好的稳定性和性能。新用户建议优先考虑迁移至 VectorChord。

环境准备

• 操作系统：Linux, macOS, Windows (通过 Docker)
• 前置依赖：
  • Docker & Docker Compose（推荐方式）
  • 或本地安装的 PostgreSQL 14/15/16/17 及 Rust 工具链（若从源码编译）
• 客户端工具：psql 命令行工具或其他 PostgreSQL 客户端

安装步骤

推荐使用 Docker 镜像快速启动，无需配置复杂的编译环境。

1. 拉取并运行 Docker 容器

   docker run \
     --name pgvecto-rs-demo \
     -e POSTGRES_PASSWORD=mysecretpassword \
     -p 5432:5432 \
     -d ghcr.io/tensorchord/pgvecto-rs:pg17-v0.4.0
   

2. 连接数据库

   使用 psql 连接到本地运行的实例（默认用户：postgres，密码：mysecretpassword）：

   psql -h localhost -p 5432 -U postgres
   

3. 启用扩展

   在数据库中执行以下 SQL 命令以激活 pgvecto.rs：

   DROP EXTENSION IF EXISTS vectors;
   CREATE EXTENSION vectors;
   

基本使用

1. 创建表与向量列

pgvecto.rs 引入了 vector(n) 数据类型，其中 n 代表向量维度（$1 \leq n \leq 65535$）。

-- 创建一个包含 3 维向量列的表
CREATE TABLE items (
  id bigserial PRIMARY KEY,
  embedding vector(3) NOT NULL
);

2. 插入向量数据

可以直接插入数组格式的数据，或通过类型转换插入。

-- 直接插入
INSERT INTO items (embedding)
VALUES ('[1,2,3]'), ('[4,5,6]');

-- 或者从数组转换插入
INSERT INTO items (embedding)
VALUES (ARRAY[1, 2, 3]::real[]), (ARRAY[4, 5, 6]::real[]);

3. 执行相似度搜索

pgvecto.rs 支持三种距离运算符：

• <->: 欧几里得距离平方 (Squared Euclidean Distance)
• <#>: 负点积 (Negative Dot Product)
• <=>: 余弦距离 (Cosine Distance)

示例：查找与 [3,2,1] 最相似的 5 条记录

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

4. 进阶提示：半精度浮点数

为了减少内存占用并提升性能，您可以使用 vecf16 类型替代 vector，它存储的是 16 位浮点数，用法与 vector 完全一致。

-- 示例：使用 vecf16 创建列
CREATE TABLE items_fp16 (
  id bigserial PRIMARY KEY,
  embedding vecf16(3) NOT NULL
);