AI 函数

云器 Lakehouse AI Functions 是一组内置于 SQL 引擎的 AI 增强函数，无需离开数据平台、无需编写 Python 脚本，即可在标准 SQL 查询中直接调用大语言模型（LLM）和嵌入模型，对文本、图像、音频等内容进行智能化处理。

详细介绍请参阅 AI 函数概述。

模型接入方式

AI Functions 支持通过以下方式配置默认模型（按推荐程度排列）：

方式一：创建新工作区时开启开关（推荐）

2026 年 9 月起新建的工作区，在创建时打开 "启用 AI Function" 开关，系统将自动为每个 AI 函数配置默认模型。配置后，调用函数时可以完全省略 model 参数：

SELECT AI_SENTIMENT('这个产品很好！') AS sentiment;

方式二：工作区级别 ALTER WORKSPACE 配置

通过

ALTER WORKSPACE

ALTER WORKSPACE <workspace_name> SET PROPERTIES ( 'cz.sql.ai.complete.default.model' = '<connection>:<model>' );

方式三：会话级 SET 覆盖

在当前会话中临时指定默认模型，优先级高于工作区属性，仅当前 session 生效：

SET cz.sql.ai.complete.default.model=conn_bailian:qwen/qwen3.6-flash; SELECT ai_complete('请简要介绍量子计算的基本原理。');

方式四：API Connection 连接对象

通过

CREATE API CONNECTION

CREATE API CONNECTION conn_bailian TYPE ai_function PROVIDER = 'bailian' BASE_URL = 'https://dashscope.aliyuncs.com/api/v1' API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx'; SELECT AI_SENTIMENT('conn_bailian:qwen3.5-plus', '这个产品很好！');

函数列表

文本理解与生成

AI_COMPLETE

通用 LLM 补全函数，支持自定义 Prompt，适合复杂推理、代码生成等专用函数无法覆盖的自定义场景。

-- 使用工作区默认模型（推荐） ai_complete(<prompt> [, json '{}']) -- 或手动指定连接 ai_complete('<connection>:<model>', <prompt> [, json '{}']) -- 图像模式 ai_complete('<connection>:<model>', (<prompt> AS prompt, <image_url> AS image) [, json '{}'])

返回值： STRING，模型生成的响应文本。通过

output.behavior

formatted_json

raw_string

fail_on_error

使用说明：

• model 参数可省略，系统自动使用工作区默认模型
• 当任务可以用专用函数（如

  AI_TRANSLATE

  AI_TRANSLATE
  、

  AI_SENTIMENT

  AI_SENTIMENT
  ）完成时，优先使用专用函数，结果更稳定、成本更低
• 图像模式必须使用支持多模态的模型（如

  doubao-seed-2-0-pro-260215

  doubao-seed-2-0-pro-260215
  ）；纯文本模型传入图像时不报错但会忽略图片内容
• qwen3 系列模型默认开启 thinking 模式，批量处理建议通过 options 关闭：

  json '{"model.params":{"enable_thinking":false}}'

  json '{"model.params":{"enable_thinking":false}}'

• prompt

  prompt
  为 NULL 或空字符串时返回 NULL

详细文档：AI_COMPLETE

AI_SUMMARIZE

对输入文本生成简洁摘要，支持通过

max_words

-- 使用工作区默认模型（推荐） AI_SUMMARIZE(content [, max_words] [, options]) -- 或手动指定连接 AI_SUMMARIZE(model, content [, max_words] [, options])

返回值： STRING，输入文本的摘要。

使用说明：

• model 参数可省略，系统自动使用工作区默认模型

• max_words

  max_words
  默认为 50，是目标值而非硬限制，实际输出可能有 ±20% 偏差

• max_words=0

  max_words=0
  时返回原始文本，不调用模型

• max_words

  max_words
  为负数时报错
• 输入为 NULL 时返回 NULL，输入为空字符串时返回空字符串
• 输出语言自动跟随输入语言

详细文档：AI_SUMMARIZE

AI_TRANSLATE

将输入文本翻译成指定语言，源语言自动检测，支持 20+ 语言互译。

