Qwen-Audio-ASR-Message SDK de iOS para reconocimiento de voz en tiempo real

Inicio rápido

Obtener una clave de API: Obtener una clave de API
Descargue el SDK y ejecute el código de ejemplo:
- Descargue el paquete más reciente del SDK.
- Extraiga el paquete ZIP y agregue el nuisdk.xcframework incluido a su proyecto.
- En Build Phases → Link Binary With Libraries, agregue nuisdk.xcframework.
- En General → Frameworks, Libraries, and Embedded Content, configure nuisdk.xcframework en Embed & Sign.
- Abra el proyecto de ejemplo en Xcode. El código de ejemplo se encuentra en DashFunAsrSpeechTranscriberViewController.m. Reemplace la clave API por la suya propia para probar la función.

Secuencia de llamadas

Inicialice el SDK.
Configure los parámetros para su caso de uso: utilice la API nui_initialize para establecer los Parámetros de conexión y control, y utilice la API nui_set_params para establecer los Parámetros de calidad de reconocimiento.
Llame a nui_dialog_start para iniciar el proceso de reconocimiento.
En la devolución de llamada onNuiAudioStateChanged, abra el dispositivo de grabación según el estado del audio.
En la devolución de llamada onNuiNeedAudioData, suministre datos de grabación continuamente o llame a nui_update_audio_data para enviar activamente datos de grabación.
En la devolución de llamada onNuiEventCallback, escuche los eventos y recupere los resultados del reconocimiento de voz.
Llame a nui_dialog_cancel para detener el reconocimiento y confirme que ha finalizado escuchando el evento EVENT_TRANSCRIBER_COMPLETE.
Cuando ya no necesite la función de reconocimiento, llame a nui_release para liberar los recursos del SDK.

Parámetros de solicitud

Parámetros de conexión y control

Configure estos parámetros pasando una cadena JSON en el argumento parameters de la API nui_initialize. Parámetros de ejemplo: La siguiente cadena JSON es un ejemplo y no enumera todos los parámetros. Agregue los parámetros que necesite al escribir su código:

