纲要
PostgreSQL+pgvector扩展实现向量数据存储与语义检索- 向量相似度计算:
内积、余弦距离、欧几里得距离 IVFFlat索引的创建与参数调优KNN与ANN检索原理及召回率影响RAG系统三阶段:Embedding、Retrieval、Generation- 执行计划分析:
Index Scan与Sequential Scan pgvector索引参数:lists、probes
从关键词匹配到语义检索
传统搜索系统依赖关键词匹配,例如使用 LIKE 或全文索引进行内容查找。这种方式只能匹配文本的字面形式,无法理解用户查询背后的真实语义。
-- 传统关键词匹配方式
SELECT * FROM knowledge_base WHERE content LIKE '%查询性能%';
当用户提问 “数据库运行缓慢,如何优化” 或 “如何提升 PostgreSQL 的查询速度” 时,若知识库中存储的是 “PostgreSQL 索引优化技巧”,传统关键词匹配将无法命中。语义检索通过将文本转换为向量,计算向量间的距离来度量语义相似度,从根本上解决了这一问题。
PostgreSQL 配合 pgvector 扩展,提供完整的向量存储与检索能力,成为构建语义检索系统的理想基座。
测试数据准备
以下示例构建一个简单的知识库表 knowledge_base,用于存储知识片段及其对应的向量表示。
-- 启用 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;
-- 创建知识库表
CREATE TABLE knowledge_base (
id BIGSERIAL PRIMARY KEY,
content TEXT NOT NULL,
embedding VECTOR(768)
);
-- 插入测试数据(此处使用随机向量模拟真实模型生成的 embedding)
INSERT INTO knowledge_base (content, embedding) VALUES
('PostgreSQL 索引优化技巧', (SELECT ARRAY(SELECT random()::REAL FROM generate_series(1, 768))::VECTOR(768))),
('数据库连接池配置指南', (SELECT ARRAY(SELECT random()::REAL FROM generate_series(1, 768))::VECTOR(768))),
('查询计划分析与调优', (SELECT ARRAY(SELECT random()::REAL FROM generate_series(1, 768))::VECTOR(768))),
('事务隔离级别详解', (SELECT ARRAY(SELECT random()::REAL FROM generate_series(1, 768))::VECTOR(768))),
('PostgreSQL 分区表使用实践', (SELECT ARRAY(SELECT random()::REAL FROM generate_series(1, 768))::VECTOR(768)));
在真实系统中,embedding 向量通常通过 Embedding 模型(如 text-embedding-ada-002、BGE 等)生成,维度通常为 768、1536 或更高。
基于距离的相似度检索
语义检索的核心是计算向量之间的相似度。pgvector 支持多种距离度量方式:
| 距离函数 | 说明 | 使用场景 |
|---|---|---|
<-> | 欧几里得距离(L2) | 适合低维向量 |
<=> | 余弦距离 | 适合高维语义向量 |
<#> | 负内积 | 适合内积相似度 |
以下示例演示如何将用户问题转换为向量,并检索最相似的三条知识片段。
-- 模拟用户问题 "如何提高 PostgreSQL 的查询性能"
-- 实际场景中需通过模型将问题转为向量,此处使用随机向量模拟
WITH question_embedding AS (
SELECT ARRAY(SELECT random()::REAL FROM generate_series(1, 768))::VECTOR(768) AS q_vec
)
SELECT
content,
embedding <=> (SELECT q_vec FROM question_embedding) AS distance
FROM knowledge_base
ORDER BY distance ASC
LIMIT 3;
ORDER BY distance ASC 表示按距离升序排列,距离越小则语义越相似。
向量索引的创建与执行计划分析
随着数据量增长,全表扫描(顺序扫描)会带来严重的性能瓶颈。pgvector 支持创建 IVFFlat 索引以加速向量检索。
创建 IVFFlat 索引
-- 在 embedding 列上创建 IVFFlat 索引
-- lists 参数表示聚类中心数量,通常建议设置为 行数 / 1000
CREATE INDEX idx_knowledge_base_embedding ON knowledge_base
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
索引扫描与顺序扫描对比
-- 启用执行计划分析
EXPLAIN ANALYZE
SELECT
content,
embedding <=> (SELECT ARRAY(SELECT random()::REAL FROM generate_series(1, 768))::VECTOR(768)) AS distance
FROM knowledge_base
ORDER BY distance ASC
LIMIT 3;
当使用索引扫描(Index Scan)时,可能看到类似如下的执行计划:
Limit (cost=... rows=...)
-> Index Scan using idx_knowledge_base_embedding on knowledge_base
Order By: (embedding <=> ...)
IVFFlat 的 probes 参数与召回率调优
IVFFlat 是一种近似最近邻(ANN)索引,其检索过程并非精确的 KNN,而是通过聚类近似加速。probes 参数决定检索时扫描的聚类数量,直接影响召回率。
-- 设置 probes 参数(会话级别)
SET ivfflat.probes = 10;
| probes 值 | 扫描聚类数 | 召回率表现 |
|---|---|---|
| 1(默认) | 1 个聚类 | 召回率较低,可能遗漏相似向量 |
| 10 | 10 个聚类 | 召回率提升 |
| 30 | 30 个聚类 | 召回率更高 |
| 50 | 50 个聚类 | 接近 100% 召回率 |
当 probes=1(默认值)时,IVFFlat 仅随机检索一个聚类。若目标向量不在该聚类中,则不会返回任何结果(即召回率为 0)。增大 probes 值可显著提升召回率,但会相应增加查询耗时。实际生产中需根据业务场景在性能与召回率之间权衡。
RAG 智能问答系统架构
一个完整的 RAG(检索增强生成)系统通常包含三个核心阶段:
Embedding 阶段
用户问题和知识库内容分别经过 Embedding 模型处理,转换为固定维度的向量。
- 知识库内容 → 向量 → 存储于
PostgreSQL的VECTOR字段 - 用户问题 → 向量 → 用于检索匹配
Retrieval 阶段
系统将用户问题的向量作为查询条件,执行语义检索:
-- 假设用户问题向量为 q_vec
SELECT content, embedding <=> q_vec AS distance
FROM knowledge_base
ORDER BY distance ASC
LIMIT 3;
PostgreSQL 借助 pgvector 索引快速返回最相似的 Top-K 知识片段。
Generation 阶段
系统将用户问题与检索到的知识片段合并为上下文,提交给大模型生成最终答案。此阶段类似 “开卷考试”,模型在具备相关知识背景的前提下生成回答,有效避免幻觉(Hallucination)问题。
API 速览
本节梳理 pgvector 涉及的核心 API。
CREATE EXTENSION
启用 pgvector 扩展。
CREATE EXTENSION IF NOT EXISTS vector;
VECTOR 数据类型
声明向量列,需指定维度。
-- 声明 768 维向量列
embedding VECTOR(768)
向量距离操作符
| 操作符 | 说明 |
|---|---|
<=> | 余弦距离 |
<-> | 欧几里得距离 |
<#> | 负内积 |
-- 余弦距离检索
SELECT * FROM table ORDER BY embedding <=> '[...]'::VECTOR LIMIT 10;
-- 欧几里得距离检索
SELECT * FROM table ORDER BY embedding <-> '[...]'::VECTOR LIMIT 10;
IVFFlat 索引创建
CREATE INDEX index_name ON table_name
USING ivfflat (column_name vector_cosine_ops)
WITH (lists = 100);
lists: 聚类中心数量,建议设为rows / 1000vector_cosine_ops: 余弦距离操作符类
probes 参数设置
-- 会话级别设置
SET ivfflat.probes = 10;
-- 事务级别设置
BEGIN;
SET LOCAL ivfflat.probes = 30;
SELECT ...;
COMMIT;
执行计划分析
EXPLAIN (ANALYZE, BUFFERS, COSTS)
SELECT ...;
Demo 简单示例
以下基于 Node.js 与 pg 驱动构建一个完整的语义检索 Demo。
项目结构
postgres-rag-demo
├── package.json
├── .env
├── init.sql
└── index.js
运行说明
- 安装依赖
npm init -y
npm install pg dotenv
- 配置
.env文件
PG_HOST=localhost
PG_PORT=5432
PG_DATABASE=testdb
PG_USER=postgres
PG_PASSWORD=yourpassword
- 执行初始化 SQL(
init.sql)
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS knowledge_base (
id BIGSERIAL PRIMARY KEY,
content TEXT NOT NULL,
embedding VECTOR(768)
);
CREATE INDEX IF NOT EXISTS idx_kb_embedding ON knowledge_base
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 10);
- 运行 Demo
node index.js
核心代码(index.js)
const { Client } = require('pg');
require('dotenv').config();
// 生成随机 768 维向量(模拟 Embedding 模型输出)
function randomVector(dims = 768) {
const arr = [];
for (let i = 0; i < dims; i++) {
arr.push(Math.random());
}
return '[' + arr.join(',') + ']';
}
async function main() {
const client = new Client({
host: process.env.PG_HOST,
port: process.env.PG_PORT,
database: process.env.PG_DATABASE,
user: process.env.PG_USER,
password: process.env.PG_PASSWORD,
});
await client.connect();
// 1. 插入测试数据(模拟知识库文档)
const docs = [
'PostgreSQL 索引优化技巧',
'数据库连接池配置指南',
'查询计划分析与调优',
'事务隔离级别详解',
'PostgreSQL 分区表使用实践',
];
for (const content of docs) {
const vec = randomVector(768);
await client.query(
'INSERT INTO knowledge_base (content, embedding) VALUES ($1, $2::VECTOR)',
[content, vec]
);
}
console.log('✅ 插入测试数据完成');
// 2. 设置 probes 参数,提高召回率
await client.query('SET ivfflat.probes = 10');
// 3. 模拟用户问题,生成随机查询向量
const queryVec = randomVector(768);
const res = await client.query(
`SELECT content, embedding <=> $1::VECTOR AS distance
FROM knowledge_base
ORDER BY distance ASC
LIMIT 3`,
[queryVec]
);
console.log('📝 检索结果:');
for (const row of res.rows) {
console.log(` - ${row.content} (距离: ${row.distance.toFixed(4)})`);
}
await client.end();
}
main().catch(console.error);
技术点总结
- 使用
pgvector的VECTOR类型存储高维向量 - 通过余弦距离操作符
<=>计算语义相似度 - 通过
SET ivfflat.probes动态调整召回率 - 使用
LIMIT实现 Top-K 语义检索 - 完整演示了从数据入库到查询的全流程
对应的 PostgreSQL 原生指令
-- 插入文档
INSERT INTO knowledge_base (content, embedding)
VALUES ('PostgreSQL 索引优化技巧', '[0.1,0.2,...]'::VECTOR);
-- 设置 probes
SET ivfflat.probes = 10;
-- 语义检索
SELECT content, embedding <=> '[0.3,0.4,...]'::VECTOR AS distance
FROM knowledge_base
ORDER BY distance ASC
LIMIT 3;
多语言示例
Go
运行说明
- 安装 Go 1.19+ 和 PostgreSQL(已启用 pgvector)
- 创建项目目录并初始化模块:
mkdir pgvector-go-demo && cd pgvector-go-demo
go mod init pgvector-go-demo
- 安装依赖:
go get github.com/lib/pq
- 配置数据库连接信息(修改下方代码中的 DSN)
- 运行:
go run main.go
代码说明
本示例使用 database/sql 标准库和 github.com/lib/pq 驱动,实现与 PostgreSQL 的交互。核心流程包括:
- 创建
knowledge_base表,包含VECTOR(768)列 - 使用随机向量模拟嵌入数据插入
- 设置
ivfflat.probes参数提升召回率 - 执行余弦距离检索,返回 Top-3 结果
代码示例(main.go)
package main
import (
"database/sql"
"fmt"
"math/rand"
"strings"
"time"
_ "github.com/lib/pq"
)
const (
host = "localhost"
port = 5432
user = "postgres"
password = "yourpassword"
dbname = "testdb"
)
func randomVector(dim int) string {
vals := make([]string, dim)
for i := 0; i < dim; i++ {
vals[i] = fmt.Sprintf("%f", rand.Float64())
}
return "[" + strings.Join(vals, ",") + "]"
}
func main() {
rand.Seed(time.Now().UnixNano())
dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=disable",
host, port, user, password, dbname)
db, err := sql.Open("postgres", dsn)
if err != nil {
panic(err)
}
defer db.Close()
// 创建表
_, err = db.Exec(`
CREATE TABLE IF NOT EXISTS knowledge_base (
id BIGSERIAL PRIMARY KEY,
content TEXT NOT NULL,
embedding VECTOR(768)
)
`)
if err != nil {
panic(err)
}
// 插入测试数据
docs := []string{
"PostgreSQL 索引优化技巧",
"数据库连接池配置指南",
"查询计划分析与调优",
"事务隔离级别详解",
"PostgreSQL 分区表使用实践",
}
for _, content := range docs {
vec := randomVector(768)
_, err = db.Exec(
"INSERT INTO knowledge_base (content, embedding) VALUES ($1, $2::VECTOR)",
content, vec,
)
if err != nil {
panic(err)
}
}
fmt.Println("✅ 插入测试数据完成")
// 设置 probes 参数
_, err = db.Exec("SET ivfflat.probes = 10")
if err != nil {
panic(err)
}
// 模拟查询向量
queryVec := randomVector(768)
rows, err := db.Query(`
SELECT content, embedding <=> $1::VECTOR AS distance
FROM knowledge_base
ORDER BY distance ASC
LIMIT 3
`, queryVec)
if err != nil {
panic(err)
}
defer rows.Close()
fmt.Println("📝 检索结果:")
for rows.Next() {
var content string
var distance float64
if err := rows.Scan(&content, &distance); err != nil {
panic(err)
}
fmt.Printf(" - %s (距离: %.4f)\n", content, distance)
}
}
技术点总结
- 使用
lib/pq驱动连接 PostgreSQL,支持VECTOR类型参数传递 - 通过
$1::VECTOR显式类型转换传递向量参数 - 动态设置会话级
ivfflat.probes参数 - 使用标准
database/sql接口,便于迁移或测试
Python
运行说明
- 安装 Python 3.9+ 和 PostgreSQL(已启用 pgvector)
- 安装依赖:
pip install psycopg2-binary python-dotenv
- 配置数据库连接(修改下方代码中的连接参数)
- 运行:
python demo.py
代码说明
本示例使用 psycopg2 驱动,通过 execute() 方法执行 SQL。代码结构与 Node.js 版本保持一致,采用随机向量模拟嵌入,演示了建表、插入、设置 probes 及向量检索的完整流程。
代码示例(demo.py)
import psycopg2
import random
import os
# 数据库配置
conn = psycopg2.connect(
host="localhost",
port=5432,
database="testdb",
user="postgres",
password="yourpassword"
)
cur = conn.cursor()
def random_vector(dim=768):
return '[' + ','.join(str(random.random()) for _ in range(dim)) + ']'
# 创建表
cur.execute("""
CREATE TABLE IF NOT EXISTS knowledge_base (
id BIGSERIAL PRIMARY KEY,
content TEXT NOT NULL,
embedding VECTOR(768)
)
""")
conn.commit()
# 插入测试数据
docs = [
"PostgreSQL 索引优化技巧",
"数据库连接池配置指南",
"查询计划分析与调优",
"事务隔离级别详解",
"PostgreSQL 分区表使用实践"
]
for content in docs:
vec = random_vector(768)
cur.execute(
"INSERT INTO knowledge_base (content, embedding) VALUES (%s, %s::VECTOR)",
(content, vec)
)
conn.commit()
print("✅ 插入测试数据完成")
# 设置 probes 参数
cur.execute("SET ivfflat.probes = 10")
# 模拟查询向量
query_vec = random_vector(768)
cur.execute("""
SELECT content, embedding <=> %s::VECTOR AS distance
FROM knowledge_base
ORDER BY distance ASC
LIMIT 3
""", (query_vec,))
print("📝 检索结果:")
for row in cur.fetchall():
print(f" - {row[0]} (距离: {row[1]:.4f})")
cur.close()
conn.close()
技术点总结
psycopg2原生支持VECTOR类型传递,使用%s占位符- 显式类型转换
%s::VECTOR确保参数类型正确 - 通过
SET ivfflat.probes动态调优召回率 - 代码简洁,适合快速原型验证
Java
运行说明
- 安装 JDK 11+、Maven 和 PostgreSQL(已启用 pgvector)
- 创建 Maven 项目,在
pom.xml中添加依赖:
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>42.6.0</version>
</dependency>
- 修改下方代码中的数据库 URL、用户名和密码
- 编译运行:
mvn compile exec:java -Dexec.mainClass="com.demo.PgVectorDemo"
代码说明
本示例使用 JDBC 官方驱动 org.postgresql.Driver,采用 PreparedStatement 执行参数化查询。向量以字符串形式传递,需显式转换为 VECTOR 类型。流程包括建表、插入随机向量数据、设置 probes 参数及余弦距离检索。
代码示例(PgVectorDemo.java)
package com.demo;
import java.sql.*;
import java.util.Random;
import java.util.stream.Collectors;
import java.util.stream.IntStream;
public class PgVectorDemo {
private static final String URL = "jdbc:postgresql://localhost:5432/testdb";
private static final String USER = "postgres";
private static final String PASSWORD = "yourpassword";
private static final int DIM = 768;
private static final Random RAND = new Random();
private static String randomVector() {
return "[" + IntStream.range(0, DIM)
.mapToObj(i -> String.valueOf(RAND.nextDouble()))
.collect(Collectors.joining(",")) + "]";
}
public static void main(String[] args) throws SQLException {
try (Connection conn = DriverManager.getConnection(URL, USER, PASSWORD);
Statement stmt = conn.createStatement()) {
// 创建表
stmt.execute("""
CREATE TABLE IF NOT EXISTS knowledge_base (
id BIGSERIAL PRIMARY KEY,
content TEXT NOT NULL,
embedding VECTOR(768)
)
""");
// 插入测试数据
String[] docs = {
"PostgreSQL 索引优化技巧",
"数据库连接池配置指南",
"查询计划分析与调优",
"事务隔离级别详解",
"PostgreSQL 分区表使用实践"
};
try (PreparedStatement pstmt = conn.prepareStatement(
"INSERT INTO knowledge_base (content, embedding) VALUES (?, ?::VECTOR)")) {
for (String content : docs) {
pstmt.setString(1, content);
pstmt.setString(2, randomVector());
pstmt.executeUpdate();
}
}
System.out.println("✅ 插入测试数据完成");
// 设置 probes 参数
stmt.execute("SET ivfflat.probes = 10");
// 模拟查询向量
String queryVec = randomVector();
try (PreparedStatement pstmt = conn.prepareStatement("""
SELECT content, embedding <=> ?::VECTOR AS distance
FROM knowledge_base
ORDER BY distance ASC
LIMIT 3
""")) {
pstmt.setString(1, queryVec);
try (ResultSet rs = pstmt.executeQuery()) {
System.out.println("📝 检索结果:");
while (rs.next()) {
String content = rs.getString("content");
double distance = rs.getDouble("distance");
System.out.printf(" - %s (距离: %.4f)%n", content, distance);
}
}
}
}
}
}
技术点总结
- 使用 JDBC
PreparedStatement避免 SQL 注入,通过?::VECTOR实现类型转换 - 向量以字符串形式传递,驱动自动处理参数绑定
- 支持会话级
SET命令调优索引参数 - 代码遵循标准 Java 资源管理(try-with-resources)
多语言对比
| 维度 | Node.js | Go | Python | Java |
|---|---|---|---|---|
| 驱动/库 | pg | lib/pq | psycopg2 | postgresql JDBC |
| 参数占位符 | $1, $2 | $1, $2 | %s (格式化后传递) | ? |
| 向量参数传递 | 字符串 + ::VECTOR | 字符串 + ::VECTOR | 字符串 + ::VECTOR | 字符串 + ::VECTOR |
设置 probes | client.query('SET ...') | db.Exec('SET ...') | cur.execute('SET ...') | stmt.execute('SET ...') |
| 异步支持 | 原生 async/await | 无(同步,可配合 goroutine) | 无(同步,可配合 asyncio) | 无(同步,可配合线程池) |
| 错误处理 | try/catch | 显式 error 返回 | try/except | try/catch |
| 连接管理 | 自动池化(默认) | 需手动维护 | 需手动维护 | 连接池推荐 HikariCP |
| 适用场景 | 快速原型、前端全栈 | 高并发微服务 | 数据分析、快速开发 | 企业级应用、Spring 生态 |
| 代码可运行性 | 是 | 是 | 是 | 是 |
以上四种语言实现的功能完全一致,均基于 pgvector 的余弦距离检索,并支持 ivfflat.probes 动态调优。开发者可根据自身技术栈选择最适合的实现方式。
项目难点与解决方案
核心难点
- 向量检索的精度与性能平衡:精确 KNN 检索随数据量增长性能急剧下降,ANN 索引在加速的同时引入了召回率损失。
- 索引参数调优:
IVFFlat的lists和probes参数需要根据数据分布和业务场景反复调试。 - 向量维度与存储成本:高维向量(768/1536)占用大量存储空间,且距离计算开销较高。
解决方案
- 采用
IVFFlat近似索引,通过调节probes参数在查询性能与召回率之间取得平衡。 - 根据数据规模设定
lists参数(通常为行数 / 1000),并通过测试逐步调整probes值(经验范围 10~100)。 - 结合
PostgreSQL的原生分区能力对向量表进行水平拆分,降低单表数据量。
广度
涵盖从传统关键词检索到语义检索的演进,完整覆盖 RAG 系统的 Embedding、Retrieval、Generation 三阶段,涉及 SQL 编写、索引创建、执行计划分析及参数调优。
深度
深入剖析 IVFFlat 索引的聚类原理,通过实验数据验证 probes 参数对召回率的实际影响,区分 KNN 与 ANN 的检索差异,并对执行计划中的 Index Scan 与 Sequential Scan 进行对比分析。
复杂度
涉及向量数据库、近似最近邻检索、大模型应用等多个技术领域,需要综合理解语义模型、数据库索引、距离度量及系统架构设计,属于典型的多技术栈融合场景。
官方文档
参考链接
总结
本文系统讲解了基于 PostgreSQL + pgvector 构建语义检索与 RAG 智能问答系统的核心技术路径。从传统关键词匹配的局限性出发,引入向量化语义检索,详细阐述了 pgvector 的向量数据类型、距离度量操作符及 IVFFlat 索引的创建与调优。通过实际实验数据,深入分析了 probes 参数对 ANN 检索召回率的显著影响,揭示了 KNN 与 ANN 的本质区别。
同时,完整梳理了 RAG 系统的 Embedding、Retrieval、Generation 三阶段架构,阐明 PostgreSQL 作为知识中枢在其中的关键作用。本文提供的 SQL 示例、Node.js Demo 及执行计划分析方法,可帮助开发者快速落地基于 PostgreSQL 的语义检索能力,为构建企业级智能助手奠定坚实基础。
561



被折叠的 条评论
为什么被折叠?



