Qwen-Audio-Realtime Conexión mediante WebSocket
qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus y qwen-audio-3.0-realtime-flash.
Endpoint
Utilice la siguiente URL de WebSocket. El parámetro de consulta model especifica el modelo. Reemplace <model_name> con el nombre del modelo:
- China (Pekín)
- Singapur
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>Sustituya {WorkspaceId} por el ID de su espacio de trabajo al llamar a la API.Encabezados de la solicitud
Incluya la siguiente información en los encabezados de la solicitud:
Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
Authorization | string | Sí | Token de autenticación en el formato |
user-agent | string | No | Identificador del cliente que se usa para rastrear el origen de la solicitud. |
X-DashScope-WorkSpace | string | No | ID del espacio de trabajo de Alibaba Cloud Model Studio. |
X-DashScope-DataInspection para la inspección de datos. Úselo de acuerdo con los requisitos del modelo. El ejemplo de qwen-audio-3.1-realtime-plus usa x-dashscope-dataInspection: disable.
Conceptos principales
- Sesión: Una conexión de WebSocket corresponde a una sesión que mantiene la configuración y el contexto de la conversación.
- Elemento de conversación: Cada mensaje de la conversación, organizado como una lista enlazada.
- Respuesta: La salida de una inferencia del modelo. Una respuesta contiene uno o varios elementos de salida, que pueden ser mensajes del asistente o llamadas a funciones.
- Llamada a función: Una solicitud del modelo para que el cliente ejecute una función de herramienta. Después de ejecutarla, el cliente envía el resultado como
function_call_output, y después envíaresponse.createpara activar la siguiente inferencia. - Detección de turnos: Controla cuándo se activa la inferencia.
Modos de interacción
Qwen-Audio Realtime API admite tres modos de interacción, que se configuran mediante session.turn_detection en el evento session.update. Para la detección automática, establezca type dentro del objeto. Para push-to-talk, establezca todo el campo turn_detection en null:
Modo | Valor de session.turn_detection | Descripción | Casos de uso |
|---|---|---|---|
server_vad | Objeto. Establezca | El servidor usa VAD para detectar el inicio y el final del habla y activar la inferencia automáticamente. | Conversación con manos libres y asistentes de voz |
Detección semántica inteligente de turnos | Objeto. Establezca | Combina la percepción acústica y la comprensión semántica para detectar los límites de los turnos, en lugar de basarse únicamente en las señales de voz. Los sonidos sin significado semántico, como "uh" y "ah", no activan un turno ni interrumpen la reproducción del modelo. | Conversación natural de baja latencia y manejo preciso de interrupciones |
push-to-talk |
| El cliente envía el audio manualmente y activa la inferencia. | Push-to-talk y control preciso |
Flujo de interacción
Para consultar las definiciones detalladas de los eventos, consulte Eventos del cliente y Eventos del servidor.
Modo server_vad
El servidor realiza la detección de actividad de voz en el audio entrante y activa la inferencia automáticamente cuando detecta el final del habla.
Activar este modo: Establezca turn_detection.type a server_vad en el campo session.update evento.
- Un turno de conversación completo
- Interrupción del usuario
- El cliente establece una conexión de WebSocket. El servidor devuelve
session.created. - El cliente envía
session.updatepara configurar la sesión. El servidor devuelvesession.updated. - El cliente envía continuamente
input_audio_buffer.appendpara agregar datos de audio. - Cuando el servidor detecta el inicio del habla, devuelve
input_audio_buffer.speech_startedy transmite los incrementos de transcripción ASR medianteconversation.item.input_audio_transcription.delta. - Cuando el servidor detecta el final del habla, devuelve
input_audio_buffer.speech_stopped,input_audio_buffer.committedyconversation.item.created. - El servidor genera una respuesta automáticamente y transmite los incrementos de texto y audio (
response.audio_transcript.deltayresponse.audio.delta), y después devuelveresponse.done.
Modo smart_turn / smart_turn_v2
Este modo combina la percepción acústica y la comprensión semántica para detectar el final del habla. Puede filtrar sonidos sin significado, como expresiones de asentimiento y audio de fondo. Estos sonidos se transmiten mediante eventos conversation.item.ambient_audio_transcription.delta y no activan un turno de conversación.
Activar este modo: Establezca turn_detection.type a smart_turn o smart_turn_v2 en el campo session.update evento.
smart_turn_v2 (recomendado): amplía smart_turn con una mejor comprensión del contexto de la conversación para identificar la intención de interacción en escenarios con varios participantes. Reduce las respuestas e interrupciones no deseadas causadas por otros hablantes o comentarios ajenos a la conversación.
- Un turno de conversación completo
- Interrupción del usuario
- Turno no válido
- Los sonidos sin significado semántico, como "uh" y "ah", no activan la inferencia. Se devuelven mediante eventos
ambient_audio_transcription. - El habla que antes se identificó como válida puede invalidarse:
input_audio_buffer.speech_stoppeddevuelvereason=turn_invalid. En ese caso, no se activa la inferencia. - Mientras espera la siguiente entrada del usuario, el cliente puede enviar explícitamente
response.createpara activar la inferencia.
Flujo de configuración de mejora del hablante
En modo smart_turn / smart_turn_v2, si el primer session.update incluye voiceprint_audio_urls, el servidor registra las huellas de voz de forma asíncrona al cargar las características de audio de los hablantes de destino. Los eventos informan el progreso del registro. Un error de registro no bloquea la conversación normal.
El registro de huellas de voz se realiza en el siguiente orden:
-
El cliente establece una conexión de WebSocket. El servidor devuelve
session.created. -
El cliente envía su primer
session.updatecon las URL de audio de las huellas de voz enturn_detection.voiceprint_audio_urls. -
El servidor inicia de inmediato el registro asíncrono de huellas de voz. Antes de devolver
session.updated, envíavoiceprint_audio_list.in_progresscon el identificador único de la tarea de registroitem_id. -
El servidor devuelve
session.updatedpara confirmar que la configuración de la sesión está aplicada. -
Al terminar el registro de huellas de voz, el servidor envía un evento final. Su
item_idcoincide con el valor del paso 3:- Registro exitoso:
voiceprint_audio_list.completed. - Error de registro:
voiceprint_audio_list.failed, con un camporeasonque explica el error, como una URL de audio que no se puede descargar.
- Registro exitoso:
voiceprint_audio_urls solo tiene efecto en el primer session.update. El campo se ignora en las actualizaciones posteriores.Modo push-to-talk
El cliente controla manualmente cuándo enviar el audio y activar la inferencia. Este modo es adecuado para interacciones push-to-talk.
Activar este modo: Establezca turn_detection a null en el campo session.update evento.
- Un turno de conversación completo
- Interrupción del usuario
- El cliente envía continuamente
input_audio_buffer.appendpara agregar datos de audio. - Cuando el usuario termina de hablar, el cliente envía
input_audio_buffer.commitpara enviar el búfer. - El cliente envía
response.createpara activar la inferencia manualmente. - El servidor genera una respuesta y transmite texto y audio en streaming.
Restricciones de operaciones por modo
Operación | push-to-talk | server_vad | smart_turn / smart_turn_v2 |
|---|---|---|---|
session.update | Todos los campos se pueden cambiar en IDLE; algunos tienen restricciones en otros estados | Todos los campos se pueden cambiar en IDLE; algunos tienen restricciones en otros estados | Todos los campos se pueden cambiar en IDLE; algunos tienen restricciones en otros estados |
input_audio_buffer.append | Permitido | Permitido | Permitido |
input_audio_buffer.commit | Permitido | Se ignora | Se ignora |
input_audio_buffer.clear | Permitido | Se ignora | Se ignora |
response.create | Permitido después de enviar el audio almacenado en búfer con | Permitido cuando no se está generando una respuesta; no active otra respuesta mientras se genera una | Permitido mientras se espera la siguiente entrada del usuario; no active otra respuesta dentro de un turno activo, desde |
response.cancel | Permitido durante la inferencia | Permitido durante la inferencia | Permitido durante la inferencia |
conversation.item.create/delete/retrieve | Permitido | Permitido | Permitido |
turn_detection e input_audio_format solo se pueden cambiar antes de enviar audio por primera vez, mientras la sesión está en IDLE.Manejo de errores
Si falla el handshake, verifique el dominio, la región, el espacio de trabajo, la API Key, el nombre del modelo, su estado de activación y los permisos. Para consultar las descripciones completas, consulte Códigos de error.
Tipo | Comportamiento | Ejemplo |
|---|---|---|
Error del cliente ( | La conexión permanece abierta; se informa el error | Parámetros no válidos, operaciones no permitidas en el estado actual o item_id duplicado |
Error del servidor ( | Se termina la conexión | Error de conexión con el LLM o error de almacenamiento |