AI 函数服务语法及示例

本文档为 AI 函数服务的参考文档，介绍 OceanBase Database AI 中 AI 函数服务的功能、各函数的语法与参数、以及多种使用示例。目前支持的函数有 AI_SPLIT_DOCUMENT、AI_EMBED、AI_COMPLETE、AI_PROMPT 和 AI_RERANK。

AI 函数通过 SQL 表达式，将 AI 模型能力直接集成到数据库内的数据处理中。它极大地简化了利用 AI 大模型进行数据读取、分析、总结和保存等操作，是当前数据库和数据仓库领域的重要新特性。OceanBase Database AI 通过 DBMS_AI_SERVICE 包提供 AI 模型和端点管理，并新增了几个内置 AI 函数表达式，并支持通过视图监控 AI 模型调用情况。

前提条件（除 AI_SPLIT_DOCUMENT 外）

• 已具备 AI 模型相关权限，具体请参见 AI 函数服务权限。
• 若尚未注册 AI 模型与端点，请先按 AI 模型注册 完成注册。

注意事项（除 AI_SPLIT_DOCUMENT 外）

• CREATE AI MODEL 和 DROP AI MODEL 操作会在主备租户间同步，但 CREATE AI MODEL ENDPOINT、ALTER AI MODEL ENDPOINT 和 DROP AI MODEL ENDPOINT 操作不会。因此，备租户需要手动配置 AI 模型端点才能使用 AI 函数服务。
• 混合搜索（Hybrid Search）依赖 AI 函数服务的模型管理和嵌入（embedding）功能。在删除 AI 模型时，需检查其是否被混合搜索引用，以避免潜在问题。

函数语法及示例

本节介绍 AI 函数服务的语法及示例。

AI_SPLIT_DOCUMENT

AI_SPLIT_DOCUMENT 函数将文本切分为多个片段，为后续处理做准备。

使用

语法如下：

AI_SPLIT_DOCUMENT(content TEXT, [parameters JSON]) [AS alias_name]

参数说明：

返回值：

• 返回一个关系表，包含四个字段：CHUNK_ID、CHUNK_OFFSET、CHUNK_LENGTH、CHUNK_TEXT。其中，CHUNK_ID 为切分后的块 ID，CHUNK_OFFSET 为切分后的块起始位置，CHUNK_LENGTH 为切分后的块长度（字节），CHUNK_TEXT 为切分后的块的文本内容。

限制如下：

• 目前仅支持对 UTF-8 编码的数据进行切分。
• 该函数只能在 FROM 子句后作为表函数使用，不支持直接作为标量函数出现在 SELECT 列表中。

示例

SELECT * FROM ai_split_document("你好世界",'{"max":1}');

返回结果如下：

+----------+--------------+--------------+------------+
| CHUNK_ID | CHUNK_OFFSET | CHUNK_LENGTH | CHUNK_TEXT |
+----------+--------------+--------------+------------+
|        0 |            0 |            6 | 你好       |
|        1 |            6 |            6 | 世界       |
+----------+--------------+--------------+------------+

AI_EMBED

AI_EMBED 函数通过 model_key 指定一个已注册的嵌入模型（Embedding Model），将用户提供的文本数据转换为向量数据。当模型支持多个维度时，允许通过 dim 参数指定输出相关维度的向量。

使用

语法如下：

AI_EMBED(model_key, input, [dim])

参数说明：

必须指定 model_key、input，并且其中一个为 NULL 时，函数提示报错。

返回值：

• vector 格式的字符串，嵌入模型根据文本转换的向量。

示例

1. 嵌入单行数据

   SELECT AI_EMBED("ob_embed","Hello world") AS embedding;
   

   返回结果如下：

   +----------------+
   | embedding      |
   +----------------+
   | [0.1, 0.2, 0.3]|	
   +----------------+
   

2. 嵌入表上列

   CREATE TABLE comments (
       id INT AUTO_INCREMENT PRIMARY KEY,
       content TEXT
   );
   
   INSERT INTO comments (content) VALUES ('hello world!');
   
   SELECT AI_EMBED("ob_embed",content) AS embedding FROM comments;
   

   返回结果如下：

   +----------------+
   | embedding      |
   +----------------+
   | [0.1, 0.2, 0.3]|	
   +----------------+
   

AI_COMPLETE 和 AI_PROMPT

AI_COMPLETE 函数通过 model_key 指定一个已注册的文本生成大模型（LLM），对用户提供的提示词（prompt）和数据进行处理，并返回大模型生成的文本信息。用户可以在 prompt 参数中自定义组织提示词和数据库内的数据格式。这种方式不仅支持对文本数据进行多样化处理，还能在数据库内部实现批量处理，有效避免了数据在数据库与大模型之间来回拷贝的开销。

考虑到许多 AI 应用场景中，提示词往往具有高度结构化特征，需要动态注入具体数据，而每次手动使用 CONCAT 等函数拼接提示词和输入内容，不仅开发成本高，还容易写错导致格式问题。为了支持提示词复用和提示词与数据动态组合的需求，OceanBase Database AI 提供了 AI_PROMPT 函数。AI_PROMPT 将提示词从"静态文本"升级为"可复用、可参数化"的函数模板形式，可以在 AI_COMPLETE 中替代 prompt 参数直接使用，从而极大地简化了提示词的构建过程，提升了开发效率和准确性。

AI_PROMPT 函数

AI_PROMPT 函数用于基于提示词模版动态构建格式化的提示词，支持动态插入数据。

语法

AI_PROMPT 函数语法如下：

AI_PROMPT('template', expr0 [ , expr1, ... ]);

