Skip to main content

SDK de iOS de Qwen-Audio-Realtime

Use el SDK de iOS de Qwen-Audio-Realtime para conversaciones de voz en tiempo real, con entrada de audio en tiempo real y salida de voz o texto.

Para la conexión y la autenticación, consulte Conexión mediante WebSocket. Para consultar los campos de eventos y los ejemplos JSON, consulte Eventos del cliente y Eventos del servidor. Guía del usuario: Para introducciones a los modelos y consejos de selección, consulte Conversación de voz en tiempo real.

Inicio rápido

  1. Obtenga una clave API: Obtenga y configure una clave API.
  2. Descargue el SDK y ejecute el código de ejemplo:
    • Descargue el paquete más reciente del SDK.
    • Extraiga el paquete ZIP y agregue nuisdk.xcframework 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 en Xcode. El código de ejemplo se encuentra en DashQwenAudioChatViewController.m. Reemplace la clave API para probar la función.

Procedimiento de llamada

  1. Inicialice el SDK.
  2. Configure los parámetros para su caso de uso. Utilice el argumento parameters de nui_initialize para establecer los parámetros de conexión y control, y utilice nui_set_params para establecer los parámetros de conversación de voz.
  3. Llame a nui_dialog_start para iniciar la conversación.
  4. En onNuiAudioStateChanged, inicie el dispositivo de grabación según el estado del audio.
  5. Suministre datos de grabación continuamente en onNuiNeedAudioData, o llame a nui_update_audio_data para enviar activamente los datos de grabación.
  6. Reciba continuamente el audio devuelto por el modelo en onNuiAssistEventCallback.
  7. Escuche los eventos y obtenga la información de los mismos en onNuiEventCallback.
  8. Llame a nui_dialog_cancel para detener la conversación y escuche EVENT_TRANSCRIBER_COMPLETE para confirmar que ha finalizado.
  9. Cuando la función de conversación ya no sea necesaria, 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 en el argumento parameters de nui_initialize. Ejemplo: La siguiente cadena JSON no enumera todos los parámetros. Agregue los parámetros según sea necesario para su caso de uso. El ejemplo usa qwen-audio-3.1-realtime-plus. Para usar otro modelo, actualice tanto model en la URL como nls_config.model en Parámetros de conversación de voz.
{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=qwen-audio-3.1-realtime-plus",
  "apikey": "st-****",
  "device_id": "my_device_id",
  "service_mode": "1"
}
Parámetros
ParámetroTipoObligatorioDescripción
urlStringSíEndpoint del servicio:
  • wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • China (Pekín): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Singapur: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Reemplace {WorkspaceId} con su ID de espacio de trabajo.
apikeyStringSíClave de API.
service_modeStringSíModo de ejecución. Establezca este parámetro en "1" para conversaciones de voz en tiempo real.
device_idStringSíUna cadena única que identifica al usuario final. Puede utilizar 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 solución de problemas.
audio_update_manuallyStringNoIndica si se deben enviar activamente datos de audio. Valor predeterminado: "false". Si se establece en "true" y el SDK admite capacidades de audio en el dispositivo, como AEC y VAD, dichas capacidades se habilitan de forma predeterminada.
workspaceStringNoLa ruta de almacenamiento para los archivos de recursos en el dispositivo. Este parámetro es obligatorio cuando audio_update_manually es "true" y está habilitada una capacidad de audio en el dispositivo, como AEC o VAD.
debug_pathStringNoLa ruta de almacenamiento del archivo de registro. Este parámetro solo surte efecto cuando save_log es true en nui_initialize. En este caso, la ruta es obligatoria. El SDK conserva como máximo dos archivos de registro localmente.
save_wavStringNoIndica si se debe guardar el audio de depuración en debug_path. Valor predeterminado: "false". Los valores válidos son "true" y "false". Este parámetro solo surte efecto cuando save_log es true, y debug_path también debe estar definido.
max_log_file_sizeintNoEl tamaño máximo del archivo de registro en bytes. Este parámetro solo surte efecto cuando save_log es true. Predeterminado: 104857600 (100 × 1024 × 1024 bytes, o 100 MiB).
log_track_levelintNoEl nivel de filtro para los registros enviados a través de onNuiLogTrackCallback. Valor predeterminado: 2. Valores válidos: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR) y 5 (NONE). Un registro se devuelve solo cuando su nivel es mayor o igual tanto a log_track_level como al level pasado a nui_initialize. Por ejemplo, si log_track_level es 2 (INFO) y level es 3 (WARNING), solo se devuelven registros de nivel WARNING y superior (valores mayores o iguales a 3).

