Skip to main content
Multimodal em Tempo Real

Python SDK

Principais interfaces e parâmetros de solicitação do Qwen-Omni real-time com o DashScope Python SDK.

Pré-requisitos

A versão do SDK deve ser 1.25.17 ou posterior. Antes de começar, consulte Real-time multimodal interaction flow.

Primeiros passos

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

O 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_modalitieslist[MultiModality]Modalidade de saída do modelo. Defina como [MultiModality.TEXT] para apenas texto ou [MultiModality.TEXT, MultiModality.AUDIO] para áudio e texto simultaneamente.
voicestrVoz para a saída de áudio. Para vozes compatíveis, consulte Voice list.Vozes padrão:
  • Série de modelos Qwen3.5-Omni: "Tina"
  • Série de modelos Qwen3-Omni-Flash-Realtime: "Cherry"
  • Série de modelos Qwen-Omni-Turbo-Realtime: "Chelsie"
input_audio_formatAudioFormatFormato 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_formatAudioFormatFormato 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_outputboolParâmetro compatível apenas com a série Qwen3-Omni-Flash-Realtime.
  • 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.
instructionsstrMensagem 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_transcriptionboolAtive o reconhecimento de fala para o áudio de entrada.
input_audio_transcription_modelstrModelo 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_typestrTipo 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_thresholdfloatLimiar 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_msintDuraçã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_paramdictParâ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_searchboolEste 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_optionsobjectOpçõ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}.
toolslist[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.
temperaturefloatTemperatura 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
  • Série de modelos qwen3-omni-flash-realtime: 0,9
  • Série de modelos qwen-omni-turbo-realtime: 1,0
Modelos qwen-omni-turbo não suportam modificação.
top_pfloatLimiar 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
  • Série de modelos qwen3-omni-flash-realtime: 1,0
  • Série de modelos qwen-omni-turbo-realtime: 0,01
Modelos qwen-omni-turbo não suportam modificação.
top_kintegerTamanho 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
  • Série de modelos qwen3-omni-flash-realtime: 50
  • Série de modelos qwen-omni-turbo-realtime: 20
Modelos qwen-omni-turbo não suportam modificação.
max_tokensintegerNú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.
Modelos qwen-omni-turbo não suportam modificação.
repetition_penaltyfloatControla 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
Modelos qwen-omni-turbo não suportam modificação.
presence_penaltyfloatControla 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.
Modelos qwen-omni-turbo não suportam modificação.
seedintegerTorna 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.
Modelos qwen-omni-turbo não suportam modificação.

Interfaces principais

Classe OmniRealtimeConversation

Importe com from dashscope.audio.qwen_omni import OmniRealtimeConversation.
Assinatura do métodoEvento 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
NoneAdiciona á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
NoneAdiciona 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
NoneCancele a resposta em andamento. Se não houver resposta para cancelar, o servidor responde com um erro.
def create_item(self, item: dict) -> None
NoneEnvia 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
NoneEncerra a tarefa e fecha a conexão.
def get_session_id(self) -> str
NoneObtém o session_id da tarefa atual.
def get_last_response_id(self) -> str
NoneObté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étodoParâmetrosValor de retornoDescrição
def on_open(self) -> None
NoneNoneChamado após o estabelecimento da conexão com o servidor.
def on_event(self, message: str) -> None
message: Um evento de resposta do servidor.NoneConté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.NoneChamado após o servidor fechar a conexão.

Perguntas frequentes

P: Como alinhar áudio e imagens de entrada?

O modelo em tempo real Qwen-Omni usa o fluxo de áudio como linha do tempo de entrada. As imagens são inseridas no fluxo de áudio com base no momento em que são enviadas. É possível adicionar imagens em qualquer ponto da linha do tempo do áudio. Em cenários de interação em tempo real, você pode ativar ou desativar a entrada de vídeo a qualquer momento.

P: Qual é a frequência recomendada para entrada de imagens e áudio?

Em cenários de interação em tempo real, recomendamos enviar imagens com taxa de quadros de 1 ou 2 fps e enviar áudio em pacotes de 100 ms.

P: Quais são as diferenças entre os dois modos da chave turn_detection?

Quando turn_detection está ativado, ele suporta dois modos: server_vad e semantic_vad:
  • Ativar "turn_detection":
    • Estado de entrada: O VAD baseado em cloud detecta o fim de uma frase no áudio de entrada e aciona imediatamente a inferência do Qwen-Omni para retornar o texto e a fala de resposta.
    • Estado de resposta: Neste estado, você continua enviando entradas de áudio e vídeo sem interrupção enquanto o modelo responde. Após a conclusão da resposta, o estado retorna ao estado de entrada para aguardar a próxima entrada de fala.
    • Interrupção: Se o usuário começar a falar enquanto o modelo responde, uma interrupção é acionada. O service interrompe imediatamente a resposta atual e muda para o estado de entrada.
  • Desativar "turn_detection":
    • Você deve determinar manualmente o fim de uma rodada de entrada de áudio e vídeo e acionar a inferência do Qwen-Omni para obter uma resposta usando commit e create_response.
    • Enquanto o modelo responde, você deve parar de enviar entradas de áudio e vídeo. Só é possível retomar a entrada para a próxima rodada após o modelo terminar de responder.
    • Use o método cancel_response para interromper a resposta do modelo.
Note que, mesmo com turn_detection ativado, ainda é possível acionar ativamente uma resposta usando commit e create_response, e interrompê-la ativamente usando cancel_response.

P: Por que preciso selecionar outro modelo para input_audio_transcription?

O Qwen-Omni em tempo real é um modelo multimodal ponta a ponta. Sua saída de texto é uma resposta à entrada, não uma transcrição direta do áudio de entrada. Um modelo ASR separado é necessário para transcrição. Atualmente, o modelo é determinado pela configuração integrada e não é configurável.
Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais