AI_TRANSCRIBE

概述

AI_TRANSCRIBE

AI_TRANSCRIBE

是云器 Lakehouse 提供的 AI 语音转文字函数，可将音频文件的内容转录为纯文本。支持中文、英文等多语言，可与

AI_CLASSIFY

AI_CLASSIFY

、

AI_EXTRACT

AI_EXTRACT

等函数组合使用，实现「音频入湖 → 转录 → AI 分析」的完整流水线。

云器将 AI 计算下沉至存储层与执行引擎，数据在平台内部即可完成智能处理，无需流转至外部环境，在保障数据安全的同时大幅降低任务延迟。

语法

AI_TRANSCRIBE

AI_TRANSCRIBE

支持两种调用形式：

-- 使用工作区默认模型（推荐，需已配置默认 ASR 模型） AI_TRANSCRIBE(<audio_url> [, json '{}']) -- 或手动指定连接 AI_TRANSCRIBE('<connection>:<model>', <audio_url> [, json '{}'])

参数说明

model（可选）

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

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

SELECT AI_TRANSCRIBE(GET_PRESIGNED_URL(USER VOLUME, 'audios/meeting.wav', 36000)) AS transcription;

注意：音频转录需要 ASR 模型支持，若未通过下方方式配置默认 ASR 模型，则仍需显式传入 model 参数。

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

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

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

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

通过

ALTER WORKSPACE

ALTER WORKSPACE

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

ALTER WORKSPACE <workspace_name> SET PROPERTIES ( 'cz.sql.ai.transcribe.default.model' = '<connection>:<model>' ); SELECT AI_TRANSCRIBE(GET_PRESIGNED_URL(USER VOLUME, 'audios/meeting.wav', 36000)) AS transcription;

方式三：会话级 SET 覆盖

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

SET cz.sql.ai.transcribe.default.model=conn_asr:qwen3-asr-flash; SELECT AI_TRANSCRIBE(GET_PRESIGNED_URL(USER VOLUME, 'audios/meeting.wav', 36000)) AS transcription;

方式四：API Connection 连接对象

通过

CREATE API CONNECTION

CREATE API CONNECTION

创建连接对象后，在调用时显式传入：

CREATE API CONNECTION conn_asr TYPE ai_function PROVIDER = 'bailian' BASE_URL = 'https://dashscope.aliyuncs.com/api/v1' API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx'; SELECT AI_TRANSCRIBE( 'conn_asr:qwen3-asr-flash', GET_PRESIGNED_URL(USER VOLUME, 'audios/meeting.wav', 36000) ) AS transcription;

CREATE API CONNECTION

CREATE API CONNECTION

各字段说明：

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

audio_url（必需）

音频文件的访问地址，类型为 STRING。必须是以

http://

http://

或

https://

https://

开头的 URL。通常通过

GET_PRESIGNED_URL()

GET_PRESIGNED_URL()

函数从 Volume 中获取。

GET_PRESIGNED_URL(USER VOLUME, 'audios/meeting.wav', 36000)

options（可选）

使用

json '{}'

json '{}'

字面量语法传入，控制输出格式和执行行为：

输出格式控制

参数键类型默认值说明

参数键	类型	默认值	说明
`output.behavior` output.behavior	STRING	`formatted_json` formatted_json	输出格式： `formatted_json` formatted_json / `raw_string` raw_string / `fail_on_error` fail_on_error

output.behavior

output.behavior

STRING

formatted_json

formatted_json

输出格式：

formatted_json

formatted_json

raw_string

raw_string

fail_on_error

fail_on_error

三种输出模式对比：

模式	成功输出	错误输出	适用场景
`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

运行时参数

参数键	类型	说明
`response.timeout` response.timeout	STRING（秒）	HTTP 请求超时时间，长音频建议设置较大值，如 `"120"` "120"

JSON'{"response.timeout":"120"}'

返回值

STRING 类型，为音频内容的纯文本转录结果，不含时间戳或说话人信息。

错误行为

输入	行为
`audio_url` audio_url 为 `NULL` NULL	返回 `NULL` NULL ，不报错
`audio_url` audio_url 为空字符串 `''` ''	报错： `AI_TRANSCRIBE: audio_url must start with http:// or https://` AI_TRANSCRIBE: audio_url must start with http:// or https://
`audio_url` audio_url 不以 `http://` http:// 或 `https://` https:// 开头	报错： `AI_TRANSCRIBE: audio_url must start with http:// or https://` AI_TRANSCRIBE: audio_url must start with http:// or https://
连接对象或模型错误	报错： `API request failed` API request failed
文件下载失败（如 URL 已过期）	报错： `Download multimodal file timed out` Download multimodal file timed out 或 HTTP 错误

使用说明

