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.
Início rápido
- Obtenha e configure 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. Obtenha o SDK AAR em
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 arquivos de cabeçalho. - Abra o projeto no Android Studio. O código de exemplo está em
DashQwenAudioChatActivity.java. 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 initialize para definir os parâmetros de conexão e controle, e use setParams para definir os parâmetros de conversa por voz. - Chame startDialog 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 updateAudio 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 stopDialog para parar a conversa e escute
EVENT_TRANSCRIBER_COMPLETEpara confirmar que ela terminou. - Quando o recurso de conversa não for mais necessário, chame 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 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 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 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. |
aec_params | object | Não | Configuração avançada de AEC no dispositivo. Este objeto entra em vigor apenas quando audio_update_manually é "true". |
aec_params.enable_aec | boolean | Não | Se deve habilitar o AEC no dispositivo. Se audio_update_manually for "true" e o SDK suportar AEC no dispositivo, o AEC é habilitado por padrão. |
aec_params.save_audio | boolean | Não | Se deve salvar o áudio processado pelo módulo AEC no dispositivo. Se save_wav for "true" e debug_path estiver definido, este recurso é habilitado por padrão e o áudio é salvo em debug_path. |
aec_params.enable_aec_data_callback | boolean | Não | Se deve retornar o áudio processado por AEC através de EVENT_AEC_DATA em onNuiAssistEventCallback. Padrão: false. |
vad_params | object | Não | Configuração avançada de VAD no dispositivo. Este objeto entra em vigor apenas quando audio_update_manually é "true". |
vad_params.enable_vad | boolean | Não | Se deve habilitar o VAD no dispositivo. Se audio_update_manually for "true" e o SDK suportar VAD no dispositivo, o VAD é habilitado por padrão. |
vad_params.save_audio | boolean | Não | Se deve salvar o áudio processado pelo módulo VAD no dispositivo. Se save_wav for "true" e debug_path estiver definido, este recurso é habilitado por padrão e o áudio é salvo em debug_path. |
Parâmetros de conversa de voz
Passe uma string JSON no argumento params de setParams.
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 | boolean | 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: true. Valores válidos: true e false. |
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
NativeNui
initialize
Inicializa uma instância do SDK de conversa por voz. O SDK é um singleton. Não o inicialize mais de uma vez antes de chamar release.
Este método é bloqueante, portanto, chame-o em uma thread que não seja de UI.
Assinatura do método
Parâmetro | Tipo | Descrição |
|---|---|---|
| A implementação da interface de callback de eventos e dados. | |
|
| Uma string JSON que contém os 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 dos próprios logs do SDK. |
|
| Se deve salvar logs locais. Se definido como |
setParams
Define os Parâmetros de conversa por voz no formato JSON. Chame este método antes de startDialog.
Assinatura do método
Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
startDialog
Inicia a conversa.
Assinatura do método
| Parâmetro | Tipo | Descrição |
|---|---|---|
vad_mode | VadMode | Modo VAD. Fixado como VadMode.TYPE_P2T. |
dialog_params | String | 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: |
stopDialog
Encerra a conversa. Depois que você chama este método, o servidor retorna o resultado final da conversa e encerra a tarefa.
Assinatura do método
cancelDialog
Encerra a conversa imediatamente. Depois que você chama este método, a tarefa termina de uma vez sem esperar que o servidor retorne o resultado final da conversa.
Assinatura do método
updateAction
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 | String | 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. |
updateAudio
Quando audio_update_manually está definido como "true", chame este método para enviar ativamente os dados de gravação em vez de fornecer os dados através de onNuiNeedAudioData.
Assinatura do método
Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Os dados de áudio a serem enviados. |
|
| O número de bytes de dados de áudio a serem enviados. |
|
| Ignore este parâmetro. |
updateRefAudio
Quando audio_update_manually está definido como "true" e o AEC no dispositivo está habilitado, chame este método para enviar o áudio reproduzido pelo player como o sinal de referência.
Assinatura do método
Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Os dados de áudio a serem enviados. |
|
| O número de bytes de dados de áudio a serem enviados. |
|
| Ignore este parâmetro. |
release
Libera todos os recursos internos do SDK. Depois que você chama este método, a instância do SDK fica indisponível. Para usá-la novamente, você deve reinicializá-la chamando initialize.
Assinatura do método
GetVersion
Obtém as informações da versão atual do SDK.
Assinatura do método
INativeNuiCallback: callbacks de listener
onNuiEventCallback: ouvir informações de eventos
Assinatura do método
Parâmetro | Tipo | Descrição |
|---|---|---|
| O evento de callback. | |
|
| Válido apenas quando o evento |
|
| Um parâmetro reservado. |
|
| O resultado do reconhecimento de fala. |
|
| O recurso de despertar por voz. Você não precisa usar este parâmetro. |
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
Estado | 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 preenchidos. |
|
| O número de bytes de dados de áudio a serem preenchidos. |
onNuiAssistEventCallback: receber eventos e dados auxiliares
Este callback recebe eventos auxiliares e dados relacionados do SDK.
Assinatura do método
Parâmetro | Tipo | Descrição |
|---|---|---|
|
| Um evento |
|
| Ignore este parâmetro. |
|
| Ignore este parâmetro. |
|
| Dados auxiliares, como áudio TTS retornado pelo modelo. |
onNuiLogTrackCallback: ouvir logs de rastreamento
Este callback recebe logs internos detalhados do SDK para ajudar na solução de problemas e depuração.
NuiEvent: 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. |