Todos os produtos
Search
Central de documentação

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

Última atualização: Nov 19, 2026

Principais interfaces e parâmetros de solicitação do Qwen-Omni real-time com o DashScope Python 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 SDK deve ser 1.25.17 ou posterior. Antes de começar, consulte Real-time multimodal interaction flow.

Início rápido

Baixe o código de exemplo no GitHub. Há três métodos de chamada disponíveis:

  1. Exemplo de conversa por áudio: Captura entrada de áudio em tempo real do microfone, permite que o VAD mode detecte automaticamente o início e o fim da fala e suporta interrupção de voz.

    Defina o parâmetro enable_turn_detection como True.

    Recomendamos o uso de fones de ouvido para reprodução de áudio a fim de evitar que ecos acionem a interrupção de voz.

  2. Exemplo de conversa por áudio e vídeo: Captura entradas de áudio e vídeo em tempo real do microfone e da câmera, permite que o VAD mode detecte automaticamente o início e o fim da fala e suporta interrupção de voz.

    Defina o parâmetro enable_turn_detection como True.

    Recomendamos o uso de fones de ouvido para reprodução de áudio a fim de evitar que ecos acionem a interrupção de voz.

  3. Chamada local: Usa arquivos locais de áudio e imagem como entrada e habilita o Manual mode, permitindo controle manual do ritmo de envio.

    Defina o parâmetro enable_turn_detection como False.

Parâmetros da solicitação

Defina os seguintes parâmetros de solicitação no construtor (init) da classe OmniRealtimeConversation.

Parâmetro

Tipo

Descrição

model

str

Modelo Qwen-Omni a ser usado. Consulte Lista de modelos.

callback

OmniRealtimeCallback

Instância de callback que processa eventos do lado do servidor.

url

str

Endereço da chamada:

  • 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 Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para 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, encontrado na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.

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

ParâmetroTipoDescrição

output_modalities

list[MultiModality]

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

voice

str

Voz para a saída de áudio. Para vozes compatíveis, consulte Voice list.

Vozes padrão:

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

input_audio_format

AudioFormat

Formato do áudio de entrada do usuário. Atualmente, oferece suporte apenas a PCM_16000HZ_MONO_16BIT, que representa um fluxo de áudio PCM com taxa de amostragem de 16 kHz.

output_audio_format

AudioFormat

Formato do áudio de saída do modelo. Atualmente, oferece suporte apenas a PCM_24000HZ_MONO_16BIT, que representa um fluxo de áudio PCM com taxa de amostragem de 24 kHz.

smooth_output

bool

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

  • True: Retorna uma resposta em estilo de conversa.

  • False: Retorna uma resposta mais formal, em estilo escrito.

    No entanto, isso pode resultar em baixa qualidade se o conteúdo for difícil de ler em voz alta.

  • None: O modelo seleciona automaticamente um estilo de resposta conversacional ou formal.

instructions

str

Mensagem de sistema que define o objetivo ou a função do modelo.

Por exemplo: Você é um agente 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. Seja preciso e amigável. Responda sempre com uma atitude profissional e prestativa. Não forneça informações não verificadas ou fora do escopo de services do hotel.

enable_input_audio_transcription

bool

Ative o reconhecimento de fala para o áudio de entrada.

input_audio_transcription_model

str

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.

turn_detection_type

str

