AI_CLASSIFY

AI_CLASSIFY

AI_CLASSIFY

是云器 Lakehouse 提供的 AI 文本/图像分类函数，可将输入内容自动归类到用户自定义的类别中。无需训练模型、无需编写 prompt，一行 SQL 即可完成分类。

语法

AI_CLASSIFY(content, labels [, options]) -- 使用工作区默认模型 AI_CLASSIFY(model, content, labels [, options]) -- 手动指定模型

参数	类型	必需	说明
`model` model	STRING	否 *	模型标识，支持 `connection:` connection: 来源或使用工作区默认模型
`content` content	STRING 或图像引用	是	待分类的文本，或 `GET_PRESIGNED_URL(...) AS image` GET_PRESIGNED_URL(...) AS image
`labels` labels	ARRAY	是	类别数组， `ARRAY('类别1', '类别2', ...)` ARRAY('类别1', '类别2', ...)
`options` options	JSON 字面量	否	可选参数（超时、并发、模型参数、输出行为等）

*模型参数为可选：当工作区已配置

cz.sql.ai.classify.default.model

cz.sql.ai.classify.default.model

时，可省略 model 参数，函数将使用该默认模型。

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

model（可选）

指定要调用的语言模型。从 2026 年 9 月起，该参数可以省略——模型通过工作区默认模型自动路由，无需在每次调用时显式传入。

省略 model 参数时调用方式最简洁：

SELECT AI_CLASSIFY('产品质量很好', ARRAY('好评', '差评'));

工作区默认模型可通过以下方式配置：

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

2026 年 9 月起新建的工作区，在创建时打开 "启用 AI Function" 开关，系统将自动配置默认模型，调用时无需传入 model 参数。对于此之前创建的工作区，需通过下方方式手动配置。

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

通过

ALTER WORKSPACE

ALTER WORKSPACE

设置工作区默认模型，对所有使用该工作区的 session 生效：

ALTER WORKSPACE <workspace_name> SET PROPERTIES ( 'cz.sql.ai.classify.default.model' = '<connection>:<model>' ); SELECT AI_CLASSIFY('苹果手机', ARRAY('电子产品', '服装', '食品'));

方式三：会话级 SET 覆盖

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

SET cz.sql.ai.classify.default.model=conn_bailian:qwen/qwen3.6-flash; SELECT AI_CLASSIFY('产品质量很好', ARRAY('好评', '差评'));

方式四：API Connection 连接对象

通过

CREATE 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_CLASSIFY('conn_bailian:qwen3.5-plus', '苹果手机', ARRAY('电子产品', '服装', '食品'));

CREATE API CONNECTION

CREATE API CONNECTION

各字段说明：

字段	说明
`TYPE` TYPE	固定为 `ai_function` ai_function
`PROVIDER` PROVIDER	模型供应商标识，如 `'bailian'` 'bailian' 、 `'openai'` 'openai' 、 `'anthropic'` 'anthropic' 等
`BASE_URL` BASE_URL	模型服务的 API 基础地址
`API_KEY` API_KEY	调用服务所需的认证密钥

快速开始

省略 model 参数（推荐）

当工作区已配置默认模型时，调用方式最简洁：

SELECT AI_CLASSIFY('产品质量很好', ARRAY('好评', '差评')) AS result; -- 返回：好评

指定模型

-- 文本分类 SELECT AI_CLASSIFY( 'conn_bailian:qwen3.5-plus', '苹果手机', ARRAY('电子产品', '服装', '食品') ); -- 返回：电子产品

使用场景

场景一：商品分类

SELECT product_name, AI_CLASSIFY('conn_bailian:qwen3.5-plus', product_desc, ARRAY('电子产品', '服装', '食品')) AS category FROM products;

product_name	category
iphone	电子产品
Dior连衣裙	服装
奥利奥饼干	食品

场景二：图像分类

SELECT relative_path, AI_CLASSIFY( 'conn_bailian:qwen3.5-plus', (GET_PRESIGNED_URL(USER VOLUME, relative_path, 36000) AS image), ARRAY('电子产品', '男装', '女装', '食品', '汽车') ) AS classification FROM (SHOW USER VOLUME DIRECTORY SUBDIRECTORY 'images/products');

场景三：新闻分类

SELECT headline, AI_CLASSIFY('conn_bailian:qwen3.5-plus', headline, ARRAY('tech', 'sports', 'finance', 'entertainment')) AS topic FROM news_articles;

场景四：客服工单路由

SELECT ticket_id, AI_CLASSIFY( 'conn_bailian:qwen3.5-plus', description, ARRAY('支付问题', '物流问题', '商品质量', '账号问题', '功能建议') ) AS department FROM support_tickets;

场景五：带 options 的批量分类

SELECT product_name, AI_CLASSIFY( 'conn_bailian:qwen3.5-plus', product_desc, ARRAY('电子产品', '服装', '食品'), JSON '{"model.params":{"enable_thinking":false},"response.timeout":"300","task.concurrency":"12"}' ) AS category FROM products;

多语言支持

AI_CLASSIFY 基于你选择的模型，原生支持 29+ 种语言的分类，包括：

语系	支持语言
CJK	中文、日语、韩语
拉丁语系	英语、法语、西班牙语、葡萄牙语、德语、意大利语
东南亚	越南语、泰语、印尼语
其他	阿拉伯语、俄语、波兰语、荷兰语、土耳其语等

同语言分类

输入和标签使用相同语言：

-- 日语 SELECT AI_CLASSIFY('conn_bailian:qwen3.5-plus', '東京オリンピックで日本は金メダル27個を獲得しました', ARRAY('テクノロジー', 'スポーツ', '金融', 'エンタメ') ); -- 返回：スポーツ -- 阿拉伯语 SELECT AI_CLASSIFY('conn_bailian:qwen3.5-plus', 'أعلن البنك المركزي عن رفع أسعار الفائدة', ARRAY('تقنية', 'مالية', 'رياضة', 'ترفيه') ); -- 返回：مالية

