pg_vectorize

从"数据库管理员的困境"说起

凌晨三点，一家中型电商公司的 DBA 李工被告警铃声惊醒——用户搜索商品时，词不达意的查询（比如"显瘦的裙子"）返回了空结果。他知道问题出在哪里：传统 LIKE 模糊匹配根本不认识语义，而公司的向量数据库集群刚刚宕机，数据还在同步中。RAG 搜索体验倒退回了五年前。

这是 pg_vectorize 试图解决的核心问题：把向量搜索能力直接嵌入 PostgreSQL，让关系数据库既有的 ACID 保障、高可用方案和运维经验直接复用，而不是引入一个全新的专用向量数据库。 开发者不需要维护两套存储引擎，运维也不需要半夜同时处理两种不同的故障告警。

项目起源：从 pgvector 使用痛点出发

pg_vectorize 的作者 Chuck Hendren 在生产环境中大量使用 pgvector 扩展，他发现虽然 pgvector 提供了向量存储和相似度计算，但围绕向量搜索的整个工程链路——从文本分块、Embedding 生成、向量化索引构建，到增量数据同步、混合检索排名——仍然需要大量定制代码。

这个项目本质上是把 RAG 场景下向量搜索的"脏活累活"自动化：用户只需声明一张表和要向量化哪些列，项目自动生成向量、管理索引、处理增量更新、执行混合检索。 它不是要替代 pgvector，而是 pgvector 的智能化上层建筑。

核心功能：三种接入方式

pg_vectorize 提供三种使用模式，适应不同部署场景：

HTTP Server 模式（推荐）：运行独立的 Rust HTTP 服务，连接现有 PostgreSQL 数据库，通过 REST API 管理向量化任务。适合使用 RDS、Cloud SQL 等托管数据库的团队。API 风格简洁：POST /api/v1/table 创建向量化任务，GET /api/v1/search 执行检索。

PostgreSQL Extension 模式：将扩展直接安装进 PostgreSQL，通过 SQL 函数操作。提供 vectorize.table() 建表、vectorize.search() 查询等接口。适合有权限访问数据库服务器、内部部署的团队。使用 pgrx 框架开发，遵循 PostgreSQL 扩展规范。

SQL Proxy 模式：透明拦截 PostgreSQL 协议，识别嵌入向量相关的 SQL 语句并改写。适合不想改应用代码、渐进式引入向量能力的场景。

检索层面支持三种模式：纯语义搜索（向量相似度）、纯全文搜索（pg_trgm）、混合搜索（RRF 融合排名）。默认使用 Reciprocal Rank Fusion 算法融合两种检索结果，这比简单的分数归一化更能平衡两种检索模式的偏好。

架构设计：Rust 微服务 + Python 推理服务

项目采用 Rust Workspace 架构，包含四个核心 crate：

• server：Actix-web HTTP 服务，处理 API 请求，路由配置在 /api/v1 下提供 table 和 search 端点。
• worker：后台异步任务处理器，监听 pgmq 消息队列，批量生成 Embedding、更新向量列。健康监控内置，支持热更新。
• core：共享业务逻辑，包括配置管理、数据库连接池（sqlx）、缓存层（Redis 兼容接口）、Embedding 提供者抽象。
• proxy：PostgreSQL 协议代理，拦截并改写 SQL，支持透明接入。

向量推理服务独立为 Python FastAPI 应用（vector-serve），通过 Hugging Face Inference API 调用 SentenceTransformers 模型，保持推理逻辑与主服务解耦。Embedding 提供者支持 OpenAI、Cohere、VoyageAI、Ollama 本地模型，以及自定义 HTTP 服务，扩展性良好。

PostgreSQL 扩展部分使用 pgrx 框架开发，这是 PostgreSQL 官方推荐的扩展开发方案，支持 PostgreSQL 13~18 版本。SQL 迁移管理极其规范，仓库中包含从 0.2.0 到 23.0 的完整 SQL 升级脚本（共 31 个迁移文件），覆盖了每次版本迭代的 schema 变更。

上手体验：docker-compose 一键启动

部署非常简单，在已有 Docker 环境的机器上：

git clone https://github.com/ChuckHend/pg_vectorize
cd pg_vectorize
docker compose up -d

