tencent cloud

云数据库 PostgreSQL

文档云数据库 PostgreSQLAI 能力向量与图检索pgvector 向量扩展使用指南

pgvector 向量扩展使用指南

下载
聚焦模式
字号
最后更新时间： 2026-06-08 10:47:55

概述

pgvector 是 PostgreSQL 的开源向量相似度搜索扩展，支持精确和近似最近邻搜索。腾讯云数据库 PostgreSQL 已预置 pgvector 0.8.x 版本，支持以下核心能力：
向量数据类型：vector（单精度）、halfvec（半精度）、sparsevec（稀疏向量）。
索引算法：HNSW（高性能）、IVFFlat（内存友好）。
距离度量：L2 欧氏距离、余弦相似度、内积、L1 曼哈顿距离。

前提条件

云数据库 PostgreSQL 实例版本 ≥ 12。
已创建数据库并具有 CREATE EXTENSION 权限。

安装与启用

-- 创建 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;

-- 验证安装
SELECT extversion FROM pg_extension WHERE extname = 'vector';

向量数据类型

vector（单精度浮点）

最常用的向量类型，每个维度占4字节。
-- 创建带向量列的表（1536 维，适配常见 Embedding 模型）
CREATE TABLE documents (
    id BIGSERIAL PRIMARY KEY,
    content TEXT NOT NULL,
    embedding vector(1536)
);

-- 插入向量数据
INSERT INTO documents (content, embedding)
VALUES ('PostgreSQL 是最先进的开源数据库', '[0.1, 0.2, 0.3, ...]'::vector(1536));
说明：
向量维度需与您使用的大模型输出维度一致。常见模型维度：OpenAI text-embedding-3-small（1536维）、BGE-M3（1024维）、ChatGLM Embedding（1024维）。

halfvec（半精度浮点）

每个维度占2字节，适合大规模向量存储（空间减半，精度损失极小）。
CREATE TABLE docs_halfvec (
    id BIGSERIAL PRIMARY KEY,
    embedding halfvec(1536)
);

sparsevec（稀疏向量）

适合高维稀疏向量（如 BM25 分数、SPLADE 输出）。
CREATE TABLE docs_sparse (
    id BIGSERIAL PRIMARY KEY,
    embedding sparsevec(30000)
);

-- 稀疏向量使用 {index:value}/dim 格式
INSERT INTO docs_sparse (embedding)
VALUES ('{1:0.5, 100:0.3, 999:0.8}/30000'::sparsevec);

距离运算符

运算符
含义
使用场景
<->
L2欧氏距离
通用相似度搜索
<=>
余弦距离
文本 / 图像嵌入（推荐）
<#>
负内积
归一化向量的最大内积搜索
<+>
L1曼哈顿距离
特殊场景
-- 余弦相似度搜索（最常用）
SELECT id, content,
       1 - (embedding <=> query_vec) AS similarity
FROM documents
ORDER BY embedding <=> query_vec
LIMIT 10;

-- L2 距离搜索
SELECT id, content
FROM documents
ORDER BY embedding <-> query_vec
LIMIT 10;

索引创建

HNSW 索引（推荐）

HNSW（Hierarchical Navigable Small World）基于图的近似搜索，查询性能高、召回率好。
-- 创建 HNSW 索引（余弦距离）
CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);

-- 创建 HNSW 索引（L2 距离）
CREATE INDEX ON documents
USING hnsw (embedding vector_l2_ops)
WITH (m = 16, ef_construction = 200);
参数说明：
参数
默认值
说明
m
16
每个节点的最大连接数，越大越精确但内存越多
ef_construction
64
构建时搜索宽度，越大构建越慢但质量越高
查询时调优：
-- 增大 ef_search 提高召回率（默认 40）
SET hnsw.ef_search = 100;

IVFFlat 索引

IVFFlat 适合对内存敏感的场景，构建速度更快。
-- 需要先有数据才能创建
CREATE INDEX ON documents
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);  -- lists 建议 = sqrt(行数)

-- 查询时设置探测数
SET ivfflat.probes = 10;

索引选择建议

场景
推荐索引
原因
数据量 < 100万
HNSW
查询快，召回率高
数据量 > 100万
磁盘友好
频繁插入更新
IVFFlat
增量成本低
对召回率要求极高
HNSW（大 ef_search）
可趋近精确搜索

实战：构建语义搜索

-- 1. 创建知识库表
CREATE TABLE knowledge_base (
    id BIGSERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    embedding vector(1024),
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 2. 创建索引
CREATE INDEX idx_kb_hnsw ON knowledge_base
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);

-- 3. 语义搜索（结合 tencentdb_ai 获取查询向量）
SELECT title, content,
       1 - (embedding <=> query_embedding) AS similarity
FROM knowledge_base,
LATERAL (
    SELECT tencentdb_ai.get_embedding('bge-m3', '什么是 PostgreSQL？')
    AS query_embedding
) q
WHERE embedding <=> query_embedding < 0.5
ORDER BY embedding <=> query_embedding
LIMIT 5;

性能调优

批量导入优化

-- 先插数据，后建索引（速度更快）
DROP INDEX IF EXISTS idx_kb_hnsw;
-- ... 批量 COPY 数据 ...
CREATE INDEX idx_kb_hnsw ON knowledge_base
USING hnsw (embedding vector_cosine_ops);

向量维度选择

模型
维度
建议场景
BGE-M3
1024
中英文通用
text-embedding-3-small
1536
OpenAI 生态
Cohere embed-v3
1024
多语言
自定义降维
256 – 512
超大规模数据

注意事项

同一列向量维度必须相同。
数据量 < 1000行时全表扫描可能更快。
NULL 向量不会被索引收录。
HNSW 索引支持并发读写。
向量列建议设置 NOT NULL 约束。

相关文档

pgvectorscale（DiskANN）高性能向量检索。
tencentdb_ai 插件功能介绍。
Apache AGE 图数据库使用指南。
pgvector 官方 GitHub。
上一篇: pgvectorscale（DiskANN）高性能向量检索下一篇: Apache AGE 图数据库使用指南

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