pgvector怎么用 PostgreSQL向量扩展教程

pgvector是PostgreSQL的向量检索扩展，装好之后就能在熟悉的PostgreSQL里存向量、做相似度搜索，不用额外搭数据库。它适合语义检索、推荐和RAG等场景：先用嵌入模型把文本转成数字向量，再让数据库按距离找出最相近的内容。本文用余弦距离演示从安装到查询的基本流程。

第一步：安装和启用pgvector

先确认PostgreSQL版本和部署方式，再安装与数据库版本匹配的pgvector。使用托管数据库时，先查看服务是否已提供该扩展；自建环境则按系统包管理器或项目说明安装。安装扩展程序只是准备工作，后面还要在每个需要存向量的数据库里启用它，不能只在服务器上装完就直接创建vector列。

连接目标数据库后执行 CREATE EXTENSION IF NOT EXISTS vector;。注意扩展名是vector，不是pgvector；重复执行也不会因为已安装而报错。可用 SELECT extname, extversion FROM pg_extension WHERE extname = ‘vector’; 检查是否启用并查看版本。如果提示找不到扩展，通常需要先在服务器安装对应组件，或确认当前托管服务支持它。

第二步：建向量表和索引

向量维度必须和生成嵌入时的模型输出一致。下面用1536维举例，实际使用时请替换为模型的真实维度；文档正文和向量放在同一行，便于检索结果直接返回原文。执行建表语句后，可先插入少量测试数据，再检查字段类型与数据是否符合预期。

例如创建一张文档表：CREATE TABLE documents (id bigserial PRIMARY KEY, content text NOT NULL, embedding vector(1536));。其中content存文本，embedding存向量。若模型输出不是1536维，就把括号中的数字改成实际维数。向量不是随手编写的文本特征，通常由嵌入模型生成；入库时要确保每条向量长度一致，并与列定义匹配。

选择距离类型和索引方式

先确定业务要用哪种距离。余弦距离常用于语义嵌入，查询运算符是 <=>，对应索引操作类 vector_cosine_ops；L2欧氏距离用 <->，内积用 <#>。索引操作类要和查询距离匹配，否则索引可能无法用于预期的检索。

数据量较大时可建HNSW近似索引：CREATE INDEX documents_embedding_hnsw ON documents USING hnsw (embedding vector_cosine_ops);。它通常查询较快，但会用更多内存，建索引也可能更慢。IVFFlat则适合希望控制内存、且已有一定数据量的场景；它需要先有数据再建索引，列表数和查询探测数还要结合数据规模调节。

• HNSW：不要求先训练聚类，可在空表建索引；常作为优先测试的近似检索方案，但要留意内存和建索引成本。
• IVFFlat：建索引快、占用内存较少，通常先写入数据再建；增加探测列表数有助于提高召回，但可能降低速度。
• 如果数据量还不大，先直接查询并观察性能；pgvector默认可执行精确最近邻搜索，结果召回完整，未必一开始就需要近似索引。

第三步：写入向量并查询

将内容和对应嵌入一并写入。比如：INSERT INTO documents (content, embedding) VALUES (‘介绍数据库向量检索’, ‘[0.12, -0.08, 0.31]’);。这里的短向量只是展示格式，不能直接插入前面定义的1536维列；真实示例中的数组必须有1536个数。应用程序通常先调用嵌入模型，再用参数化SQL把文本和向量写入数据库。

查询时，用同一嵌入模型把用户问题转为向量，再按余弦距离排序：SELECT id, content, embedding <=> ‘[…]’ AS distance FROM documents ORDER BY embedding <=> ‘[…]’ LIMIT 5;。把两处省略号替换为实际查询向量。距离越小，向量越接近。为了让近似索引有机会生效，排序应直接使用距离运算符并配合LIMIT；不要把距离改写成相似度表达式再排序。

落地时建议先用小批数据验证维度、距离选择和返回内容，再用真实规模测试查询耗时与召回质量。若检索还需要关键词、分类或权限条件，可在SQL中结合常规字段过滤；上线前检查执行计划，确认索引是否被采用。面向国内用户构建AI应用时，也可了解码上飞这一替代方案；官网地址：codeflying.cgref.cn。本文由润灭整理。