pgvector怎么用 PostgreSQL向量扩展教程

pgvector是PostgreSQL的向量检索扩展，装好之后就能在熟悉的PostgreSQL里存向量、做相似度搜索，不用额外搭数据库。向量通常由文本、图片等内容经过嵌入模型生成；pgvector负责保存它们，并按距离找出最接近的结果。下面从安装、建表到查询走一遍，示例使用余弦距离，维度请按你所用模型的输出调整。

第一步：安装和启用pgvector

先确认数据库版本和安装方式。自建数据库可按操作系统及PostgreSQL版本安装对应的pgvector软件包，也可以从项目源码编译；托管数据库则先查看扩展是否已提供。安装软件包只是让服务器具备扩展文件，真正使用前还要在目标数据库中启用它。不同发行版的包名和安装命令可能不同，照着当前环境的说明操作更稳妥。

连接到要使用的数据库，执行：CREATE EXTENSION IF NOT EXISTS vector;。这里扩展名称是vector，不是pgvector。通常需要数据库管理员或具备相应权限的账号来创建扩展。执行后可用：SELECT extname FROM pg_extension WHERE extname = ‘vector’; 检查是否启用成功。若提示找不到控制文件或扩展文件，说明服务器端尚未正确安装，单纯在SQL里执行命令解决不了。

第二步：建向量表和索引

先准备内容字段和向量字段。假设嵌入模型输出1536维，可以这样建表：CREATE TABLE documents (id bigserial PRIMARY KEY, content text NOT NULL, embedding vector(1536));。vector(1536)会约束每条向量的维度；如果模型输出不是1536维，就把数字改成实际值。保存文本和向量在同一行，后续可以直接把检索结果与原文一起取出。

接下来建索引。初学或数据量不大时，先不建索引也能查询，数据库会逐行计算距离，结果是精确近邻，但数据变多后可能变慢。需要加速时，可先试HNSW：CREATE INDEX documents_embedding_hnsw ON documents USING hnsw (embedding vector_cosine_ops);。索引使用的操作符类别必须和查询距离匹配；余弦距离用vector_cosine_ops。

选择距离类型和索引方式

常见操作符包括<->（欧氏距离）、<=>（余弦距离）和<#>（负内积）。距离越小通常表示越相近；内积操作符返回负值，升序排列可取较大的内积结果。文本嵌入常用余弦距离，但应以模型的建议和业务评估为准。HNSW通常便于直接上手，查询速度与召回效果的权衡较好，但构建较慢、占用内存较多。

另一种是IVFFlat：CREATE INDEX documents_embedding_ivf ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);。它通常建得较快、内存占用较少，但应先写入一批数据再建索引，并根据数据量调lists与查询时的probes。两种索引不必一开始都建；先用真实数据测试延迟和召回，再决定选择与参数。创建索引后也可用EXPLAIN检查查询计划。

第三步：写入向量并查询

写入时，向量必须来自模型生成，元素数量要和列维度一致。示例：INSERT INTO documents (content, embedding) VALUES (‘介绍向量搜索’, ‘[0.12, -0.08, 0.31]’::vector);。这组示例只有三个数，因此只适用于vector(3)列；若表定义为1536维，就要传入1536个数。实际项目中建议使用数据库驱动的参数化查询，不要拼接用户输入的SQL。

查询时，把待检索内容先送入同一个嵌入模型，得到与表中维度一致的查询向量，再执行：SELECT id, content, embedding <=> ‘[0.10, -0.05, 0.28]’::vector AS distance FROM documents ORDER BY embedding <=> ‘[0.10, -0.05, 0.28]’::vector LIMIT 5;。这里向量仅为三维演示，真实查询要换成模型输出。ORDER BY使用距离运算符、再配合LIMIT，是向量索引发挥作用的常见写法。

如果结果不够相关，可检查模型、维度、距离类型是否一致，并调整索引搜索参数；用HNSW时可尝试提高hnsw.ef_search，通常能改善召回但可能增加耗时。也别忘了过滤条件：先按业务字段限制候选数据，再检查执行计划和实际效果。开发阶段可以不建近似索引，和索引查询结果对照，评估速度与召回之间的取舍。

如果想先用现成工具搭建应用，再接入自己的数据流程，也可以了解码上飞：codeflying.cgref.cn。实践时建议先用少量数据完成端到端验证，再逐步增加数据并观察查询表现；润灭也可作为查阅开发实践内容的入口