pgai

给 PostgreSQL 装上 AI 大脑：pgai 如何让数据库直接跑 RAG

场景切入： 想象你经营一家电商平台，数据库里躺着上百万条商品评论。用户问"哪些用户对这款相机评价最好"，传统做法是先 SQL 查出评论，再调 AI 接口分析情感，再返回结果——至少两个系统、三次网络调用、三个月的集成工期。pgai 出现后，你只需要一条 SQL：SELECT * FROM moderate_reviews('这款相机怎么样')。数据库自己就把向量检索、全文语义匹配、AI 推理全干了，结果直接返回。

这就是 Timescale（知名时序数据库公司）推出 pgai 的核心思路：让 PostgreSQL 本身变成一个 AI 推理平台。

一、项目背景：数据库巨头为什么要做 AI 扩展

Timescale 是 PostgreSQL 生态中最专注于时序数据的公司，其 TimescaleDB 产品广泛用于监控、物联网、金融分析场景。2024 年前后，向量数据库概念大热，Pinecone、Weaviate、Qdrant 纷纷崛起，而 Timescale 敏锐地注意到：大多数 AI 应用的数据本来就存在 PostgreSQL 里，用户不想要又一个独立的向量数据库，而是希望"在现有数据库上直接跑 AI"。

pgai 正是这一思路的产物。它于 2024 年中正式开源，目标是将 LLM 调用和向量检索能力直接以内核扩展（extension）的形式嵌入 PostgreSQL。开发者无需学习新的 SDK、无需维护独立服务，直接用熟悉的 SQL 就能完成复杂的 AI 任务。

项目的两位核心维护者分别来自 Timescale 核心工程团队和学术研究背景，技术路线稳健，推进节奏稳定。截至 2026 年初，仓库已积累超过 5700 颗星、300+ Fork、44 个活跃 Issue，社区活跃度在 PostgreSQL 扩展类项目中名列前茅。

二、核心功能：三条主轴，撑起 AI 数据库能力

pgai 的功能可以概括为三个层次：

1. 向量检索（Vector Search）

pgai 扩展集成了 pgvector 和 pgvectorscale，为 PostgreSQL 带来高效的向量存储和相似度搜索能力。支持余弦相似度、欧氏距离、L2 距离等多种度量方式，能够处理高维 Embedding 向量（1536 维、3072 维等）。更重要的是，它利用 TimescaleDB 的自动分区（hyper table）能力，让向量检索在大规模数据集（百万级向量）上依然保持毫秒级延迟。

2. LLM 调用（LLM Invocation）

pgai 支持通过 SQL 函数直接调用主流 LLM API，包括 OpenAI GPT 系列、Anthropic Claude 系列、Cohere、Ollama（本地模型），以及 LiteLLM（统一网关，支持 50+ 模型）。通过 ai.process() 函数，开发者可以在 SQL 中传递 prompt 并获得 LLM 返回结果。这意味着：SQL 查询 → Embedding 检索 → LLM 推理 → 结果返回，全部在一个数据库事务内完成。

3. Vectorizer 异步向量化管道

这是 pgai 最具差异化的功能之一。它提供了一个独立的后台 Worker（Python 进程），持续监听数据库内的待处理文档队列，自动完成分词、Embedding 生成、向量化存储的全流程。开发者只需把原始文档插入队列，Worker 异步完成剩余工作，不阻塞主业务流程。文档变更（更新/删除）也会同步到向量索引中。

三、技术架构：双组件协同的分布式设计

pgai 并不是一个单一组件，而是由两个独立子系统组成，协同工作：

组件一：PostgreSQL 扩展（projects/extension/）

用 PL/pgSQL、Python（PL/Python）和 C 语言混合编写，以 CREATE EXTENSION pgai 的形式安装进 PostgreSQL。核心功能包括：

• ai.embed()：将文本转为向量存入表字段
• ai.process()：调用 LLM API 执行推理
• semantic_catalog：语义目录，管理 Embedding 模型配置和元数据
• vectorizer 触发器：监控表的数据变更，自动触发向量化任务

扩展使用 justfile 构建系统，支持 Docker 多阶段构建（Dockerfile 中目标镜像含 pgai-test-db）。

