Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:SDK Java do Qwen-Omni-Realtime

Última atualização: Nov 20, 2026

Este artigo apresenta as principais APIs e os parâmetros de solicitação para chamar modelos Qwen-Omni em tempo real com o DashScope Java SDK.

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.

Pré-requisitos

A versão do Java SDK deve ser v2.22.15 ou posterior. Leia primeiro o fluxo de interação multimodal em tempo real.

Início rápido

Ao usar o qwen3.8-omni-flash-realtime, defina o parâmetro de construção da sessão model com esse nome de modelo; a voz padrão é Tina. Para exemplos de configuração de sessão e de parâmetros de agregação de vídeo do Java SDK, consulte o guia de invocação em tempo real.

Baixe o código de exemplo no GitHub. Fornecemos código de exemplo para três métodos de chamada:

  1. Exemplo de conversa por áudio: captura áudio em tempo real do microfone, ativa o modo VAD (detecção de atividade de voz) (detecta 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, ativa o modo VAD (detecta 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.

  3. Chamada local: usa arquivos locais de áudio e imagem como entrada e ativa o modo manual (controle manual do ritmo de envio).

    Defina o parâmetro enableTurnDetection como false .

Parâmetros da 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

O nome do modelo Qwen-Omni em tempo real. Consulte Modelos.

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.

ImportanteO Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapura. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade nas solicitações de inferência. Recomendamos migrar para os novos domínios:

  • Região China (Beijing): de wss://dashscope.aliyuncs.com para wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Região Singapura: 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 Detalhes do workspace no console do Alibaba Cloud Model Studio. O Qwen3.8-Omni-Flash-Realtime deve usar os domínios dedicados por workspace acima; modelos anteriores podem continuar usando os domínios originais.

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

modalities

List<OmniRealtimeModality>

Modalidade de saída do modelo. Defina como [OmniRealtimeModality.TEXT] para apenas texto ou [OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO] para áudio e texto simultaneamente.

voice

String

Voz do áudio gerado pelo modelo. Para vozes compatíveis, consulte a lista de vozes.

Voz padrão:

  • Série de modelos Qwen3,5-Omni: "Tina"
  • qwen3-omni-flash-realtime-2025-09-15: "Cherry"

inputAudioFormat

OmniRealtimeAudioFormat

Formato 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.

outputAudioFormat

OmniRealtimeAudioFormat

Formato 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. Não há suporte atualmente para taxas de amostragem de saída personalizadas.

instructions

String

Mensagem 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."

ObservaçãoDefina 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", "你是个人助理小云"
        ))
        .build()
);

smooth_output

Boolean

Parâmetro compatível apenas com qwen3-omni-flash-realtime-2025-09-15.

  • 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.

enableInputAudioTranscription

Boolean

Ative o reconhecimento de fala no áudio de entrada.

InputAudioTranscription

String

Modelo 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.

enableTurnDetection

Boolean

Ative o VAD. Se desativado, envie o áudio manualmente para gerar uma resposta.

turnDetectionType

String

Tipo 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 e filtra falas sem significado (como confirmações verbais e ruídos de fundo). Compatível com os modelos Qwen3,8-Omni-Flash-Realtime e a série Qwen3,5-Omni-Realtime.

turnDetectionThreshold

Float

Limiar 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].

turnDetectionSilenceDurationMs

Integer

Duraçã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].

turnDetectionParam

Map

Parâ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 com base no contexto atual. Intervalo válido: [5000, 30000].

Exemplo: turnDetectionParam(Map.of("idle_timeout_ms", 5000))

enable_search

Boolean

Aplica-se aos modelos Qwen3,8-Omni-Flash-Realtime e à série Qwen3,5-Omni-Realtime.

Ative a pesquisa na web. Defina como true para ativar; o padrão é false. Quando ativada, o modelo pode decidir autonomamente se realiza pesquisas para responder às perguntas imediatas do usuário.

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_options

Object

Configuraçõ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.

tools

List<Map<String, Object>>

Aplica-se aos modelos Qwen3,8-Omni-Flash-Realtime e à série Qwen3,5-Omni-Realtime.

A lista de definições de ferramentas. Quando ativadas, o modelo pode decidir autonomamente se chama ferramentas externas para responder às perguntas do usuário. Quando uma Function Calling é acionada, o modelo não gera áudio e retorna apenas os parâmetros de chamada da ferramenta.

O Qwen3,8-Omni-Flash-Realtime pode ser configurado com ferramentas Function Calling e MCP na mesma sessão. Para os campos de configuração do MCP, consulte Eventos do cliente; para os limites de chamada, consulte Limites de chamada do MCP. tools e enable_search não podem ser ativados ao mesmo tempo, e essa limitação também se aplica ao MCP.

