SDK de HarmonyOS para reconocimiento de voz no en tiempo real Paraformer

Guía del usuario: Reconocimiento de voz no en tiempo real

Inicio rápido

Obtención de una clave de API: Obtención y configuración de una clave de API. Por motivos de seguridad, recomendamos configurar la clave de API como una variable de entorno.
Para otorgar acceso temporal a aplicaciones o usuarios externos, o para controlar estrictamente operaciones de alto riesgo como acceder o eliminar datos confidenciales, utilice una clave de API temporal. Una clave de API temporal tiene una validez predeterminada de 60 segundos. Obtenga una nueva después de que caduque.
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 DashParaformerFileTranscriberPage.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 parámetros según sea necesario:

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"paraformer-v2",
        "disfluency_removal_enabled":false,
        "timestamp_alignment_enabled": false
    }
}

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 los protocolos HTTP y HTTPS. Una sola solicitud admite únicamente 1 URL. Si un archivo de audio está almacenado en Alibaba Cloud OSS, el SDK no admite una URL temporal que utilice el prefijo `oss://`. - Formatos de audio: `aac`, `amr`, `avi`, `flac`, `flv`, `m4a`, `mkv`, `mov`, `mp3`, `mp4`, `mpeg`, `ogg`, `opus`, `wav`, `webm`, `wma` y `wmv`. Debido a que los formatos de audio y video tienen muchas variantes, es técnicamente imposible probarlos todos. La API no puede garantizar que cada formato se reconozca correctamente. Pruebe su archivo para verificar que produce un resultado de reconocimiento válido. - Tasas de muestreo de audio varían según el modelo: - paraformer-v2 admite cualquier tasa de muestreo. - paraformer-8k-v2 admite únicamente 8 kHz. - Tamaño y duración del archivo de audio: El archivo no puede superar los 2 GB y su duración no puede exceder las 12 horas. Para procesar un archivo que supere estos límites, preprocéselo para reducir su tamaño. Para conocer las mejores prácticas, consulte Preprocesar archivos de video para mejorar la eficiencia de transcripción en el reconocimiento de archivos de audio.
`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 de reconocimiento de voz.
`nls_config.language_hints`	`array[string]`	No	Especifica los códigos de idioma para el audio a reconocer. Este parámetro se aplica únicamente a paraformer-v2. Valor predeterminado: `["zh", "en"]`. Códigos de idioma admitidos: - zh: chino - en: inglés - ja: japonés - yue: cantonés - ko: coreano - de: alemán - fr: francés - ru: ruso.
`nls_config.disfluency_removal_enabled`	`boolean`	No	Especifica si se deben eliminar las disfluencias, como las muletillas. Valor predeterminado: false. Valores válidos: - true: elimina disfluencias - false: conserva disfluencias.
`nls_config.timestamp_alignment_enabled`	`boolean`	No	Especifica si se debe habilitar la alineación de marcas de tiempo. Valor predeterminado: false. Valores válidos: - true: habilitado - false: deshabilitado.
`nls_config.special_word_filter`	`object`	No	Especifica las palabras sensibles que se deben procesar durante el reconocimiento de voz y admite diferentes métodos de procesamiento para distintas palabras. Si se omite este parámetro, se habilita la lógica integrada de filtrado de palabras sensibles. Las palabras que coincidan con la lista de palabras sensibles de Alibaba Cloud Model Studio se reemplazarán por el mismo número de caracteres ``. Si se especifica este parámetro, las palabras coincidentes pueden reemplazarse por caracteres `` o eliminarse. El valor es un objeto JSON con el siguiente formato: `{ "filter_with_signed": { "word_list": ["test"] }, "filter_with_empty": { "word_list": ["start", "happen"] }, "system_reserved_filter": true }`. Descripciones de los campos JSON: - `filter_with_signed`: Un objeto opcional que especifica las palabras que se deben reemplazar por el mismo número de caracteres ``. En el ejemplo anterior, el resultado para "Ayúdame a probar este código" es "Ayúdame a *** este código". Su campo `word_list` es una matriz de cadenas que se deben reemplazar. - `filter_with_empty`: Un objeto opcional que especifica las palabras que se deben eliminar del resultado. En el ejemplo anterior, el resultado para "El juego está a punto de comenzar, ¿verdad?" es "El juego está a punto de, ¿verdad?". Su campo `word_list` es una matriz de cadenas que se deben eliminar. - `system_reserved_filter`: Un valor booleano opcional. Valor predeterminado: true. Especifica si se deben habilitar las reglas integradas de palabras sensibles. Si se establece en `true`, las palabras que coincidan con la lista de palabras sensibles de Alibaba Cloud Model Studio se reemplazarán por el mismo número de caracteres `*`.
`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. Para ver un ejemplo de `speaker_id`, consulte Descripciones de resultados de reconocimiento.
`nls_config.speaker_count`	`integer`	No	Un valor de referencia para el número de hablantes. Para utilizar esta función, establezca `diarization_enabled` en `true`. De forma predeterminada, el número de hablantes se determina automáticamente. Si se establece este parámetro, solo guía al algoritmo para que genere el número especificado y no garantiza dicha cantidad. Rango válido: `[2, 100]`. El mínimo es 2 porque esta función distingue a múltiples hablantes.
`nls_config.vocabulary_id`	`string`	No	El ID de vocabulario de palabras clave, que mejora la precisión de reconocimiento de palabras específicas. Este parámetro se aplica a modelos v2 y posteriores. Para obtener más información, consulte Palabras clave personalizadas.

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.

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":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_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":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_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.

​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