pgai

环境要求

• 一个可用的 PostgreSQL 数据库（支持 Timescale Cloud、Amazon RDS、Supabase 等）
• 一个 OpenAI API Key（快速上手示例使用 OpenAI 生成嵌入，也支持多种模型提供商）
• 已安装 Python 与 pip
• 若数据库不在 Timescale Cloud 上，需要运行 pgai vectorizer worker

安装与启动步骤

1. 1安装 pgai 包

   在 Python 环境中安装 pgai 主包，这是使用 pgai 全部能力的前提。建议先创建并激活虚拟环境。

   pip install pgai

   复制

2. 2安装数据库组件

   pgai 需要在数据库中安装若干目录表与函数，pgai.install 会把它们装到 ai schema 下。把 DB_URL 换成你的真实数据库连接串。

   python -c "import pgai; pgai.install('postgres://postgres:password@localhost:5432/postgres')"

   复制

3. 3安装 worker 依赖

   如果数据库不在 Timescale Cloud 上，还需要运行 vectorizer worker，需额外安装它的依赖。

   pip install "pgai[vectorizer-worker]"

   复制

4. 4安装语义目录依赖

   仅当你使用 Semantic Catalog（自然语言转 SQL）功能时才需要执行这一步。不使用可跳过。

   pip install "pgai[semantic-catalog]"

   复制

5. 5配置 .env 文件

   在运行示例的同一个目录下创建 .env，填入 OpenAI 密钥和数据库地址，切勿把该文件提交到公开仓库。

   OPENAI_API_KEY=<your-openai-api-key>
   DB_URL=<your-database-url>

   复制

6. 6创建向量化器

   先在数据库里建 wiki 表，再调用 ai.create_vectorizer 声明式定义嵌入管道；它会自动为已有数据生成嵌入，并在数据变化时保持同步。

   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
   );
   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')
       )

   复制

7. 7运行快速上手示例

   下载官方 quickstart 的 main.py 与依赖清单，建虚拟环境装依赖后运行；也可以在代码里以 Worker(DB_URL, once=True) 手动跑一次 worker。

   curl -O https://raw.githubusercontent.com/timescale/pgai/main/examples/quickstart/main.py
   curl -O https://raw.githubusercontent.com/timescale/pgai/main/examples/quickstart/requirements.txt
   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   python main.py

   复制

关键配置

如何确认成功

运行 python main.py 后能在终端看到 "Search results"（含 url、title、chunk、distance 字段）以及 "RAG response" 输出，即表示部署与检索链路正常。

常见问题

注意事项

• 该项目自 2026 年 2 月起已停止维护，不建议用于长期生产项目。
• OPENAI_API_KEY 与 DB_URL 属于敏感信息，不要写入代码或提交到版本库。
• 向量化器类似“声明式索引”：你只需定义管道，嵌入的生成与同步由 pgai 负责。
• 命令中出现的连接串、密钥、路径均为示例，请替换为你自己的真实值。