全部產品
Search
文件中心

Alibaba Cloud Model Studio:Qwen-Audio-ASR / Fun-ASR Python SDK

更新時間:Nov 19, 2026

前提條件

已開通服務並擷取與配置 API Key。請配置API Key到環境變數,而非寫入程式碼在代碼中,防範因代碼泄露導致的安全風險。

快速開始

以下呼叫範例可共用。依下表替換範例中的模型 ID。

模型範例中的模型 ID
Qwen-Audio-ASR-Streamingqwen-audio-3.0-asr-flash-streaming
Qwen-Audio-ASR-Messageqwen-audio-3.1-asr-flash-message
取樣率僅支援 16000 Hz。
Fun-ASR-Realtimefun-asr-realtime

核心資源(client.audio.asr)提供了非流式調用和雙向流式調用等介面。請根據實際需求選擇合適的調用方式:

  • 非流式調用(recognize_file):針對本地檔案進行識別,SDK自動分塊發送音頻並驅動到任務結束。適合處理錄製好的音頻。
  • 雙向流式調用(recognize會話):可直接對音頻流進行識別,並即時輸出結果。音頻流可以來自外部裝置(如麥克風)或從本地檔案讀取。適合需要即時反饋的情境。

非流式調用

提交單個語音即時轉寫任務,通過傳入本地檔案的方式同步阻塞地拿到轉寫結果。

調用核心資源(client.audio.asr)的recognize_file方法綁定請求參數並傳入本地檔案路徑,迭代服務端事件擷取識別結果。

import os
import dashscope

# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # 以下為新加坡(ap-southeast-1)地區的配置。調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# 識別本地語音檔案:recognize_file自動分塊發送音頻並驅動到任務結束
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='qwen-audio-3.0-asr-flash-streaming',
        format='wav',
        sample_rate=16000):
    payload = event.get('payload') or {}
    sentence = (payload.get('output') or {}).get('sentence') or {}
    if sentence.get('text') and not sentence.get('heartbeat'):
        print('識別結果:', sentence['text'])

雙向流式調用

提交單個語音即時轉寫任務,通過迭代事件的方式流式輸出即時識別結果。

  1. 啟動流式語音辨識

    調用核心資源(client.audio.asr)的recognize方法建立識別會話並綁定請求參數,進入with上下文(自動調用start方法建立串連並發送任務)啟動流式語音辨識。

  2. 串流

    迴圈調用會話的send_audio_frame方法,將從本地檔案或裝置(如麥克風)讀取的二進位音頻流分段發送至服務端。發送與接收需並發進行:接收線程通過會話的events()方法迭代服務端事件,將識別結果即時返回給用戶端。

    建議每次發送的音頻時間長度約為100毫秒,資料大小保持在1KB至16KB之間。

  3. 結束處理

    調用會話的stop方法結束語音辨識。

    該方法只通知服務端輸入結束;接收線程需繼續消費events()直到task-finished事件以獲得最後的識別結果和統計資訊。ws層的錯誤會以DashScopeError異常拋出,可在發送/接收處使用try/except捕獲。

import os
import signal  # for keyboard events handling (press "Ctrl+C" to terminate recording)
import sys

import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor

mic = None
stream = None

# Set recording parameters
sample_rate = 16000  # 麥克風與辨識請求使用相同的取樣率。Qwen-Audio-ASR-Message 僅支援 16000 Hz。
channels = 1  # mono channel
dtype = 'int16'  # data type
format_pcm = 'pcm'  # the format of the audio data
block_size = 3200  # number of frames per buffer

# Real-time speech recognition event receiver
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognition text: ', sentence['text'])
            if sentence.get('sentence_end'):
                print(
                    'Recognition sentence end, request_id:%s, usage:%s'
                    % (rec.request_id, rec.usage))

def signal_handler(sig, frame):
    print('Ctrl+C pressed, stop recognition ...')
    # Stop recognition
    recognition.stop()
    print('Recognition stopped.')
    print(
        '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
        .format(
            recognition.request_id,
            recognition.first_package_delay,
            recognition.last_package_delay,
        ))
    # Forcefully exit the program
    sys.exit(0)

