iOS SDK de reconocimiento de voz no en tiempo real (Qwen-Audio-ASR)

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
Descargue el SDK y ejecute el código de ejemplo:
- Descargue el paquete más reciente del SDK.
- Extraiga el archivo ZIP y agregue nuisdk.framework al proyecto.
- Agregue nuisdk.xcframework en Build Phases → Link Binary With Libraries.
- 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 DashFunAsrFlashFileTranscriberViewController.m. 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 nui_file_trans_start para enviar una solicitud de reconocimiento de voz no en tiempo real.
Utilice onFileTransEventCallback para escuchar el evento EVENT_FILE_TRANS_RESULT y obtener el resultado final del reconocimiento
Llame a nui_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 nui_initialize 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://dashscope.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í	Endpoints de servicio: `wss://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` China (Pekín): `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` Singapur: `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` Reemplace `{WorkspaceId}` con su ID de espacio de trabajo.
`apikey`	`String`	Sí	Clave de API.
`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 surte efecto cuando llama a `nui_initialize` con `save_log` establecido en `YES`. 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`	`int`	No	El tamaño máximo del archivo de registro en bytes. Este parámetro solo surte efecto cuando llama a `nui_initialize` con `save_log` establecido en `YES`. Valor predeterminado: 104857600 (100 * 1024 * 1024 bytes, o 100 MiB).
`log_track_level`	`int`	No	El nivel de filtrado para los registros enviados a través del callback de registro (`onFileTransLogTrackCallback`). 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). `log_track_level` y `level` (configurados a través del método `nui_initialize`) determinan conjuntamente qué registros se entregan. El nivel numérico de un registro debe ser mayor o igual tanto a `log_track_level` como a `level` para que el registro se entregue. Por ejemplo, si `log_track_level` se establece en 2 (INFO) y `level` se establece en 3 (WARNING), solo se entregan los registros de WARNING y de mayor severidad (nivel numérico >= 3).

Parámetros de reconocimiento

Utilice nui_file_trans_start 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 nombre del modelo.
`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. `{ "张三": 5, "李四": 5 }`
`nls_config.language_hints`	`array[string]`	No	Los códigos de idioma que se reconocerán. Si desconoce el idioma, omita este parámetro para que el modelo lo detecte automáticamente. Puede especificar hasta 4 valores. Si especifica más, solo los primeros 4 tendrán efecto.Especificar los códigos de idioma puede mejorar la precisión del reconocimiento. 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 `qwen-audio-3.1-asr-flash` también admite los siguientes códigos de idioma: tr: turco fa: persa mr: maratí ml: malabar ne: nepalí ky: kirguís az: azerbaiyano ka: georgiano hy: armenio sl: esloveno sq: albanés et: estonio lv: letón lt: lituano ca: catalán eu: euskera gl: gallego or: oriya dv: divehi as: asamés ku: kurdo tig: tigré fy: frisón occidental ba: baskir be: bielorruso tt: tártaro ia: interlingua mhr: marí oriental tok: toki pona
`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:

El contexto mejora la precisión del reconocimiento de términos especializados. Para instrucciones de uso, consulte Mejora de contexto.Los mensajes de contexto (tipos input_text y text) están limitados a cinco cada uno. Si se excede 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 400 caracteres. Cada carácter cuenta como uno. Los caracteres excedentes se truncan desde el final.

