这是本节的多页打印视图。 .

快速入门

pgvecto.rs 的简介与安装指南。

1: 概览
2: 安装

1 - 概览

pgvecto.rs 简介。

警告

我们强烈建议您探索全新的 VectorChord 实现，它提供了更高的稳定性和性能。建议用户迁移至 VectorChord，详情请参考迁移指南。

pgvecto.rs 简介。

什么是 `pgvecto.rs`

pgvecto.rs 是一个提供向量相似度搜索功能的 Postgres 扩展。它使用 Rust 编写，基于 pgrx 构建。目前处于测试（Beta）阶段，诚邀您在生产环境中试用并向我们提供反馈。更多信息请参阅📝我们的发布博客。

与 pgvector 的对比

查看 pgvecto.rs vs pgvector 了解更多详情。

特性	pgvecto.rs	pgvector
过滤（Filtering）	引入 VBASE 方法，将向量搜索与关系查询统一（例如：单向量 TopK + 过滤 + 连接）。	应用过滤条件时，返回结果可能不完整。例如，原本希望限制返回 10 条结果，加上过滤后可能最终只得到 5 条结果。
向量维度	最高支持 65535 维。	最高支持 2000 维。
SIMD	在运行时动态分派 SIMD 指令，根据具体机器的硬件能力最大化性能。	在 0.7.0 版本中为 Linux x86-64 增加了距离函数的 CPU 动态分派。
数据类型	引入额外的数据类型：二值向量（binary vector）、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 tensorchord/pgvecto-rs:pg16-v0.2.0

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

psql postgresql://postgres:mysecretpassword@localhost:5432/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 维
);

详情

仅当 $1 \leq n \leq 65535$ 时，vector(n) 才是有效的数据类型。受限于 PostgreSQL 的机制，您有可能在 vector(3) 类型的列中存入 $5$ 维的值，而且不带维度的 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[]);

我们支持三种用于计算两个向量之间距离的操作符：

<->：平方欧氏距离（Squared Euclidean distance），定义为 $\Sigma (x_i - y_i) ^ 2$ 。
<#>：负点积（Negative dot product），定义为 $- \Sigma x_iy_i$ 。
<=>：余弦距离（Cosine distance），定义为 $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;

简单的问答（Question-Answering）应用

请查看问答应用教程。

半精度浮点数

vecf16 类型除了标量元素类型外，其余与 vector 完全一致。它存储 16 位浮点数。如果您希望减少内存占用以获得更好的性能，可以尝试将 vector 类型替换为 vecf16 类型。

关于 vecf16 的更多用法，请参考向量类型。

稀疏向量

svector 类型是稀疏向量类型。它以稀疏格式存储向量，非常适合包含大量零元素的向量。

关于 svector 的更多用法，请参考向量类型。

二值向量

bvector 类型是二值向量类型，本质上是定长位串（bit string）。除了上述 3 种距离外，我们还支持 jaccard 距离 <~>，其定义为 $1 - \frac{|X\cap Y|}{|X\cup Y|}$ 。而汉明距离（hamming distance）与平方欧氏距离等价，您可以使用 <-> 操作符来计算。此外，我们还提供了 binarize 函数，用于从 vector 构造 bvector（将正数元素设为 1，其余设为 0）。

关于 bvector 的更多用法，请参考向量类型。

路线图 🗂️

请查看路线图（ROADMAP）。

参与贡献 😊

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

加入我们的 Discord 社区！
如需从源码构建，请阅读我们的贡献指南和开发教程。

与我们交流

💬 有兴趣与我们聊聊您在构建或管理 AI/ML 应用方面的经验吗？

预约交流时间！

2 - 安装

安装 pgvecto.rs 的四种方式。

警告

我们强烈建议您探索全新的 VectorChord 实现，它提供了更高的稳定性和性能。建议用户迁移至 VectorChord，详情请参考迁移指南。

安装 pgvecto.rs 有四种方式。

Docker

试用 pgvecto.rs 最简单的方式是直接运行开箱即用的 Docker 镜像。

docker run \
  --name pgvecto-rs-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d tensorchord/pgvecto-rs:pg16-v0.2.0

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

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

运行以下 SQL 确保扩展已启用：

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;