# main function
if __name__ == '__main__':
    # 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    # 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
    client = dashscope.Client(
        api_key=os.environ.get('DASHSCOPE_API_KEY'),
        # 以下為新加坡(ap-southeast-1)地區的配置。調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
    )

    # Call recognition service, you can customize the recognition parameters, like model, format,
    # sample_rate
    with client.audio.asr.recognize(
            model='qwen-audio-3.0-asr-flash-streaming',
            format=format_pcm,
            # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr', you can check the supported formats in the document
            sample_rate=sample_rate,
    ) as recognition:
        # Open the microphone
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=sample_rate,
                          input=True)
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, recognition)
            try:
                # Send audio from the microphone until "Ctrl+C" is pressed
                while stream:
                    data = stream.read(3200, exception_on_overflow=False)
                    recognition.send_audio_frame(data)
                recognition.stop()
                receiver.result()
            finally:
                # close must run inside the pool context to unblock the receiver
                recognition.close()
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None
import os
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor

# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # 以下為新加坡(ap-southeast-1)地區的配置。調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

# Real-time speech recognition event receiver
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print(get_timestamp() + ' Recognition text: ', sentence['text'])
        if sentence.get('sentence_end'):
            print(get_timestamp() +
                  'Recognition sentence end, request_id:%s, usage:%s'
                  % (rec.request_id, rec.usage))

with client.audio.asr.recognize(
        model='qwen-audio-3.0-asr-flash-streaming',
        format='wav',
        sample_rate=16000,
) as recognition:
    with ThreadPoolExecutor(max_workers=1) as pool:
        receiver = pool.submit(receive_events, recognition)
        try:
            audio_data: bytes = None
            f = open("{YOUR_AUDIO_FILE}", 'rb')
            if os.path.getsize("{YOUR_AUDIO_FILE}"):
                # 一次性將檔案資料全部讀入buffer
                file_buffer = f.read()
                f.close()
                print("Start Recognition")

                # 從buffer中間隔3200位元組發送一次
                buffer_size = len(file_buffer)
                offset = 0
                chunk_size = 3200

                while offset < buffer_size:
                    # 計算本次要發送的資料區塊大小
                    remaining_bytes = buffer_size - offset
                    current_chunk_size = min(chunk_size, remaining_bytes)

                    # 從buffer中提取當前資料區塊
                    audio_data = file_buffer[offset:offset + current_chunk_size]

                    # 發送音頻資料幀
                    recognition.send_audio_frame(audio_data)
                    # 更新位移量
                    offset += current_chunk_size

                    # 添加延遲類比即時傳輸
                    time.sleep(0.1)

                recognition.stop()
                receiver.result()
            else:
                raise Exception(
                    'The supplied file was empty (zero bytes long)')
        finally:
            # close must run inside the pool context to unblock the receiver
            recognition.close()

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.request_id,
        recognition.first_package_delay,
        recognition.last_package_delay,
    ))

請求參數

Qwen-Audio-ASR-Streaming

共用說明

請參閱新版 Qwen-Audio-ASR-Streaming Python SDK。

請求參數通過核心資源(client.audio.asr)的recognize/recognize_file方法進行設定:model、format、sample_rate、vocabulary_id 可直接傳入。透過 parameters 字典傳入 language_hints。

參數類型是否必須說明
modelstr

是

模型名稱。
sample_rateint

是

採樣率(Hz),支援任意採樣率。

formatstr

是

音頻格式。

取值範圍:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

重要opus/speex:必須使用Ogg封裝;

wav:必須為PCM編碼;

amr:僅支援AMR-NB類型。

keep_dialectbool

否

說明僅適用於 qwen-audio-3.1-asr-flash-streaming。

預設為 false,將方言轉寫為普通話文本。設為 true 時保留方言表達。 透過 parameters 字典傳入。

vad_modelstr

否

說明僅適用於 qwen-audio-3.1-asr-flash-streaming。

VAD 模型。取值為 near_meeting_16k(近場)或 far_field_meeting_16k(遠場,預設值)。 透過 parameters 字典傳入。

vocabulary_idstr

否

先行編譯熱詞列表 ID。

需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。

適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。

使用方法請參見先行編譯熱詞。

vocabularydict

否

即時熱詞。

以索引值對形式傳入,鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50:取 [1, 5] 時值越大模型越傾向輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞數量最多不超過 50 個。

適用於臨時性、會話層級的熱詞最佳化。

與先行編譯熱詞同時配置時,僅即時熱詞生效。使用方法請參見即時熱詞。

樣本:

