Skip to main content

SDK iOS do Qwen-Audio-Realtime

Use o SDK iOS do Qwen-Audio-Realtime para entrada de áudio em tempo real e saída de voz ou texto em conversas por voz em tempo real.

Para a conexão e a autenticação, consulte Acesso por WebSocket. Para os campos de eventos e exemplos JSON, consulte Eventos do cliente e Eventos do servidor. Guia do usuário: Para apresentações de modelos e conselhos de seleção, consulte Conversa por voz em tempo real.

Início rápido

  1. Obter uma chave de API: Obter e configurar uma chave de API.
  2. Baixe o SDK e execute o código de exemplo:
    • Baixe o pacote mais recente do SDK.
    • Extraia o pacote ZIP e adicione nuisdk.xcframework ao seu projeto.
    • Em Build Phases > Link Binary With Libraries, adicione nuisdk.xcframework.
    • Em General > Frameworks, Libraries, and Embedded Content, defina nuisdk.xcframework como Embed & Sign.
    • Abra o projeto no Xcode. O código de exemplo está em DashQwenAudioChatViewController.m. Substitua a chave de API para testar o recurso.

Procedimento de chamada

  1. Inicialize o SDK.
  2. Defina os parâmetros para o seu caso de uso. Use o argumento parameters de nui_initialize para definir os parâmetros de conexão e controle e use nui_set_params para definir os parâmetros de conversa por voz.
  3. Chame nui_dialog_start para iniciar a conversa.
  4. Em onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio.
  5. Forneça continuamente dados de gravação em onNuiNeedAudioData ou chame nui_update_audio_data para enviar ativamente os dados de gravação.
  6. Receba continuamente o áudio retornado pelo modelo em onNuiAssistEventCallback.
  7. Ouça eventos e obtenha informações de eventos em onNuiEventCallback.
  8. Chame nui_dialog_cancel para interromper a conversa e escute EVENT_TRANSCRIBER_COMPLETE para confirmar que ela terminou.
  9. Quando o recurso de conversa não for mais necessário, chame nui_release para liberar os recursos do SDK.

Parâmetros de solicitação

Parâmetros de conexão e controle

Passe uma string JSON no argumento parameters de nui_initialize. Exemplo: A string JSON a seguir não lista todos os parâmetros. Adicione parâmetros conforme necessário para o seu caso de uso. O exemplo usa qwen-audio-3.1-realtime-plus. Para usar outro modelo, atualize model na URL e nls_config.model em Parâmetros de conversa por 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âmetroTipoObrigatórioDescrição
urlStringSimEndpoint do serviço:
  • wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • China (Pequim): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Substitua {WorkspaceId} pelo seu ID do Workspace.
apikeyStringSimAPI key.
service_modeStringSimModo de execução. Defina este parâmetro como "1" para conversa de voz em tempo real.
device_idStringSimUma string exclusiva que identifica o usuário final. Você pode usar um ID de usuário no aplicativo ou um identificador de dispositivo gerado pelo cliente. Este ID é usado principalmente para rastreamento de logs e solução de problemas.
audio_update_manuallyStringNãoSe deve enviar ativamente dados de áudio. Padrão: "false". Se definido como "true" e o SDK suportar recursos de áudio no dispositivo, como AEC e VAD, esses recursos serão habilitados por padrão.
workspaceStringNãoO caminho de armazenamento para arquivos de recursos no dispositivo. Este parâmetro é obrigatório quando audio_update_manually é "true" e um recurso de áudio no dispositivo, como AEC ou VAD, está habilitado.
debug_pathStringNãoO caminho de armazenamento do arquivo de log. Este parâmetro entra em vigor apenas quando save_log é true em nui_initialize. Neste caso, o caminho é obrigatório. O SDK retém no máximo dois arquivos de log localmente.
save_wavStringNãoSe deve salvar o áudio de depuração em debug_path. Padrão: "false". Os valores válidos são "true" e "false". Este parâmetro entra em vigor apenas quando save_log é true, e debug_path também deve estar definido.
max_log_file_sizeintNãoO tamanho máximo do arquivo de log em bytes. Este parâmetro entra em vigor apenas quando save_log é true. Padrão: 104857600 (100 × 1024 × 1024 bytes, ou 100 MiB).
log_track_levelintNãoO nível de filtro para logs enviados através de onNuiLogTrackCallback. Padrão: 2. Valores válidos: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR) e 5 (NONE). Um log é retornado apenas quando seu nível é maior ou igual a log_track_level e ao level passado para nui_initialize. Por exemplo, se log_track_level for 2 (INFO) e level for 3 (WARNING), apenas logs de WARNING e de nível superior (valores maiores ou iguais a 3) são retornados.