Parámetros de conversación de voz

Pase una cadena JSON en el argumento params de nui_set_params. Ejemplo: La siguiente cadena JSON no enumera todos los parámetros. Agregue los parámetros según sea necesario para su caso de uso.
{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}
Parámetros
Parámetro de nivel superiorTipoObligatorioDescripción
service_typeintSíTipo de servicio de voz. Establezca este parámetro en 4 para conversaciones de voz en tiempo real.
nls_configobjectSíConfiguración principal de la conversación de voz, incluida la selección del modelo y el comportamiento de la conversación.
nls_config.modelstringSíNombre del modelo. Admite las series de modelos qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus y qwen-audio-3.0-realtime-flash.
nls_config.sr_formatstringSíFormato de audio de entrada. Solo se admite pcm. El formato predeterminado es PCM monoaural de 16 kHz y 16 bits.
nls_config.modalitiesstringNoUna cadena que contiene una matriz de modalidades de salida. Valores válidos:
  • ["text"]: devuelve solo texto.
  • ["audio", "text"] (predeterminado): devuelve tanto audio como texto.
nls_config.voicestringNoVoz TTS. El valor predeterminado es longanqian_v3.1 para 3.1 Plus y longanqian para 3.0 Plus/Flash. Este parámetro solo se puede establecer en la primera session.update; los valores posteriores se ignoran. Voces del sistema: longanqian, longanlingxin, longanlingxi, longanxiaoxin y longanlufeng. También puede especificar un voice_id clonado creado a través de la API de clonación de voz. Consulte Configuración de voz.3.1 Plus también admite longanqian_v3.1, longanhuan_v3.1, longanlingxin_v3.1, longanfengyue_v3.1, xunanchuan_v3.1, beth_v3.1, betty_v3.1 y cally_v3.1.
nls_config.enable_speech_emotionBOOLNoIndica si se debe habilitar la expresión emocional mejorada. Cuando está habilitada, la voz de respuesta presenta una variación emocional más notable. Valor predeterminado: YES. Valores válidos: YES y NO.
nls_config.instructionsstringNoInstrucciones del sistema que definen el rol del modelo, el estilo de respuesta y las preferencias de comportamiento para toda la sesión.
nls_config.max_history_turnsintNoNúmero máximo de turnos históricos de preguntas y respuestas permitidos en una solicitud. Valores válidos: de 1 a 50. Predeterminado: 20.
nls_config.toolsstringNoUna cadena que contiene una matriz de definiciones de herramientas de Function Calling. Después de configurar este parámetro, el modelo decide si llamar a una herramienta basándose en la entrada del usuario. Cada definición utiliza type (obligatorio y fijado en function) y un objeto function que contiene name (obligatorio), description (opcional) y parameters (opcional). Si una función no tiene argumentos, omita parameters.
Ejemplo:
[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Queries weather information for a specified city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  }
]
nls_config.turn_detectionstringNoUna cadena que contiene un objeto JSON para la detección de turnos. Si se omite, la sesión utiliza el modo pulsar para hablar, en el cual el audio se confirma y la inferencia se activa manualmente. Si se establece, se habilita el modo de conversación dúplex.
nls_config.turn_detection.typestringNoTipo de VAD. server_vad (predeterminado) detecta los límites del habla a partir de características acústicas y activa automáticamente la inferencia. smart_turn combina señales acústicas y semánticas; los sonidos sin contenido semántico, como las muletillas, no inician un turno ni interrumpen la reproducción del modelo.
nls_config.turn_detection.thresholdfloatNoSensibilidad de VAD. Este parámetro solo se aplica a server_vad y no tiene efecto en smart_turn. Los valores más bajos hacen que el VAD sea más sensible a sonidos tenues y ruido de fondo; los valores más altos requieren un habla más clara y fuerte. Rango válido: [-1.0, 1.0]. Valor predeterminado: 0.5.
nls_config.turn_detection.silence_duration_msintNoDuración mínima de silencio después del habla, en milisegundos, antes de que se active la respuesta del modelo. Este parámetro solo se aplica a server_vad y no tiene efecto en smart_turn. Los valores más bajos reducen la latencia, pero pueden activarse con pausas breves. Rango válido: [200, 6000]. Valor predeterminado: 800. Recomendado para conversación: de 400 a 800.
nls_config.turn_detection.voiceprint_audio_urlsstringNoUna cadena que contiene una matriz de URL de audio pregrabado de acceso público para el hablante objetivo. Este parámetro solo se aplica a smart_turn. En conversaciones dúplex, ayuda al modelo a centrarse en el hablante objetivo e ignorar a otros hablantes y el ruido de fondo. Se admiten hasta cinco URL. El audio debe ser PCM o WAV de 16 kHz.

