通過語音 Node.js SDK 調用 Qwen-Audio-Realtime,配置會話、收發音頻、處理轉寫和工具調用。
前提條件
在控制台獲取 API Key,並配置為環境變量 DASHSCOPE_API_KEY。
安裝 SDK
需要 Node.js 18 或以上版本。下載 SDK 0.1.0 安裝包後,在項目目錄運行:
快速開始
下載示例音頻,保存為 input.mp3,並轉換為 16 kHz、16-bit、單聲道 PCM:
example.mjs,運行 node example.mjs。
請求參數
RealtimeClient 的構造參數如下。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
apiKey | string | 否 | API Key。默認讀取 DASHSCOPE_API_KEY。 |
workspaceId | string | 否 | 業務空間 ID。默認讀取 DASHSCOPE_WORKSPACE_ID。 |
baseUrl | string | 否 | 服務域名,設置為 dashscope-intl.aliyuncs.com(新加坡)。 |
model | string | 是 | 模型 ID。 |
voice | string | 否 | 音色 ID。省略時使用服務端默認音色。 |
instructions | string | 否 | 系統指令,設置角色、風格等。 |
turnDetection | TurnDetection | null | 否 | 默認 { type: "server_vad" };null 表示手動提交;可使用 smart_turn 或 smart_turn_v2。 |
modalities | Array<'text' | 'audio'> | 否 | 輸出模態,默認 ["text", "audio"]。 |
maxHistoryTurns | number | 否 | 歷史輪數,範圍 [1,50],服務端默認 20。 |
tools | ToolDefinition[] | 否 | 工具定義;應用執行工具並校驗參數。 |
inputTranscription | { model?: string; language?: string } | null | 否 | 輸入音頻轉寫配置,如 { model: "fun-asr", language: "zh" };null 關閉轉寫。 |
sessionExtras | SessionConfig | 否 | 擴展會話參數,如 speech_rate、enable_search;覆蓋對應的頂層配置,字段見客戶端事件。 |
connectTimeoutMs | number | 否 | 建連超時(ms),默認 10000。 |
介面參考
主要方法
| 方法 | 返回值 | 說明 |
|---|---|---|
connect() | Promise<void> | 建立連接併發送會話配置,通過 sessionUpdated 確認配置生效。 |
updateSession(session: SessionConfig) | void | 更新會話參數,通過 sessionUpdated 確認生效。 |
appendAudio(pcm: Buffer | Uint8Array) | void | 發送 16 kHz、16-bit、單聲道 PCM 音頻。 |
commit() | void | 手動模式下提交音頻緩衝區。 |
clearAudioBuffer() | void | 清空尚未提交的音頻緩衝區。 |
createResponse(response?: Record<string, unknown>) | void | 請求模型生成響應。 |
cancelResponse() | void | 取消當前響應,保留會話。 |
createConversationItem(item: ConversationItem, previousItemId?: string) | void | 添加對話歷史或工具結果;previousItemId 指定插入位置。 |
submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean) | void | 提交工具結果字符串;autoCreateResponse 默認 true,自動請求後續響應。 |
deleteConversationItem(itemId: string) | void | 刪除指定對話項。 |
retrieveConversationItem(itemId: string) | void | 查詢對話項,結果通過 event 回調返回。 |
sendEvent(event: ClientEvent) | void | 發送原始客戶端事件。 |
close(code?: number, reason?: string) | void | 關閉會話和 WebSocket 連接。 |
回調事件
通過 on(event, listener) 註冊回調;完整事件字段見服務端事件。
| 事件 | 負載 | 說明 |
|---|---|---|
open | void | 連接已建立、初始配置已發送。 |
sessionCreated / sessionUpdated | ServerEvent | 會話創建或配置確認。 |
audio | Buffer | 音頻二進制塊,可多次觸發。 |
audioTranscriptDelta | { delta: string } | 輸出音頻轉寫的增量文本。 |
outputTranscript | { transcript: string } | 輸出音頻的完整轉寫。 |
textDelta / textDone | { delta: string } / { text: string } | 純文本模態的增量或完整文本。 |
inputTranscriptDelta | { text: string; stash: string } | text 是確定文本,stash 是暫存文本;以二者替換當前顯示,而非累計拼接。 |
inputTranscript | { transcript: string } | 輸入音頻的最終轉寫。 |
speechStarted / speechStopped | ServerEvent | 檢測到用戶語音開始或停止。 |
responseCreated / responseDone | ServerEvent | 響應開始或結束。檢查 responseDone.response.status 是否為 completed,或為取消、失敗狀態。 |
functionCall | { callId: string; name: string; arguments: string } | 完整工具調用參數;由應用解析並校驗 arguments JSON 字符串。 |
ambientTranscript / ambientTranscriptCompleted | { text: string; stash: string } / { transcript: string } | 環境音當前或最終轉寫,不寫入會話上下文。 |
event | ServerEvent | 原始服務端 JSON 消息。 |
error | DashScopeError | 連接或服務端錯誤。 |
close | { code: number; reason: string } | 底層連接關閉通知。 |