QwenCloudBRASIL
Início›Biblioteca›Documentação
Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

Qwen-Omni SDK Java

Qwen-Omni-Realtime SDK Java

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

Pré-requisitos

Certifique-se de que a versão do Java SDK seja 2.22.15 ou posterior. Antes de começar, consulte Fluxo de interação multimodal em tempo real.

Para usar qwen3.8-omni-flash-realtime, defina o construtor da sessão model parâmetro para este nome de modelo. A voz padrão é Tina. Para obter exemplos de configuração de sessão do Java SDK e agregação de vídeo, consulte o guia em tempo real.

Parâmetros de solicitação

Configure os seguintes parâmetros de solicitação usando os métodos encadeados ou setters do OmniRealtimeParam objeto. Em seguida, passe este objeto e uma instância de retorno de chamada para o OmniRealtimeConversation construtor.

Parâmetro Tipo Descrição
modelo Corda O nome do Qwen-Omni modelo em tempo real. Consulte Lista de modelos.
url Corda O URL do terminal: wss://maas.qwencloudapi.com/api-ws/v1/realtime

Configure os seguintes parâmetros de solicitação usando os métodos encadeados ou setters do OmniRealtimeConfig objeto. Em seguida, passe este objeto como parâmetro para o updateSession interface.

Parâmetro Tipo Descrição
modalidades Lista\
As modalidades de saída do modelo. Definir como [OmniRealtimeModality.TEXT] apenas para saída de texto ou [OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO] para saída de áudio e texto.
voz Corda A voz usada para a saída de áudio do modelo. Aceita vozes predefinidas ou vozes clonadas (Qwen3.5-Omni-Realtime somente) criado por meio da API de clonagem de voz. Para obter uma lista de vozes predefinidas suportadas, consulte Lista de vozes. Voz padrão: Qwen3.5-Omni-Realtime: "Tina".
entradaAudioFormat OmniRealtimeAudioFormat O formato do áudio de entrada do usuário. Atualmente só suporta PCM_16000HZ_MONO_16BIT, que representa um fluxo de áudio PCM com uma taxa de amostragem de 16 kHz.
saídaAudioFormat OmniRealtimeAudioFormat O formato do áudio de saída do modelo. Atualmente só suporta PCM_24000HZ_MONO_16BIT, que representa um fluxo de áudio PCM com uma taxa de amostragem de 24 kHz.
instruções Corda Uma mensagem do sistema que define a meta ou a função do modelo. Exemplo: "Você é um agente de atendimento ao cliente de IA de um hotel cinco estrelas. Responda às perguntas dos clientes sobre tipos de quartos, instalações, preços e políticas de reserva."
suave_saída Booleano true: o modelo fornece respostas conversacionais. false: o modelo fornece respostas mais formais e escritas (o desempenho pode ser abaixo do ideal se o conteúdo for difícil de ler em voz alta). null (padrão): o modelo escolhe automaticamente entre estilos de resposta conversacional e formal. Defina usando o parameters método do OmniRealtimeConfig exemplo, o mesmo que instructions.
enableInputAudioTranscrição Booleano Especifica se o reconhecimento de fala deve ser ativado para o áudio de entrada.
EntradaÁudioTranscrição Corda O modelo de reconhecimento de fala usado para transcrever o áudio de entrada. Sempre qwen3-asr-flash-realtime. Este parâmetro não é configurável.
habilitarTurnDetecção Booleano Especifica se a detecção de atividade de voz (VAD) deve ser habilitada. Se desativado, você deverá enviar o áudio manualmente para acionar uma resposta do modelo.
turnDetectionType Corda O tipo de VAD. Valores válidos: "server_vad" (padrão): Detecta o final da fala do usuário com base nos recursos acústicos. "semantic_vad": detecta o final da fala do usuário com base na validade semântica. Este modo pode filtrar falas sem sentido, como backchannels e ruídos de fundo. Apoiado por qwen3.8-omni-flash-realtime e o qwen3.5-omni-realtime série.
turnDetectionThreshold Flutuar O limite do VAD. Aumente este valor em ambientes ruidosos e diminua-o em ambientes silenciosos. Um valor mais próximo de -1 aumenta a probabilidade de o ruído ser detectado como fala. Um valor mais próximo de 1 diminui a probabilidade. Valor padrão: 0,5. Faixa de valores: [-1,0, 1,0].
turnDetectionSilenceDurationMs Inteiro A duração do silêncio (em milissegundos) que indica o fim do discurso. O modelo aciona uma resposta após o término desse período. Valor padrão: 800. Faixa de valores: [200, 6000].
turnDetectionParam Mapa Adicional turn_detection parâmetros de configuração. Atualmente suporta idle_timeout_ms (Inteiro): o tempo limite de inatividade em milissegundos. Aplica-se apenas a qwen3.5-omni-plus-realtime e qwen3.5-omni-flash-realtime modelos em server_vad modo. Depois que o servidor terminar a reprodução de áudio e o usuário permanecer em silêncio além dessa duração (sem speech.started acionado), o modelo gera proativamente uma resposta para solicitar que o usuário continue a conversa. Intervalo válido: [5000, 30000]. Exemplo: turnDetectionParam(Map.of("idle_timeout_ms", 5000))
temperatura flutuar A temperatura de amostragem, que controla a diversidade do conteúdo gerado. Um valor mais alto resulta em conteúdo mais diversificado. Um valor mais baixo resulta em conteúdo mais determinístico. Faixa de valores: [0, 2). Porque ambos temperature e top_p controlar a diversidade de conteúdo, recomendamos definir apenas um deles. Padrões: qwen3.8-omni-flash-realtime: 0.6, qwen3.5-omni-realtime série: 0,7.
topo_p flutuar O limite de probabilidade para amostragem nuclear, que controla a diversidade do conteúdo gerado. Um valor mais alto resulta em conteúdo mais diversificado. Um valor mais baixo resulta em conteúdo mais determinístico. Faixa de valores: (0, 1,0]. Porque ambos temperature e top_p controlar a diversidade de conteúdo, recomendamos definir apenas um deles. Padrões: qwen3.8-omni-flash-realtime: 0.95, qwen3.5-omni-realtime série: 0,8.
topo_k inteiro O tamanho do token candidato definido para amostragem durante a geração. Um valor maior aumenta a aleatoriedade, enquanto um valor menor aumenta o determinismo. Se o valor for None ou superior a 100, top_k amostragem está desativada e somente top_p a amostragem entra em vigor. O valor deve ser 0 ou superior. Padrões: qwen3.8-omni-flash-realtime: 20, qwen3.5-omni-realtime série: 20.
máximo_tokens inteiro O número máximo de tokens que podem ser retornados na resposta. Este parâmetro não afeta o processo de geração do modelo. Se o número de tokens gerados pelo modelo exceder max_tokens, o conteúdo retornado será truncado. Para qwen3.8-omni-flash-realtime, o intervalo válido é [1, 65536]. Para outros modelos, os valores padrão e máximo são o comprimento máximo de saída do modelo. Usar max_tokens em cenários em que você precisa limitar o comprimento da saída, controlar custos ou reduzir a latência de resposta.
repetição_penalidade flutuar Controla a penalidade de repetição para sequências consecutivas durante a geração do modelo. Um valor mais alto reduz a repetição. Um valor de 1,0 significa que nenhuma penalidade é aplicada. qwen3.8-omni-flash-realtime também aceita 0. Para outros modelos, o valor deve ser maior que 0. Padrões: qwen3.8-omni-flash-realtime: 0, qwen3.5-omni-realtime série: 1.0.
presença_penalidade flutuar Controla a probabilidade de tokens repetidos no conteúdo gerado. Faixa de valores: [-2,0, 2,0]. Valores positivos reduzem a repetição, enquanto valores negativos a aumentam. Um valor mais alto é adequado para escrita criativa ou brainstorming. Um valor mais baixo é adequado para documentos técnicos ou redação formal. Padrões: qwen3.8-omni-flash-realtime: 1, qwen3.5-omni-realtime série: 1,5.
semente inteiro Definir o parâmetro inicial torna a saída do modelo mais determinística. Se você passar o mesmo valor inicial em cada chamada de modelo e manter os outros parâmetros inalterados, o modelo retornará o mesmo resultado sempre que possível. Faixa de valores: 0 a 2^31-1. Valor padrão: -1.
ferramentas Lista\

