Skip to main content

SDK Android do Qwen-Audio-Realtime

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 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. Obtenha e configure 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. Obtenha o SDK AAR em app/libs e adicione-o às dependências do seu projeto. Para integração com Android C++, use android_libs e android_include no 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

  1. Inicialize o SDK.
  2. Defina os parâmetros para o seu caso de uso. Use o argumento parameters de initialize para definir os parâmetros de conexão e controle, e use setParams para definir os parâmetros de conversa por voz.
  3. Chame startDialog 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 updateAudio 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 stopDialog para parar 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 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.
{
    "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 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 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_paramsobjectNãoConfiguração avançada de AEC no dispositivo. Este objeto entra em vigor apenas quando audio_update_manually é "true".
aec_params.enable_aecbooleanNãoSe 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_audiobooleanNãoSe 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_callbackbooleanNãoSe deve retornar o áudio processado por AEC através de EVENT_AEC_DATA em onNuiAssistEventCallback. Padrão: false.
vad_paramsobjectNãoConfiguração avançada de VAD no dispositivo. Este objeto entra em vigor apenas quando audio_update_manually é "true".
vad_params.enable_vadbooleanNãoSe 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_audiobooleanNãoSe 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.
{
  "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_emotionbooleanNãoSe 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.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

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
public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)
Parâmetros

Parâmetro

Tipo

Descrição

callback

INativeNuiCallback

A implementação da interface de callback de eventos e dados.

parameters

String

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.

level

Constants.LogLevel

Controla o nível de impressão dos próprios logs do SDK.

save_log

boolean

Se deve salvar logs locais. Se definido como true, especifique o caminho através de debug_path nos Parâmetros de conexão e controle e, opcionalmente, defina o tamanho do arquivo através de max_log_file_size.

setParams

Define os Parâmetros de conversa por voz no formato JSON. Chame este método antes de startDialog. Assinatura do método
public synchronized int setParams(String params)
Parâmetros

Parâmetro

Tipo

Descrição

params

String

Parâmetros de conversa por voz.

startDialog

Inicia a conversa. Assinatura do método
public synchronized int startDialog(VadMode vad_mode, String dialog_params)
Parâmetros
ParâmetroTipoDescrição
vad_modeVadModeModo VAD. Fixado como VadMode.TYPE_P2T.
dialog_paramsStringSe 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-****"
}

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
public synchronized int stopDialog();

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
public synchronized int cancelDialog();

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
public synchronized int updateAction(String params);
Parâmetros
ParâmetroTipoDescrição
paramsStringUma 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"
  }
}

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
public synchronized int updateAudio(byte[] data, int len,
                                    boolean first_pack);
Parâmetros

Parâmetro

Tipo

Descrição

data

byte[]

Os dados de áudio a serem enviados.

len

int

O número de bytes de dados de áudio a serem enviados.

first_pack

boolean

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
public synchronized int updateRefAudio(byte[] data, int len,
                                       boolean first_pack);
Parâmetros

Parâmetro

Tipo

Descrição

data

byte[]

Os dados de áudio a serem enviados.

len

int

O número de bytes de dados de áudio a serem enviados.

first_pack

boolean

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
public synchronized int release();

GetVersion

Obtém as informações da versão atual do SDK. Assinatura do método
public synchronized String GetVersion();
Valor de retorno As informações da versão atual do SDK.

INativeNuiCallback: callbacks de listener

onNuiEventCallback: ouvir informações de eventos

Assinatura do método
void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);
Parâmetros

Parâmetro

Tipo

Descrição

event

NuiEvent

O evento de callback.

resultCode

int

Válido apenas quando o evento EVENT_ASR_ERROR ocorre.

arg2

int

Um parâmetro reservado.

asrResult

AsrResult

O resultado do reconhecimento de fala.

kwsResult

KwsResult

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
void onNuiAudioStateChanged(AudioState state);
Estados AudioState

Estado

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(byte[] buffer, int len);
Parâmetros

Parâmetro

Tipo

Descrição

buffer

byte[]

Os dados de áudio a serem preenchidos.

len

int

O número de bytes de dados de áudio a serem preenchidos.

Valor de retorno O número de bytes realmente preenchidos.

onNuiAssistEventCallback: receber eventos e dados auxiliares

Este callback recebe eventos auxiliares e dados relacionados do SDK. Assinatura do método
void onNuiAssistEventCallback_(int event, byte[] info, int info_len,
                               byte[] data);
Parâmetros

Parâmetro

Tipo

Descrição

event

int

Um evento NuiEvent.

info

String

Ignore este parâmetro.

info_len

int

Ignore este parâmetro.

data

byte[]

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.
default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

NuiEvent: 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.