Skip to main content

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

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

Para los requisitos de entrada, como formatos de audio compatibles, límites de tamaño de archivo y límites de duración, consulte Especificaciones de audio.

Inicio rápido

  1. Obtener una clave API: Obtener una clave API. Para mayor seguridad, almacene la clave API en una variable de entorno.
  2. Descargue el SDK y ejecute el código de ejemplo:
    • Descargue el paquete más reciente del SDK.
    • Extraiga el paquete ZIP. Encuentre el SDK en formato AAR en el directorio app/libs y agréguelo a las dependencias de su proyecto. Para la integración con Android C++, utilice android_libs y android_include en el 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 DashFunAsrFileTranscriberActivity.java. Reemplace la clave API y luego pruebe la función.

Procedimiento de llamada

  • Modo síncrono
  • Modo asíncrono
  1. Inicialice el SDK.
  2. Configure los parámetros que requiere su negocio.
  3. Configure async_request en false y llame a startFileTranscriber para enviar una solicitud de reconocimiento de voz no en tiempo real y esperar el resultado.
  4. Escuche el evento EVENT_FILE_TRANS_RESULT en la interfaz onFileTransEventCallback para obtener el resultado final del reconocimiento.
  5. Llame a release para liberar los recursos del SDK.

Parámetros de solicitud

Parámetros de conexión y control