| Aplica-se a Qwen3.8-Omni-Flash-Realtime e Qwen3.5-Omni-Realtime modelos. Definições de ferramentas. Quando fornecido, o modelo pode chamar ferramentas externas para responder às perguntas do usuário. Para Chamada de Função, o modelo não gera áudio e apenas retorna os parâmetros de chamada da ferramenta. Qwen3.8-Omni-Flash-Realtime suporta chamadas de função e ferramentas MCP na mesma sessão. Consulte eventos do cliente para configuração do MCP e limites de chamadas do MCP para cotas. tools e enable_search são mutuamente exclusivos, incluindo ferramentas MCP. Os campos a seguir descrevem ferramentas de chamada de função. Cada ferramenta é um mapa contendo: type (String, obrigatório): fixado em "function"; function (Mapa, obrigatório): contém name (String, obrigatório, por ex. get_current_weather), description (String, opcional, usado pelo modelo para decidir se deve chamar a ferramenta), e parameters (Mapa, opcional, contém type fixado em "object", properties descrevendo o tipo e a descrição de cada parâmetro de entrada, e required listando os parâmetros necessários). | | ativar_pesquisar | Booleano | Se deve ativar a pesquisa na web. Quando ativado, o modelo determina de forma autônoma se deve pesquisar na web para responder às perguntas dos usuários. Padrão: false. Aplica-se a Qwen3.8-Omni-Flash-Realtime e Qwen3.5-Omni-Realtime modelos. tools e enable_search são incompatíveis. Você não pode ativá-los ao mesmo tempo. | | pesquisa_opções | Objeto | Opções de pesquisa na web. Só entra em vigor quando enable_search está habilitado. Contém: enable_source (Booleano): definido como true para retornar fontes de resultados de pesquisa. |

