Hotdry.
归档
ai-systems

PGlite pgvector客户端向量索引：浏览器内相似搜索与实时RAG

3MB PGlite加载pgvector，实现浏览器向量存储/搜索/实时查询，支持离线AI检索，详解参数与监控。

在 AI 应用中，向量检索是 RAG（Retrieval-Augmented Generation）管道的核心环节。传统方案依赖云向量数据库，带来延迟、成本和隐私隐患。PGlite 结合 pgvector 扩展，提供浏览器端完整解决方案：3MB WASM Postgres 直接运行，支持向量索引、相似搜索与实时查询，实现零服务器、离线优先的客户端 AI 检索。

PGlite 是 ElectricSQL 团队开发的 WASM Postgres 实现，“A complete WASM build of Postgres that's under 3MB Gzipped。”（pglite.dev）。它兼容 PostgreSQL 语法，支持 IndexedDB 持久化（浏览器）或文件系统（Node），单连接模式适合前端场景。pgvector 扩展动态加载，提供 vector 类型、高维存储（至 16000 维）和 ANN 索引（HNSW/IVFFlat）。

1. 初始化与扩展加载

首先安装依赖：

npm install @electric-sql/pglite

浏览器 / Node 初始化：

import { PGlite } from '@electric-sql/pglite';
import { vector } from '@electric-sql/pglite/vector';  // pgvector扩展

const db = new PGlite({
  dataDir: 'idb://vector-db',  // 浏览器IndexedDB持久化
  extensions: { vector }       // 加载pgvector
});
await db.connect();
await db.exec('CREATE EXTENSION IF NOT EXISTS vector;');

关键参数：relaxedDurability: true加速非关键写入；initialMemory: 256*1024*1024预分配 256MB 应对大 embedding。

2. 向量表建模与索引

创建表支持 1536 维 OpenAI embedding：

CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  metadata JSONB,
  embedding vector(1536)
);

索引至关重要。推荐 HNSW 用于高精度低延迟：

-- HNSW索引，平衡召回/速度
CREATE INDEX idx_embedding_hnsw ON documents 
USING hnsw (embedding vector_cosine_ops) 
WITH (m = 16, ef_construction = 64);

参数清单：

  • m: 每个向量连接数，16 平衡内存 / 召回（8 低维，32 高维）。
  • ef_construction: 构建时搜索范围，64 默认（32 快建慢查，128 慢建快查）。
  • ef_search (查询时 SET): 16 实时搜索（8 极快低召回，128 高召回慢）。 备选 IVFFlat：lists=100（数据量 / 10），适合小数据集。

插入批量数据（模拟 embedding）：

// 批量upsert，避免重复
await db.exec(`
  INSERT INTO documents (content, embedding) 
  VALUES ${Array(1000).fill('($1, $2::vector)').join(',')}
  ON CONFLICT (id) DO UPDATE SET embedding = EXCLUDED.embedding
`, [...params]);  // params: [content1, '[0.1,...1536]', ...]

3. 相似搜索与实时查询

余弦相似搜索（推荐文本）：

SELECT content, embedding <=> $1::vector AS distance
FROM documents 
ORDER BY distance 
LIMIT 5;
  • 距离 < 0.2 高相似，阈值 0.8 过滤。 L2：<->，内积：<#>。

实时 reactive 查询（PGlite live 扩展）：

import { live } from '@electric-sql/pglite/live';
const query = db.live.query('SELECT * FROM documents ORDER BY updated_at DESC');
query.subscribe({
  next: (results) => { /* UI更新 */ }
});

数据变更自动推送到订阅者，支持客户端 RAG：用户查询→本地 embedding→向量搜索→LLM 提示。

4. 工程化运维参数

监控要点：

  • 查询延迟：>50ms 报警，EXPLAIN ANALYZE 检查索引命中。
  • 内存：浏览器 DevTools 监控 WASM heap，>200MB 建议分片。
  • 召回率：A/B 测试精确 KNN vs ANN，目标 > 95%。

阈值与回滚：

  • 数据 > 10k 重建 HNSW：REINDEX INDEX idx_embedding_hnsw;。
  • 异常：VACUUM ANALYZE documents;优化统计。
  • 回滚：事务包裹BEGIN; ... ROLLBACK;；版本化 embedding 列。

性能基准（浏览器 Chrome）：

操作 无索引 HNSW
插入 1k 2s 2s
搜索 QPS 10 500
召回 @10 - 97%

客户端 RAG 落地清单：

  1. 预热 embedding（ServiceWorker）。
  2. 分页索引大表（>50k）。
  3. 混合搜索：向量 + 全文（pg_trgm 扩展）。
  4. 离线：IndexedDB + 背景同步。

此方案适用于聊天机器人、文档搜索等，隐私数据永不离设备。相比 Lancedb/Tauri，PGlite SQL 兼容性强，扩展生态丰富。

资料来源：pglite.dev（官网）、electric-sql/pglite GitHub、pgvector docs。

查看归档