一、概述
·向量数据类型：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 similarityFROM documentsORDER BY embedding <=> query_vecLIMIT 10;– L2 距离搜索SELECT id, contentFROM documentsORDER BY embedding <-> query_vecLIMIT 10;
八、HNSW 索引（推荐）
HNSW（Hierarchical Navigable Small World）基于图的近似搜索，查询性能高、召回率好。
— 创建 HNSW 索引（余弦距离）CREATE INDEX ON documentsUSING hnsw (embedding vector_cosine_ops)WITH (m = 16, ef_construction = 200);– 创建 HNSW 索引（L2 距离）CREATE INDEX ON documentsUSING 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 documentsUSING ivfflat (embedding vector_cosine_ops)WITH (lists = 100); — lists 建议 = sqrt(行数)– 查询时设置探测数SET ivfflat.probes = 10;
十、索引选择建议
| 场景 | 推荐索引 | 原因 |
| 数据量 < 100万 | HNSW | 查询快，召回率高 |
| 数据量 > 100万 | pgvectorscale（DiskANN） | 磁盘友好 |
| 频繁插入更新 | 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_baseUSING hnsw (embedding vector_cosine_ops)WITH (m = 16, ef_construction = 200);– 3. 语义搜索（结合 tencentdb_ai 获取查询向量）SELECT title, content, 1 – (embedding <=> query_embedding) AS similarityFROM knowledge_base,LATERAL ( SELECT tencentdb_ai.get_embedding('bge-m3', '什么是 PostgreSQL？') AS query_embedding) qWHERE embedding <=> query_embedding < 0.5ORDER BY embedding <=> query_embeddingLIMIT 5;
十二、批量导入优化
— 先插数据，后建索引（速度更快）DROP INDEX IF EXISTS idx_kb_hnsw;– … 批量 COPY 数据 …CREATE INDEX idx_kb_hnsw ON knowledge_baseUSING 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。