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

Esta guía le muestra cómo utilizar el SDK de iOS para reconocimiento de voz no en tiempo real de Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR, para que pueda convertir audio en texto.

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

Inicio rápido

1. Obtener una clave de API:Obtener una clave de API

2. Descargue el SDK y ejecute el código de ejemplo:
   • Descargue el paquete más reciente del SDK.
   • Descomprima el paquete ZIP y agregue el nuisdk.framework 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 DashFunAsrFileTranscriberViewController.m. Reemplace la API Key para probar la función.

Pasos de llamada

Modo síncrono

1. Inicialice el SDK.
2. Configure los parámetros relevantes para su caso de uso.
3. Establezca async_request en false y llame a nui_file_trans_start para enviar una solicitud de reconocimiento de voz no en tiempo real y esperar el resultado.
4. En el callback onFileTransEventCallback, escuche el evento EVENT_FILE_TRANS_RESULT para obtener el resultado final del reconocimiento.
5. Llame a nui_release para liberar los recursos del SDK.

Modo asíncrono

1. Inicialice el SDK.
2. Configure los parámetros relevantes para su caso de uso.
3. Establezca async_request en true y llame a nui_file_trans_start para enviar una solicitud de reconocimiento de voz no en tiempo real.
4. Llame a nui_file_trans_query para consultar activamente el progreso o el resultado del reconocimiento.
5. En el callback onFileTransEventCallback, escuche el evento EVENT_FILE_TRANS_QUERY_RESULT para obtener el resultado actual de la consulta.
6. En el callback onFileTransEventCallback, escuche el evento EVENT_FILE_TRANS_RESULT para obtener el resultado final del reconocimiento.
7. 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 interfaz nui_initialize.

• Parámetros de ejemplo: La siguiente es una cadena JSON de muestra. No se listan todos los parámetros. Agregue los que necesite cuando escriba su código:

