本文檔介紹如何使用 DashScope Python SDK 調用即時語音辨識(Qwen-ASR-Realtime)模型。
重要阿里雲百鍊為華北2(北京)、新加坡地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
- 華北2(北京)地區:從
dashscope.aliyuncs.com遷移至{WorkspaceId}.cn-beijing.maas.aliyuncs.com - 新加坡地區:從
dashscope-intl.aliyuncs.com遷移至{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。
前提條件
- 安裝SDK,確保DashScope SDK版本不低於2.0.1。
- 擷取API Key。
- 瞭解WebSocket API。
快速開始
說明範例程式碼讀取 your_audio_file.pcm(PCM16、16 kHz、單聲道)。如僅有 MP3/WAV 等格式,可使用 ffmpeg 轉換:
ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm
import logging
import os
import signal
import sys
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",
)
def setup_logging():
"""配置日誌輸出"""
logger = logging.getLogger('dashscope')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(sys.stdout)
handler.setLevel(logging.DEBUG)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.propagate = False
return logger
def handle_event(event):
"""處理單個服務端事件"""
kind = event.get('type')
if kind == 'session.created':
print(f"Start session: {event['session']['id']}")
elif kind == 'conversation.item.input_audio_transcription.completed':
print(f"Final recognized text: {event['transcript']}")
elif kind == 'conversation.item.input_audio_transcription.text':
print(f"Got transcription result: {event['text'] + event['stash']}")
elif kind == 'input_audio_buffer.speech_started':
print('======Speech Start======')
elif kind == 'input_audio_buffer.speech_stopped':
print('======Speech Stop======')
def receive_events(session):
"""接收並處理服務端事件"""
for event in session.events():
handle_event(event)
def read_audio_chunks(file_path, chunk_size=3200):
"""按塊讀取音頻檔案"""
with open(file_path, 'rb') as f:
while chunk := f.read(chunk_size):
yield chunk
def send_audio(session, file_path, delay=0.1):
"""發送音頻資料"""
if not os.path.exists(file_path):
raise FileNotFoundError(f"Audio file {file_path} does not exist.")
print("Processing audio file... Press 'Ctrl+C' to stop.")
for chunk in read_audio_chunks(file_path):
session.append_audio(chunk) # bytes 發送前會自動進行 Base64 編碼
time.sleep(delay)
def main():
setup_logging()
audio_file_path = "./your_audio_file.pcm"
# 進入 with 上下文時自動建立串連
with client.audio.realtime.connect(
model='qwen3-asr-flash-realtime',
) as session:
def handle_exit(sig, frame):
print('Ctrl+C pressed, exiting...')
session.close()
sys.exit(0)
signal.signal(signal.SIGINT, handle_exit)
# 更新會話配置:僅文本輸出,並開啟輸入音頻轉寫
session.update_session(
output_modalities=['text'],
enable_input_audio_transcription=True,
transcription_params={
'language': 'zh',
'sample_rate': 16000,
'input_audio_format': 'pcm',
},
)
# 讀取直到 session.updated,確認配置已生效
for event in session.events():
if event.get('type') == 'session.updated':
break
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, session)
try:
send_audio(session, audio_file_path)
# send session.finish and wait for finished and close
session.end_session()
receiver.result()
finally:
# close must run inside the pool context to unblock the receiver
session.close()
print("Audio processing completed.")
if __name__ == '__main__':
main()
請求參數
-
以下參數通過
client.audio.realtime.connect方法設定。點擊查看範例程式碼
# 新加坡和北京地區的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", ) # 建立即時識別會話:進入 with 上下文時自動建立串連 session = client.audio.realtime.connect( model='qwen3-asr-flash-realtime', )參數
類型
是否必須
說明
modelstr是
指定要使用的模型名稱。
ws_urlstr否
完整WebSocket端點,未指定時按
Client的workspace與region自動選擇端點:華北2(北京)地區:
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime。調用時請將{WorkspaceId}替換為真實的Workspace ID。新加坡地區:
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime。調用時請將{WorkspaceId}替換為真實的業務空間ID。
-
以下參數通過
RealtimeSession的update_session方法設定。點擊查看範例程式碼
session.update_session( output_modalities=['text'], enable_turn_detection=True, turn_detection_type="server_vad", turn_detection_threshold=0.0, turn_detection_silence_duration_ms=400, enable_input_audio_transcription=True, transcription_params={ 'language': 'zh', 'sample_rate': 16000, 'input_audio_format': 'pcm', }, )參數
類型
是否必須
說明
output_modalitiesList[str]是
模型輸出模態,固定為
["text"]。enable_turn_detectionbool否
是否開啟服務端語音活動檢測(VAD)。關閉後,需手動調用
commit()方法觸發識別。預設值:
True。取值範圍:
True:開啟False:關閉
turn_detection_typestr否
服務端VAD類型,固定為
server_vad。turn_detection_thresholdfloat否
VAD檢測閾值。推薦將該值設為
0.0。預設值:
0.2。取值範圍:
[-1, 1]。較低的閾值會提高 VAD 的靈敏度,可能將背景雜音誤判為語音。較高的閾值則降低靈敏度,有助於在嘈雜環境中減少誤觸發。
turn_detection_silence_duration_msint否
VAD斷句檢測閾值(ms)。靜音持續時間長度超過該閾值將被認為是語句結束。推薦將該值設為
400。預設值:
800。取值範圍:
[200, 6000]。較低的值(如 300ms)可使模型更快響應,但可能導致在自然停頓處發生不合理的斷句。較高的值(如 1200ms)可更好地處理長句內的停頓,但會增加整體響應延遲。
transcription_paramsdict否
語音辨識相關配置。
-
以下參數通過
update_session的transcription_params字典設定。點擊查看範例程式碼
session.update_session( output_modalities=['text'], enable_input_audio_transcription=True, transcription_params={ 'language': 'zh', 'sample_rate': 16000, 'input_audio_format': 'pcm', }, )參數
類型
是否必須
說明
languagestr否
音頻源語言。
zh:中文(普通話、四川話、閩南語、吳語)
yue:粵語
en:英文
ja:日語
de:德語
ko:韓語
ru:俄語
fr:法語
pt:葡萄牙語
ar:阿拉伯語
it:意大利語
es:西班牙語
hi:印地語
id:印尼語
th:泰語
tr:土耳其語
uk:烏克蘭語
vi:越南語
cs:捷克語
da:丹麥語
fil:菲律賓語
fi:芬蘭語
is:冰島語
ms:馬來語
no:挪威語
pl:波蘭語
sv:瑞典語
sample_rateint否
音頻採樣率(Hz)。支援
16000和8000。預設值:
16000。設定為
8000時,服務端會先升採樣到16000Hz再進行識別,可能引入微小延遲。建議僅在源音頻為8000Hz(如電話線路)時使用。input_audio_formatstr否
音頻格式。支援
pcm和opus。預設值:
pcm。
介面參考
RealtimeSession(client.audio.realtime.connect)
即時識別會話通過client.audio.realtime.connect(model=...)建立:進入with上下文(或調用會話的connect()方法)後建立串連。
| 方法簽名 | 服務端響應事件(通過events()下發) | 說明 |
|---|---|---|
|
| 和服務端建立串連。進入 |
|
| 用於更新會話配置,建議在串連建立後首先調用該方法進行設定。若未調用該方法,系統將使用預設配置。只需關注請求參數中的涉及到的參數。 |
| 無 | 將音頻資料片段追加到雲端輸入音頻緩衝區。 |
|
| 提交之前通過append添加到雲端緩衝區的音視頻,如果輸入的音頻緩衝區為空白將產生錯誤。 禁用情境:請求參數 |
|
| 通知服務端結束會話,服務端收到會話結束通知後將完成最後的語音辨識。 調用時機:
|
| 無 | 終止任務,並關閉串連(冪等,不發送 |
| 無 | 擷取當前任務的session_id、最近一次response的response_id(屬性)。 |
事件迭代(events())
服務端會通過事件的方式,將服務端響應事件和資料返回給用戶端。您需要在接收線程中迭代會話的events(),按event["type"]分發處理(完整事件列表參見服務端事件)。
def receive_events(session):
for event in session.events():
kind = event.get('type')
if kind == 'session.created':
print(f"Start session: {event['session']['id']}")
elif kind == 'conversation.item.input_audio_transcription.completed':
print(f"Final recognized text: {event['transcript']}")
elif kind == 'conversation.item.input_audio_transcription.text':
print(f"Got transcription result: {event['text'] + event['stash']}")
| 方法簽名 | 參數 | 說明 |
|---|---|---|
| event:服務端事件 | 連續讀取並逐個產出服務端事件( |
| 無 | 阻塞讀取單條服務端事件,不自動迴圈;無事件(串連關閉)時返回 |