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.
Início rápido
- Obter uma chave de API: Obter e configurar uma chave de API.
-
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote mais recente do SDK.
- Extraia o pacote ZIP e adicione
nuisdk.xcframeworkao seu projeto. - Em Build Phases > Link Binary With Libraries, adicione
nuisdk.xcframework. - Em General > Frameworks, Libraries, and Embedded Content, defina
nuisdk.xcframeworkcomo 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
- Inicialize o SDK.
- Defina os parâmetros para o seu caso de uso. Use o argumento
parametersde 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. - Chame nui_dialog_start para iniciar a conversa.
- Em onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio.
- Forneça continuamente dados de gravação em onNuiNeedAudioData ou chame nui_update_audio_data para enviar ativamente os dados de gravação.
- Receba continuamente o áudio retornado pelo modelo em onNuiAssistEventCallback.
- Ouça eventos e obtenha informações de eventos em onNuiEventCallback.
- Chame nui_dialog_cancel para interromper a conversa e escute
EVENT_TRANSCRIBER_COMPLETEpara confirmar que ela terminou. - 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.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | String | Sim | Endpoint do serviço:
{WorkspaceId} pelo seu ID do Workspace. |
apikey | String | Sim | API key. |
service_mode | String | Sim | Modo de execução. Defina este parâmetro como "1" para conversa de voz em tempo real. |
device_id | String | Sim | Uma 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_manually | String | Não | Se 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. |
workspace | String | Não | O 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_path | String | Não | O 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_wav | String | Não | Se 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_size | int | Não | O 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_level | int | Não | O 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.
| Parâmetro de nível superior | Tipo | Obrigatório | Descrição |
|---|---|---|---|
service_type | int | Sim | Tipo de serviço de voz. Defina este parâmetro como 4 para conversa de voz em tempo real. |
nls_config | object | Sim | Configuração principal da conversa de voz, incluindo seleção de modelo e comportamento da conversa. |
nls_config.model | string | Sim | Nome 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_format | string | Sim | Formato de áudio de entrada. Apenas pcm é suportado. O formato padrão é PCM mono de 16 kHz e 16 bits. |
nls_config.modalities | string | Não | Uma string contendo uma matriz de modalidades de saída. Valores válidos:
|
nls_config.voice | string | Não | Voz 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_emotion | BOOL | Não | Se 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.instructions | string | Não | Instruçõ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_turns | int | Não | Nú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.tools | string | Não | Uma 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: |
nls_config.turn_detection | string | Não | Uma 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.type | string | Não | Tipo 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.threshold | float | Não | Sensibilidade 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_ms | int | Não | Duraçã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_urls | string | Não | Uma 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
Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Uma string JSON que contém parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle. |
|
| Nível de impressão para os próprios logs do SDK. |
| BOOL | Se deve salvar logs localmente. Se definido como |
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
Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
nui_dialog_start
Inicia a conversa.
Assinatura do método
| Parâmetro | Tipo | Descrição |
|---|---|---|
vad_mode | NuiVadMode | Modo VAD. Fixado como MODE_P2T. |
dialog_params | char* | 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: |
nui_dialog_cancel
Encerra a conversa ou cancela imediatamente a interação atual.
Assinatura do método
Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Se deve encerrar forçadamente e descartar o resultado final.
|
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
| Parâmetro | Tipo | Descrição |
|---|---|---|
params | char* | Uma string JSON usada para atualizar o comportamento em tempo de execução, como o contexto da conversa. |
params.type | String | Defina como "action". |
params.command | String | Comando de tempo de execução. Valores válidos:
|
params.context | String | Atualização de solicitação de chamada de função. Usado quando command é "function_call". |
params.context.type | String | Tipo 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.item | object | Obrigatório quando params.context.type é conversation.item.create. O item de conversa a ser criado. |
params.context.response | object | Opcional 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. |
context.item:
| Parâmetro | Tipo | Descrição |
|---|---|---|
id | String | ID de item de conversa exclusivo opcional. Se omitido, o servidor gera um. Um erro é retornado se o ID especificado já existir. |
type | String | Tipo de item obrigatório. Valores válidos:
|
role | String | Obrigatório para message. Valores válidos: system, user e assistant. |
content | array | Obrigató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_id | String | Obrigatório para function_call e function_call_output. O ID exclusivo que associa uma solicitação de chamada de função ao seu resultado. |
name | String | Obrigatório para function_call. O nome da função a ser chamada. |
arguments | String | Obrigatório para function_call. Argumentos da função como uma string JSON. |
output | String | Obrigatório para function_call_output. Resultado da execução da ferramenta como uma string JSON. |
context.response:
| Parâmetro | Tipo | Descrição |
|---|---|---|
modalities | array | Modalidades de saída. ["text"] retorna apenas texto. ["audio", "text"] (padrão) retorna áudio e texto. |
voice | string | Substitui a voz TTS para esta inferência. |
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
Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Os dados de áudio a serem enviados. |
|
| O comprimento dos dados de áudio, em bytes. |
|
| 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
Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Os dados de áudio a serem enviados. |
|
| O comprimento dos dados de áudio, em bytes. |
|
| 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
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
nui_get_all_response
Obtém as informações completas para o callback de evento atual.
Assinatura do método
NeoNuiSdkDelegate: listeners de callback
onNuiEventCallback: ouvir informações de eventos
Assinatura do método
Parâmetro | Tipo | Descrição |
|---|---|---|
| Evento de callback. | |
|
| ID da sessão. Você não precisa usar este parâmetro. |
|
| Despertar por voz. Você não precisa usar este parâmetro. |
|
| Resultado do reconhecimento de fala. |
|
| Se a rodada de reconhecimento atual foi concluída. |
|
| Válido apenas quando o evento |
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
Parâmetro | Descrição |
|---|---|
| A interação foi iniciada. Você pode abrir o dispositivo de gravação e começar a gravar. |
| A interação parou. Você pode parar a gravação. |
| 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
Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Os dados de áudio a serem fornecidos. |
|
| 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
Parâmetro | Tipo | Descrição |
|---|---|---|
|
| O evento de callback. |
|
| Você não precisa usar este parâmetro. |
|
| Você não precisa usar este parâmetro. |
|
| Dados auxiliares, como áudio TTS retornado pelo modelo. |
|
| 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.
NuiCallbackEvent: tipos de evento
| Evento | Descrição |
|---|---|
EVENT_TRANSCRIBER_STARTED | A tarefa foi iniciada com sucesso. |
EVENT_VAD_START | Acionado imediatamente após o início da tarefa. Isso não significa que o início da fala foi detectado. |
EVENT_VAD_END | O fim da fala foi detectado. |
EVENT_ASR_PARTIAL_RESULT | Um resultado intermediário de reconhecimento de fala. |
EVENT_ASR_ERROR | Ocorreu um erro durante a conversa de voz. |
EVENT_MIC_ERROR | Acionado quando nenhum dado de áudio é recebido por dois segundos consecutivos. |
EVENT_SENTENCE_END | O fim de uma frase foi detectado e um resultado de reconhecimento completo foi retornado. |
EVENT_TRANSCRIBER_COMPLETE | A conversa de voz terminou. |
EVENT_AUDIO_TRANSCRIPTION | Um 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_COMPLETED | A transcrição da saída de áudio está concluída. |
EVENT_OTHER_RESULT | Outras informações de evento, como um resultado de Function Calling. |
EVENT_ASR_TTS_START | O modelo começou a retornar áudio TTS. |
EVENT_ASR_TTS_DATA | Áudio TTS retornado pelo modelo. |
EVENT_ASR_TTS_COMPLETE | O modelo terminou de retornar áudio TTS. |
EVENT_AEC_DATA | Dados de áudio processados pelo AEC. |