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

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. 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 nombre del modelo.
`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. Cada 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. Si 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	Este 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. Puede especificar hasta 4 valores. Si especifica más, solo se aplican los primeros 4. Haga clic para ver los códigos de idioma admitidos 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.

A 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.

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 } }`

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.

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`.

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.

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

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.

​Inicio rápido

​Pasos de invocación

​Modo síncrono

​Modo asíncrono

​Parámetros de solicitud

​Parámetros de conexión y control

​Parámetros de efecto de reconocimiento de voz

​Interfaces clave

​NativeNui

​initializeFileTrans

​setParams

​startFileTranscriber

​queryFileTranscriber

​cancelFileTranscriber

​release

​GetVersion

​INativeFileTransCallback

​onFileTransEventCallback

​Constants.NuiEvent

​Tipos auxiliares

​Constants.LogLevel

​Descargar el resultado

Inicio rápido

Pasos de invocación

Modo síncrono

Modo asíncrono

Parámetros de solicitud

Parámetros de conexión y control

Parámetros de efecto de reconocimiento de voz

Interfaces clave

NativeNui

initializeFileTrans

setParams

startFileTranscriber

queryFileTranscriber

cancelFileTranscriber

release

GetVersion

INativeFileTransCallback

onFileTransEventCallback

Constants.NuiEvent

Tipos auxiliares

Constants.LogLevel

Descargar el resultado