Configure estos parámetros pasando una cadena JSON en el argumento parameters de la interfaz initialize. Ejemplo de parámetro La siguiente cadena JSON es un ejemplo y no enumera todos los parámetros. Agregue los parámetros que necesite cuando escriba su código: 
{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
Descripción de parámetros
ParámetroTipoObligatorioDescripción
urlStringSíPuntos de conexión del servicio:
  • wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
  • China (Pekín): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
  • Singapur: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
apikeyStringSíLa clave API.
service_modeStringSíEl modo de ejecución. Fijado en "1" para el reconocimiento de voz grabada.
device_idStringSíUna cadena única que identifica al usuario final. Configúrela como 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 seguimiento de registros y la resolución de problemas.
debug_pathStringNoLa ruta de almacenamiento para el archivo de registro.Este parámetro solo surte efecto cuando save_log se establece en true en la interfaz initialize. En ese caso, debe establecer la ruta del archivo de registro; de lo contrario, se reporta un error.Se conservan como máximo dos archivos de registro localmente.
max_log_file_sizeintNoEl tamaño máximo del archivo de registro, en bytes.Este parámetro surte efecto solo cuando save_log se establece en true en la interfaz 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 (onFileTransLogTrackCallback).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 (desactiva esta función)
Nota: log_track_level y level (configurados a través de la interfaz 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), solo los registros de nivel WARNING o superior (valor >= 3) se envían a la devolución de llamada.

Parámetros de reconocimiento de voz

Configure todos los parámetros de reconocimiento de voz a través de la interfaz startFileTranscriber. Ejemplo de parámetro La siguiente cadena JSON es un ejemplo y no enumera todos los parámetros. Agregue los parámetros que necesite cuando escriba su código: 
{
    "apikey": "st-****",
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}
Descripción de parámetros
ParámetroTipoObligatorioDescripción
file_urlsarray[string]SíUna lista de URL de los archivos de audio o video a transcribir. Se admiten HTTP y HTTPS. Una sola solicitud admite únicamente una URL. Para los requisitos de entrada, como formatos de audio compatibles, límites de tamaño de archivo y límites de duración, consulte Especificaciones de audio.Si la grabación se almacena en Alibaba Cloud OSS, la API RESTful admite URLs temporales con el prefijo oss://, mientras que el SDK no admite URLs temporales con el prefijo oss://.
  • Una URL temporal es válida durante 48 horas y no se puede usar después de que expire. No la use en producción.
  • La interfaz de credenciales de carga tiene un límite de tasa de 100 QPS y no se puede escalar. No la use en escenarios de producción, alta concurrencia o pruebas de carga.
  • Para producción, utilice almacenamiento estable como Alibaba Cloud OSS para mantener los archivos disponibles a largo plazo y evitar límites de tasa.
  • Si una URL de archivo de audio configurada como una URL pública temporal de OSS no es accesible, configure X-DashScope-OssResourceResolve en enable en el encabezado de la solicitud (no recomendado). El SDK no admite la configuración de encabezados de solicitud.
async_requestbooleanNoSi la solicitud de reconocimiento es asíncrona.Predeterminado: false.Valores válidos:
  • true: solicitud asíncrona
  • false: solicitud síncrona
apikeystringNoSi el parámetro apikey en Parámetros de conexión y control es una clave API temporal, puede actualizarla aquí para evitar su caducidad.
nls_configobjectSíEl objeto de configuración principal para el reconocimiento de voz. Contiene parámetros clave como la selección del modelo y el control del reconocimiento.
nls_config.modelstringSíEl nombre del modelo.
nls_config.special_word_filterobjectNoLas palabras sensibles a procesar durante el reconocimiento de voz. Puede establecer un método de manejo diferente para cada palabra sensible. Para más detalles, consulte Filtrado de palabras sensibles.
nls_config.channel_idarray[integer]NoEl índice de las pistas de audio a reconocer en un archivo de audio multipista. El índice comienza en 0. Por ejemplo, [0] reconoce la primera pista, y [0, 1] reconoce la primera y la segunda pista simultáneamente. Si omite este parámetro, solo se procesa la primera pista.
Cada pista especificada se factura de forma independiente. Por ejemplo, solicitar [0, 1] para un solo archivo incurre en dos cargos separados.
Valor predeterminado: [0].
nls_config.diarization_enabledbooleanNoSi se debe habilitar la diarización de hablantes. Deshabilitado de forma predeterminada.Se aplica solo a audio monoaural. El audio multicanal no admite la diarización de hablantes.Cuando está habilitado, el resultado del reconocimiento incluye un campo speaker_id que distingue a los diferentes hablantes.
Cuando la diarización de hablantes está habilitada, mantenga la duración del audio dentro de 2 horas. De lo contrario, el reconocimiento puede fallar o agotar el tiempo de espera.
Predeterminado: false.Para ver un ejemplo de speaker_id, consulte Descripción del resultado de reconocimiento.
nls_config.speaker_countintegerNo
Surte efecto solo cuando la diarización de hablantes está habilitada (diarization_enabled está configurado en true).
Un valor de referencia para el número de hablantes. El rango válido es un entero de 2 a 100 (inclusive).De forma predeterminada, el número de hablantes se detecta automáticamente. Si configura este valor, solo guía al algoritmo para generar el recuento especificado cuando sea posible y no garantiza ese recuento exacto.Sin valor predeterminado.
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.input_contextarrayNoUna lista de mensajes que contienen contexto de conversación opcional para mejorar la precisión del reconocimiento.
El contexto ayuda a mejorar el reconocimiento de términos específicos del dominio. Para su uso, consulte Mejora de contexto.Puede incluir hasta 5 mensajes de cada tipo de contexto: input_text y text. Si se supera este límite, solo se conservan los 5 mensajes más recientes de cada tipo. La longitud combinada de los campos text en los mensajes de user y assistant en cada turno no debe exceder los 400 caracteres. Cada carácter cuenta como 1. El texto excedente se trunca desde el final.
Cuando incluya contexto, organice messages por turno de conversación. En cada turno, el mensaje de user (tipo input_text) debe preceder al mensaje correspondiente de assistant (tipo text). El mensaje de user que contiene input_audio debe ser el último mensaje en el arreglo messages.
[
  {
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "你好啊，我是通义千问，有什么可以帮助你的？"
      }
    ]
  }
]
nls_config.instant_vocabularyobjectNoPalabras clave instantáneas, pasadas como pares clave-valor. Cada clave es el texto de la palabra clave (string) y cada valor es su peso (integer). No se requiere una lista de palabras clave precompilada. Utilice este parámetro para palabras clave temporales a nivel de sesión.Los pesos válidos son números enteros de 1 a 5, o 50. Un peso mayor de 1 a 5 aumenta la probabilidad de que el modelo genere la palabra clave. Un peso de 50 define una súper palabra clave y mejora significativamente la recuperación. Puede especificar hasta 50 súper palabras clave.Si también configura palabras clave precompiladas, ambos conjuntos se fusionan. Si el conjunto fusionado supera las 2000 palabras clave, se seleccionan 2000 al azar. Para su uso, consulte Palabras clave instantáneas.
Para los modelos y límites aplicables a palabras clave instantáneas, consulte Palabras clave instantáneas.
{
  "张三": 5,
  "李四": 5
}
nls_config.language_hintsarray[string]NoLos códigos de idioma a reconocer. Si no puede determinar el idioma con antelación, déjelo sin configurar y el modelo detectará el idioma automáticamente.Puede especificar hasta 4 valores. Si especifica más, solo se aplican los primeros 4.
  • 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

