Skip to main content

SDK de Java de Qwen-Omni-Realtime

Las interfaces clave y los parámetros de solicitud para el SDK de Java DashScope en tiempo real de Qwen-Omni.

Para la conexión y la autenticación, consulte Conexión mediante WebSocket. Para consultar los campos de eventos y los ejemplos JSON, consulte Eventos del cliente y Eventos del servidor.

Requisitos previos

Su versión del SDK de Java debe ser v2.22.15 o posterior. Antes de comenzar, consulte el 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 Java, consulte la guía de tiempo real. Descargue el código de ejemplo de GitHub. Hay tres métodos de llamada disponibles:
  1. Ejemplo de conversación de audio: Captura audio en tiempo real desde un micrófono, habilita el modo de Detección de Actividad de Voz (VAD), que detecta automáticamente el inicio y el final del habla, y admite interrupción de voz.
    Establezca el parámetro enableTurnDetection en true.
    Utilice auriculares para la reproducción de audio y evitar que los ecos provoquen interrupciones de voz.
  2. Ejemplo de conversación de audio y video: Captura audio y video en tiempo real desde un micrófono y una cámara, habilita el modo VAD y admite interrupción de voz.
    Establezca el parámetro enableTurnDetection en true.
    Utilice auriculares para la reproducción de audio y evitar que los ecos provoquen interrupciones de voz.
  3. 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.
    Establezca el parámetro enableTurnDetection en false.

Parámetros de solicitud

Configure los siguientes parámetros de solicitud mediante los métodos encadenados o setters del objeto OmniRealtimeParam y, a continuación, páselo al constructor OmniRealtimeConversation.

Parámetro

Tipo

Descripción

model

String

El modelo Qwen-Omni a utilizar. Consulte la Lista de modelos.

url

String

La URL del endpoint:

  • Región de Singapur: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime

  • Región de Pekín: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Alibaba 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.com a wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapur: de wss://dashscope-intl.aliyuncs.com a wss://{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 mediante los métodos encadenados o setters del objeto OmniRealtimeConfig y, a continuación, páselo al método updateSession.
ParámetroTipoDescripción
modalitiesList<OmniRealtimeModality>La modalidad de salida del modelo. Configure [OmniRealtimeModality.TEXT] para solo texto, o [OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO] para audio y texto.
voiceStringLa voz para la salida de audio. Para ver las voces compatibles, consulte la Lista de voces.Voz predeterminada:
  • Modelo de la serie Qwen3.5-Omni: "Tina"
  • qwen3-omni-flash-realtime-2025-09-15: "Cherry"
inputAudioFormatOmniRealtimeAudioFormatEl formato del audio de entrada del usuario. Actualmente solo admite PCM_16000HZ_MONO_16BIT, que representa una transmisión de audio PCM con una tasa de muestreo de 16 kHz.
outputAudioFormatOmniRealtimeAudioFormatEl formato del audio de salida del modelo. Actualmente solo admite PCM_24000HZ_MONO_16BIT, que representa una transmisión de audio PCM con una tasa de muestreo de 24 kHz.
instructionsStringUn mensaje del sistema que establece el objetivo o rol para el modelo.Ejemplo: "Usted es un agente de servicio al cliente 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 de manera precisa y amable. Responda siempre de forma profesional y útil. No proporcione información no verificada o fuera del alcance de los servicios del hotel".
Configure instructions mediante el método parameters de la instancia OmniRealtimeConfig:
conversation.updateSession(OmniRealtimeConfig.builder()
        .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
        .voice("Tina")
        .enableTurnDetection(true)
        .enableInputAudioTranscription(true)
        .parameters(Map.of(
                "instructions", "You are a personal assistant named Xiaoyun"
        ))
        .build()
);
smooth_outputBooleanEste parámetro solo es compatible con qwen3-omni-flash-realtime-2025-09-15.
  • true: El modelo proporciona respuestas conversacionales.
  • false: El modelo proporciona respuestas más formales, al estilo escrito.
    Sin embargo, el rendimiento puede ser subóptimo si el contenido es difícil de leer en voz alta.
  • null: El valor predeterminado. El modelo elige automáticamente entre estilos de respuesta conversacional y formal.
