Skip to main content

Qwen-Audio-Realtime Node.js SDK

通過語音 Node.js SDK 調用 Qwen-Audio-Realtime,配置會話、收發音頻、處理轉寫和工具調用。

前提條件

在控制台獲取 API Key,並配置為環境變量 DASHSCOPE_API_KEY。

安裝 SDK

需要 Node.js 18 或以上版本。下載 SDK 0.1.0 安裝包後,在項目目錄運行:
npm install ./dashscope-sdk-nodejs-0.1.0.tgz

快速開始

下載示例音頻,保存為 input.mp3,並轉換為 16 kHz、16-bit、單聲道 PCM:
ffmpeg -i input.mp3 -f s16le -ac 1 -ar 16000 input.pcm
將以下示例保存為 example.mjs,運行 node example.mjs。
import { readFileSync, writeFileSync } from 'node:fs'
import { setTimeout as sleep } from 'node:timers/promises'
import { RealtimeClient } from 'dashscope-sdk-nodejs/realtime'

const pcm = readFileSync('input.pcm')
const client = new RealtimeClient({
  apiKey: process.env.DASHSCOPE_API_KEY,
  workspaceId: process.env.DASHSCOPE_WORKSPACE_ID,
  baseUrl: 'dashscope-intl.aliyuncs.com',
  model: 'qwen-audio-3.1-realtime-plus',
  voice: 'longanqian_v3.1',
  turnDetection: null,
  inputTranscription: { language: 'zh' },
})
const audio = []
function fail(err) {
  console.error(err.code, err.message)
  process.exitCode = 1
  client.close()
}
const timer = setTimeout(() => fail(new Error('Response timed out')), 60000)
client.on('close', () => clearTimeout(timer))
client.on('error', fail)
client.on('audio', chunk => audio.push(chunk))
client.on('inputTranscript', ({ transcript }) => console.log('User:', transcript))
client.on('outputTranscript', ({ transcript }) => console.log('Assistant:', transcript))
client.once('sessionUpdated', () => {
  ;(async () => {
    for (let offset = 0; offset < pcm.length; offset += 3200) {
      client.appendAudio(pcm.subarray(offset, offset + 3200))
      await sleep(100)
    }
    client.commit()
    client.createResponse()
  })().catch(fail)
})
client.once('responseDone', event => {
  if (event.response?.status !== 'completed') {
    fail(new Error('Response status: ' + event.response?.status))
    return
  }
  writeFileSync('output.pcm', Buffer.concat(audio))
  client.close()
})
try {
  await client.connect()
} catch (err) {
  fail(err)
}

請求參數

RealtimeClient 的構造參數如下。
參數類型必填說明
apiKeystring否API Key。默認讀取 DASHSCOPE_API_KEY。
workspaceIdstring否業務空間 ID。默認讀取 DASHSCOPE_WORKSPACE_ID。
baseUrlstring否服務域名,設置為 dashscope-intl.aliyuncs.com(新加坡)。
modelstring是模型 ID。
voicestring否音色 ID。省略時使用服務端默認音色。
instructionsstring否系統指令,設置角色、風格等。
turnDetectionTurnDetection | null否默認 { type: "server_vad" };null 表示手動提交;可使用 smart_turn 或 smart_turn_v2。
modalitiesArray<'text' | 'audio'>否輸出模態,默認 ["text", "audio"]。
maxHistoryTurnsnumber否歷史輪數,範圍 [1,50],服務端默認 20。
toolsToolDefinition[]否工具定義;應用執行工具並校驗參數。
inputTranscription{ model?: string; language?: string } | null否輸入音頻轉寫配置,如 { model: "fun-asr", language: "zh" };null 關閉轉寫。
sessionExtrasSessionConfig否擴展會話參數,如 speech_rate、enable_search;覆蓋對應的頂層配置,字段見客戶端事件。
connectTimeoutMsnumber否建連超時(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) 註冊回調;完整事件字段見服務端事件。
事件負載說明
openvoid連接已建立、初始配置已發送。
sessionCreated / sessionUpdatedServerEvent會話創建或配置確認。
audioBuffer音頻二進制塊,可多次觸發。
audioTranscriptDelta{ delta: string }輸出音頻轉寫的增量文本。
outputTranscript{ transcript: string }輸出音頻的完整轉寫。
textDelta / textDone{ delta: string } / { text: string }純文本模態的增量或完整文本。
inputTranscriptDelta{ text: string; stash: string }text 是確定文本,stash 是暫存文本;以二者替換當前顯示,而非累計拼接。
inputTranscript{ transcript: string }輸入音頻的最終轉寫。
speechStarted / speechStoppedServerEvent檢測到用戶語音開始或停止。
responseCreated / responseDoneServerEvent響應開始或結束。檢查 responseDone.response.status 是否為 completed,或為取消、失敗狀態。
functionCall{ callId: string; name: string; arguments: string }完整工具調用參數;由應用解析並校驗 arguments JSON 字符串。
ambientTranscript / ambientTranscriptCompleted{ text: string; stash: string } / { transcript: string }環境音當前或最終轉寫,不寫入會話上下文。
eventServerEvent原始服務端 JSON 消息。
errorDashScopeError連接或服務端錯誤。
close{ code: number; reason: string }底層連接關閉通知。