realZachi/pg-jev

pg-jev — PostgreSQL 内部的自然语言查询

pg-jev 是一个 PostgreSQL 扩展，让您可以使用由名为 Jev (来自 TypeSafe) 的 AI 模型驱动的自然语言条件，来筛选、排序和分类数据表中的行。您无需编写 WHERE age > 40 AND country = 'France'，而是可以编写 WHERE jev(people, 'the name is European')。

功能说明

它新增了 SQL 函数，可根据您以自然语言编写的条件来判断每一行：

• jev(row, 'condition') — 返回 true/false，可用于 WHERE 子句
• jev_prob(row, 'condition') — 返回该行符合条件的概率 (0–1)
• jev_choice(row, 'question', options) — 从列表中选择最可能的选项 (例如：哪个团队应该处理此工单)
• jev_score(row, 'question', levels) — 在有序量表上对行进行排名 (例如：此产品的奢华程度)

由于这些是普通的 SQL 函数，它们可以与其他所有功能组合使用：joins、GROUP BY、ORDER BY、LIMIT 以及其他 WHERE 谓词。

运作原理

1. 当您在数据表上调用 jev() 时，扩展会启动 read-ahead：它会以物理顺序串流读取数据表，并对行进行批处理。
2. 每一行会被打包成 每 API 请求 20 行 的单一共享状态，每行对应一个是非题。模型会平行评估所有 20 个问题，这分摊了每个请求的开销 (每批 20 行约 175 个 token，而单行约 435 个)。
3. 多个请求通过持久的 HTTPS 连接并发执行。一旦回答了足够的行数，LIMIT 就会停止 read-ahead，且同一个 WHERE 中的较便宜谓词会先执行，因此被拒绝的行永远不会发送到 API。
4. 回答会针对该会话的 行内容和问题进行缓存，因此重新执行查询或按概率排序在第二次执行时几乎是免费的。

在 2,000 行的数据表上测量：第一次执行约 3.5 秒，API 成本约 $0.012；第二次执行约 50 毫秒 (缓存)；在新条件下执行 LIMIT 3 约 0.6 秒。

关键设计选择

• 无索引、无嵌入、无向量列 — 设计上就是全表扫描；执行器询问的每一行都会发送到 API。
• 批次大小 20 是一个刻意的准确度权衡：根据基准测试，1–20 行的批次准确率为 100%，但 40 行的批次降至 92–98%，80 行的批次降至 77–94%。
• 校准概率，而非生成文本 — 模型为每一行返回一个概率，因此模糊的情况会落在 0.5 附近，您可以调整阈值。
• 本地服务器支持 — jev.api_url 可以指向本地的 Jev 兼容服务器，因此数据永远不会离开您的网络，也没有按行计费的问题。

安装与需求

需要 PostgreSQL 14–17 以及 plpython3u、超级用户权限和 TypeSafe API 密钥。无法提供超级用户或 plpython3u 的托管主机 (如 Supabase、Neon、RDS) 无法执行此功能。可通过 PGXN、源代码、Docker 或自动化设置的 AI 代理技能进行安装。

注意事项

• 行内容会发送到第三方 API (除非您运行本地服务器) — 请勿在无法共享的数据上使用。
• 回答缓存存在于每个后端会话中，并会随着唯一的行/问题对而增加；jev_cache_clear() 可重置它。
• plpython3u 是一种不受信任的语言，因此函数会以服务器的操作系统权限执行。
• 针对共享部署设有支出限制 (jev.max_rows_per_statement, jev.max_chars_per_statement)。

总结

pg-jev 是自然语言与 SQL 之间实用且设计精良的桥梁 — 当您想要根据 意义 (情绪、类别、语气) 而非精确值来筛选或排序数据，并且愿意支付少量的每行 API 成本并接受全表扫描时，它非常有用。