Qwen-Audio es un modelo de interacción de voz en tiempo real de extremo a extremo para conversaciones de voz de baja latencia. Los casos de uso incluyen asistentes de voz, servicio al cliente inteligente y compañeros de IA.
Visión general
Qwen-Audio convierte el audio en tiempo real en voz y texto a través de una conexión dúplex completa, con entrada y salida en streaming.
Además de WebSocket, este modelo admite AOQ y WebRTC. Para una integración del lado del cliente que priorice latencia estable, interacción en redes deficientes y supresión de ruido y cancelación de eco en la comunicación dúplex completa en tiempo real, considere primero AOQ. Para comparar y seleccionar protocolos, consulte la Referencia de la API.
- Tres modos de interacción: VAD acústico (server_vad), detección inteligente de turnos semánticos (smart_turn) y control manual (pulsar para hablar)
- En el modo smart_turn, el modelo combina la percepción acústica y la comprensión semántica para determinar los límites de los turnos, de modo que sonidos de relleno como "eh" o "mmm" no interrumpan la conversación
- La compatibilidad con Function Calling permite que el modelo decida cuándo invocar herramientas externas para obtener información adicional
- La compatibilidad con búsqueda web permite que el modelo decida cuándo recuperar información actualizada y devolver fuentes de resultados de búsqueda (la búsqueda web y Function Calling no pueden habilitarse al mismo tiempo)
- Gestión del contexto de conversación: cree, recupere y elimine elementos de conversación para inyectar contexto histórico o eliminar elementos irrelevantes
- Salida de voz expresiva que ajusta dinámicamente el tono, el ritmo y la emoción según el contexto de la conversación
- Compatibilidad con voces del sistema y voces clonadas; utilice Voice Cloning para crear una voz de IA personalizada para la salida de voz
- Mejora del hablante en modo smart_turn: pase audio pregrabado de un usuario objetivo para que el modelo pueda fijarse en ese hablante durante conversaciones dúplex, bloqueando eficazmente otras voces y ruido de fondo
Funcionamiento
Qwen-Audio usa una conexión dúplex completa con una arquitectura impulsada por eventos. El cliente y el servidor intercambian datos simultáneamente a través de una conexión persistente: el cliente transmite continuamente audio del micrófono mientras el servidor devuelve respuestas de voz y texto en tiempo real. Toda la interacción está impulsada por eventos: el cliente envía eventos como session.update y input_audio_buffer.append, y el servidor responde con eventos como response.audio.delta y response.done. No se requiere sondeo.
Un ciclo de vida de conexión típico es: establecer la conexión WebSocket, enviar session.update para configurar los parámetros de la sesión, transmitir audio y recibir respuestas, y luego cerrar la conexión.
Formato de audio
Dirección | Formato | Especificación |
|---|---|---|
Entrada (cliente a servidor) | PCM | Tasa de muestreo de 16 kHz, profundidad de 16 bits, mono |
Salida (servidor a cliente) | PCM | Tasa de muestreo de 24 kHz, profundidad de 16 bits, mono |
Idiomas admitidos
Las conversaciones de voz en tiempo real admiten los siguientes idiomas y variedades del chino:
- Idiomas: alemán (de), inglés (en), español (es), francés (fr), indonesio (id), italiano (it), japonés (ja), coreano (ko), portugués (pt), ruso (ru) y chino (zh).
- Variedades del chino: mandarín, cantonés, chongqing, noreste, Gansu, Guizhou, Zhejiang, Hebei, Henan, Hubei, Hunan, Jiangxi, Ningbo, Ningxia, Qingdao, Shaanxi, Shanxi, Shandong, shanghainés, Sichuan y Yunnan.
qwen-audio-3.1-realtime-plus, puede usar session.input_audio_transcription.language y session.output_audio.language para especificar el idioma de origen del audio de entrada y el idioma de destino del audio de salida, respectivamente. Para los códigos de idioma válidos para cada parámetro, consulte Eventos del cliente. De los dos, session.output_audio.language se aplica a la síntesis de voz (TTS): el modelo hace todo lo posible para producir habla en el idioma de destino, pero esto no está garantizado, y el idioma del texto de respuesta no cambia.
Capacidad de contexto
El modelo mantiene el historial de conversación. Cuando el número de turnos o la duración acumulada de audio excede los siguientes límites, el historial anterior se descarta automáticamente. La duración máxima es el límite superior de audio acumulado que el contexto del modelo puede retener.
Modelo | Turnos máximos de audio | Duración máxima de audio |
|---|---|---|
qwen-audio-3.1-realtime-plus | 50 | 300 segundos |
qwen-audio-3.0-realtime-plus | 50 | 300 segundos |
qwen-audio-3.0-realtime-flash | 50 | 300 segundos |
Requisitos previos
- Obtenga una clave de API y configúrela como variable de entorno.
- Para utilizar el protocolo AOQ, descargue e integre el SDK del cliente AOQ. Para más detalles, consulte Descripción general del SDK.
Inicio rápido
Los ejemplos básicos de WebSocket a continuación usan qwen-audio-3.1-realtime-plus con la voz del sistema longanqian_v3.1 establecida explícitamente. Para migrar desde 3.0 Plus, actualice el parámetro de consulta model en la URL y seleccione una voice coincidente en Configuración de voz. El protocolo de eventos WebSocket no ha cambiado.
Siga estos pasos para iniciar una conversación de voz en tiempo real con el modelo Qwen-Audio.
- WebSocket nativo
server_vad. Antes de ejecutarlo, instale las dependencias necesarias:realtime_quickstart.py:python realtime_quickstart.py y hable por su micrófono para iniciar una conversación en tiempo real. El servidor detecta automáticamente la actividad del habla y activa las respuestas.Ejemplo completoEl siguiente ejemplo amplía la conversación básica con manejo de interrupciones de voz y cancelación de eco. Cree los dos archivos en el mismo directorio:B64PCMPlayer.py
B64PCMPlayer.py
realtime_demo.py
realtime_demo.py
websockets es anterior a la versión 11, cambie additional_headers por extra_headers en el código, o actualice: pip install --upgrade websockets.python realtime_demo.py y hable por su micrófono para iniciar una conversación en tiempo real. El sistema detecta automáticamente la actividad del habla y activa las respuestas.Configuración de sesión
Modos de interacción
Qwen-Audio admite tres modos de interacción: server_vad (VAD acústico que detecta automáticamente el inicio y el final del habla), smart_turn (detección semántica inteligente de turnos que combina señales acústicas y semánticas; se recomienda smart_turn_v2) y push-to-talk (control manual del cliente). Para obtener detalles y la secuencia de interacción de eventos, incluidos los diagramas de secuencia, consulte Modos de interacción.
turn_detection solo se puede configurar antes de enviar el primer audio (estado IDLE). Para cambiar los modos de interacción a mitad de sesión, cierre y restablezca la conexión.turn_detection en un evento session.update:
- server_vad:
- smart_turn:
- pulsar para hablar:
manual_funchat.py
manual_funchat.py
Instrucciones del sistema
Utilice el parámetro instructions para definir el rol del modelo, el estilo de respuesta y las preferencias de comportamiento. Configure este parámetro en session.update para aplicarlo a toda la sesión.
- Defina una identidad de rol clara (por ejemplo, "Usted es un asistente de voz inteligente" o "Usted es un tutor de conversación en inglés") y, opcionalmente, incluya detalles como nombre o género.
- Especifique un tono conversacional y un estilo de fraseo, enfatizando que un tono natural no compromete la integridad del contenido: los detalles, números y recomendaciones específicas aún deben incluirse, solo que expresados de manera relajada y natural.
- Indique al modelo que tenga en cuenta todas las restricciones de contexto en la conversación (como presupuesto, preferencias, restricciones o acuerdos previos). Cuando se apliquen múltiples condiciones, aborde cada una y no omita ninguna información crítica.
- Controlar el formato de salida: a menos que el usuario solicite lo contrario, evite emojis y otros caracteres especiales, así como el formato Markdown. Genere texto sin formato para garantizar una reproducción natural de TTS.
- Defina la estrategia de respuesta: mantenga los saludos simples y los intercambios casuales breves y naturales; para razonamientos, problemas de múltiples condiciones, listas de recomendaciones o consejos de seguridad, priorice la integridad: asegúrese de que la información clave (como precios, ubicaciones y condiciones) esté completamente presente, sin preámbulos innecesarios, repeticiones o relleno.
- Establezca una estrategia de seguimiento: siga el principio de "responder primero la pregunta actual del usuario, luego plantear naturalmente una pregunta de seguimiento al final para avanzar en la conversación". Haga solo una pregunta a la vez; no haga múltiples preguntas seguidas ni confirme repetidamente.
instructions para escenarios generales de conversación por voz. Cubre la definición de roles, el estilo conversacional, el control de formato y la estrategia de seguimiento. Úsela directamente o adáptela a sus necesidades:
instructions abarcan una variedad de estilos de personalidad. Elija uno que se adapte a su caso de uso o personalícelo aún más:
- Daisy (Compañera dulce y genial):
- Len (Genial y Sarcástico):
- Mochen (Sereno y Carismático):
- Hannibal (Elegante e incisivo):
- Heizi (Compañero del Noreste):
Configuración de voz
Use el parámetro voice para establecer la voz TTS para las respuestas del modelo. El valor predeterminado es longanqian_v3.1 para 3.1 Plus y longanqian para 3.0 Plus/Flash. Se admiten tanto voces del sistema como voces clonadas. 3.1 Plus conserva las voces de 3.0 Plus y añade ocho opciones de voces del sistema.
Voces del sistema: seleccione un ID de voz para el modelo.
| Modelo | ID de voces del sistema |
|---|---|
qwen-audio-3.1-realtime-plus | longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng, longanqian_v3.1, longanhuan_v3.1, longanlingxin_v3.1, longanfengyue_v3.1, xunanchuan_v3.1, beth_v3.1, betty_v3.1, cally_v3.1 |
qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash | longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng |
target_model en qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus o qwen-audio-3.0-realtime-flash. Después establezca el parámetro voice en el voice_id devuelto.
Modalidades de salida
Utilice el parámetro modalities para controlar los tipos de salida del modelo:
["audio", "text"](predeterminado): genera tanto voz como texto.["text"]: genera solo texto, sin voz. Adecuado para depuración, registro o escenarios que solo requieren respuestas de texto.
response.modalities en response.create para anular la configuración de modalidad para una sola respuesta.
Configuración de VAD
En el modo server_vad, configure los siguientes parámetros en el objeto session.turn_detection para ajustar el comportamiento del VAD (estos parámetros no tienen efecto en el modo smart_turn):
Parámetro | Tipo | Descripción |
|---|---|---|
| float | Sensibilidad VAD. Valores más bajos aumentan la sensibilidad VAD, facilitando la detección de sonidos tenues (incluido el ruido de fondo) como habla. Valores más altos disminuyen la sensibilidad, requiriendo un habla más clara y fuerte para activar la detección. Rango: [-1.0, 1.0]. Valor predeterminado: 0.5. |
| integer | Duración mínima de silencio (en milisegundos) después de que termina el habla antes de activar una respuesta del modelo. Valores más bajos producen respuestas más rápidas pero pueden causar activaciones false durante pausas breves. Rango: [200, 6000]. Valor predeterminado: 800. Rango recomendado para conversaciones: 400-800. |
Control de turnos de historial
Use el parámetro max_history_turns para controlar cuántos turnos históricos de preguntas y respuestas referencia el modelo durante la inferencia. Valores más altos permiten que el modelo revise más historial de conversación para una mejor comprensión del contexto, pero aumentan el consumo de tokens y la latencia de inferencia.
max_history_turns: 1-50. Valor predeterminado: 20.
Consejos de ajuste:
- Conversaciones cortas (como preguntas y respuestas rápidas): establezca un valor más bajo (por ejemplo, 5-10) para reducir la latencia.
- Conversaciones largas (como servicio al cliente de múltiples turnos): establezca un valor más alto (por ejemplo, 30-50) para ayudar al modelo a comprender el contexto completo.
Funciones avanzadas
Function Calling
Qwen-Audio admite Function Calling, lo que permite al modelo decidir cuándo invocar herramientas externas basándose en el contexto de la conversación.
1. Registrar herramientas
Configurar tools a través de session.update:
response.function_call_arguments.done, ejecute la herramienta en el cliente y envíe el resultado de vuelta mediante conversation.item.create:
response.create para que el modelo genere una respuesta basada en dicho resultado:
function_call y puede incluir tanto mensajes regulares como llamadas a funciones. El contenido de las llamadas a funciones no se envía a TTS para su reproducción.realtime_demo.py del inicio rápido. Asegúrese de que B64PCMPlayer.py esté en el mismo directorio antes de ejecutarlo.
realtime_fc_demo.py
realtime_fc_demo.py
python realtime_fc_demo.py y hable en su micrófono para probar conversaciones en tiempo real con Function Calling. Por ejemplo, pregunte "¿Qué tiempo hace en Hangzhou?" o "¿Cuánto cuesta un boleto de tren de Beijing a Shanghai?" y el modelo invocará automáticamente la herramienta correspondiente y responderá con el resultado.
Gestión del contexto de conversación
Qwen-Audio le permite gestionar elementos de conversación en el contexto a través de eventos del cliente. Utilice esto para inyectar contexto histórico, agregar información de texto o eliminar elementos de conversación irrelevantes.
-
Crear un elemento de conversación (
conversation.item.create): inserta un elemento de conversación en el contexto. Se admiten los siguientes tres valores deitem.type:message: un mensaje de conversación regular. Especifiquerole(system,useroassistant) y un arreglocontent. Utilice esto para inyectar historial de conversación o instrucciones del sistema.function_call: solicitud de llamada a función. Especifiquecall_id,nameyarguments(cadena JSON). Generalmente es generada por el servidor, pero el cliente también puede usarla para inyectar registros históricos de llamadas a funciones.function_call_output: resultado de la ejecución de una herramienta. Especifiquecall_idyoutput(cadena JSON). Después de recibir unfunction_call, ejecute la herramienta en el cliente y devuelva el resultado con este tipo.
previous_item_idespecifica el elemento de conversación existente después del cual insertar el nuevo elemento. Esto le permite insertar contenido en cualquier posición del historial de conversación. Si se omite, el nuevo elemento se añade al final.- Insertar un mensaje de usuario en una posición específica:
- Devolver un resultado de Function Calling:
item.id especificado en conversation.item.create ya existe en la conversación, se devuelve un error.- Recuperar un elemento de conversación (
conversation.item.retrieve): consulta un elemento de conversación almacenado en el servidor. Para contenido de tipo audio, solo se devuelve el texto transcrito, no los datos de audio sin procesar.
- Eliminar un elemento de conversación (
conversation.item.delete): elimina un elemento específico del contexto de la conversación.
Transcripción de audio ambiental
Solo modo smart_turn. Cuando VAD detecta actividad del habla pero el análisis semántico determina que no es un turno válido (como ruido o sonidos de relleno como "eh" o "hmm"), el servidor no activa un turno de conversación. En su lugar, envía el resultado ASR al cliente como un evento ambient_audio_transcription. Esta transcripción no se escribe en el contexto de la conversación.
delta y completed. Utilice este evento para implementar la monitorización de audio ambiental o la conciencia del entorno de conversación.
Mejora de hablante
Solo modo smart_turn. Pase URLs de audio pregrabado del usuario objetivo en session.update. El modelo se fijará en ese hablante durante conversaciones dúplex, ignorando efectivamente otras voces y ruido de fondo, permitiendo interacciones dúplex fluidas en entornos abiertos.
Configuración: pase URL de audio de impresión de voz accesibles públicamente en turn_detection.voiceprint_audio_urls dentro de la primera llamada a session.update.
- Hasta 5 URL. El audio debe estar en formato PCM o WAV de 16 kHz.
- Este parámetro solo surte efecto en la primera llamada a
session.update. El campo se ignora en las llamadas posteriores.
voiceprint_audio_list.in_progress: el registro ha comenzado. Se envía antes desession.updated, portandoitem_id.voiceprint_audio_list.completed: registro exitoso. Elitem_idcoincide con el dein_progress.voiceprint_audio_list.failed: error en el registro, con un camporeasonque describe el error (por ejemplo, la URL de audio no es accesible). Un fallo en el registro no bloquea la conversación en curso.
Puesta en marcha
Configurar tolerancia a fallos
- Reconexión del cliente: implemente la reconexión automática para manejar la inestabilidad de la red. Establezca una señal de reconexión en la devolución de llamada
on_errory utilice retroceso exponencial (por ejemplo, espere 1s, 2s, 4s) para los reintentos. - Clasificación de errores: los errores del cliente (
invalid_request_error) no desconectan la sesión; regístrelos o ajuste los parámetros. Los errores del servidor (server_error) terminan la conexión y requieren volver a conectarse. - Manejo de interrupciones: en los modos server_vad / smart_turn, el nuevo habla del usuario interrumpe automáticamente la respuesta en curso del modelo (
response.donedevuelvestatus=cancelled). Cuando se recibeinput_audio_buffer.speech_started, borre inmediatamente el búfer de reproducción local para evitar superposición de audio.
Ciclo de vida de la conexión
Una sesión típica de WebSocket sigue este ciclo de vida:
- Conectar: el cliente inicia una conexión WebSocket y el servidor devuelve un evento
session.created. - Configurar: el cliente envía
session.updatepara establecer el modo de interacción, la voz, las herramientas y otros parámetros. Complete este paso antes de enviar cualquier audio. - Interactuar: el cliente transmite audio continuamente (
input_audio_buffer.append). El servidor realiza la inferencia basándose en la detección de VAD o activadores manuales y devuelve voz y texto en streaming. - Cerrar: el cliente cierra la conexión WebSocket. El servidor también puede desconectarse si la conexión permanece inactiva durante demasiado tiempo.
item_id correspondiente antes de cerrar la conexión. response.done indica el final de la respuesta del modelo; la transcripción puede llegar después.Optimización de latencia
- Tamaño del fragmento de audio: envíe aproximadamente 100 ms de datos de audio por fragmento (16 kHz x 16 bits x mono = 3,200 bytes por fragmento). Esto equilibra el rendimiento en tiempo real con la eficiencia de la red.
- Reproducción en streaming: comience a reproducir el audio tan pronto como llegue
response.audio.delta. No espere aresponse.donepara reproducir la respuesta completa. - Borrar búfer en interrupción: cuando se recibe
input_audio_buffer.speech_started, borre inmediatamente el búfer de reproducción local para evitar que se siga reproduciendo audio obsoleto.
Modelos y regiones compatibles
- Singapore
- China (Beijing)
- qwen-audio-3.1-realtime-plus
- qwen-audio-3.0-realtime-plus
- qwen-audio-3.0-realtime-flash