Qwen-Audio-ASR-Streaming SDK de Android para reconocimiento de voz en tiempo real - Alibaba Cloud Model Studio

Esta guía le muestra cómo utilizar el SDK de Android para el reconocimiento de voz en tiempo real de Qwen-Audio-ASR-Streaming con el fin de convertir voz a texto.

Inicio rápido

Obtener una clave API
Descargue el SDK y ejecute el código de ejemplo:
- Descargue el paquete más reciente del SDK.
- Extraiga el paquete ZIP. El SDK en formato AAR se encuentra en el directorio app/libs. Agréguelo a las dependencias de su proyecto. Para la integración con Android C++, utilice android_libs y android_include del paquete ZIP para obtener las bibliotecas dinámicas y los archivos de encabezado.
- Abra el proyecto en Android Studio. El código de muestra se encuentra en DashFunAsrSpeechTranscriberActivity.java. Reemplace la clave API para probar la función.

Procedimiento de llamada

Inicialice el SDK.
Configure los parámetros para su caso de uso. Utilice el argumento parameters del método initialize para establecer los Parámetros de conexión y control, y utilice el método setParams para establecer los Parámetros de reconocimiento de voz.
Llame a startDialog para iniciar el reconocimiento.
En la devolución de llamada onNuiAudioStateChanged, inicie el dispositivo de grabación según el estado del audio.
Proporcione datos de grabación continuamente en la devolución de llamada onNuiNeedAudioData, o envíe activamente datos de grabación llamando a updateAudio.
En la devolución de llamada onNuiEventCallback, escuche los eventos y obtenga los resultados del reconocimiento de voz.
Llame a stopDialog para detener el reconocimiento y escuche el evento EVENT_TRANSCRIBER_COMPLETE para confirmar que el reconocimiento ha finalizado.
Cuando ya no necesite el reconocimiento, llame a release para liberar los recursos del SDK.

Parámetros de solicitud

Parámetros de conexión y control

Para configurar estos parámetros, pase una cadena JSON en el argumento parameters del método initialize.

Ejemplo: El siguiente es un ejemplo de cadena JSON. No se enumeran todos los parámetros. Agregue otros según sea necesario cuando escriba su código:

