pgvector怎么用？从向量入库到相似度查询与索引选择的入门指南

一、安装扩展，创建向量列

目标是保存产品说明段落，再找出与用户问题最接近的内容。先按官方README选择适合操作系统和PostgreSQL环境的安装方式；源码安装需在源码目录执行make及make install。托管数据库则先确认服务商支持该扩展。服务器安装完成后，在目标数据库执行以下SQL；CREATE EXTENSION不是下载或安装系统软件包的命令。([github.com](https://github.com/pgvector/pgvector))

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE product_chunks (id bigserial PRIMARY KEY, doc_id text NOT NULL, content text NOT NULL, embedding vector(3) NOT NULL);

vector(3)将该列限定为三维，不能插入其他维度的向量。下面使用手写三维数据，只验证数据库流程，不代表真实语义效果。正式接入时，应按嵌入模型输出维度建列。([github.com](https://github.com/pgvector/pgvector))

二、保存文档标识、正文和向量

INSERT INTO product_chunks (doc_id, content, embedding) VALUES ('manual-export', '管理员可以在报表页面导出数据。', '[1,0,0]'), ('manual-access', '管理员可以为成员分配访问权限。', '[0,1,0]'), ('manual-backup', '系统支持备份和恢复业务数据。', '[0,0,1]');

真实项目中，可先把内部产品说明切成段落，由应用调用嵌入模型，再将段落、来源标识和模型返回的向量一并写入。用户提问时，使用与入库一致的模型、版本和向量处理配置生成查询向量；仅仅维度相同，不足以证明两个模型的向量可以比较。

三、先跑精确检索，建立基线

暂不创建近似索引。假设演示查询向量为[0.9,0.1,0]，执行：

SELECT id, doc_id, content, embedding '[0.9,0.1,0]'::vector AS distance FROM product_chunks ORDER BY embedding '[0.9,0.1,0]'::vector ASC LIMIT 2;

这里按余弦距离升序取前两条，演示数据中导出说明排在最前。pgvector默认执行精确最近邻检索；保留这次查询的结果标识，后续可与近似检索比较。需要展示余弦相似度时，可计算1减去余弦距离，但用于索引检索的排序仍保留距离表达式。([github.com](https://github.com/pgvector/pgvector))

距离运算符不要混用

• 欧氏距离：，升序；对应vector_l2_ops。
• 内积：返回负内积，升序相当于原始内积降序；对应vector_ip_ops。
• 余弦距离：，升序；对应vector_cosine_ops。

查询距离和索引操作符类必须配套，不能给余弦查询配置欧氏距离操作符类，并期待它承担同一种索引检索。([github.com](https://github.com/pgvector/pgvector))

四、数据增多后再选择索引

三条演示数据无需近似索引。使用真实数据评估时，可以先试HNSW：

CREATE INDEX product_chunks_cos_hnsw ON product_chunks USING hnsw (embedding vector_cosine_ops);

HNSW无需训练，可以在空表建索引；相比IVFFlat，通常需要更多内存和更长构建时间。IVFFlat先将向量分组，再搜索部分分组，适合已有代表性数据、需要权衡构建成本的场景。两者都不保证完整召回。([github.com](https://github.com/pgvector/pgvector))

若单独测试IVFFlat，可使用以下建索引语句替代HNSW方案，而非在小样本上同时创建两种索引：

CREATE INDEX product_chunks_cos_ivf ON product_chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

100只是配置示例，不适合直接套用到三条数据。lists决定分组数量，查询时ivfflat.probes决定探查多少组；HNSW则可通过hnsw.ef_search调整搜索候选列表大小。增加搜索范围通常有利于召回，但也增加查询开销，应与精确基线一起测试。([github.com](https://github.com/pgvector/pgvector))

五、业务过滤也会影响结果

限定某份文档时，在前面的查询中加入WHERE doc_id = 'manual-export'。近似索引扫描后再过滤，可能使返回条数少于LIMIT，即使表中存在足够的匹配记录。可评估提高搜索范围、为过滤列建普通索引，或使用当前扩展版本支持的迭代扫描；固定业务子集也可考虑部分索引。([github.com](https://github.com/pgvector/pgvector))

上线前使用EXPLAIN (ANALYZE, BUFFERS)检查实际执行计划，不要把“已建索引”当成“查询已使用索引”。选取真实问题，在相同过滤条件下比较精确与近似结果，再决定索引和参数；SQL跑通与语义检索有效，需要分别验证。