compose 配置包含三个服务：PostgreSQL 18（带 pgvector）、Rust HTTP 服务（8080 端口）、Python 向量推理服务（3000 端口）。启动后大约等待 10 秒，向量服务拉取 HuggingFace 模型（all-MiniLM-L6-v2，约 90MB），即可开始使用。

创建向量化任务并搜索的完整流程不超过 5 条命令，对比手动配置 pgvector + 编写 Python 脚本的方案，效率提升明显。HTTP API 设计清晰，查询参数直接映射到搜索选项，对于习惯使用 REST API 的团队非常友好。

Extension 模式需要手动编译 Rust 扩展，对 PostgreSQL 有文件系统访问权限要求，门槛相对较高，适合有经验的 DBA 或内部平台团队。

局限与挑战

pg_vectorize 并非银弹，有几个场景需要评估：

向量规模：pgvector 的 HNSW 索引适合百万级向量，亿级向量场景下，专用向量数据库（如 Milvus、Qdrant）仍然有性能优势。项目使用的 pgv_hnsw_l2/ip/cosine 索引在超大规模下需要更多调优。

模型供应商锁定：Embedding 生成依赖外部服务（OpenAI API 等），离线部署需要自行维护模型服务。虽然支持 Ollama 本地推理，但配置相对复杂。

部署复杂度：HTTP Server 模式下需要同时运维 PostgreSQL + 向量推理服务 + HTTP 服务，compose 虽然简化了启动，但生产环境的高可用和监控仍需额外规划。

LLM 调用仅限 RAG：项目提供 vectorize_chat() 函数实现 RAG 问答（类似 pg_vectorize 内置的 ChatGPT），但这不是核心功能，专注于检索侧。

行业意义：向量搜索民主化

pg_vectorize 代表的趋势是"数据库内 AI 能力"——将 AI 功能下沉到数据层，减少数据移动，降低系统复杂度。pgvector 本身已经是 PostgreSQL 生态中最流行的向量扩展，pg_vectorize 在其基础上解决了"用起来复杂"的问题。

这个方向和 SingleStore、Pinecone 与 PostgreSQL 兼容层、Azure AI Search 等商业方案异曲同工，但完全基于开源组件。对于已有 PostgreSQL 基础设施的团队，pg_vectorize 提供了一条低迁移成本的向量搜索路径。

---

代码质量评估

从代码组织来看，项目采用了 Rust 典型的 Workspace 模式，四个核心 crate 职责边界清晰，通过 Cargo.toml 声明式管理依赖。workspace 级别的 dependency 管理避免了子 crate 重复声明公共依赖，版本一致性有保障。

核心依赖选型：使用 sqlx 而非 diesel 进行数据库操作（编译期查询验证 + 离线模式适合 Rust 的强类型哲学）；tokio 异步运行时 + actix-web 构建高并发 HTTP 服务，是 Rust Web 生态的主流组合；utoipa 生成 OpenAPI 文档，pgmq 提供消息队列能力，整体依赖链健康。

类型安全方面，serde 全程序列化/反序列化，thiserror 提供结构化错误处理，clap 处理 CLI 参数，均为 Rust 生态质量较高的库。核心类型定义（VectorizeJob、JobParams、IndexDist、TableMethod）都有完整的 Serialize/Deserialize 实现，API 契约清晰。

测试覆盖：server 目录有集成测试（tests.rs），extension 目录有完整的集成测试套件，vector-serve 有 pytest 端到端测试，CI/CD 流水线覆盖 server、extension、proxy 三个核心模块。SQL 升级脚本的规范性也间接保证了数据库迁移的可测试性。

文档质量：mkdocs.yml 配置完整，docs 目录结构清晰，涵盖 Server API、Extension API、模型提供商、配置说明等。mkdocs-material 主题提供了良好的阅读体验，但图片资源较少，主要依赖文字说明。

数据隐私方面，项目作为数据库扩展，所有数据处理发生在用户控制的 PostgreSQL 实例内，不存在数据外传的隐患。Embedding 生成调用外部 API 时，需要注意模型提供商的隐私政策（OpenAI/Cohere 等均有数据使用条款）。

总体评分：代码质量扎实，架构清晰，测试规范，文档完善，适合生产使用。扣分项在于没有内置 Web UI、离线部署需要额外配置，以及大规模向量场景下的性能边界需要实测验证。