{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`url`	`String`	Sí	Dirección del servicio: `wss://dashscope.aliyuncs.com/api-ws/v1/inference` China (Beijing): `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference` Singapur: `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference` Reemplace `{WorkspaceId}` con su ID de espacio de trabajo real.
`apikey`	`String`	Sí	La clave API.
`service_mode`	`String`	Sí	El modo de ejecución. Fijo en `"1"` para el reconocimiento de voz en tiempo real.
`device_id`	`String`	Sí	Una cadena única que identifica al usuario final. Puede configurarla como un ID de usuario dentro de la aplicación o un identificador de dispositivo único generado por el cliente. Este ID se utiliza principalmente para el rastreo de registros y la resolución de problemas.
`audio_update_manually`	`String`	No	Si se debe habilitar el envío activo de datos de audio. Predeterminado: `"false"`. Si se establece en `"true"` y la versión del SDK admite capacidades de procesamiento de audio en el dispositivo como AEC y VAD, esas capacidades se habilitan de forma predeterminada.
`workspace`	`String`	No	La ruta donde se almacenan los archivos de recursos en el dispositivo. Este parámetro es obligatorio cuando `audio_update_manually` se establece en `"true"` y está habilitada una capacidad de procesamiento de audio en el dispositivo, como AEC o VAD.
`debug_path`	`String`	No	La ruta de almacenamiento para archivos de registro. Este parámetro solo surte efecto cuando `save_log` se establece en true en el método `initialize`. En este caso, debe establecer la ruta del archivo de registro; de lo contrario, se producirá un error. Se conservan un máximo de dos archivos de registro localmente.
`save_wav`	`String`	No	Si se debe guardar el archivo de audio de depuración. El archivo de audio se guarda en `debug_path`. Predeterminado: "false". Valores válidos: "true": guarda el archivo. "false": no guarda el archivo. Este parámetro solo surte efecto cuando `save_log` se establece en true en el método `initialize`. Además, también se debe establecer `debug_path`.
`max_log_file_size`	`int`	No	El tamaño máximo de un archivo de registro, en bytes. Este parámetro solo surte efecto cuando `save_log` se establece en true en el método `initialize`. Predeterminado: 104857600 (100 * 1024 * 1024 bytes, es decir, 100 MiB).
`log_track_level`	`int`	No	El nivel de filtro para el contenido del registro enviado a través de la devolución de llamada de registro (`onNuiLogTrackCallback`). Predeterminado: 2. Valores válidos: 0: LOG_LEVEL_VERBOSE 1: LOG_LEVEL_DEBUG 2: LOG_LEVEL_INFO 3: LOG_LEVEL_WARNING 4: LOG_LEVEL_ERROR 5: LOG_LEVEL_NONE (deshabilita esta función) Nota: `log_track_level` y `level` (configurado mediante el método `initialize`) determinan conjuntamente qué registros se envían finalmente a la devolución de llamada. Un registro se envía a la devolución de llamada solo cuando su valor de nivel es mayor o igual tanto a `log_track_level` como a `level`. Por ejemplo, si `log_track_level` se establece en 2 (INFO) y `level` se establece en 3 (WARNING), entonces solo los registros de nivel WARNING o superior (valor >= 3) se envían a la devolución de llamada.
`enable_reconnection`	`String`	No	Si se debe reanudar la transmisión después de que la red se reconecte. Predeterminado: `"false"`.
`aec_params`	`object`	No	El objeto de configuración avanzada para la cancelación de eco acústico (AEC) en el dispositivo. Este objeto solo surte efecto cuando `audio_update_manually` se establece en `"true"`.
`aec_params.enable_aec`	`boolean`	No	Si se debe habilitar el AEC en el dispositivo. Si `audio_update_manually` se establece en `"true"` y la versión del SDK admite AEC en el dispositivo, esta capacidad se habilita de forma predeterminada.
`aec_params.save_audio`	`boolean`	No	Si se debe guardar el audio procesado por el módulo AEC en el dispositivo. Si `save_wav` se establece en `"true"` y se especifica `debug_path`, esta función se habilita de forma predeterminada y los datos de audio AEC se guardan en `debug_path`.
`aec_params.enable_aec_data_callback`	`boolean`	No	Si se deben devolver los datos procesados por AEC a su aplicación. Predeterminado: false. Si está habilitado, reciba los datos del evento `EVENT_AEC_DATA` en `onNuiAssistEventCallback`.
`vad_params`	`object`	No	El objeto de configuración avanzada para la detección de actividad de voz (VAD) en el dispositivo. Este objeto solo surte efecto cuando `audio_update_manually` se establece en `"true"`.
`vad_params.enable_aec`	`boolean`	No	Si se debe habilitar el VAD en el dispositivo. Si `audio_update_manually` se establece en `"true"` y la versión del SDK admite VAD en el dispositivo, esta capacidad 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` se establece en `"true"` y se especifica `debug_path`, esta función se habilita de forma predeterminada y los datos de audio del VAD se guardan en `debug_path`.

Parámetros de reconocimiento de voz

Para configurar estos parámetros, pase una cadena JSON en el argumento params del método setParams.

Ejemplo: El siguiente es un ejemplo de cadena JSON. No se enumeran todos los parámetros. Agregue otros según sea necesario cuando escriba su código:

{
    "service_type": 4,
    "nls_config": {
        "model": "qwen-audio-3.0-asr-flash-streaming",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

Parámetros

Parámetro de nivel superior	Tipo	Obligatorio	Descripción
`service_type`	`int`	Sí	El tipo de servicio de voz. Fijo en `4` para el reconocimiento de voz en tiempo real.
`nls_config`	`object`	Sí	El objeto de configuración principal para el reconocimiento de voz. Contiene parámetros clave como la selección del modelo y los controles de calidad del reconocimiento.
`nls_config.model`	`string`	Sí	El nombre del modelo.
`nls_config.sr_format`	`string`	Sí	El formato de audio. Valores válidos: `pcm` `opus` ImportantePara audio Opus, pase audio PCM al SDK. El SDK lo codifica como Opus internamente.
`nls_config.sample_rate`	`int`	Sí	La frecuencia de muestreo en Hz. Se admite cualquier frecuencia de muestreo. ImportanteNo se admite 8000 Hz cuando está habilitada una capacidad de procesamiento de audio en el dispositivo, como AEC o VAD.
`nls_config.keep_dialect`	`boolean`	No	Especifica si se conservan las expresiones dialectales. Valor predeterminado: `false`. Establezca el valor en `false` para transcribir el habla dialectal como texto en mandarín estándar, o en `true` para conservar las expresiones dialectales. NotaSe aplica a `qwen-audio-3.1-asr-flash-streaming`.
`nls_config.vad_model`	`string`	No	El modelo VAD. Valor predeterminado: `far_field_meeting_16k`. `near_meeting_16k`: escenarios de campo cercano. `far_field_meeting_16k`: escenarios de campo lejano. NotaSe aplica a `qwen-audio-3.1-asr-flash-streaming`.
`nls_config.max_sentence_silence`	`int`	No	El umbral de silencio del VAD para la segmentación, en ms. Cuando el silencio posterior a un segmento de voz supera este umbral, el sistema determina que la oración ha finalizado. Valor predeterminado: 800. Valores válidos: [200, 6000].
`nls_config.multi_threshold_mode_enabled`	`boolean`	No	Si se debe habilitar el modo de umbral múltiple. Cuando está habilitado, esto evita que los segmentos VAD sean demasiado largos. Valor predeterminado: false.
`nls_config.heartbeat`	`boolean`	No	Si se habilitan los paquetes de latido. Valor predeterminado: false. true: Mantiene activa la conexión con el servidor incluso cuando se envía audio silencioso de forma continua. false (predeterminado): Incluso cuando se envía audio silencioso de forma continua, la conexión expira y se cierra después de un período de tiempo. El audio silencioso se refiere al contenido en un archivo de audio o flujo de datos que no contiene señal de sonido. Puede generar audio silencioso de varias maneras, como utilizando software de edición de audio como Audacity o Adobe Audition, o utilizando una herramienta de línea de comandos como FFmpeg.
`nls_config.vocabulary_id`	`string`	No	El ID de una lista de palabras calientes precompilada. Genere este ID con antelación llamando a la API de creación de lista de palabras clave. Pase el ID durante el reconocimiento para usar las palabras clave de la lista. Adecuado para escenarios donde el vocabulario es conocido y relativamente estable, y donde necesita reutilizar la misma lista de palabras en distintas solicitudes. Para obtener detalles sobre el uso, consulte Palabras clave precompiladas.
`nls_config.instant_vocabulary`	`object`	No	Palabras clave instantáneas. Se pasan como pares clave-valor, donde la clave es el texto de la palabra clave (`string`) y el valor es el peso de la palabra clave (`integer`). No es necesario crear una lista de palabras clave con antelación. El peso oscila entre [1, 5] o se establece en 50: un valor en [1, 5] hace que el modelo tenga más probabilidades de generar la palabra a medida que aumenta el valor; un valor de 50 designa una súper palabra clave, lo que mejora enormemente la recuperación, pero el número de súper palabras clave no puede exceder 50. Adecuado para la optimización temporal de palabras clave a nivel de sesión. Cuando se configuran conjuntamente palabras clave instantáneas y precompiladas, el sistema fusiona ambos conjuntos. Si el conjunto fusionado contiene más de 2000 palabras clave, el sistema selecciona aleatoriamente 2000 para su uso. Para obtener información sobre el uso, los modelos compatibles y los límites, consulte Palabras clave instantáneas.
`nls_config.language_hints`	`array[string]`	No	El idioma del audio a reconocer. No hay valor predeterminado; si no se establece, el modelo detecta el idioma automáticamente. Puede configurar hasta 4 valores. Si configura más, solo los primeros 4 surten efecto. Haga clic para ver los códigos de idioma admitidos zh: Chino en: Inglés ja: Japonés ko: Coreano vi: Vietnamita th: Tailandés id: Indonesio ms: Malayo tl: Filipino hi: Hindi ar: Árabe fr: Francés de: Alemán es: Español pt: Portugués ru: Ruso it: Italiano nl: Neerlandés sv: Sueco da: Danés fi: Finés no: Noruego el: Griego pl: Polaco cs: Checo hu: Húngaro ro: Rumano bg: Búlgaro hr: Croata sk: Eslovaco
`nls_config.speech_noise_threshold`	`float`	No	El umbral para distinguir el habla del ruido, utilizado para ajustar la sensibilidad de la Detección de Actividad de Voz (VAD). Valores válidos: [-1.0, 1.0]. Descripciones de valores: Cuanto más cerca esté el valor de -1: El umbral de ruido disminuye, por lo que es más probable que el ruido se reconozca como habla, lo que puede causar que se transcriba más ruido. Cuanto más cerca esté el valor de +1: El umbral de ruido aumenta, por lo que es más probable que el habla se juzgue erróneamente como ruido, lo que puede causar que se filtre parte del habla. Este es un parámetro de configuración avanzada. Ajustarlo puede afectar significativamente los resultados del reconocimiento. Recomendaciones: Pruebe y verifique exhaustivamente los resultados antes de ajustar. Ajuste en incrementos pequeños según el entorno de audio real (se recomienda un paso de 0.1).
`nls_config.special_word_filter`	`object`	No	Especifica las palabras sensibles que se deben procesar durante el reconocimiento de voz y permite configurar diferentes métodos de procesamiento para cada una. Para más detalles, consulte Filtrado de palabras sensibles.
`nls_config.enable_connection_fast_check`	`boolean`	No	Si se deben detectar rápidamente las interrupciones de la red y reportarlas lo antes posible. Predeterminado: false.

Interfaces clave

NativeNui

initialize

Inicializa una instancia del SDK de reconocimiento 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

public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)

Parámetros

Parámetro	Tipo	Descripción
`callback`	`INativeNuiCallback`	La implementación de la interfaz de callback de eventos y datos.
`parameters`	`String`	Una cadena JSON que contiene los parámetros de autenticación, conexión y depuración. Consulte Parámetros de conexión y control.
`level`	`Constants.LogLevel`	Controla el nivel de impresión de los propios registros del SDK.
`save_log`	`boolean`	Si se deben guardar los registros locales. Si se establece en `true`, especifique la ruta a través de `debug_path` en los Parámetros de conexión y control, y opcionalmente configure el tamaño del archivo a través de `max_log_file_size`.

Valor de retorno

Un código de error.

setParams

Establece los parámetros de reconocimiento de voz en formato JSON. Llame a este método antes de startDialog.

Firma del método

public synchronized int setParams(String params)

Parámetros

Parámetro	Tipo	Descripción
`params`	`String`	Parámetros de reconocimiento de voz.

Valor de retorno

Un código de error.

startDialog

Inicia el reconocimiento.

Firma del método

public synchronized int startDialog(VadMode vad_mode, String dialog_params)

Parámetros

Parámetro Tipo Descripción

Parámetro	Tipo	Descripción
`vad_mode`	`VadMode`	El modo VAD. Fijado en `VadMode.TYPE_P2T`.
`dialog_params`	`String`	Si el parámetro `apikey` en Parámetros de conexión y control utiliza una clave API temporal, puede actualizarla aquí cuando expire. Para mejorar la precisión del reconocimiento mediante el contexto, actualice el contexto aquí. El contenido está en formato JSON: `{ "apikey": "st-****", "input_context": [ { "role": "user", "content": [ { "text": "xxxxx", "type": "input_text" } ] } ] }`

vad_mode

VadMode

El modo VAD. Fijado en VadMode.TYPE_P2T.

dialog_params

String

Si el parámetro apikey en Parámetros de conexión y control utiliza una clave API temporal, puede actualizarla aquí cuando expire.

Para mejorar la precisión del reconocimiento mediante el contexto, actualice el contexto aquí.

El contenido está en formato JSON:

{
  "apikey": "st-****",
  "input_context": [
    {
      "role": "user",
      "content": [
        {
          "text": "xxxxx",
          "type": "input_text"
        }
      ]
    }
  ]
}

Valor de retorno

Un código de error.

stopDialog

Finaliza el reconocimiento. Después de llamar a este método, el servidor devuelve el resultado final del reconocimiento y termina la tarea.

Firma del método

public synchronized int stopDialog();

Valor de retorno

Un código de error.

cancelDialog

Finaliza el reconocimiento inmediatamente. Después de llamar a este método, la tarea termina de inmediato sin esperar a que el servidor devuelva el resultado final del reconocimiento.

Firma del método

public synchronized int cancelDialog();

Valor de retorno

Un código de error.

updateAction

Envía una acción en tiempo de ejecución para notificar al AEC en el dispositivo el estado de reproducción.

Firma del método

public synchronized int updateAction(String params);

Parámetros

Parámetro Tipo Descripción

Parámetro	Tipo	Descripción
`params`	`String`	Una cadena JSON que contiene la acción en tiempo de ejecución.
`params.type`	`String`	Establezca en `"action"`.
`params.command`	`String`	`play_start`: Cuando se utiliza AEC en el dispositivo, notifica al SDK que el reproductor ha comenzado a reproducir audio. `play_over`: Cuando se utiliza AEC en el dispositivo, notifica al SDK que el reproductor ha terminado de reproducir audio.

params

String

Una cadena JSON que contiene la acción en tiempo de ejecución.

params.type

String

Establezca en "action".

params.command

String

play_start: Cuando se utiliza AEC en el dispositivo, notifica al SDK que el reproductor ha comenzado a reproducir audio.

play_over: Cuando se utiliza AEC en el dispositivo, notifica al SDK que el reproductor ha terminado de reproducir audio.

Valor de retorno

Un código de error.

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

public synchronized int updateAudio(byte[] data, int len,
                                    boolean first_pack);

Parámetros

Parámetro	Tipo	Descripción
`data`	`byte[]`	Los datos de audio a enviar.
`len`	`int`	El número de bytes de datos de audio a enviar.
`first_pack`	`boolean`	Ignore este parámetro.

Valor de retorno

Un código de error.

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

public synchronized int updateRefAudio(byte[] data, int len,
                                       boolean first_pack);

Parámetros

Parámetro	Tipo	Descripción
`data`	`byte[]`	Los datos de audio a enviar.
`len`	`int`	El número de bytes de datos de audio a enviar.
`first_pack`	`boolean`	Ignore este parámetro.

Valor de retorno

Un código de error.

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 usarla nuevamente, debe reinicializarla llamando a initialize.

Firma del método

public synchronized int release();

Valor de retorno

Un código de error.

GetVersion

Obtiene la información de la versión actual del SDK.

Firma del método

public synchronized String GetVersion();

Valor de retorno

La información de la versión actual del SDK.

INativeNuiCallback: callbacks de escucha

onNuiEventCallback: escucha de eventos y resultados del reconocimiento de voz

Firma del método

void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);

Parámetros

Parámetro	Tipo	Descripción
`event`	`NuiEvent`	El evento de callback.
`resultCode`	`int`	El código de error. Válido cuando ocurre el evento EVENT_ASR_ERROR.
`arg2`	`int`	Un parámetro reservado.
`asrResult`	`AsrResult`	El resultado del reconocimiento de voz.
`kwsResult`	`KwsResult`	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

void onNuiAudioStateChanged(AudioState state);

Estados AudioState

Estado	Descripción
`STATE_OPEN`	La interacción ha comenzado. Puede abrir el dispositivo de grabación e iniciar la grabación.
`STATE_PAUSE`	La interacción se ha detenido. Puede detener la grabación.
`STATE_CLOSE`	La instancia del SDK ha sido liberada. Puede cerrar completamente el dispositivo de grabación.

onNuiNeedAudioData: suministro de los datos de audio a reconocer

Después de que comienza el reconocimiento, esta devolución de llamada se activa continuamente. Proporcione los datos de audio a reconocer en esta devolución de llamada.

Firma del método

int onNuiNeedAudioData(byte[] buffer, int len);

Parámetros

Parámetro	Tipo	Descripción
`buffer`	`byte[]`	Los datos de audio a rellenar.
`len`	`int`	El número de bytes de datos de audio a rellenar.

Valor de retorno

El número de bytes realmente rellenados.

onNuiAssistEventCallback: recepción de eventos y datos auxiliares

Este callback recibe eventos auxiliares y datos relacionados del SDK.

Firma del método

void onNuiAssistEventCallback_(int event, byte[] info, int info_len,
                               byte[] data);

Parámetros

Parámetro	Tipo	Descripción
`event`	`int`	Un evento `NuiEvent`.
`info`	`String`	Ignore este parámetro.
`info_len`	`int`	Ignore este parámetro.
`data`	`byte[]`	Datos auxiliares, como datos de audio procesados por AEC.

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.

default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

`NuiEvent`: tipos de eventos

Evento	Descripción
`EVENT_TRANSCRIBER_STARTED`	La tarea se inició correctamente.
`EVENT_VAD_START`	Se activa justo después de que comienza la tarea. Esto no significa que se haya detectado el inicio del habla.
`EVENT_VAD_END`	Se detectó el fin del habla.
`EVENT_ASR_PARTIAL_RESULT`	Un resultado intermedio de reconocimiento de voz.
`EVENT_ASR_WARN`	Ocurrió una advertencia que no interrumpe el reconocimiento de voz, como una interrupción de la red cuando la reconexión está habilitada.
`EVENT_ASR_ERROR`	Ocurrió un error durante el reconocimiento de voz.
`EVENT_MIC_ERROR`	Se activa cuando no se reciben datos de audio durante 2 segundos consecutivos.
`EVENT_SENTENCE_END`	Se detecta el final de una oración. Se devuelve un resultado de reconocimiento completo para la oración.
`EVENT_TRANSCRIBER_COMPLETE`	El reconocimiento de voz ha finalizado.
`EVENT_AEC_DATA`	Datos de audio procesados por AEC.

Inicio rápido

Procedimiento de llamada

Parámetros de solicitud

Parámetros de conexión y control

Parámetros de reconocimiento de voz

Interfaces clave

NativeNui

initialize

setParams

startDialog

stopDialog

cancelDialog

updateAction

updateAudio

updateRefAudio

release

GetVersion

INativeNuiCallback: callbacks de escucha

onNuiEventCallback: escucha de eventos y resultados del reconocimiento de voz

onNuiAudioStateChanged: escucha del estado de audio

onNuiNeedAudioData: suministro de los datos de audio a reconocer

onNuiAssistEventCallback: recepción de eventos y datos auxiliares

onNuiLogTrackCallback: escucha de registros de seguimiento

NuiEvent: tipos de eventos

`NuiEvent`: tipos de eventos