pixeltable/pixeltable · 上手攻略

仓库：pixeltable/pixeltable
链接：https://github.com/pixeltable/pixeltable
分类：AI 数据基础设施 · 多模态数据库 · RAG
作者：Jay
更新：2026-10-07

这是什么

Pixeltable 是一个将数据库、编排层和服务层合一的 Python 库，专为多模态 AI 数据应用设计。它的核心主张是：传统 AI 应用需要协调 Postgres（存储）+ 对象存储（文件）+ 向量数据库（ Embedding）+ 消息队列（编排）+ API 服务层（HTTP），而 Pixeltable 将这些全部压缩到一个 app.py 文件中——声明表结构、计算列和 HTTP 路由，用同一套 Python 代码完成本地开发和云端部署。

创始人曾参与 Apache Impala 和 Apache Parquet 的开发，Apache 2.0 许可证，当前 GitHub Stars 约 1,638。

解决什么问题

碎片化：RAG 系统需要单独搭向量数据库、单独写嵌入逻辑、单独维护同步脚本。Pixeltable 在表层面统一管理，Insert 一行 → 计算列自动运行 → 索引自动更新。
AI Agent 上下文限制：Agent 无法hold 四个系统（DB、文件存储、向量库、服务端），Pixeltable 的单一 app.py 文件让 Agent 能一次性写出完整后端。
重复性 ETL 劳动：每次换模型或换 embedding 策略需要改多处代码，Pixeltable 的声明式列机制让变更集中在 schema 定义层。

快速安装

# 基础安装
pip install pixeltable

# 含 serving 功能（推荐，FastAPI 路由）
pip install 'pixeltable[serve]'

# 初始化项目
pxt init

# 验证安装
pxt --version  # 确认 CLI 可用

目前 npm 上有独立的 pixeltable-skill 包供 Agent 使用：

npx skills add pixeltable/pixeltable-skill

⚠️ Pixeltable Cloud 处于 Limited Beta 阶段（联系 contact@pixeltable.com 申请），本地使用无需云端账号。

核心用法

1. 创建表（含计算列）

import pixeltable as pxt
import pixeltable.functions as pxtf

class Docs(pxt.TableModel, name='docs'):
    id: str = pxt.Column(value=pxtf.uuid.uuid7(), primary_key=True)
    title: pxt.String
    body: pxt.String | None
    title_upper: str = pxtf.string.upper(title)      # 写入时自动计算
    summary: str = pxtf.string.excerpt(title, n=12) # 自定义 UDF

# 插入数据 → 计算列自动执行
docs = Docs()
docs.insert(title='Hello', body='world')

计算列在 insert 和 update 时自动触发，结果持久化，无需手动 ETL。

2. 定义 UDF（用户定义函数）

import pixeltable as pxt

@pxt.udf
def excerpt(text: str, n: int = 12) -> str:
    return text if len(text) <= n else f'{text[:n]}...'

UDF 可在任何计算列、查询或路由输入输出中复用。

3. 暴露 HTTP 路由（一条命令上线服务）

from pixeltable.serving import FastAPIRouter

ingest = FastAPIRouter(name='ingest')

ingest.add_insert_route(
    Docs,
    path='/docs',
    inputs=[Docs.title, Docs.body],
    outputs=[Docs.id, Docs.title_upper, Docs.summary]
)

将路由注册到 FastAPI 实例：

from fastapi import FastAPI
app = FastAPI()
app.include_router(ingest.router)

4. 生成应用代码并部署

# 生成示例 app.py
pxt service example --out app.py

# 创建 catalog schema
pxt schema update app.py my_app

# 启动 HTTP 服务
pxt service update app.py my_app

pxt schema update 创建 catalog 和表；pxt service update 启动 HTTP 服务（两条命令分离，逻辑清晰）。

5. 调用服务

# 获取服务地址（端口由系统分配，避免硬编码）
URL=$(pxt service list --json | jq -r '.[0].endpoint')