import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# 即時熱詞通過 parameters 傳入
vocab = {"張三": 5, "李四": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.0-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
max_sentence_silenceint

否

VAD 斷句靜音閾值(ms)。當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。

預設值:800。

取值範圍:[200, 6000]。

multi_threshold_mode_enabledbool

否

是否啟用多閾值模式。啟用後可防止 VAD 斷句切割過長。

預設值:False。

punctuation_prediction_enabledbool

否

設定是否在識別結果中自動添加標點:

  • True(預設):是,不支援修改。
heartbeatbool

否

是否啟用心跳包。

預設值:False。

  • True:在持續發送靜音音訊情況下,可保持與服務端的串連不中斷。
  • False(預設):即使持續發送靜音音頻,串連也將在一定時間後因逾時而斷開。

靜音音頻指的是在音頻檔案或資料流中沒有聲音訊號的內容。靜音音頻可以通過多種方法產生,例如使用音頻編輯軟體如Audacity或Adobe Audition,或者通過命令列工具如FFmpeg。

使用該欄位時,SDK版本不能低於2.0.1。

language_hintslist[str]

否

待識別音頻語種。無預設值,不設定時模型自動識別。

最多支援設定 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:斯洛伐克語
speech_noise_thresholdfloat

否

語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。

取值範圍:[-1.0, 1.0]。

取值說明:

  • 取值越接近 -1:降低噪音判定閾值,噪音被識別為語音的機率增大,可能導致更多噪音被轉寫
  • 取值越接近 +1:提高噪音判定閾值,語音被誤判為噪音的機率增大,可能導致部分語音被過濾

此參數為進階配置參數,調整可能顯著影響識別效果,建議:

  • 調整前充分測實驗證效果
  • 根據實際音頻環境小幅度調整(建議步長 0.1)
special_word_filterstr

否

指定在語音辨識過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。

使用 recognize 建立辨識工作階段時,透過 input 傳入上下文。

參數類型是否必須說明
inputdict

否

輸入對象,用於傳入對話上下文(context)。上下文用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見快速開始。

dict 中需包含 context 鍵,值為訊息列表(list[dict]),每條訊息包含以下欄位:

  • role(str,必選):訊息角色。user 表示前幾輪使用者語音的識別結果或領域相關的詞表;assistant 表示前幾輪大語言模型的回複內容。
  • content(list[dict],必選):訊息內容列表。每個元素包含 type(str,role 為 user 時填 input_text,role 為 assistant 時填 text)和 text(str,常值內容)。

重要約束:上下文訊息(input_text 和 text 類型)各最多 5 條,超出時保留最近的 5 條。每輪上下文文本總長度不超過 400 個字元,超出部分從末尾截斷。

重要攜帶上下文時,context 中的訊息順序有要求:上下文訊息必須按對話輪次排列,每輪中 user(input_text 類型)必須在對應的 assistant(text 類型)之前。

說明使用該欄位時,SDK版本不能低於2.0.1。

input通過recognize方法傳入:

# 構建 input 傳入資料
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "你好啊"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "你好啊,我是通義千問,有什麼可以協助你的?"
                }
            ]
        }
    ]
}

# 建立識別會話時通過 input 參數傳入
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.0-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Qwen-Audio-ASR-Message

共用說明

請參閱新版 Qwen-Audio-ASR-Message Python SDK。

請求參數通過核心資源(client.audio.asr)的recognize/recognize_file方法進行設定:model、format、sample_rate、vocabulary_id 可直接傳入。透過 parameters 字典傳入 language_hints。

參數類型是否必須說明
modelstr

是

模型名稱。
sample_rateint

是

採樣率(Hz),僅支援 16000。

formatstr

是

音頻格式。

取值範圍:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

重要opus/speex:必須使用Ogg封裝;

wav:必須為PCM編碼;

amr:僅支援AMR-NB類型。

keep_dialectbool

否

預設為 false,將方言轉寫為普通話文本。設為 true 時保留方言表達。 透過 parameters 字典傳入。

僅在最終結果(sentence_end=true)生效,中間結果(sentence_end=false)不支援。

vad_modelstr

否

VAD 模型。取值為 near_meeting_16k(近場)或 far_field_meeting_16k(遠場,預設值)。 透過 parameters 字典傳入。

disfluency_removal_enabledbool

否

是否過濾語氣詞並潤飾輸出。預設為 false,設為 true 時啟用。 透過同名的關鍵字參數傳入。

intermediate_result_enabledbool

否

是否傳回串流中間結果。預設為 false,設為 true 時傳回中間結果。 透過 parameters 字典傳入。

