本文檔提供了Qwen-Audio-ASR-Filetrans非即時語音識別Android SDK的詳細使用指南,幫助您將語音轉換為文本。
關於支援的音訊格式、檔案大小限制、時長限制等輸入要求,請參見音訊規格。
通過在
參數說明
通過
參數說明
初始化語音識別SDK實例。SDK為單例模式,在呼叫
參數說明
此介面用於獨立設定或更新
參數說明
開始識別。
方法簽名
參數說明
此介面用於主動查詢一個非同步任務的當前狀態和結果。呼叫成功後,結果將通過
方法簽名
參數說明
立即取消當前任務。
方法簽名
參數說明
釋放SDK所有內部資源。此方法呼叫後,SDK實例將變為不可用狀態,如需再次使用,必須重新呼叫
獲得當前SDK版本資訊。
方法簽名
返回值說明
當前SDK版本資訊。
方法簽名
參數說明
此回呼用於接收 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 資源
請求參數
連接與控制參數
通過在initialize介面的parameters參數中傳入一個JSON字串來設定。
參數示例
以下為 JSON 字串示例,參數未完整列出。請按實際需求在編碼時補充:
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
url | String | 是 | 服務地址:
{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。取值範圍:
log_track_level與level(通過initialize介面設定)共同決定最終回呼的日誌。一條日誌的級別數值必須同時大於或等於log_track_level和level的值,才會被回呼。例如,log_track_level設為2 (INFO),level設為3 (WARNING),則只有WARNING及以上級別(數值>=3)的日誌才會被回呼。 |
語音識別效果參數
通過startFileTranscriber介面設定所有語音識別效果參數。
參數示例
以下為 JSON 字串示例,參數未完整列出。請按實際需求在編碼時補充:
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
file_urls | array[string] | 是 | 音視訊檔案轉寫的URL列表,支援HTTP / HTTPS協議,單次請求僅支援1個URL。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求,請參見音訊規格。若錄音檔案存儲在阿里雲OSS,使用RESTful API方式支援使用以oss://為前綴的臨時 URL,使用SDK方式不支援使用以 oss://為前綴的臨時 URL。 |
async_request | boolean | 否 | 語音識別是否為非同步請求。預設值: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]。 |
nls_config.diarization_enabled | boolean | 否 | 是否啓用說話人分離,預設關閉。僅適用於單聲道音訊,多聲道音訊不支援說話人分離。啓用該功能後,識別結果中將顯示speaker_id字段,用於區分不同說話人。如果啓用說話人分離功能,建議音訊時長不超過2小時,否則可能導致識別失敗或超時。 speaker_id的示例,請參見識別結果說明。 |
nls_config.speaker_count | integer | 否 | 說話人數量參考值。取值範圍為2至100的整數(包含2和100)。預設自動判斷說話人數量,如果設定此項,只能輔助算法盡量輸出指定人數,無法保證一定會輸出此人數。無預設值。 |
nls_config.vocabulary_id | string | 否 | 預編譯熱詞列表 ID。需預先呼叫建立熱詞列表介面生成,識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求復用同一詞表的場景。使用方法請參見預編譯熱詞。 |
nls_config.input_context | array | 否 | 消息列表,包含用於提升識別效果的可選對話上下文。 |
nls_config.instant_vocabulary | object | 否 | 即時熱詞,以鍵值對形式傳入:鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。適用於臨時性、會話級別的熱詞優化。權重取值範圍為 1 至 5 或 50。取 1 至 5 時,值越大,模型越傾向於輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞最多不超過 50 個。與預編譯熱詞同時設定時,系統會合併兩類熱詞;合併後超過 2000 個時,隨機選擇 2000 個使用。使用方法請參見即時熱詞。 |
nls_config.language_hints | array[string] | 否 | 設定待識別語言程式碼。如果無法提前確定語種,可不設定,模型會自動識別語種。最多支援設定 4 個值,超出時僅前 4 個生效。
點擊查看支援的語言程式碼
|
關鍵介面
NativeNui
initialize
初始化語音識別SDK實例。SDK為單例模式,在呼叫release前禁止重復初始化。
此介面會引起阻塞,應在非UI線程呼叫。
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
callback | INativeFileTransCallback | 事件和資料回呼介面的實現。 |
parameters | String | JSON字串,包含鑒權、連接和調試參數。參見連接與控制參數。 |
level | Constants.LogLevel | 控制SDK自身日誌的打印級別。 |
save_log | boolean | 是否儲存本地日誌。若為true,須在連接與控制參數中通過debug_path指定路徑,並可通過max_log_file_size設定檔案大小。 |
setParams
此介面用於獨立設定或更新 nls_config 參數。如果所有參數都在startFileTranscriber中一次性提供,則無需呼叫此方法。
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
params | String | 語音識別效果參數中的nls_config參數,nls_config之外的參數不支援通過該方法進行設定。示例: |
startFileTranscriber
開始識別。
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
params | String | 語音識別效果參數。示例: |
task_id | byte[] | 任務ID,SDK內部生成隨機字串,在此介面呼叫成功後可獲得task_id。 |
queryFileTranscriber
此介面用於主動查詢一個非同步任務的當前狀態和結果。呼叫成功後,結果將通過onFileTransEventCallback回呼中的 EVENT_FILE_TRANS_QUERY_RESULT 事件返回。
此處傳入的
task_id 從 EVENT_FILE_TRANS_UPLOADED 事件中取得。| 參數 | 類型 | 說明 |
|---|---|---|
task_id | String | 待查詢的任務 ID,從 EVENT_FILE_TRANS_UPLOADED 事件中取得。 |
cancelFileTranscriber
立即取消當前任務。
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
task_id | String | 待取消的任務 ID,從 EVENT_FILE_TRANS_UPLOADED 事件中取得。 |
release
釋放SDK所有內部資源。此方法呼叫後,SDK實例將變為不可用狀態,如需再次使用,必須重新呼叫initialize進行初始化。
方法簽名
GetVersion
獲得當前SDK版本資訊。
方法簽名
INativeFileTransCallback:監聽回呼
onFileTransEventCallback:監聽事件和語音識別結果
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
event | NuiEvent | 回呼事件。 |
resultCode | int | 僅在出現 EVENT_ASR_ERROR 事件時有效。 |
asrResult | AsrResult | 語音識別結果。 |
taskId | String | 任務ID。 |
arg2 | int | 保留參數。 |
onFileTransLogTrackCallback:監聽追蹤日誌
此回呼用於接收 SDK 內部的詳細日誌,方便進行問題定位和調試。
NuiEvent:事件類型
| 事件 | 說明 |
|---|---|
EVENT_FILE_TRANS_CONNECTED | 連接服務成功。 |
EVENT_FILE_TRANS_UPLOADED | 上傳待識別音訊檔案成功,此時可獲得當前任務的 task_id。 |
EVENT_FILE_TRANS_QUERY_RESULT | 查詢任務結果。 |
EVENT_FILE_TRANS_RESULT | 識別最終結果。 |
EVENT_ASR_ERROR | 語音識別過程中出現錯誤。 |