Defina esses parâmetros (junto com instructions, tools, enable_searche search_options) usando o parameters método do OmniRealtimeConfig exemplo:

conversation.updateSession(OmniRealtimeConfig.builder()
  .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
  .voice("Cherry")
  .enableTurnDetection(true)
  .enableInputAudioTranscription(true)
  .parameters(Map.of(
    "instructions", "You are a helpful assistant."))
  .build()
);

Interfaces principais

Classe OmniRealtimeConversation

Importe o OmniRealtimeConversation classe usando import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;.

Construtor

public OmniRealtimeConversation(OmniRealtimeParam param, OmniRealtimeCallback callback)

Cria um OmniRealtimeConversation instância.

Parâmetros:

Parâmetro Tipo Descrição
parâmetro OmniRealtimeParam Os parâmetros de configuração da conversa, incluindo modelo, URL e chave de API.
retorno de chamada OmniRealtimeCallback A instância de retorno de chamada que manipula eventos do lado do servidor. Consulte Interface de retorno de chamada.

conectar

public void connect() throws NoApiKeyException, InterruptedException

Cria uma conexão com o servidor.

Eventos de resposta do servidor: session.created (Sessão criada), session.updated (Configuração da sessão atualizada).

atualizaçãoSessão

public void updateSession(OmniRealtimeConfig config)

Atualiza a configuração padrão da sessão atual. Para configurações de parâmetros, consulte Solicitar parâmetros seção.

Ao estabelecer uma conexão, o servidor retorna as configurações padrão de entrada e saída da sessão. Para atualizar a configuração de sessão padrão, recomendamos chamar esse método imediatamente após o estabelecimento da conexão.