Os campos a seguir descrevem ferramentas de Function Calling. Cada ferramenta é um Map que contém 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.

temperature

Float

Temperatura 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:

  • qwen3.8-omni-flash-realtime: 0,6
  • Série de modelos Qwen3,5-Omni-Realtime: 0,7
  • qwen3-omni-flash-realtime-2025-09-15: 0,9

Defina o parâmetro temperature pelo método parameters da instância OmniRealtimeConfig, da mesma forma que define o parâmetro instructions.

top_p

Float

Limiar 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:

  • qwen3.8-omni-flash-realtime: 0,95
  • Série de modelos Qwen3,5-Omni-Realtime: 0,8
  • qwen3-omni-flash-realtime-2025-09-15: 1,0

Defina top_p pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.

top_k

Integer

Tamanho 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:

  • qwen3.8-omni-flash-realtime: 20
  • Série de modelos Qwen3,5-Omni-Realtime: 20
  • qwen3-omni-flash-realtime-2025-09-15: 50

Defina top_k pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.

max_tokens

Integer

Nú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.

O qwen3.8-omni-flash-realtime aceita valores no intervalo [1, 65536]. Para outros modelos, o valor padrão e o valor máximo correspondem ao comprimento máximo de saída do modelo. Para o comprimento máximo de saída de cada modelo, consulte Modelos.

Use max_tokens para limitar o comprimento da saída ao gerar resumos ou palavras-chave, controlar custos ou reduzir o tempo de resposta.

Defina max_tokens pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.

repetition_penalty

Float

O grau de repetição em sequências consecutivas durante a geração do modelo. Aumentar repetition_penalty reduz a repetitividade da saída do modelo, e 1,0 significa nenhuma penalidade. O qwen3.8-omni-flash-realtime aceita o valor 0; outros modelos não têm intervalo de valores estrito, desde que o valor seja maior que 0.

Valores padrão de repetition_penalty:

  • qwen3.8-omni-flash-realtime: 0
  • Série de modelos Qwen3,5-Omni-Realtime: 1,0
  • Outros modelos: 1,05

Defina repetition_penalty pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.

presence_penalty

Float

Controla 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:

  • qwen3.8-omni-flash-realtime: 1
  • Série de modelos Qwen3,5-Omni-Realtime: 1,5
  • Outros modelos: 0,0

Cenário aplicável:

Um presence_penalty mais alto é adequado para cenários que exigem diversidade, diversão ou criatividade, como escrita criativa ou brainstorming.

Um presence_penalty mais baixo é adequado para cenários que exigem consistência ou terminologia profissional, como documentos técnicos ou outros documentos formais.

Defina presence_penalty pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.

seed

Integer

Torna 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.

Defina seed pelo método parameters da instância OmniRealtimeConfig. O uso é igual ao de instructions.

Referência da API

Classe OmniRealtimeConversation

Importe com import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;.

Assinatura do método

Evento de resposta do servidor (enviado via callback)

Descrição

public void connect() throws NoApiKeyException, InterruptedException

Eventos do servidor

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)

Nenhum

Adiciona á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)

Nenhum

Adiciona 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)

Eventos do servidor

Servidor inicia geração de resposta

response.output_item.added

Novo conteúdo de saída disponível na resposta

Eventos do servidor

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 criar uma resposta do modelo.

Com a sessão configurada no modo "turn_detection", o servidor cria automaticamente uma resposta do modelo.

public void cancelResponse()

Nenhum

Cancele a resposta em andamento. Se não houver resposta disponível para cancelar, o servidor retorna erro.

public void createItem(JsonObject item)

Nenhum

Envia o evento conversation.item.create ao servidor.

Ao retornar o resultado de uma ferramenta de Function Calling, item é um JsonObject que contém 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.

A aprovação do MCP também usa este evento, mas item.type é mcp_approval_response; para os campos, consulte Resposta de aprovação do MCP nos eventos do cliente.

public void close()

Nenhum

Interrompe a tarefa e fecha a conexão.

public String getSessionId()

Nenhum

Retorna o ID da sessão da tarefa atual.

public String getResponseId()

Nenhum

Retorna 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étodo

Parâmetro

Valor de retorno

Descrição

public void onOpen()

Nenhum

Nenhum

Invocado imediatamente após o estabelecimento da conexão com o servidor.

public abstract void onEvent(JsonObject message)

message: Evento de resposta do servidor.

Nenhum

Contém respostas de chamadas de interface, além de texto e áudio gerados pelo modelo. Consulte Eventos do servidor.

public abstract void onClose(int code, String reason)

code: Código de status de fechamento do WebSocket.

reason: Motivo do fechamento do WebSocket.

Nenhum

Invocado após o fechamento da conexão com o servidor.