使用Android SDK进行录音文件识别-大模型服务平台百炼-阿里云_大模型服务平台百炼(Model Studio) - 大模型服务平台百炼

本文档提供了Qwen-Audio-ASR-Filetrans非实时语音识别Android SDK的详细使用指南，帮助您将语音转换为文本。

关于支持的音频格式、文件大小限制、时长限制等输入要求，请参见音频规格。

快速开始

获取API Key：获取API Key，为安全起见，推荐将API Key配置到环境变量。
下载SDK并运行示例代码：
- 下载最新SDK整合包。
- 解压 ZIP 包。在 app/libs 目录中获取 AAR 格式 SDK，并添加到项目依赖。
  需要 Android CPP 接入时，使用 ZIP 包内的 android_libs 与 android_include 获取动态库和头文件。
- 用 Android Studio 打开工程。示例代码位于DashFunAsrFileTranscriberActivity.java，替换 API Key 后体验功能。

调用步骤

同步模式

初始化 SDK
按业务需求配置相关参数
当 async_request 设为 false 时，调用 startFileTranscriber 发送非实时语音识别请求，并等待结果返回。
在onFileTransEventCallback接口中监听EVENT_FILE_TRANS_RESULT 事件，获取最终识别结果
调用 release 释放 SDK 资源

异步模式

初始化 SDK
按业务需求配置相关参数
当 async_request 设为 true 时，调用 startFileTranscriber 发送非实时语音识别请求。
调用 queryFileTranscriber 主动查询识别进度/结果
在onFileTransEventCallback接口中监听EVENT_FILE_TRANS_QUERY_RESULT事件，获取当前查询结果
在onFileTransEventCallback接口中监听 EVENT_FILE_TRANS_RESULT 事件，获取最终识别结果
调用 release 释放 SDK 资源

请求参数

连接与控制参数

通过在initialize接口的parameters参数中传入一个JSON字符串来配置。

参数示例

以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

参数说明

参数	类型	是否必须	说明
`url`	`String`	是	服务地址： `wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription` 华北2（北京）：`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription` 新加坡：`wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription` 调用时，请将 `{WorkspaceId}` 替换为真实的 Workspace ID。
`apikey`	`String`	是	API Key。
`service_mode`	`String`	是	运行模式。非实时语音识别固定为 `"1"`。
`device_id`	`String`	是	用于标识终端用户的唯一字符串，可设为应用内用户ID或客户端生成的设备唯一标识符。此ID主要用于日志追踪和问题排查。
`debug_path`	`String`	否	日志文件的存储路径。此参数仅在调用`initialize`接口时将`save_log`设为true时生效。此时必须设置日志文件路径，否则将报错。本地最多保留两个日志文件。
`max_log_file_size`	`int`	否	设定日志文件的最大字节数。此参数仅在调用`initialize`接口时将`save_log`设为true时生效。默认值：104857600（100 * 1024 * 1024 字节, 即 100MiB）。
`log_track_level`	`int`	否	控制通过日志回调（`onFileTransLogTrackCallback`）对外发送的日志内容的过滤级别。默认值：2。取值范围： 0：LOG_LEVEL_VERBOSE 1：LOG_LEVEL_DEBUG 2：LOG_LEVEL_INFO 3：LOG_LEVEL_WARNING 4：LOG_LEVEL_ERROR 5：LOG_LEVEL_NONE（表示关闭此功能）注意：`log_track_level`与`level`（通过`initialize`接口设置）共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于`log_track_level`和`level`的值，才会被回调。例如，`log_track_level`设为2 (INFO)，`level`设为3 (WARNING)，则只有WARNING及以上级别（数值>=3）的日志才会被回调。

语音识别效果参数

通过startFileTranscriber接口配置所有语音识别效果参数。

参数示例

以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
    "apikey": "st-****",
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}

参数说明