参数说明：

参数 template 和 expr 为必填项，不允许为空。其中，expr 参数只支持 VARCHAR 类型，不支持 JSON 类型。

返回值：

• 返回值为格式化后的提示词，返回值类型为 JSON。

示例

AI_PROMPT 函数将模板字符串和动态数据组织成 JSON 格式：

• 第一个参数（模板字符串 template）会被放在返回 JSON 的 template 字段中。
• 后续的参数（数据值 expr0、expr1、...）会被放在返回 JSON 的 args 数组中。
• 模板中的占位符 {0}、{1} 等会按索引对应 args 数组中的数据，在 AI_COMPLETE 函数中使用时会被自动替换。

例如：

SELECT AI_PROMPT('Recommend {0} of the most popular {1} to me.', 'ten', 'mobile phones');

返回结果如下：

{
  "template": "Recommend {0} of the most popular {1} to me.",
  "args": ["ten", "mobile phones"]
}

基于上个例子，在 AI_COMPLETE 函数中使用 AI_PROMPT 函数：

SELECT AI_COMPLETE("ob_complete",AI_PROMPT('Recommend {0} of the most popular {1} to me.just output name in json array format', 'two', 'mobile phones')) AS ans;

返回结果如下：

+--------------------------------------------------+
| ans                                              |
+--------------------------------------------------+
| ["iPhone 15 Pro Max","Samsung Galaxy S24 Ultra"] |
+--------------------------------------------------+

AI_COMPLETE 函数

语法

AI_COMPLETE 函数语法如下：

AI_COMPLETE(model_key, prompt[, parameters])
--如果使用 AI_PROMPT 函数，则将 prompt 参数替换为 AI_PROMPT 函数，示例见 AI_PROMPT 函数。
AI_COMPLETE(model_key, AI_PROMPT(prompt_template, data))

参数说明：

必须指定 model_key、prompt，并且其中一个为 NULL 时，函数提示报错。

返回值：

• text，大模型根据提示词生成的文本。

示例

1. 情感分析示例

   SELECT AI_COMPLETE("ob_complete","你的任务是对提供的文本进行情感分析，判断其情感倾向为正面还是负面。
   以下是需要分析的文本：
   <text>
   天气真好啊
   </text>
   判断标准如下：
   如果文本表达的是正面情感，输出1；如果文本表达的是负面情感，输出 -1。不要输出其他东西.\n") AS ans;
   

   返回结果如下：

   +-----+
   | ans |
   +-----+
   | 1   |
   +-----+
   

2. 翻译示例

   CREATE TABLE comments (
       id INT AUTO_INCREMENT PRIMARY KEY,
       content TEXT
   );
   
   INSERT INTO comments (content) VALUES ('hello world!');
   
   -- 以 concat 表达式形式将处理的数据替换成数据库中表上的列名，自然地就能对数据库中的数据进行批量处理，而无需将数据从数据库拷贝到大模型和将大模型结果拷贝回数据库内
   SELECT AI_COMPLETE("ob_complete",
   concat("你是一个翻译大师，你需要将以下将英语翻译成中文。以下是需要翻译的文本：<text>",
       content,
       "</text>")) AS ans FROM comments;
   

   返回结果如下：

   +-------------+
   | ans         |
   +-------------+
   | 你好，世界！  |
   +-------------+
   

3. 分类示例

   SELECT AI_COMPLETE("ob_complete","你是一个分类大师，你会获取到一堆问题文本，你需要区分这些问题的归属，归属列表为[\"硬件部\",\"软件部\",\"其他\"].以下是需要分析的文本：
   <text>
   这块屏幕质量真差
   </text>") AS res;
   

   返回结果如下：

   +--------+
   | res    |
   +--------+
   | 硬件部 |
   +--------+
   

AI_RERANK

AI_RERANK 函数通过 model_key 指定一个已注册的重排序模型（Rerank Model），将用户提供的查询词和文档列表按厂商规则组织消息发送给指定模型，解析并返回模型返回的排序结果，适用于 RAG 的 rerank 场景。

使用

语法如下：

AI_RERANK(model_key, query, documents[, document_key])

参数说明：

必须指定 model_key、query、documents，并且其中一个为 NULL 时，函数提示报错。

返回值：

• JSON 数组，包含重排序模型返回的文档及其相关性分数，并按相关性分数降序排列。

示例

SELECT AI_RERANK("ob_rerank","Apple",'["apple","banana","fruit","vegetable"]');

返回结果如下：

+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ai_rerank("ob_rerank","Apple",'["apple","banana","fruit","vegetable"]')                                                                                                                                                                                                                                                                                   |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| [{"index": 0, "document": {"text": "apple"}, "relevance_score": 0.9912109375}, {"index": 1, "document": {"text": "banana"}, "relevance_score": 0.0033512115478515625}, {"index": 2, "document": {"text": "fruit"}, "relevance_score": 0.0003669261932373047}, {"index": 3, "document": {"text": "vegetable"}, "relevance_score": 0.00001996755599975586}] |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

查看 AI 模型信息

OceanBase Database AI 支持通过视图查看已注册的 AI 模型和 AI 模型端点信息，具体请参见：

• CDB/DBA_OB_AI_MODELS：查看 AI 模型信息。
• CDB/DBA_OB_AI_MODEL_ENDPOINTS：查看 AI 模型端点信息。

相关文档

• AI 模型注册：注册模型与端点的完整命令。
• AI 函数服务快速上手：首次使用指引，从注册到运行第一个示例的最少步骤。
• 向量嵌入技术
• 权限分类