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
- 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++, utiliceandroid_libsyandroid_includedel 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
parametersdel 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 continuamente datos de grabación 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:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
url | String | Sí | Dirección del servicio:
{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 | Indica 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. |
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 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_wav | String | No | Indica 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:
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 del callback de registro (onNuiLogTrackCallback).Predeterminado: 2.Valores válidos:
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_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:
| 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. Establézcalo en qwen-audio-3.1-asr-flash-message. |
nls_config.sr_format | string | Sí | El formato de audio.Valores válidos:
|
nls_config.sample_rate | int | Sí | La frecuencia de muestreo, en Hz.Solo se admite 16000 Hz. |
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
sentence_end=true) y no es compatible con los resultados intermedios (sentence_end=false). |
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.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_model | string | No | El modelo VAD. Valor predeterminado: far_field_meeting_16k.
|
nls_config.max_sentence_silence | int | No | El 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.heartbeat | boolean | No | Si se deben habilitar los paquetes de latido.Valor predeterminado: false.
|
nls_config.disfluency_removal_enabled | boolean | No | Indica 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_enabled | boolean | No | Indica 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_id | string | No | El 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_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.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:
|
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
| 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 | Indica 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. |
setParams
Establece los Parámetros de reconocimiento de voz en formato JSON. Llame a este método antes de startDialog.
Firma del método
| Parámetro | Tipo | Descripción |
|---|---|---|
params | String | Parámetros de reconocimiento de voz. |
startDialog
Inicia el reconocimiento.
Firma del método
| 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 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: |
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
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
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
| Parámetro | Tipo | Descripción |
|---|---|---|
params | String | Una cadena JSON utilizada para actualizar el comportamiento en tiempo de ejecución, como el contexto de reconocimiento. |
params.type | String | Establezca en "action". |
params.command | String | El comando en tiempo de ejecución. Valores válidos:
|
params.context | String | Cuando 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. |
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 |
|---|---|---|
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. |
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 |
|---|---|---|
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. |
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 eventos y resultados del reconocimiento de voz
Firma del método
| 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
| 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
| 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. |
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 |
|---|---|---|
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.
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. |