API clave

NeoNui

nui_initialize

Inicializa la instancia del SDK de conversación de voz. El SDK es un singleton. No lo inicialice de nuevo 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 propios registros del SDK.

save_log

BOOL

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.

nui_set_params

Establece los Parámetros de conversación de voz 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 conversación de voz.

nui_dialog_start

Inicia la conversación. Firma del método
-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;
Parámetros
ParámetroTipoDescripción
vad_modeNuiVadModeModo VAD. Fijo en MODE_P2T.
dialog_paramschar*Si apikey en los parámetros de conexión y control es una clave API temporal, actualícela aquí después de que caduque.
Formato JSON:
{
  "apikey": "st-****"
}

nui_dialog_cancel

Finaliza la conversación o cancela inmediatamente la interacción actual. 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 de la conversación.

  • NO: Finaliza la tarea, pero espera a que se devuelva el resultado completo.

nui_dialog_action

Envía un comando de acción de conversación durante una interacción para actualizar el comportamiento en tiempo de ejecución, como el contexto de la conversación. Firma del método
- (NuiResultCode) nui_dialog_action:(const char *)params;
Parámetros
ParámetroTipoDescripción
paramschar*Una cadena JSON utilizada para actualizar el comportamiento en tiempo de ejecución, como el contexto de la conversación.
params.typeStringEstablecido en "action".
params.commandStringComando de tiempo de ejecución. Valores válidos:
  • function_call: actualiza una solicitud de llamada de función.
  • play_start: cuando se utiliza AEC en el dispositivo, notifica al SDK que la reproducción de audio ha comenzado.
  • play_over: cuando se utiliza AEC en el dispositivo, notifica al SDK que la reproducción de audio ha terminado.
