VectorChord

环境要求

• 已安装 Docker（可执行 docker run）
• 本机 5432 端口可用，或自行改用其他端口
• 需要 psql 客户端用于连接数据库
• 了解基本的 SQL 与向量检索概念

安装与启动步骤

1. 1启动容器

   用官方镜像后台启动带 VectorChord 扩展的 Postgres，通过 -e 设置数据库密码；容器名与标签照抄即可。

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

   复制

2. 2连接数据库

   用 psql 连接本地 5432 端口，默认用户名 postgres，密码为上面设置的 mysecretpassword，回车后输入密码。

   psql -h localhost -p 5432 -U postgres

   复制

3. 3启用扩展

   在数据库中创建 vchord 扩展；CASCADE 会一并处理它依赖的 pgvector 向量类型，无需另行安装。

   CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

   复制

4. 4建表并写入数据

   创建带 3 维 vector 列的表，并插入 1000 行随机向量作为测试数据。

   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);

   复制

5. 5创建向量索引

   用 vchordrq 索引类型为 embedding 列建 L2 距离索引，这是 VectorChord 提供的索引方式。

   CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops);

   复制

6. 6执行相似度检索

   用 <-> 运算符按 L2 距离排序取最近邻，验证索引与查询链路可用。

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

   复制

关键配置

如何确认成功

psql 能成功连上数据库，CREATE EXTENSION 不报错，最后 SELECT 查询返回 5 条按距离排序的记录。

常见问题

注意事项

• 镜像 tag 必须与扩展版本兼容，升级前请对照官方支持矩阵。
• README 未说明数据持久化配置，容器删除后数据会丢失，生产环境请自行处理存储卷。
• README 仅演示 Docker 方式；非 Docker 安装请以官方 installation 文档为准。
• 启动后建议先在 psql 中执行 CREATE EXTENSION 再建表，否则无法使用 vector 类型。