本文介紹 DashScope Python SDK 調用 Qwen-TTS-Realtime 系列模型時的關鍵介面與請求參數。
前期準備
DashScope Python SDK 版本需要不低於2.0.1。
快速開始
import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor
import dashscope
text_to_synthesize = [
'對吧~我就特別喜歡這種超市,',
'尤其是過年的時候',
'去逛超市',
'就會覺得',
'超級超級開心!',
'想買好多好多的東西呢!'
]
# 新加坡地區和北京地區的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.getenv("DASHSCOPE_API_KEY"),
# 以下為新加坡(ap-southeast-1)地區的配置。調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區配置不同。
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# 接收線程:迭代服務端事件,將音頻增量寫入檔案
def receive_events(session):
with open('result_24k.pcm', 'wb') as f:
for event in session.events():
event_type = event.get('type')
if event_type == 'session.created':
print('start session: {}'.format(event['session']['id']))
elif event_type == 'response.audio.delta':
f.write(base64.b64decode(event['delta']))
elif event_type == 'response.done':
print(f'response {session.last_response_id} done')
elif event_type == 'session.finished':
print('session finished')
if __name__ == '__main__':
print('Initializing ...')
# 建立即時語音合成會話:進入with上下文時自動建立串連
with client.audio.realtime.connect(
model='qwen3-tts-flash-realtime',
) as session:
session.update_session(
output_modalities=['audio'],
voice='Cherry',
response_format='pcm',
sample_rate=24000,
mode='server_commit'
)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, session)
for text_chunk in text_to_synthesize:
print(f'send text: {text_chunk}')
session.send_event({'type': 'input_text_buffer.append', 'text': text_chunk})
time.sleep(0.1)
# 通知服務端輸入完成(server_commit模式下由服務端決定合成時機)
session.end_session()
receiver.result()
print('[Metric] session: {}, first audio delay: {}'.format(
session.session_id,
session.last_first_audio_delay,
))
import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor
import dashscope
text_to_synthesize = [
'這是第一句話。',
'這是第二句話。',
'這是第三句話。',
]
# 新加坡地區和北京地區的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.getenv("DASHSCOPE_API_KEY"),
# 以下為新加坡(ap-southeast-1)地區的配置。調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區配置不同。
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# 接收線程:迭代服務端事件,將音頻增量寫入檔案
def receive_events(session):
with open('result_24k.pcm', 'wb') as f:
for event in session.events():
event_type = event.get('type')
if event_type == 'session.created':
print('start session: {}'.format(event['session']['id']))
elif event_type == 'response.audio.delta':
f.write(base64.b64decode(event['delta']))
elif event_type == 'response.done':
print(f'response {session.last_response_id} done')
elif event_type == 'session.finished':
print('session finished')
if __name__ == '__main__':
print('Initializing ...')
# 建立即時語音合成會話:進入with上下文時自動建立串連
with client.audio.realtime.connect(
model='qwen3-tts-flash-realtime',
) as session:
session.update_session(
output_modalities=['audio'],
voice='Cherry',
response_format='pcm',
sample_rate=24000,
mode='commit'
)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, session)
for text in text_to_synthesize:
print(f'send text: {text}')
session.send_event({'type': 'input_text_buffer.append', 'text': text})
# commit模式下由用戶端觸發合成
session.send_event({'type': 'input_text_buffer.commit'})
time.sleep(0.1)
session.end_session()
receiver.result()
print('[Metric] session: {}, first audio delay: {}'.format(
session.session_id,
session.last_first_audio_delay,
))
訪問github下載更多範例程式碼。
請求參數
下述請求參數可以通過client.audio.realtime的connect方法設定。
參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | str | 是 | 模型名稱。參見支援的模型。 |
ws_url | str | 否 | 會話端點。缺省時由Client構造參數 |
下述請求參數可以通過會話的update_session方法配置(具名參數直接傳入,其餘參數透傳至session.update事件的session對象)。
參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
voice | str | 是 | 語音合成所使用的音色。參見Qwen-TTS音色列表。 |
language_type | str | 否 | 指定合成音訊語種,預設為
|
mode | str | 否 | 互動模式,可選值:
|
response_format | str | 否 | 模型輸出音訊格式。 支援的格式:
|
sample_rate | int | 否 | 模型輸出音訊採樣率(Hz)。 支援的採樣率:
|
speech_rate | float | 否 | 音訊語速。1.0為正常語速,小於1.0為慢速,大於1.0為快速。 預設值:1.0。 取值範圍:[0.5, 2.0]。 |
volume | int | 否 | 音訊音量。 取值範圍:[0, 100]。 |
pitch_rate | float | 否 | 合成音訊語調。 預設值:1.0。 取值範圍:[0.5, 2.0]。 |
bit_rate | int | 否 |
關鍵介面
會話(RealtimeSession)
即時語音合成會話通過client.audio.realtime.connect(model=...)建立,進入with上下文時自動建立串連(也可調用會話的connect()方法手動建立)。
方法簽名 | 服務端響應事件(通過 | 說明 |
|---|---|---|
|
| 和服務端建立串連。進入 |
|
| 更新本次會話互動的預設配置。參數配置請參考《請求參數》章節。 在您建立連結,服務端會及時返回用於此會話的預設輸出輸入配置。如果您需要更新預設會話配置,我們也推薦您總是在建立連結後即刻調用此介面。 服務端在收到session.update事件後,會進行參數校正,如果參數不合法則返回錯誤,否則更新服務端側的會話配置。 |
| 無 | 發送原始事件。文本輸入通過
|
|
| 發送 |
|
| 發送
|
|
| 發送session.finish事件,終止任務。之後繼續消費 |
| 無 | 關閉串連。退出 |
| 無 | 擷取當前任務的session_id。 |
| 無 | 擷取最近一次response的response_id。 |
| 無 | 擷取首包音頻延遲。 |
事件迭代(events())
服務端會通過事件的方式,將服務端響應事件和資料返回給用戶端。在接收線程中迭代會話的events()處理服務端事件,session.finished事件後迭代結束;error事件會以DashScopeError異常拋出,可使用try/except捕獲。
方法 | 參數 | 傳回值 | 描述 |
|---|---|---|---|
| event:服務端響應事件( | 迭代器 | 包括對介面調用的回複響應和模型產生的文本和音頻, |
| event:服務端響應事件( | 事件或 | 讀取一條服務端事件,正常關閉後返回 |