Pixeltable：把数据库、编排与 HTTP 服务压进一个 app.py

它要消灭的是管道之间的胶水代码

一个典型的 AI 数据应用通常由四块拼成：对象存储放原始图片和视频，向量库存 embedding，编排工具跑模型调用，最后再写一个 FastAPI 或 Flask 服务把这些东西串起来暴露成接口。四块之间靠代码搬运数据，搬运代码本身不产生业务价值，却最容易在字段改名或模型升级时出错。Pixeltable 的判断是这四层可以合并：媒体文件直接作为表的列存在，一次模型调用就是一个计算列，索引是声明，HTTP 路由也是声明。README 给的原话是，插入一行，它下面的一切都会运行。目标读者是那些已经在用 Python 写数据处理、但被多套系统之间的同步逻辑拖住的工程师，尤其是做多模态检索、RAG 和视频分析的人。

TableModel 里注解和赋值是两种不同的东西

理解 Pixeltable 的关键在于区分类体里的两类语句。`doc_id: pxt.Int` 是注解，它声明一个由调用方插入的值；`title_upper = pxtf.string.upper(title)` 是赋值，它声明一个计算列，在插入和更新时自动重算。README 的示例里两者并排出现，还额外演示了 `@pxt.udf` 装饰器：`excerpt` 是一个普通 Python 函数，被 `summary = excerpt(title)` 引用后成为计算列。这意味着计算逻辑的边界由你控制，内置函数用 `pxtf`，自定义逻辑用 udf。计算列的触发时机是插入与更新，这一点决定了它的成本模型：写放大发生在写入路径上，读取路径拿到的是已经算好的结果。对于需要反复查询同一批 embedding 或同一批缩略图的场景，这个方向是合理的；对于写多读少、且计算昂贵的场景，插入时的延迟会直接暴露给调用方。

pxt 命令链里 schema 与 service 是两条独立的线

README 反复强调了一组容易混淆的边界，值得原样记住：`pxt schema update` 创建目录和表，但不启动 HTTP；`pxt service update` 启动 HTTP，但不创建表。也就是说目录结构和进程生命周期是分开管理的，先 schema 后 service。本地跑通的最短路径是 `pip install 'pixeltable[serve]'`，然后 `pxt init`，再 `pxt service example --out app.py` 生成一个可运行的示例文件，接着 `pxt schema update app.py my_app` 和 `pxt service update app.py my_app`。端口不是硬编码的，README 明确要求从 `pxt service list --json | jq -r '.[0].endpoint'` 读回来再拼 URL，示例的 curl 请求体是 `{"doc_id": 1, "title": "Hello", "body": "world"}`，返回 `{"title_upper":"HELLO","summary":"Hello"}`。路由声明在 `FastAPIRouter` 上，`add_insert_route` 对应写入并返回计算列，`add_compute_route` 对应只算不写。

本地与 Cloud 之间有一道不能跨的命令

README 里最容易被忽略的一句是：`pxt service run` 只能在本地跑，无法指向 Cloud。要部署到 Pixeltable Cloud，路径是先在控制台创建 API key，设置环境变量 `PIXELTABLE_API_KEY`，在 `pixeltable.toml` 里写明数据库名，然后用 URI 形式执行 `pxt db update pxt://org:mydb`、`pxt schema update app.py pxt://org:mydb`、`pxt service update app.py pxt://org:mydb`。这里还有一条边界：`pxt db update` 创建或更新托管数据库，但不插入行。Cloud 本身标注为 Limited Beta，README 给出的联系方式是发邮件到 contact@pixeltable.com。对于把数据放在自建机房、或者需要审计部署链路的团队，Beta 状态本身就是需要纳入考量的信息。

不想暴露 HTTP 时的退路是 export_sql

