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

El SDK de HarmonyOS para reconocimiento de voz no en tiempo real Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash convierte voz en texto.

Guía del usuario: Reconocimiento de voz no en tiempo real. Para formatos de audio admitidos, límites de tamaño de archivo, límites de duración y otros requisitos de entrada, consulte Especificaciones de audio.

Inicio rápido

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

Procedimiento de llamada

Modo síncrono

Inicializar el SDK
Configure los parámetros según sus requisitos comerciales
Llame a startFileTranscriber para enviar una solicitud de reconocimiento de voz no en tiempo real y esperar el resultado.
Utilice onFileTransEventCallback para escuchar el evento EVENT_FILE_TRANS_RESULT y 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 del método initializeFileTrans para configurar estos ajustes.

Ejemplo de parámetro: La siguiente cadena JSON es un ejemplo y no enumera todos los parámetros. Agregue parámetros según sea necesario en su código:

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

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`url`	`string`	Sí	El punto de conexión del servicio. Establezca este parámetro en `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`. Reemplace `{WorkspaceId}` con su ID de espacio de trabajo real.
`apikey`	`string`	Sí	La clave API. Recomendamos utilizar una clave API temporal de corta duración y mayor seguridad para reducir el riesgo de exponer una clave de larga duración.
`service_mode`	`string`	Sí	El modo de operación. Para el reconocimiento de voz no en tiempo real, establezca este parámetro en `"1"`.
`device_id`	`string`	Sí	Una cadena única que identifica al usuario final. Puede usar 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 rastreo de registros y la resolución de problemas.
`debug_path`	`string`	No	La ruta para los archivos de registro. Este parámetro solo tiene efecto cuando llama a initializeFileTrans con `save_log` establecido en true. En este caso, debe especificar la ruta del archivo de registro. De lo contrario, se producirá un error. Se conservan hasta dos archivos de registro localmente.
`max_log_file_size`	`number`	No	El tamaño máximo del archivo de registro en bytes. Este parámetro solo tiene efecto cuando llama a initializeFileTrans con `save_log` establecido en true. Valor predeterminado: 104857600 (100 * 1024 * 1024 bytes, o 100 MiB).

Parámetros de reconocimiento

Utilice setParams para configurar los parámetros de nls_config, o utilice startFileTranscriber para configurar todos los parámetros de reconocimiento.

Ejemplo de parámetro: La siguiente cadena JSON es un ejemplo y no enumera todos los parámetros. Agregue parámetros según sea necesario en su código:

