AI 函数服务语法及示例

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

AI 函数通过 SQL 表达式，将 AI 模型能力直接集成到数据库内的数据处理中。它极大地简化了利用 AI 大模型进行数据读取、分析、总结和保存等操作，是当前数据库和数据仓库领域的重要新特性。OceanBase 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 参数指定输出相关维度的向量；对图片输入时，通过 JSON 参数 {"type":"image"} 指定输入类型。

使用

语法如下：

AI_EMBED(model_key, input[, dim[, parameters]])

参数说明：

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

返回值：

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

示例

1. 嵌入单行数据

   SELECT AI_EMBED('aliyun-dashscope/text-embedding-v3', '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('aliyun-dashscope/text-embedding-v3', content) AS embedding FROM comments;
   

   返回结果如下：

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

3. 图片嵌入

   SET @img_url = 'https://example.com/image.jpg';
   
   -- 图片 URL 向量化
   SELECT AI_EMBED('aliyun-dashscope/qwen2.5-vl-embedding', @img_url, '{"type":"image"}') AS embedding;
   
   -- 图片二进制数据向量化（BASE64）
   SELECT AI_EMBED('aliyun-dashscope/qwen2.5-vl-embedding', FROM_BASE64(@img_base64), '{"type":"image"}') AS embedding;
   

4. 以图搜图

   结合 cosine_distance 比较图片向量相似度：

   SET @query_vec = AI_EMBED('aliyun-dashscope/qwen2.5-vl-embedding', @img_url, '{"type":"image"}');
   SELECT
       id,
       cosine_distance(
           AI_EMBED('aliyun-dashscope/qwen2.5-vl-embedding', image_url, '{"type":"image"}'),
           @query_vec
       ) AS distance
   FROM image_table
   WHERE image_url IS NOT NULL
   ORDER BY distance ASC
   LIMIT 3;
   

AI_COMPLETE 和 AI_PROMPT

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

考虑到许多 AI 应用场景中，提示词往往具有高度结构化特征，需要动态注入具体数据，而每次手动使用 CONCAT 等函数拼接提示词和输入内容，不仅开发成本高，还容易写错导致格式问题。为了支持提示词复用和提示词与数据动态组合的需求，OceanBase 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。URL 图片在 JSON 中包含 type=image 与 url 字段；二进制图片包含 type=image、format 与 data 字段。

示例

AI_PROMPT 函数会将用户提供的模板字符串与动态数据组织成 JSON 格式，便于下游 AI 函数自动替换和复用。其使用主要分为两类场景：文本占位与图片占位。

1. 文本占位符使用示例

   文本占位符通过 {0}、{1} 等在模板中进行标记，随后会用参数顺序对应的文本自动替换。

   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"] |
   +--------------------------------------------------+
   

2. 图片占位符使用示例

   图片占位符通过 {img_0}、{img_1} 等在模板中进行标记，对应的参数传入图片 URL 或二进制数据。支持多模态大模型进行图片内容处理。

   图片占位符规则如下：

   • 如果所有参数都是图片，只需要用 {img_0}、{img_1} 等方式依次标记，每个图片参数对应一个编号，编号从 0 开始，和文本占位符 {0}、{1} 没有关系。
   • 如果图片参数和文本参数混合使用，那么 {img_N} 中的 N 就是这个参数在所有参数中的位置（下标，从 0 开始），和文本占位符 {N} 的编号一致。比如第二个参数（下标 1）如果是图片，就写 {img_1}；第四个参数（下标 3）如果是图片，就写 {img_3}，不用按第几张图单独编号。

   示例如下：

   -- 单图片 URL
   SELECT AI_PROMPT('请描述这张图片 {img_0}', @img_url) AS result;
   
   -- 多图片对比
   SELECT AI_PROMPT(
       '比较这两张图片 {img_0} 和 {img_1} 的差异',
       @img_url_1,
       @img_url_2
   ) AS result;
   
   -- 文本与图片混合（图片在下标 1，故用 {img_1}）
   SELECT AI_PROMPT(
       '请用 {0} 句话描述这张 {img_1} 图片',
       '3',
       @img_url
   ) AS result;
   
   -- 文本与图片交错（第二张图在下标 3，故用 {img_3}）
   SELECT AI_PROMPT(
       '对比 {0} 格式的图片 {img_1} 和 {2} 格式的图片 {img_3}，用一句话总结差异',
       'JPEG',
       @img_jpeg,
       'PNG',
       @img_png
   ) AS result;
   

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    |
   +--------+
   | 硬件部 |
   +--------+
   

4. 图片处理

   注意

   本功能从 V4.6.2.1 版本开始支持。

   SET @img_url = 'https://example.com/image.jpg';
   
   -- 单图片处理（URL）
   SELECT AI_COMPLETE(
       'aliyun-dashscope/qwen3.5-plus',
       AI_PROMPT('请描述这张图片 {img_0}', @img_url)
   ) AS result;
   
   -- 单图片处理（BASE64）
   SELECT AI_COMPLETE(
       'aliyun-dashscope/qwen3.5-plus',
       AI_PROMPT('请描述这张图片 {img_0}', FROM_BASE64(@img_base64))
   ) AS result;
   
   -- 多图片对比
   SELECT AI_COMPLETE(
       'aliyun-dashscope/qwen3.5-plus',
       AI_PROMPT(
           '对比 {0} 格式的图片 {img_1} 和 {2} 格式的图片 {img_3}，用一句话总结差异',
           'JPEG',
           @img_jpeg,
           'PNG',
           @img_png
       )
   ) AS result;
   

AI_RERANK

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

使用

语法如下：

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

参数说明：

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

返回值：

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

示例

-- documents 为字符串数组（省略 document_key）
SELECT AI_RERANK("aliyun/gte-rerank-v2","Apple",'["apple","banana","fruit","vegetable"]');

-- documents 为对象数组，用 document_key 指定参与排序的文本字段
SELECT AI_RERANK(
  "aliyun/gte-rerank-v2",
  "Apple",
  '[{"text":"apple","id":1},{"text":"banana","id":2},{"text":"fruit","id":3}]',
  'text'
);

返回结果如下（字符串数组示例）：

+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 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 AI 数据库支持通过视图查看已注册的 AI 模型和 AI 模型端点信息，具体请参见：

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

相关文档

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