Skip to main content

Qwen-Audio-ASR-Message SDK de Android para reconocimiento de voz en tiempo real

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

Inicio rápido

  1. Obtener una clave API
  2. 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

  1. Inicialice el SDK.
  2. 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.
  3. Llame a startDialog para iniciar el reconocimiento.
  4. En la devolución de llamada onNuiAudioStateChanged, inicie el dispositivo de grabación según el estado del audio.
  5. Proporcione continuamente datos de grabación en la devolución de llamada onNuiNeedAudioData, o envíe activamente datos de grabación llamando a updateAudio.
  6. En la devolución de llamada onNuiEventCallback, escuche los eventos y obtenga los resultados del reconocimiento de voz.
  7. Llame a stopDialog para detener el reconocimiento y escuche el evento EVENT_TRANSCRIBER_COMPLETE para confirmar que el reconocimiento ha finalizado.
  8. 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ámetroTipoObligatorioDescripción
urlStringSíDirección del servicio:
  • wss://dashscope.aliyuncs.com/api-ws/v1/inference
  • China (Pekín): 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.
apikeyStringSíLa clave API.
service_modeStringSíEl modo de ejecución. Fijo en "1" para el reconocimiento de voz en tiempo real.
device_idStringSí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_manuallyStringNoIndica si se habilita el envío activo de datos de audio. Valor 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, dichas capacidades se habilitan de forma predeterminada.
workspaceStringNoLa 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_pathStringNoLa ruta de almacenamiento para los 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 mantienen un máximo de dos archivos de registro localmente.
save_wavStringNoIndica si se debe guardar el archivo de audio de depuración. El archivo de audio se guarda en debug_path.Valor 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_sizeintNoEl 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_levelintNoEl nivel de filtro para el contenido del registro enviado a través del callback 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 (establecidos 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_reconnectionStringNoSi se debe reanudar la transmisión después de que la red se reconecte. Predeterminado: "false".
aec_paramsobjectNoEl 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_aecbooleanNoSi 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_audiobooleanNoSi 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_callbackbooleanNoSi 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_paramsobjectNoEl 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_aecbooleanNoSi 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_audiobooleanNoIndica 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.1-asr-flash-message",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}
Parámetros
Parámetro de nivel superiorTipoObligatorioDescripción
service_typeintSíEl tipo de servicio de voz. Fijo en 4 para el reconocimiento de voz en tiempo real.
nls_configobjectSí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.modelstringSíEl nombre del modelo. Establézcalo en qwen-audio-3.1-asr-flash-message.
nls_config.sr_formatstringSíEl formato de audio.Valores válidos:
  • pcm
  • opus
Para audio Opus, pase audio PCM al SDK. El SDK lo codifica como Opus internamente.
nls_config.sample_rateintSíLa frecuencia de muestreo, en Hz.Solo se admite 16000 Hz.
nls_config.language_hintsarray[string]NoEl 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.
  • 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
Este parámetro solo se aplica a los resultados finales (sentence_end=true) y no es compatible con los resultados intermedios (sentence_end=false).
nls_config.keep_dialectbooleanNoEspecifica 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.
Este parámetro solo se aplica a los resultados finales (sentence_end=true) y no se admite en los resultados intermedios (sentence_end=false).
nls_config.vad_modelstringNoEl modelo VAD. Valor predeterminado: far_field_meeting_16k.
  • near_meeting_16k: escenarios de campo cercano.
  • far_field_meeting_16k: escenarios de campo lejano.
nls_config.max_sentence_silenceintNoEl umbral de silencio VAD para la segmentación, en ms. Cuando el silencio después de un segmento de voz supera este umbral, el sistema determina que la oración ha terminado.Valor predeterminado: 800.Valores válidos: [200, 6000].
nls_config.heartbeatbooleanNoSi se deben habilitar 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.disfluency_removal_enabledbooleanNoIndica si se deben filtrar las muletillas y pulir la salida. El valor predeterminado es false. Establézcalo en true para habilitar esta función.
nls_config.intermediate_result_enabledbooleanNoIndica si se deben devolver resultados de transmisión intermedios. El valor predeterminado es false. Establézcalo en true para devolver resultados de transmisión intermedios.
nls_config.vocabulary_idstringNoEl ID de una lista de palabras clave 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_vocabularyobjectNoPalabras 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.speech_noise_thresholdfloatNoEl 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.enable_connection_fast_checkbooleanNoSi 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ámetroTipoDescripción
callbackINativeNuiCallbackLa implementación de la interfaz de callback de eventos y datos.
parametersStringUna cadena JSON que contiene los parámetros de autenticación, conexión y depuración. Consulte Parámetros de conexión y control.
levelConstants.LogLevelControla el nivel de impresión de los propios registros del SDK.
save_logbooleanIndica si se deben guardar los registros locales. Si se establece en true, especifique la ruta mediante debug_path en los Parámetros de conexión y control y, opcionalmente, configure el tamaño del archivo mediante 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ámetroTipoDescripción
paramsStringPará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ámetroTipoDescripción
vad_modeVadModeEl modo VAD. Fijado en VadMode.TYPE_P2T.
dialog_paramsStringSi el parámetro apikey en Parámetros de conexión y control utiliza una clave de API temporal, puede actualizarla aquí cuando caduque.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 un comando de acción durante una interacción para actualizar el comportamiento en tiempo de ejecución, como el contexto de reconocimiento. Firma del método
public synchronized int updateAction(String params);
Parámetros
ParámetroTipoDescripción
paramsStringUna cadena JSON utilizada para actualizar el comportamiento en tiempo de ejecución, como el contexto de reconocimiento.
params.typeStringEstablezca en "action".
params.commandStringEl comando en tiempo de ejecución. Valores válidos:
  • context: Actualiza inmediatamente el contexto para mejorar la precisión del reconocimiento.
  • 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.contextStringCuando command se establece en context, actualiza inmediatamente el contexto para mejorar la precisión del reconocimiento. El valor es una cadena JSON, como se muestra en el siguiente ejemplo.
{
  "context": [
    {
      "role": "user",
      "content": [
        {
          "text": "xxx",
          "type": "input_text"
        }
      ]
    }
  ]
}
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ámetroTipoDescripción
databyte[]Los datos de audio a enviar.
lenintEl número de bytes de datos de audio a enviar.
first_packbooleanIgnore 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ámetroTipoDescripción
databyte[]Los datos de audio a enviar.
lenintEl número de bytes de datos de audio a enviar.
first_packbooleanIgnore 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 volver a utilizarla, 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ámetroTipoDescripción
eventNuiEventEl evento de callback.
resultCodeintEl código de error. Válido cuando ocurre el evento EVENT_ASR_ERROR.
arg2intUn parámetro reservado.
asrResultAsrResultEl resultado del reconocimiento de voz.
kwsResultKwsResultLa 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
EstadoDescripción
STATE_OPENLa interacción ha comenzado. Puede abrir el dispositivo de grabación e iniciar la grabación.
STATE_PAUSELa interacción se ha detenido. Puede detener la grabación.
STATE_CLOSELa 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ámetroTipoDescripción
bufferbyte[]Los datos de audio a rellenar.
lenintEl 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ámetroTipoDescripción
eventintUn evento NuiEvent.
infoStringIgnore este parámetro.
info_lenintIgnore este parámetro.
databyte[]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

EventoDescripción
EVENT_TRANSCRIBER_STARTEDLa tarea se inició correctamente.
EVENT_VAD_STARTSe activa justo después de que comienza la tarea. Esto no significa que se haya detectado el inicio del habla.
EVENT_VAD_ENDSe detectó el fin del habla.
EVENT_ASR_PARTIAL_RESULTUn resultado intermedio de reconocimiento de voz.
EVENT_ASR_WARNOcurrió una advertencia que no interrumpe el reconocimiento de voz, como una interrupción de la red cuando la reconexión está habilitada.
EVENT_ASR_ERROROcurrió un error durante el reconocimiento de voz.
EVENT_MIC_ERRORSe activa cuando no se reciben datos de audio durante 2 segundos consecutivos.
EVENT_SENTENCE_ENDSe detecta el final de una oración. Se devuelve un resultado de reconocimiento completo para la oración.
EVENT_TRANSCRIBER_COMPLETEEl reconocimiento de voz ha finalizado.
EVENT_AEC_DATADatos de audio procesados por AEC.