Alibaba Cloud Model Studio:SDK de Android para reconocimiento de voz no en tiempo real de Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR

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-3.x-ASR-Flash-Filetrans/Fun-ASR.

Guía del usuario:Reconocimiento de voz no en tiempo real. 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

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.

Modo asíncrono

1. Inicialice el SDK.
2. Configure los parámetros que requiere su negocio.
3. Configure async_request en true y llame a startFileTranscriber para enviar una solicitud de reconocimiento de voz no en tiempo real.
4. Llame a queryFileTranscriber para sondear el progreso y el resultado del reconocimiento.
5. Escuche el evento EVENT_FILE_TRANS_QUERY_RESULT en la interfaz onFileTransEventCallback para obtener el resultado de la consulta actual.
6. Escuche el evento EVENT_FILE_TRANS_RESULT en la interfaz onFileTransEventCallback para obtener el resultado final del reconocimiento.
7. 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ámetro	Tipo	Obligatorio	Descripción
  url	String	Sí	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.
  apikey	String	Sí	La clave API.
  service_mode	String	Sí	El modo de ejecución. Fijado en "1" para el reconocimiento de voz grabada.
  device_id	String	Sí	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_path	String	No	La 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_size	int	No	El 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_level	int	No	El 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ámetro	Tipo	Obligatorio	Descripción
  file_urls	array[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://. Importante 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_request	boolean	No	Si la solicitud de reconocimiento es asíncrona. Predeterminado: false. Valores válidos: true: solicitud asíncrona false: solicitud síncrona
  apikey	string	No	Si 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_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 el control del reconocimiento.
  nls_config.model	string	Sí	El modelo utilizado en el ejemplo. Para información sobre modelos, consulte Modelos y regiones admitidos.
  nls_config.special_word_filter	object	No	Las 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_id	array[integer]	No	El í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. ImportanteCada 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_enabled	boolean	No	Si 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. NotaCuando 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_count	integer	No	ImportanteSurte 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_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.input_context	array	No	Una lista de mensajes que contienen contexto de conversación opcional para mejorar la precisión del reconocimiento. ImportanteEl 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. ImportanteCuando 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_vocabulary	object	No	Palabras 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. ImportantePara los modelos y límites aplicables a palabras clave instantáneas, consulte Palabras clave instantáneas. { "张三": 5, "李四": 5 }
  nls_config.language_hints	array[string]	No	Los 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. Para los modelos Qwen-Audio-3.x-ASR-Flash-Filetrans, puede configurar hasta 4 valores; cualquier valor más allá de los primeros 4 se ignora. Para los modelos Fun-ASR, solo puede configurar 1 valor; si configura varios, solo el primero surte efecto. Haga clic para ver los códigos de idioma admitidos Qwen-Audio-3.x-ASR-Flash-Filetrans, fun-asr: 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ámetro	Tipo	Descripción
  callback	INativeFileTransCallback	La implementación de la interfaz de devolución de llamada 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 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.

• Valor de retorno

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ámetro	Tipo	Descripción
  params	String	El 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 } }

• Valor de retorno

startFileTranscriber

Inicia el reconocimiento.

• Firma del método

public synchronized int startFileTranscriber(String params, byte[] task_id)

• Descripción de parámetros

  Parámetro	Tipo	Descripción
  params	String	Pará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_id	byte[]	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.

• Valor de retorno

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.

• Firma del método

public synchronized int queryFileTranscriber(String task_id)

• Descripción de parámetros

  Parámetro	Tipo	Descripción
  task_id	String	El ID de la tarea a consultar, obtenido del evento EVENT_FILE_TRANS_UPLOADED.

• Valor de retorno

cancelFileTranscriber

Cancela la tarea actual inmediatamente.

• Firma del método

public synchronized int cancelFileTranscriber(String task_id)

• Descripción de parámetros

  Parámetro	Tipo	Descripción
  task_id	String	El ID de la tarea a cancelar, obtenido del evento EVENT_FILE_TRANS_UPLOADED.

• Valor de retorno

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();

• Valor de retorno

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ámetro	Tipo	Descripción
  event	NuiEvent	El evento de devolución de llamada.
  resultCode	int	Válido solo cuando ocurre el evento EVENT_ASR_ERROR.
  asrResult	AsrResult	El resultado del reconocimiento de voz.
  taskId	String	El ID de la tarea.
  arg2	int	Un 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

Evento	Descripción
EVENT_FILE_TRANS_CONNECTED	La conexión al servicio se realizó correctamente.
EVENT_FILE_TRANS_UPLOADED	El archivo de audio a reconocer se cargó correctamente. Ahora puede obtener el task_id de la tarea actual.
EVENT_FILE_TRANS_QUERY_RESULT	Una consulta de resultado de tarea.
EVENT_FILE_TRANS_RESULT	El resultado final del reconocimiento.
EVENT_ASR_ERROR	Ocurrió un error durante el reconocimiento de voz.