跨语言分类

输入和标签可以是不同语言：

-- 中文输入 + 英文标签 SELECT AI_CLASSIFY('conn_bailian:qwen3.5-plus', '特斯拉发布了全新的自动驾驶系统', ARRAY('technology', 'sports', 'finance', 'entertainment') ); -- 返回：technology -- 英文输入 + 中文标签 SELECT AI_CLASSIFY('conn_bailian:qwen3.5-plus', 'Bitcoin surged past 150000 as institutional investors poured billions', ARRAY('科技', '体育', '金融', '娱乐') ); -- 返回：金融

Options 参数

JSON '{"model.params":{"enable_thinking":false},"response.timeout":"300","task.concurrency":"12"}'

参数	类型	说明
`output.behavior` output.behavior	STRING	输出格式，见下方对比表
`model.params.enable_thinking` model.params.enable_thinking	boolean	设为 `false` false 关闭思考过程，加快响应（批量分类推荐）
`model.params.temperature` model.params.temperature	FLOAT	输出随机性，范围 [0, 2]，越低越确定
`model.params.top_p` model.params.top_p	FLOAT	核采样概率，范围 (0, 1]
`response.timeout` response.timeout	string（秒）	单次调用超时时间
`task.concurrency` task.concurrency	string（整数）	批量处理并发度
`classify.pack_size` classify.pack_size	string（整数）	批量打包条数，将多条输入合并为一次模型调用以减少 API 调用次数
`classify.pack_max_tokens` classify.pack_max_tokens	string（整数）	批量打包最大 token 数，控制单次模型调用的输入长度上限

output.behavior 说明

output.behavior

output.behavior

控制分类结果的返回格式和行为：

模式	成功输出	错误输出	适用场景
`formatted_json` formatted_json	`{"value":"类别名称"}` {"value":"类别名称"}	`{"value":"","error_message":"..."}` {"value":"","error_message":"..."}	生产环境默认，结构化输出便于下游解析
`raw_string` raw_string	原始字符串（类别名称）	NULL	兼容旧行为，应急使用
`fail_on_error` fail_on_error	原始字符串（类别名称）	抛异常，整个 job 失败	严格模式，不容忍单行错误

output.behavior

output.behavior

输入兼容性（大小写不敏感，

、

等价）：

输入值解析结果

输入值	解析结果
`formatted_json` formatted_json / `formatted.json` formatted.json / `json` json	FORMATTED_JSON
`raw_string` raw_string / `raw.string` raw.string / `raw` raw	RAW_STRING
`fail_on_error` fail_on_error / `fail.on.error` fail.on.error / `fail-on-error` fail-on-error / `fail` fail	FAIL_ON_ERROR

formatted_json

formatted_json

formatted.json

formatted.json

json

json

FORMATTED_JSON

raw_string

raw_string

raw.string

raw.string

raw

raw

RAW_STRING

fail_on_error

fail_on_error

fail.on.error

fail.on.error

fail-on-error

fail-on-error

fail

fail

FAIL_ON_ERROR

NULL 和空输入的行为

输入	返回值	说明
content 为 NULL	NULL	透传 NULL
content 为空字符串	`""` ""	返回空字符串（非 NULL）
正常文本	匹配的类别名称	纯字符串

⚠️ 注意：空字符串返回

""

而非 NULL，如需统一处理建议在查询中加

NULLIF(result, '')

NULLIF(result, '')

。

最佳实践

类别名称要清晰 — 使用描述性的类别名（如"电子产品"而非"cat_1"），模型通过语义理解类别含义。
类别数量适中 — 建议 2~10 个类别效果最佳。类别过多可能降低准确率。
关闭 thinking 加速 — 批量分类时建议设置
```
enable_thinking:false
```
enable_thinking:false
，可显著减少响应时间。
先过滤再分类 — 对大表使用时，建议先用
```
WHERE
```
WHERE
缩小范围，避免不必要的模型调用。
利用跨语言能力 — 标签可以统一用英文，即使输入是其他语言也能正确分类，方便下游统一处理。
图像分类 — 通过
```
GET_PRESIGNED_URL(USER VOLUME, path, expiry) AS image
```
GET_PRESIGNED_URL(USER VOLUME, path, expiry) AS image
传入图片，模型会根据图片内容进行分类。
空字符串防御 — 对可能含空字符串的列，建议加
```
WHERE content IS NOT NULL AND content != ''
```
WHERE content IS NOT NULL AND content != ''
过滤后再分类。

限制说明

限制项	说明
模型参数	可选，省略时将使用工作区默认模型（需先配置 `cz.sql.ai.classify.default.model` cz.sql.ai.classify.default.model ）
标签最少数量	1 个（建议 ≥ 2 个，单标签时直接返回该标签）
标签最多数量	建议 ≤ 20 个，过多会降低准确率
返回值	单标签（返回一个类别名称字符串）
图像输入	需使用 `GET_PRESIGNED_URL(...) AS image` GET_PRESIGNED_URL(...) AS image 语法
配额	受 AI Gateway 租户 token 配额限制

错误处理

错误场景	错误信息	解决方法
Endpoint 不存在	`CZLH-67000 No available endpoints found` CZLH-67000 No available endpoints found	检查 endpoint 名称是否正确
配额超限	`Tenant quota exceeded` Tenant quota exceeded	联系管理员提升配额
图片不存在	`Failed to fetch image from URL` Failed to fetch image from URL	检查 Volume 文件路径

联系我们