Skip to main content

Qwen-Audio-Realtime Node.js SDK

Use el SDK de voz Node.js para configurar sesiones Qwen-Audio-Realtime, intercambiar audio y gestionar transcripciones y llamadas a funciones.

Requisitos previos

Obtenga una clave API en la consola y configúrela como variable de entorno DASHSCOPE_API_KEY.

Instalar el SDK

Requiere Node.js 18 o posterior. Descargue el paquete SDK 0.1.0 y ejecute en su proyecto:
npm install ./dashscope-sdk-nodejs-0.1.0.tgz

Inicio rápido

Descargue el audio de ejemplo como input.mp3 y conviértalo a PCM mono de 16 kHz y 16 bits:
ffmpeg -i input.mp3 -f s16le -ac 1 -ar 16000 input.pcm
Guarde el ejemplo como example.mjs y ejecute 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)
}

Parámetros de solicitud

Opciones del constructor de RealtimeClient:
ParámetroTipoObligatorioDescripción
apiKeystringNoClave API. Usa DASHSCOPE_API_KEY de forma predeterminada.
workspaceIdstringNoID del espacio de trabajo. Usa DASHSCOPE_WORKSPACE_ID de forma predeterminada.
baseUrlstringNoEstablezca el host en dashscope-intl.aliyuncs.com (Singapur).
modelstringSíID del modelo.
voicestringNoID de voz. Usa la voz predeterminada del servicio si se omite.
instructionsstringNoInstrucciones del sistema para rol, estilo y comportamiento.
turnDetectionTurnDetection | nullNoPredeterminado: { type: "server_vad" }. null activa el envío manual. También admite smart_turn y smart_turn_v2.
modalitiesArray<'text' | 'audio'>NoModalidades de salida. Predeterminado: ["text", "audio"].
maxHistoryTurnsnumberNoTurnos de historial: [1,50]. Predeterminado del servicio: 20.
toolsToolDefinition[]NoDefiniciones de herramientas. La aplicación las ejecuta y valida sus argumentos.
inputTranscription{ model?: string; language?: string } | nullNoConfiguración de transcripción de entrada, como { model: "fun-asr", language: "zh" }; null la desactiva.
sessionExtrasSessionConfigNoAjustes adicionales, como speech_rate y enable_search. Sustituyen los ajustes de nivel superior correspondientes; consulte los campos en eventos del cliente.
connectTimeoutMsnumberNoTiempo de conexión en ms. Predeterminado: 10000.

Referencia de la API

Métodos principales

MétodoValor de retornoDescripción
connect()Promise<void>Conecta y envía los ajustes. sessionUpdated confirma su aplicación.
updateSession(session: SessionConfig)voidActualiza la sesión; confirme mediante sessionUpdated.
appendAudio(pcm: Buffer | Uint8Array)voidEnvía audio PCM mono de 16 kHz y 16 bits.
commit()voidConfirma el búfer de audio en modo manual.
clearAudioBuffer()voidBorra el búfer de audio no confirmado.
createResponse(response?: Record<string, unknown>)voidSolicita una respuesta del modelo.
cancelResponse()voidCancela la respuesta actual manteniendo la sesión.
createConversationItem(item: ConversationItem, previousItemId?: string)voidAñade historial o resultados. previousItemId define la posición.
submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean)voidEnvía el resultado como cadena. autoCreateResponse vale true por defecto y solicita la siguiente respuesta.
deleteConversationItem(itemId: string)voidElimina un elemento de conversación.
retrieveConversationItem(itemId: string)voidConsulta un elemento; recíbalo mediante event.
sendEvent(event: ClientEvent)voidEnvía un evento original del cliente.
close(code?: number, reason?: string)voidCierra la sesión y la conexión WebSocket.

Eventos de callback

Registre callbacks con on(event, listener). Consulte los campos completos en eventos del servidor.
EventoCarga útilDescripción
openvoidConexión establecida y configuración inicial enviada.
sessionCreated / sessionUpdatedServerEventCreación de sesión o confirmación de configuración.
audioBufferFragmento de audio binario; puede emitirse varias veces.
audioTranscriptDelta{ delta: string }Texto incremental de la transcripción del audio de salida.
outputTranscript{ transcript: string }Transcripción completa del audio de salida.
textDelta / textDone{ delta: string } / { text: string }Texto incremental o completo en modalidad de solo texto.
inputTranscriptDelta{ text: string; stash: string }text es texto confirmado y stash, provisional. Sustituya la visualización actual por su combinación, en lugar de añadirla.
inputTranscript{ transcript: string }Transcripción final del audio de entrada.
speechStarted / speechStoppedServerEventInicio o fin del habla del usuario.
responseCreated / responseDoneServerEventRespuesta iniciada o terminada. Compruebe si responseDone.response.status es completed, cancelado o fallido.
functionCall{ callId: string; name: string; arguments: string }Argumentos completos de la llamada. La aplicación analiza y valida la cadena JSON arguments.
ambientTranscript / ambientTranscriptCompleted{ text: string; stash: string } / { transcript: string }Transcripción actual o final del audio ambiental, excluida del contexto de conversación.
eventServerEventMensaje JSON original del servicio.
errorDashScopeErrorError de conexión o del servicio.
close{ code: number; reason: string }Notificación de cierre de la conexión subyacente.