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:
-
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_detectioncomo 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.
-
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_detectioncomo 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.
-
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_detectioncomo 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 |
| Instância de callback que processa eventos do lado do servidor. |
url | str | Endereço da chamada:
Substitua |
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.comparawss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: de
wss://dashscope-intl.aliyuncs.comparawss://{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âmetro | Tipo | Descriçã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:
|
input_audio_format | AudioFormat | Formato do áudio de entrada do usuário. Atualmente, oferece suporte apenas a |
output_audio_format | AudioFormat | Formato do áudio de saída do modelo. Atualmente, oferece suporte apenas a |
smooth_output | bool | Parâmetro compatível apenas com
|
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:
|
turn_detection_threshold | float | Limiar de detecção VAD. Aumente em ambientes ruidosos e diminua em ambientes silenciosos.
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 Exemplo: |
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:
|
search_options | object | Opções de pesquisa na web. Tem efeito apenas quando Atualmente, é possível definir apenas |
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:
|
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.
|
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:
|
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 serem retornados.
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:
|
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á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 |
|---|---|---|
|
| Crie uma 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 definições. Quando o servidor recebe o evento |
| 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.
|
| 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:
|
|
| Exclui o áudio do buffer atual na cloud. |
|
| Confirma áudio e vídeo do buffer na cloud. Retorna um erro se o buffer estiver vazio.
Nota:
|
|
response.audio_transcript.delta
response.audio_transcript.done
| 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. |
| None | Cancele a resposta em andamento. Se não houver resposta para cancelar, o servidor responde com um erro. |
| None | Envia um evento O parâmetro item é um dicionário que deve conter os seguintes campos:
|
| None | Encerra a tarefa e fecha a conexão. |
| None | Obtém o session_id da tarefa atual. |
| 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 |
|---|---|---|---|
| None | None | Chamado após o estabelecimento da conexão com o servidor. |
| 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. |
| 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. |