SDK de HarmonyOS para reconocimiento de voz en tiempo real de Paraformer 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 en tiempo real de Paraformer con el fin de convertir voz a texto.

ImportanteAlibaba Cloud Model Studio ha introducido un dominio específico del espacio de trabajo para la región China (Beijing). El dominio ofrece un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar de dashscope.aliyuncs.com a {WorkspaceId}.cn-beijing.maas.aliyuncs.com.

Reemplace {WorkspaceId} con su ID de espacio de trabajo real. El dominio existente permanece disponible.

Guía del usuario: Para introducciones a los modelos y recomendaciones de selección, consulte Reconocimiento de voz en tiempo real - Fun-ASR y Paraformer.

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.

NotaPara 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 DashParaformerSpeechTranscriberPage.ets. Reemplace la clave API para probar la función.

Pasos de invocación

Inicialice el SDK.
Configure los parámetros según sus requisitos empresariales: Utilice el parámetro parameters de initialize para establecer los parámetros de conexión y control, y utilice setParams para establecer los parámetros de efecto de reconocimiento de voz.
Llame a startDialog para iniciar el reconocimiento.
En la devolución de llamada onNuiAudioStateChanged, inicie el dispositivo de grabación según el estado del audio.
En la devolución de llamada onNuiNeedAudioData, proporcione continuamente datos de audio grabados.
En la devolución de llamada onNuiEventCallback, escuche eventos y obtenga resultados de reconocimiento de voz.
Llame a stopDialog para detener el reconocimiento y escuche el evento EVENT_TRANSCRIBER_COMPLETE para confirmar que el reconocimiento ha finalizado.
Cuando ya no se necesite el reconocimiento de voz, 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 initialize para configurar los siguientes parámetros. Ejemplo: La siguiente cadena JSON es un ejemplo y no incluye todos los parámetros. Agregue parámetros según sea necesario:

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "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-ws/v1/inference`. 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 en tiempo real, este valor 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 archivos de registro. Este parámetro solo surte efecto si establece `save_log` en true al llamar a initialize. 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.
`save_wav`	`string`	No	Especifica si se deben guardar archivos de audio para depuración. Los archivos de audio se guardan en `debug_path`. Valor predeterminado: `"false"`. Valores válidos: - `"true"`: sí - `"false"`: no. Este parámetro solo surte efecto si establece `save_log` en true al llamar a initialize. También debe establecer `debug_path`.
`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 initialize. Valor predeterminado: 104857600 (100 * 1024 * 1024 bytes, o 100 MiB).
`log_track_level`	`number`	No	Controla el nivel de filtrado del contenido de registro enviado externamente a través de la devolución de llamada `onNuiLogTrackCallback`. Valor 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 (deshabilita esta función). Nota: `log_track_level` y `level`, que se establece mediante initialize, determinan conjuntamente qué registros se envían a la devolución de llamada. Un nivel de registro debe ser mayor o igual tanto a `log_track_level` como a `level` para activar la devolución de llamada. Por ejemplo, si `log_track_level` es 2 (INFO) y `level` es 3 (WARNING), solo los registros de nivel WARNING o superior (valor >=3) activan la devolución de llamada.

Parámetros de efecto de reconocimiento de voz

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

{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

Descripciones de parámetros

Parámetro de nivel 1	Tipo	Obligatorio	Descripción
`service_type`	`int`	Sí	El tipo de servicio de voz. Para el reconocimiento de voz en tiempo real, este valor está fijado en `4`.
`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.sr_format`	`string`	Sí	El formato del audio a reconocer. Formatos admitidos: pcm, wav y opus. Importante opus: El audio fuente debe estar codificado en PCM. El SDK lo codifica en OPUS. wav/pcm: El audio debe estar codificado en PCM.
`nls_config.sample_rate`	`int`	Sí	La frecuencia de muestreo del audio a reconocer, en Hz. Esto varía según el modelo: - paraformer-realtime-v2 admite cualquier frecuencia de muestreo. - paraformer-realtime-8k-v2 solo admite 8000 Hz.
`nls_config.disfluency_removal_enabled`	`boolean`	No	Especifica si se deben eliminar las disfluencias, como palabras de relleno. Valor predeterminado: false.
`nls_config.language_hints`	`array[string]`	No	Especifica los códigos de idioma del audio a reconocer. Si el idioma no se puede determinar de antemano, omita este parámetro y el modelo detectará automáticamente el idioma. 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. Este parámetro solo surte efecto para los modelos que admiten múltiples idiomas.
`nls_config.semantic_punctuation_enabled`	`boolean`	No	Especifica el modo de segmentación de oraciones. Valor predeterminado: false. Valores válidos: - true: Habilita la segmentación semántica y deshabilita la segmentación VAD. - false: Habilita la segmentación VAD y deshabilita la segmentación semántica. La segmentación semántica es más precisa y es adecuada para la transcripción de reuniones. La segmentación VAD (Detección de Actividad de Voz) tiene menor latencia y es adecuada para la interacción en tiempo real. Este parámetro solo surte efecto para los modelos v2 y posteriores.
`nls_config.max_sentence_silence`	`int`	No	El umbral de silencio para la segmentación de oraciones VAD (Detección de Actividad de Voz), en milisegundos. Valor predeterminado: 800. Rango válido: `[200, 6000]`. Cuando el silencio después de un segmento supera este umbral, el sistema determina que la oración ha terminado. Este parámetro solo surte efecto cuando `semantic_punctuation_enabled` es false y el modelo es v2 o posterior.
`nls_config.multi_threshold_mode_enabled`	`boolean`	No	Especifica si se debe habilitar el modo de prevención de segmentos excesivamente largos. Este modo evita que los segmentos VAD sean demasiado largos. Valor predeterminado: false (deshabilitado). Valores válidos: - true: habilita el modo - false: deshabilita el modo. Este parámetro solo surte efecto cuando `semantic_punctuation_enabled` es false y el modelo es v2 o posterior.
`nls_config.punctuation_prediction_enabled`	`boolean`	No	Especifica si se debe agregar puntuación automáticamente a los resultados de reconocimiento. Valor predeterminado: true. Valores válidos: - true: sí - false: no. Este parámetro solo surte efecto en modelos v2 y posteriores.
`nls_config.heartbeat`	`boolean`	No	Especifica si se debe mantener una conexión persistente con el servidor. Valor predeterminado: false. Valores válidos: - true: La conexión permanece activa mientras se envía continuamente audio silencioso. - false: Incluso si se envía continuamente audio silencioso, la conexión expira después de un período de tiempo. El tiempo de espera es un valor predeterminado del servidor y no se puede configurar en el cliente. Este parámetro solo surte efecto en modelos v2 y posteriores.
`nls_config.inverse_text_normalization_enabled`	`boolean`	No	Especifica si se debe habilitar la normalización inversa de texto (ITN). Cuando está habilitada, los numerales chinos se convierten a números arábigos. Valor predeterminado: true (habilitado). Valores válidos: - true: habilitado - false: deshabilitado. Este parámetro solo surte efecto en modelos v2 y posteriores.
`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