Parâmetros de conversa de voz

Passe uma string JSON no argumento params de nui_set_params. Exemplo: A string JSON a seguir não lista todos os parâmetros. Adicione parâmetros conforme necessário para o seu caso de uso.
{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}
Parâmetros
Parâmetro de nível superiorTipoObrigatórioDescrição
service_typeintSimTipo de serviço de voz. Defina este parâmetro como 4 para conversa de voz em tempo real.
nls_configobjectSimConfiguração principal da conversa de voz, incluindo seleção de modelo e comportamento da conversa.
nls_config.modelstringSimNome do modelo. Suporta as séries de modelos qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash.
nls_config.sr_formatstringSimFormato de áudio de entrada. Apenas pcm é suportado. O formato padrão é PCM mono de 16 kHz e 16 bits.
nls_config.modalitiesstringNãoUma string contendo uma matriz de modalidades de saída. Valores válidos:
  • ["text"]: retorna apenas texto.
  • ["audio", "text"] (padrão): retorna áudio e texto.
nls_config.voicestringNãoVoz TTS. O padrão é longanqian_v3.1 para 3.1 Plus e longanqian para 3.0 Plus/Flash. Este parâmetro pode ser definido apenas no primeiro session.update; valores posteriores são ignorados. Vozes do sistema: longanqian, longanlingxin, longanlingxi, longanxiaoxin e longanlufeng. Você também pode especificar um voice_id clonado criado através da API de clonagem de voz. Consulte Configuração de voz.3.1 Plus também suporta longanqian_v3.1, longanhuan_v3.1, longanlingxin_v3.1, longanfengyue_v3.1, xunanchuan_v3.1, beth_v3.1, betty_v3.1, cally_v3.1.
nls_config.enable_speech_emotionBOOLNãoSe deve habilitar a expressão emocional aprimorada. Quando habilitada, a voz de resposta tem uma variação emocional mais perceptível. Padrão: YES. Valores válidos: YES e NO.
nls_config.instructionsstringNãoInstruções do sistema que definem o papel do modelo, o estilo de resposta e as preferências comportamentais para toda a sessão.
nls_config.max_history_turnsintNãoNúmero máximo de turnos históricos de perguntas e respostas permitidos em uma solicitação. Valores válidos: 1 a 50. Padrão: 20.
nls_config.toolsstringNãoUma string contendo uma matriz de definições de ferramentas de Function Calling. Depois que você configura este parâmetro, o modelo decide se deve chamar uma ferramenta com base na entrada do usuário. Cada definição usa type (obrigatório e fixo como function) e um objeto function contendo name (obrigatório), description (opcional) e parameters (opcional). Se uma função não tiver argumentos, omita parameters.
Exemplo:
[
  {
    "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_detectionstringNãoUma string contendo um objeto JSON para detecção de turnos. Se omitido, a sessão usa o modo push-to-talk, no qual o áudio é enviado e a inferência é acionada manualmente. Se definido, o modo de conversa duplex é habilitado.
nls_config.turn_detection.typestringNãoTipo de VAD. server_vad (padrão) detecta os limites da fala a partir de recursos acústicos e aciona a inferência automaticamente. smart_turn combina sinais acústicos e semânticos; sons sem conteúdo semântico, como sons de preenchimento, não iniciam um turno nem interrompem a reprodução do modelo.
nls_config.turn_detection.thresholdfloatNãoSensibilidade do VAD. Este parâmetro se aplica apenas a server_vad e não tem efeito em smart_turn. Valores mais baixos tornam o VAD mais sensível a sons baixos e ruído de fundo; valores mais altos exigem uma fala mais clara e alta. Intervalo válido: [-1.0, 1.0]. Padrão: 0.5.
nls_config.turn_detection.silence_duration_msintNãoDuração mínima de silêncio após a fala, em milissegundos, antes que a resposta do modelo seja acionada. Este parâmetro se aplica apenas a server_vad e não tem efeito em smart_turn. Valores mais baixos reduzem a latência, mas podem ser acionados em pausas breves. Intervalo válido: [200, 6000]. Padrão: 800. Recomendado para conversa: 400 a 800.
nls_config.turn_detection.voiceprint_audio_urlsstringNãoUma string contendo uma matriz de URLs de áudio pré-gravado publicamente acessíveis para o locutor alvo. Este parâmetro se aplica apenas a smart_turn. Em conversas duplex, ajuda o modelo a focar no locutor alvo e ignorar outros locutores e ruídos de fundo. Até cinco URLs são suportados. O áudio deve ser PCM ou WAV de 16 kHz.

APIs principais

NeoNui

nui_initialize

Inicializa a instância do SDK de conversa por voz. O SDK é um singleton. Não o inicialize novamente antes de chamar nui_release. Assinatura do método
-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;
Descrições dos parâmetros

Parâmetro

Tipo

Descrição

parameters

char*

Uma string JSON que contém parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle.

level

NuiSdkLogLevel

Nível de impressão para os próprios logs do SDK.

save_log

BOOL

Se deve salvar logs localmente. Se definido como YES, especifique um caminho com debug_path em Parâmetros de conexão e controle e, opcionalmente, defina o tamanho do arquivo com max_log_file_size.

nui_set_params

Define os Parâmetros de conversa por voz no formato JSON. Chame este método antes de nui_dialog_start. Assinatura do método
-(NuiResultCode) nui_set_params:(const char *)params;
Descrições dos parâmetros

Parâmetro

Tipo

Descrição

params

char*

Parâmetros de conversa por voz.

nui_dialog_start

Inicia a conversa. Assinatura do método
-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;
Parâmetros
ParâmetroTipoDescrição
vad_modeNuiVadModeModo VAD. Fixado como MODE_P2T.
dialog_paramschar*Se apikey nos parâmetros de conexão e controle for uma chave de API temporária, atualize-a aqui após a expiração.
Formato JSON:
{
  "apikey": "st-****"
}

nui_dialog_cancel

Encerra a conversa ou cancela imediatamente a interação atual. Assinatura do método
-(NuiResultCode) nui_dialog_cancel:(BOOL)force;
Descrições dos parâmetros

Parâmetro

Tipo

Descrição

force

BOOL

Se deve encerrar forçadamente e descartar o resultado final.

  • YES: Encerre a tarefa imediatamente sem esperar que o servidor retorne o resultado final da conversa.

  • NO: Encerre a tarefa, mas aguarde o retorno do resultado completo.

nui_dialog_action

Envia um comando de ação de conversa durante uma interação para atualizar o comportamento em tempo de execução, como o contexto da conversa. Assinatura do método
- (NuiResultCode) nui_dialog_action:(const char *)params;
Parâmetros
ParâmetroTipoDescrição
paramschar*Uma string JSON usada para atualizar o comportamento em tempo de execução, como o contexto da conversa.
params.typeStringDefina como "action".
params.commandStringComando de tempo de execução. Valores válidos:
  • function_call: atualiza uma solicitação de chamada de função.
  • play_start: quando o AEC no dispositivo é usado, notifica o SDK de que a reprodução de áudio começou.
  • play_over: quando o AEC no dispositivo é usado, notifica o SDK de que a reprodução de áudio terminou.
params.contextStringAtualização de solicitação de chamada de função. Usado quando command é "function_call".
params.context.typeStringTipo de evento. Este parâmetro é obrigatório quando command é "function_call". conversation.item.create insere um item de conversa para contexto histórico, texto suplementar ou resultado de ferramenta. Após enviar conversation.item.create, use response.create para acionar outra inferência.
params.context.itemobjectObrigatório quando params.context.type é conversation.item.create. O item de conversa a ser criado.
params.context.responseobjectOpcional quando params.context.type é response.create. Substitui os padrões da sessão para esta inferência. Se omitido, a configuração atual da sessão é usada.
Parâmetros de context.item:
ParâmetroTipoDescrição
idStringID de item de conversa exclusivo opcional. Se omitido, o servidor gera um. Um erro é retornado se o ID especificado já existir.
typeStringTipo de item obrigatório. Valores válidos:
  • message: uma mensagem comum.
  • function_call: uma solicitação de chamada de função. Este tipo é normalmente gerado pelo servidor. O cliente também pode usá-lo para adicionar contexto histórico.
  • function_call_output: um resultado de execução de ferramenta. Após receber um function_call, o cliente executa a ferramenta e usa este tipo para gravar o resultado de volta.
roleStringObrigatório para message. Valores válidos: system, user e assistant.
contentarrayObrigatório para message. Cada item contém um type e o campo de dados associado. system suporta input_text com text; user suporta input_text com text e input_audio com audio codificado em Base64; assistant suporta output_text com text.
call_idStringObrigatório para function_call e function_call_output. O ID exclusivo que associa uma solicitação de chamada de função ao seu resultado.
nameStringObrigatório para function_call. O nome da função a ser chamada.
argumentsStringObrigatório para function_call. Argumentos da função como uma string JSON.
outputStringObrigatório para function_call_output. Resultado da execução da ferramenta como uma string JSON.
Parâmetros de context.response:
ParâmetroTipoDescrição
modalitiesarrayModalidades de saída. ["text"] retorna apenas texto. ["audio", "text"] (padrão) retorna áudio e texto.
voicestringSubstitui a voz TTS para esta inferência.
Exemplo:
{
  "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

Quando audio_update_manually é definido como "true", os dados de gravação não são mais fornecidos por meio de onNuiNeedAudioData. Use este método para enviá-los ativamente. Assinatura do método
-(NuiResultCode) nui_update_audio_data:(const char *)data
                                    Len:(int)length
                              FirstPack:(BOOL)first_pack;
Descrições dos parâmetros

Parâmetro

Tipo

Descrição

data

const char *

Os dados de áudio a serem enviados.

length

int

O comprimento dos dados de áudio, em bytes.

first_pack

BOOL

Você não precisa usar este parâmetro.

nui_push_reference_data

Quando audio_update_manually é definido como "true" e o cancelamento de eco acústico (AEC) no dispositivo está ativado, use este método para enviar o áudio reproduzido pelo player como sinal de referência. Assinatura do método
-(NuiResultCode) nui_push_reference_data:(const char *)data
                                     Len:(int)length
                               FirstPack:(BOOL)first_pack;
Descrições dos parâmetros

Parâmetro

Tipo

Descrição

data

const char *

Os dados de áudio a serem enviados.

length

int

O comprimento dos dados de áudio, em bytes.

first_pack

BOOL

Você não precisa usar este parâmetro.

nui_release

Libera todos os recursos internos do SDK e encerra forçosamente todas as tarefas em execução. Depois de chamar este método, a instância do SDK fica indisponível. Para usá-la novamente, você deve chamar nui_initialize para inicializá-la novamente. Assinatura do método
-(NuiResultCode) nui_release;

nui_get_version

Obtém a versão atual do SDK. Este método retorna um valor somente após nui_initialize ser chamado. Assinatura do método
-(const char*) nui_get_version;
Valor de retorno A versão atual do SDK.

nui_get_all_response

Obtém as informações completas para o callback de evento atual. Assinatura do método
-(const char*) nui_get_all_response;
Valor de retorno As informações completas do evento como uma string JSON.

NeoNuiSdkDelegate: listeners de callback

onNuiEventCallback: ouvir informações de eventos

Assinatura do método
-(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;
Descrições dos parâmetros

Parâmetro

Tipo

Descrição

nuiEvent

NuiCallbackEvent

Evento de callback.

dialog

long

ID da sessão. Você não precisa usar este parâmetro.

wuw

char*

Despertar por voz. Você não precisa usar este parâmetro.

asr_result

char*

Resultado do reconhecimento de fala.

finish

BOOL

Se a rodada de reconhecimento atual foi concluída.

code

int

Válido apenas quando o evento EVENT_ASR_ERROR ocorre.

onNuiAudioStateChanged: ouvir o estado do áudio

O SDK usa este callback para notificá-lo quando iniciar ou parar a gravação. Assinatura do método
-(void) onNuiAudioStateChanged:(NuiAudioState)state;
Estados de NuiAudioState

Parâmetro

Descrição

STATE_OPEN

A interação foi iniciada. Você pode abrir o dispositivo de gravação e começar a gravar.

STATE_PAUSE

A interação parou. Você pode parar a gravação.

STATE_CLOSE

A instância do SDK foi liberada. Você pode fechar completamente o dispositivo de gravação.

onNuiNeedAudioData: fornecer dados de áudio

Depois que a conversa começa, este callback é acionado continuamente. Forneça os dados de áudio neste callback. Você não precisa usar este callback quando audio_update_manually está definido como "true". Assinatura do método
-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;
Descrições dos parâmetros

Parâmetro

Tipo

Descrição

audioData

char *

Os dados de áudio a serem fornecidos.

len

int

O tamanho dos dados de áudio fornecidos, em bytes.

onNuiAssistEventCallback: receber dados e informações auxiliares

Recebe eventos auxiliares e dados relacionados do SDK. Assinatura do método
-(void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
                            info:(char*)info
                         infoLen:(int)info_len
                          buffer:(char*)buffer
                             len:(int)len;
Descrições dos parâmetros

Parâmetro

Tipo

Descrição

nuiEvent

NuiCallbackEvent

O evento de callback.

info

char *

Você não precisa usar este parâmetro.

info_len

int

Você não precisa usar este parâmetro.

buffer

char *

Dados auxiliares, como áudio TTS retornado pelo modelo.

len

int

O comprimento dos dados auxiliares, em bytes.

onNuiLogTrackCallback: escutar logs de rastreamento

Este callback recebe os logs internos detalhados do SDK para ajudar você a localizar e depurar problemas.
-(void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

NuiCallbackEvent: tipos de evento

EventoDescrição
EVENT_TRANSCRIBER_STARTEDA tarefa foi iniciada com sucesso.
EVENT_VAD_STARTAcionado imediatamente após o início da tarefa. Isso não significa que o início da fala foi detectado.
EVENT_VAD_ENDO fim da fala foi detectado.
EVENT_ASR_PARTIAL_RESULTUm resultado intermediário de reconhecimento de fala.
EVENT_ASR_ERROROcorreu um erro durante a conversa de voz.
EVENT_MIC_ERRORAcionado quando nenhum dado de áudio é recebido por dois segundos consecutivos.
EVENT_SENTENCE_ENDO fim de uma frase foi detectado e um resultado de reconhecimento completo foi retornado.
EVENT_TRANSCRIBER_COMPLETEA conversa de voz terminou.
EVENT_AUDIO_TRANSCRIPTIONUm evento de transcrição de texto incremental para saída de áudio. Os segmentos de transcrição são retornados no modo de streaming.
EVENT_AUDIO_TRANSCRIPTION_COMPLETEDA transcrição da saída de áudio está concluída.
EVENT_OTHER_RESULTOutras informações de evento, como um resultado de Function Calling.
EVENT_ASR_TTS_STARTO modelo começou a retornar áudio TTS.
EVENT_ASR_TTS_DATAÁudio TTS retornado pelo modelo.
EVENT_ASR_TTS_COMPLETEO modelo terminou de retornar áudio TTS.
EVENT_AEC_DATADados de áudio processados pelo AEC.