Skip to main content
Multimodal em Tempo Real

Java SDK

Principais interfaces e parâmetros de solicitação do DashScope Java SDK para o Qwen-Omni real-time .

Pré-requisitos

A versão do Java SDK deve ser v2.22.15 ou posterior. Antes de começar, consulte Real-time multimodal interaction flow.

Primeiros passos

Baixe o código de exemplo no GitHub. Há três métodos de chamada disponíveis:
  1. Exemplo de conversa por áudio: Captura áudio em tempo real do microfone, ative o Voice Activity Detection (VAD) mode para detectar automaticamente o início e o fim da fala e permite interrupção por voz.
    Defina o parâmetro enableTurnDetection como true .
    Use fones de ouvido para reprodução de áudio e evite que ecos acionem a interrupção de voz.
  2. Exemplo de conversa por áudio e vídeo: Captura áudio e vídeo em tempo real do microfone e da câmera, ative o VAD mode e permite interrupção por voz.
    Defina o parâmetro enableTurnDetection como true .
    Use fones de ouvido para reprodução de áudio e evite que ecos acionem a interrupção de voz.
  3. Chamada local: Usa arquivos locais de áudio e imagem como entrada e ative o Manual mode, permitindo controle manual do ritmo de envio.
    Defina o parâmetro enableTurnDetection como false .

Parâmetros de solicitação

Configure os parâmetros de solicitação a seguir com os métodos encadeados ou setters do objeto OmniRealtimeParam e passe-o ao construtor OmniRealtimeConversation.

Parâmetro

Tipo

Descrição

model

String

Modelo Qwen-Omni a ser usado. Consulte Model list.

url

String

URL do endpoint:

  • Região Singapore: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime

  • Região Beijing: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime

Substitua {WorkspaceId} pelo seu workspace ID real.

