Skip to main content

Qwen-Audio-Realtime Node.js SDK

Gunakan SDK Node.js suara untuk mengonfigurasi sesi Qwen-Audio-Realtime, bertukar audio, serta menangani transkripsi dan pemanggilan fungsi.

Prasyarat

Dapatkan API key di konsol dan atur sebagai variabel lingkungan DASHSCOPE_API_KEY.

Instal SDK

Memerlukan Node.js 18 atau lebih baru. Unduh paket SDK 0.1.0, lalu jalankan perintah ini di proyek:
npm install ./dashscope-sdk-nodejs-0.1.0.tgz

Mulai cepat

Unduh audio contoh sebagai input.mp3 dan konversi ke PCM mono 16 kHz, 16-bit:
ffmpeg -i input.mp3 -f s16le -ac 1 -ar 16000 input.pcm
Simpan contoh berikut sebagai example.mjs dan jalankan 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)
}

Parameter permintaan

Opsi konstruktor RealtimeClient:
ParameterTipeWajibDeskripsi
apiKeystringTidakAPI key. Default membaca DASHSCOPE_API_KEY.
workspaceIdstringTidakID ruang kerja. Default membaca DASHSCOPE_WORKSPACE_ID.
baseUrlstringTidakAtur nama host layanan ke dashscope-intl.aliyuncs.com (Singapura).
modelstringYaID model.
voicestringTidakID suara. Menggunakan suara default layanan jika diabaikan.
instructionsstringTidakInstruksi sistem untuk peran, gaya, dan perilaku lainnya.
turnDetectionTurnDetection | nullTidakDefault: { type: "server_vad" }. null mengaktifkan pengiriman manual. Juga mendukung smart_turn dan smart_turn_v2.
modalitiesArray<'text' | 'audio'>TidakModalitas keluaran. Default: ["text", "audio"].
maxHistoryTurnsnumberTidakJumlah giliran riwayat: [1,50]. Default layanan: 20.
toolsToolDefinition[]TidakDefinisi alat. Aplikasi mengeksekusi alat dan memvalidasi argumennya.
inputTranscription{ model?: string; language?: string } | nullTidakPengaturan transkripsi input, misalnya { model: "fun-asr", language: "zh" }; null menonaktifkannya.
sessionExtrasSessionConfigTidakPengaturan sesi tambahan, seperti speech_rate dan enable_search. Menimpa pengaturan tingkat atas terkait; lihat peristiwa klien untuk kolomnya.
connectTimeoutMsnumberTidakBatas waktu koneksi dalam ms. Default: 10000.

Referensi API

Metode utama

MetodeNilai kembalianDeskripsi
connect()Promise<void>Hubungkan dan kirim pengaturan sesi. sessionUpdated mengonfirmasi penerapannya.
updateSession(session: SessionConfig)voidPerbarui pengaturan sesi; konfirmasikan melalui sessionUpdated.
appendAudio(pcm: Buffer | Uint8Array)voidKirim audio PCM mono 16 kHz, 16-bit.
commit()voidKomit buffer audio dalam mode manual.
clearAudioBuffer()voidBersihkan buffer audio yang belum dikomit.
createResponse(response?: Record<string, unknown>)voidMinta model membuat respons.
cancelResponse()voidBatalkan respons saat ini tanpa menutup sesi.
createConversationItem(item: ConversationItem, previousItemId?: string)voidTambahkan riwayat atau hasil alat. previousItemId menentukan posisi sisipan.
submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean)voidKirim string hasil alat. autoCreateResponse default true dan meminta respons berikutnya.
deleteConversationItem(itemId: string)voidHapus item percakapan.
retrieveConversationItem(itemId: string)voidAmbil item; terima melalui event.
sendEvent(event: ClientEvent)voidKirim peristiwa klien asli.
close(code?: number, reason?: string)voidTutup sesi dan koneksi WebSocket.

Peristiwa callback

Daftarkan callback dengan on(event, listener). Lihat peristiwa server untuk kolom lengkap.
PeristiwaPayloadDeskripsi
openvoidKoneksi terbentuk dan konfigurasi awal dikirim.
sessionCreated / sessionUpdatedServerEventPembuatan sesi atau konfirmasi konfigurasi.
audioBufferPotongan audio biner; dapat dipicu beberapa kali.
audioTranscriptDelta{ delta: string }Teks inkremental transkrip output audio.
outputTranscript{ transcript: string }Transkrip lengkap output audio.
textDelta / textDone{ delta: string } / { text: string }Teks inkremental atau lengkap dalam modalitas teks saja.
inputTranscriptDelta{ text: string; stash: string }text adalah teks pasti, stash sementara. Ganti tampilan saat ini dengan gabungan keduanya, bukan menambahkannya.
inputTranscript{ transcript: string }Transkrip final input audio.
speechStarted / speechStoppedServerEventUcapan pengguna mulai atau berhenti.
responseCreated / responseDoneServerEventRespons mulai atau berakhir. Periksa apakah responseDone.response.status adalah completed, dibatalkan, atau gagal.
functionCall{ callId: string; name: string; arguments: string }Argumen pemanggilan fungsi lengkap. Aplikasi mengurai dan memvalidasi string JSON arguments.
ambientTranscript / ambientTranscriptCompleted{ text: string; stash: string } / { transcript: string }Transkrip sementara atau final audio lingkungan, tidak masuk konteks percakapan.
eventServerEventPesan JSON layanan asli.
errorDashScopeErrorKesalahan koneksi atau layanan.
close{ code: number; reason: string }Notifikasi penutupan koneksi dasar.