组件二：Python CLI 库（projects/pgai/）

提供命令行工具和 Python SDK，用于：

• pgai install：一键将扩展安装到目标 PostgreSQL 实例
• pgai vectorizer-worker：启动后台 Worker 进程
• pgai status：查看扩展安装状态和 Worker 健康状态
• SQLAlchemy 集成：with_psycopg.py 和 with_sqlalchemy.py 示例展示了如何用 Python 应用代码驱动 pgai

两个组件通过 docker compose-dev.yaml 协同启动，数据库启动后自动安装扩展，Worker 进程持续消费向量化队列。

四、适用场景与典型案例

pgai 最适合以下场景：

场景	传统方案痛点	pgai 优势
RAG 应用后端	需要维护向量库 + API 网关 + 数据库三套系统	一个 PostgreSQL 全搞定
实时 AI 决策	LLM 调用延迟高，需异步队列	SQL 事务内完成，数据一致性有保障
多租户 SaaS	每用户独立 AI API 配额管理复杂	统一在数据库层管理，天然隔离
数据分析增强	分析结果需导出到 Python 再处理	SQL 内直接调 LLM，Pipeline 更简洁

仓库的 examples/ 目录提供了丰富的参考实现，包括 Discord Bot 接入、AI 文章摘要、文本转 SQL（Text-to-SQL）、实体识别（NER）、内容审核（Moderation）等，覆盖了 RAG 的主流用法。

五、部署与上手门槛

pgai 的部署存在一定门槛，不属于"开箱即用"类型：

依赖要求：

• PostgreSQL 16 或更高版本（推荐 18）
• 必须安装 pgvector 或 pgvectorscale 扩展
• Python 3.10+ 环境（CLI 工具）
• LLM API Key（OpenAI / Anthropic / Ollama 等）

部署难度：中等。项目提供了 Docker Compose 开发环境（compose-dev.yaml），但实际生产部署需要：

1. 在已有 PostgreSQL 上安装 pgai 扩展
2. 配置 LLM API 密钥（通过 ai.secrets 表管理）
3. 启动独立的 Vectorizer Worker 进程
4. 初始化 Embedding 模型（语义目录配置）

整个过程涉及数据库扩展安装、Python 环境配置、LLM 凭证管理，对新手有一定挑战。不过，examples/docker_compose_pgai 和 examples/docker_compose_pgai_ollama 两个示例提供了参考配置，降低了启动难度。

硬件需求： 无 GPU 依赖，普通云服务器即可运行。推荐 4GB+ RAM、2GB+ 磁盘空间。

六、局限与争议

pgai 并非银弹，存在几个值得关注的局限：

性能上限：在超大规模向量检索场景下（10 亿级向量），专用向量数据库（Milvus、Qdrant）依然具有优势。pgai 的向量索引基于 pgvector，性能与独立向量库有差距。

LLM 调用成本：直接在数据库层调用 LLM API，如果 SQL 查询设计不当（例如不加限制的全表扫描触发 LLM 调用），会产生大量不必要的 API 费用。需要在应用层做充分过滤。

上下文窗口管理：pgai 目前没有内置的上下文窗口管理（Chunk 管理靠外部应用负责），RAG 效果很大程度上取决于 Embedding 质量分块策略。

版本稳定性：作为相对年轻的项目，API 和 SQL 函数接口在不同版本间可能有 breaking change，需要关注 CHANGELOG。

七、行业意义与增长趋势

pgai 代表了"AI 基础设施下沉"的大趋势——从独立 AI 服务走向数据库内嵌 AI。从 2024 年中开源到 2026 年初突破 5700 星，增长曲线陡峭，社区活跃度高。它的成功验证了一个核心假设：开发者不愿意为 AI 单独学一套新系统，他们更愿意在现有技术栈上增量引入 AI 能力。

紧随其后的还有 Supabase（pgvector）、Neon（Serverless Postgres +向量）、MongoDB Atlas Vector Search 等，PostgreSQL 生态正在成为 AI 时代的"操作系统底座"。pgai 作为这一趋势的先行者之一，具有较高的研究和参考价值。

---

图1：pgai 官方 Logo（深色主题）

图2：pgai 官方 Logo（浅色主题）