Configure smooth_output mediante el método parameters de la instancia OmniRealtimeConfig. El uso es el mismo que para instructions.
enableInputAudioTranscriptionBooleanHabilita el reconocimiento de voz para el audio de entrada.
InputAudioTranscriptionStringModelo 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.
enableTurnDetectionBooleanHabilita VAD. Si está deshabilitado, debe enviar manualmente el audio para crear una respuesta.
turnDetectionTypeStringEl tipo de VAD. Valores válidos:
  • server_vad (predeterminado): Detecta el final del habla del usuario basándose en características acústicas.
  • semantic_vad: Detecta el final del habla del usuario basándose en la validez semántica. Este modo puede filtrar habla sin sentido, como retroalimentaciones verbales y ruido de fondo. Esta opción es compatible con Qwen3.8-Omni-Flash-Realtime y la serie Qwen3.5-Omni-Realtime.
turnDetectionThresholdFloatUmbral de detección de VAD. Auméntelo en entornos ruidosos y redúzcalo en entornos silenciosos.
  • Cuanto más se acerque el valor a -1, mayor será la probabilidad de que el ruido se detecte como habla.
  • Cuanto más cerca esté el valor de 1, menos probable será que el ruido se detecte como habla.
Predeterminado: 0.5. Valores válidos: [-1.0, 1.0].
turnDetectionSilenceDurationMsIntegerDuración de silencio que indica el final del habla. Si se supera, el modelo activa una respuesta. Predeterminado: 800. Valores válidos: [200, 6000].
turnDetectionParamMapaParámetros de configuración adicionales de turn_detection. Actualmente admite idle_timeout_ms (Integer): el tiempo de espera de inactividad en milisegundos. Se aplica solo aqwen3.5-omni-plus-realtimeyqwen3.5-omni-flash-realtimemodelos enserver_vadmodo. Después de que el servidor finaliza la reproducción de audio y el usuario permanece en silencio más allá de esta duración (sin que se active speech.started), el modelo genera proactivamente una respuesta para indicar al usuario que continúe la conversación. Rango válido: [5000, 30000].Ejemplo: turnDetectionParam(Map.of("idle_timeout_ms", 5000))
enable_searchBooleanAplica a los modelos Qwen3.8-Omni-Flash-Realtime y Qwen3.5-Omni-Realtime.Habilita la búsqueda web. Predeterminado: false. Cuando está habilitado, el modelo puede buscar en la web para responder preguntas en tiempo real.
Los parámetros enable_search y search_options deben configurarse mediante el método parameters de la instancia OmniRealtimeConfig. El proceso es el mismo para instructions.
La llamada a herramientas (tools) y la búsqueda web (enable_search) son incompatibles y no pueden habilitarse al mismo tiempo.
search_optionsObjectConfiguración de opciones de búsqueda web. Este parámetro solo surte efecto después de habilitar enable_search. Puede configurar enable_source (Boolean) en true para devolver una lista de fuentes de resultados de búsqueda.
search_options mediante el método parameters de la instancia OmniRealtimeConfig. El uso es el mismo que para instructions.
toolsList<Map<String, Object>>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. tools y enable_search son mutuamente excluyentes, incluidas las herramientas MCP.Los siguientes campos describen las herramientas de Function Calling. Cada herramienta es un Map que contiene los siguientes campos:
  • type (String, obligatorio): El valor es fijo en "function".
  • function (Map, obligatorio): La definición de la función de la herramienta. Este campo contiene los siguientes subcampos:
    • name (String, obligatorio): Un nombre personalizado para la función de la herramienta. Le recomendamos usar el mismo nombre que la función, como get_current_weather o get_current_time.
    • description (String, opcional): Una descripción de la función de la herramienta. El modelo utiliza esta descripción para decidir si llama a la función.
    • parameters (Map, opcional): Descripciones de parámetros de entrada. El modelo las utiliza para extraer parámetros. Si la función de la herramienta no requiere parámetros de entrada, no necesita especificar este campo. Este campo contiene los siguientes subcampos:
      • type (String, obligatorio): El valor es fijo en "object".
      • properties (Map, opcional): Describe el nombre, el tipo de datos y la descripción de cada parámetro de entrada. La clave es el nombre del parámetro y el valor es un Map que contiene el tipo de datos (type) y la descripción (description).
      • required (List, opcional): Especifica qué parámetros de entrada son obligatorios.
