Use o SDK Android do Qwen-Audio-Realtime para conversas por voz em tempo real, com entrada de áudio em tempo real e saída de voz ou texto.
Para conexão e autenticação, consulte Acesso por WebSocket; para campos de eventos e exemplos JSON, consulte eventos do cliente e eventos do servidor.
Guia do usuário:Para introdução ao modelo e recomendações de seleção de modelo, 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 mais recente do SDK.
- Descompacte o pacote ZIP. Obtenha o SDK no formato AAR no diretório
app/libse adicione-o às dependências do seu projeto. Para integração com Android C++, useandroid_libseandroid_includeno pacote ZIP para obter as bibliotecas dinâmicas e os arquivos de cabeçalho.
Início rápido
Abra o projeto no Android Studio. O código de exemplo está em DashQwenAudioChatActivity.java. Substitua a chave de API para experimentar os recursos.
Procedimento de chamada
- Inicialize o SDK.
- Defina os parâmetros de acordo com os requisitos do seu negócio: defina os parâmetros de conexão e controle por meio do parâmetro
parametersda interface initialize; defina os parâmetros de efeito de conversa por voz por meio da interface setParams. - Chame startDialog para iniciar o fluxo de conversa.
- No callback onNuiAudioStateChanged, ative o dispositivo de gravação com base no estado do áudio.
- Forneça continuamente os dados de gravação no callback onNuiNeedAudioData ou envie continuamente os dados de gravação por meio de updateAudio.
- Obtenha continuamente os dados de voz retornados pela IA no callback onNuiAssistEventCallback.
- Ouça os eventos e obtenha as informações de eventos no callback onNuiEventCallback.
- Chame stopDialog para encerrar a conversa e confirme que a conversa terminou ouvindo o evento EVENT_TRANSCRIBER_COMPLETE.
- Quando o recurso de conversa não for mais utilizado, chame a interface 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 initialize.
Exemplo de parâmetros:Veja a seguir um exemplo de string JSON com parâmetros não totalmente listados. Adicione-os de acordo com seus requisitos reais ao codificar:
O exemplo usa qwen-audio-3.1-realtime-plus. Ao alterar o modelo, atualize tanto model na URL quanto nls_config.model nos parâmetros de efeito 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"
}
Descrição dos parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Endereço do serviço:
{WorkspaceId} pelo seu ID do Workspace real. |
|
| Sim | Chave de API. |
|
| Sim | Modo de execução. Para conversa por voz em tempo real, este valor é fixado como |
|
| Sim | Uma string exclusiva que identifica 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. |
audio_update_manually |
| Não | Se deve ativar o modo de envio ativo de dados de áudio. Valor padrão: "false". |
workspace |
| Não | Quando o parâmetro audio_update_manually é definido como "true" e os recursos de áudio no dispositivo (como AEC e VAD) estão habilitados, você deve definir workspace, que é o caminho onde os arquivos de recursos no dispositivo são armazenados. |
|
| 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 a API initialize. Nesse caso, debug_path também deve ser definido. |
|
| Não | O tamanho máximo de um arquivo de log, em bytes. |
|
| Não | Controla o nível de filtro do conteúdo de log enviado por meio do callback de log (
log_track_level e level (definido por meio da API initialize) determinam em conjunto os logs que são finalmente retornados por callback. Um log é retornado por callback apenas se o seu valor de nível for maior ou igual tanto a log_track_level quanto a 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 por callback. |
aec_params |
| Não | Objeto de configuração de parâmetros avançados para os recursos de AEC no dispositivo. Este objeto de configuração é ativado apenas quando o parâmetro audio_update_manually é definido como "true". |
aec_params.enable_aec |
| Não | Se deve ativar o recurso de cancelamento de eco AEC no dispositivo. |
aec_params.save_audio |
| Não | Se deve ativar o recurso de armazenamento de áudio do módulo de cancelamento de eco AEC no dispositivo. Quando |
aec_params.enable_aec_data_callback |
| Não | Se deve enviar os dados processados pelo AEC ao usuário; padrão false; uma vez ativado, os dados são recebidos em EVENT_AEC_DATA de onNuiAssistEventCallback. |
vad_params |
| Não | Objeto de configuração de parâmetros avançados para os recursos de VAD no dispositivo. |
vad_params.enable_vad |
| Não | Se deve ativar o recurso de detecção de voz VAD no dispositivo. |
vad_params.save_audio |
| Não | Se deve ativar o recurso de armazenamento de áudio do módulo de detecção de voz VAD no dispositivo. |
Parâmetros de efeito de conversa por voz
Configurado passando uma string JSON para o parâmetro params da API setParams.
Exemplo de parâmetros:Veja a seguir um exemplo de string JSON com parâmetros não totalmente listados. Adicione-os de acordo com seus requisitos reais ao codificar:
{
"service_type": 4,
"nls_config": {
"model": "qwen-audio-3.1-realtime-plus",
"sr_format": "pcm"
}
}
Descrição dos parâmetros
| Parâmetros de nível superior | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Tipo de serviço de voz. Fixado como |
|
| Sim | Objeto de configuração principal da conversa por voz, contendo parâmetros essenciais como seleção de modelo e controle do efeito da conversa. |
|
| Sim | Especifica o nome do modelo. Oferece suporte aos modelos das 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 de áudio de entrada. Atualmente, apenas |
|
| Não | Uma string em formato de matriz para as configurações de modalidade de saída do modelo. Valores válidos:
|
nls_config.voice |
| Não | Nome da voz TTS. O valor padrão para 3.1 Plus/Flash é
|
nls_config.enable_speech_emotion |
| Não | Se deve ativar o recurso de 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 | Instrução do sistema usada para definir a identidade do papel do modelo, o estilo de resposta e as preferências de comportamento. Tem efeito durante toda a sessão. |
nls_config.max_history_turns |
| 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 configurada, 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. Configuração de detecção de turno. Quando não definida, muda para o modo push-to-talk (enviar áudio e acionar a inferência manualmente). Caso contrário, o modo de conversa duplex é habilitado. |
nls_config.turn_detection.type |
| Nã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. Em vigor apenas no modo server_vad (sem efeito nos modos smart_turn e smart_turn_v2). Quando o silêncio atinge essa duração, a resposta do modelo é acionada. Quanto menor o valor, mais rápida a resposta, mas pausas breves também podem causar acionamento incorreto. |
nls_config.turn_detection.voiceprint_audio_urls |
| Não | Uma string em formato de matriz. Em vigor 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 aprimoramento do locutor. O modelo usa esses clipes de áudio para focar no locutor alvo durante a conversa duplex, ignorando vozes de terceiros e ruído de fundo. Até 5 URLs são suportadas. Requisitos de formato de áudio: PCM ou WAV de 16kHz. |
Referência de interface
NativeNui
initialize · Inicializar o SDK
Inicializa a instância do SDK de conversa por voz. O SDK é um singleton; é proibido inicializá-lo novamente antes de chamar release.
Esta interface é bloqueante e deve ser chamada em uma thread que não seja de UI.
Assinatura do métodopublic synchronized int initialize(final INativeNuiCallback callback,
String parameters,
final Constants.LogLevel level,
final boolean save_log)
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| A implementação da interface de callback de eventos e dados. |
|
| 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 impressão de log do próprio SDK. |
|
| Se deve salvar logs locais. Se |
setParams
Define os parâmetros de efeito de conversa por voz no formato JSON. Chame antes de startDialog.
Assinatura do métodopublic synchronized int setParams(String params)
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
startDialog
Inicia uma conversa.
Assinatura do métodopublic synchronized int startDialog(VadMode vad_mode, String dialog_params)
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Modo VAD. Fixado como |
|
| Se o parâmetro |
stopDialog
Encerra a conversa. Depois que esta interface é chamada, o servidor retorna o resultado final da conversa e encerra a tarefa.
Assinatura do métodopublic synchronized int stopDialog();
cancelDialog
Encerra a conversa imediatamente. Depois que esta interface é chamada, a tarefa termina imediatamente, sem esperar que o servidor retorne o resultado final da conversa.
Assinatura do métodopublic synchronized int cancelDialog();
updateAction
Envia comandos de ação de conversa durante a interação, usados para atualizar o comportamento em tempo de execução, como o contexto da conversa.
Assinatura do métodopublic synchronized int updateAction(String 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 "action". |
|
| A instrução de tempo de execução específica. Atualmente,
|
|
| Atualiza a solicitação de chamada de função quando |
|
| O 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 é retornado. |
type |
| Obrigatório. O tipo do 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, com o 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 para as configurações de modalidade de saída do modelo. Valores válidos:
|
voice | string | Substitui a voz TTS da rodada atual. |
Exemplo:
{
"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"
}
}
updateAudio
Quando o parâmetro audio_update_manually é definido como "true", os dados de gravação não são mais preenchidos por meio de onNuiNeedAudioData, mas enviados ativamente por meio desta interface.
Assinatura do métodopublic synchronized int updateAudio(byte[ ] data, int len,
boolean 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. |
|
| Por favor, ignore isto. Não é necessário prestar atenção a este parâmetro. |
updateRefAudio
Quando o parâmetro audio_update_manually é definido como "true" e o recurso de cancelamento de eco AEC no dispositivo está habilitado, você deve usar esta interface para enviar os dados de áudio reproduzidos pelo player como sinal de referência.
Assinatura do métodopublic synchronized int updateRefAudio(byte[ ] data, int len,
boolean 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. |
|
| Por favor, ignore isto. Não é necessário prestar atenção a este parâmetro. |
release · Liberar os recursos do SDK
Libera todos os recursos internos do SDK. Depois que este método é chamado, a instância do SDK fica inutilizável. Para usá-la novamente, você deve chamar initialize novamente para reinicializá-la.
Assinatura do métodopublic synchronized int release();
GetVersion
Obtém as informações da versão atual do SDK.
Assinatura do métodopublic synchronized String GetVersion();
Descrição do valor retornado
As informações da versão atual do SDK.
INativeNuiCallback: Ouvir callbacks
onNuiEventCallback: Ouvir informações de eventos
Assinatura do métodovoid onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| O evento de callback. |
|
| Válido apenas quando o evento |
|
| Parâmetro reservado. |
|
| O resultado do reconhecimento de fala. |
|
| Recurso de despertar por voz. Não é necessário prestar atenção a este parâmetro. |
onNuiAudioStateChanged: Ouvir o estado do áudio
O SDK usa este callback para notificar quando iniciar ou parar a gravação.
Assinatura do métodovoid onNuiAudioStateChanged(AudioState state);
Descrição dos estados AudioState
| Estado | Descrição |
|---|---|
| A interação começa. Você pode abrir o dispositivo de gravação para gravar. |
| 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 os dados de áudio a serem processados
Depois que uma conversa começa, este callback é acionado continuamente, e você deve fornecer nele os dados de áudio a serem processados. Quando o parâmetro audio_update_manually é definido como "true", você pode ignorar este callback.
Assinatura do métodoint onNuiNeedAudioData(byte[ ] buffer, int len);
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Os dados de áudio a serem preenchidos. |
|
| O número de bytes dos dados de áudio preenchidos. |
O número real de bytes 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étodovoid onNuiAssistEventCallback_(int event, byte[ ] info, int info_len,
byte[ ] data);
Descrição dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Evento |
|
| Você não precisa prestar atenção a este parâmetro. |
|
| Você não precisa prestar atenção a este parâmetro. |
|
| Dados auxiliares, como o áudio TTS retornado pela IA. |
onNuiLogTrackCallback: Ouvir logs de rastreamento
Este callback é usado para receber logs detalhados de dentro do SDK, facilitando a solução de problemas e a depuração.
default void onNuiLogTrackCallback(Constants.LogLevel level, String log)
NuiEvent: 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. Não indica que o início de uma voz humana foi detectado. |
EVENT_VAD_END | O fim de uma voz humana é detectado. |
EVENT_ASR_PARTIAL_RESULT | Resultado intermediário do reconhecimento de fala. |
EVENT_ASR_ERROR | Ocorreu um erro durante a conversa por voz. |
EVENT_MIC_ERROR | Acionado porque nenhum dado de áudio foi recebido por 2 segundos consecutivos. |
EVENT_SENTENCE_END | O fim de uma frase é detectado e um resultado de reconhecimento completo é retornado. |
EVENT_TRANSCRIBER_COMPLETE | A conversa por voz termina. |
EVENT_AUDIO_TRANSCRIPTION | Evento incremental de legenda de texto no modo de áudio, retornando fragmentos 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 eventos não classificados, como o resultado retornado 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. |