Use o SDK iOS de conversa por voz em tempo real do Qwen-Audio-Realtime para implementar entrada de áudio em tempo real e saída de voz ou texto.
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 a apresentação do modelo e recomendações de seleção, consulte Conversa por voz em tempo real.
Pré-requisitos
- Obtenha e configure uma chave de API. Não insira chaves de API de longa duração diretamente no código de aplicativos móveis. Recomendamos que o servidor do seu aplicativo gere uma chave de API temporária e a distribua ao cliente.
Instalar o SDK
- Baixe o pacote de integração 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.
Início rápido
Abra o projeto de exemplo no Xcode. O código de exemplo está em DashQwenAudioChatViewController.m. Substitua a chave de API e teste os recursos.
Procedimento
- Inicialize o SDK.
- Defina os parâmetros de acordo com as necessidades do seu negócio: use a interface nui_initialize para definir os parâmetros de conexão e controle; use a interface nui_set_params para definir os parâmetros de efeito da conversa por voz.
- Chame nui_dialog_start para iniciar o processo de conversa.
- No callback onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio.
- No callback onNuiNeedAudioData, forneça continuamente os dados de gravação ou use nui_update_audio_data para enviar continuamente os dados de gravação.
- No callback onNuiAssistEventCallback, receba continuamente os dados de voz retornados pela IA.
- No callback onNuiEventCallback, ouça os eventos e obtenha as informações dos eventos.
- Chame nui_dialog_cancel para interromper a conversa e confirme que ela foi encerrada ouvindo o evento EVENT_TRANSCRIBER_COMPLETE.
- Quando a função de conversa não for mais necessária, chame a interface nui_release para liberar os recursos do SDK.
Parâmetros da solicitação
Parâmetros de conexão e controle
Configure passando uma string JSON para o parâmetro parameters da interface nui_initialize.
Exemplo de parâmetros:O exemplo a seguir é uma string JSON. Os parâmetros não estão totalmente listados. Adicione-os conforme necessário durante o desenvolvimento:
Este exemplo usa qwen-audio-3.1-realtime-plus. Ao alterar o modelo, atualize model na URL e nls_config.model nos parâmetros de efeito da conversa por voz adequadamente.
{
"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"
}
Descrição dos parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | URL do serviço:
{WorkspaceId} pelo seu ID do Workspace real. |
|
| Sim | Chave de API. |
|
| Sim | Modo de operação. Para conversa por voz em tempo real, este parâmetro é fixado como |
|
| Sim | Uma string exclusiva usada para identificar o usuário final. Você pode defini-la como o ID de usuário no aplicativo ou um identificador exclusivo de dispositivo gerado pelo cliente. Este ID é usado principalmente para rastreamento de logs e solução de problemas. |
|
| Não | Se deve ativar o modo de envio proativo de dados de áudio. Valor padrão: "false". |
|
| Não | O caminho de armazenamento dos arquivos de recursos no dispositivo. Este parâmetro deve ser definido quando |
|
| Não | O caminho de armazenamento dos arquivos de log. Este parâmetro entra em vigor apenas quando |
|
| Não | Se deve salvar arquivos de áudio para depuração. Os arquivos de áudio são salvos em
save_log é definido como true ao chamar o método nui_initialize. Além disso, debug_path também deve ser definido. |
|
| Não | Define o número máximo de bytes para os arquivos de log. Este parâmetro entra em vigor apenas quando |
|
| Não | Controla o nível de filtro do conteúdo de log enviado externamente por meio do callback de log (onNuiLogTrackCallback).
log_track_level e level (definido por meio do método nui_initialize) determinam conjuntamente os logs que são finalmente retornados. Um log é retornado apenas se o seu valor de nível for maior ou igual a ambos log_track_level e level. Por exemplo, se log_track_level for definido como 2 (INFO) e level como 3 (WARNING), apenas logs de nível WARNING e superior (valor >=3) serão retornados. |
Parâmetros de efeito da conversa por voz
Configurado passando uma string JSON para o parâmetro params do método nui_set_params.
Exemplo de parâmetros:O exemplo a seguir é uma string JSON. Os parâmetros não estão totalmente listados. Adicione-os conforme necessário durante o desenvolvimento:
{
"service_type": 4,
"nls_config": {
"model": "qwen-audio-3.1-realtime-plus",
"sr_format": "pcm"
}
}
Descrição dos parâmetros
| Parâmetro de nível superior | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Tipo de serviço de voz. Fixado em |
|
| Sim | O objeto de configuração principal da conversa por voz, contendo parâmetros-chave como seleção de modelo e controle do efeito da conversa. |
|
| Sim | Especifica o nome do modelo. Os modelos suportados incluem as séries qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash. |
|
| Sim | Formato do áudio de entrada. Atualmente, apenas |
|
| Não | Uma string em formato de matriz. As configurações de modalidade de saída do modelo. Valores válidos:
|
nls_config.voice |
| Não | O nome da voz do TTS. O valor padrão para 3.1 Plus/Flash é
|
nls_config.enable_speech_emotion |
| Não | Se deve ativar o aprimoramento de emoção. Quando ativado, as mudanças emocionais da voz de resposta ficam mais perceptíveis. Valor padrão: |
nls_config.instructions |
| Não | A instrução do sistema, usada para definir o papel do modelo, o estilo de resposta e as preferências de comportamento. Aplica-se a toda a sessão. |
nls_config.max_history_turns | int | Não | O número máximo de turnos históricos de perguntas e respostas permitidos por solicitação. Intervalo de valores: 1-50. Valor padrão: 20. |
nls_config.tools |
| Não | Uma string em formato de matriz. Uma lista de definições de ferramentas de Function Calling. Depois de configurado, o modelo pode decidir de forma autônoma se deve chamar ferramentas com base na entrada do usuário. |
nls_config.turn_detection |
| Não | As descrições dos campos de detecção de turno a seguir se aplicam a Uma string em formato de objeto JSON. A configuração de detecção de turno. Quando não definida, muda para o modo push-to-talk (envio manual de áudio e acionamento manual da inferência). Caso contrário, o modo de conversa duplex é habilitado. |
nls_config.turn_detection.type |
| Não | O tipo de VAD. Valores válidos:
|
nls_config.turn_detection.threshold | float | Não | Sensibilidade do VAD. Aplica-se a |
nls_config.turn_detection.silence_duration_ms |
| Não | A duração mínima de silêncio (em milissegundos) após o fim da fala. Apenas efetivo no modo server_vad (não efetivo nos modos smart_turn e smart_turn_v2). Assim que o silêncio atinge essa duração, a resposta do modelo é acionada. Valores menores tornam as respostas mais rápidas, mas pausas breves também podem causar acionamentos falsos. |
nls_config.turn_detection.voiceprint_audio_urls |
| Não | Uma string em formato de matriz. Efetivo nos modos smart_turn e smart_turn_v2.Uma lista de URLs publicamente acessíveis do áudio pré-gravado do usuário alvo, usada para o aprimoramento do locutor. O modelo usa essas amostras de áudio para focar no locutor alvo durante conversas full-duplex, ignorando outras vozes e o ruído de fundo. Até 5 URLs são suportadas. Requisitos de formato de áudio: PCM ou WAV de 16kHz. |
Referência da API
NeoNui
nui_initialize
Inicializa a instância do SDK de conversa por voz. O SDK é um singleton; não o inicialize repetidamente antes de chamar nui_release.
- (NuiResultCode) nui_initialize:(const char *)parameters
logLevel:(NuiSdkLogLevel)level
saveLog:(BOOL)save_log;
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Uma string JSON contendo parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle. |
|
| Controla o nível de saída de log dos logs do próprio SDK. |
| BOOL | Se deve salvar logs localmente. Se definido como |
nui_set_params
Define parâmetros de efeito da conversa por voz em formato JSON. Chame antes de nui_dialog_start.
- (NuiResultCode) nui_set_params:(const char *)params;
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
nui_dialog_start
Inicia uma conversa.
Assinatura do método- (NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
dialogParam:(const char *)dialog_params;
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Modo VAD. Fixado em |
|
| Se o parâmetro |
nui_dialog_cancel
Encerra a conversa ou cancela imediatamente a interação atual.
Assinatura do método- (NuiResultCode) nui_dialog_cancel:(BOOL)force;
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Se deve encerrar a tarefa forçosamente e ignorar o resultado final.
|
nui_dialog_action
Envia comandos de ação de diálogo durante a interação, usados para atualizar comportamentos em tempo de execução, como o contexto da conversa.
Assinatura do método- (NuiResultCode) nui_dialog_action:(const char *)params;
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Uma string JSON usada para atualizar comportamentos em tempo de execução, como o contexto da conversa. |
|
| Fixado como |
|
| O comando de tempo de execução específico. Atualmente suporta
|
|
| Atualiza a solicitação de chamada de função quando |
|
| Tipo de evento; obrigatório quando
|
|
| Obrigatório quando |
|
| Opcional quando |
Parâmetro context.item:
| Parâmetro | Tipo | Descrição |
|---|---|---|
id |
| Opcional. O identificador exclusivo do item de conversa. Se não especificado, é gerado automaticamente pelo servidor. Se o ID especificado já existir na conversa, um erro será retornado. |
type |
| Obrigatório. O tipo de item de conversa. Valores válidos:
|
role |
| Obrigatório para o tipo |
content | array | Obrigatório para o tipo
output_text: Saída de texto do assistente, campo obrigatório text. |
call_id |
| (Obrigatório para os tipos |
name |
| (Obrigatório para o tipo |
arguments |
| Obrigatório para o tipo |
output |
| (Obrigatório para o tipo |
Parâmetro context.response:
| Parâmetro | Tipo | Descrição |
|---|---|---|
modalities |
| Uma string em formato de matriz. As configurações de modalidade de saída do modelo. Valores válidos:
|
voice | string | Substitui a voz do TTS para a rodada atual. |
Exemplos:
{
"type": "action",
"command": "function_call",
"context": {
"item": {
"call_id": "call_xxxx",
"output": "{\"city\":\"杭州\",\"condition\":\"晴\",\"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 preenchidos por meio de onNuiNeedAudioData; em vez disso, são enviados ativamente por meio desta interface.
- (NuiResultCode) nui_update_audio_data:(const char *)data
Len:(int)length
FirstPack:(BOOL)first_pack;
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Os dados de áudio enviados. |
|
| O número de bytes dos dados de áudio enviados. |
|
| Você não precisa prestar atenção neste parâmetro. |
nui_push_reference_data
Quando audio_update_manually é definido como "true" e o recurso de cancelamento de eco AEC no dispositivo está habilitado, você precisa enviar os dados de áudio reproduzidos pelo player por meio desta interface como sinal de referência.
- (NuiResultCode) nui_push_reference_data:(const char *)data
Len:(int)length
FirstPack:(BOOL)first_pack;
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Os dados de áudio enviados. |
|
| O número de bytes dos dados de áudio enviados. |
|
| Você não precisa prestar atenção neste parâmetro. |
nui_release
Libera todos os recursos internos do SDK e encerra forçosamente todas as tarefas em andamento. Depois que este método é chamado, a instância do SDK fica indisponível. Para usá-la novamente, você deve chamar nui_initialize novamente para inicialização.
- (NuiResultCode) nui_release;
nui_get_version
Obtém as informações da versão atual do SDK. Esta interface deve ser chamada após nui_initialize para retornar um valor.
- (const char*) nui_get_version;
Descrição do valor de retorno
Informações da versão atual do SDK.
nui_get_all_response
Obtém as informações completas do callback de evento atual.
Assinatura do método- (const char*) nui_get_all_response;
Descrição do valor de retorno
Informações completas do evento em formato de string JSON.
NeoNuiSdkDelegate: Callbacks de listener
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ção dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Evento de callback. |
|
| Codificação da sessão. Você não precisa prestar atenção neste parâmetro. |
|
| Despertar por voz. Você não precisa prestar atenção neste parâmetro. |
|
| Resultado do reconhecimento de fala. |
|
| Indicador de se o reconhecimento desta rodada foi encerrado. |
|
| Válido apenas quando o evento |
onNuiAudioStateChanged: Ouvir o estado do áudio
O SDK usa este callback para notificar quando iniciar ou parar a gravação.
Assinatura do método- (void) onNuiAudioStateChanged:(NuiAudioState)state;
Descrição de NuiAudioState
| Parâmetro | Descrição |
|---|---|
| A interação começa. Você pode ligar o dispositivo de gravação para gravar áudio. |
| A interação para. Você pode parar a gravação. |
| A instância do SDK foi liberada. Você pode fechar completamente o dispositivo de gravação. |
onNuiNeedAudioData: Preencher dados de áudio para processar
Depois que uma conversa começa, este callback é acionado continuamente, e você deve fornecer nele os dados de áudio a serem processados. Você pode ignorar este callback se o parâmetro audio_update_manually estiver definido como "true".
Assinatura do método- (int) onNuiNeedAudioData:(char *)audioData length:(int)len;
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Os dados de áudio preenchidos. |
|
| O número de bytes dos dados de áudio preenchidos. |
onNuiAssistEventCallback: Resultados de dados e informações auxiliares
Este callback é usado para receber eventos auxiliares e dados relacionados de dentro do SDK.
Assinatura do método- (void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
info:(char*)info
infoLen:(int)info_len
buffer:(char*)buffer
len:(int)len;
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Evento de callback. |
|
| Você não precisa prestar atenção neste parâmetro. |
|
| Você não precisa prestar atenção neste parâmetro. |
|
| Dados auxiliares, como áudio TTS retornado pela IA. |
|
| O número de bytes dos dados auxiliares. |
onNuiLogTrackCallback: Ouvir logs de rastreamento
Este callback é usado para receber logs detalhados de dentro do SDK, o que facilita a solução de problemas e a depuração.
- (void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
logMessage:(const char *)log;
NuiCallbackEvent: Tipos de evento
| Evento | Descrição |
|---|---|
EVENT_TRANSCRIBER_STARTED | A tarefa foi iniciada com sucesso. |
EVENT_VAD_START | Este evento é acionado assim que a tarefa começa. Ele não indica que o início da fala humana foi detectado. |
EVENT_VAD_END | O fim da fala humana é detectado. |
EVENT_ASR_PARTIAL_RESULT | Resultados intermediários do reconhecimento de fala. |
EVENT_ASR_ERROR | Ocorre um erro durante a conversa por voz. |
EVENT_MIC_ERROR | Acionado quando nenhum dado de áudio é recebido por 2 segundos consecutivos. |
EVENT_SENTENCE_END | O fim de uma frase é detectado, e um resultado completo do reconhecimento é retornado neste momento. |
EVENT_TRANSCRIBER_COMPLETE | A conversa por voz termina. |
EVENT_AUDIO_TRANSCRIPTION | Evento incremental de legenda de texto no modo de áudio, que retorna segmentos de legenda de maneira contínua (streaming). |
EVENT_AUDIO_TRANSCRIPTION_COMPLETED | Evento de conclusão da saída de legendas no modo de áudio. |
EVENT_OTHER_RESULT | Outras informações de evento não classificadas, como os resultados retornados de function_call. |
EVENT_ASR_TTS_START | A IA começa a retornar dados TTS. |
EVENT_ASR_TTS_DATA | Dados TTS retornados pela IA. |
EVENT_ASR_TTS_COMPLETE | A IA termina de retornar dados TTS. |
EVENT_AEC_DATA | Dados de áudio após o cancelamento de eco AEC. |