Alibaba Cloud Model Studio:Guía de conexión WebSocket

Obtenga información sobre los endpoints de WebSocket, los flujos de interacción y los SDK para los modelos Qwen-Omni-Realtime.

Endpoints de conexión

Modelos compatibles: qwen3.8-omni-flash-realtime, qwen3.5-omni-plus-realtime y qwen3.5-omni-flash-realtime.

China (Beijing)

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime

Singapore

wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime

Reemplace {WorkspaceId} con el ID del espacio de trabajo para la región seleccionada y establezca model en el modelo al que desea llamar. Para autenticación y requisitos previos, consulte Visión general de conexión.

Flujo de trabajo de conexión

Modo VAD

Para habilitar el modo VAD, establezca el parámetro session.turn_detection.type del evento del cliente en "server_vad". En este modo, el servidor realiza la detección de actividad de voz (VAD) en el audio entrante y responde cuando detecta habla. Este modo es el predeterminado y está diseñado para escenarios donde el cliente envía audio continuamente al servidor.

• El servidor envía el evento input_audio_buffer.speech_started cuando detecta el inicio del habla.
• El cliente puede añadir audio al búfer en cualquier momento enviando un evento input_audio_buffer.append.
• El servidor envía el evento input_audio_buffer.speech_stopped cuando detecta el final del habla.
• El servidor confirma el búfer de audio de entrada enviando un evento input_audio_buffer.committed.
• El servidor envía un evento conversation.item.created, que contiene el elemento de mensaje de usuario creado a partir del búfer de audio.

Flujo de Function Calling

En el modo VAD, cuando una respuesta requiere que el cliente ejecute una herramienta de Function Calling, utilice este flujo:

• Después de detectar el final del habla y generar una respuesta, el servidor determina que se requiere una llamada a herramienta.
• El servidor envía un evento response.function_call_arguments.delta, que contiene datos incrementales para los argumentos de la llamada a la herramienta.
• El servidor envía un evento response.function_call_arguments.done para indicar que se han enviado todos los argumentos de la llamada a la herramienta.
• El cliente ejecuta la llamada a la herramienta y obtiene el resultado.
• El cliente envía un evento conversation.item.create que contiene el resultado de la llamada a la herramienta.
• El cliente envía un evento response.create para activar una respuesta basada en el resultado de la llamada a la herramienta.

Modo manual

Para habilitar el modo manual, establezca el parámetro session.turn_detection del evento del cliente en null. En este modo, el cliente solicita una respuesta del servidor enviando explícitamente los eventos input_audio_buffer.commit y response.create. Este modo es adecuado para escenarios de pulsar para hablar, como el envío de mensajes de voz en aplicaciones de chat.

• El cliente puede añadir audio al búfer enviando un evento input_audio_buffer.append.
• El cliente confirma el búfer de audio de entrada enviando un evento input_audio_buffer.commit. Esta confirmación crea un nuevo elemento de mensaje de usuario en la conversación.
• El servidor responde enviando un evento input_audio_buffer.committed.
• El cliente envía un evento response.create para activar el modelo y generar la respuesta final.
• El servidor responde enviando un evento conversation.item.created.

Flujo de Function Calling

En el modo Manual, cuando una respuesta requiere que el cliente ejecute una herramienta de Function Calling, utilice este flujo:

• Después de que el cliente envía un evento response.create, el servidor genera una respuesta y detecta que se requiere una llamada a herramienta.
• El servidor envía un evento response.function_call_arguments.delta, que contiene datos incrementales para los argumentos de la llamada a la herramienta.
• El servidor envía un evento response.function_call_arguments.done para indicar que la transferencia de argumentos de la llamada a la herramienta ha finalizado.
• El cliente ejecuta la llamada a la herramienta y obtiene el resultado.
• El cliente envía el resultado de la llamada a la herramienta mediante un evento conversation.item.create.
• El cliente envía un evento response.create para activar el modelo y generar la respuesta final.
• El servidor genera una respuesta basada en el resultado de la llamada a la herramienta y la envía al cliente mediante eventos response.audio.delta o response.text.delta.