initialize

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

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

Firma del método

public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`callback`	`INativeNuiCallback`	Una implementación de la interfaz de devolución de llamada de eventos y datos.
`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 los parámetros de efecto de reconocimiento de voz en formato JSON. Llame a esta interfaz antes de startDialog.

Firma del método

public setParams(params: string): number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`params`	`string`	Los parámetros de efecto de reconocimiento de voz.

Valor de retorno

startDialog

Inicia el reconocimiento.

Firma del método

public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`vad_mode`	`Constants.VadMode`	El modo VAD. Este valor está fijado en `Constants.VadMode.TYPE_P2T`.
`dialog_params`	`string`	Si la clave de API temporal especificada por `apikey` en Parámetros de conexión y control ha caducado, actualícela aquí. El valor está en formato JSON: `typescript { "apikey": "st-****" }`

Valor de retorno

stopDialog

Detiene el reconocimiento. Después de llamar a esta interfaz, el servidor devuelve el resultado final del reconocimiento y finaliza la tarea.

Firma del método

public stopDialog(): number

Valor de retorno

cancelDialog

Detiene inmediatamente el reconocimiento sin esperar a que el servidor devuelva el resultado final del reconocimiento.

Firma del método

public cancelDialog(): number

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

INativeNuiCallback

Escucha eventos, estados de audio, cambios de volumen y registros durante el reconocimiento de voz en tiempo real.

onNuiEventCallback

Escucha eventos de reconocimiento y obtiene resultados de reconocimiento de voz.

Firma del método

onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => 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`.
`asrResult`	`AsrResult`	El resultado del reconocimiento de voz.
`kwsResult`	`KwsResult`	La función de activación por voz. No necesita utilizar este parámetro.
`arg2`	`number`	Un parámetro reservado.

onNuiAudioStateChanged