Tipo de Detecção de Atividade de Voz (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 sentido, como palavras de preenchimento e ruído de fundo. Compatível apenas com a série de modelos Qwen3.5-Omni-Realtime.

turn_detection_threshold

float

Limiar de detecção 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,2. Valores válidos: [-1,0, 1,0].

turn_detection_silence_duration_ms

int

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

turn_detection_param

dict

Parâmetros adicionais de configuração de turn_detection. Atualmente, oferece suporte a idle_timeout_ms (int): o 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 concluir 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: turn_detection_param={'idle_timeout_ms': 5000}

enable_search

bool

Este parâmetro tem efeito apenas ao usar a 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.

A chamada de ferramentas (tools) e a pesquisa na web (enable_search) são incompatíveis. Não é possível ativar ambas simultaneamente.

search_options

object

Opções de pesquisa na web. Tem efeito apenas quando enable_search está ativado.

Atualmente, é possível definir apenas enable_source (Boolean), que controla se as fontes dos resultados da pesquisa devem ser retornadas. Defina como true para ativar. Exemplo: search_options={'enable_source': True}.

tools

list[dict]

Este parâmetro tem efeito apenas ao usar a 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 dicionário contendo os seguintes campos:

  • type (string, obrigatório): Deve ser definido como "function".

  • function (dict, obrigatório): Definição da função da ferramenta. Contém os seguintes campos:

    • name (string, obrigatório): Nome personalizado da função da ferramenta. Recomendamos usar um nome idêntico ao 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 deve chamar a função.

    • parameters (dict, opcional): Descrições dos parâmetros de entrada. O modelo as utiliza para extrair parâmetros. Se a função da ferramenta não exigir parâmetros de entrada, não é necessário especificar este campo. Contém os seguintes campos:

      • type (string, obrigatório): Deve ser definido como "object".
      • properties (dict, 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 dicionário contendo o tipo de dados (type) e a descrição (description).
      • required (list, opcional): Especifique quais parâmetros de entrada são obrigatórios.

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 tanto temperature quanto top_p controlam a diversidade do conteúdo, recomendamos definir apenas um deles.

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

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 tanto temperature quanto 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
  • qwen3-omni-flash-realtime-2025-09-15: 1,0

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:

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

max_tokens

integer

Número máximo de tokens a serem retornados.

A configuração de max_tokens não afeta o processo de geração do LLM. Se o número de tokens gerados pelo modelo 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 o console do Model Studio para obter detalhes.

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

repetition_penalty

float

Controla 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

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:

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

seed

integer

Torna a geração mais determinística, garantindo resultados consistentes entre execuções.

Passar 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 from dashscope.audio.qwen_omni import OmniRealtimeConversation.

Assinatura do método

Evento de resposta do servidor (entregue via callback)

Descrição

def connect(self,) -> None

Server-side event

Sessão criada

session.updated

Configuração da sessão atualizada

Crie uma conexão com o servidor.

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

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 definições.

Quando o servidor recebe o evento session.update, ele valida os parâmetros. Parâmetros inválidos retornam um erro; caso contrário, o servidor atualiza a configuração da sessão.

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

None

Adiciona áudio codificado em Base64 ao buffer de entrada na cloud. O buffer é um armazenamento temporário que pode ser gravado e confirmado posteriormente.

  • Se "turn_detection" estiver ativado, o buffer de áudio é usado para detecção de voz e o servidor decide quando confirmar.
  • Se "turn_detection" estiver desativado, o cliente envia até 15 MiB de áudio por evento. Transmitir blocos menores torna o VAD mais responsivo.
def append_video(self, video_b64: str) -> None

None

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.
def clear_appended_audio(self, ) -> None

input_audio_buffer.cleared

Exclui o áudio recebido pelo servidor

Exclui o áudio do buffer atual na cloud.

def commit(self, ) -> None

input_audio_buffer.committed

Servidor recebeu o áudio confirmado

Confirma áudio e vídeo do buffer na cloud. Retorna um 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 a transcrição de áudio estiver configurada para a sessão usando input_audio_transcription, o sistema transcreverá o áudio.
  2. Confirmar o buffer de áudio de entrada não cria uma resposta do modelo.
def create_response(self,
        instructions: str = None,
        output_modalities: list[MultiModality] = None) -> None

Server-side event

Servidor começa a gerar uma resposta

response.output_item.added

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

Server-side event

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.

Ao configurar uma sessão no modo "turn_detection", o servidor cria automaticamente uma resposta do modelo.

def cancel_response(self, ) -> None

None

Cancele a resposta em andamento. Se não houver resposta para cancelar, o servidor responde com um erro.

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

None

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

O parâmetro item é um dicionário que deve conter os seguintes campos:

  • type: Deve ser "function_call_output".
  • call_id: O call_id do evento response.function_call_arguments.done.
  • output: Uma string contendo o resultado da execução da ferramenta.
def close(self, ) -> None

None

Encerra a tarefa e fecha a conexão.

def get_session_id(self) -> str

None

Obtém o session_id da tarefa atual.

def get_last_response_id(self) -> str

None

Obtém o response_id da última resposta.

Interface de callback (OmniRealtimeCallback)

O servidor retorna eventos de resposta e dados via callbacks. Implemente métodos de callback para processar as respostas do servidor.

Importe com from dashscope.audio.qwen_omni import OmniRealtimeCallback.

Método

Parâmetros

Valor de retorno

Descrição

def on_open(self) -> None

None

None

Chamado após o estabelecimento da conexão com o servidor.

def on_event(self, message: str) -> None

message: Um evento de resposta do servidor.

None

Contém respostas de chamadas de interface e texto e áudio gerados pelo modelo. Consulte Server-side events.

def on_close(self, close_status_code, close_msg) -> None

close_status_code: Código de status para fechamento do WebSocket.

close_msg: Mensagem de fechamento do WebSocket.

None

Chamado após o servidor fechar a conexão.