Conozca el flujo de trabajo del SDK de cliente AOQ: obtención de credenciales, inicialización del SDK, configuración de direcciones de medios, conexión, intercambio de eventos del modelo y liberación de recursos.
AOQ transmite audio, video y eventos del modelo en pistas separadas. El SDK gestiona la captura, codificación, decodificación, transporte y reproducción de medios. Su aplicación envía eventos del modelo y gestiona las respuestas a través de pistas de datos. Seleccione las direcciones de medios y el protocolo de eventos requeridos por su modelo objetivo.
Requisitos previos
-
Complete los preparativos en Resumen de conexión y confirme el modelo objetivo, la región y la compatibilidad con AOQ.
-
Importe el SDK correspondiente a su plataforma desde Descarga del SDK. Importe el complemento correspondiente si utiliza Opus.
-
Implemente la Autenticación por token en su servidor de aplicaciones (AppServer). Mantenga la clave API en AppServer y proporcione credenciales de conexión temporales al cliente.
NotaSolicite permiso para el micrófono o la cámara solo si se requiere captura. Por ejemplo, la síntesis de voz no requiere ninguno de estos permisos.
Flujo de trabajo
- Obtener credenciales de conexión a través de AppServer.
- Crear el motor del SDK y registrar las devoluciones de llamada.
- Configurar las pistas de medios y de Datos, y deshabilitar la transmisión de medios en enlace ascendente.
- Establecer la conexión AOQ y esperar a que se conecte.
- Configurar el modelo según su protocolo. Habilitar los medios en enlace ascendente requeridos tras la confirmación.
- Desconectar y liberar recursos cuando finalice la interacción.
Nota
-
El SDK de AOQ gestiona la captura, procesamiento, transmisión, recepción y reproducción de medios. Su aplicación debe enviar y recibir mensajes de datos conforme a las definiciones de eventos del modelo objetivo.
-
Una conexión exitosa significa que se ha establecido el canal de transporte hacia el modelo. Si su aplicación requiere operaciones preliminares, como configurar una voz, complete la configuración del modelo antes de enviar medios. Por ejemplo, los modelos Realtime deben esperar
session.updatedy los modelos Inference deben esperartask-started. El cliente puede habilitar los medios ascendentes necesarios solo después de que la inicialización del modelo se haya completado correctamente.
1. Obtener credenciales de conexión
El cliente solicita credenciales a AppServer. AppServer selecciona el punto de conexión de Realtime o Inference para el modelo objetivo y envía la clave API y el encabezado x-dashscope-rtc-transport: moq a la puerta de enlace. Para consultar puntos de conexión, solicitudes y campos, véase Autenticación por token.
Asigne la respuesta a AoqConnectConfig:
| Respuesta de la puerta de enlace | Configuración del SDK |
|---|---|
aoqTokenForClient | token |
sid | sid |
clientRelayCertFingerprint | certFingerprint |
clientRelayEndpoints | relayEndpoints: convertir cada endpoint a la estructura requerida |
extraInfo.workspaceIdHash | workspaceIdHash |
Obtenga nuevas credenciales para cada nueva conexión. La posibilidad de reutilizar una sesión o iniciar otra tarea dentro de la misma conexión depende del protocolo del modelo objetivo.
2. Inicializar el SDK y registrar devoluciones de llamada
Cree el motor y registre callbacks para el estado de la conexión, mensajes de datos y errores. El siguiente ejemplo utiliza Swift en iOS:
let createConfig = AoqCreateConfig()
createConfig.workDir = workDir
createConfig.enableDumpAudio = false
engine = AoqClientEngine.createEngine(createConfig, delegate: self)
Implemente AoqEngineDelegate: mantenga el estado de la conexión en onConnectionStatusChange, analice los eventos del modelo en onDataMsg y gestione los errores del SDK en onError. Gestione los eventos de error del modelo por separado en el manejador de mensajes de datos. Para consultar las interfaces y errores del SDK, véase SDK de cliente AOQ.
3. Configurar el SDK
Seleccionar direcciones de medios
Las direcciones son relativas al cliente. Configure únicamente las modalidades de entrada y salida que su aplicación necesite. No agregue pistas para direcciones no utilizadas.
| Dirección | Configuración | Uso típico |
|---|---|---|
| Enviar audio | Publicar una pista de Audio, configurar el codificador y utilizar la captura integrada o externa | Reconocimiento de voz, conversación y traducción |
| Recibir audio | Suscribirse a una pista de Audio, configurar el decodificador y utilizar la reproducción integrada o externa | Síntesis de voz y respuestas habladas |
| Enviar video | Publicar una pista de Video y configurar la cámara o entrada externa y la codificación | Proporcionar imágenes a un modelo que admita entrada visual |
| Recibir video | Configure la suscripción y recepción solo si el modelo o la aplicación objetivo admite explícitamente la salida de video | Seguir la documentación del modelo o aplicación objetivo |
Las pistas de datos son independientes de estas cuatro direcciones: publique una pista de datos para enviar eventos del modelo y suscríbase para recibir respuestas. La entrada y salida de texto también requieren pistas de datos.
Elegir direcciones para su modelo
La siguiente tabla enumera las configuraciones típicas. Para consultar los modelos y versiones compatibles, véase Resumen de la API en tiempo real y la documentación del modelo.
| Modelo o aplicación | Enviar audio | Recibir audio | Enviar video | Recibir video |
|---|---|---|---|---|
| Qwen-Omni-Realtime | Para entrada de voz | Para respuestas habladas | Para entrada visual | No compatible |
| Qwen-Audio-Realtime | Para conversaciones de voz | Para respuestas habladas | No compatible | No compatible |
| Qwen-Audio-TTS, CosyVoice | No compatible | Enabled | No compatible | No compatible |
| Qwen-Audio-ASR-Streaming, Qwen-Audio-ASR-Message | Enabled | No compatible | No compatible | No compatible |
| Fun-ASR-Realtime | Enabled | No compatible | No compatible | No compatible |
| Qwen-LiveTranslate-Realtime | Para entrada de voz | Para traducciones habladas | Depende de la versión y el escenario | No compatible |
| multimodal-dialog | Basado en la entrada de la aplicación | Basado en la salida de la aplicación | Basado en las capacidades de la aplicación | Solo si la aplicación lo admite explícitamente |
Configurar parámetros de medios y pistas
Configure el audio ascendente y descendente por separado: utilice setAudioEncoderConfig para el audio ascendente y setAudioDecoderConfig para el audio descendente. Estos parámetros controlan la transmisión de red; la puerta de enlace convierte el audio al formato requerido por el modelo. Configure la codificación de transporte y el formato de audio en los eventos del modelo según los requisitos del SDK y del modelo objetivo, respectivamente.
Inicie startAudioCapture, startAudioPlayer o startVideoCapture según sea necesario. Para entradas y salidas personalizadas, consulte Funciones avanzadas a continuación.
publishTracks son enviados por el cliente, y subscribeTracks son recibidos por el cliente:
| Escenario | publishTracks | subscribeTracks |
|---|---|---|
| Conversación de voz | Audio, Datos | Audio, Datos |
| Conversación de voz con entrada visual | Audio, Video, Datos | Audio, Datos |
| Reconocimiento de voz | Audio, Datos | Data |
| Síntesis de voz | Data | Audio, Datos |
Deshabilite los medios en enlace ascendente antes de conectarse para evitar que la entrada llegue al modelo antes de que esté listo:
engine.enableSendMediaStream(.audio, enable: false)
engine.enableSendMediaStream(.video, enable: false)
La captura, la publicación de pistas y el permiso para enviar son operaciones separadas. Deshabilitar la transmisión no detiene la captura local ni afecta los eventos de datos. Habilitar la transmisión no crea pistas que no hayan sido agregadas.
4. Establecer la conexión
Rellene AoqConnectConfig con las credenciales y la configuración de pistas, y luego llame a:
engine.connect(connectConfig)
Espere .connected en onConnectionStatusChange antes de inicializar el modelo. Un retorno de connect no significa que la conexión se haya establecido correctamente.
5. Intercambiar eventos del modelo y medios
Enviar y analizar eventos del modelo
Enviar eventos a través de la pista de Datos. Ejemplo para Swift en iOS:
// Build eventJSON according to the target model client event protocol.
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)
Analice las respuestas en onDataMsg. No asuma que todos los eventos utilizan type: los eventos en tiempo real suelen usar type, mientras que los eventos del servidor de inferencia usan header.event. Consulte la documentación del modelo objetivo para conocer los campos, parámetros y condiciones de finalización.
Habilitar medios después de que el modelo esté listo
Una vez que el modelo, la sesión o la tarea actuales cumplan sus condiciones de preparación, habilite solo las direcciones ascendentes configuradas. Para la entrada de voz, llame a:
engine.enableSendMediaStream(.audio, enable: true)
Habilite .video solo si se requiere entrada de video. TTS acepta entrada de texto y no requiere audio ni video en enlace ascendente.
Transmita audio y video en sus pistas de medios, y eventos del modelo y texto en pistas de datos. Por ejemplo, Omni sobre AOQ no requiere input_audio_buffer.append ni input_image_buffer.append para volver a enviar los mismos medios. Gestione el audio descendente con el reproductor configurado o con lógica de reproducción externa.
6. Finalizar la interacción y liberar recursos
Cuando la conexión ya no sea necesaria, llame a las interfaces de desconexión y liberación de recursos del SDK de AOQ desde su aplicación:
engine.disconnect()
AoqClientEngine.destroy()
Tras una desconexión inesperada, borre el estado de preparación de la aplicación y siga Gestión del estado de conexión. Inicialice el modelo nuevamente después de volver a conectarse.
Enviar y recibir eventos a través de pistas de Datos
Publique y suscríbase a pistas de datos al conectarse. Para enviar un evento, serialícelo en AoqDataMsg y llame a engine.send(msg). Analice los mensajes recibidos en onDataMsg.
Siga las definiciones de eventos del cliente del modelo objetivo para los nombres, campos, parámetros y tiempos de los eventos salientes. Siga sus definiciones de eventos del servidor para el análisis de respuestas, cambios de estado, resultados y errores. Envíe eventos de inicialización según lo requiera el modelo, así como eventos de texto y control posteriores según lo requiera su aplicación.
| Modelo o aplicación | Eventos del cliente (envío) | Eventos del servidor (recepción) |
|---|---|---|
| Qwen-Omni-Realtime | Eventos del cliente | Eventos del servidor |
| Qwen-Audio-Realtime | Eventos del cliente | Eventos del servidor |
| Qwen-Audio-TTS, CosyVoice | Eventos del cliente | Eventos del servidor |
| Qwen-Audio-ASR-Streaming | Eventos del cliente | Eventos del servidor |
| Qwen-Audio-ASR-Message | Eventos del cliente | Eventos del servidor |
| Fun-ASR-Realtime | Eventos del cliente | Eventos del servidor |
| Qwen-LiveTranslate-Realtime | Eventos del cliente | Eventos del servidor |
| multimodal-dialog | Mensaje de entrada en el protocolo de interacción | Mensaje de salida en el protocolo de interacción |
El conjunto de interacción multimodal define ambas direcciones en un único protocolo de interacción. Seleccione las definiciones de eventos correspondientes a la versión real del modelo; los modelos no comparten un esquema de eventos fijo.
Siga también estas reglas:
-
Identifique los tipos de eventos y los identificadores de correlación según el modelo. Los eventos en tiempo real suelen utilizar
type; los clientes de inferencia usanheader.action, los servidores usanheader.eventy las tareas se correlacionan mediantetask_id. -
Gestione la confirmación de inicialización, el envío de entradas, la cancelación de respuestas y la finalización de tareas a través de pistas de datos según lo requiera el protocolo. Estas operaciones son distintas del cierre de la conexión de transporte.
-
Por ejemplo, los modelos de inferencia utilizan
finish-taskpara finalizar una tarea ytask-finishedpara confirmar su finalización. Reciba cualquier resultado restante antes de liberar la conexión. Si se requiere una reproducción completa, drene también el audio local pendiente. -
Los medios utilizan pistas de medios. Al consultar la documentación de eventos del modelo, siga esta página de AOQ para el transporte de medios y los modos de interacción disponibles; no copie los mecanismos de carga de medios de WebSocket.
Funciones avanzadas
| Capacidad | Caso de uso | Documentación |
|---|---|---|
| Controlar la transmisión de audio y video por separado | Esperar a que el modelo esté listo, pausar los medios en enlace ascendente o habilitar el video según sea necesario | Gestión de la transmisión de medios |
| Dispositivos de audio y procesamiento | Codificación, decodificación, altavoces, mezcla de archivos y devoluciones de llamada de tramas de audio | Funciones comunes de audio |
| Entrada de audio externa | Utilizar una fuente de audio proporcionada por la aplicación | Captura de audio personalizada |
| Salida de audio externa | Procesar o reproducir audio de salida en su aplicación | Reproducción de audio personalizada |
| Captura y entrada de video | Utilizar una cámara o imágenes proporcionadas por la aplicación | Funciones de video comunes, Entrada de video personalizada |
Los controles de transmisión de medios afectan únicamente a los medios. La cancelación de respuestas del modelo y el envío de turnos aún requieren los eventos del modelo objetivo.
Mejores prácticas
-
Llamadas en tiempo real Omni: entrada de audio/video, respuestas habladas y eventos de sesión.
-
Pulsar para hablar Omni: entrada controlada por botón y turnos manuales.
-
Conversaciones de voz de Qwen-Audio: audio bidireccional.
-
Síntesis de voz de Qwen-Audio: entrada de texto en pistas de datos y salida de voz en pistas de audio.
-
Reconocimiento de voz de Fun-ASR: entrada de audio en pistas de audio y resultados de reconocimiento en pistas de datos.