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:
Inicio rápido
Descargue el audio de ejemplo como input.mp3 y conviértalo a PCM mono de 16 kHz y 16 bits:
example.mjs y ejecute node example.mjs.
Parámetros de solicitud
Opciones del constructor de RealtimeClient:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
apiKey | string | No | Clave API. Usa DASHSCOPE_API_KEY de forma predeterminada. |
workspaceId | string | No | ID del espacio de trabajo. Usa DASHSCOPE_WORKSPACE_ID de forma predeterminada. |
baseUrl | string | No | Establezca el host en dashscope-intl.aliyuncs.com (Singapur). |
model | string | Sí | ID del modelo. |
voice | string | No | ID de voz. Usa la voz predeterminada del servicio si se omite. |
instructions | string | No | Instrucciones del sistema para rol, estilo y comportamiento. |
turnDetection | TurnDetection | null | No | Predeterminado: { type: "server_vad" }. null activa el envío manual. También admite smart_turn y smart_turn_v2. |
modalities | Array<'text' | 'audio'> | No | Modalidades de salida. Predeterminado: ["text", "audio"]. |
maxHistoryTurns | number | No | Turnos de historial: [1,50]. Predeterminado del servicio: 20. |
tools | ToolDefinition[] | No | Definiciones de herramientas. La aplicación las ejecuta y valida sus argumentos. |
inputTranscription | { model?: string; language?: string } | null | No | Configuración de transcripción de entrada, como { model: "fun-asr", language: "zh" }; null la desactiva. |
sessionExtras | SessionConfig | No | Ajustes adicionales, como speech_rate y enable_search. Sustituyen los ajustes de nivel superior correspondientes; consulte los campos en eventos del cliente. |
connectTimeoutMs | number | No | Tiempo de conexión en ms. Predeterminado: 10000. |
Referencia de la API
Métodos principales
| Método | Valor de retorno | Descripción |
|---|---|---|
connect() | Promise<void> | Conecta y envía los ajustes. sessionUpdated confirma su aplicación. |
updateSession(session: SessionConfig) | void | Actualiza la sesión; confirme mediante sessionUpdated. |
appendAudio(pcm: Buffer | Uint8Array) | void | Envía audio PCM mono de 16 kHz y 16 bits. |
commit() | void | Confirma el búfer de audio en modo manual. |
clearAudioBuffer() | void | Borra el búfer de audio no confirmado. |
createResponse(response?: Record<string, unknown>) | void | Solicita una respuesta del modelo. |
cancelResponse() | void | Cancela la respuesta actual manteniendo la sesión. |
createConversationItem(item: ConversationItem, previousItemId?: string) | void | Añade historial o resultados. previousItemId define la posición. |
submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean) | void | Envía el resultado como cadena. autoCreateResponse vale true por defecto y solicita la siguiente respuesta. |
deleteConversationItem(itemId: string) | void | Elimina un elemento de conversación. |
retrieveConversationItem(itemId: string) | void | Consulta un elemento; recíbalo mediante event. |
sendEvent(event: ClientEvent) | void | Envía un evento original del cliente. |
close(code?: number, reason?: string) | void | Cierra 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.
| Evento | Carga útil | Descripción |
|---|---|---|
open | void | Conexión establecida y configuración inicial enviada. |
sessionCreated / sessionUpdated | ServerEvent | Creación de sesión o confirmación de configuración. |
audio | Buffer | Fragmento 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 / speechStopped | ServerEvent | Inicio o fin del habla del usuario. |
responseCreated / responseDone | ServerEvent | Respuesta 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. |
event | ServerEvent | Mensaje JSON original del servicio. |
error | DashScopeError | Error de conexión o del servicio. |
close | { code: number; reason: string } | Notificación de cierre de la conexión subyacente. |