AI_TRANSCRIBE

概述

AI_TRANSCRIBE

AI_TRANSCRIBE

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

AI_CLASSIFY

AI_CLASSIFY

、

AI_EXTRACT

AI_EXTRACT

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

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

语法

AI_TRANSCRIBE( <model>, <audio_url> [, <options>] )

参数说明

必需参数

model

model

指定用于语音转文字的 ASR 模型，支持两种来源：

来源一：API Gateway Endpoint（推荐）

平台管理员在 API Gateway 中预先配置模型服务，普通用户通过

endpoint:

endpoint:

前缀引用，无需关心底层连接细节。

'endpoint:<endpoint名称>' -- 示例 'endpoint:qwen3-asr-flash' 'endpoint:paraformer-v2'

来源二：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:paraformer-v2', GET_PRESIGNED_URL(USER VOLUME, 'audios/meeting.wav', 36000));

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

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

options

JSON 字面量，用于控制超时等行为。

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

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://
Endpoint 不存在	报错： `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
确认文件列表，避免因文件不存在导致查询失败。
静音文件：静音或近静音文件可能产生少量幻觉文本，建议在下游处理时做长度过滤。

示例

基础用法

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

批量转录 Volume 中的音频文件

SELECT relative_path, AI_TRANSCRIBE( 'endpoint: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( 'endpoint:qwen3.5-plus', AI_TRANSCRIBE( 'endpoint: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( 'endpoint:qwen3.5-plus', AI_TRANSCRIBE( 'endpoint:qwen3-asr-flash', GET_PRESIGNED_URL(USER VOLUME, 'audios/interview.wav', 36000) ), JSON'{"speaker":"说话人", "topic":"讨论主题", "conclusion":"结论"}' ) AS info;

带 options 的批量转录

SELECT relative_path, AI_TRANSCRIBE( 'endpoint: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;

使用 API Connection

SELECT AI_TRANSCRIBE( 'conn_asr:paraformer-v2', GET_PRESIGNED_URL(USER VOLUME, 'audios/call.wav', 36000) ) AS transcription;

限制说明

model 参数必填：省略 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 配额限制，大批量转录前建议确认配额余量。

联系我们