用SQL调用大模型:OpenTenBase opentenbase_ai插件与pgvector向量检索完整指南
用SQL调用大模型:OpenTenBase opentenbase_ai插件与pgvector向量检索完整指南
OpenTenBase 是一款企业级分布式 HTAP 开源数据库,内置的 opentenbase_ai 插件让你可以直接用 SQL 调用大模型——文本生成、翻译、情感分析、向量嵌入一条语句搞定;再配合内置的 pgvector 向量检索扩展,无需搭建任何外部中间件,就能在数据库里完成"嵌入 → 存储 → 相似度检索 → 问答"的 RAG 全流程。本文带你从零到一快速上手,10 分钟跑通第一条 SELECT ai.generate_text(...)。
OpenTenBase 采用 CN(协调节点)+ DN(数据节点)的分布式架构,
opentenbase_ai与vector扩展在 CN/DN 上均可启用,向量索引随数据分布存储,天然适配大规模检索场景。
一、为什么要在数据库里调大模型?
传统方案里,调用大模型需要应用服务拼接 HTTP 请求、解析 JSON、管理密钥,代码散落在业务层。而 opentenbase_ai 的思路是:把"调用模型"变成一条普通的 SQL 函数。
- ✅ 零中间件:扩展基于内置的 pgsql-http 扩展直接发起 HTTP 请求,不依赖向量数据库、消息队列等外部组件;
- ✅ SQL 原生集成:
ai.generate_text()可以出现在SELECT、INSERT、视图、存储过程里,与业务数据无缝组合; - ✅ 模型可插拔:所有兼容 OpenAI Chat / Embeddings API 的模型(开源模型网关、商用 API 等)都能通过一张配置表注册使用;
- ✅ 检索与生成同库:pgvector 提供
vector类型和 HNSW/IVFFlat 索引,嵌入结果直接落表,JOIN、事务、备份一应俱全。
二、快速安装:2 条语句启用扩展
opentenbase_ai 插件源码位于 contrib/opentenbase_ai/ 目录,它依赖 http 扩展(requires = 'http',见 opentenbase_ai.control),在数据库中执行:
CREATE EXTENSION http; -- 依赖:数据库内 HTTP 客户端
CREATE EXTENSION opentenbase_ai; -- AI 插件,自动创建 ai schema 与模型注册表
CREATE EXTENSION vector; -- pgvector 向量检索扩展
💡 若使用源码构建的安装方式,对应构建入口为 contrib/opentenbase_ai/Makefile 与 contrib/pgvector/Makefile,在各自目录下执行
make && make install后即可CREATE EXTENSION。
启用后数据库会自动创建:
| 对象 | 作用 |
|---|---|
ai schema |
所有 AI 函数的命名空间 |
ai_model_list 表 |
模型注册表(名称、URI、请求头、默认参数、结果提取路径) |
ai.models 视图 |
方便查询当前已注册的模型 |
三、注册你的第一个大模型
插件提供三个"开箱即用"的注册函数,分别对应三类 OpenAI 兼容 API:
-- 1. 对话生成模型(Chat Completions 兼容)
SELECT ai.add_completion_model(
'my-gpt', -- 模型别名,后续 SQL 用它
'http://your-llm-gateway/v1/chat/completions', -- API 地址
'{"model": "gpt-4o", "temperature": 0.7}'::jsonb, -- 默认请求参数
'sk-xxxxx', -- API Key(放入 Authorization 头)
'openai' -- 供应商备注
);
-- 2. 向量嵌入模型(Embeddings 兼容)
SELECT ai.add_embedding_model(
'my-embed',
'http://your-llm-gateway/v1/embeddings',
'{"model": "text-embedding-v3", "encoding_format": "float"}'::jsonb,
'sk-xxxxx',
'openai'
);
-- 3. 视觉/图像模型(可选)
SELECT ai.add_image_model(
'my-vision',
'http://your-llm-gateway/v1/chat/completions',
'{"model": "gpt-4o"}'::jsonb,
'sk-xxxxx',
'openai'
);
注册逻辑在 opentenbase_ai--1.0.sql 中实现:ai.add_completion_model() 会自动拼好 Authorization: Bearer <token> 请求头,并内置 JSONPath(choices[0].message.content)用于从响应中抽取答案;ai.add_embedding_model() 则抽取 data[0].embedding。你也可以用通用的 ai.add_model() 注册任意自定义接口。
验证与日常管理:
SELECT * FROM ai.models; -- 查看已注册模型
SELECT ai.update_model('my-gpt', 'default_args', '{"model":"gpt-4o-mini"}'); -- 改参数
SELECT ai.delete_model('my-gpt'); -- 删除模型
四、10 个 SQL 函数,把大模型写进业务
插件在 ai schema 下提供了完整的函数族,核心实现在 opentenbase_ai--1.0.sql。所有函数的第三个参数(model_name)可省略,此时使用会话默认模型:
SET ai.completion_model = 'my-gpt'; -- 默认对话模型(会话级 GUC 参数)
SET ai.embedding_model = 'my-embed'; -- 默认嵌入模型
SET ai.image_model = 'my-vision';-- 默认视觉模型
三个默认模型参数在 contrib/opentenbase_ai/ai.c 中注册。常用函数速查:
| 函数 | 说明 | 示例 |
|---|---|---|
ai.generate_text(prompt) |
通用文本生成 | SELECT ai.generate_text('用一句话介绍 HTAP'); |
ai.generate_int(prompt) |
返回整数(自动清洗非数字字符) | SELECT ai.generate_int('15 + 27 等于多少'); |
ai.generate_double(prompt) |
返回浮点数 | 计算类问答 |
ai.generate_bool(prompt) |
返回布尔值 | 分类判断 |
ai.translate(text, lang) |
机器翻译 | SELECT ai.translate('数据库', 'English'); |
ai.sentiment(text) |
情感分析(positive/negative/neutral/mixed) | 评论舆情统计 |
ai.summarize(text) |
文本摘要 | 长文自动压缩 |
ai.extract_answer(context, question) |
基于给定上下文回答问题(RAG 关键函数) | 见第七节 |
ai.embedding(text) |
文本 → 向量字符串(配合 pgvector) | 见第五节 |
ai.image(prompt, url) |
图像理解(支持 URL 或 bytea) | 报表截图解读 |
几个典型玩法:
-- 批量给产品评论打情感标签
SELECT id, ai.sentiment(content) AS label
FROM reviews;
-- 长文档摘要入库
UPDATE articles
SET summary = ai.summarize(body)
WHERE char_length(body) > 2000;
-- 图片理解:直接传 URL,或从表里取 bytea 字段
SELECT ai.image('这张仪表盘上哪个指标异常?', 'http://host/report.png');
⚠️ 小提醒:
ai.generate()系列会按返回类型自动追加"只输出数字/布尔"的系统提示并做结果清洗,因此ai.generate_int()可以直接参与WHERE、GROUP BY等 SQL 逻辑,非常适合作为"数据库内轻量推理"使用。
五、pgvector 向量检索:vector 类型 + HNSW 索引
pgvector 扩展(contrib/pgvector/,当前版本 0.8.0)为数据库带来原生的向量类型与近似最近邻(ANN)检索。核心定义见 contrib/pgvector/sql/vector.sql:
- 向量类型:
vector(768)(单精度,维度上限 16000)、halfvec(半精度,省一半空间)、bitvec(二值)、sparsevec(稀疏); - 距离函数:
l2_distance()(欧氏距离)、inner_product()(内积)、cosine_distance()(余弦距离)、l1_distance()(曼哈顿距离)等; - 距离算子:
<->(L2)、<#>(负内积)、<=>(余弦),可直接用于ORDER BY; - 索引方法:
hnsw(图索引,召回率高、查询快)与ivfflat(倒排聚类,构建快)。
5.1 建表与写入
-- 创建带向量列的文档表
CREATE TABLE docs (
id bigserial PRIMARY KEY,
content text,
embedding vector(768) -- 768 维嵌入向量
);
-- 为向量列建 HNSW 索引(余弦距离)
CREATE INDEX ON docs USING hnsw (embedding vector_cosine_ops);
5.2 相似度查询
-- 找出与查询向量最相似的 5 篇文档
SELECT id, content,
embedding <=> '[0.012, -0.034, ...]'::vector AS distance
FROM docs
ORDER BY distance
LIMIT 5;
ORDER BY embedding <=> $1 LIMIT n 会命中 HNSW 索引,避免全表扫描;若数据量不大或需要精确结果,也可以不建索引做暴力检索。
💡 选型建议:数据千万级以内、追求查询延迟选 HNSW;写入量大、内存敏感选 IVFFlat(
CREATE INDEX ON docs USING ivfflat (embedding vector_l2_ops) WITH (lists = 100))。
六、组合拳:SQL 版 RAG 问答流水线
现在把两个扩展拼起来,一条流水线完成"文档入库 → 嵌入 → 检索 → 生成答案":
第 1 步:入库并生成嵌入
-- 新增文档时,用 ai.embedding() 现场生成向量并写入
INSERT INTO docs (content, embedding)
SELECT content,
ai.embedding(content)::vector(768)
FROM new_docs;
第 2 步:检索相似上下文
WITH hits AS (
SELECT content,
content <=> ai.embedding('如何给大表建向量索引?')::vector(768) AS dist
FROM docs
ORDER BY dist
LIMIT 3
)
SELECT string_agg(content, ' ') AS context
FROM hits;
第 3 步:基于上下文生成答案
SELECT ai.extract_answer(
(SELECT context FROM rag_step2),
'如何给大表建向量索引?'
) AS answer;
ai.extract_answer() 的提示词会强制模型"只依据给定上下文回答"(见 opentenbase_ai--1.0.sql),有效降低大模型幻觉。整个过程无需一行应用代码,全部在数据库内闭环。
七、常见问题排查
| 现象 | 排查方向 |
|---|---|
CREATE EXTENSION opentenbase_ai 报依赖缺失 |
先执行 CREATE EXTENSION http; |
Model xxx not found |
模型别名拼写错误或未注册,检查 SELECT * FROM ai.models; |
Failure in http-request. http_code: ... |
数据库服务器能否访问模型网关地址?核对 URI 与 API Key |
Completion model name is not set |
未指定 model_name 且未 SET ai.completion_model |
| 嵌入维度报错 | ai.embedding() 返回的维度需与 vector(n) 声明一致 |
八、源码导读
| 想深入了解 | 去哪看 |
|---|---|
| 插件构建与依赖声明 | contrib/opentenbase_ai/Makefile |
| 默认模型 GUC 参数 | contrib/opentenbase_ai/ai.c |
| 模型注册 / 各类 AI 函数 | contrib/opentenbase_ai/opentenbase_ai--1.0.sql |
| vector 类型、距离算子与索引 | contrib/pgvector/sql/vector.sql |
| HNSW 索引实现 | contrib/pgvector/src/hnsw.c |
| 数据库内 HTTP 客户端 | contrib/pgsql-http/http.c |
写在最后:OpenTenBase 用"一个插件 + 两条 SQL"把大模型接进了 SQL 世界——opentenbase_ai 负责"生成",pgvector 负责"检索",两者合力让 RAG、智能问答、舆情分析这类 AI 场景第一次可以像写报表一样自然地写在数据库里。不妨从第三节的注册语句开始,跑通你的第一条 ai.generate_text() 吧!
