概述
AI_EXTRACT
AI_EXTRACT
是云器 Lakehouse 提供的 AI 信息抽取函数，可从文本或图像中按指定字段提取结构化 JSON 数据。无需编写 prompt，只需通过
schema
schema
定义要提取的字段，即可在 SQL 中一行完成信息抽取。
云器将 AI 计算下沉至存储层与执行引擎，
AI_EXTRACT
AI_EXTRACT
可直接在 SQL 查询中对表中每一行调用大模型，无需将数据导出到外部系统，兼顾数据安全与处理效率。
语法
AI_EXTRACT(content, schema [, options]) -- 使用工作区默认模型
AI_EXTRACT(model, content, schema [, options]) -- 手动指定模型
参数说明
必需参数
| 参数 | 类型 | 说明 |
|---|
content
content | STRING 或图像引用 | 待抽取的文本内容，或通过 GET_PRESIGNED_URL()
GET_PRESIGNED_URL() 引用的图像。 |
schema
schema | JSON 字面量 | 定义要提取的字段，格式为 JSON'{"key":"字段描述", ...}'
JSON'{"key":"字段描述", ...}' 。每个 key 是返回 JSON 中的字段名，value 是对该字段的自然语言描述。 |
可选参数
| 参数 | 类型 | 说明 |
|---|
model
model | STRING | 模型标识，指定调用的 AI 模型。通过 API Connection 连接对象指定，格式为 <连接名称>:<模型名称>
<连接名称>:<模型名称> 。当工作区已配置 cz.sql.ai.extract.default.model
cz.sql.ai.extract.default.model 时可省略。 |
options
options | JSON 字面量 | 控制超时、并发、输出行为、模型参数等，格式见下方 options 说明。 |
model（可选）
指定要调用的语言模型。从 2026 年 9 月起，该参数可以省略——模型通过工作区默认模型自动路由，无需在每次调用时显式传入。
省略 model 参数时调用方式最简洁：
SELECT AI_EXTRACT('张三，28岁', JSON'{"name":"姓名","age":"年龄"}');
工作区默认模型可通过以下方式配置：
方式一：创建新工作区时开启开关（推荐）
2026 年 9 月起新建的工作区，在创建时打开 "启用 AI Function" 开关，系统将自动配置默认模型，调用时无需传入 model 参数。对于此之前创建的工作区，需通过下方方式手动配置。
方式二：工作区级别 ALTER WORKSPACE 配置
通过
ALTER WORKSPACE
ALTER WORKSPACE
设置工作区默认模型，对所有使用该工作区的 session 生效：
ALTER WORKSPACE <workspace_name> SET PROPERTIES (
'cz.sql.ai.extract.default.model' = '<connection>:<model>'
);
SELECT AI_EXTRACT('张三，28岁', JSON'{"name":"姓名","age":"年龄"}');
方式三：会话级 SET 覆盖
在当前会话中临时指定默认模型，优先级高于工作区属性，仅当前 session 生效：
SET cz.sql.ai.extract.default.model=conn_bailian:qwen3.5-plus;
SELECT AI_EXTRACT('张三，28岁', JSON'{"name":"姓名","age":"年龄"}');
方式四：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_EXTRACT('conn_bailian:qwen3.5-plus', '张三，28岁', JSON'{"name":"姓名","age":"年龄"}');
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 | 调用服务所需的认证密钥 |
options 参数说明
| 选项 | 类型 | 默认值 | 说明 |
|---|
output.behavior
output.behavior | STRING | formatted_json
formatted_json | 输出格式，见下方对比表 |
response.timeout
response.timeout | STRING（秒） | 系统默认 | HTTP 请求超时时间 |
task.concurrency
task.concurrency | STRING | 系统默认 | 批量处理时的并发度 |
model.params
model.params | JSON 对象 | — | 透传给底层模型的参数，如 {"temperature":0.7,"top_p":0.9,"enable_thinking":false}
{"temperature":0.7,"top_p":0.9,"enable_thinking":false} |
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 |
示例：
-- 使用 raw_string 获取模型原始回答
JSON'{"output.behavior":"raw_string"}'
-- 要求字段必须全部提取，失败则报错
JSON'{"output.behavior":"fail_on_error"}'
-- 综合示例：设置超时、并发和模型参数
JSON'{"response.timeout":"300", "task.concurrency":"12", "model.params":{"enable_thinking":false}}'
返回值
返回 STRING 类型，内容为 JSON 格式字符串，包含
schema
schema
中定义的所有 key 及其抽取结果。所有字段值均为字符串类型。
示例：
{"age": "28", "name": "张三", "phone": "13800138000"}
错误行为
| 输入情况 | 返回值 |
|---|
content
content 为 NULL | NULL |
content
content 为空字符串 ''
'' | NULL |
content
content 为纯空白字符（如 ' '
' ' ） | 发送给模型，各字段返回空字符串，如 {"name": ""}
{"name": ""} |
| 文本中找不到对应字段的信息 | 该字段值为空字符串 ""
"" ，如 {"name": "", "phone": ""}
{"name": "", "phone": ""} |
| 请求超时 | 报错：Read timed out
Read timed out |
| 图片文件不存在 | 报错：Failed to fetch image from URL...HTTP status: 404
Failed to fetch image from URL...HTTP status: 404 |
使用说明
schema 定义
schema 的 value 支持简单标签和问句描述两种写法，效果等价，问句描述在字段含义模糊时可提升准确率：
-- 简单标签
JSON'{"name":"姓名", "age":"年龄", "phone":"电话"}'
-- 问句描述
JSON'{"name":"员工姓名是什么？", "age":"员工年龄是多大？", "phone":"员工的电话号码是多少？"}'
schema 的 key 和 value 均支持中文、英文、日文等多语言。value 必须是字符串，不支持嵌套对象（如
{"type":"number"}
{"type":"number"}
）。建议字段数控制在 10 个以内，最多支持约 20 个字段。
超时设置建议
| 场景 | 推荐 timeout |
|---|
| 纯文本抽取 | ≥ 30 秒 |
| 单张图像抽取 | ≥ 60 秒 |
| 批量图像抽取 | ≥ 300 秒 |
批量处理
处理大量数据时，通过
task.concurrency
task.concurrency
控制并发度（建议 5~12），平衡速度与稳定性。对大表建议先用
WHERE
WHERE
过滤出需要处理的行，避免不必要的模型调用。
图像处理
图像场景建议设置
"model.params":{"enable_thinking":false}
"model.params":{"enable_thinking":false}
以减少响应时间。批量图像处理前，先用
SHOW USER VOLUME DIRECTORY
SHOW USER VOLUME DIRECTORY
确认文件列表，避免因文件不存在导致查询失败。
结合 JSON 函数解析结果
返回值为 JSON 字符串，可配合
json_extract_string
json_extract_string
等函数进一步解析：
WITH extracted AS (
SELECT
id,
AI_EXTRACT(
'conn_bailian:qwen3.5-plus',
content,
JSON'{"name":"姓名", "phone":"电话"}'
) AS result
FROM my_table
)
SELECT
id,
json_extract_string(result, '$.name') AS name,
json_extract_string(result, '$.phone') AS phone
FROM extracted;
示例
省略 model 参数（推荐）
当工作区已配置默认模型时，调用方式最简洁：
SELECT AI_EXTRACT('张三，28岁', JSON'{"name":"姓名","age":"年龄"}') AS result;
-- 返回：{"age": "28", "name": "张三"}
示例一：使用默认模型（省略 model 参数）
当工作区已配置
cz.sql.ai.extract.default.model
cz.sql.ai.extract.default.model
时，可省略
model
model
参数：
SELECT AI_EXTRACT(
'张三，28岁',
JSON'{"name":"姓名","age":"年龄"}'
) AS result;
返回：
{"age": "28", "name": "张三"}
示例二：从文本中抽取联系人信息
SELECT AI_EXTRACT(
'conn_bailian:qwen3.5-plus',
'张三，28岁，电话13800138000',
JSON'{"name":"姓名", "age":"年龄", "phone":"电话"}'
) AS result;
返回：
{"age": "28", "name": "张三", "phone": "13800138000"}
示例三：批量抽取客户记录
SELECT
id,
AI_EXTRACT(
'conn_bailian:qwen3.5-plus',
content,
JSON'{"name":"客户姓名", "phone":"联系电话", "email":"邮箱地址", "company":"公司名称"}'
) AS extracted
FROM customer_records
WHERE content IS NOT NULL;
示例四：抽取订单信息
SELECT AI_EXTRACT(
'conn_bailian:qwen3.5-plus',
'订单信息：客户张三于2024年3月15日下单，购买了iPhone 15 Pro Max 256GB，单价8999元，数量2台，总计17998元',
JSON'{"customer":"客户姓名", "order_date":"下单日期", "product":"产品名称", "unit_price":"单价", "quantity":"数量", "total":"总金额"}'
) AS result;
返回：
{
"customer": "张三",
"order_date": "2024年3月15日",
"product": "iPhone 15 Pro Max 256GB",
"quantity": "2台",
"total": "17998元",
"unit_price": "8999元"
}
示例五：批量图像商品信息抽取
SELECT AI_EXTRACT(
'conn_bailian:qwen3.5-plus',
(GET_PRESIGNED_URL(USER VOLUME, relative_path) AS image),
JSON'{"product_name":"产品名称", "brand":"品牌", "category":"类别", "price":"价格", "spec":"规格"}',
JSON'{"model.params":{"enable_thinking":false}, "response.timeout":"300", "task.concurrency":"12"}'
) AS info
FROM (SHOW USER VOLUME DIRECTORY SUBDIRECTORY 'images/products');
示例六：使用 API Connection
SELECT AI_EXTRACT(
'conn_bailian:qwen3.5-plus',
'李四，35岁，邮箱 lisi@example.com',
JSON'{"name":"姓名", "age":"年龄", "email":"邮箱"}'
) AS result;
限制说明
| 限制项 | 说明 |
|---|
| schema value 类型 | 仅支持字符串描述，不支持 JSON Schema 类型定义（如 {"type":"number"}
{"type":"number"} ） |
| 返回值类型 | 所有字段值均为字符串类型，不会自动转换为数字或布尔值 |
| 字段数量 | 建议不超过 10 个字段，最多支持约 20 个字段 |
| 错误隔离 | 批量处理中如有单行失败（如图片 404），整个查询会失败 |
| 模型依赖 | 需要预先创建的 API Connection |
| 结果确定性 | LLM 输出具有非确定性，同一输入多次执行结果可能略有差异 |
