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 Python

Qwen-Omni-Realtime SDK Python

Este tópico descreve as principais interfaces e parâmetros de solicitação para o Qwen-Omni-Realtime SDK Python do DashScope.

Pré-requisitos

A versão 1.26.5+ do SDK é necessária. 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 Python SDK e agregação de vídeo, consulte o guia em tempo real.

Parâmetros de solicitação

Defina os seguintes parâmetros de solicitação usando o método construtor (__init__) do OmniRealtimeConversation aula.

Parâmetro Tipo Descrição
modelo O Qwen-Omni nome do modelo. Consulte Lista de modelos.
retorno de chamada OmniRealtimeCallback A instância do objeto de retorno de chamada que manipula eventos do lado do servidor.
url O endereço da chamada: wss://maas.qwencloudapi.com/api-ws/v1/realtime

Configure os seguintes parâmetros de solicitação usando o comando update_session método.

Parâmetro Tipo Descrição
saída_modalidades lista[MultiModalidade] Modalidade de saída do modelo. Definir como [MultiModality.TEXT] apenas para texto ou [MultiModality.TEXT, MultiModality.AUDIO] para ambos.
voz A voz para o áudio gerado pelo 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. Vozes padrão: Qwen3.5-Omni-Realtime: "Tina".
entrada_áudio_formato Formato de Áudio 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ída_áudio_formato Formato de Áudio 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.
suave_saída bool True: o modelo fornece uma resposta conversacional. False: o modelo fornece uma resposta mais formal e escrita (a qualidade pode ser inferior se o conteúdo for difícil de ler em voz alta). None (padrão): o modelo escolhe automaticamente entre estilos de resposta conversacional e formal.
instruções Uma mensagem do sistema que define o objetivo ou a função do modelo. Por exemplo: "Você é um agente 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."
ativar_entrada_áudio_transcrição bool Se o reconhecimento de fala deve ser ativado para áudio de entrada.
entrada_áudio_transcrição_modelo Modelo de reconhecimento de fala para transcrever áudio de entrada. Sempre qwen3-asr-flash-realtime. Este parâmetro não é configurável.
turno_detecção_tipo Tipo de detecção de atividade de voz (VAD) do lado do servidor. 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 palavras de preenchimento e ruído de fundo. Este modo é suportado por qwen3.8-omni-flash-realtime e o qwen3.5-omni-realtime série.
turno_detecção_limiar flutuar O limite de detecção de VAD. Aumente este valor em ambientes ruidosos e diminua-o em ambientes silenciosos. Quanto mais próximo o valor estiver de -1, maior será a probabilidade de o ruído ser detectado como fala. Quanto mais próximo o valor estiver de 1, menor será a probabilidade de o ruído ser detectado como fala. Valor padrão: 0,2. Valores válidos: [-1,0, 1,0].
turno_detecção_silêncio_duração_ms interno A duração do silêncio que indica o fim do discurso. Se esta duração for excedida, o modelo dispara uma resposta. Valor padrão: 800. Valores válidos: [200, 6000].
virar_detecção_param ditado Adicional turn_detection parâmetros de configuração. Atualmente suporta idle_timeout_ms (int): 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: turn_detection_param={'idle_timeout_ms': 5000}
temperatura flutuar A temperatura de amostragem controla a diversidade de conteúdo. Valores mais altos aumentam a diversidade e valores mais baixos aumentam o determinismo. Valores válidos: [0, 2). Porque ambos temperature e top_p controlar a diversidade de conteúdo, defina 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 de amostragem de núcleo controla a diversidade de conteúdo. Valores mais altos aumentam a diversidade e valores mais baixos aumentam o determinismo. Valores válidos: (0, 1,0]. Porque ambos temperature e top_p controlar a diversidade de conteúdo, defina 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 conjunto candidato para amostragem durante a geração. Um valor maior aumenta a aleatoriedade. Um valor menor aumenta o determinismo. Se definido para None ou um valor superior a 100, o top_k política não está habilitada e apenas o top_p política entra em vigor. O valor deve ser maior ou igual a 0. 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 a serem retornados para a solicitação atual. Este parâmetro não afeta a geração do modelo. Se a saída exceder max_tokens, o conteúdo truncado será retornado. 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. O max_tokens O parâmetro é adequado para cenários em que você precisa limitar a contagem de palavras, controlar custos ou reduzir o tempo de resposta.
repetição_penalidade flutuar O grau de repetição em sequências consecutivas durante a geração do modelo. Um valor mais alto reduz a repetição. Um valor de 1,0 significa nenhuma penalidade. 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 repetição do conteúdo que o modelo gera. Valores válidos: [-2,0, 2,0]. Um valor positivo reduz a repetição e um valor negativo aumenta a repetição. Um valor mais alto é adequado para escrita criativa ou brainstorming. Um valor mais baixo é adequado para documentos técnicos ou documentos formais. Padrões: qwen3.8-omni-flash-realtime: 1, qwen3.5-omni-realtime série: 1,5.
semente inteiro Torna a geração de modelos mais determinística, garantindo resultados consistentes em todas as execuções. Se você passar o mesmo valor inicial e manter os outros parâmetros inalterados, o modelo retornará o mesmo resultado tanto quanto possível. Valores válidos: 0 a 2^31-1. Valor padrão: -1.
ativar_pesquisar bool Aplica-se a qwen3.8-omni-flash-realtime e qwen3.5-omni-realtime modelos. Se deve ativar a pesquisa na web.
pesquisa_opções ditado Opções de pesquisa na web. Só entra em vigor quando enable_search está habilitado. Atualmente, você só pode definir enable_source (Booleano), que controla se as fontes de resultados de pesquisa devem ser retornadas. Definir como true para habilitar. Exemplo: search_options={'enable_source': True}.
ferramentas lista[dict] 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 dicionário com os seguintes campos: type (str, obrigatório): Deve ser definido como "function". function (dict, obrigatório): A definição da função da ferramenta, contendo name (str, obrigatório), description (str, opcional) e parameters (dict, opcional, formato JSON Schema com type, propertiese required campos).