-- 使用工作区默认模型（推荐） AI_TRANSLATE(content, to_lang [, options]) -- 或手动指定连接 AI_TRANSLATE(model, content, to_lang [, options])

返回值： STRING，翻译后的文本。

使用说明：

• model 参数可省略，系统自动使用工作区默认模型

• to_lang

  to_lang
  必须为有效的 ISO-639 语言代码（如

  'zh'

  'zh'
  、

  'en'

  'en'
  、

  'ja'

  'ja'
  ），不支持语言全名
• 不支持手动指定源语言，始终自动检测
• 输入与目标语言相同时返回原文不变
• 可与

  AI_SUMMARIZE

  AI_SUMMARIZE
  组合使用（先摘要再翻译）

详细文档：AI_TRANSLATE

AI_FIX_GRAMMAR

自动修复输入文本中的语法、拼写和标点错误，支持中英文及多语言混合文本。

-- 使用工作区默认模型（推荐） AI_FIX_GRAMMAR(content [, options]) -- 或手动指定连接 AI_FIX_GRAMMAR(model, content [, options])

返回值： STRING，修正后的文本；若输入无语法错误，返回原文不变。

使用说明：

• model 参数可省略，系统自动使用工作区默认模型
• 输入为 NULL 时返回 NULL，输入为空字符串时返回空字符串
• 中英混合文本会智能统一为主要语言
• 以语法修正为主，极少数情况下可能修改语义，语义敏感场景建议人工抽检
• 建议在

  AI_SENTIMENT

  AI_SENTIMENT
  或

  AI_SUMMARIZE

  AI_SUMMARIZE
  之前先用此函数清洗文本

详细文档：AI_FIX_GRAMMAR

文本分析与分类

AI_CLASSIFY

将文本或图像归入用户定义的类别，无需编写 Prompt，支持 29+ 种语言及跨语言分类。

-- 使用工作区默认模型（推荐） AI_CLASSIFY(content, labels [, options]) -- 或手动指定连接 AI_CLASSIFY(model, content, labels [, options])

返回值： STRING，返回最匹配的类别名称（纯字符串，非 JSON）。

使用说明：

• model 参数可省略，系统自动使用工作区默认模型

• labels

  labels
  为 ARRAY(STRING)，建议 2~10 个类别，类别名称要有描述性语义
• 图像输入使用

  GET_PRESIGNED_URL(USER VOLUME, path, expiry) AS image

  GET_PRESIGNED_URL(USER VOLUME, path, expiry) AS image
  语法
• 批量分类建议设置

  enable_thinking:false

  enable_thinking:false
  加速响应
• 可通过

  classify.pack_size

  classify.pack_size
  控制打包行数，

  classify.pack_max_tokens

  classify.pack_max_tokens
  控制 token 上限
• 输入为 NULL 时返回 NULL，输入为空字符串时返回空字符串

  ""

  ""
• 标签可统一用英文，即使输入是其他语言也能正确分类

详细文档：AI_CLASSIFY

AI_SENTIMENT

对输入文本进行情感倾向分析，支持中文、英文、日文等多语言。

-- 使用工作区默认模型（推荐） AI_SENTIMENT(text [, options]) -- 或手动指定连接 AI_SENTIMENT(model, text [, options])

返回值： STRING，为以下值之一：

positive

negative

neutral

mixed

使用说明：

• model 参数可省略，系统自动使用工作区默认模型
• 输入为 NULL 或空字符串时返回 NULL
• 能识别讽刺/反语、双重否定、emoji 情感等复杂语义

• mixed

  mixed
  表示文本中同时存在正负评价；

  neutral

  neutral
  表示文本不含情感倾向
• 结果具有非确定性，同一输入多次执行结果可能略有差异

详细文档：AI_SENTIMENT

AI_EXTRACT

从非结构化文本或图像中按指定字段提取结构化 JSON 数据，无需编写 Prompt。

-- 使用工作区默认模型（推荐） AI_EXTRACT(content, schema [, options]) -- 或手动指定连接 AI_EXTRACT(model, content, schema [, options])

返回值： STRING（JSON 格式），包含