并非所有场景都需要把表暴露成接口。README 给出的替代做法是先执行 `pxt schema update`，然后从 Python 直接插入数据，再用 `export_sql` 导出。这条路径适合把 Pixeltable 当作批处理管道使用，计算列照常触发，但不产生任何监听端口。另一种集成方式是把路由挂到已有服务上，用 `app.include_router(...)` 把 `FastAPIRouter` 并入现有的 FastAPI 应用，这样鉴权、日志和中间件可以复用原有实现，不必让 Pixeltable 接管整个进程。这两种做法说明 Pixeltable 并不强制你接受它的服务层，但服务层之外的能力边界，文档描述得比服务层本身要薄。

与直接用 Postgres 加 pgvector 的差别在哪

最自然的对照是自己搭一套 Postgres 加 pgvector，再配一个任务队列。两者的差别不在存储引擎，而在计算列这个概念。Postgres 的生成列只能写 SQL 表达式，无法直接调用 Python 函数或模型；要在写入时跑模型，你得自己写触发器、外部 worker 或者 CDC 流程，把结果回写。Pixeltable 把这一步变成类体里的一行赋值，代价是计算逻辑必须活在 Python 进程里，数据库本身不理解这些函数。另一个差别是路由：用 Postgres 方案你必须另写服务层，Pixeltable 把 `add_insert_route` 放进同一个文件。反过来说，Postgres 生态里的在线迁移工具、只读副本、行级权限，Pixeltable 目前没有对应物，README 只提供了 `export_sql` 这个出口。

版本节奏与升级时要盯的地方

仓库最近的发布节奏偏快，v0.7.4 到 v0.7.6 之间只隔了一周左右，三个版本集中在 2026 年 9 月上旬。这种节奏对早期项目是常态，但也意味着小版本之间可能出现行为调整。README 里有一条具体的版本约束值得单独拎出来：Skill 2.8.0 及以上写出的 app.py 使用 `TableModel`，如果你的编码代理生成的代码里出现 `create_table`，说明本地安装的 skill 是旧的，需要重新执行 `npx skills add pixeltable/pixeltable-skill`。同时 README 说明 notebook 和测试仍然使用 `pxt.create_table()`，也就是说两套写法在仓库内并存，读示例代码时要先确认它属于哪一类。许可方面，项目采用 Apache-2.0，允许商用和修改，但 README 没有描述 Cloud 服务的商业条款，自托管与托管是两套不同的授权语境，这一点需要向项目方确认，这里不构成法律意见。

什么时候它是对的，什么时候该换

判断标准可以落到具体问题上。如果你的数据是图片、视频、音频或文档，管道里既有 Python 函数又有模型调用，并且你希望表定义、计算列和 HTTP 路由在同一个文件里演进，那么 Pixeltable 的结构和这类需求是对齐的。如果你的核心诉求是让 DBA 用熟悉的工具做在线 schema 变更、或者你需要行级权限和只读副本，那么这套方案目前给不出对应机制，`export_sql` 只是单向出口。还有一种情况要谨慎：计算列在插入时触发，如果某个模型调用耗时很长或者按量计费，写入路径的成本会变得难以预估，README 没有给出批量写入的节流参数或异步计算列的配置项，需要自己在应用层控制。

编辑结论

Pixeltable 适合这样的团队：数据形态以图像、视频、音频、文档为主，管道里既有 Python 函数又有模型调用，并且愿意把表定义、计算列和 HTTP 路由收进一个 app.py，用 pxt schema update 与 pxt service update 分开管理目录和进程。不适合的人同样明确：如果你的表结构需要频繁在线迁移、或者你依赖 Postgres 生态里成熟的权限与复制工具，Pixeltable 目前给出的替代路径只有 export_sql 这一条，README 没有描述反向导入。上手前先验证三件事：一是 pxt service list --json 返回的 endpoint 端口是否稳定，二是目标环境能否安装 pixeltable[serve] 这一组依赖，三是如果打算上 Cloud，pxt service run 不能指向 Cloud，必须改用 pxt service update app.py pxt://org:mydb 这条路径。

官方来源

1. License: Apache-2.0
2. pixeltable/pixeltable on GitHub
3. Project website
4. README
5. Releases