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

El SDK de iOS para reconocimiento de voz no en tiempo real de Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash convierte el habla 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
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). Nota: `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 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 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.

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

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