schema

使用说明：

• model 参数可省略，系统自动使用工作区默认模型

• schema

  schema
  格式为

  JSON'{"key":"字段描述", ...}'

  JSON'{"key":"字段描述", ...}'
  ，value 支持简单标签或问句描述
• 字段数建议不超过 10 个，最多支持约 20 个
• 文本中找不到对应字段时，该字段值为空字符串

  ""

  ""
• 输入为 NULL 或空字符串时返回 NULL
• 返回值为 JSON 字符串，可配合

  json_extract_string

  json_extract_string
  进一步解析

详细文档：AI_EXTRACT

AI_MASK

识别并脱敏文本中的 PII 敏感信息，用

[MASKED]

-- 使用工作区默认模型（推荐） AI_MASK(content, labels [, options]) -- 或手动指定连接 AI_MASK(model, content, labels [, options])

返回值： STRING，脱敏后的文本；若文本中不包含指定标签对应的信息，返回原文不变。

使用说明：

• model 参数可省略，系统自动使用工作区默认模型

• labels

  labels
  为 ARRAY(STRING)，数量须在 1~20 之间，不能为空数组
• 标签越具体越精准（如"身份证号"比"证件"更准确）
• 标签语言与文本语言匹配效果更佳
• 所有被脱敏信息统一替换为

  [MASKED]

  [MASKED]
  ，不区分类型
• AI 脱敏基于 LLM，可能存在漏脱或误脱，合规场景建议人工抽检

详细文档：AI_MASK

向量与语义搜索

AI_EMBEDDING

将文本转换为高维嵌入向量，用于语义检索、推荐、聚类等下游任务。

-- 使用工作区默认模型（推荐） AI_EMBEDDING(input [, model_parameters]) -- 或手动指定连接 AI_EMBEDDING(model, input [, model_parameters])

返回值： ARRAY<FLOAT>，输入文本的嵌入向量。

使用说明：

• model 参数可省略，系统自动使用工作区默认模型
• 必须使用嵌入模型（如

  text-embedding-v4

  text-embedding-v4
  ），不能使用对话补全模型

• model_parameters

  model_parameters
  中

  input

  input
  （

  'document'

  'document'
  /

  'query'

  'query'
  ）和

  dimensions

  dimensions
  为必填项
• 结果具有确定性，相同输入始终返回相同向量
• 检索场景中，文档入库使用

  "input":"document"

  "input":"document"
  ，用户查询使用

  "input":"query"

  "input":"query"
• 可通过

  embeddings.batch_size

  embeddings.batch_size
  控制批量大小，

  embeddings.batch_max_tokens

  embeddings.batch_max_tokens
  控制 token 上限
• 输入为 NULL 时返回 NULL；输入为空字符串时报错，调用前需过滤
• 输入长度上限为 8,192 tokens

详细文档：AI_EMBEDDING

AI_SIMILARITY

基于 Embedding 模型计算两段文本的余弦相似度，返回 [0, 1] 分值。

-- 使用工作区默认模型（推荐） AI_SIMILARITY(text1, text2 [, options]) -- 或手动指定连接 AI_SIMILARITY(model, text1, text2 [, options])

返回值： FLOAT，余弦相似度，实际使用中通常落在 [0, 1] 区间。

使用说明：

• model 参数可省略，系统自动使用工作区默认模型
• 必须使用嵌入模型，不能使用 LLM
• 结果具有确定性，函数具有对称性（

  a,b

  a,b
  与

  b,a

  b,a
  结果相同）
• 任一参数为 NULL 时返回 0
• 支持跨语言相似度计算（如中文与英文语义对比）
• 批量 CROSS JOIN 场景 token 消耗 = 行数² × 平均 token 数，请提前评估配额

详细文档：AI_SIMILARITY

多模态处理

AI_TRANSCRIBE

将 Volume 中的音频文件转录为纯文本（ASR），支持中文、英文等多语言。

-- 使用工作区默认模型（需预先配置 ASR 默认模型） AI_TRANSCRIBE(audio_url [, options]) -- 或手动指定连接 AI_TRANSCRIBE(model, audio_url [, options])