Llamadas a herramientas MCP

Este flujo se aplica a Qwen3.8-Omni-Flash-Realtime con modo VAD o Manual.

Function Calling y MCP se pueden configurar juntos en session.tools. No se pueden utilizar con la búsqueda web (enable_search). Model Studio no cobra una tarifa adicional por la invocación de herramientas MCP. La inferencia del modelo sigue sujeta a los precios del modelo.

Descubrimiento de herramientas

Después de que el cliente configura los servidores MCP con session.update, el servicio Realtime descubre sus herramientas de forma asíncrona:

En los diagramas de secuencia de esta sección, opt indica ejecución cuando se cumple una condición, alt indica ramas alternativas seleccionadas por condición y par indica procesamiento paralelo.

1. Envíe session.update con entradas MCP en session.tools.
2. Gestione mcp_list_tools.in_progress, que puede llegar antes de session.updated. session.updated confirma la aceptación de la configuración, no la disponibilidad de herramientas.
3. El servicio descubre herramientas. Envía conversation.item.created con un elemento mcp_list_tools, seguido de mcp_list_tools.completed o mcp_list_tools.failed con el mismo item_id. El elemento contiene las herramientas filtradas finales o un error.

La entrada de audio y response.create pueden continuar durante el descubrimiento, pero solo las respuestas creadas después de que finalice el descubrimiento pueden utilizar las herramientas correspondientes.

Llamadas MCP y continuación

Cuando el modelo selecciona una herramienta MCP, el servicio Realtime ejecuta la llamada. Si se requiere aprobación, el cliente primero responde a la solicitud de aprobación:

1. El servidor crea un elemento mcp_call a través de response.output_item.added.
2. Concatene cero o más fragmentos de response.mcp_call_arguments.delta. Utilice la cadena JSON completa en response.mcp_call_arguments.done como autoritativa.
3. Cuando se requiere aprobación, maneje conversation.item.created con item.type="mcp_approval_request". Decida si permite la llamada y responda con conversation.item.create, item.type="mcp_approval_response", el item.id exacto de la aprobación y el valor booleano approve. La aprobación es obligatoria de forma predeterminada.
4. Las llamadas aprobadas, o las llamadas configuradas para no requerir aprobación, emiten response.mcp_call.in_progress. El servicio ejecuta la llamada MCP y luego emite response.mcp_call.completed o response.mcp_call.failed. El rechazo o el tiempo de espera de aprobación emite failed sin ejecución.
5. Consuma response.output_item.done para el elemento de llamada final. El evento padre response.done llega después de que cada elemento MCP en esa respuesta alcance un estado terminal. Su response.output incluye instantáneas finales: las llamadas exitosas tienen completed y output; las llamadas fallidas tienen failed y error.
6. Para generar una respuesta del modelo a partir de los resultados MCP, envíe un response.create después del response.done principal. No adjunte resultados MCP: ya están en la conversación. No utilice el flujo de retorno manual de function_call_output para estas llamadas MCP ejecutadas por el servidor.

Consulte configuración de MCP del cliente, respuestas de aprobación, eventos del servidor MCP y elementos de conversación MCP.

Límites de uso

Las siguientes restricciones predeterminadas de MCP se aplican a cada sesión:

Elemento	Valor predeterminado
Servidores MCP	8
Herramientas MCP	128
Tiempo de espera de descubrimiento de herramientas	30 segundos
Tiempo de espera de aprobación	60 segundos
Tiempo de espera de ejecución de herramientas	30 segundos
Tamaño de respuesta única ascendente	2 MB
Tamaño acumulado de resultados de herramientas	8 MB
Llamadas a herramientas acumuladas	256

SDK

• SDK de Python
• SDK de Java