pg_vectorize：基于Postgres的向量数据库

pg_vectorize 是一个 Postgres 服务器及扩展，可自动将文本转换为嵌入向量并进行编排，同时提供与主流大语言模型的集成接口。借助该工具，您可以快速搭建并向量搜索、全文搜索以及混合搜索系统实现自动化运维，从而在 Postgres 上高效构建 RAG 系统和搜索引擎。

本项目深度依赖于 pgvector 的向量相似度搜索功能、pgmq 的后台任务编排能力，以及 SentenceTransformers 提供的预训练模型。

---

API 文档: https://chuckhend.github.io/pg_vectorize/

源代码: https://github.com/tembo-io/pg_vectorize

概述

pg_vectorize 提供两种方式，可为任意 Postgres 数据库添加语义搜索、全文搜索和混合搜索功能，从而轻松在 Postgres 上构建检索增强生成（RAG）系统。该项目既支持独立的外部服务端实现，也通过 Postgres 扩展提供 SQL 使用体验。

模式概览：

• HTTP 服务器（推荐用于托管数据库）：运行一个独立的服务，连接到 Postgres 并暴露 REST API（POST /api/v1/table，GET /api/v1/search）。
• Postgres 扩展（SQL）：将扩展安装到 Postgres 中，使用 vectorize.table() 和 vectorize.search() 等 SQL 函数（需要访问 Postgres 文件系统；详情请参阅 ./extension/README.md）。

快速入门 — HTTP 服务器

使用 Docker Compose 在本地运行 Postgres 和 HTTP 服务器：

# 启动 Postgres、嵌入向量服务及管理 API
docker compose up -d

（可选）将示例数据集加载到 Postgres 中：

psql postgres://postgres:postgres@localhost:5432/postgres -f server/sql/example.sql

CREATE TABLE
INSERT 0 40

通过 HTTP API 创建嵌入作业。此操作会为现有数据生成嵌入向量，并持续监控数据更新或新增数据：

curl -X POST http://localhost:8080/api/v1/table -d '{
		"job_name": "my_job",
		"src_table": "my_products",
		"src_schema": "public",
		"src_columns": ["product_name", "description"],
		"primary_key": "product_id",
		"update_time_col": "updated_at",
		"model": "sentence-transformers/all-MiniLM-L6-v2"
	}' -H "Content-Type: application/json"

{"id":"16b80184-2e8e-4ee6-b7e2-1a068ff4b314"}

使用 HTTP API 进行搜索：

curl -G \
  "http://localhost:8080/api/v1/search" \
  --data-urlencode "job_name=my_job" \
  --data-urlencode "query=camping backpack" \
  --data-urlencode "limit=1" \
  | jq .

[
  {
    "description": "Storage solution for carrying personal items on ones back",
    "fts_rank": 1,
    "price": 45.0,
    "product_category": "accessories",
    "product_id": 6,
    "product_name": "Backpack",
    "rrf_score": 0.03278688524590164,
    "semantic_rank": 1,
    "similarity_score": 0.6296013593673706,
    "updated_at": "2025-10-05T00:14:39.220893+00:00"
  }
]

我应该选择哪种方式？

• 当您的 Postgres 数据库由第三方托管（如 RDS、Cloud SQL 等）或无法安装扩展时，请使用 HTTP 服务器。它仅需数据库中已存在 pgvector 扩展即可运行，且 HTTP 服务可独立部署。
• 当您自建并托管 Postgres 数据库，且具备安装扩展权限时，请使用 Postgres 扩展。这种方式可在数据库内部直接使用，并提供面向向量化和 RAG 的原生 SQL 接口。

如需更多 SQL 示例或有关如何将扩展安装到 Postgres 的说明，请参阅 ./extension/README.md。完整的 HTTP API 文档及部署指南，请参阅 ./server/README.md。

有关贡献指南，请参阅仓库根目录下的 CONTRIBUTING.md 文件。

pg_vectorize 快速上手指南

pg_vectorize 是一个基于 PostgreSQL 的向量数据库解决方案，能够自动化将文本转换为向量嵌入（Embeddings），并集成主流大语言模型（LLM）。它支持语义搜索、全文搜索及混合搜索，是构建 RAG（检索增强生成）应用的理想工具。

本指南重点介绍HTTP Server 模式，该模式无需在数据库内安装扩展，适用于托管型数据库（如阿里云 RDS、腾讯云 CDB 等）或无法直接操作文件系统的场景。

环境准备

系统要求

• 操作系统：Linux / macOS / Windows (需安装 Docker)
• 容器运行时：Docker 及 Docker Compose
• 数据库版本：PostgreSQL 13 ~ 18
• 前置依赖：
  • 数据库中需已安装 pgvector 扩展（大多数云厂商或现代 PG 镜像默认包含）。
  • 本地需安装 curl 和 jq (用于测试 API)。

网络加速建议

由于默认拉取的 HuggingFace 模型（如 sentence-transformers）位于海外，国内用户建议在 docker-compose.yml 中配置镜像加速，或在运行容器时设置环境变量指向国内镜像源（如 hf-mirror.com），以加快模型下载速度。

安装步骤

使用 Docker Compose 一键启动 PostgreSQL、嵌入服务及管理 API。

1. 克隆项目或获取配置文件 确保你拥有项目的 docker-compose.yml 文件。

2. 启动服务 在终端执行以下命令，后台启动所有必要组件：

docker compose up -d

3. （可选）加载示例数据 为了快速验证功能，可以加载官方提供的示例数据集：

psql postgres://postgres:postgres@localhost:5432/postgres -f server/sql/example.sql

预期输出：

CREATE TABLE
INSERT 0 40

基本使用

1. 创建向量化任务

通过 HTTP API 创建一个任务，指定源表、需要向量化列以及使用的模型。该任务会自动处理现有数据，并持续监听新数据或更新。

curl -X POST http://localhost:8080/api/v1/table -d '{
		"job_name": "my_job",
		"src_table": "my_products",
		"src_schema": "public",
		"src_columns": ["product_name", "description"],
		"primary_key": "product_id",
		"update_time_col": "updated_at",
		"model": "sentence-transformers/all-MiniLM-L6-v2"
	}' -H "Content-Type: application/json"

响应示例（返回任务 ID）：

{"id":"16b80184-2e8e-4ee6-b7e2-1a068ff4b314"}

注意：首次运行时，系统会自动下载模型文件。国内用户若遇下载超时，请检查 Docker 容器的网络代理配置。

2. 执行语义搜索

任务创建完成后，即可通过 API 进行自然语言搜索。以下示例搜索“露营背包”：

curl -G \
  "http://localhost:8080/api/v1/search" \
  --data-urlencode "job_name=my_job" \
  --data-urlencode "query=camping backpack" \
  --data-urlencode "limit=1" \
  | jq .

响应示例：

[
  {
    "description": "Storage solution for carrying personal items on ones back",
    "fts_rank": 1,
    "price": 45.0,
    "product_category": "accessories",
    "product_id": 6,
    "product_name": "Backpack",
    "rrf_score": 0.03278688524590164,
    "semantic_rank": 1,
    "similarity_score": 0.6296013593673706,
    "updated_at": "2025-10-05T00:14:39.220893+00:00"
  }
]

下一步

• 生产部署：参考 ./server/README.md 获取详细的部署配置和高可用方案。
• SQL 模式：如果你拥有数据库文件系统权限且希望直接在 SQL 中操作，可参考 ./extension/README.md 安装 Postgres 扩展版本。