用SQL调用大模型:OpenTenBase opentenbase_ai插件与pgvector向量检索完整指南

原创2026-11-05 14:56:541,328 阅读
文章标签:数据库关系型数据库分布式数据库数据存储OLAP数据同步高可用OpenAtom

用SQL调用大模型:OpenTenBase opentenbase_ai插件与pgvector向量检索完整指南

OpenTenBase 是一款企业级分布式 HTAP 开源数据库,内置的 opentenbase_ai 插件让你可以直接用 SQL 调用大模型——文本生成、翻译、情感分析、向量嵌入一条语句搞定;再配合内置的 pgvector 向量检索扩展,无需搭建任何外部中间件,就能在数据库里完成"嵌入 → 存储 → 相似度检索 → 问答"的 RAG 全流程。本文带你从零到一快速上手,10 分钟跑通第一条 SELECT ai.generate_text(...)。

OpenTenBase 集群架构:GTM事务管理器、Coordinator协调节点与Datanode数据节点组成分布式拓扑

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() 吧!

登录后查看全文
OpenTenBase