GitHub高星项目：AI+PostgreSQL=PGAI

数据库版本：PostgreSQL 15 +，Python 3.10+

安装方式：

# 直接pip安装，需要的pip版本比较高pip install pgai
# 核心功能 vectorizer，可用于RAGpip install "pgai[vectorizer-worker]"
# 核心功能 semantic-catalog，可用于NL2SQLpip install "pgai[semantic-catalog]"

语言模型：可以配置 Ollama、OpenAI 等 LLM

1.Semantic Catalog（语义目录）

PGAI提到一种“语义目录”的概念，即相比传统数据库中 数据库-表-字段-数据的数据结构，PGAI会进一步维护一个描述层。语义目录会存放：表的语义说明、列的业务含义、示例 SQL、领域事实（domain facts）。PGAI 通过语义目录的方式，存放大模型所需的字段语义、业务中的字段逻辑和样例数据。

Quick start

（1）环境变量中配置api-key和数据库连接地址

OPENAI_API_KEY="your-OpenAPI-key-goes-here"TARGET_DB="postgres://postgres@localhost:5555/postgres"

（2）创建 semantic-catalog

pgai semantic-catalog create

（3）生成数据库表语义描述的yaml文件

pgai semantic-catalog describe -f descriptions.yaml

这是比较关键的一步，需要人工确认提高语义的准确度，生成的yaml文件示例：

---schema: postgres_airname: aircrafttype: tabledescription: Lists aircraft models with performance characteristics and unique codes.columns:- name: model  description: Commercial name of the aircraft model.- name: range  description: Maximum flight range in kilometers.- name: class  description: Airframe class category or configuration indicator.- name: velocity  description: Cruising speed of the aircraft.- name: code  description: Three-character aircraft code serving as the primary key....

（4）导入语义文件

pgai semantic-catalog import -f descriptions.yaml

（5）接下来就可以 AI问数 和 NL2SQL了

pgai semantic-catalog search -p "Your natural language question goes here!"

生成SQL

pgai semantic-catalog generate-sql -p "Your natural language question goes here!"

值得注意的是，pgai生成的SQL会调用pgsql去explain一下拿执行计划，如果不通过则将报错信息继续喂给LLM

2.Vectorizer （向量嵌入）

向量嵌入（Vector Embeddings） 是一种将文本转化为紧凑且语义丰富表示的方法，比传统关键词搜索更智能，能够理解语义相似但用词不同的查询。

虽然 PostgreSQL 等现代向量数据库可以高效存储和查询嵌入，但过去开发者需要手动维护嵌入与源数据的一致性，工作量大且流程复杂。

为此，PGAI引入了一种创新的 SQL 层级接口，把嵌入当作类似索引的声明式功能：

• 可以灵活指定任意文本列进行嵌入；

• 自动生成并维护可搜索的嵌入表；

• 保持嵌入与源数据的异步同步；

• 通过视图无缝将基础表与嵌入结合。

简单来说，就是把嵌入的生成、管理、同步过程交给数据库自动完成，开发者像建索引一样轻松使用语义搜索。

Quick start

（1）在pgsql中启动pgai插件

CREATE EXTENSION IF NOT EXISTS ai CASCADE;

（2）创建表

CREATE TABLE IF NOT EXISTS wiki (    id INTEGER PRIMARY KEY GENERATED ALWAYS AS IDENTITY,    url TEXT NOT NULL,    title TEXT NOT NULL,    text TEXT NOT NULL)

（3）创建 vectorizer

SELECT ai.create_vectorizer(     'wiki'::regclass,     loading => ai.loading_column(column_name=>'text'),     destination => ai.destination_table(target_table=>'wiki_embedding_storage'),     embedding => ai.embedding_openai(model=>'text-embedding-ada-002', dimensions=>'1536')    )

（4）启动后台worker进程，代码可参考 https://github.com/timescale/pgai/blob/main/examples/quickstart/main.py

Vectorizer 会自动为wiki 表中的所有行生成向量嵌入，并且在底层数据发生变化时保持同步。它的作用很像在表上声明一个索引，只不过数据库管理的是索引结构，而 Vectorizer 管理的是嵌入数据。

• 数据分析：

例如运营人员往往不熟悉SQL，也可以通过自然语言快速获取数据报表，支撑运营工作。

• 研发提效：

开发人员不需要再从零开始编写SQL，仅需在PGAI返回结果的基础上进行微调，简化工作量。

• 数据库文档：

自动维护表的语义文档，减少新人的学习成本，规范开发流程。

如果说 PostgreSQL 是一台性能卓越的“跑车”，那么 pgai 就是它的智能“交互中枢”：它理解业务语义，能自动生成 SQL，还能为数据提供解释。对数据工程师和分析师而言，pgai 或许正成为未来工作中不可或缺的“智能助手”。

不妨想象这样的场景：在未来，使用 BI 工具时不再需要繁琐的拖拽配置，只需轻松说一句：“帮我查看过去三个月的活跃用户留存情况”，数据库就能自动返回完整的 SQL 语句与可视化报表。

这，正是 pgai 所带来的范式变革。