curl -X POST "$URL/docs" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Hello", "body": "world"}'
# 返回: {"id":"...","title_upper":"HELLO","summary":"Hello"}

6. RAG 场景（多模态数据管理）

class Chunks(pxt.TableModel, iterator=document_splitter(Docs.document)):
    ...

# Insert 文档 → 自动切分 → 自动生成 Embedding → 向量索引同步更新

Insert 一行，多模态 pipeline 自动执行：文档切分 → Embedding 生成 → 向量索引更新，RAG 查询直接 @pxt.query 即可。

7. 视频帧处理

class Frames(pxt.TableModel, iterator=frame_iterator(video=Videos.video, fps=1)):
    ...

Insert 视频 → 自动抽帧 → 每帧自动生成缩略图和字幕。

典型适用场景

RAG 系统快速搭建：不需要分别搭 PG + Milvus + LangChain，一条 schema 定义搞定分块、嵌入、查询。
多模态数据管理：视频/音频/图像的自动处理管道，插入即触发全链路计算。
AI Agent 后端：Agent 写一个 app.py 就能交付完整后端，不需要协调多个系统。
快速原型验证：在 Notebook 中用 pxt.create_table() 快速建表测试，换到生产时用 pxt schema update 迁移。
增量数据处理：源数据变化时只重新计算受影响部分，无需全量 ETL。

坑与注意

坑	说明	建议
Notebook API vs App API 分离	Notebook 用 `pxt.create_table()`，App 用 `pxt schema update` + `app.py`	不要在 App 代码中混用两种建表方式
云端 Beta 阶段	Pixeltable Cloud 目前仅限申请用户使用	生产全托管暂不可用，目前仅本地或自托管
HTTP 路由需要 pxt service update	`pxt schema update` 只建表不启动 HTTP	两条命令职责分离，理解后再开始
Python 3.10+	基于 Python type hint 和现代语法	低于 3.10 的 Python 环境可能不兼容
Embedding / LLM 调用依赖外部 API	Pixeltable 本身不提供 Embedding 服务，需要配置 API Key	`/ask` 路由需要 `ANTHROPIC_API_KEY` 环境变量
单一文件 ≠ 无状态	app.py 包含 catalog 和 route 定义，每次 `pxt service update` 重新加载	修改 schema 后需重启服务
向量数据库作为内置能力	底层集成向量检索，但具体实现细节未在 README 中详述	⚠️ 如对向量库有特殊要求（如元数据过滤精度），需核实具体实现
Starter kit 默认 chat app	`uvx pixeltable-new myapp` 默认生成聊天应用模板	需要视频搜索等模板需加参数 `--video` 或 `agent`

与同类对比

工具	类型	Pixeltable 的差异
Postgres + pgvector	关系数据库 + 向量扩展	Pixeltable 在表层直接支持多模态类型（视频/音频/文档），无需手动配置向量列
Milvus / Qdrant	专用向量数据库	专用向量库专注检索；Pixeltable 在向量之上还提供 ETL、计算列和 HTTP 服务层
LangChain	LLM 应用编排	LangChain 是编排库，不做存储；Pixeltable 替代的是数据层而非编排层
LlamaIndex	索引和查询框架	同样偏重索引侧；Pixeltable 把数据库也纳入统一抽象
Dolt / DuckDB	版本化数据库 / 分析数据库	这些解决的是数据版本化或分析性能问题；Pixeltable 解决的是 AI 数据的建模和 serving 一体化

结论：Pixeltable 的核心差异化在于声明式多模态表 + 计算列 + HTTP serving 三位一体，特别适合 AI Agent 需要交付完整数据后端的场景。如果你已经在用 Postgres + 向量库 + FastAPI 的组合，迁移到 Pixeltable 能显著减少样板代码，但需要接受其相对较新的生态（Beta 云服务、有限生产案例）。

一句话推荐

多模态 AI 数据应用的"三合一"方案——一张 Python 表声明替代数据库 + ETL + API 服务三层，适合 Agent 直接产出可部署后端，但云端 Beta 阶段生产使用需谨慎评估。