search_options mediante el método parameters de la instancia OmniRealtimeConfig. El uso es el mismo que para instructions.
temperatureFloatTemperatura 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.Valores predeterminados de temperature:
  • qwen3.8-omni-flash-realtime: 0.6
  • Modelo de la serie Qwen3.5-Omni-Realtime: 0.7
  • qwen3-omni-flash-realtime-2025-09-15: 0.9
Parámetro temperature mediante el método parameters de la instancia OmniRealtimeConfig, de la misma manera que configura el parámetro instructions.
top_pFloatUmbral 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:
  • qwen3.8-omni-flash-realtime: 0.95
  • Modelo de la serie Qwen3.5-Omni-Realtime: 0.8
  • qwen3-omni-flash-realtime-2025-09-15: 1.0
top_p mediante el método parameters de la instancia OmniRealtimeConfig. El uso es el mismo que para instructions.
top_kIntegerTamañ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:
  • qwen3.8-omni-flash-realtime: 20
  • Modelo de la serie Qwen3.5-Omni-Realtime: 20
  • qwen3-omni-flash-realtime-2025-09-15: 50
top_k mediante el método parameters de la instancia OmniRealtimeConfig. El uso es el mismo que para instructions.
max_tokensIntegerNúmero máximo de tokens a devolver.
La configuración de max_tokens no afecta el proceso de generación del modelo. Si el número de tokens generados por el modelo excede max_tokens, el contenido devuelto se trunca.
Para qwen3.8-omni-flash-realtime, el rango válido es [1, 65536]. Para otros modelos, los valores predeterminados y máximos equivalen a la longitud máxima de salida del modelo. Consulte la Lista de modelos para más detalles.Utilice max_tokens para limitar la longitud de salida al generar resúmenes, palabras clave, controlar costos o reducir el tiempo de respuesta.
max_tokens mediante el método parameters de la instancia OmniRealtimeConfig. El uso es el mismo que para instructions.
repetition_penaltyFloatControla la repetición en secuencias generadas. Los valores más altos reducen la repetición. 1.0 significa sin penalización. qwen3.8-omni-flash-realtime también acepta 0. Para otros modelos, el valor debe ser mayor que 0.Valores predeterminados de repetition_penalty:
  • qwen3.8-omni-flash-realtime: 0
  • Modelo de la serie Qwen3.5-Omni-Realtime: 1.0
  • Otros modelos: 1.05
repetition_penalty mediante el método parameters de la instancia OmniRealtimeConfig. El uso es el mismo que para instructions.
presence_penaltyFloatControla 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:
  • qwen3.8-omni-flash-realtime: 1
  • Modelo de la serie Qwen3.5-Omni-Realtime: 1.5
  • Otros modelos: 0.0
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.
presence_penalty mediante el método parameters de la instancia OmniRealtimeConfig. El uso es el mismo que para instructions.
seedIntegerHace 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.
seed mediante el método parameters de la instancia OmniRealtimeConfig. El uso es el mismo que para instructions.

Interfaces clave

Clase OmniRealtimeConversation

Importe con import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;.
Firma del métodoEvento de respuesta del servidor (enviado mediante callback)Descripción
public void connect() throws NoApiKeyException, InterruptedException
Eventos del servidor
Sesión creada
session.updated
Configuración de sesión actualizada
Crea una conexión con el servidor.
public void updateSession(OmniRealtimeConfig config)
session.updated
Configuración de sesión actualizada
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 session.update, valida los parámetros. Los parámetros no válidos devuelven un error; de lo contrario, el servidor actualiza la configuración de la sesión.
public void appendAudio(String audioBase64)
NoneAnexa 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.
  • Si "turn_detection" está habilitado, el búfer de audio se utiliza para detectar el habla y el servidor decide cuándo confirmarlo.
  • Si "turn_detection" está deshabilitado, el cliente puede enviar hasta 15 MiB de audio por evento. Transmitir bloques más pequeños hace que el VAD sea más receptivo.