Depois de receber o session.update evento, o servidor valida os parâmetros. Se os parâmetros forem inválidos, um erro será retornado. Caso contrário, a configuração da sessão do lado do servidor será atualizada.

Eventos de resposta do servidor: session.updated (Configuração da sessão atualizada).

anexarÁudio

public void appendAudio(String audioBase64)

Acrescenta dados de áudio codificados em Base64 ao buffer de áudio de entrada na nuvem (armazenamento temporário para gravação de dados antes do envio).

Eventos de resposta do servidor: Nenhum.

anexarVídeo

public void appendVideo(String videoBase64)

Adiciona dados de imagem codificados em Base64 ao buffer de vídeo na nuvem (imagens locais ou capturas de fluxo de vídeo em tempo real).

Limites de entrada de imagem:

Eventos de resposta do servidor: Nenhum.

clearAppendedAudio

public void clearAppendedAudio()

Limpa o áudio no buffer de nuvem atual.

Eventos de resposta do servidor: input_audio_buffer.cleared (O áudio recebido pelo servidor é apagado).

confirmar

public void commit()

Envia áudio e vídeo previamente adicionados ao buffer da nuvem por meio de acréscimo. Retorna um erro se o buffer de áudio de entrada estiver vazio.

Eventos de resposta do servidor: input_audio_buffer.committed (O servidor recebeu o áudio enviado).

criarResposta

public void createResponse(String instructions, List<OmniRealtimeModality> modalities)

Instrui o servidor a criar uma resposta de modelo. Quando a sessão é configurada com turn_detection ativado, o servidor cria automaticamente uma resposta de modelo.

Eventos de resposta do servidor: response.created, response.output_item.added, conversação.item.criado, response.content_part.added, response.audio_transcript.delta, response.audio.delta, response.audio_transcript.done, response.audio.done, response.content_part.done, response.output_item.done, resposta.concluído.

cancelarResposta

public void cancelResponse()

Cancela a resposta em andamento. Retorna um erro se não existir resposta para cancelar.

Eventos de resposta do servidor: Nenhum.

criarItem

public void createItem(JsonObject item)

Envia o conversation.item.create evento para o servidor. Em um cenário de chamada de ferramenta, este método é usado para enviar o resultado da execução da ferramenta de volta ao servidor.

O item parâmetro é um JsonObject e deve conter os seguintes campos:

Campo Tipo Descrição
tipo Corda Valor fixo: "function_call_output".
chamada_id Corda Corresponde ao call_id no response.function_call_arguments.done evento.
saída Corda Uma string que representa o resultado da execução da ferramenta.

Eventos de resposta do servidor: Nenhum.

fechar

public void close(int code, String reason)

Interrompe a tarefa e fecha a conexão WebSocket.

Parâmetros:

Parâmetro Tipo Descrição
código interno O código de status para fechar o WebSocket.
motivo Corda O motivo do fechamento do WebSocket.

Eventos de resposta do servidor: Nenhum.

getSessionId

public String getSessionId()

Obtém o ID da sessão da tarefa atual.

Eventos de resposta do servidor: Nenhum.

getResponseId

public String getResponseId()

Obtém o ID da resposta mais recente.

Eventos de resposta do servidor: Nenhum.

Interface de retorno de chamada (OmniRealtimeCallback)

O servidor usa retornos de chamada para retornar eventos e dados ao cliente. Implemente esses métodos de retorno de chamada para lidar com eventos e dados do lado do servidor.

Importe a interface usando import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;.

Método Parâmetro Valor de retorno Descrição
onOpen() Nenhum Nenhum Chamado imediatamente após uma conexão ser estabelecida com o servidor.
onEvent(JsonObject message) message: o evento de resposta do servidor. Nenhum Inclui respostas de chamadas de método e texto e áudio gerados por modelo. Consulte Eventos do servidor.
onClose(int code, String reason) code: o código de status para fechar o WebSocket. reason: o motivo do fechamento do WebSocket. Nenhum Chamado depois que a conexão com o servidor é encerrada.