参数	类型	是否必须	说明
`file_urls`	`array[string]`	是	音视频文件转写的URL列表，支持HTTP / HTTPS协议，单次请求仅支持1个URL。关于支持的音频格式、文件大小限制、时长限制等输入要求，请参见音频规格。若录音文件存储在阿里云OSS，使用RESTful API方式支持使用以`oss://`为前缀的临时 URL，使用SDK方式不支持使用以 oss://为前缀的临时 URL。重要临时 URL 有效期48小时，过期后无法使用，请勿用于生产环境。文件上传凭证接口限流为 100 QPS 且不支持扩容，请勿用于生产环境、高并发及压测场景。生产环境建议使用阿里云OSS 等稳定存储，确保文件长期可用并规避限流问题。录音文件URL设置成OSS临时公网访问不通该如何处理？请求头中将`X-DashScope-OssResourceResolve`设为`enable`（不推荐该方式）。 SDK不支持对请求头进行配置。
`async_request`	`boolean`	否	语音识别是否为异步请求。默认值：`false`。取值范围： true：异步请求 false：同步请求
`apikey`	`string`	否	如果连接与控制参数的`apikey`使用的是临时API Key，可在此处进行更新，以免超时失效。
`nls_config`	`object`	是	语音识别核心配置对象，包含模型选择、识别效果控制等关键参数。
`nls_config.model`	`string`	是	模型名称。
`nls_config.special_word_filter`	`object`	否	指定在语音识别过程中需要处理的敏感词，并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。
`nls_config.channel_id`	`array[integer]`	否	指定在多音轨音频文件中需要识别的音轨索引，索引从 0 开始。例如，[0] 表示识别第一个音轨，[0, 1] 表示同时识别第一和第二个音轨。如果省略此参数，则默认处理第一个音轨。重要指定的每一个音轨都将独立计费。例如，为单个文件请求 [0, 1] 会产生两笔独立的费用。默认值：[0]。
`nls_config.diarization_enabled`	`boolean`	否	是否启用说话人分离，默认关闭。仅适用于单声道音频，多声道音频不支持说话人分离。启用该功能后，识别结果中将显示`speaker_id`字段，用于区分不同说话人。说明如果启用说话人分离功能，建议音频时长不超过2小时，否则可能导致识别失败或超时。默认值：false。有关`speaker_id`的示例，请参见识别结果说明。
`nls_config.speaker_count`	`integer`	否	重要仅在开启说话人分离功能（`diarization_enabled`设置为`true`）时生效。说话人数量参考值。取值范围为2至100的整数（包含2和100）。默认自动判断说话人数量，如果配置此项，只能辅助算法尽量输出指定人数，无法保证一定会输出此人数。无默认值。
`nls_config.vocabulary_id`	`string`	否	预编译热词列表 ID。需预先调用创建热词列表接口生成，识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。
`nls_config.input_context`	`array`	否	消息列表，包含用于提升识别效果的可选对话上下文。重要上下文功能用于提升专有词汇的识别准确率，使用方法请参见上下文增强。上下文消息（`input_text` 和 `text` 类型）各最多 5 条，超出时保留最近的 5 条。每轮上下文文本总长度（`user` 和 `assistant` 的 `text` 字段长度之和）不超过 400 个字符，每个字符计为 1，超出部分从末尾截断。重要携带上下文时，`messages` 中的消息必须按对话轮次排列，每轮中 `user`（`input_text` 类型）必须在对应的 `assistant`（`text` 类型）之前；包含 `input_audio` 的 `user` 消息必须放在 `messages` 数组的最后。 `[ { "role": "user", "content": [ { "type": "input_text", "text": "你好啊，我是通义千问，有什么可以帮助你的？" } ] } ]`
`nls_config.instant_vocabulary`	`object`	否	即时热词，以键值对形式传入：键为热词文本（`string`），值为热词权重（`integer`），无需预先创建热词列表。适用于临时性、会话级别的热词优化。权重取值范围为 1 至 5 或 50。取 1 至 5 时，值越大，模型越倾向于输出该词；取 50 时为超级热词，召回率大幅提升，但超级热词最多不超过 50 个。与预编译热词同时配置时，系统会合并两类热词；合并后超过 2000 个时，随机选择 2000 个使用。使用方法请参见即时热词。 `{ "张三": 5, "李四": 5 }`
`nls_config.language_hints`	`array[string]`	否	设置待识别语言代码。如果无法提前确定语种，可不设置，模型会自动识别语种。最多支持设置 4 个值，超出时仅前 4 个生效。点击查看支持的语言代码 zh: 中文 en: 英文 ja: 日语 ko：韩语 vi：越南语 th：泰语 id：印尼语 ms：马来语 tl：菲律宾语 hi：印地语 ar：阿拉伯语 fr：法语 de：德语 es：西班牙语 pt：葡萄牙语 ru：俄语 it：意大利语 nl：荷兰语 sv：瑞典语 da：丹麦语 fi：芬兰语 no：挪威语 el：希腊语 pl：波兰语 cs：捷克语 hu：匈牙利语 ro：罗马尼亚语 bg：保加利亚语 hr：克罗地亚语 sk：斯洛伐克语

关键接口

NativeNui

initialize

初始化语音识别SDK实例。SDK为单例模式，在调用release前禁止重复初始化。