params.contextStringActualización de solicitud de llamada de función. Se usa cuando command es "function_call".
params.context.typeStringTipo de evento. Este parámetro es obligatorio cuando command es "function_call". conversation.item.create inserta un elemento de conversación para contexto histórico, texto complementario o resultado de una herramienta. Después de enviar conversation.item.create, utilice response.create para activar otra inferencia.
params.context.itemobjectRequerido cuando params.context.type es conversation.item.create. El elemento de conversación a crear.
params.context.responseobjectOpcional cuando params.context.type es response.create. Anula los valores predeterminados de la sesión para esta inferencia. Si se omite, se utiliza la configuración actual de la sesión.
Parámetros de context.item:
ParámetroTipoDescripción
idStringID de elemento de conversación único opcional. Si se omite, el servidor genera uno. Se devuelve un error si el ID especificado ya existe.
typeStringTipo de elemento obligatorio. Valores válidos:
  • message: un mensaje normal.
  • function_call: una solicitud de llamada de función. Este tipo suele ser generado por el servidor. El cliente también puede utilizarlo para agregar contexto histórico.
  • function_call_output: resultado de ejecución de una herramienta. Después de recibir un function_call, el cliente ejecuta la herramienta y utiliza este tipo para devolver el resultado.
roleStringRequerido para message. Valores válidos: system, user y assistant.
contentarrayObligatorio para message. Cada elemento contiene un type y el campo de datos asociado. system admite input_text con text; user admite input_text con text y input_audio con audio codificado en Base64; assistant admite output_text con text.
call_idStringRequerido para function_call y function_call_output. El ID único que asocia una solicitud de llamada de función con su resultado.
nameStringRequerido para function_call. El nombre de la función a llamar.
argumentsStringRequerido para function_call. Argumentos de la función como una cadena JSON.
outputStringRequerido para function_call_output. Resultado de ejecución de la herramienta como una cadena JSON.
Parámetros de context.response:
ParámetroTipoDescripción
modalitiesarrayModalidades de salida. ["text"] devuelve solo texto. ["audio", "text"] (predeterminado) devuelve tanto audio como texto.
voicestringAnula la voz TTS para esta inferencia.
Ejemplo:
{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"Hangzhou\",\"condition\":\"sunny\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": ["text", "audio"]
    },
    "type": "response.create"
  }
}

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.

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.

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;

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 información de eventos

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

Si la ronda de reconocimiento actual ha finalizado.

code

int

Válido solo cuando ocurre el evento EVENT_ASR_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: suministro de datos de audio

Después de que comienza la conversación, esta devolución de llamada se activa continuamente. Proporcione los datos de audio en esta devolución de llamada. No necesita utilizar esta devolución de llamada cuando audio_update_manually está establecido en "true". 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 devolución de llamada.

info

char *

No necesita utilizar este parámetro.

info_len

int

No necesita utilizar este parámetro.

buffer

char *

Datos auxiliares, como el audio TTS devuelto por el modelo.

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

EventoDescripción
EVENT_TRANSCRIBER_STARTEDLa tarea se inició correctamente.
EVENT_VAD_STARTSe activa inmediatamente después de que comienza la tarea. Esto no significa que se haya detectado el inicio del habla.
EVENT_VAD_ENDSe detectó el final del habla.
EVENT_ASR_PARTIAL_RESULTUn resultado intermedio del reconocimiento de voz.
EVENT_ASR_ERROROcurrió un error durante la conversación de voz.
EVENT_MIC_ERRORSe activa cuando no se reciben datos de audio durante dos segundos consecutivos.
EVENT_SENTENCE_ENDSe detectó el final de una oración y se devolvió un resultado de reconocimiento completo.
EVENT_TRANSCRIBER_COMPLETELa conversación de voz finalizó.
EVENT_AUDIO_TRANSCRIPTIONUn evento de transcripción de texto incremental para la salida de audio. Los segmentos de transcripción se devuelven en modo streaming.
EVENT_AUDIO_TRANSCRIPTION_COMPLETEDLa transcripción de la salida de audio está completa.
EVENT_OTHER_RESULTOtra información de eventos, como un resultado de Function Calling.
EVENT_ASR_TTS_STARTEl modelo comenzó a devolver audio TTS.
EVENT_ASR_TTS_DATAAudio TTS devuelto por el modelo.
EVENT_ASR_TTS_COMPLETEEl modelo terminó de devolver audio TTS.
EVENT_AEC_DATADatos de audio procesados por AEC.