{
    "url": "wss://dashscope.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í	Dirección del servicio: `wss://dashscope.aliyuncs.com/api-ws/v1/inference` China (Pekín): `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference` Singapur: `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference` Reemplace `{WorkspaceId}` con su ID de espacio de trabajo real.
`apikey`	`String`	Sí	Clave de API.
`service_mode`	`String`	Sí	Modo de ejecución. Fijado en `"1"` para reconocimiento de voz en tiempo real.
`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 generado en el cliente. Este ID se utiliza principalmente para el rastreo de registros y la solución de problemas.
`audio_update_manually`	`String`	No	Indica si se habilita el envío activo de datos de audio. Valor predeterminado: `"false"`.Si se establece en `"true"` y la versión del SDK admite capacidades de procesamiento de audio en el dispositivo, como AEC o VAD, dichas capacidades se habilitan de forma predeterminada.
`workspace`	`String`	No	La ruta donde se almacenan los archivos de recursos en el dispositivo. Este parámetro es obligatorio cuando `audio_update_manually` se establece en `"true"` y está habilitada una capacidad de procesamiento de audio en el dispositivo, como AEC o VAD.
`debug_path`	`String`	No	Ruta de almacenamiento para el archivo de registro.Este parámetro solo surte efecto cuando `save_log` se establece en `YES` en la API nui_initialize. En ese caso, debe establecer la ruta del archivo de registro; de lo contrario, se producirá un error.Se conservan como máximo dos archivos de registro localmente.
`save_wav`	`String`	No	Indica si se debe guardar un archivo de audio para depuración. El archivo de audio se guarda en `debug_path`.Valor predeterminado: "false".Valores válidos: "true": guarda el archivo. "false": no guarda el archivo. Este parámetro solo surte efecto cuando `save_log` se establece en true en la API nui_initialize. Además, también debe establecerse `debug_path`.
`max_log_file_size`	`int`	No	Tamaño máximo del archivo de registro, en bytes.Este parámetro solo surte efecto cuando `save_log` se establece en `YES` en la API nui_initialize.Predeterminado: 104857600 (100 * 1024 * 1024 bytes, es decir, 100 MiB).
`log_track_level`	`int`	No	Nivel de filtro para el contenido de registro enviado a través de la devolución de llamada de registro (onNuiLogTrackCallback).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` (establecido a través de la API nui_initialize) determinan conjuntamente qué registros se envían finalmente a la devolución de llamada. Un registro se envía a la devolución de llamada solo cuando su valor de nivel es mayor o igual tanto a `log_track_level` como a `level`. Por ejemplo, si `log_track_level` se establece en 2 (INFO) y `level` se establece en 3 (WARNING), entonces solo los registros de nivel WARNING o superior (valor >= 3) se envían a la devolución de llamada.

Parámetros de calidad de reconocimiento

Configure estos parámetros pasando una cadena JSON en el argumento params de la API nui_set_params. Parámetros de ejemplo: La siguiente cadena JSON es un ejemplo y no enumera todos los parámetros. Agregue los parámetros que necesite al escribir su código:

{
    "service_type": 4,
    "nls_config": {
        "model": "qwen-audio-3.1-asr-flash-message",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

Descripciones de parámetros

Parámetro de nivel superior	Tipo	Obligatorio	Descripción
`service_type`	`int`	Sí	Tipo de servicio de voz. Fijado en `4` para reconocimiento de voz en tiempo real.
`nls_config`	`object`	Sí	El objeto de configuración de reconocimiento principal. Contiene parámetros clave como la selección del modelo y los controles de calidad del reconocimiento.
`nls_config.model`	`string`	Sí	El nombre del modelo. Establézcalo en `qwen-audio-3.1-asr-flash-message`.
`nls_config.sr_format`	`string`	Sí	El formato de audio.Valores válidos: `pcm` `opus` Si proporciona datos de audio PCM y establece este parámetro en `opus`, el SDK codifica los datos en Opus internamente.
`nls_config.sample_rate`	`int`	Sí	La frecuencia de muestreo, en Hz.Solo se admite `16000` Hz.
`nls_config.language_hints`	`array[string]`	No	El idioma del audio a reconocer. No hay valor predeterminado; si no se establece, el modelo detecta el idioma automáticamente.Puede configurar hasta 4 valores. Si configura más, solo los primeros 4 surten efecto. 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 Este parámetro solo se aplica a los resultados finales (`sentence_end=true`) y no es compatible con los resultados intermedios (`sentence_end=false`).
`nls_config.keep_dialect`	`boolean`	No	Especifica si se conservan las expresiones dialectales. Valor predeterminado: `false`. Establezca el valor en `false` para transcribir el habla dialectal como texto en mandarín estándar, o en `true` para conservar las expresiones dialectales. Este parámetro solo se aplica a los resultados finales (`sentence_end=true`) y no se admite en los resultados intermedios (`sentence_end=false`).
`nls_config.vad_model`	`string`	No	El modelo VAD. Valor predeterminado: `far_field_meeting_16k`. `near_meeting_16k`: escenarios de campo cercano. `far_field_meeting_16k`: escenarios de campo lejano.
`nls_config.max_sentence_silence`	`int`	No	El umbral de silencio VAD para la segmentación, en ms. Cuando el silencio después de un segmento de voz supera este umbral, el sistema determina que la oración ha terminado.Valor predeterminado: 800.Valores válidos: [200, 6000].
`nls_config.heartbeat`	`boolean`	No	Si se deben habilitar los paquetes de latido.Valor predeterminado: false. true: Mantiene activa la conexión con el servidor incluso cuando se envía audio silencioso de forma continua. false (predeterminado): Incluso cuando se envía audio silencioso de forma continua, la conexión expira y se cierra después de un período de tiempo. El audio silencioso se refiere al contenido en un archivo de audio o flujo de datos que no contiene señal de sonido. Puede generar audio silencioso de varias maneras, como utilizando software de edición de audio como Audacity o Adobe Audition, o utilizando una herramienta de línea de comandos como FFmpeg.
`nls_config.disfluency_removal_enabled`	`boolean`	No	Indica si se deben filtrar las muletillas y pulir la salida. El valor predeterminado es `false`. Establézcalo en `true` para habilitar esta función.
`nls_config.intermediate_result_enabled`	`boolean`	No	Indica si se deben devolver resultados de transmisión intermedios. El valor predeterminado es `false`. Establézcalo en `true` para devolver resultados de transmisión intermedios.
`nls_config.vocabulary_id`	`string`	No	El ID de una lista de palabras clave precompilada.Genere este ID con antelación llamando a la API de creación de lista de palabras clave. Pase el ID durante el reconocimiento para usar las palabras clave de la lista.Adecuado para escenarios donde el vocabulario es conocido y relativamente estable, y donde necesita reutilizar la misma lista de palabras en distintas solicitudes.Para obtener detalles sobre el uso, consulte Palabras clave precompiladas.
`nls_config.instant_vocabulary`	`object`	No	Palabras clave instantáneas.Se pasan como pares clave-valor, donde la clave es el texto de la palabra clave (`string`) y el valor es el peso de la palabra clave (`integer`). No es necesario crear una lista de palabras clave con antelación. El peso oscila entre [1, 5] o se establece en 50: un valor en [1, 5] hace que el modelo tenga más probabilidades de generar la palabra a medida que aumenta el valor; un valor de 50 designa una súper palabra clave, lo que mejora enormemente la recuperación, pero el número de súper palabras clave no puede exceder 50.Adecuado para la optimización temporal de palabras clave a nivel de sesión.Cuando se configuran conjuntamente palabras clave instantáneas y precompiladas, el sistema fusiona ambos conjuntos. Si el conjunto fusionado contiene más de 2000 palabras clave, el sistema selecciona aleatoriamente 2000 para su uso. Para obtener información sobre el uso, los modelos compatibles y los límites, consulte Palabras clave instantáneas.
`nls_config.speech_noise_threshold`	`float`	No	El umbral para distinguir el habla del ruido, utilizado para ajustar la sensibilidad de la Detección de Actividad de Voz (VAD).Valores válidos: [-1.0, 1.0].Descripciones de valores: Cuanto más cerca esté el valor de -1: El umbral de ruido disminuye, por lo que es más probable que el ruido se reconozca como habla, lo que puede causar que se transcriba más ruido. Cuanto más cerca esté el valor de +1: El umbral de ruido aumenta, por lo que es más probable que el habla se juzgue erróneamente como ruido, lo que puede causar que se filtre parte del habla. Este es un parámetro de configuración avanzada. Ajustarlo puede afectar significativamente los resultados del reconocimiento. Recomendaciones: Pruebe y verifique exhaustivamente los resultados antes de ajustar. Ajuste en incrementos pequeños según el entorno de audio real (se recomienda un paso de 0.1).
`nls_config.enable_connection_fast_check`	`BOOL`	No	Si se deben habilitar comprobaciones rápidas de red para que las desconexiones se notifiquen lo antes posible. Valor predeterminado: `NO`.

API clave

NeoNui

nui_initialize

Inicializa la instancia del SDK de reconocimiento de voz. El SDK es un singleton. No lo inicialice nuevamente antes de llamar a nui_release. Firma del método

-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`parameters`	`char*`	Una cadena JSON que contiene parámetros de autenticación, conexión y depuración. Consulte Parámetros de conexión y control.
`level`	`NuiSdkLogLevel`	Nivel de impresión para los registros propios del SDK.
`save_log`	`BOOL`	Indica si se deben guardar los registros localmente. Si se establece en `YES`, especifique una ruta con `debug_path` en Parámetros de conexión y control y, opcionalmente, configure el tamaño del archivo con `max_log_file_size`.

Valor de retorno Devuelve un código de error. Consulte la Referencia de códigos de error.

nui_set_params

Establece los Parámetros de calidad de reconocimiento en formato JSON. Llame a este método antes de nui_dialog_start. Firma del método

-(NuiResultCode) nui_set_params:(const char *)params;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`params`	`char*`	Parámetros de calidad de reconocimiento.

Valor de retorno Devuelve un código de error. Consulte la Referencia de códigos de error.

nui_dialog_start

Inicia el reconocimiento. Firma del método

-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`vad_mode`	`NuiVadMode`	Modo VAD. Fijado en `MODE_P2T`.
`dialog_params`	`char*`	Si el parámetro `apikey` en Parámetros de conexión y control es una clave de API temporal, puede actualizarla aquí cuando caduque. También puede proporcionar contexto aquí para mejorar la precisión del reconocimiento mediante la mejora de contexto.El contenido está en formato JSON: `{ "apikey": "st-****", "input_context": [ { "role": "user", "content": [ { "text": "xxxxx", "type": "input_text" } ] } ] }`

Valor de retorno Devuelve un código de error. Consulte la Referencia de códigos de error.

nui_dialog_cancel

Finaliza el reconocimiento o cancela la interacción actual inmediatamente. Firma del método

-(NuiResultCode) nui_dialog_cancel:(BOOL)force;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`force`	`BOOL`	Si se debe finalizar forzosamente y descartar el resultado final. `YES`: Finaliza la tarea inmediatamente sin esperar a que el servidor devuelva el resultado final del reconocimiento. `NO`: Finaliza la tarea, pero espera a que se devuelva el resultado completo.

Valor de retorno Devuelve un código de error. Consulte la Referencia de códigos de error.

nui_dialog_action

Envía una acción de diálogo durante una interacción para actualizar el contexto de reconocimiento u otro comportamiento de tiempo de ejecución. Firma del método

-(NuiResultCode) nui_dialog_action:(const char *)action_params;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`action_params`	`char*`	Una cadena JSON utilizada para actualizar el contexto de reconocimiento u otro comportamiento de tiempo de ejecución.
`action_params.type`	`String`	Fijado en `"action"`.
`action_params.command`	`String`	Comando de tiempo de ejecución. Valores válidos: `context`: Actualiza la mejora de contexto inmediatamente para mejorar la precisión del reconocimiento. `play_start`: Cuando se utiliza AEC en el dispositivo, notifica al reproductor AEC interno que la reproducción de audio ha comenzado. `play_over`: Cuando se utiliza AEC en el dispositivo, notifica al reproductor AEC interno que la reproducción de audio ha terminado.
`action_params.context`	`String`	Cuando `command` es `"context"`, proporciona la mejora de contexto para actualizar inmediatamente. Ejemplo: `{ "context": [ { "role": "user", "content": [ { "text": "xxx", "type": "input_text" } ] } ] }`

Valor de retorno Devuelve un código de error. Consulte la Referencia de códigos de error.

nui_update_audio_data

Cuando audio_update_manually se establece en "true", los datos de grabación ya no se suministran a través de onNuiNeedAudioData. Utilice este método para enviarlos activamente en su lugar. Firma del método

-(NuiResultCode) nui_update_audio_data:(const char *)data
                                    Len:(int)length
                              FirstPack:(BOOL)first_pack;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`data`	`const char *`	Los datos de audio a enviar.
`length`	`int`	La longitud de los datos de audio, en bytes.
`first_pack`	`BOOL`	No necesita utilizar este parámetro.

Valor de retorno Devuelve un código de error. Consulte la Referencia de códigos de error.

nui_push_reference_data

Cuando audio_update_manually se establece en "true" y la cancelación de eco acústico (AEC) en el dispositivo está habilitada, utilice este método para enviar el audio reproducido por el reproductor como señal de referencia. Firma del método

-(NuiResultCode) nui_push_reference_data:(const char *)data
                                     Len:(int)length
                               FirstPack:(BOOL)first_pack;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`data`	`const char *`	Los datos de audio a enviar.
`length`	`int`	La longitud de los datos de audio, en bytes.
`first_pack`	`BOOL`	No necesita utilizar este parámetro.

Valor de retorno Devuelve un código de error. Consulte la Referencia de códigos de error.

nui_release

Libera todos los recursos internos del SDK y termina forzosamente todas las tareas en ejecución. Después de llamar a este método, la instancia del SDK deja de estar disponible. Para utilizarla de nuevo, debe llamar a nui_initialize para inicializarla nuevamente. Firma del método

-(NuiResultCode) nui_release;

Valor de retorno Devuelve un código de error. Consulte la Referencia de códigos de error.

nui_get_version

Obtiene la versión actual del SDK. Este método devuelve un valor solo después de llamar a nui_initialize. Firma del método

-(const char*) nui_get_version;

Valor de retorno La versión actual del SDK.

nui_get_all_response

Obtiene la información completa para la devolución de llamada del evento actual. Firma del método

-(const char*) nui_get_all_response;

Valor de retorno La información completa del evento como una cadena JSON.

NeoNuiSdkDelegate: listeners de devolución de llamada

onNuiEventCallback: escucha de eventos y resultados del reconocimiento de voz

Firma del método

-(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`nuiEvent`	NuiCallbackEvent	Evento de callback.
`dialog`	`long`	ID de sesión. No necesita utilizar este parámetro.
`wuw`	`char*`	Activación por voz. No necesita utilizar este parámetro.
`asr_result`	`char*`	Resultado del reconocimiento de voz.
`finish`	`BOOL`	Indica si la ronda de reconocimiento actual ha finalizado.
`code`	`int`	Código de error. Válido cuando ocurre el evento EVENT_ASR_ERROR. Consulte la Referencia de códigos de error.

onNuiAudioStateChanged: escucha del estado de audio

El SDK utiliza esta devolución de llamada para notificarle cuándo iniciar o detener la grabación. Firma del método

-(void) onNuiAudioStateChanged:(NuiAudioState)state;

Estados NuiAudioState

Parámetro	Descripción
`STATE_OPEN`	La interacción ha comenzado. Puede abrir el dispositivo de grabación e iniciar la grabación.
`STATE_PAUSE`	La interacción se ha detenido. Puede detener la grabación.
`STATE_CLOSE`	La instancia del SDK ha sido liberada. Puede cerrar el dispositivo de grabación por completo.

onNuiNeedAudioData: suministrar datos de audio para el reconocimiento

Después de que comienza el reconocimiento, esta devolución de llamada se activa continuamente. Suministre en ella los datos de audio que se van a reconocer. Firma del método

-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`audioData`	`char *`	Los datos de audio a suministrar.
`len`	`int`	El tamaño de los datos de audio suministrados, en bytes.

onNuiAssistEventCallback: recepción de datos e información auxiliar

Recibe eventos auxiliares y datos relacionados del SDK. Firma del método

-(void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
                            info:(char*)info
                         infoLen:(int)info_len
                          buffer:(char*)buffer
                             len:(int)len;

Descripciones de parámetros

Parámetro	Tipo	Descripción
`nuiEvent`	`NuiCallbackEvent`	El evento de callback.
`info`	`char *`	No necesita utilizar este parámetro.
`info_len`	`int`	No necesita utilizar este parámetro.
`buffer`	`char *`	Datos auxiliares, como datos de audio después del procesamiento AEC.
`len`	`int`	La longitud de los datos auxiliares, en bytes.

onNuiLogTrackCallback: escuchar registros de seguimiento

Esta devolución de llamada recibe los registros internos detallados del SDK para ayudarle a localizar y depurar problemas.

-(void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

NuiCallbackEvent: tipos de eventos

Evento	Descripción
EVENT_TRANSCRIBER_STARTED	La tarea se inició correctamente.
EVENT_VAD_START	Se activa justo después de que comienza la tarea. No significa que se haya detectado el inicio del habla.
EVENT_VAD_END	Se detectó el final del habla.
EVENT_ASR_PARTIAL_RESULT	Un resultado intermedio de reconocimiento de voz.
EVENT_ASR_ERROR	Ocurrió un error durante el reconocimiento de voz.
EVENT_MIC_ERROR	Activado porque no se recibieron datos de audio durante 2 segundos consecutivos.
EVENT_SENTENCE_END	Se detectó el final de una oración. Se devuelve un resultado de reconocimiento completo para la oración.
EVENT_TRANSCRIBER_COMPLETE	Reconocimiento de voz finalizado.
EVENT_AEC_DATA	Datos de audio después del procesamiento de cancelación de eco acústico (AEC).

​Inicio rápido

​Secuencia de llamadas

​Parámetros de solicitud

​Parámetros de conexión y control

​Parámetros de calidad de reconocimiento

​API clave

​NeoNui

​nui_initialize

​nui_set_params

​nui_dialog_start

​nui_dialog_cancel

​nui_dialog_action

​nui_update_audio_data

​nui_push_reference_data

​nui_release

​nui_get_version

​nui_get_all_response

​NeoNuiSdkDelegate: listeners de devolución de llamada

​onNuiEventCallback: escucha de eventos y resultados del reconocimiento de voz

​onNuiAudioStateChanged: escucha del estado de audio

​onNuiNeedAudioData: suministrar datos de audio para el reconocimiento

​onNuiAssistEventCallback: recepción de datos e información auxiliar

​onNuiLogTrackCallback: escuchar registros de seguimiento

​NuiCallbackEvent: tipos de eventos

Inicio rápido

Secuencia de llamadas

Parámetros de solicitud

Parámetros de conexión y control

Parámetros de calidad de reconocimiento

API clave

NeoNui

nui_initialize

nui_set_params

nui_dialog_start

nui_dialog_cancel

nui_dialog_action

nui_update_audio_data

nui_push_reference_data

nui_release

nui_get_version

nui_get_all_response

NeoNuiSdkDelegate: listeners de devolución de llamada

onNuiEventCallback: escucha de eventos y resultados del reconocimiento de voz

onNuiAudioStateChanged: escucha del estado de audio

onNuiNeedAudioData: suministrar datos de audio para el reconocimiento

onNuiAssistEventCallback: recepción de datos e información auxiliar

onNuiLogTrackCallback: escuchar registros de seguimiento

NuiCallbackEvent: tipos de eventos