vocabulary_idstr

否

先行編譯熱詞列表 ID。

需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。

適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。

使用方法請參見先行編譯熱詞。

vocabularydict

否

即時熱詞。

以索引值對形式傳入,鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50:取 [1, 5] 時值越大模型越傾向輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞數量最多不超過 50 個。

適用於臨時性、會話層級的熱詞最佳化。

與先行編譯熱詞同時配置時,僅即時熱詞生效。使用方法請參見即時熱詞。

重要僅qwen-audio-3.1-asr-flash-message支援即時熱詞。

樣本:

import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# 即時熱詞通過 parameters 傳入
vocab = {"張三": 5, "李四": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
language_hintslist[str]

否

待識別音頻語種。無預設值,不設定時模型自動識別。

最多支援設定 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:斯洛伐克語

透過 parameters 字典傳入,例如 parameters={"language_hints": ["zh"]}。

僅在最終結果(sentence_end=true)生效,中間結果(sentence_end=false)不支援。

max_sentence_silenceint

否

VAD 斷句靜音閾值(毫秒)。語音後的靜音時長超過此值時判定句子結束。預設值為 800,取值範圍為 [200, 6000]。

heartbeatbool

否

是否啟用心跳包。

預設值:False。

  • True:在持續發送靜音音訊情況下,可保持與服務端的串連不中斷。
  • False(預設):即使持續發送靜音音頻,串連也將在一定時間後因逾時而斷開。

靜音音頻指的是在音頻檔案或資料流中沒有聲音訊號的內容。靜音音頻可以通過多種方法產生,例如使用音頻編輯軟體如Audacity或Adobe Audition,或者通過命令列工具如FFmpeg。

該欄位自 SDK 1.23.1 引入,2.0.1 及以上版本已包含。

speech_noise_thresholdfloat

否

語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。

取值範圍:[-1.0, 1.0]。

取值說明:

  • 取值越接近 -1:降低噪音判定閾值,噪音被識別為語音的機率增大,可能導致更多噪音被轉寫
  • 取值越接近 +1:提高噪音判定閾值,語音被誤判為噪音的機率增大,可能導致部分語音被過濾

此參數為進階配置參數,調整可能顯著影響識別效果,建議:

  • 調整前充分測實驗證效果
  • 根據實際音頻環境小幅度調整(建議步長 0.1)

使用 recognize 建立辨識工作階段時,透過 input 傳入上下文。

參數類型是否必須說明
inputdict

否

輸入對象,用於傳入對話上下文(context)。上下文用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見快速開始。

重要僅 qwen-audio-3.1-asr-flash-message 模型支援 context 參數。

dict 中需包含 context 鍵,值為訊息列表(list[dict]),每條訊息包含以下欄位:

  • role(str,必選):訊息角色。user 表示前幾輪使用者語音的識別結果或領域相關的詞表;assistant 表示前幾輪大語言模型的回複內容。
  • content(list[dict],必選):訊息內容列表。每個元素包含 type(str,role 為 user 時填 input_text,role 為 assistant 時填 text)和 text(str,常值內容)。

重要約束:上下文訊息(input_text 和 text 類型)各最多 5 條,超出時保留最近的 5 條。每輪上下文文本總長度不超過 400 個字元,超出部分從末尾截斷。

重要攜帶上下文時,context 中的訊息順序有要求:上下文訊息必須按對話輪次排列,每輪中 user(input_text 類型)必須在對應的 assistant(text 類型)之前。

說明該欄位自 SDK 1.25.23 引入,2.0.1 及以上版本已包含。

input通過recognize方法傳入:

# 構建 input 傳入資料
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "你好啊"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "你好啊,我是通義千問,有什麼可以協助你的?"
                }
            ]
        }
    ]
}

# 通過 input 參數傳入
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Fun-ASR-Realtime

共用說明

請參閱新版 Fun-ASR-Realtime Python SDK。

請求參數通過核心資源(client.audio.asr)的recognize/recognize_file方法進行設定:model、format、sample_rate、vocabulary_id 可直接傳入。透過 parameters 字典傳入 max_sentence_silence 和 language_hints。

參數類型是否必須說明
modelstr

是

模型名稱。
sample_rateint

是

採樣率(Hz)。

取值範圍:8k模型僅支援 8000 Hz,其他模型支援任意採樣率。

formatstr

是

音頻格式。

取值範圍:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