返回值： STRING，音频内容的纯文本转录结果，不含时间戳或说话人信息。

使用说明：

• model 参数可省略，系统自动使用工作区默认 ASR 模型

• audio_url

  audio_url
  必须是

  http://

  http://
  或

  https://

  https://
  开头的 URL，通常通过

  GET_PRESIGNED_URL()

  GET_PRESIGNED_URL()
  获取
• 支持 WAV、MP3、FLAC、M4A 格式，推荐 16kHz 单声道 WAV
• presigned URL 建议设置 36000 秒（10 小时）有效期，避免批量处理中 URL 过期
• 返回纯文本，可直接作为

  AI_CLASSIFY

  AI_CLASSIFY
  、

  AI_EXTRACT

  AI_EXTRACT
  等函数的输入
• 静音或近静音文件可能产生少量幻觉文本，建议下游做长度过滤

详细文档：AI_TRANSCRIBE

通用 options 参数

AI 函数支持通过可选的

options

输出格式控制

output.behavior

formatted_json

formatted_json

raw_string

fail_on_error

三种模式对比：

formatted_json

{"value":"模型输出"}

{"value":"","error_message":"..."}

raw_string

fail_on_error

模型参数

model.params.temperature

model.params.max_tokens

model.params.enable_thinking

运行时参数

response.timeout

"300"

task.concurrency

"12"

优化参数

classify.pack_size

classify.pack_max_tokens

embeddings.batch_size

embeddings.batch_max_tokens

-- 综合示例 SELECT AI_CLASSIFY( content, ARRAY('类别1', '类别2'), JSON '{"output.behavior":"raw_string","model.params":{"enable_thinking":false},"classify.pack_size":"10","task.concurrency":"4"}' ) AS category FROM table;

使用前提

1. 通过工作区开关（新工作区）自动配置，或通过

   ALTER WORKSPACE

   ALTER WORKSPACE
   / 会话级

   SET

   SET
   配置各函数的默认模型。
2. 如需手动指定模型，需通过

   CREATE API CONNECTION

   CREATE API CONNECTION
   创建连接对象。
3. 图像和音频处理场景需将文件上传至 Volume，并通过

   GET_PRESIGNED_URL()

   GET_PRESIGNED_URL()
   获取访问 URL。

相关文档

• AI 函数概述
• AI_COMPLETE
• AI_CLASSIFY
• AI_EXTRACT
• AI_SENTIMENT
• AI_SUMMARIZE
• AI_TRANSLATE
• AI_FIX_GRAMMAR
• AI_MASK
• AI_EMBEDDING
• AI_SIMILARITY
• AI_TRANSCRIBE

通过外部函数自定义 AI 函数

除内置 AI Functions 外，云器 Lakehouse 还支持通过**外部函数（External Function）**框架自行开发 AI 函数，适用于需要对接私有模型、离线推理包或自定义业务逻辑的场景。

外部函数（亦称远程函数，Remote Function）是一种特殊的自定义函数（UDF），允许用户通过 Python 或 Java 定义函数逻辑，核心计算任务卸载到外部远程服务执行（支持阿里云函数计算 FC、腾讯云云函数 SCF）。在执行过程中可调用：

• 在线服务：以 API 形式对外提供的在线服务，如大语言模型 API、云平台提供的在线 AI API 服务。
• 离线功能：将特定功能函数代码、依赖库、模型和数据等文件打包成的离线服务包，如从 Hugging Face 下载的图像识别模型等。

云器 Lakehouse 通过创建 API Connection，在元数据中保存外部函数计算服务的连接和访问信息。外部函数通过 HTTP 协议调用外部函数计算服务，实现数据处理并返回结果。

预览

Lakehouse 平台在获得用户预先授权后，于创建外部函数时，将自动在客户账号下的函数计算服务中部署该函数。当用户在 SQL 查询中使用外部函数时，由外部函数实现与外部计算服务的安全连接、数据处理并返回查询结果。

外部函数创建主要流程：使用流程: External Function

开发指南：

• External Function（Python3）
• External Function（Java）