Las interfaces clave y los parámetros de solicitud para Qwen-Omni en tiempo real mediante el SDK de Python de DashScope.
Requisitos previos
Su versión del SDK debe ser 1.26.5 o posterior. Antes de comenzar, consulte Flujo de interacción multimodal en tiempo real.
Introducción
Para usar qwen3.8-omni-flash-realtime, establezca el parámetro model del constructor de sesión en este nombre de modelo. La voz predeterminada es Tina. Para ejemplos de configuración de sesión y agregación de video del SDK de Python, consulte la guía de tiempo real.
Descargue el código de ejemplo de GitHub. Hay tres métodos de llamada disponibles:
-
Ejemplo de conversación de audio: Captura entrada de audio en tiempo real desde el micrófono, habilita el modo VAD para detectar automáticamente el inicio y el final del habla, y admite interrupción de voz.
El parámetro
enable_turn_detectiondebe establecerse en True.Recomendamos usar auriculares para la reproducción de audio y evitar que los ecos activen la interrupción de voz.
-
Ejemplo de conversación de audio y video: Captura entrada de audio y video en tiempo real desde el micrófono y la cámara, habilita el modo VAD para detectar automáticamente el inicio y el final del habla, y admite interrupción de voz.
El parámetro
enable_turn_detectiondebe establecerse en True.Recomendamos usar auriculares para la reproducción de audio y evitar que los ecos activen la interrupción de voz.
-
Llamada local: Utiliza audio e imágenes locales como entrada y habilita el Modo manual, que le permite controlar manualmente el ritmo de envío.
El parámetro
enable_turn_detectiondebe establecerse en False.
Parámetros de solicitud
Establezca los siguientes parámetros de solicitud en el constructor (init) de la clase OmniRealtimeConversation.
Parámetro | Tipo | Descripción |
|---|---|---|
model | str | El modelo Qwen-Omni a utilizar. Consulte la Lista de modelos. |
callback |
| Instancia de callback que maneja eventos del lado del servidor. |
url | str | La dirección de llamada:
Reemplace |
ImportanteAlibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:
- China (Pekín): de
wss://dashscope.aliyuncs.comawss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapur: de
wss://dashscope-intl.aliyuncs.comawss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} es su ID de espacio de trabajo, que se encuentra en la página Workspace Details de la consola de Alibaba Cloud Model Studio. Qwen3.8-Omni-Flash-Realtime requiere los dominios específicos del espacio de trabajo mencionados anteriormente. Los modelos anteriores pueden continuar usando los dominios originales.
Configure los siguientes parámetros de solicitud con el método update_session.
Parámetro | Tipo | Descripción |
|---|---|---|
output_modalities | list[MultiModality] | La modalidad de salida del modelo. Establezca [MultiModality.TEXT] para solo texto, o [MultiModality.TEXT, MultiModality.AUDIO] para ambos audio y texto. |
voice | str | La voz para la salida de audio. Para ver las voces compatibles, consulte la Lista de voces. Voces predeterminadas:
|
input_audio_config | AudioFormatConfig | Configuración de formato de audio de entrada. Use Se aplica a |
output_audio_config | AudioFormatConfig | Configuración de formato de audio de salida. Use Se aplica a |
input_audio_format | AudioFormat | Argumento de formato de entrada heredado. Admite |
output_audio_format | AudioFormat | Argumento de formato de salida heredado. Admite |
smooth_output | bool | Este parámetro solo es compatible con
|
instructions | str | Un mensaje del sistema que establece el objetivo o rol del modelo. Por ejemplo: Usted es un agente de IA para un hotel de cinco estrellas. Responda las preguntas de los clientes sobre tipos de habitaciones, instalaciones, precios y políticas de reserva. Sea preciso y amable. Responda siempre con una actitud profesional y útil. No proporcione información no verificada o fuera del alcance de los servicios del hotel. |
enable_input_audio_transcription | bool | Habilita el reconocimiento de voz para el audio de entrada. |
input_audio_transcription_model | str | Modelo de reconocimiento de voz para la transcripción de audio de entrada. El valor siempre es qwen3-asr-flash-realtime. Este parámetro no es configurable. |
turn_detection_type | str | El tipo de Detección de Actividad de Voz (VAD). Valores válidos:
|
turn_detection_threshold | float | Umbral de detección de VAD. Auméntelo en entornos ruidosos y redúzcalo en entornos silenciosos.
Predeterminado: 0.2. Valores válidos: [-1.0, 1.0]. |
turn_detection_silence_duration_ms | int | Duración de silencio que indica el final del habla. Si se supera, el modelo activa una respuesta. Predeterminado: 800. Valores válidos: [200, 6000]. |
turn_detection_param | dict | Parámetros de configuración adicionales de Ejemplo: |
enable_search | bool | Aplica a los modelos Qwen3.8-Omni-Flash-Realtime y Qwen3.5-Omni-Realtime. Habilita la búsqueda web. Predeterminado: La llamada de herramientas (tools) y la búsqueda web (enable_search) son incompatibles. No puede habilitar ambas al mismo tiempo. |
search_options | object | Opciones de búsqueda web. Surte efecto solo cuando Actualmente, solo puede establecer |
tools | list[dict] | Aplica a los modelos Qwen3.8-Omni-Flash-Realtime y Qwen3.5-Omni-Realtime. Definiciones de herramientas. Cuando se proporcionan, el modelo puede llamar a herramientas externas para responder a las preguntas del usuario. Para Function Calling, el modelo no genera audio y solo devuelve los parámetros de llamada a la herramienta. Qwen3.8-Omni-Flash-Realtime admite Function Calling y herramientas MCP en la misma sesión. Consulte eventos del cliente para la configuración de MCP y límites de llamadas MCP para cuotas. Los siguientes campos describen las herramientas de Function Calling. Cada herramienta es un diccionario que contiene los siguientes campos:
|
temperature | float | Temperatura de muestreo que controla la diversidad del contenido. Los valores más altos generan contenido más diverso; los valores más bajos generan contenido más determinista. Valores válidos: [0, 2). Dado que tanto temperature como top_p controlan la diversidad del contenido, le recomendamos configurar solo uno de ellos.
|
top_p | float | Umbral de probabilidad para el muestreo de núcleo que controla la diversidad del contenido. Los valores más altos generan contenido más diverso; los valores más bajos generan contenido más determinista. Valores válidos: (0, 1.0]. Dado que tanto temperature como top_p controlan la diversidad del contenido, le recomendamos configurar solo uno de ellos. Valores predeterminados de top_p:
|
top_k | integer | Tamaño del conjunto de candidatos para el muestreo. Por ejemplo, 50 significa que solo los 50 tokens con mayor puntuación forman el conjunto de candidatos. Los valores más grandes aumentan la aleatoriedad; los valores más pequeños aumentan el determinismo. Configure en None o un valor mayor que 100 para deshabilitar top_k y usar solo top_p. El valor debe ser mayor o igual a 0. Valores predeterminados de top_k:
|
max_tokens | integer | Número máximo de tokens a devolver.
Para Utilice max_tokens para limitar la longitud de salida al generar resúmenes, palabras clave, controlar costos o reducir el tiempo de respuesta. |
repetition_penalty | float | Controla la repetición en secuencias generadas. Los valores más altos reducen la repetición. 1.0 significa sin penalización. Valores predeterminados de repetition_penalty:
|
presence_penalty | float | Controla la repetición de contenido en la salida del modelo. Valores válidos: [-2.0, 2.0]. Los valores positivos reducen la repetición; los valores negativos la aumentan. Valores predeterminados de presence_penalty:
Escenarios: Los valores más altos son adecuados para escenarios que requieren diversidad o creatividad, como escritura creativa o lluvia de ideas. Los valores más bajos son adecuados para escenarios que requieren consistencia o precisión técnica, como documentos técnicos. |
seed | integer | Hace que la generación sea más determinista, asegurando resultados consistentes entre ejecuciones. Pasar la misma semilla con parámetros idénticos produce el mismo resultado en la medida de lo posible. Valores válidos: 0 a 231−1. Valor predeterminado: -1. |
Interfaces clave
Clase OmniRealtimeConversation
Importe con from dashscope.audio.qwen_omni import OmniRealtimeConversation.
Firma del método | Evento de respuesta del lado del servidor (entregado mediante callback) | Descripción |
|---|---|---|
|
| Crea una conexión con el servidor. |
|
| Actualiza la configuración de la sesión. Para obtener detalles sobre los parámetros, consulte Parámetros de solicitud. Después de conectarse, el servidor devuelve configuraciones de sesión predeterminadas. Llame a este método inmediatamente después de conectarse para actualizar la configuración. Cuando el servidor recibe el evento |
| None | Anexa audio codificado en Base64 al búfer de entrada en la nube. El búfer es un almacenamiento temporal en el que se puede escribir y confirmar posteriormente.
|
| None | Agrega datos de imagen codificados en Base64 al búfer de video en la nube. Acepta imágenes locales o capturas de transmisiones de video en tiempo real. Límites de entrada de imagen:
|
|
| Elimina el audio del búfer en la nube actual. |
|
| Confirma el audio y el video desde el búfer en la nube. Devuelve un error si el búfer está vacío.
Nota:
|
|
response.audio_transcript.delta
response.audio_transcript.done
| Indica al servidor que cree una respuesta del modelo. Cuando configura una sesión en modo "turn_detection", el servidor crea automáticamente una respuesta del modelo. |
| None | Cancela la respuesta en curso. Si no hay ninguna respuesta que cancelar, el servidor responde con un error. |
| None | Envía un evento Para un resultado de herramienta de Function Calling,
Para la aprobación de MCP, el mismo evento utiliza |
| None | Finaliza la tarea y cierra la conexión. |
| None | Obtiene el session_id de la tarea actual. |
| None | Obtiene el response_id de la última respuesta. |
Clase de configuración AudioFormatConfig
Importe AudioFormatConfig, AudioFormatType y AudioSampleRate desde dashscope.audio.qwen_omni. La clase establece el formato de audio y la frecuencia de muestreo juntos. Se aplica a qwen3.5-omni-plus-realtime y qwen3.5-omni-flash-realtime.
En una OmniRealtimeConversation ya conectada, use valores enum o valores literales:
from dashscope.audio.qwen_omni import (
AudioFormatConfig, AudioFormatType, AudioSampleRate, MultiModality,
)
# Option 1: use enum values.
conversation.update_session(
output_modalities=[MultiModality.AUDIO, MultiModality.TEXT],
voice="Tina",
input_audio_config=AudioFormatConfig(
type=AudioFormatType.PCM,
sample_rate=AudioSampleRate.SAMPLE_RATE_16K,
),
output_audio_config=AudioFormatConfig(
type=AudioFormatType.WAV,
sample_rate=AudioSampleRate.SAMPLE_RATE_24K,
),
)
# Option 2: use literal values.
conversation.update_session(
output_modalities=[MultiModality.AUDIO, MultiModality.TEXT],
voice="Tina",
input_audio_config=AudioFormatConfig(type="pcm", sample_rate=16000),
output_audio_config=AudioFormatConfig(type="wav", sample_rate=24000),
)
Interfaz de callback (OmniRealtimeCallback)
El servidor devuelve eventos de respuesta y datos mediante callbacks. Implemente métodos de callback para procesar las respuestas del servidor.
Importe con from dashscope.audio.qwen_omni import OmniRealtimeCallback.
Método | Parámetros | Valor de retorno | Descripción |
|---|---|---|---|
| None | None | Llamado después de establecer la conexión con el servidor. |
| message: Un evento de respuesta del lado del servidor. | None | Contiene respuestas de llamadas a la interfaz y texto y audio generados por el modelo. Consulte Eventos del lado del servidor. |
| close_status_code: El código de estado para cerrar el WebSocket. close_msg: El mensaje de cierre para el WebSocket. | None | Llamado después de que el servidor cierra la conexión. |
FAQ
P: ¿Cómo alineo el audio de entrada y las imágenes?
El modelo en tiempo real Qwen-Omni utiliza la transmisión de audio como línea de tiempo de entrada. Las imágenes se insertan en la transmisión de audio según el momento en que se envían. Puede agregar imágenes en cualquier punto de la línea de tiempo de audio.
En escenarios de interacción en tiempo real, puede habilitar o deshabilitar la entrada de video en cualquier momento.
P: ¿Cuál es la frecuencia recomendada para ingresar imágenes y audio?
En escenarios de interacción en tiempo real, recomendamos enviar imágenes a una tasa de cuadros de 1 o 2 fps y enviar audio en paquetes de 100 ms.
P: ¿Cuáles son las diferencias entre los dos modos del interruptor turn_detection?
Cuando turn_detection está habilitado, admite dos modos: server_vad y semantic_vad:
-
Habilitar "turn_detection":
- Estado de entrada: El VAD basado en la nube detecta el final de una oración en el audio de entrada y activa inmediatamente la inferencia de Qwen-Omni para devolver el texto y el habla de respuesta.
- Estado de respuesta: En este estado, puede continuar enviando entradas de audio y video sin interrupción mientras el modelo responde. Una vez completada la respuesta, el estado vuelve al estado de entrada para esperar la siguiente entrada de voz.
- Interrupción: Si el usuario comienza a hablar mientras el modelo responde, se activa una interrupción. El servicio detiene inmediatamente la respuesta actual y cambia al estado de entrada.
-
Deshabilitar "turn_detection":
- Debe determinar manualmente el final de una ronda de entrada de audio y video y activar la inferencia de Qwen-Omni para obtener una respuesta utilizando commit y create_response.
- Mientras el modelo responde, debe dejar de enviar entradas de audio y video. Solo puede reanudar la entrada para la siguiente ronda después de que el modelo haya terminado de responder.
- Debe usar el método cancel_response para interrumpir la respuesta del modelo.
Tenga en cuenta que cuando turn_detection está habilitado, aún puede activar activamente una respuesta usando commit y create_response, e interrumpirla activamente usando cancel_response.
P: ¿Por qué necesito seleccionar otro modelo para input_audio_transcription?
Qwen-Omni real-time es un modelo multimodal de extremo a extremo. Su salida de texto es una respuesta a la entrada, no una transcripción directa del audio de entrada. Se requiere un modelo ASR independiente para la transcripción. Actualmente, el modelo está determinado por la configuración integrada y no es configurable.