支持的音频格式：WAV、MP3、FLAC、M4A。推荐使用 16kHz 单声道 WAV 格式，ASR 模型内部使用 16kHz 采样率，使用匹配格式可避免重采样损失，获得最佳识别效果。
使用 presigned URL 并设置足够有效期：建议设置 36000 秒（10 小时），避免批量处理中 URL 过期导致下载失败。
返回纯文本：
```
AI_TRANSCRIBE
```
AI_TRANSCRIBE
返回纯文本字符串，不含时间戳或说话人信息，可直接作为
```
AI_CLASSIFY
```
AI_CLASSIFY
、
```
AI_EXTRACT
```
AI_EXTRACT
、
```
AI_SIMILARITY
```
AI_SIMILARITY
等函数的输入。
批量处理用 REGEXP 过滤：使用
```
REGEXP = '.*\.wav'
```
REGEXP = '.*\.wav'
确保只处理音频文件，避免对非音频文件发起转录请求。
先确认文件存在：批量转录前先用
```
SHOW USER VOLUME DIRECTORY
```
SHOW USER VOLUME DIRECTORY
确认文件列表，避免因文件不存在导致查询失败。
静音文件：静音或近静音文件可能产生少量幻觉文本，建议在下游处理时做长度过滤。

示例

使用默认模型转录（需已配置默认 ASR 模型）

若已通过

ALTER WORKSPACE

ALTER WORKSPACE

或

SET

SET

配置了默认 ASR 模型，可省略 model 参数：

SELECT AI_TRANSCRIBE( GET_PRESIGNED_URL(USER VOLUME, 'audios/meeting.wav', 36000) ) AS transcription;

基础用法

-- 单条音频转录 SELECT AI_TRANSCRIBE( 'conn_asr:qwen3-asr-flash', GET_PRESIGNED_URL(USER VOLUME, 'audios/meeting.wav', 36000) ) AS transcription;

批量转录 Volume 中的音频文件

SELECT relative_path, AI_TRANSCRIBE( 'conn_asr:qwen3-asr-flash', GET_PRESIGNED_URL(USER VOLUME, relative_path, 36000) ) AS transcription FROM (SHOW USER VOLUME DIRECTORY SUBDIRECTORY 'audios' REGEXP = '.*\.wav');

转录后分类（客服录音分析）

SELECT relative_path, AI_CLASSIFY( 'conn_bailian:qwen3.5-plus', AI_TRANSCRIBE( 'conn_asr:qwen3-asr-flash', GET_PRESIGNED_URL(USER VOLUME, relative_path, 36000) ), ARRAY('投诉', '咨询', '表扬', '建议') ) AS category FROM (SHOW USER VOLUME DIRECTORY SUBDIRECTORY 'audios/calls' REGEXP = '.*\.wav');

转录后提取关键信息

SELECT AI_EXTRACT( 'conn_bailian:qwen3.5-plus', AI_TRANSCRIBE( 'conn_asr:qwen3-asr-flash', GET_PRESIGNED_URL(USER VOLUME, 'audios/interview.wav', 36000) ), JSON'{"speaker":"说话人", "topic":"讨论主题", "conclusion":"结论"}' ) AS info;

带 options 的批量转录

SELECT relative_path, AI_TRANSCRIBE( 'conn_asr:qwen3-asr-flash', GET_PRESIGNED_URL(USER VOLUME, relative_path, 36000), JSON'{"response.timeout":"120"}' ) AS transcription FROM (SHOW USER VOLUME DIRECTORY SUBDIRECTORY 'audios' REGEXP = '.*\.wav') LIMIT 20;

使用 raw_string 输出格式

SELECT AI_TRANSCRIBE( 'conn_asr:qwen3-asr-flash', GET_PRESIGNED_URL(USER VOLUME, 'audios/meeting.wav', 36000), json '{"output.behavior":"raw_string"}' ) AS transcription;

限制说明

model 参数可选：从 2026 年 9 月起，model 参数可以省略，需通过
```
ALTER WORKSPACE
```
ALTER WORKSPACE
或
```
SET
```
SET
配置
```
cz.sql.ai.transcribe.default.model
```
cz.sql.ai.transcribe.default.model
；若未配置默认 ASR 模型且未指定 model，会报错
```
AI function must have at least two arguments
```
AI function must have at least two arguments
。
audio_url 必须是 HTTP/HTTPS URL：仅支持通过 URL 引用音频文件，不支持直接传入文件内容或本地路径。通常通过
```
GET_PRESIGNED_URL()
```
GET_PRESIGNED_URL()
获取。
支持格式有限：仅支持 WAV、MP3、FLAC、M4A 格式，不支持 OGG、WEBM 等格式。
返回纯文本：不含时间戳、说话人分离（diarization）或置信度信息。
静音文件：静音或近静音文件可能产生少量幻觉文本。
配额限制：受 AI Gateway 租户 token 配额限制，大批量转录前建议确认配额余量。

联系我们