Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR reconocimiento de voz no en tiempo real HarmonyOS SDK_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

Esta guía explica cómo utilizar el SDK de HarmonyOS para reconocimiento de voz no en tiempo real Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR con el fin de convertir voz en texto.

Guía del usuario: Reconocimiento de voz no en tiempo real. Para conocer los requisitos de entrada, como los formatos de audio compatibles y los límites de tamaño y duración de archivos, consulte Especificaciones de audio.

Inicio rápido

Obtener una clave API: Obtener una clave API. Por seguridad, recomendamos configurar la clave API como una variable de entorno.
Descargue el SDK y ejecute el código de ejemplo:
- Descargue el paquete más reciente del SDK.
- Extraiga el paquete TAR. Obtenga el SDK en formato HAR del directorio neonui y agréguelo a las dependencias de su proyecto. Para la integración con C++, obtenga las bibliotecas dinámicas y los archivos de encabezado de native/libs y native/include en el paquete TAR.
- Abra el proyecto en DevEco Studio. El código de ejemplo se encuentra en DashFunAsrFileTranscriberPage.ets. Reemplace la clave API para probar la función.

Pasos de invocación

Modo síncrono

Inicialice el SDK.
Configure los parámetros según sus requisitos comerciales.
Llame a startFileTranscriber para iniciar una tarea de reconocimiento con async_request establecido en false.
En la interfaz onFileTransEventCallback, escuche el evento EVENT_FILE_TRANS_RESULT para obtener el resultado final del reconocimiento.
Llame a release para liberar los recursos del SDK.

Modo asíncrono

Inicialice el SDK.
Configure los parámetros según sus requisitos comerciales.
Llame a startFileTranscriber para iniciar una tarea de reconocimiento con async_request establecido en true.
Llame a queryFileTranscriber para consultar el progreso o el resultado del reconocimiento.
En la interfaz onFileTransEventCallback, escuche el evento EVENT_FILE_TRANS_QUERY_RESULT para obtener el resultado de la consulta actual.
En la interfaz onFileTransEventCallback, escuche el evento EVENT_FILE_TRANS_RESULT para obtener el resultado final del reconocimiento.
Llame a release para liberar los recursos del SDK.

Parámetros de solicitud

Parámetros de conexión y control

Pase una cadena JSON al parámetro parameters de initializeFileTrans para configurar los siguientes parámetros. Ejemplo: La siguiente cadena JSON es un ejemplo y no incluye todos los parámetros. Agregue los parámetros según sea necesario:

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

Descripciones de parámetros

Parámetro	Tipo	Obligatorio	Descripción
`url`	`string`	Sí	El punto de conexión. Esto está fijado en `wss://{WorkspaceId}.cn-beijing.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. Recomendamos utilizar una clave API temporal más segura con un periodo de validez corto para reducir el riesgo de filtrar una clave a largo plazo.
`service_mode`	`string`	Sí	El modo de operación. Para el reconocimiento de voz no en tiempo real, esto está fijado en `"1"`.
`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 seguimiento de registros y la resolución de problemas.
`debug_path`	`string`	No	La ruta de almacenamiento para los archivos de registro. Este parámetro solo surte efecto si establece `save_log` en true al llamar a initializeFileTrans. En este caso, debe especificar una ruta de archivo de registro. De lo contrario, se producirá un error. Se conservan un máximo de dos archivos de registro localmente.
`max_log_file_size`	`number`	No	Establece el tamaño máximo de un archivo de registro en bytes. Este parámetro solo surte efecto si establece `save_log` en true al llamar a initializeFileTrans. Valor predeterminado: 104857600 (100 * 1024 * 1024 bytes, o 100 MiB).

Parámetros de efecto de reconocimiento de voz

Configure el parámetro nls_config mediante setParams, o configure todos los parámetros de efecto de reconocimiento de voz mediante startFileTranscriber. Ejemplo: La siguiente cadena JSON es un ejemplo y no incluye todos los parámetros. Agregue los parámetros según sea necesario:

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false,
        "parameters": {
            "speech_noise_threshold": 0.0
        }
    }
}

Descripciones de parámetros

