本文檔提供了Qwen-Audio-ASR-Filetrans非即時語音識別iOS SDK的詳細使用指南,幫助您將語音轉換為文本。
關於支援的音訊格式、檔案大小限制、時長限制等輸入要求,請參見音訊規格。
通過在
參數說明
通過
參數說明
初始化語音識別SDK實例。SDK為單例模式,在呼叫
參數說明
此介面用於獨立設定或更新
參數說明
開始識別。
方法簽名
參數說明
此介面用於主動查詢一個非同步任務的當前狀態和結果。呼叫成功後,結果將通過
方法簽名
參數說明
立即取消當前任務。
方法簽名
參數說明
釋放SDK所有內部資源,並強制終止所有正在進行的任務。此方法呼叫後,SDK實例將變為不可用狀態,如需再次使用,必須重新呼叫
獲得當前SDK版本資訊。
方法簽名
返回值說明
當前SDK版本資訊。
方法簽名
參數說明
此回呼用於接收 SDK 內部的詳細日誌,方便進行問題定位和調試。
快速開始
- 取得API Key:取得API Key
-
下載SDK並運行示例程式碼:
- 下載最新SDK整合包。
- 解壓 ZIP 包,將其中的 nuisdk.framework 添加到工程。
- 在 Build Phases → Link Binary With Libraries 中添加
nuisdk.xcframework。 - 在 General → Frameworks, Libraries, and Embedded Content 中將
nuisdk.xcframework設定為 Embed & Sign。 - 用 Xcode 打開示例工程。示例程式碼位於
DashFunAsrFileTranscriberViewController.m,替換 API Key 後體驗功能。
呼叫步驟
- 同步模式
- 非同步模式
- 初始化 SDK
- 按業務需求設定相關參數
- 當
async_request設為false時,呼叫nui_file_trans_start發送非即時語音識別請求,並等待結果返回。 - 在
onFileTransEventCallback介面中監聽EVENT_FILE_TRANS_RESULT事件,取得最終識別結果 - 呼叫
nui_release釋放 SDK 資源
請求參數
連接與控制參數
通過在nui_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 | 否 | 日誌檔案的存儲路徑。此參數僅在呼叫nui_initialize介面時將save_log設為YES時生效。此時必須設定日誌檔案路徑,否則將報錯。本地最多保留兩個日誌檔案。 |
max_log_file_size | int | 否 | 設定日誌檔案的最大字節數。此參數僅在呼叫nui_initialize介面時將save_log設為YES時生效。預設值:104857600(100 * 1024 * 1024 字節, 即 100MiB)。 |
log_track_level | int | 否 | 控制通過日誌回呼(onFileTransLogTrackCallback)對外發送的日誌內容的過濾級別。預設值:2。取值範圍:
log_track_level與level(通過nui_initialize介面設定)共同決定最終回呼的日誌。一條日誌的級別數值必須同時大於或等於log_track_level和level的值,才會被回呼。例如,log_track_level設為2 (INFO),level設為3 (WARNING),則只有WARNING及以上級別(數值>=3)的日誌才會被回呼。 |
語音識別效果參數
通過nui_file_trans_start介面設定所有語音識別效果參數。
參數示例
以下為 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 個生效。
點擊查看支援的語言程式碼
|
關鍵介面
NeoNui
nui_initialize
初始化語音識別SDK實例。SDK為單例模式,在呼叫 nui_release 前禁止重復初始化。
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
parameters | char* | JSON字串,包含鑒權、連接和調試參數。參見連接與控制參數。 |
level | NuiSdkLogLevel | 控制SDK自身日誌的打印級別。 |
save_log | BOOL | 是否儲存本地日誌。若為YES,須在連接與控制參數通過debug_path指定路徑,並可通過max_log_file_size設定檔案大小。 |
nui_set_params
此介面用於獨立設定或更新 nls_config 參數。如果所有參數都在nui_file_trans_start中一次性提供,則無需呼叫此方法。
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
params | char* | 語音識別效果參數中的nls_config參數,nls_config之外的參數不支援通過該方法進行設定。示例: |
nui_file_trans_start
開始識別。
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
params | char* | 語音識別效果參數。示例: |
task_id | char* | 任務ID,SDK內部生成隨機字串,在此介面呼叫成功後可獲得task_id。 |
nui_file_trans_query
此介面用於主動查詢一個非同步任務的當前狀態和結果。呼叫成功後,結果將通過onFileTransEventCallback回呼中的 EVENT_FILE_TRANS_QUERY_RESULT 事件返回。
此處傳入的
task_id 從 EVENT_FILE_TRANS_UPLOADED 事件中取得。| 參數 | 類型 | 說明 |
|---|---|---|
task_id | char* | 待查詢的任務 ID,從 EVENT_FILE_TRANS_UPLOADED 事件中取得。 |
nui_file_trans_cancel
立即取消當前任務。
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
task_id | char* | 待取消的任務 ID,從 EVENT_FILE_TRANS_UPLOADED 事件中取得。 |
nui_release
釋放SDK所有內部資源,並強制終止所有正在進行的任務。此方法呼叫後,SDK實例將變為不可用狀態,如需再次使用,必須重新呼叫 nui_initialize 進行初始化。
方法簽名
nui_get_version
獲得當前SDK版本資訊。
方法簽名
NeoNuiSdkDelegate:監聽回呼
onFileTransEventCallback:監聽事件和語音識別結果
方法簽名
| 參數 | 類型 | 說明 |
|---|---|---|
nuiEvent | NuiCallbackEvent | 回呼事件。 |
asr_result | char* | 語音識別結果。 |
task_id | char* | 任務ID。 |
finish | BOOL | 本輪識別是否結束標誌。 |
code | int | 僅在出現 EVENT_ASR_ERROR 事件時有效。 |
onFileTransLogTrackCallback:監聽追蹤日誌
此回呼用於接收 SDK 內部的詳細日誌,方便進行問題定位和調試。
NuiCallbackEvent:事件類型
| 事件 | 說明 |
|---|---|
EVENT_FILE_TRANS_CONNECTED | 連接服務成功。 |
EVENT_FILE_TRANS_UPLOADED | 上傳待識別音訊檔案成功,此時可獲得當前任務的 task_id。 |
EVENT_FILE_TRANS_QUERY_RESULT | 查詢任務結果。 |
EVENT_FILE_TRANS_RESULT | 識別最終結果。 |
EVENT_ASR_ERROR | 語音識別過程中出現錯誤。 |