重要opus/speex:必須使用Ogg封裝;

wav:必須為PCM編碼;

amr:僅支援AMR-NB類型。

vocabulary_idstr

否

先行編譯熱詞列表 ID。

需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。

適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。

使用方法請參見先行編譯熱詞。

max_sentence_silenceint

否

VAD 斷句靜音閾值(ms)。當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。

預設值:1300。

取值範圍:[200, 6000]。

multi_threshold_mode_enabledbool

否

是否啟用多閾值模式。啟用後可防止 VAD 斷句切割過長。

預設值:False。

punctuation_prediction_enabledbool

否

設定是否在識別結果中自動添加標點:

  • True(預設):是,不支援修改。
heartbeatbool

否

是否啟用心跳包。

預設值:False。

  • True:在持續發送靜音音訊情況下,可保持與服務端的串連不中斷。
  • False(預設):即使持續發送靜音音頻,串連也將在一定時間後因逾時而斷開。

靜音音頻指的是在音頻檔案或資料流中沒有聲音訊號的內容。靜音音頻可以通過多種方法產生,例如使用音頻編輯軟體如Audacity或Adobe Audition,或者通過命令列工具如FFmpeg。

使用該欄位時,SDK版本不能低於2.0.1。

language_hintslist[str]

否

待識別音頻語種。無預設值,不設定時模型自動識別。

僅支援設定 1 個值,設定多個時僅第一個生效。

點擊查看支援的語言代碼

  • fun-asr-realtime:

    • 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:斯洛伐克語
  • fun-asr-realtime-2026-02-28:

    • zh: 中文
    • en: 英文
    • ja: 日語
  • fun-asr-flash-8k-realtime、fun-asr-flash-8k-realtime-2026-01-28:

    • zh: 中文
speech_noise_thresholdfloat

否

語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。

取值範圍:[-1.0, 1.0]。

取值說明:

  • 取值越接近 -1:降低噪音判定閾值,噪音被識別為語音的機率增大,可能導致更多噪音被轉寫
  • 取值越接近 +1:提高噪音判定閾值,語音被誤判為噪音的機率增大,可能導致部分語音被過濾

此參數為進階配置參數,調整可能顯著影響識別效果,建議:

  • 調整前充分測實驗證效果
  • 根據實際音頻環境小幅度調整(建議步長 0.1)
special_word_filterstr

否

指定在語音辨識過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。

使用 recognize 建立辨識工作階段時,透過 input 傳入上下文。

參數類型是否必須說明
inputdict

否

輸入對象,用於傳入對話上下文(context)。上下文用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見提升識別準確率。

重要僅 fun-asr-realtime 模型支援 context 參數。

dict 中需包含 context 鍵,值為訊息列表(list[dict]),每條訊息包含以下欄位:

  • role(str,必選):訊息角色。user 表示前幾輪使用者語音的識別結果或領域相關的詞表;assistant 表示前幾輪大語言模型的回複內容。
  • content(list[dict],必選):訊息內容列表。每個元素包含 type(str,role 為 user 時填 input_text,role 為 assistant 時填 text)和 text(str,常值內容)。

重要約束:上下文訊息(input_text 和 text 類型)各最多 5 條,超出時保留最近的 5 條。每輪上下文文本總長度不超過 400 個字元,超出部分從末尾截斷。

重要攜帶上下文時,context 中的訊息順序有要求:上下文訊息必須按對話輪次排列,每輪中 user(input_text 類型)必須在對應的 assistant(text 類型)之前。

說明使用該欄位時,SDK版本不能低於2.0.1。

input通過recognize方法傳入:

# 構建 input 傳入資料
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "你好啊"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "你好啊,我是通義千問,有什麼可以協助你的?"
                }
            ]
        }
    ]
}

