Use el SDK de Android de Qwen-Audio-Realtime para conversaciones de voz en tiempo real, con entrada de audio en tiempo real y salida de voz o texto.
Inicio rápido
- Obtenga y configure una clave de API.
-
Descargue el SDK y ejecute el código de ejemplo:
- Descargue el paquete más reciente del SDK.
- Extraiga el paquete ZIP. Obtenga el SDK AAR de
app/libsy agréguelo a las dependencias de su proyecto. Para la integración con Android C++, utiliceandroid_libsyandroid_includeen el paquete ZIP para obtener las bibliotecas dinámicas y los archivos de encabezado. - Abra el proyecto en Android Studio. El código de ejemplo se encuentra en
DashQwenAudioChatActivity.java. Reemplace la clave de API para probar la función.
Procedimiento de llamada
- Inicialice el SDK.
- Configure los parámetros para su caso de uso. Utilice el argumento
parametersde initialize para establecer los parámetros de conexión y control, y utilice setParams para establecer los parámetros de conversación de voz. - Llame a startDialog para iniciar la conversación.
- En onNuiAudioStateChanged, inicie el dispositivo de grabación según el estado del audio.
- Suministre continuamente datos de grabación en onNuiNeedAudioData, o llame a updateAudio para enviar activamente datos de grabación.
- Reciba continuamente el audio devuelto por el modelo en onNuiAssistEventCallback.
- Escuche los eventos y obtenga la información de los mismos en onNuiEventCallback.
- Llame a stopDialog para detener la conversación y escuche
EVENT_TRANSCRIBER_COMPLETEpara confirmar que ha finalizado. - Cuando ya no necesite la función de conversación, llame a release para liberar los recursos del SDK.
Parámetros de solicitud
Parámetros de conexión y control
Pase una cadena JSON en el argumento parameters de initialize.
Ejemplo: La siguiente cadena JSON no enumera todos los parámetros. Agregue los parámetros según sea necesario para su caso de uso.
El ejemplo usa qwen-audio-3.1-realtime-plus. Para usar otro modelo, actualice tanto model en la URL como nls_config.model en Parámetros de conversación de voz.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
url | String | Sí | Endpoint del servicio:
{WorkspaceId} con su ID de espacio de trabajo. |
apikey | String | Sí | Clave de API. |
service_mode | String | Sí | Modo de ejecución. Establezca este parámetro en "1" para conversaciones de voz en tiempo real. |
device_id | String | Sí | Una cadena única que identifica al usuario final. Puede utilizar un ID de usuario dentro de la aplicación o un identificador de dispositivo generado por el cliente. Este ID se utiliza principalmente para el rastreo de registros y la solución de problemas. |
audio_update_manually | String | No | Indica si se deben enviar activamente datos de audio. Valor predeterminado: "false". Si se establece en "true" y el SDK admite capacidades de audio en el dispositivo, como AEC y VAD, dichas capacidades se habilitan de forma predeterminada. |
workspace | String | No | La ruta de almacenamiento para los archivos de recursos en el dispositivo. Este parámetro es obligatorio cuando audio_update_manually es "true" y está habilitada una capacidad de audio en el dispositivo, como AEC o VAD. |
debug_path | String | No | La ruta de almacenamiento del archivo de registro. Este parámetro solo surte efecto cuando save_log es true en initialize. En este caso, la ruta es obligatoria. El SDK conserva como máximo dos archivos de registro localmente. |
save_wav | String | No | Indica si se debe guardar el audio de depuración en debug_path. Valor predeterminado: "false". Los valores válidos son "true" y "false". Este parámetro solo surte efecto cuando save_log es true, y debug_path también debe estar definido. |
max_log_file_size | int | No | El tamaño máximo del archivo de registro en bytes. Este parámetro solo surte efecto cuando save_log es true. Predeterminado: 104857600 (100 × 1024 × 1024 bytes, o 100 MiB). |
log_track_level | int | No | El nivel de filtro para los registros enviados a través de onNuiLogTrackCallback. Valor predeterminado: 2. Valores válidos: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR) y 5 (NONE). Un registro se devuelve solo cuando su nivel es mayor o igual tanto a log_track_level como al level pasado a initialize. Por ejemplo, si log_track_level es 2 (INFO) y level es 3 (WARNING), solo se devuelven registros de nivel WARNING y superior (valores mayores o iguales a 3). |
aec_params | object | No | Configuración avanzada de AEC en el dispositivo. Este objeto solo surte efecto cuando audio_update_manually es "true". |
aec_params.enable_aec | boolean | No | Indica si se debe habilitar AEC en el dispositivo. Si audio_update_manually es "true" y el SDK admite AEC en el dispositivo, AEC se habilita de forma predeterminada. |
aec_params.save_audio | boolean | No | Indica si se debe guardar el audio procesado por el módulo AEC en el dispositivo. Si save_wav es "true" y debug_path está definido, esta función se habilita de forma predeterminada y el audio se guarda en debug_path. |
aec_params.enable_aec_data_callback | boolean | No | Indica si se debe devolver el audio procesado por AEC a través de EVENT_AEC_DATA en onNuiAssistEventCallback. Predeterminado: false. |
vad_params | object | No | Configuración avanzada de VAD en el dispositivo. Este objeto solo surte efecto cuando audio_update_manually es "true". |
vad_params.enable_vad | boolean | No | Indica si se debe habilitar VAD en el dispositivo. Si audio_update_manually es "true" y el SDK admite VAD en el dispositivo, VAD se habilita de forma predeterminada. |
vad_params.save_audio | boolean | No | Indica si se debe guardar el audio procesado por el módulo VAD en el dispositivo. Si save_wav es "true" y debug_path está definido, esta función se habilita de forma predeterminada y el audio se guarda en debug_path. |
Parámetros de conversación de voz
Pase una cadena JSON en el argumento params de setParams.
Ejemplo: La siguiente cadena JSON no enumera todos los parámetros. Agregue los parámetros según sea necesario para su caso de uso.
| Parámetro de nivel superior | Tipo | Obligatorio | Descripción |
|---|---|---|---|
service_type | int | Sí | Tipo de servicio de voz. Establezca este parámetro en 4 para conversaciones de voz en tiempo real. |
nls_config | object | Sí | Configuración principal de la conversación de voz, incluida la selección del modelo y el comportamiento de la conversación. |
nls_config.model | string | Sí | Nombre del modelo. Admite las series de modelos qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus y qwen-audio-3.0-realtime-flash. |
nls_config.sr_format | string | Sí | Formato de audio de entrada. Solo se admite pcm. El formato predeterminado es PCM monoaural de 16 kHz y 16 bits. |
nls_config.modalities | string | No | Una cadena que contiene una matriz de modalidades de salida. Valores válidos:
|
nls_config.voice | string | No | Voz TTS. El valor predeterminado es longanqian_v3.1 para 3.1 Plus y longanqian para 3.0 Plus/Flash. Este parámetro solo se puede establecer en la primera session.update; los valores posteriores se ignoran. Voces del sistema: longanqian, longanlingxin, longanlingxi, longanxiaoxin y longanlufeng. También puede especificar un voice_id clonado creado a través de la API de clonación de voz. Consulte Configuración de voz.3.1 Plus también admite longanqian_v3.1, longanhuan_v3.1, longanlingxin_v3.1, longanfengyue_v3.1, xunanchuan_v3.1, beth_v3.1, betty_v3.1 y cally_v3.1. |
nls_config.enable_speech_emotion | boolean | No | Indica si se debe habilitar la expresión emocional mejorada. Cuando está habilitada, la voz de respuesta presenta una variación emocional más notable. Valor predeterminado: true. Valores válidos: true y false. |
nls_config.instructions | string | No | Instrucciones del sistema que definen el rol del modelo, el estilo de respuesta y las preferencias de comportamiento para toda la sesión. |
nls_config.max_history_turns | int | No | Número máximo de turnos históricos de preguntas y respuestas permitidos en una solicitud. Valores válidos: de 1 a 50. Predeterminado: 20. |
nls_config.tools | string | No | Una cadena que contiene una matriz de definiciones de herramientas de Function Calling. Después de configurar este parámetro, el modelo decide si llamar a una herramienta basándose en la entrada del usuario. Cada definición utiliza type (obligatorio y fijado en function) y un objeto function que contiene name (obligatorio), description (opcional) y parameters (opcional). Si una función no tiene argumentos, omita parameters.Ejemplo: |
nls_config.turn_detection | string | No | Una cadena que contiene un objeto JSON para la detección de turnos. Si se omite, la sesión utiliza el modo pulsar para hablar, en el cual el audio se confirma y la inferencia se activa manualmente. Si se establece, se habilita el modo de conversación dúplex. |
nls_config.turn_detection.type | string | No | Tipo de VAD. server_vad (predeterminado) detecta los límites del habla a partir de características acústicas y activa automáticamente la inferencia. smart_turn combina señales acústicas y semánticas; los sonidos sin contenido semántico, como las muletillas, no inician un turno ni interrumpen la reproducción del modelo. |
nls_config.turn_detection.threshold | float | No | Sensibilidad de VAD. Este parámetro solo se aplica a server_vad y no tiene efecto en smart_turn. Los valores más bajos hacen que el VAD sea más sensible a sonidos tenues y ruido de fondo; los valores más altos requieren un habla más clara y fuerte. Rango válido: [-1.0, 1.0]. Valor predeterminado: 0.5. |
nls_config.turn_detection.silence_duration_ms | int | No | Duración mínima de silencio después del habla, en milisegundos, antes de que se active la respuesta del modelo. Este parámetro solo se aplica a server_vad y no tiene efecto en smart_turn. Los valores más bajos reducen la latencia, pero pueden activarse con pausas breves. Rango válido: [200, 6000]. Valor predeterminado: 800. Recomendado para conversación: de 400 a 800. |
nls_config.turn_detection.voiceprint_audio_urls | string | No | Una cadena que contiene una matriz de URL de audio pregrabado de acceso público para el hablante objetivo. Este parámetro solo se aplica a smart_turn. En conversaciones dúplex, ayuda al modelo a centrarse en el hablante objetivo e ignorar a otros hablantes y el ruido de fondo. Se admiten hasta cinco URL. El audio debe ser PCM o WAV de 16 kHz. |
API clave
NativeNui
initialize
Inicializa una instancia del SDK de conversación de voz. El SDK es un singleton. No lo inicialice más de una vez antes de llamar a release.
Este método es bloqueante, así que llámelo en un hilo que no sea de UI.
Firma del método
Parámetro | Tipo | Descripción |
|---|---|---|
| La implementación de la interfaz de devolución de llamada de eventos y datos. | |
|
| Una cadena JSON que contiene los parámetros de autenticación, conexión y depuración. Consulte Parámetros de conexión y control. |
|
| Controla el nivel de impresión de los propios registros del SDK. |
|
| Indica si se deben guardar los registros locales. Si se establece en |
setParams
Establece los Parámetros de conversación de voz en formato JSON. Llame a este método antes de startDialog.
Firma del método
Parámetro | Tipo | Descripción |
|---|---|---|
|
|
startDialog
Inicia la conversación.
Firma del método
| Parámetro | Tipo | Descripción |
|---|---|---|
vad_mode | VadMode | Modo VAD. Fijo en VadMode.TYPE_P2T. |
dialog_params | String | Si apikey en los parámetros de conexión y control es una clave API temporal, actualícela aquí después de que caduque.Formato JSON: |
stopDialog
Finaliza la conversación. Después de llamar a este método, el servidor devuelve el resultado final de la conversación y termina la tarea.
Firma del método
cancelDialog
Finaliza la conversación inmediatamente. Después de llamar a este método, la tarea termina de inmediato sin esperar a que el servidor devuelva el resultado final de la conversación.
Firma del método
updateAction
Envía un comando de acción de conversación durante una interacción para actualizar el comportamiento en tiempo de ejecución, como el contexto de la conversación.
Firma del método
| Parámetro | Tipo | Descripción |
|---|---|---|
params | String | Una cadena JSON utilizada para actualizar el comportamiento en tiempo de ejecución, como el contexto de la conversación. |
params.type | String | Establecido en "action". |
params.command | String | Comando de tiempo de ejecución. Valores válidos:
|
params.context | String | Actualización de solicitud de llamada de función. Se usa cuando command es "function_call". |
params.context.type | String | Tipo de evento. Este parámetro es obligatorio cuando command es "function_call". conversation.item.create inserta un elemento de conversación para contexto histórico, texto complementario o resultado de una herramienta. Después de enviar conversation.item.create, utilice response.create para activar otra inferencia. |
params.context.item | object | Requerido cuando params.context.type es conversation.item.create. El elemento de conversación a crear. |
params.context.response | object | Opcional cuando params.context.type es response.create. Anula los valores predeterminados de la sesión para esta inferencia. Si se omite, se utiliza la configuración actual de la sesión. |
context.item:
| Parámetro | Tipo | Descripción |
|---|---|---|
id | String | ID de elemento de conversación único opcional. Si se omite, el servidor genera uno. Se devuelve un error si el ID especificado ya existe. |
type | String | Tipo de elemento obligatorio. Valores válidos:
|
role | String | Requerido para message. Valores válidos: system, user y assistant. |
content | array | Obligatorio para message. Cada elemento contiene un type y el campo de datos asociado. system admite input_text con text; user admite input_text con text y input_audio con audio codificado en Base64; assistant admite output_text con text. |
call_id | String | Requerido para function_call y function_call_output. El ID único que asocia una solicitud de llamada de función con su resultado. |
name | String | Requerido para function_call. El nombre de la función a llamar. |
arguments | String | Requerido para function_call. Argumentos de la función como una cadena JSON. |
output | String | Requerido para function_call_output. Resultado de ejecución de la herramienta como una cadena JSON. |
context.response:
| Parámetro | Tipo | Descripción |
|---|---|---|
modalities | array | Modalidades de salida. ["text"] devuelve solo texto. ["audio", "text"] (predeterminado) devuelve tanto audio como texto. |
voice | string | Anula la voz TTS para esta inferencia. |
updateAudio
Cuando audio_update_manually se establece en "true", llame a este método para enviar activamente datos de grabación en lugar de proporcionar los datos a través de onNuiNeedAudioData.
Firma del método
Parámetro | Tipo | Descripción |
|---|---|---|
|
| Los datos de audio a enviar. |
|
| El número de bytes de datos de audio a enviar. |
|
| Ignore este parámetro. |
updateRefAudio
Cuando audio_update_manually se establece en "true" y el AEC en el dispositivo está habilitado, llame a este método para enviar el audio reproducido por el reproductor como señal de referencia.
Firma del método
Parámetro | Tipo | Descripción |
|---|---|---|
|
| Los datos de audio a enviar. |
|
| El número de bytes de datos de audio a enviar. |
|
| Ignore este parámetro. |
release
Libera todos los recursos internos del SDK. Después de llamar a este método, la instancia del SDK deja de estar disponible. Para volver a utilizarla, debe reinicializarla llamando a initialize.
Firma del método
GetVersion
Obtiene la información de la versión actual del SDK.
Firma del método
INativeNuiCallback: callbacks de escucha
onNuiEventCallback: escucha de información de eventos
Firma del método
Parámetro | Tipo | Descripción |
|---|---|---|
| El evento de devolución de llamada. | |
|
| Válido solo cuando ocurre el evento |
|
| Un parámetro reservado. |
|
| El resultado del reconocimiento de voz. |
|
| La función de activación por voz. No necesita utilizar este parámetro. |
onNuiAudioStateChanged: escucha del estado de audio
El SDK utiliza esta devolución de llamada para notificarle cuándo iniciar o detener la grabación.
Firma del método
Estado | Descripción |
|---|---|
| La interacción ha comenzado. Puede abrir el dispositivo de grabación e iniciar la grabación. |
| La interacción se ha detenido. Puede detener la grabación. |
| La instancia del SDK se ha liberado. Puede cerrar completamente el dispositivo de grabación. |
onNuiNeedAudioData: suministro de datos de audio
Después de que comienza la conversación, esta devolución de llamada se activa continuamente. Proporcione los datos de audio en esta devolución de llamada. No necesita utilizar esta devolución de llamada cuando audio_update_manually está establecido en "true".
Firma del método
Parámetro | Tipo | Descripción |
|---|---|---|
|
| Los datos de audio a rellenar. |
|
| El número de bytes de datos de audio a rellenar. |
onNuiAssistEventCallback: recepción de eventos y datos auxiliares
Este callback recibe eventos auxiliares y datos relacionados del SDK.
Firma del método
Parámetro | Tipo | Descripción |
|---|---|---|
|
| Un evento |
|
| Ignore este parámetro. |
|
| Ignore este parámetro. |
|
| Datos auxiliares, como el audio TTS devuelto por el modelo. |
onNuiLogTrackCallback: escucha de registros de seguimiento
Esta devolución de llamada recibe registros internos detallados del SDK para ayudar en la resolución de problemas y la depuración.
NuiEvent: tipos de eventos
| Evento | Descripción |
|---|---|
EVENT_TRANSCRIBER_STARTED | La tarea se inició correctamente. |
EVENT_VAD_START | Se activa inmediatamente después de que comienza la tarea. Esto no significa que se haya detectado el inicio del habla. |
EVENT_VAD_END | Se detectó el final del habla. |
EVENT_ASR_PARTIAL_RESULT | Un resultado intermedio del reconocimiento de voz. |
EVENT_ASR_ERROR | Ocurrió un error durante la conversación de voz. |
EVENT_MIC_ERROR | Se activa cuando no se reciben datos de audio durante dos segundos consecutivos. |
EVENT_SENTENCE_END | Se detectó el final de una oración y se devolvió un resultado de reconocimiento completo. |
EVENT_TRANSCRIBER_COMPLETE | La conversación de voz finalizó. |
EVENT_AUDIO_TRANSCRIPTION | Un evento de transcripción de texto incremental para la salida de audio. Los segmentos de transcripción se devuelven en modo streaming. |
EVENT_AUDIO_TRANSCRIPTION_COMPLETED | La transcripción de la salida de audio está completa. |
EVENT_OTHER_RESULT | Otra información de eventos, como un resultado de Function Calling. |
EVENT_ASR_TTS_START | El modelo comenzó a devolver audio TTS. |
EVENT_ASR_TTS_DATA | Audio TTS devuelto por el modelo. |
EVENT_ASR_TTS_COMPLETE | El modelo terminó de devolver audio TTS. |
EVENT_AEC_DATA | Datos de audio procesados por AEC. |