{
  "apikey": "st-****",
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`apikey`	`string`	No	Si Parámetros de conexión y control `apikey` utiliza una clave API temporal, puede actualizarla aquí para evitar su caducidad.
`nls_config`	`object`	Sí	El objeto de configuración principal de reconocimiento de voz, que incluye el modelo y los parámetros que controlan el reconocimiento.
`nls_config.model`	`string`	Sí	El modelo utilizado en el ejemplo. Para información sobre modelos, consulte Modelos y regiones admitidos.
`nls_config.format`	`string`	Sí	El formato de audio. Establezca este parámetro en el formato real. Los formatos admitidos incluyen `wav`, `mp3`, `opus`. Para más detalles, consulte Especificaciones de audio.
`nls_config.sample_rate`	`string`	No	La frecuencia de muestreo de audio en Hz. Por ejemplo, `16000` indica una frecuencia de muestreo de 16 kHz. Para más detalles, consulte Especificaciones de audio.
`nls_config.vocabulary_id`	`string`	No	El ID de vocabulario precompilado. Cree un vocabulario con antelación y pase su ID durante el reconocimiento para usar sus palabras clave. Use esta opción cuando el vocabulario es conocido, relativamente estable y se reutiliza en varias solicitudes. Para instrucciones de uso, consulte Palabras clave precompiladas.
`nls_config.instant_vocabulary`	`object`	No	Palabras clave instantáneas. Pase pares clave-valor. La clave es el texto de la palabra clave (`string`) y el valor es su peso (`integer`). No necesita crear un vocabulario con antelación. Los pesos válidos son [1, 5] o 50. Dentro de [1, 5], un peso mayor hace que sea más probable que el modelo genere la palabra. Un peso de 50 especifica una súper palabra clave y aumenta significativamente la recuperación. Puede especificar hasta 50 súper palabras clave. Use esta opción para la optimización temporal de palabras clave a nivel de sesión. Cuando se configuran tanto palabras clave instantáneas como precompiladas, el sistema las fusiona. Si la lista fusionada excede 2000 entradas, selecciona aleatoriamente 2000 entradas. Para instrucciones de 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 para el reconocimiento. Si el idioma se desconoce de antemano, omita este parámetro para permitir que el modelo lo detecte automáticamente. Para los modelos Qwen-Audio-3.0-ASR-Flash, se admiten hasta cuatro valores. Si se especifican más, solo los primeros cuatro tienen efecto. Para los modelos Fun-ASR-Flash, solo se admite un valor. Si se especifican múltiples valores, solo el primero tiene efecto. Qwen-Audio-3.x-ASR-Flash, fun-asr-flash-2026-06-15: 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
messages	`array[object]`	Sí	La lista de mensajes. Contiene el audio a reconocer y el contexto de conversación opcional para mejorar el reconocimiento. Consulte las siguientes descripciones.

parámetros de messages:

ImportanteEl contexto mejora la precisión del reconocimiento de términos especializados. Para instrucciones de uso, consulte Mejora de contexto.

Restricciones: Los mensajes de contexto (tipos input_text y text) están limitados a cinco cada uno. Si se supera el límite, solo se conservan los cinco mensajes más recientes. La longitud total del texto de contexto por turno (la suma de las longitudes de los campos user y assistant text) no debe exceder los 400 caracteres. Cada carácter cuenta como uno. Los caracteres excedentes se truncan desde el final.

ImportanteCuando se incluye contexto, los mensajes de messages deben seguir un orden específico. Organice los mensajes de contexto por turno de conversación. Dentro de cada turno, user (tipo input_text) debe preceder al assistant correspondiente (tipo text). El mensaje input_audio user que contiene el audio de entrada debe colocarse al final de messages.

Parámetro Tipo Obligatorio Descripción

Parámetro	Tipo	Obligatorio	Descripción
role	`string`	Sí	El rol del mensaje. Valores válidos: `user` (requerido): Un mensaje de usuario. Cuando type es `input_audio`, representa el audio a reconocer. Cuando type es `input_text`, representa resultados de reconocimiento de turnos anteriores o un vocabulario específico del dominio (contexto opcional). `assistant` (contexto opcional): Respuestas del modelo de lenguaje grande de turnos anteriores.
content	`array[object]`	Sí	La lista de contenido de mensajes. Consulte las siguientes descripciones.

role

string

Sí

El rol del mensaje. Valores válidos:

user (requerido): Un mensaje de usuario. Cuando type es input_audio, representa el audio a reconocer. Cuando type es input_text, representa resultados de reconocimiento de turnos anteriores o un vocabulario específico del dominio (contexto opcional).
assistant (contexto opcional): Respuestas del modelo de lenguaje grande de turnos anteriores.

content

array[object]

Sí

La lista de contenido de mensajes. Consulte las siguientes descripciones.

parámetros de content:

Parámetro	Tipo	Obligatorio	Descripción
type	`string`	Sí	El tipo de contenido. Cada solicitud requiere al menos un mensaje `input_audio` . Valores válidos: `input_audio` (requerido): La entrada de audio a reconocer (el rol es user). También debe proporcionar el objeto `input_audio`. `input_text` (contexto opcional): Resultados de reconocimiento del habla del usuario de turnos anteriores o un vocabulario específico del dominio (el rol es user). También debe proporcionar el campo `text`. `text` (contexto opcional): Respuestas del modelo de lenguaje grande de turnos anteriores (el rol es assistant). También debe proporcionar el campo `text`.
input_audio	`object`	No	Requerido cuando `type` es `input_audio`.
input_audio.data	string	Sí	Los datos de audio a reconocer. Para formatos de audio admitidos, límites de tamaño de archivo, límites de duración y otros requisitos de entrada, consulte Especificaciones de audio. Se admiten los siguientes dos métodos de entrada: URL del archivo de audio: Pase una URL de archivo de audio accesible públicamente. URI de datos Base64: Pase audio codificado en Base64 como un URI de datos. Concatene el prefijo `data:{MIME_TYPE};base64,` con los datos de audio codificados en Base64. Los tipos MIME admitidos incluyen `audio/wav`, `audio/mp3`. Ejemplo (URL): `https://example.com/audio/sample.wav` Ejemplo (Base64): `data:audio/wav;base64,{BASE64_ENCODED_DATA}`
text	`string`	No	Obligatorio cuando `type` es `input_text`, proporcione resultados de reconocimiento del habla del usuario de turnos anteriores o un vocabulario específico del dominio. Cuando `type` es `text`, proporcione respuestas del modelo de lenguaje grande de turnos anteriores. La longitud del texto se cuenta en caracteres, y cada carácter cuenta como uno. La longitud total de todos los campos `text` de los mensajes en cada turno de contexto no debe exceder los 400 caracteres. Los caracteres excedentes se truncan desde el final.

Interfaces clave

NativeNui

initializeFileTrans

Inicialice la instancia del SDK de reconocimiento de voz.

NotaA diferencia del reconocimiento de voz en tiempo real, la transcripción no en tiempo real (de archivos grabados) requiere initializeFileTrans con una devolución de llamada INativeFileTransCallback en lugar de initialize.

Este método es bloqueante. Llámelo 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

Parámetros

Parámetro	Tipo	Descripción
`callback`	`INativeFileTransCallback`	La implementación de la interfaz de devolución de llamada de eventos y datos 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`	El nivel de registro del SDK. Utilice un valor de la enumeración.
`save_log`	`boolean`	Indica si se deben guardar los registros localmente. Si se establece en `true`, use Parámetros de conexión y control para establecer `debug_path` y especificar la ruta, y use `max_log_file_size` para establecer el tamaño del archivo.

setParams

Utilice este método para establecer o actualizar nls_config por separado. No es necesario llamar a este método si todos los parámetros se proporcionan en startFileTranscriber en una sola llamada.

Firma del método

public setParams(params: string): number

Parámetros

Parámetro	Tipo	Descripción
`params`	`string`	Parámetros de reconocimiento en los parámetros de `nls_config`; los parámetros fuera de `nls_config` no se pueden establecer con este método.

startFileTranscriber

Iniciar el reconocimiento.

Firma del método

public startFileTranscriber(params: string, task_id: ArrayBuffer): number

Parámetros

Parámetro Tipo Descripción

Parámetro	Tipo	Descripción
`params`	`string`	Parámetros de reconocimiento. Ejemplo: `{ "apikey": "st-****", "messages": [ { "content": [ { "input_audio": { "data": "{YOUR_AUDIO_URL}" }, "type": "input_audio" } ], "role": "user" } ], "nls_config": { "format": "mp3", "model": "qwen-audio-3.0-asr-flash" } }`
`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. Su longitud en bytes debe ser >= 33 bytes (el ejemplo utiliza `new ArrayBuffer(64)`). Después de una llamada exitosa, decodifique el búfer para obtener el `task_id` de la tarea.

params

string

Parámetros de reconocimiento.
Ejemplo:

{
 "apikey": "st-****",
 "messages": [
 {
 "content": [
 {
 "input_audio": {
 "data": "{YOUR_AUDIO_URL}"
 },
 "type": "input_audio"
 }
 ],
 "role": "user"
 }
 ],
 "nls_config": {
 "format": "mp3",
 "model": "qwen-audio-3.0-asr-flash"
 }
}

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. Su longitud en bytes debe ser >= 33 bytes (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

Utilice este método para consultar el estado actual y el resultado de una tarea asíncrona. Después de una llamada exitosa, el resultado se devuelve a través del evento EVENT_FILE_TRANS_QUERY_RESULT de la devolución de llamada onFileTransEventCallback.

Firma del método

public queryFileTranscriber(task_id: string): number

Parámetros

Parámetro	Tipo	Descripción
`task_id`	`string`	El ID de la tarea a consultar (escrito en el búfer por `startFileTranscriber`).

cancelFileTranscriber

Cancelar inmediatamente la tarea actual.

Firma del método

public cancelFileTranscriber(task_id: string): number

Parámetros

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

release

Libere todos los recursos internos del SDK. Después de esta llamada, la instancia del SDK deja de estar disponible. Para volver a utilizarla, llame a initializeFileTrans para inicializarla nuevamente.

Firma del método

public release(): number

GetVersion

Obtener la versión actual del SDK.

Firma del método

public GetVersion(): string

Valor de retorno

La versión actual del SDK.

INativeFileTransCallback: Callbacks

onFileTransEventCallback: Escuchar eventos y resultados de reconocimiento

Firma del método

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

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.

onFileTransLogTrackCallback: Escuchar registros de rastreo

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

Para utilizar esta devolución de llamada, descargue el paquete del SDK de HarmonyOS con fecha 20260908 o posterior.

onFileTransLogTrackCallback?: (level: Constants.LogLevel, log: string) => void;

Tipos de eventos

En el SDK de HarmonyOS, los tipos de eventos se definen mediante la enumeración Constants.NuiEvent. Los siguientes eventos están relacionados con la transcripción de archivos grabados:

Evento	Descripción
EVENT_FILE_TRANS_CONNECTED	Conectado correctamente al servicio.
EVENT_FILE_TRANS_UPLOADED	El archivo de audio se cargó correctamente.
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	Ocurrió un error durante el reconocimiento de voz.