# 建立識別會話時通過 input 參數傳入
recognition = client.audio.asr.recognize(
    model='fun-asr-realtime',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

介面參考

共用介面

事件迭代(events()/results())

雙向流式調用時,服務端會通過事件的方式,將關鍵流程資訊和資料返回給用戶端。您需要在接收線程中迭代會話的events()(原始事件dict)或results()(類型化識別結果幀),處理服務端返回的資訊或者資料。

# 迭代原始事件:識別文本位於 payload.output.sentence
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('識別文本:', sentence['text'])


# 或只迭代識別結果幀(返回 RecognitionResult,心跳幀已過濾)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('識別文本:', sentence['text'])
事件/迭代方法產出內容傳回值描述
event["header"]["event"] == "task-started"

task-started事件

無

由start()內部讀取,啟動返回時保存在last_response中,不會由events()再次產出。

def events(self) -> Iterator[Dict]

event:服務端事件dict

迭代器

當服務有回複時產出事件。識別結果位於payload.output.sentence,可能為心跳或空文本事件,應用可按需忽略。請由一個接收線程持續消費,不要並發建立多個讀取者。

def results(self) -> Iterator[RecognitionResult]

result:識別結果(RecognitionResult)

迭代器

只產出識別結果幀(心跳幀已過濾),全部識別結果返回後迭代結束。

try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)

DashScopeError異常

無

發生異常時在發送/接收線程中拋出,可使用try/except捕獲。

event["header"]["event"] == "task-finished"

task-finished事件

無

當服務已經完成全部識別後由events()產出,隨後迭代結束;發送stop()後仍須讀取此事件。

識別結果(RecognitionResult)

RecognitionResult代表會話results()迭代產出的一次識別結果幀(雙向流式調用與非流式調用均可使用;events()產出的是原始事件dict,如需該類型化視圖請改用results())。

成員方法方法簽名說明
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

擷取當前識別的句子及時間戳記資訊,此方法傳回型別為Dict[str, Any](單句資訊)。

詳情請參見單句資訊(Sentence)。

request_id
result.request_id

當前事件對應的請求request_id。

is_sentence_end
def is_sentence_end(self) -> bool

判斷當前句子是否已經結束。該方法通過檢查 get_sentence() 返回的單句資訊中 end_time 欄位是否為 None 來判定——end_time 不為 None 時表示句子已結束。

單句資訊(Sentence)

Sentence類成員如下:

參數類型說明
begin_timeint句子開始時間,單位為ms。
end_timeint句子結束時間,單位為ms。
textstr識別文本。
words字時間戳記資訊(Word)的list集合字時間戳記資訊。

字時間戳記資訊(Word)

Word類成員如下:

參數類型說明
begin_timeint字開始時間,單位為ms。
end_timeint字結束時間,單位為ms。
textstr字。
punctuationstr標點。

Qwen-Audio-ASR-Streaming / Qwen-Audio-ASR-Message

介面地址

SDK的即時識別走WebSocket介面,端點由Client的workspace與region自動決定(包含WorkspaceId)。如需切換到其他地區,構造Client時設定對應地區的region即可。

新加坡

wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference

調用時請將{WorkspaceId}替換為真實的Workspace ID。

華北2(北京)

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference

調用時請將{WorkspaceId}替換為真實的Workspace ID。

重要阿里雲百鍊為華北2(北京)、新加坡地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:

  • 華北2(北京)地區:從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區:從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Qwen-Audio-ASR-Streaming

關鍵介面

核心資源(client.audio.asr)

即時語音辨識能力掛載在client.audio.asr資源上:recognize建立雙向流式識別會話(Recognition),recognize_file對本地檔案一次性識別。

成員方法方法簽名說明

recognize

def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition

建立雙向流式識別會話,進入with上下文時自動調用start建立串連並發送任務。

發送音頻與消費事件需並發進行(配合send_audio_frame、events()/results()和stop使用)。

recognize_file

def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]

基於本地檔案的非流式調用:自動分塊發送音頻並驅動到任務結束,逐個產出服務端事件。該方法要求所識別檔案具有可讀許可權。

start
def start(self)

開始語音辨識:建立串連、發送任務並等待task-started。進入with上下文時自動調用,啟動成功後才能發送音頻。

send_audio_frame
def send_audio_frame(self, buffer: bytes)

推送音頻。每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。

識別結果通過事件迭代(events()/results())擷取。

stop
def stop(self)

停止語音辨識:只通知服務端輸入結束,接收線程需繼續消費events()直到task-finished事件。

events / results

def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]

迭代服務端事件:events()產出原始事件dict(識別文本位於payload.output.sentence);results()只產出識別結果幀,返回識別結果(RecognitionResult)類型化對象(心跳幀已過濾)。

close

def close(self)

關閉識別會話。退出with上下文時自動調用。

request_id / first_package_delay / last_package_delay / last_response

rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.last_response

擷取request_id、首包延遲(從發送第一包音頻到收到首包識別結果延遲)和尾包延遲(發送stop指令到最後一包識別結果下發耗時),在任務完成後使用;last_response為最近一次成功讀取的原始報文,可用於擷取task-failed報錯。會話關閉後仍可讀取。