为了获得完整性能，请添加类似 -v $PWD/pgdata:/var/lib/postgresql/data 的选项，将数据卷挂载到 PostgreSQL 数据目录。

您可以参考父镜像文档 https://hub.docker.com/_/postgres/ 来配置 PostgreSQL。

使用 Debian 软件包安装

提示

从 Debian 软件包安装需要依赖 GLIBC >= 2.31，例如：

Ubuntu 20.04 或更高版本
Debian Bullseye 或更高版本

Debian 软件包（.deb）适用于基于 Debian 的发行版（如 Ubuntu 等），可以通过 dpkg 或 apt-get 轻松安装。

在 Release 页面下载 .deb 软件包，并执行 sudo apt install vectors-pg15-*.deb 进行安装。
修改 shared_preload_libraries 和 search_path 以包含该扩展，从而完成 PostgreSQL 配置。

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vectors.so"'
psql -U postgres -c 'ALTER SYSTEM SET search_path TO "$user", public, vectors'
# 需要重启 PostgreSQL 集群以使配置生效。
sudo systemctl restart postgresql.service   # 适用于通过 systemd 运行的 pgvecto.rs

连接到数据库并启用扩展。

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;

使用 ZIP 压缩包安装

since v0.2.1

提示

从 ZIP 压缩包安装需要依赖 GLIBC >= 2.31，例如：

RHEL 9 或更高版本

对于非 Debian 系且无法运行 Docker 容器的系统，请按以下步骤安装：

安装前，请确保已安装必要的软件包，包括 PostgreSQL、pg_config、unzip 和 wget。

# RHEL 9 dnf 示例
# 请根据您的包管理器进行检查
sudo dnf install -y unzip wget libpq-devel
sudo dnf module install -y postgresql:15/server
sudo postgresql-setup --initdb
sudo systemctl start postgresql.service
sudo systemctl enable postgresql.service

验证 PostgreSQL 是否已设置 $pkglibdir 和 $shardir。

pg_config --pkglibdir
# 输出类似于：
# /usr/lib/postgresql/15/lib 或
# /usr/lib64/pgsql

pg_config --sharedir
# 输出类似于：
# /usr/share/postgresql/15 或
# /usr/share/pgsql

在 Release 页面下载 zip 压缩包并解压到临时目录。

wget https://github.com/tensorchord/pgvecto.rs/releases/download/v0.2.1/vectors-pg15_x86_64-unknown-linux-gnu_0.2.1.zip -O vectors.zip
unzip vectors.zip -d vectors

将扩展文件复制到 PostgreSQL 目录。

# 将动态库复制到 `$pkglibdir`
sudo cp vectors/vectors.so $(pg_config --pkglibdir)/
# 将 schema 文件复制到 `$shardir`
sudo cp vectors/vectors--* $(pg_config --sharedir)/extension/
sudo cp vectors/vectors.control $(pg_config --sharedir)/extension/

修改 shared_preload_libraries 和 search_path 以包含该扩展，从而完成 PostgreSQL 配置。

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vectors.so"'
psql -U postgres -c 'ALTER SYSTEM SET search_path TO "$user", public, vectors'
# 需要重启 PostgreSQL 集群以使配置生效。
sudo systemctl restart postgresql.service   # 适用于通过 systemd 运行的 pgvecto.rs

连接到数据库并启用扩展。

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;

从源码构建安装

在从源码构建之前，您可以参考开发指南配置开发环境。

构建并安装扩展：

sed -e "s/@CARGO_VERSION@/0.0.0/g" ./vectors.control  # 这里的 0.0.0 是您所需的版本号
sudo cp -a ./sql/upgrade/. $(pg_config --sharedir)/extension
cargo pgrx install --sudo --release

修改 shared_preload_libraries 和 search_path 以包含该扩展，从而完成 PostgreSQL 配置。

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vectors.so"'
psql -U postgres -c 'ALTER SYSTEM SET search_path TO "$user", public, vectors'
# 需要重启 PostgreSQL 集群以使配置生效。
sudo systemctl restart postgresql.service   # 适用于通过 systemd 运行的 pgvecto.rs
service postgresql restart  # 适用于在 envd 中运行的 pgvecto.rs

连接到数据库并启用扩展。

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;