El SDK utiliza esta devolución de llamada para indicar cuándo debe iniciarse o detenerse la grabación.

Firma del método

onNuiAudioStateChanged: (state: Constants.AudioState) => void

Descripciones de AudioState

Estado	Descripción
`STATE_OPEN`	La interacción comienza. Puede iniciar el dispositivo de grabación.
`STATE_PAUSE`	La interacción está en pausa. Puede pausar la grabación.
`STATE_CLOSE`	La interacción se detiene. Puede detener completamente el dispositivo de grabación.

onNuiAudioRMSChanged

Supervisa el volumen de los datos de audio grabados para su visualización en la interfaz de usuario.

Firma del método

onNuiAudioRMSChanged: (val: number) => number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`val`	`number`	El volumen de los datos de audio grabados. El rango de salida es generalmente `[-160, 0]`.

onNuiNeedAudioData

Después de que se inicia el reconocimiento, esta devolución de llamada se activa continuamente. Proporcione los datos de audio a reconocer en la devolución de llamada.

Firma del método

onNuiNeedAudioData: (buffer: ArrayBuffer) => number

Descripciones de parámetros

Parámetro	Tipo	Descripción
`buffer`	`ArrayBuffer`	Los datos de audio a proporcionar. El SDK utiliza `buffer.byteLength` como el número de bytes solicitado.

Valor de retorno

El número real de bytes proporcionados. Un valor de retorno de <=0 indica un error o ausencia de datos.

onNuiLogTrackCallback

Este callback recibe registros internos detallados del SDK para resolución de problemas y depuración.

onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

Constants.NuiEvent

Los tipos de eventos del SDK de HarmonyOS están definidos por la enumeración Constants.NuiEvent. Los siguientes eventos se aplican al reconocimiento de voz en tiempo real:

Evento	Descripción
`EVENT_TRANSCRIBER_STARTED`	La tarea se inicia correctamente.
`EVENT_VAD_START`	Este evento se activa inmediatamente después de que se inicia la tarea. No indica que se haya detectado el inicio del habla.
`EVENT_VAD_END`	Se detecta el final del habla.
`EVENT_ASR_PARTIAL_RESULT`	Un resultado intermedio del reconocimiento de voz.
`EVENT_ASR_RESULT`	Un resultado completo de reconocimiento de voz.
`EVENT_ASR_ERROR`	Se produce un error durante el reconocimiento de voz.
`EVENT_MIC_ERROR`	Este evento se activa cuando no se reciben datos de audio durante 2 segundos consecutivos.
`EVENT_SENTENCE_START`	Se detecta el inicio de una oración.
`EVENT_SENTENCE_END`	Se detecta el final de una oración y se devuelve un resultado de reconocimiento completo.
`EVENT_TRANSCRIBER_COMPLETE`	El reconocimiento de voz finaliza.

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.

Gestión de dispositivos de audio

A diferencia de Android, que utiliza AudioRecord, HarmonyOS utiliza AudioCapturer de @kit.AudioKit para capturar audio. El ejemplo del producto encapsula esta lógica en la clase de utilidad AudioRecorder.ets, que puede reutilizar directamente.

Creación: audio.createAudioCapturer(capturerOptions) crea asíncronamente el captador con una frecuencia de muestreo fija de 16 kHz, profundidad de bits de 16 y un canal (SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW).
Evento de datos: capturer.on('readData', (buffer: ArrayBuffer) => void) obtiene continuamente datos de audio grabados. Almacene los datos en búfer en una cola para que la devolución de llamada onNuiNeedAudioData pueda recuperarlos según sea necesario.
Evento de estado: capturer.on('stateChange', (state: audio.AudioState) => void). STATE_RUNNING indica que la grabación ha comenzado y STATE_STOPPED indica que la grabación se ha detenido.
Control: start() inicia, stop() detiene y release() libera el captador.

NotaHarmonyOS crea AudioCapturer de forma asíncrona. Llame a start() solo después de que se complete la creación. Por lo tanto, no cree e inicie inmediatamente un grabador cuando ocurra STATE_OPEN. Créelo primero y luego llame a start() en la devolución de llamada STATE_OPEN. El ejemplo crea el grabador durante doInit y lo inicia durante onNuiAudioStateChanged. Cuando ocurra STATE_CLOSE, detenga el grabador pero conserve la instancia para su reutilización. Libérelo en release.

Declaración de permisos

Declare el permiso de micrófono en module.json5 para utilizar la grabación:

{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}