前提條件
快速開始
以下呼叫範例可共用。依下表替換範例中的模型 ID。
| 模型 | 範例中的模型 ID |
|---|---|
| Qwen-Audio-ASR-Streaming | qwen-audio-3.0-asr-flash-streaming |
| Qwen-Audio-ASR-Message | qwen-audio-3.1-asr-flash-message取樣率僅支援 16000 Hz。 |
| Fun-ASR-Realtime | fun-asr-realtime |
client.audio.asr)提供了非流式調用和雙向流式調用等介面。請根據實際需求選擇合適的調用方式:
- 非流式調用(
recognize_file):針對本地檔案進行識別,SDK自動分塊發送音頻並驅動到任務結束。適合處理錄製好的音頻。 - 雙向流式調用(
recognize會話):可直接對音頻流進行識別,並即時輸出結果。音頻流可以來自外部裝置(如麥克風)或從本地檔案讀取。適合需要即時反饋的情境。
- 非流式調用
- 雙向流式調用
提交單個語音即時轉寫任務,通過傳入本地檔案的方式同步阻塞地拿到轉寫結果。調用核心資源(
client.audio.asr)的recognize_file方法綁定請求參數並傳入本地檔案路徑,迭代服務端事件擷取識別結果。請求參數
Qwen-Audio-ASR-Streaming
共用說明
請參閱新版 Qwen-Audio-ASR-Streaming Python SDK。
請求參數通過核心資源(client.audio.asr)的recognize/recognize_file方法進行設定:model、format、sample_rate、vocabulary_id為具名參數,其餘參數(如language_hints)通過parameters字典傳入。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | str | 是 | 模型名稱。 |
sample_rate | int | 是 | 採樣率(Hz),支援任意採樣率。 |
format | str | 是 | 音頻格式。取值範圍:
|
keep_dialect | bool | 否 | 僅適用於 qwen-audio-3.1-asr-flash-streaming。false,將方言轉寫為普通話文本。設為 true 時保留方言表達。 透過同名的關鍵字參數傳入。 |
vad_model | str | 否 | 僅適用於 qwen-audio-3.1-asr-flash-streaming。near_meeting_16k(近場)或 far_field_meeting_16k(遠場,預設值)。 透過同名的關鍵字參數傳入。 |
vocabulary_id | str | 否 | 先行編譯熱詞列表 ID。需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。使用方法請參見先行編譯熱詞。 |
vocabulary | dict | 否 | 即時熱詞。以索引值對形式傳入,鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50:取 [1, 5] 時值越大模型越傾向輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞數量最多不超過 50 個。適用於臨時性、會話層級的熱詞最佳化。與先行編譯熱詞同時配置時,僅即時熱詞生效。使用方法請參見即時熱詞。樣本: |
max_sentence_silence | int | 否 | VAD 斷句靜音閾值(ms)。當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。預設值:800。取值範圍:[200, 6000]。 |
multi_threshold_mode_enabled | bool | 否 | 是否啟用多閾值模式。啟用後可防止 VAD 斷句切割過長。預設值:False。 |
punctuation_prediction_enabled | bool | 否 | 設定是否在識別結果中自動添加標點:
|
heartbeat | bool | 否 | 是否啟用心跳包。預設值:False。
|
language_hints | list[str] | 否 | 待識別音頻語種。無預設值,不設定時模型自動識別。最多支援設定 4 個值,超出時僅前 4 個生效。
點擊查看支援的語言代碼
|
speech_noise_threshold | float | 否 | 語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。取值範圍:[-1.0, 1.0]。取值說明:
|
special_word_filter | str | 否 | 指定在語音辨識過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。 |
recognize/recognize_file方法的input關鍵字參數傳入。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
input | dict | 否 | 輸入對象,用於傳入對話上下文(context)。上下文用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見快速開始。dict 中需包含 context 鍵,值為訊息列表(list[dict]),每條訊息包含以下欄位:
使用該欄位時,SDK版本不能低於2.0.1。 input通過recognize/recognize_file方法傳入: |
Qwen-Audio-ASR-Message
共用說明
請參閱新版 Qwen-Audio-ASR-Message Python SDK。
請求參數通過核心資源(client.audio.asr)的recognize/recognize_file方法進行設定:model、format、sample_rate、vocabulary_id為具名參數,其餘參數(如language_hints)通過parameters字典傳入。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | str | 是 | 模型名稱。 |
sample_rate | int | 是 | 採樣率(Hz),僅支援 16000。 |
format | str | 是 | 音頻格式。取值範圍:
|
keep_dialect | bool | 否 | 預設為 false,將方言轉寫為普通話文本。設為 true 時保留方言表達。 透過同名的關鍵字參數傳入。僅在最終結果(sentence_end=true)生效,中間結果(sentence_end=false)不支援。 |
vad_model | str | 否 | VAD 模型。取值為 near_meeting_16k(近場)或 far_field_meeting_16k(遠場,預設值)。 透過同名的關鍵字參數傳入。 |
disfluency_removal_enabled | bool | 否 | 是否過濾語氣詞並潤飾輸出。預設為 false,設為 true 時啟用。 透過同名的關鍵字參數傳入。 |
intermediate_result_enabled | bool | 否 | 是否傳回串流中間結果。預設為 false,設為 true 時傳回中間結果。 透過同名的關鍵字參數傳入。 |
vocabulary_id | str | 否 | 先行編譯熱詞列表 ID。需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。使用方法請參見先行編譯熱詞。 |
vocabulary | dict | 否 | 即時熱詞。以索引值對形式傳入,鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50:取 [1, 5] 時值越大模型越傾向輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞數量最多不超過 50 個。適用於臨時性、會話層級的熱詞最佳化。與先行編譯熱詞同時配置時,僅即時熱詞生效。使用方法請參見即時熱詞。樣本: |
language_hints | list[str] | 否 | 待識別音頻語種。無預設值,不設定時模型自動識別。最多支援設定 4 個值,超出時僅前 4 個生效。
點擊查看支援的語言代碼
sentence_end=true)生效,中間結果(sentence_end=false)不支援。 |
max_sentence_silence | int | 否 | VAD 斷句靜音閾值(毫秒)。語音後的靜音時長超過此值時判定句子結束。預設值為 800,取值範圍為 [200, 6000]。 |
heartbeat | bool | 否 | 是否啟用心跳包。預設值:False。
|
speech_noise_threshold | float | 否 | 語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。取值範圍:[-1.0, 1.0]。取值說明:
|
recognize/recognize_file方法的input關鍵字參數傳入。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
input | dict | 否 | 輸入對象,用於傳入對話上下文(context)。上下文用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見快速開始。dict 中需包含 context 鍵,值為訊息列表(list[dict]),每條訊息包含以下欄位:
該欄位自 SDK 1.25.23 引入,2.0.1 及以上版本已包含。 input通過recognize/recognize_file方法傳入: |
Fun-ASR-Realtime
共用說明
請參閱新版 Fun-ASR-Realtime Python SDK。
請求參數通過核心資源(client.audio.asr)的recognize/recognize_file方法進行設定:model、format、sample_rate、vocabulary_id為具名參數,其餘參數(如max_sentence_silence、language_hints)通過parameters字典傳入。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | str | 是 | 模型名稱。 |
sample_rate | int | 是 | 採樣率(Hz)。取值範圍:8k模型僅支援 8000 Hz,其他模型支援任意採樣率。 |
format | str | 是 | 音頻格式。取值範圍:
|
vocabulary_id | str | 否 | 先行編譯熱詞列表 ID。需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。使用方法請參見先行編譯熱詞。 |
max_sentence_silence | int | 否 | VAD 斷句靜音閾值(ms)。當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。預設值:1300。取值範圍:[200, 6000]。 |
multi_threshold_mode_enabled | bool | 否 | 是否啟用多閾值模式。啟用後可防止 VAD 斷句切割過長。預設值:False。 |
punctuation_prediction_enabled | bool | 否 | 設定是否在識別結果中自動添加標點:
|
heartbeat | bool | 否 | 是否啟用心跳包。預設值:False。
|
language_hints | list[str] | 否 | 待識別音頻語種。無預設值,不設定時模型自動識別。僅支援設定 1 個值,設定多個時僅第一個生效。
點擊查看支援的語言代碼
|
speech_noise_threshold | float | 否 | 語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。取值範圍:[-1.0, 1.0]。取值說明:
|
special_word_filter | str | 否 | 指定在語音辨識過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。 |
recognize/recognize_file方法的input關鍵字參數傳入。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
input | dict | 否 | 輸入對象,用於傳入對話上下文(context)。上下文用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見提升識別準確率。dict 中需包含 context 鍵,值為訊息列表(list[dict]),每條訊息包含以下欄位:
使用該欄位時,SDK版本不能低於2.0.1。 input通過recognize/recognize_file方法傳入: |
介面參考
共用介面
事件迭代(events()/results())
雙向流式調用時,服務端會通過事件的方式,將關鍵流程資訊和資料返回給用戶端。您需要在接收線程中迭代會話的events()(原始事件dict)或results()(類型化識別結果幀),處理服務端返回的資訊或者資料。
| 事件/迭代方法 | 產出內容 | 傳回值 | 描述 |
|---|---|---|---|
task-started事件 | 無 | 由start()內部讀取,啟動返回時保存在last_response中,不會由events()再次產出。 | |
event:服務端事件dict | 迭代器 | 當服務有回複時產出事件。識別結果位於payload.output.sentence,可能為心跳或空文本事件,應用可按需忽略。請由一個接收線程持續消費,不要並發建立多個讀取者。 | |
result:識別結果(RecognitionResult) | 迭代器 | 只產出識別結果幀(心跳幀已過濾),全部識別結果返回後迭代結束。 | |
DashScopeError異常 | 無 | 發生異常時在發送/接收線程中拋出,可使用try/except捕獲。 | |
task-finished事件 | 無 | 當服務已經完成全部識別後由events()產出,隨後迭代結束;發送stop()後仍須讀取此事件。 |
識別結果(RecognitionResult)
RecognitionResult代表會話results()迭代產出的一次識別結果幀(雙向流式調用與非流式調用均可使用;events()產出的是原始事件dict,如需該類型化視圖請改用results())。
| 成員方法 | 方法簽名 | 說明 |
|---|---|---|
get_sentence | 擷取當前識別的句子及時間戳記資訊,此方法傳回型別為Dict[str, Any](單句資訊)。詳情請參見單句資訊(Sentence)。 | |
request_id | 當前事件對應的請求request_id。 | |
is_sentence_end | 判斷當前句子是否已經結束。該方法通過檢查 get_sentence() 返回的單句資訊中 end_time 欄位是否為 None 來判定——end_time 不為 None 時表示句子已結束。 |
單句資訊(Sentence)
Sentence類成員如下:
| 參數 | 類型 | 說明 |
|---|---|---|
begin_time | int | 句子開始時間,單位為ms。 |
end_time | int | 句子結束時間,單位為ms。 |
text | str | 識別文本。 |
words | 字時間戳記資訊(Word)的list集合 | 字時間戳記資訊。 |
字時間戳記資訊(Word)
Word類成員如下:
| 參數 | 類型 | 說明 |
|---|---|---|
begin_time | int | 字開始時間,單位為ms。 |
end_time | int | 字結束時間,單位為ms。 |
text | str | 字。 |
punctuation | str | 標點。 |
Qwen-Audio-ASR-Streaming / Qwen-Audio-ASR-Message
介面地址
SDK的即時識別走WebSocket介面,端點由Client的workspace與region自動決定(包含WorkspaceId)。如需切換到其他地區,構造Client時設定對應地區的region即可。
- 新加坡
- 華北2(北京)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference調用時請將{WorkspaceId}替換為真實的Workspace ID。Qwen-Audio-ASR-Streaming
關鍵介面
核心資源(client.audio.asr)
即時語音辨識能力掛載在client.audio.asr資源上:recognize建立雙向流式識別會話(Recognition),recognize_file對本地檔案一次性識別。
| 成員方法 | 方法簽名 | 說明 |
|---|---|---|
| recognize | 建立雙向流式識別會話,進入with上下文時自動調用start建立串連並發送任務。發送音頻與消費事件需並發進行(配合send_audio_frame、events()/results()和stop使用)。 | |
| recognize_file | 基於本地檔案的非流式調用:自動分塊發送音頻並驅動到任務結束,逐個產出服務端事件。該方法要求所識別檔案具有可讀許可權。 | |
start | 開始語音辨識:建立串連、發送任務並等待task-started。進入with上下文時自動調用,啟動成功後才能發送音頻。 | |
send_audio_frame | 推送音頻。每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。識別結果通過事件迭代(events()/results())擷取。 | |
stop | 停止語音辨識:只通知服務端輸入結束,接收線程需繼續消費events()直到task-finished事件。 | |
| events / results | 迭代服務端事件:events()產出原始事件dict(識別文本位於payload.output.sentence);results()只產出識別結果幀,返回識別結果(RecognitionResult)類型化對象(心跳幀已過濾)。 | |
| close | 關閉識別會話。退出with上下文時自動調用。 | |
| request_id / first_package_delay / last_package_delay / last_response | 擷取request_id、首包延遲(從發送第一包音頻到收到首包識別結果延遲)和尾包延遲(發送stop指令到最後一包識別結果下發耗時),在任務完成後使用;last_response為最近一次成功讀取的原始報文,可用於擷取task-failed報錯。會話關閉後仍可讀取。 |
響應結果
Qwen-Audio-ASR-Message
關鍵介面
核心資源(client.audio.asr)
即時語音辨識能力掛載在client.audio.asr資源上:recognize建立雙向流式識別會話(Recognition),recognize_file對本地檔案一次性識別。
| 成員方法 | 方法簽名 | 說明 |
|---|---|---|
recognize | 建立雙向流式識別會話,進入with上下文時自動調用start建立串連並發送任務。發送音頻與消費事件需並發進行(配合send_audio_frame、events()/results()和stop使用)。 | |
recognize_file | 基於本地檔案的非流式調用:自動分塊發送音頻並驅動到任務結束,逐個產出服務端事件。該方法要求所識別檔案具有可讀許可權。 | |
start | 開始語音辨識:建立串連、發送任務並等待task-started。進入with上下文時自動調用,啟動成功後才能發送音頻。 | |
send_audio_frame | 推送音頻。每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。識別結果通過事件迭代(events()/results())擷取。 | |
stop | 停止語音辨識:只通知服務端輸入結束,接收線程需繼續消費events()直到task-finished事件。 | |
events / results | 迭代服務端事件:events()產出原始事件dict(識別文本位於payload.output.sentence);results()只產出識別結果幀,返回識別結果(RecognitionResult)類型化對象(心跳幀已過濾)。 | |
close | 關閉識別會話。退出with上下文時自動調用。 | |
request_id / first_package_delay / last_package_delay / last_response | 擷取request_id、首包延遲(從發送第一包音頻到收到首包識別結果延遲)和尾包延遲(發送stop指令到最後一包識別結果下發耗時),在任務完成後使用;last_response為最近一次成功讀取的原始報文,可用於擷取task-failed報錯。會話關閉後仍可讀取。 |
響應結果
Fun-ASR-Realtime
介面地址
SDK的即時識別走WebSocket介面,端點由Client的workspace與region自動決定(包含WorkspaceId)。如需切換到其他地區,構造Client時設定對應地區的region即可。
- 新加坡
- 華北2(北京)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference調用時請將{WorkspaceId}替換為真實的Workspace ID。關鍵介面
核心資源(client.audio.asr)
即時語音辨識能力掛載在client.audio.asr資源上:recognize建立雙向流式識別會話(Recognition),recognize_file對本地檔案一次性識別。
| 成員方法 | 方法簽名 | 說明 |
|---|---|---|
| recognize | 建立雙向流式識別會話,進入with上下文時自動調用start建立串連並發送任務。發送音頻與消費事件需並發進行(配合send_audio_frame、events()/results()和stop使用)。 | |
| recognize_file | 基於本地檔案的非流式調用:自動分塊發送音頻並驅動到任務結束,逐個產出服務端事件。該方法要求所識別檔案具有可讀許可權。 | |
| start | 開始語音辨識:建立串連、發送任務並等待task-started。進入with上下文時自動調用,啟動成功後才能發送音頻。 | |
| send_audio_frame | 推送音頻。每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。識別結果通過events()/results()迭代擷取。 | |
| stop | 停止語音辨識:只通知服務端輸入結束,接收線程需繼續消費events()直到task-finished事件。 | |
| events / results | 迭代服務端事件:events()產出原始事件dict(識別文本位於payload.output.sentence);results()只產出識別結果幀,返回識別結果(RecognitionResult)類型化對象(心跳幀已過濾)。 | |
| close | 關閉識別會話。退出with上下文時自動調用。 | |
| request_id / first_package_delay / last_package_delay / last_response | 擷取request_id、首包延遲(從發送第一包音頻到收到首包識別結果延遲)和尾包延遲(發送stop指令到最後一包識別結果下發耗時),在任務完成後使用;last_response為最近一次成功讀取的原始報文,可用於擷取task-failed報錯。會話關閉後仍可讀取。 |