Parámetro	Tipo	Obligatorio	Descripción
`file_urls`	`array[string]`	Sí	Una lista de URL para los archivos de audio o video que se van a transcribir. Se admiten HTTP y HTTPS. Una sola solicitud admite únicamente 1 URL. Para conocer los requisitos de entrada, como los formatos de audio compatibles y los límites de tamaño y duración de archivos, consulte Especificaciones de audio. Si un archivo de audio está almacenado en Alibaba Cloud OSS, la API RESTful admite una URL temporal con el prefijo `oss://`, pero el SDK no. Importante Una URL temporal es válida durante 48 horas y no se puede utilizar después de que caduque. No utilice URLs temporales en entornos de producción. La interfaz de credenciales de carga de archivos está limitada a 100 QPS y no se puede escalar horizontalmente. No la utilice en entornos de producción, escenarios de alta concurrencia o pruebas de estrés. En entornos de producción, utilice almacenamiento estable como Alibaba Cloud OSS para garantizar la disponibilidad de archivos a largo plazo y evitar limitaciones de velocidad. - Si no se puede acceder a una URL pública temporal de OSS, configure el encabezado de solicitud `X-DashScope-OssResourceResolve` en `enable`. Este método no se recomienda. El SDK no admite la configuración de encabezados de solicitud.
`async_request`	`boolean`	No	Especifica si se debe utilizar una solicitud asíncrona. Valor predeterminado: `false`. Valores válidos: - true: solicitud asíncrona - false: solicitud síncrona.
`apikey`	`string`	No	Si `apikey` en Parámetros de conexión y control es una clave API temporal, actualícela aquí antes de que caduque.
`nls_config`	`object`	Sí	El objeto de configuración principal de reconocimiento de voz, que contiene parámetros clave para la selección del modelo y el control del efecto de 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	Especifica palabras sensibles para procesar durante el reconocimiento de voz y admite diferentes métodos de procesamiento para distintas palabras. Para obtener más información, consulte Filtrado de palabras sensibles.
`nls_config.channel_id`	`array[integer]`	No	Especifica los índices de las pistas de audio que se deben reconocer en un archivo de audio multipista. Los índices comienzan desde 0. Por ejemplo, `[0]` reconoce la primera pista y `[0, 1]` reconoce la primera y la segunda pista. Si se omite, se procesa la primera pista. ImportanteCada pista especificada se factura por separado. Por ejemplo, `[0, 1]` para un archivo genera dos cargos separados. Valor predeterminado: `[0]`.
`nls_config.diarization_enabled`	`boolean`	No	Especifica si se debe habilitar la diarización de hablantes. Esta función está deshabilitada de forma predeterminada. Solo se aplica a audio mono. El audio multicanal no admite la diarización de hablantes. Cuando está habilitada, el resultado del reconocimiento contiene `speaker_id` para distinguir a los hablantes. NotaSi la diarización de hablantes está habilitada, recomendamos limitar la duración del audio a 2 horas para evitar fallos en el reconocimiento o tiempos de espera agotados. Valor predeterminado: false. Para ver un ejemplo de `speaker_id`, consulte Descripciones de resultados de reconocimiento.
`nls_config.speaker_count`	`integer`	No	ImportanteEste parámetro solo surte efecto cuando la diarización de hablantes está habilitada configurando `diarization_enabled` en `true`. Proporciona un valor de referencia para el número de hablantes. Los valores válidos son números enteros del 2 al 100. De forma predeterminada, el número de hablantes se determina automáticamente. Si se establece este parámetro, solo guía al algoritmo para generar el número especificado y no garantiza dicha cantidad. Sin valor predeterminado.
`nls_config.vocabulary_id`	`string`	No	El ID de lista de palabras clave precompiladas. Cree primero una lista de palabras clave y pase su ID durante el reconocimiento para utilizar las palabras clave de la lista. Esto es adecuado cuando el vocabulario es conocido y relativamente estable, y se necesita reutilizar el mismo vocabulario en varias solicitudes. Para obtener más información, consulte Palabras clave precompiladas.
`nls_config.language_hints`	`array[string]`	No	Especifica los códigos de idioma del audio que se va a reconocer. Si el idioma no se puede determinar de antemano, omita este parámetro y el modelo detectará automáticamente el idioma. Los modelos Qwen-Audio-3.0-ASR-Flash-Filetrans admiten hasta 4 valores. Si se especifican más de 4 valores, solo los primeros 4 surten efecto. Los modelos Fun-ASR admiten solo 1 valor. Si se especifican varios valores, solo el primero surte efecto. Códigos de idioma admitidos: - qwen-audio-3.0-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
`nls_config.parameters`	`object`	No	Configura parámetros adicionales como un objeto JSON.

Interfaces clave

NativeNui

initializeFileTrans

Inicializa una instancia del SDK de transcripción de voz. No vuelva a inicializar la instancia antes de llamar a release.

NotaA diferencia del reconocimiento de voz en tiempo real, la transcripción de archivos de audio no en tiempo real debe utilizar initializeFileTrans y pasar una devolución de llamada INativeFileTransCallback en lugar de usar initialize.

Esta interfaz bloquea el hilo de llamada. Llámela desde un hilo que no sea de UI.

Firma del método

public initializeFileTrans(callback: INativeFileTransCallback,
                           parameters: string,
                           level: number,
                           save_log: boolean = false): number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`callback`	`INativeFileTransCallback`	Una implementación de la interfaz de devolución de llamada de datos y eventos de transcripción de archivos.