public void appendVideo(String videoBase64)
NoneAgrega 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:
  • El formato de imagen debe ser JPG o JPEG. La resolución de imagen recomendada es 480p o 720p, con un máximo de 1080p.
  • Una sola imagen después de la codificación Base64 no debe exceder 256 KB. Recomendamos mantener el tamaño de la imagen sin procesar por debajo de 190 KB antes de la codificación.
  • Los datos de la imagen deben estar codificados en Base64.
  • Le recomendamos enviar imágenes al servidor con una frecuencia de 1 imagen por segundo.
public void clearAppendedAudio()
input_audio_buffer.cleared
El audio recibido por el servidor se borra
Elimina el audio en el búfer en la nube actual.
public void commit()
input_audio_buffer.committed
El servidor recibió el audio confirmado
Confirma el audio y el video desde el búfer en la nube. Devuelve un error si el búfer está vacío.
  • Si "turn_detection" está habilitado, el cliente no necesita enviar este evento. El servidor confirma automáticamente el búfer de audio.
  • Si "turn_detection" está deshabilitado, el cliente debe confirmar el búfer de audio para crear un elemento de mensaje de usuario.
Nota:
  1. Si input_audio_transcription está configurado para la sesión, el sistema transcribe el audio.
  2. Confirmar el búfer de audio de entrada no genera una respuesta del modelo.
public void createResponse(String instructions, List<OmniRealtimeModality> modalities)
Eventos del servidor
El servidor comienza a generar una respuesta
response.output_item.added
Nuevo contenido de salida disponible en la respuesta
Eventos del servidor
Se crea un elemento de conversación
response.content_part.added
Se añade nuevo contenido de salida al elemento de mensaje del asistente
response.audio_transcript.delta
Texto transcrito generado incrementalmente
response.audio.delta
Audio generado incrementalmente por el modelo
response.audio_transcript.done
La transcripción de texto ha terminado
response.audio.done
La generación de audio ha terminado
response.content_part.done
La transmisión de contenido de texto o audio para el mensaje del asistente ha terminado
response.output_item.done
La transmisión del elemento de salida completo para el mensaje del asistente ha terminado
response.done
La respuesta está completa
Indica al servidor que cree una respuesta del modelo.Cuando la sesión está configurada en modo "turn_detection", el servidor crea automáticamente una respuesta del modelo.
public void cancelResponse()
NoneCancela la respuesta en curso. Si no hay ninguna respuesta disponible para cancelar, el servidor devuelve un error.
public void createItem(JsonObject item)
NoneEnvía el evento conversation.item.create al servidor.Para un resultado de herramienta de Function Calling, item es un JsonObject con estos campos:
  • type: Debe ser function_call_output.
  • call_id: Corresponde al call_id en el evento response.function_call_arguments.done.
  • output: Una cadena que representa el resultado de la ejecución de la herramienta.
Para la aprobación de MCP, el mismo evento utiliza item.type="mcp_approval_response". Consulte Respuesta de aprobación de MCP para ver sus campos.
public void close()
NoneDetiene la tarea y cierra la conexión.
public String getSessionId()
NoneObtiene el ID de sesión de la tarea actual.
public String getResponseId()
NoneObtiene el ID de respuesta de la respuesta más reciente.

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 import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;.
MétodoParámetroValor de retornoDescripción
public void onOpen()
NoneNoneSe llama inmediatamente después de establecer una conexión con el servidor.
public abstract void onEvent(JsonObject message)
message: El evento de respuesta del servidor.NoneContiene respuestas de llamadas a la interfaz y texto y audio generados por el modelo. Consulte Eventos del servidor.
public abstract void onClose(int code, String reason)
code: El código de estado para cerrar el WebSocket.reason: El motivo del cierre del WebSocket.NoneSe llama después de que se cierra la conexión con el servidor.

FAQ

P: ¿Cómo se alinean 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, le 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.