Cuando 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 correspondiente assistant (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
`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. Data URI Base64: Pase audio codificado en Base64 como un Data URI. 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	Requerido 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 400 caracteres. Los caracteres excedentes se truncan desde el final.

Interfaces clave

NeoNui

nui_initialize

Inicialice la instancia del SDK de reconocimiento de voz. El SDK utiliza 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;

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`	El nivel de registros impresos por el SDK.
`save_log`	`BOOL`	Indica si se deben guardar los registros localmente. Si se establece en `YES`, 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.

nui_set_params

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

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

Parámetros

Parámetro Tipo Descripción

Parámetro	Tipo	Descripción
`params`	`char*`	Parámetros de reconocimiento en `nls_config` y parámetros de messages.Ejemplo: `{ "messages": [ { "content": [ { "input_audio": { "data": "{YOUR_AUDIO_URL}" }, "type": "input_audio" } ], "role": "user" } ], "nls_config": { "format": "mp3", "model": "qwen-audio-3.0-asr-flash" } }`

params

char*

Parámetros de reconocimiento en nls_config y parámetros de messages.Ejemplo:

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

nui_file_trans_start

Iniciar el reconocimiento. Firma del método

- (NuiResultCode) nui_file_trans_start:(const char *)params
                             taskId:(char *)task_id;

Parámetros

Parámetro Tipo Descripción

Parámetro	Tipo	Descripción
`params`	`char*`	Parámetros de reconocimiento. Ejemplo: `{ "messages": [ { "role": "user", "content": [ { "type": "input_audio", "input_audio": { "data": "{YOUR_AUDIO_URL}" } } ] } ], "nls_config": { "format": "mp3", "model": "qwen-audio-3.0-asr-flash" } }`
`task_id`	`char*`	Puede ignorar este parámetro y pasar null.

params

char*

Parámetros de reconocimiento. Ejemplo:

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

task_id char* Puede ignorar este parámetro y pasar null.

nui_file_trans_query

Esta función de reconocimiento de voz no en tiempo real solo admite solicitudes síncronas. Puede ignorar este método. Firma del método

- (NuiResultCode) nui_file_trans_query:(const char *)task_id;

Parámetros

Parámetro	Tipo	Descripción
`task_id`	`char*`	El ID de la tarea a consultar, obtenido de EVENT_FILE_TRANS_UPLOADED.

nui_file_trans_cancel

Cancelar inmediatamente la tarea actual. Firma del método

- (NuiResultCode) nui_file_trans_cancel:(const char *)task_id;

Parámetros

Parámetro	Tipo	Descripción
`task_id`	`char*`	El ID de la tarea a cancelar, obtenido de EVENT_FILE_TRANS_UPLOADED.

nui_release

Libere todos los recursos internos del SDK y detenga forzosamente todas las tareas en curso. Después de esta llamada, la instancia del SDK deja de estar disponible. Para usarla nuevamente, llame a nui_initialize para inicializarla otra vez. Firma del método

- (NuiResultCode) nui_release;

nui_get_version

Obtener la versión actual del SDK. Firma del método

- (const char*) nui_get_version;

Valor de retorno La versión actual del SDK.

NeoNuiSdkDelegate: Callbacks

onFileTransEventCallback: Escuchar eventos y resultados de reconocimiento

Firma del método

- (void) onFileTransEventCallback:(NuiCallbackEvent)nuiEvent
                       asrResult:(const char *)asr_result
                          taskId:(const char *)task_id
                        ifFinish:(BOOL)finish
                         retCode:(int)code;

Parámetros

Parámetro	Tipo	Descripción
`nuiEvent`	`NuiCallbackEvent`	El evento de devolución de llamada.
`asr_result`	`char*`	El resultado del reconocimiento de voz.
`task_id`	`char*`	El ID de la tarea.
`finish`	`BOOL`	Si el reconocimiento para este turno ha finalizado.
`code`	`int`	Válido solo cuando ocurre el evento `EVENT_ASR_ERROR`.

onFileTransLogTrackCallback: Escuchar registros de rastreo

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

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

NuiCallbackEvent: Tipos de eventos

Evento	Descripción
`EVENT_FILE_TRANS_CONNECTED`	Conectado correctamente al servicio.
`EVENT_FILE_TRANS_UPLOADED`	El archivo de audio se cargó correctamente. Puede obtener el task_id actual en este punto.
`EVENT_FILE_TRANS_RESULT`	El resultado final del reconocimiento.
`EVENT_ASR_ERROR`	Ocurrió un error durante el reconocimiento de voz.

​Inicio rápido

​Procedimiento de llamada

​Modo síncrono

​Parámetros de solicitud

​Parámetros de conexión y control

​Parámetros de reconocimiento

​Interfaces clave

​NeoNui

​nui_initialize

​nui_set_params

​nui_file_trans_start

​nui_file_trans_query

​nui_file_trans_cancel

​nui_release

​nui_get_version

​NeoNuiSdkDelegate: Callbacks

​onFileTransEventCallback: Escuchar eventos y resultados de reconocimiento

​onFileTransLogTrackCallback: Escuchar registros de rastreo

​NuiCallbackEvent: Tipos de eventos

Inicio rápido

Procedimiento de llamada

Modo síncrono

Parámetros de solicitud

Parámetros de conexión y control

Parámetros de reconocimiento

Interfaces clave

NeoNui

nui_initialize

nui_set_params

nui_file_trans_start

nui_file_trans_query

nui_file_trans_cancel

nui_release

nui_get_version

NeoNuiSdkDelegate: Callbacks

onFileTransEventCallback: Escuchar eventos y resultados de reconocimiento

onFileTransLogTrackCallback: Escuchar registros de rastreo

NuiCallbackEvent: Tipos de eventos