`parameters`	`string`	Una cadena JSON que contiene parámetros de autenticación, conexión y depuración. Consulte Parámetros de conexión y control.
`level`	`number`	Controla el nivel de registro del SDK. Los valores válidos están definidos por la enumeración Constants.LogLevel.
`save_log`	`boolean`	Especifica si se deben guardar registros locales. Si este parámetro es `true`, use `debug_path` en Parámetros de conexión y control para especificar una ruta. También puede usar `max_log_file_size` para establecer el tamaño del archivo.

Valor de retorno

setParams

Establece o actualiza únicamente el parámetro nls_config. Si todos los parámetros se proporcionan en startFileTranscriber, no necesita llamar a este método.

Firma del método

public setParams(params: string): number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`params`	`string`	El parámetro `nls_config` en Parámetros de efecto de reconocimiento de voz. Los parámetros fuera 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 startFileTranscriber(params: string, task_id: ArrayBuffer): number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`params`	`string`	Los parámetros de efecto 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`	`ArrayBuffer`	El búfer de ID de tarea. El SDK escribe una cadena de ID de tarea aleatoria generada internamente en este búfer. El búfer debe tener al menos 33 bytes de longitud. El ejemplo utiliza `new ArrayBuffer(64)`. Después de una llamada exitosa, decodifique el búfer para obtener el `task_id` de la tarea.

Valor de retorno

queryFileTranscriber

Consulta el estado actual y el resultado de una tarea asíncrona. Después de una llamada exitosa, el resultado se devuelve mediante el evento EVENT_FILE_TRANS_QUERY_RESULT en la devolución de llamada onFileTransEventCallback.

Firma del método

public queryFileTranscriber(task_id: string): number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`task_id`	`string`	El ID de la tarea a consultar, obtenido del búfer escrito por `startFileTranscriber`.

Valor de retorno

cancelFileTranscriber

Cancela inmediatamente la tarea actual.

Firma del método

public cancelFileTranscriber(task_id: string): number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`task_id`	`string`	El ID de la tarea a cancelar.

Valor de retorno

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, llame a initializeFileTrans para reinicializarla.

Firma del método

public release(): number

Valor de retorno

GetVersion

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

Firma del método

public GetVersion(): string

Valor de retorno

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

INativeFileTransCallback

Define las devoluciones de llamada para eventos de transcripción de archivos y resultados de reconocimiento.

onFileTransEventCallback

Escucha eventos de transcripción de archivos y obtiene resultados de reconocimiento de voz.

Firma del método

onFileTransEventCallback: (event: Constants.NuiEvent, resultCode: number, finish: number,
                           asrResult: AsrResult, taskId: string) => void;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`event`	`Constants.NuiEvent`	El evento de devolución de llamada.
`resultCode`	`number`	Válido solo cuando ocurre el evento `EVENT_ASR_ERROR`.
`finish`	`number`	Indica si la tarea ha finalizado.
`asrResult`	`AsrResult`	El resultado del reconocimiento de voz.
`taskId`	`string`	El ID de la tarea.

Constants.NuiEvent

Los tipos de eventos del SDK de HarmonyOS están definidos por la enumeración Constants.NuiEvent. Los siguientes eventos se aplican a la transcripción de archivos de audio:

Evento	Descripción
`EVENT_FILE_TRANS_CONNECTED`	El servicio está conectado.
`EVENT_FILE_TRANS_UPLOADED`	El archivo de audio a reconocer se ha cargado.
`EVENT_FILE_TRANS_QUERY_RESULT`	El resultado de la consulta de la tarea.
`EVENT_FILE_TRANS_RESULT`	El resultado final del reconocimiento.
`EVENT_ASR_ERROR`	Se produce un error durante el reconocimiento de voz.

Tipos auxiliares

Constants.LogLevel

Los valores de enumeración para el parámetro level son los siguientes:

Valor	Descripción
`LOG_LEVEL_VERBOSE`	Los registros más detallados.
`LOG_LEVEL_DEBUG`	Registros de depuración.
`LOG_LEVEL_INFO`	Registros informativos (predeterminado).
`LOG_LEVEL_WARNING`	Registros de advertencia.
`LOG_LEVEL_ERROR`	Registros de errores.
`LOG_LEVEL_NONE`	Desactiva el registro.

Descargar el resultado

Los resultados del reconocimiento de voz no en tiempo real se generan de forma asíncrona. La respuesta devuelta por el evento EVENT_FILE_TRANS_RESULT contiene transcription_url. Descargue el texto de reconocimiento en formato JSON desde esta URL. La URL tiene un periodo de validez. Descargue el resultado a la brevedad.