{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

• Descripciones de parámetros

  Parámetro	Tipo	Obligatorio	Descripción
  url	String	Sí	Puntos de conexión del servicio: wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription China (Pekín): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription Singapur: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
  apikey	String	Sí	La clave de API.
  service_mode	String	Sí	El modo de ejecución. Fijado en "1" para reconocimiento de voz no en tiempo real.
  device_id	String	Sí	Una cadena única que identifica al usuario final. Configúrela como un ID de usuario dentro de la aplicación o un identificador de dispositivo 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 de almacenamiento para el archivo de registro. Este parámetro surte efecto solo cuando save_log se establece en YES al llamar a la interfaz nui_initialize. En ese caso, debe establecer la ruta del archivo de registro; de lo contrario, se devuelve un error. Se mantienen un máximo de 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 surte efecto solo cuando save_log se establece en YES al llamar a la interfaz nui_initialize. Valor predeterminado: 104857600 (100 * 1024 * 1024 bytes, es decir, 100 MiB).
  log_track_level	int	No	Controla el nivel de filtro del contenido de registro enviado 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 (establecidos a través de la interfaz nui_initialize) determinan conjuntamente qué registros se envían finalmente al callback. El valor de nivel de un registro debe ser mayor o igual tanto a log_track_level como a level antes de ser enviado al callback. Por ejemplo, si log_track_level se establece en 2 (INFO) y level se establece en 3 (WARNING), solo los registros de WARNING o superior (valor >= 3) se envían al callback.

Parámetros de efecto de reconocimiento de voz

Configure todos los parámetros de reconocimiento de voz a través de la interfaz nui_file_trans_start.

• Parámetros de ejemplo: La siguiente es una cadena JSON de muestra. No se listan todos los parámetros. Agregue los que necesite cuando escriba su código:

{
    "apikey": "st-****",
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}

• Descripciones de parámetros

  Parámetro	Tipo	Obligatorio	Descripción
  file_urls	array[string]	Sí	Una lista de URL de los archivos de audio o video a transcribir. Se admiten HTTP y HTTPS. Una sola solicitud admite únicamente una URL. Para los requisitos de entrada, como formatos de audio compatibles, límites de tamaño de archivo y límites de duración, consulte Especificaciones de audio. Si la grabación se almacena en Alibaba Cloud OSS, la API RESTful admite URLs temporales con el prefijo oss://, mientras que el SDK no admite URLs temporales con el prefijo oss://. Importante Una URL temporal es válida durante 48 horas y no se puede usar después de que expire. No la use en producción. La interfaz de credenciales de carga tiene un límite de tasa de 100 QPS y no se puede escalar. No la use en escenarios de producción, alta concurrencia o pruebas de carga. Para producción, utilice almacenamiento estable como Alibaba Cloud OSS para mantener los archivos disponibles a largo plazo y evitar límites de tasa. Si una URL de archivo de audio configurada como una URL pública temporal de OSS no es accesible, configure X-DashScope-OssResourceResolve en enable en el encabezado de la solicitud (no recomendado). El SDK no admite la configuración de encabezados de solicitud.
  async_request	boolean	No	Indica si la solicitud de reconocimiento de voz es asíncrona. Valor predeterminado: false. Valores válidos: true: solicitud asíncrona false: solicitud síncrona
  apikey	string	No	Si la apikey en Parámetros de conexión y control es una clave de API temporal, puede actualizarla aquí para evitar que caduque.
  nls_config	object	Sí	El objeto de configuración principal de reconocimiento de voz. Contiene parámetros clave como la selección del modelo y los controles de efecto de reconocimiento.
  nls_config.model	string	Sí	El modelo utilizado en el ejemplo. Para información sobre modelos, consulte Modelos y regiones admitidos.
  nls_config.special_word_filter	object	No	Las palabras sensibles a procesar durante el reconocimiento de voz. Puede establecer un método de manejo diferente para cada palabra sensible. Para más detalles, consulte Filtrado de palabras sensibles.
  nls_config.channel_id	array[integer]	No	El índice de las pistas de audio a reconocer en un archivo de audio multipista. El índice comienza en 0. Por ejemplo, [0] reconoce la primera pista, y [0, 1] reconoce la primera y la segunda pista simultáneamente. Si omite este parámetro, solo se procesa la primera pista. ImportanteCada pista especificada se factura de forma independiente. Por ejemplo, solicitar [0, 1] para un solo archivo incurre en dos cargos separados. Valor predeterminado: [0].
  nls_config.diarization_enabled	boolean	No	Si se debe habilitar la diarización de hablantes. Deshabilitado de forma predeterminada. Se aplica solo a audio monoaural. El audio multicanal no admite la diarización de hablantes. Cuando está habilitado, el resultado del reconocimiento incluye un campo speaker_id que distingue a los diferentes hablantes. NotaCuando la diarización de hablantes está habilitada, mantenga la duración del audio dentro de 2 horas. De lo contrario, el reconocimiento puede fallar o agotar el tiempo de espera. Valor predeterminado: false. Para ver un ejemplo de speaker_id, consulte Descripción del resultado de reconocimiento.
  nls_config.speaker_count	integer	No	ImportanteSurte efecto solo cuando la diarización de hablantes está habilitada (diarization_enabled está configurado en true). Un valor de referencia para el número de hablantes. El rango válido es un entero de 2 a 100 (inclusive). De forma predeterminada, el número de hablantes se detecta automáticamente. Si configura este valor, solo guía al algoritmo para generar el recuento especificado cuando sea posible y no garantiza ese recuento exacto. Sin valor predeterminado.
  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.input_context	array	No	Una lista de mensajes que contienen contexto de conversación opcional para mejorar la precisión del reconocimiento. ImportanteEl contexto ayuda a mejorar el reconocimiento de términos específicos del dominio. Para su uso, consulte Mejora de contexto. Puede incluir hasta 5 mensajes de cada tipo de contexto: input_text y text. Si se supera este límite, solo se conservan los 5 mensajes más recientes de cada tipo. La longitud combinada de los campos text en los mensajes de user y assistant en cada turno no debe exceder los 400 caracteres. Cada carácter cuenta como 1. El texto excedente se trunca desde el final. ImportanteCuando incluya contexto, organice messages por turno de conversación. En cada turno, el mensaje de user (tipo input_text) debe preceder al mensaje correspondiente de assistant (tipo text). El mensaje de user que contiene input_audio debe ser el último mensaje en el arreglo messages. [ { "role": "user", "content": [ { "type": "input_text", "text": "你好啊，我是通义千问，有什么可以帮助你的？" } ] } ]
  nls_config.instant_vocabulary	object	No	Palabras clave instantáneas, pasadas como pares clave-valor. Cada clave es el texto de la palabra clave (string) y cada valor es su peso (integer). No se requiere una lista de palabras clave precompilada. Utilice este parámetro para palabras clave temporales a nivel de sesión. Los pesos válidos son números enteros de 1 a 5, o 50. Un peso mayor de 1 a 5 aumenta la probabilidad de que el modelo genere la palabra clave. Un peso de 50 define una súper palabra clave y mejora significativamente la recuperación. Puede especificar hasta 50 súper palabras clave. Si también configura palabras clave precompiladas, ambos conjuntos se fusionan. Si el conjunto fusionado supera las 2000 palabras clave, se seleccionan 2000 al azar. Para su 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 a reconocer. Si no puede determinar el idioma con antelación, déjelo sin configurar y el modelo detectará el idioma automáticamente. Para los modelos Qwen-Audio-3.x-ASR-Flash-Filetrans, puede configurar hasta 4 valores; cualquier valor más allá de los primeros 4 se ignora. Para los modelos Fun-ASR, solo puede configurar 1 valor; si configura varios, solo el primero surte efecto. Haga clic para ver los códigos de idioma admitidos Qwen-Audio-3.x-ASR-Flash-Filetrans, fun-asr: 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

Interfaces 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 los parámetros de autenticación, conexión y depuración. Consulte Parámetros de conexión y control.
  level	NuiSdkLogLevel	Controla el nivel de impresión de los propios registros del SDK.
  save_log	BOOL	Indica si se guardan los registros localmente. Si se establece en YES, debe especificar una ruta a través de debug_path en Parámetros de conexión y control, y puede establecer el tamaño del archivo a través de max_log_file_size.

• Valor de retorno

nui_set_params

Utilice esta interfaz para establecer o actualizar el parámetro nls_config de forma independiente. Si proporciona todos los parámetros a la vez en nui_file_trans_start, no necesita llamar a este método.

• Firma del método

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

• Descripciones de parámetros

  Parámetro	Tipo	Descripción
  params	char*	El parámetro nls_config en Parámetros de efecto de reconocimiento de voz. Los parámetros distintos de nls_config no se pueden configurar mediante este método. Ejemplo: { "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }

• Valor de retorno

nui_file_trans_start

Inicia el reconocimiento.

• Firma del método

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

• Descripciones de parámetros

  Parámetro	Tipo	Descripción
  params	char*	Parámetros de efecto de reconocimiento de voz. Ejemplo: { "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }
  task_id	char*	El ID de la tarea. El SDK genera una cadena aleatoria internamente y devuelve el task_id cuando esta interfaz se llama exitosamente.

• Valor de retorno

nui_file_trans_query

Utilice esta interfaz para consultar activamente 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 en el callback onFileTransEventCallback.

• Firma del método

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

• Descripciones de parámetros

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

• Valor de retorno

nui_file_trans_cancel

Cancela la tarea actual inmediatamente.

• Firma del método

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

• Descripciones de parámetros

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

• Valor de retorno

nui_release

Libera todos los recursos internos del SDK y termina forzosamente todas las tareas en curso. Después de llamar a este método, la instancia del SDK deja de estar disponible. Para usarla nuevamente, debe llamar a nui_initialize otra vez para inicializarla.

• Firma del método

-(NuiResultCode) nui_release;

• Valor de retorno

nui_get_version

Obtiene la información de la versión actual del SDK.

• Firma del método

-(const char*) nui_get_version;

• Valor de retorno

  La información de la versión actual del SDK.

NeoNuiSdkDelegate: callbacks de monitoreo

onFileTransEventCallback: monitorear eventos y resultados de reconocimiento de voz

• Firma del método

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

• Descripciones de 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	Indica si ha finalizado esta ronda de reconocimiento.
  code	int	Válido solo cuando ocurre el evento EVENT_ASR_ERROR.

onFileTransLogTrackCallback: monitorear registros de seguimiento

Utilice este callback para recibir registros internos detallados del SDK para la 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 al servicio exitosamente.
EVENT_FILE_TRANS_UPLOADED	El archivo de audio a reconocer se cargó correctamente. Ahora puede obtener el task_id de la tarea actual.
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.