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:
-
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.
-
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.
-
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:
Substitua |
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.comparawss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Região Singapura: de
wss://dashscope-intl.aliyuncs.comparawss://{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âmetro | Tipo | Descriçã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:
|
inputAudioFormat | OmniRealtimeAudioFormat | Formato do áudio de entrada do usuário. Atualmente, há suporte apenas para |
outputAudioFormat | OmniRealtimeAudioFormat | Formato do áudio de saída do modelo. Atualmente, há suporte apenas para |
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 |
smooth_output | Boolean | Parâmetro compatível apenas com
|
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:
|
turnDetectionThreshold | Float | Limiar de detecção do VAD. Aumente em ambientes ruidosos e diminua em ambientes silenciosos.
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 Exemplo: |
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
|
search_options | Object | Configurações de opções de pesquisa na web. Este parâmetro só tem efeito após a ativação de
|
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. Os campos a seguir descrevem ferramentas de Function Calling. Cada ferramenta é um Map que contém os seguintes campos:
|
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:
|
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:
|
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:
|
max_tokens | Integer | Número máximo de tokens a retornar.
O Use max_tokens para limitar o comprimento da saída ao gerar resumos ou palavras-chave, controlar custos ou reduzir o tempo de resposta.
|
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 Valores padrão de repetition_penalty:
|
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:
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.
|
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.
|
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 |
|---|---|---|
|
| Estabelece conexão com o servidor. |
|
| 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. |
| Nenhum | Adiciona áudio codificado em Base64 ao buffer de entrada na cloud. O buffer é um armazenamento temporário gravável e confirmável posteriormente.
|
| 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:
|
|
| Limpa o áudio do buffer atual na cloud. |
|
| Confirma áudio e vídeo do buffer na cloud. Retorna erro se o buffer estiver vazio.
|
|
response.audio_transcript.delta
response.audio_transcript.done
| 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. |
| Nenhum | Cancele a resposta em andamento. Se não houver resposta disponível para cancelar, o servidor retorna erro. |
| Nenhum | Envia o evento Ao retornar o resultado de uma ferramenta de Function Calling,
A aprovação do MCP também usa este evento, mas |
| Nenhum | Interrompe a tarefa e fecha a conexão. |
| Nenhum | Retorna o ID da sessão da tarefa atual. |
| 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 |
|---|---|---|---|
| Nenhum | Nenhum | Invocado imediatamente após o estabelecimento da conexão com o servidor. |
| 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. |
| 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. |