Interfaces clave

NativeNui

initialize

Inicializa la instancia del SDK de reconocimiento de voz. El SDK es un singleton. No lo inicialice nuevamente antes de llamar a release. Esta interfaz bloquea la ejecución, así que llámela en un hilo que no sea de UI. Firma del método 
public synchronized int initialize(final INativeFileTransCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)
Descripción de parámetros
ParámetroTipoDescripción
callbackINativeFileTransCallbackLa implementación de la interfaz de devolución de llamada 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 localmente. Si es true, especifique la ruta con debug_path en Parámetros de conexión y control y, opcionalmente, configure el tamaño del archivo con max_log_file_size.

setParams

Utilice esta interfaz para configurar o actualizar los parámetros de nls_config por separado. Si proporciona todos los parámetros a la vez en startFileTranscriber, no necesita llamar a este método. Firma del método 
public synchronized int setParams(String params);
Descripción de parámetros
ParámetroTipoDescripción
paramsStringEl parámetro nls_config en Parámetros de reconocimiento de voz. Los parámetros distintos de nls_config no se pueden configurar mediante este método.Ejemplo:
{
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}

startFileTranscriber

Inicia el reconocimiento. Firma del método 
public synchronized int startFileTranscriber(String params, byte[] task_id)
Descripción de parámetros
ParámetroTipoDescripción
paramsStringParámetros de reconocimiento de voz.Ejemplo:
{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}
task_idbyte[]El ID de la tarea. El SDK genera una cadena aleatoria internamente. Usted obtiene el task_id después de que esta interfaz regrese exitosamente.

queryFileTranscriber

Utilice esta interfaz para consultar el estado actual y el resultado de una tarea asíncrona. Después de que la llamada se realice correctamente, el resultado se devuelve a través del evento EVENT_FILE_TRANS_QUERY_RESULT en la devolución de llamada onFileTransEventCallback.
Obtenga el task_id pasado a este método del evento EVENT_FILE_TRANS_UPLOADED.
Firma del método 
public synchronized int queryFileTranscriber(String task_id)
Descripción de parámetros
ParámetroTipoDescripción
task_idStringEl ID de la tarea a consultar, obtenido del evento EVENT_FILE_TRANS_UPLOADED.

cancelFileTranscriber

Cancela la tarea actual inmediatamente. Firma del método 
public synchronized int cancelFileTranscriber(String task_id)
Descripción de parámetros
ParámetroTipoDescripción
task_idStringEl ID de la tarea a cancelar, obtenido del evento EVENT_FILE_TRANS_UPLOADED.

release

Libera todos los recursos internos del SDK. Después de llamar a este método, la instancia del SDK queda inutilizable. Para volver a utilizarlo, debe llamar a initialize para inicializarlo nuevamente. Firma del método 
public synchronized int release();

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.

INativeFileTransCallback: callbacks del listener

onFileTransEventCallback: escuchar eventos y resultados de reconocimiento

Firma del método 
void onFileTransEventCallback(NuiEvent event, final int resultCode, final int arg2, AsrResult asrResult, String taskId);
Descripción de parámetros
ParámetroTipoDescripción
eventNuiEventEl evento de devolución de llamada.
resultCodeintVálido solo cuando ocurre el evento EVENT_ASR_ERROR.
asrResultAsrResultEl resultado del reconocimiento de voz.
taskIdStringEl ID de la tarea.
arg2intUn parámetro reservado.

onFileTransLogTrackCallback: escuchar registros de seguimiento

Este callback recibe los registros internos detallados del SDK para el diagnóstico y depuración de problemas. 
default void onFileTransLogTrackCallback(Constants.LogLevel level, String log)

NuiEvent: tipos de eventos

EventoDescripción
EVENT_FILE_TRANS_CONNECTEDLa conexión al servicio se realizó correctamente.
EVENT_FILE_TRANS_UPLOADEDEl archivo de audio a reconocer se cargó correctamente. Ahora puede obtener el task_id de la tarea actual.
EVENT_FILE_TRANS_QUERY_RESULTUna consulta de resultado de tarea.
EVENT_FILE_TRANS_RESULTEl resultado final del reconocimiento.
EVENT_ASR_ERROROcurrió un error durante el reconocimiento de voz.