響應結果

Qwen-Audio-ASR-Message

關鍵介面

核心資源(client.audio.asr)

即時語音辨識能力掛載在client.audio.asr資源上:recognize建立雙向流式識別會話(Recognition),recognize_file對本地檔案一次性識別。

成員方法方法簽名說明
recognize
def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition

建立雙向流式識別會話,進入with上下文時自動調用start建立串連並發送任務。

發送音頻與消費事件需並發進行(配合send_audio_frame、events()/results()和stop使用)。

recognize_file
def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]

基於本地檔案的非流式調用:自動分塊發送音頻並驅動到任務結束,逐個產出服務端事件。該方法要求所識別檔案具有可讀許可權。

start
def start(self)

開始語音辨識:建立串連、發送任務並等待task-started。進入with上下文時自動調用,啟動成功後才能發送音頻。

send_audio_frame
def send_audio_frame(self, buffer: bytes)

推送音頻。每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。

識別結果通過事件迭代(events()/results())擷取。

stop
def stop(self)

停止語音辨識:只通知服務端輸入結束,接收線程需繼續消費events()直到task-finished事件。

events / results
def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]

迭代服務端事件:events()產出原始事件dict(識別文本位於payload.output.sentence);results()只產出識別結果幀,返回識別結果(RecognitionResult)類型化對象(心跳幀已過濾)。

close
def close(self)

關閉識別會話。退出with上下文時自動調用。

request_id / first_package_delay / last_package_delay / last_response
rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.last_response

擷取request_id、首包延遲(從發送第一包音頻到收到首包識別結果延遲)和尾包延遲(發送stop指令到最後一包識別結果下發耗時),在任務完成後使用;last_response為最近一次成功讀取的原始報文,可用於擷取task-failed報錯。會話關閉後仍可讀取。

響應結果

Fun-ASR-Realtime

介面地址

SDK的即時識別走WebSocket介面,端點由Client的workspace與region自動決定(包含WorkspaceId)。如需切換到其他地區,構造Client時設定對應地區的region即可。

新加坡

wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference

調用時請將{WorkspaceId}替換為真實的Workspace ID。

華北2(北京)

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference

調用時請將{WorkspaceId}替換為真實的Workspace ID。

重要阿里雲百鍊為華北2(北京)、新加坡地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:

  • 華北2(北京)地區:從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區:從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

關鍵介面

核心資源(client.audio.asr)

即時語音辨識能力掛載在client.audio.asr資源上:recognize建立雙向流式識別會話(Recognition),recognize_file對本地檔案一次性識別。

成員方法方法簽名說明

recognize

def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition

建立雙向流式識別會話,進入with上下文時自動調用start建立串連並發送任務。

發送音頻與消費事件需並發進行(配合send_audio_frame、events()/results()和stop使用)。

recognize_file

def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]

基於本地檔案的非流式調用:自動分塊發送音頻並驅動到任務結束,逐個產出服務端事件。該方法要求所識別檔案具有可讀許可權。

start

def start(self)

開始語音辨識:建立串連、發送任務並等待task-started。進入with上下文時自動調用,啟動成功後才能發送音頻。

send_audio_frame

def send_audio_frame(self, buffer: bytes)

推送音頻。每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。

識別結果通過events()/results()迭代擷取。

stop

def stop(self)

停止語音辨識:只通知服務端輸入結束,接收線程需繼續消費events()直到task-finished事件。

events / results

def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]

迭代服務端事件:events()產出原始事件dict(識別文本位於payload.output.sentence);results()只產出識別結果幀,返回識別結果(RecognitionResult)類型化對象(心跳幀已過濾)。

close

def close(self)

關閉識別會話。退出with上下文時自動調用。

request_id / first_package_delay / last_package_delay / last_response

rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.last_response

擷取request_id、首包延遲(從發送第一包音頻到收到首包識別結果延遲)和尾包延遲(發送stop指令到最後一包識別結果下發耗時),在任務完成後使用;last_response為最近一次成功讀取的原始報文,可用於擷取task-failed報錯。會話關閉後仍可讀取。

響應結果

錯誤碼

如遇報錯問題,請參見錯誤碼進行排查。

若問題仍未解決,請加入開發人員群反饋遇到的問題,並提供Request ID,以便進一步排查問題。