此接口会引起阻塞，应在非UI线程调用。

方法签名

public synchronized int initialize(final INativeFileTransCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)

参数说明

参数	类型	说明
`callback`	`INativeFileTransCallback`	事件和数据回调接口的实现。
`parameters`	`String`	JSON字符串，包含鉴权、连接和调试参数。参见连接与控制参数。
`level`	`Constants.LogLevel`	控制SDK自身日志的打印级别。
`save_log`	`boolean`	是否保存本地日志。若为`true`，须在连接与控制参数中通过`debug_path`指定路径，并可通过`max_log_file_size`设置文件大小。

setParams

此接口用于独立设置或更新 nls_config 参数。如果所有参数都在startFileTranscriber中一次性提供，则无需调用此方法。

方法签名

public synchronized int setParams(String params);

参数说明

参数类型说明

参数	类型	说明
`params`	`String`	语音识别效果参数中的`nls_config`参数，`nls_config`之外的参数不支持通过该方法进行设置。示例： `{ "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }`

params

String

语音识别效果参数中的nls_config参数，nls_config之外的参数不支持通过该方法进行设置。

示例：

{
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}

startFileTranscriber

开始识别。

方法签名

public synchronized int startFileTranscriber(String params, byte[] task_id)

参数说明

参数类型说明

参数	类型	说明
`params`	`String`	语音识别效果参数。示例： `{ "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }`
`task_id`	`byte[]`	任务ID，SDK内部生成随机字符串，在此接口调用成功后可获得task_id。

params

String

语音识别效果参数。

示例：

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}

task_id

byte[]

任务ID，SDK内部生成随机字符串，在此接口调用成功后可获得task_id。

queryFileTranscriber

此接口用于主动查询一个异步任务的当前状态和结果。调用成功后，结果将通过onFileTransEventCallback回调中的 EVENT_FILE_TRANS_QUERY_RESULT 事件返回。

说明此处传入的 task_id 从 EVENT_FILE_TRANS_UPLOADED 事件中获取。

方法签名

public synchronized int queryFileTranscriber(String task_id)

参数说明

参数	类型	说明
`task_id`	`String`	待查询的任务 ID，从 `EVENT_FILE_TRANS_UPLOADED` 事件中获取。

cancelFileTranscriber

立即取消当前任务。

方法签名

public synchronized int cancelFileTranscriber(String task_id)

参数说明

参数	类型	说明
`task_id`	`String`	待取消的任务 ID，从 `EVENT_FILE_TRANS_UPLOADED` 事件中获取。

release

释放SDK所有内部资源。此方法调用后，SDK实例将变为不可用状态，如需再次使用，必须重新调用initialize进行初始化。

方法签名

public synchronized int release();

GetVersion

获得当前SDK版本信息。

方法签名

public synchronized String GetVersion();

返回值说明

当前SDK版本信息。

INativeFileTransCallback：监听回调

onFileTransEventCallback：监听事件和语音识别结果

方法签名

void onFileTransEventCallback(NuiEvent event, final int resultCode, final int arg2, AsrResult asrResult, String taskId);

参数说明

参数	类型	说明
`event`	`NuiEvent`	回调事件。
`resultCode`	`int`	仅在出现 `EVENT_ASR_ERROR` 事件时有效。
`asrResult`	`AsrResult`	语音识别结果。
`taskId`	`String`	任务ID。
`arg2`	`int`	保留参数。

onFileTransLogTrackCallback：监听追踪日志

此回调用于接收 SDK 内部的详细日志，方便进行问题定位和调试。

default void onFileTransLogTrackCallback(Constants.LogLevel level, String log)

`NuiEvent`：事件类型

事件	说明
`EVENT_FILE_TRANS_CONNECTED`	连接服务成功。
`EVENT_FILE_TRANS_UPLOADED`	上传待识别音频文件成功，此时可获得当前任务的 `task_id`。
`EVENT_FILE_TRANS_QUERY_RESULT`	查询任务结果。
`EVENT_FILE_TRANS_RESULT`	识别最终结果。
`EVENT_ASR_ERROR`	语音识别过程中出现错误。

快速开始

调用步骤

同步模式

异步模式

请求参数

连接与控制参数

语音识别效果参数

关键接口

NativeNui

initialize

setParams

startFileTranscriber

queryFileTranscriber

cancelFileTranscriber

release

GetVersion

INativeFileTransCallback：监听回调

onFileTransEventCallback：监听事件和语音识别结果

onFileTransLogTrackCallback：监听追踪日志

NuiEvent：事件类型

`NuiEvent`：事件类型