Chamada de ferramenta (tools) e pesquisa na web (enable_search) são incompatíveis. Você não pode ativar os dois ao mesmo tempo.

Interfaces principais

Classe OmniRealtimeConversation

Importe o OmniRealtimeConversation classe usando a instrução from dashscope.audio.qwen_omni import OmniRealtimeConversation.

conectar

def connect(self) -> None

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ção_sessão

def update_session(self,
                   output_modalities: list[MultiModality],
                   voice: str,
                   input_audio_format: AudioFormat = AudioFormat.PCM_16000HZ_MONO_16BIT,
                   output_audio_format: AudioFormat = AudioFormat.PCM_24000HZ_MONO_16BIT,
                   enable_input_audio_transcription: bool = True,
                   input_audio_transcription_model: str = None,
                   enable_turn_detection: bool = True,
                   turn_detection_type: str = 'server_vad',
                   prefix_padding_ms: int = 300,
                   turn_detection_threshold: float = 0.2,
                   turn_detection_silence_duration_ms: int = 800,
                   turn_detection_param: dict = None,
                   **kwargs) -> None

Atualiza a configuração da sessão. Após estabelecer a conexão, o servidor retorna as configurações padrão. Chame esse método imediatamente para substituir os padrões. O servidor valida os parâmetros e retorna um erro se for inválido. Para configurações de parâmetros, consulte Solicitar parâmetros seção.

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

anexar_audio

def append_audio(self, audio_b64: str) -> None

Acrescenta áudio codificado em Base64 ao buffer de entrada da nuvem (armazenamento temporário para confirmação posterior).

Eventos de resposta do servidor: Nenhum.

anexar_video

def append_video(self, video_b64: str) -> None

Adiciona dados de imagem codificados em Base64 ao buffer de vídeo em nuvem (stream local ou em tempo real).

Os seguintes limites se aplicam à entrada de imagem:

Eventos de resposta do servidor: Nenhum.

limpar_appended_audio

def clear_appended_audio(self) -> None

Limpa o áudio do buffer da nuvem.

Eventos de resposta do servidor: input_audio_buffer.cleared (Limpa o áudio recebido pelo servidor).

confirmar

def commit(self) -> None

Confirma áudio e vídeo adicionados via append. Retorna um erro se o buffer estiver vazio.

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

criar_resposta

def create_response(self,
          instructions: str = None,
          output_modalities: list[MultiModality] = None) -> None

Instrui o servidor a criar uma resposta de modelo (automática quando turn_detection está habilitado).

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.

cancelar_resposta

def cancel_response(self) -> None

Cancela a resposta em andamento (retorna um erro se não existir).

Eventos de resposta do servidor: Nenhum.

criar_item

def create_item(self, item: dict) -> None

Envia um conversation.item.create evento para o 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 item parâmetro é um dicionário que deve conter os seguintes campos:

Eventos de resposta do servidor: Nenhum.

fechar

def close(self) -> None

Encerra a tarefa e fecha a conexão.

Eventos de resposta do servidor: Nenhum.

get_session_id

def get_session_id(self) -> str

Obtém o session_id da tarefa atual.

Eventos de resposta do servidor: Nenhum.

get_última_resposta_id

def get_last_response_id(self) -> str

Obtém o response_id da última resposta.

Eventos de resposta do servidor: Nenhum.

Interface de retorno de chamada (OmniRealtimeCallback)

O servidor retorna eventos e dados por meio de retornos de chamada. Implemente métodos de retorno de chamada para lidar com as respostas do servidor.

Importe a interface usando a instrução from dashscope.audio.qwen_omni import OmniRealtimeCallback.

Método Parâmetros Valor de retorno Descrição
on_open(self) Nenhum Nenhum Chamado imediatamente após a conexão ser estabelecida.
on_event(self, message: str) message: um evento de resposta do servidor. Nenhum Lida com respostas de chamadas de interface e texto/áudio gerado por modelo. Consulte Eventos do servidor.
on_close(self, close_status_code, close_msg) close_status_code: o código de status para fechar o WebSocket. close_msg: a mensagem de encerramento do WebSocket. Nenhum Chamado depois que a conexão é fechada.