O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões china (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade nas solicitações de inferência. Recomendamos migrar para os novos domínios:
  • china (Beijing): de wss://dashscope.aliyuncs.com para wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de wss://dashscope-intl.aliyuncs.com para wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} é o ID do seu workspace, disponível na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.
Configure os parâmetros de solicitação a seguir com os métodos encadeados ou setters do objeto OmniRealtimeConfig e passe-o ao método updateSession.
ParâmetroTipoDescrição
modalitiesList<OmniRealtimeModality>Modalidade de saída do modelo. Defina como [OmniRealtimeModality.TEXT] para apenas texto ou [OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO] para áudio e texto simultaneamente.
voiceStringVoz da saída de áudio. Para vozes compatíveis, consulte Voice list.Voz padrão:
  • Série de modelos Qwen3,5-Omni: "Tina"
  • Série de modelos Qwen3-Omni-Flash-Realtime: "Cherry"
  • Série de modelos Qwen-Omni-Turbo-Realtime: "Chelsie"
inputAudioFormatOmniRealtimeAudioFormatFormato do áudio de entrada do usuário. Atualmente, há suporte apenas para PCM_16000HZ_MONO_16BIT, que representa um fluxo de áudio PCM com taxa de amostragem de 16 kHz.
outputAudioFormatOmniRealtimeAudioFormatFormato do áudio de saída do modelo. Atualmente, há suporte apenas para PCM_24000HZ_MONO_16BIT, que representa um fluxo de áudio PCM com taxa de amostragem de 24 kHz.
instructionsStringMensagem de sistema que define o objetivo ou a função do modelo.Exemplo: "Você é um agente de atendimento ao cliente de IA para um hotel cinco estrelas. Responda às perguntas dos clientes sobre tipos de quartos, instalações, preços e políticas de reserva com precisão e cordialidade. Sempre responda de forma profissional e prestativa. Não forneça informações não verificadas ou fora do escopo dos services do hotel."
Defina instructions pelo método parameters da instância OmniRealtimeConfig:
conversation.updateSession(OmniRealtimeConfig.builder()
            .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
            .voice("Tina")
            .enableTurnDetection(true)
            .enableInputAudioTranscription(true)
            .parameters(Map.of(
                    "instructions", "You are a personal assistant named Xiaoyun"
            ))
            .build()
    );
smooth_outputBooleanParâmetro compatível apenas com a série Qwen3-Omni-Flash-Realtime.
  • true: O modelo fornece respostas em tom de conversa.
  • false: O modelo fornece respostas mais formais, no estilo escrito.
    No entanto, o desempenho pode ser subótimo se o conteúdo for difícil de ler em voz alta.
  • null: Valor padrão. O modelo escolhe automaticamente entre estilos de resposta conversacionais e formais.
Defina smooth_output pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.
enableInputAudioTranscriptionBooleanAtive o reconhecimento de fala no áudio de entrada.
InputAudioTranscriptionStringModelo de reconhecimento de fala para transcrição do áudio de entrada. O valor é sempre qwen3-asr-flash-realtime. Este parâmetro não é configurável.
enableTurnDetectionBooleanAtive o VAD. Se desativado, envie o áudio manualmente para gerar uma resposta.
turnDetectionTypeStringTipo de VAD. Valores válidos:
  • server_vad (padrão): Detecta o fim da fala do usuário com base em características acústicas.
  • semantic_vad: Detecta o fim da fala do usuário com base na validade semântica. Este modo filtra falas sem significado, como confirmações verbais e ruídos de fundo. Opção compatível apenas com a série de modelos Qwen3,5-Omni-Realtime.
turnDetectionThresholdFloatLimiar de detecção do VAD. Aumente em ambientes ruidosos e diminua em ambientes silenciosos.
  • Quanto mais próximo o valor estiver de -1, maior a probabilidade de o ruído ser detectado como fala.
  • Quanto mais próximo o valor estiver de 1, menor a probabilidade de o ruído ser detectado como fala.
Padrão: 0,5. Valores válidos: [-1,0, 1,0].
turnDetectionSilenceDurationMsIntegerDuração do silêncio que indica o fim da fala. Se excedida, o modelo aciona uma resposta. Padrão: 800. Valores válidos: [200, 6000].
turnDetectionParamMapParâmetros adicionais de configuração de turn_detection. Atualmente, há suporte para idle_timeout_ms (Integer): tempo limite de ociosidade em milissegundos. Aplica-se apenas aos modelosqwen3.5-omni-plus-realtimeeqwen3.5-omni-flash-realtimeno modoserver_vad. Após o servidor terminar a reprodução de áudio e o usuário permanecer em silêncio além dessa duração (sem acionar speech.started), o modelo gera proativamente uma resposta para incentivar o usuário a continuar a conversa. Intervalo válido: [5000, 30000].Exemplo: turnDetectionParam(Map.of("idle_timeout_ms", 5000))
enable_searchBooleanParâmetro com efeito apenas na série de modelos Qwen3,5-Omni-Realtime.Ative a pesquisa na web. Padrão: false. Quando ativado, o modelo pesquisa na web para responder a perguntas em tempo real.
Defina os parâmetros enable_search e search_options pelo método parameters da instância OmniRealtimeConfig. O processo é igual ao de instructions.
A chamada de ferramentas (tools) e a pesquisa na web (enable_search) são incompatíveis e não podem ser ativadas simultaneamente.
search_optionsObjectConfigurações de opções de pesquisa na web. Este parâmetro só tem efeito após a ativação de enable_search. Defina enable_source (Boolean) como true para retornar uma lista de fontes dos resultados da pesquisa.
Defina search_options pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.
toolsList<Map<String, Object>>Parâmetro com efeito apenas na série de modelos Qwen3,5-Omni-Realtime.Definições de ferramentas. Quando fornecidas, o modelo chama ferramentas externas para responder às perguntas do usuário. Se uma ferramenta for chamada, o modelo não gera áudio e retorna apenas os parâmetros de chamada da ferramenta.Cada ferramenta é um Map com os seguintes campos:
  • type (String, obrigatório): Valor fixo em "function".
  • function (Map, obrigatório): Definição da função da ferramenta. Este campo contém os seguintes subcampos:
    • name (String, obrigatório): Nome personalizado para a função da ferramenta. Recomendamos usar o mesmo nome da função, como get_current_weather ou get_current_time.
    • description (String, opcional): Descrição da função da ferramenta. O modelo usa essa descrição para decidir se chama a função.
    • parameters (Map, opcional): Descrições dos parâmetros de entrada. O modelo os utiliza para extrair parâmetros. Se a função da ferramenta não exigir parâmetros de entrada, não especifique este campo. Ele contém os seguintes subcampos:
      • type (String, obrigatório): Valor fixo em "object".
      • properties (Map, opcional): Descreve o nome, o tipo de dados e a descrição de cada parâmetro de entrada. A chave é o nome do parâmetro e o valor é um Map com o tipo de dados (type) e a descrição (description).
      • required (List, opcional): Especifique quais parâmetros de entrada são obrigatórios.
Defina search_options pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.
temperatureFloatTemperatura de amostragem que controla a diversidade do conteúdo.Valores mais altos produzem conteúdo mais diversificado; valores mais baixos produzem conteúdo mais determinístico.Valores válidos: [0, 2).Como temperature e top_p controlam a diversidade do conteúdo, recomendamos definir apenas um deles.Valores padrão de temperature:
  • Série de modelos Qwen3,5-Omni-Realtime: 0,7
  • Série de modelos qwen3-omni-flash-realtime: 0,9
  • Série de modelos qwen-omni-turbo-realtime: 1,0
Os modelos qwen-omni-turbo não permitem modificação.
Defina o parâmetro temperature pelo método parameters da instância OmniRealtimeConfig, da mesma forma que define o parâmetro instructions.
top_pFloatLimiar de probabilidade para amostragem de núcleo que controla a diversidade do conteúdo.Valores mais altos produzem conteúdo mais diversificado; valores mais baixos produzem conteúdo mais determinístico.Valores válidos: (0, 1,0].Como temperature e top_p controlam a diversidade do conteúdo, recomendamos definir apenas um deles.Valores padrão de top_p:
  • Série de modelos Qwen3,5-Omni-Realtime: 0,8
  • Série de modelos qwen3-omni-flash-realtime: 1,0
  • Série de modelos qwen-omni-turbo-realtime: 0,01
Os modelos qwen-omni-turbo não permitem modificação.
Defina top_p pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.
top_kIntegerTamanho do conjunto de candidatos para amostragem. Por exemplo, 50 significa que apenas os 50 tokens com maior pontuação formam o conjunto de candidatos. Valores maiores aumentam a aleatoriedade; valores menores aumentam o determinismo. Defina como None ou um valor maior que 100 para desativar top_k e usar apenas top_p.O valor deve ser maior ou igual a 0.Valores padrão de top_k:
  • Série de modelos Qwen3,5-Omni-Realtime: 20
  • Série de modelos qwen3-omni-flash-realtime: 50
  • Série de modelos qwen-omni-turbo-realtime: 20
Os modelos qwen-omni-turbo não permitem modificação.
Defina top_k pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.
max_tokensIntegerNúmero máximo de tokens a retornar.
A configuração de max_tokens não afeta o processo de geração do modelo. Se o número de tokens gerados exceder max_tokens, o conteúdo retornado será truncado.
Os valores padrão e máximo correspondem ao comprimento máximo de saída do modelo. Consulte Model list para detalhes.Use max_tokens para limitar o comprimento da saída ao gerar resumos ou palavras-chave, controlar custos ou reduzir o tempo de resposta.
Os modelos qwen-omni-turbo não permitem modificação.
Defina max_tokens pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.
repetition_penaltyFloatControla a repetição nas sequências geradas. Valores mais altos reduzem a repetição. 1,0 significa nenhuma penalidade. Deve ser maior que 0.Valores padrão de repetition_penalty:
  • Série de modelos Qwen3,5-Omni-Realtime: 1,0
  • Outros modelos: 1,05
Os modelos qwen-omni-turbo não permitem modificação.
Defina repetition_penalty pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.
presence_penaltyFloatControla a repetição de conteúdo na saída do modelo.Valores válidos: [-2,0, 2,0]. Valores positivos reduzem a repetição; valores negativos a aumentam.Valores padrão de presence_penalty:
  • Série de modelos Qwen3,5-Omni-Realtime: 1,5
  • Outros modelos: 0,0
Cenários:Valores mais altos adequam-se a cenários que exigem diversidade ou criatividade, como escrita criativa ou brainstorming.Valores mais baixos adequam-se a cenários que exigem consistência ou precisão técnica, como documentos técnicos.
Os modelos qwen-omni-turbo não permitem modificação.
Defina presence_penalty pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.
seedIntegerTorna a geração mais determinística e garante resultados consistentes entre execuções.Usar a mesma seed com parâmetros idênticos produz o mesmo resultado sempre que possível.Valores válidos: 0 a 231−1. Valor padrão: -1.
Os modelos qwen-omni-turbo não permitem modificação.
Defina seed pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.

Interfaces principais

Classe OmniRealtimeConversation

Importe com import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;.
Assinatura do métodoEvento de resposta do servidor (enviado via callback)Descrição
public void connect() throws NoApiKeyException, InterruptedException
Server events
Sessão criada
session.updated
Configuração da sessão atualizada
Estabelece conexão com o servidor.
public void updateSession(OmniRealtimeConfig config)
session.updated
Configuração da sessão atualizada
Atualize a configuração da sessão. Para detalhes dos parâmetros, consulte Parâmetros de solicitação.Após a conexão, o servidor retorna configurações de sessão padrão. Chame este método imediatamente após conectar para atualizar as configurações.Ao receber o evento session.update, o servidor valida os parâmetros. Parâmetros inválidos retornam erro; caso contrário, o servidor atualiza a configuração da sessão.
public void appendAudio(String audioBase64)
NenhumAdiciona áudio codificado em Base64 ao buffer de entrada na cloud. O buffer é um armazenamento temporário gravável e confirmável posteriormente.
  • Se "turn_detection" estiver ativado, o buffer de áudio detecta fala e o servidor decide quando confirmar.
  • Se "turn_detection" estiver desativado, o cliente pode enviar até 15 MiB de áudio por evento. Transmitir blocos menores torna o VAD mais responsivo.
public void appendVideo(String videoBase64)
NenhumAdiciona dados de imagem codificados em Base64 ao buffer de vídeo na cloud. Aceita imagens locais ou capturas de fluxo de vídeo em tempo real.Limites de entrada de imagem:
  • O formato da imagem deve ser JPG ou JPEG. A resolução recomendada é 480p ou 720p, com máximo de 1080p.
  • Uma única imagem após codificação Base64 não deve exceder 256 KB. Recomendamos manter o tamanho da imagem bruta abaixo de 190 KB antes da codificação.
  • Os dados da imagem devem estar codificados em Base64.
  • Recomendamos enviar imagens ao servidor com frequência de 1 imagem por segundo.
public void clearAppendedAudio()
input_audio_buffer.cleared
Áudio recebido pelo servidor limpo
Limpa o áudio do buffer atual na cloud.
public void commit()
input_audio_buffer.committed
Servidor recebeu o áudio confirmado
Confirma áudio e vídeo do buffer na cloud. Retorna erro se o buffer estiver vazio.
  • Se "turn_detection" estiver ativado, o cliente não precisa enviar este evento. O servidor confirma automaticamente o buffer de áudio.
  • Se "turn_detection" estiver desativado, o cliente deve confirmar o buffer de áudio para criar um item de mensagem do usuário.
Nota:
  1. Se input_audio_transcription estiver configurado para a sessão, o sistema transcreve o áudio.
  2. Confirmar o buffer de áudio de entrada não gera resposta do modelo.
public void createResponse(String instructions, List<OmniRealtimeModality> modalities)
Server events
Servidor inicia geração de resposta
response.output_item.added
Novo conteúdo de saída disponível na resposta
Server events
Item de conversa criado
response.content_part.added
Novo conteúdo de saída adicionado ao item de mensagem do assistente
response.audio_transcript.delta
Texto transcrito gerado incrementalmente
response.audio.delta
Áudio gerado incrementalmente pelo modelo
response.audio_transcript.done
Transcrição de texto concluída
response.audio.done
Geração de áudio concluída
response.content_part.done
Streaming de conteúdo de texto ou áudio para a mensagem do assistente concluído
response.output_item.done
Streaming de todo o item de saída para a mensagem do assistente concluído
response.done
Resposta concluída
Instrui o servidor a crie uma resposta do modelo.Com a sessão configurada no modo "turn_detection", o servidor cria automaticamente uma resposta do modelo.
public void cancelResponse()
NenhumCancele a resposta em andamento. Se não houver resposta disponível para cancelar, o servidor retorna erro.
public void createItem(JsonObject item)
NenhumEnvia o evento conversation.item.create ao servidor. Em cenários de chamada de ferramenta, use este método para enviar o resultado da execução da ferramenta de volta ao servidor.O parâmetro item é um JsonObject e deve conter os seguintes campos:
  • type: Valor fixo em "function_call_output".
  • call_id: Corresponde ao call_id no evento response.function_call_arguments.done.
  • output: String que representa o resultado da execução da ferramenta.
public void close()
NenhumInterrompe a tarefa e fecha a conexão.
public String getSessionId()
NenhumRetorna o ID da sessão da tarefa atual.
public String getResponseId()
NenhumRetorna o ID da resposta mais recente.

Interface de callback (OmniRealtimeCallback)

O servidor retorna eventos de resposta e dados por meio de callbacks. Implemente métodos de callback para processar as respostas do servidor. Importe com import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;.
MétodoParâmetroValor de retornoDescrição
public void onOpen()
NenhumNenhumInvocado imediatamente após o estabelecimento da conexão com o servidor.
public abstract void onEvent(JsonObject message)
message: Evento de resposta do servidor.NenhumContém respostas de chamadas de interface, além de texto e áudio gerados pelo modelo. Consulte Server events.
public abstract void onClose(int code, String reason)
code: Código de status de fechamento do WebSocket.reason: Motivo do fechamento do WebSocket.NenhumInvocado após o fechamento da conexão com o servidor.

Perguntas frequentes

P: Como ocorre o alinhamento entre áudio de entrada e imagens?

O modelo em tempo real Qwen-Omni usa o fluxo de áudio como linha do tempo de entrada. As imagens são inseridas no fluxo de áudio conforme o momento de envio. É possível adicionar imagens em qualquer ponto da linha do tempo do áudio. Em cenários de interação em tempo real, ative ou desative a entrada de vídeo a qualquer momento.

P: Qual é a frequência recomendada para entrada de imagens e áudio?

Em cenários de interação em tempo real, recomendamos enviar imagens a uma taxa de quadros de 1 ou 2 fps e áudio em pacotes de 100 ms.

P: Quais são as diferenças entre os dois modos da chave turn_detection?

Com turn_detection ativado, há suporte para dois modos: server_vad e semantic_vad:
  • Ativar "turn_detection":
    • Estado de entrada: O VAD baseado em cloud detecta o fim de uma frase no áudio de entrada e aciona imediatamente a inferência do Qwen-Omni para retornar texto e fala de resposta.
    • Estado de resposta: Neste estado, continue enviando entrada de áudio e vídeo sem interrupção enquanto o modelo responde. Após a conclusão da resposta, o estado retorna ao estado de entrada para aguardar a próxima fala.
    • Interrupção: Se o usuário começar a falar durante a resposta do modelo, uma interrupção é acionada. O service interrompe imediatamente a resposta atual e muda para o estado de entrada.
  • Desativar "turn_detection":
    • Determine manualmente o fim de uma rodada de entrada de áudio e vídeo e acione a inferência do Qwen-Omni para obter resposta com commit e create_response.
    • Durante a resposta do modelo, pare de enviar entrada de áudio e vídeo. Retome a entrada para a próxima rodada apenas após o modelo terminar de responder.
    • Use o método cancel_response para interromper a resposta do modelo.
Mesmo com turn_detection ativado, ainda é possível acionar ativamente uma resposta com commit e create_response, além de interrompê-la com cancel_response.

P: Por que selecionar outro modelo para input_audio_transcription?

O Qwen-Omni em tempo real é um modelo multimodal ponta a ponta. Sua saída de texto é uma resposta à entrada, não uma transcrição direta do áudio de entrada. Um modelo ASR separado é necessário para transcrição. Atualmente, o modelo é definido pela configuração interna e não é configurável.
Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais