O Qwen-Audio é um modelo grande de ponta a ponta para interação de voz em tempo real. Oferece suporte a conversas por voz com baixa latência e é adequado para cenários como assistentes de voz, atendimento ao cliente inteligente e companheiros de IA.
Visão geral
Permite a conversão de áudio em tempo real em fala/texto, com suporte a entrada de áudio em streaming e saída de fala e texto em streaming.
Além do protocolo WebSocket, este modelo também oferece suporte ao acesso por meio dos protocolos AOQ e WebRTC. Se você está integrando no lado do cliente e prioriza latência estável, capacidade de interação em redes instáveis e supressão de ruído e cancelamento de eco full-duplex em tempo real, o AOQ é recomendado. Para comparação e seleção de protocolos, consulte a Referência de API.
- Oferece suporte a Function Calling para chamada de ferramentas; o modelo pode decidir de forma autônoma se chama ferramentas externas para obter informações
- Oferece suporte a pesquisa na web; o modelo pode decidir de forma autônoma se realiza uma busca com base em perguntas em tempo real e retorna as fontes dos resultados da pesquisa, e ela pode ser ativada junto com o Function Calling
- Oferece suporte ao gerenciamento de contexto de conversa (criar, consultar e excluir itens de conversa), permitindo injetar contexto histórico de forma flexível ou limpar itens de conversa irrelevantes
- Saída de fala altamente expressiva que ajusta dinamicamente o tom, o ritmo e a expressão emocional com base no contexto da conversa
- Oferece suporte a vozes do sistema e vozes de clonagem; você pode criar uma voz de IA dedicada por meio da clonagem de voz para a saída da conversa por voz
qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash.
- Oferece suporte a três modos de interação: VAD acústico (server_vad), turnos semânticos inteligentes (smart_turn e smart_turn_v2, sendo este último recomendado) e controle manual (push-to-talk)
- Os modos smart_turn / smart_turn_v2 combinam percepção acústica com compreensão semântica para determinar os limites dos turnos, de modo que sons de assentimento sem significado (como "uh" e "ah") não interrompem a conversa
- O aprimoramento de falante é suportado nos modos smart_turn / smart_turn_v2; depois que você fornece o áudio pré-gravado do usuário-alvo, o modelo consegue fixar com precisão no falante-alvo em conversas full-duplex, bloqueando efetivamente as vozes de outras pessoas e o ruído de fundo
Como funciona
O Qwen-Audio adota uma arquitetura orientada a eventos. O cliente e o servidor enviam e recebem dados simultaneamente por uma conexão persistente: o cliente envia continuamente o fluxo de áudio capturado pelo microfone e o servidor retorna respostas de fala e texto em tempo real. Toda a interação é orientada por eventos do cliente (como session.update e input_audio_buffer.append) e eventos do servidor (como response.audio.delta e response.done), sem polling.
Um ciclo de vida típico de conexão é: estabelecer uma conexão WebSocket → enviar session.update para configurar os parâmetros da sessão → enviar áudio e receber respostas continuamente → fechar a conexão ativamente.
Formatos de áudio
Direção | Formato | Especificações |
|---|---|---|
Entrada (cliente → servidor) | PCM | Taxa de amostragem de 16 kHz, profundidade de 16 bits, mono |
Saída (servidor → cliente) | PCM | Taxa de amostragem de 24 kHz, profundidade de 16 bits, mono |
Idiomas suportados
A conversa por voz em tempo real oferece suporte aos seguintes idiomas e dialetos chineses:
- Idiomas (
qwen-audio-3.1-realtime-plus,qwen-audio-3.1-realtime-flash): alemão (de), inglês (en), espanhol (es), francês (fr), indonésio (id), italiano (it), japonês (ja), coreano (ko), português (pt), russo (ru), chinês (zh), tailandês (th), vietnamita (vi), árabe (ar). - Idiomas (
qwen-audio-3.0-realtime-plus,qwen-audio-3.0-realtime-flash): alemão (de), inglês (en), espanhol (es), francês (fr), indonésio (id), italiano (it), japonês (ja), coreano (ko), português (pt), russo (ru), chinês (zh). - Chinês e dialetos: mandarim, cantonês, dialeto de Chongqing, mandarim do nordeste, dialeto de Gansu, dialeto de Guizhou, dialeto de Zhejiang, dialeto de Hebei, dialeto de Henan, dialeto de Hubei, dialeto de Hunan, dialeto de Jiangxi, dialeto de Ningbo, dialeto de Ningxia, dialeto de Qingdao, dialeto de Shaanxi, dialeto de Shanxi, dialeto de Shandong, dialeto de Xangai, dialeto de Sichuan, dialeto de Yunnan.
qwen-audio-3.1-realtime-plus ou qwen-audio-3.1-realtime-flash, você pode usar session.input_audio_transcription.language e session.output_audio.language para especificar, respectivamente, o idioma de origem do áudio de entrada e o idioma de destino do áudio de saída. Para os códigos de idioma disponíveis dos dois parâmetros, consulte Eventos do cliente. Observe que session.output_audio.language se aplica à conversão de texto em fala (TTS): faz com que a saída de fala use o idioma de destino tanto quanto possível, mas não há garantia de que isso surta efeito, e isso não altera o idioma das respostas em texto do modelo.
Capacidade de contexto
O modelo mantém o contexto do histórico da conversa. Quando o número de turnos de diálogo ou a duração acumulada do áudio excede os limites a seguir, o histórico mais antigo é descartado automaticamente. A duração máxima refere-se ao limite superior da duração acumulada de áudio que pode ser retida no contexto do modelo.
Modelo | Máximo de turnos de áudio | Duração máxima de áudio |
|---|---|---|
qwen-audio-3.1-realtime-plus | 50 | 300 segundos |
qwen-audio-3.1-realtime-flash | 50 | 300 segundos |
qwen-audio-3.0-realtime-plus | 50 | 300 segundos |
qwen-audio-3.0-realtime-flash | 50 | 300 segundos |
max_history_turns controla o número de turnos históricos de perguntas e respostas referenciados durante a inferência do modelo, com valor padrão de 20 e intervalo de valores de 1-50. Para saber como ajustá-lo, consulte Controle de turnos do histórico.
Para recomendações gerais de seleção de modelos para modelos omnimodais, consulte Omnimodal.
Pré-requisitos
- Você obteve e configurou uma chave de API e a configurou como uma variável de ambiente.
- Se você se conectar por meio do protocolo AOQ, será necessário baixar e integrar o SDK do cliente AOQ. Para mais informações, consulte Visão geral do SDK do AOQ.
Início rápido
O exemplo básico de WebSocket a seguir usa qwen-audio-3.1-realtime-plus e define explicitamente a voz do sistema longanqian_v3.1. Ao migrar da versão 3.0 Plus, atualize o parâmetro de consulta model da URL e selecione uma voice compatível com o modelo conforme a Configuração de voz; o protocolo de eventos do WebSocket permanece inalterado.
Siga estas etapas para experimentar rapidamente conversas por voz em tempo real com o modelo Qwen-Audio.
- WebSocket nativo
realtime_quickstart.py:python realtime_quickstart.py e fale ao microfone para ter uma conversa em tempo real com o modelo. O servidor detecta automaticamente o início e o fim da fala e aciona as respostas.Exemplo completoO exemplo completo a seguir adiciona tratamento de interrupção de fala, supressão de eco e outros recursos sobre a conversa básica. Crie os dois arquivos a seguir (eles devem estar no mesmo diretório):B64PCMPlayer.py
B64PCMPlayer.py
realtime_demo.py
realtime_demo.py
websockets for inferior a 11, altere additional_headers no código para extra_headers ou faça a atualização: pip install --upgrade websockets.python realtime_demo.py e fale ao microfone para ter uma conversa em tempo real com o modelo. O sistema detecta automaticamente o início e o fim da fala e aciona as respostas.Configuração da sessão
Modos de interação
O Qwen-Audio oferece suporte a três modos de interação: server_vad (VAD acústico que detecta automaticamente o início e o fim da fala), smart_turn (turnos semânticos inteligentes, combinando sinais acústicos e semânticos; smart_turn_v2 é recomendado) e push-to-talk (controle manual no lado do cliente). Para descrições detalhadas de cada modo e sequências de interação de eventos (incluindo diagramas de sequência), consulte Modo de interação.
turn_detection só pode ser modificado antes do envio do primeiro áudio (no estado IDLE). Alternar o modo de interação depois que a sessão é estabelecida requer uma reconexão.turn_detection no evento session.update:
- server_vad:
- smart_turn / smart_turn_v2:
smart_turn_v2 (recomendado): baseia-se no smart_turn com compreensão aprimorada do contexto da conversa para interpretar melhor a intenção de interação em cenários com vários falantes. Ele reduz respostas incorretas e interrupções errôneas causadas pela fala de terceiros ou interjeições irrelevantes. Definir type como smart_turn ainda usa a detecção inteligente de turnos original.
- push-to-talk:
manual_realtime.py
manual_realtime.py
Instruções do sistema
Use o parâmetro instructions para definir a função do modelo, o estilo de resposta e as preferências comportamentais. Esse parâmetro é configurado em session.update e se aplica a toda a sessão.
- Defina claramente a função (por exemplo, "Você é um assistente de voz inteligente" ou "Você é um tutor de conversação em inglês"). Você pode adicionar detalhes de persona, como nome e gênero.
- Especifique um tom de conversa e um estilo de fraseado, enfatizando que um estilo conversacional não deve comprometer a integridade do conteúdo — detalhes, números e recomendações específicas devem ser incluídos, apenas expressos de forma leve e natural.
- Exija que o modelo considere totalmente todas as restrições no contexto da conversa (como orçamento, preferências, restrições e acordos anteriormente alcançados). Quando várias condições estiverem envolvidas, aborde-as uma a uma e não omita informações essenciais.
- Controle o formato de saída: a menos que o usuário solicite, não gere símbolos especiais como emojis ou formatação Markdown. Prefira texto simples para garantir uma narração TTS natural e fluida.
- Defina a estratégia de resposta: mantenha breves e naturais as conversas casuais do dia a dia e as saudações; para perguntas complexas envolvendo raciocínio e cálculo, múltiplas restrições, listas de recomendações ou conselhos de segurança, priorize respostas completas e corretas, garanta que as informações essenciais (como preços, locais e condições) estejam completas e evite preâmbulos longos ou retórica repetitiva.
- Defina uma estratégia de perguntas de acompanhamento: siga o princípio de "primeiro responder bem à pergunta atual do usuário e, em seguida, fazer naturalmente uma pergunta de acompanhamento no final para avançar o tópico". Faça apenas uma pergunta por vez e não faça perguntas de acompanhamento consecutivas nem confirmações repetidas.
- Daidai (companheira doce e descolada):
- Aleng (distante e de língua afiada):
- Mochen (composto e charmoso):
- Hannibal (elegante e incisivo):
- Heizi (amigo provocador do nordeste):
Configuração de voz
Use o parâmetro voice para definir a voz TTS das respostas do modelo. Tanto vozes do sistema quanto vozes de clonagem são suportadas. A voz padrão do 3.1 Plus/Flash é longanqian_v3.1 e a voz padrão do 3.0 Plus/Flash é longanqian.
Vozes do sistema: selecione um ID de voz com base no modelo.
| Modelo | ID de voz do sistema |
|---|---|
qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash | As vozes disponíveis incluem longanqian_v3.1, além de todas as vozes nas listas qwen-audio-3.1-tts-plus e qwen-audio-3.1-tts-flash. Você pode consultar os IDs das vozes e pré-visualizar as vozes nas listas. |
qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash | longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng |
target_model como qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus ou qwen-audio-3.0-realtime-flash ao criá-la) e, em seguida, preencha o voice_id retornado pela API no parâmetro voice.
Taxa de fala da saída de áudio
Use session.update para definir speech_rate no objeto session e controlar a taxa de fala da saída de áudio do modelo. O intervalo de valores é [0.5, 2.0] e o valor padrão é 1.0. Um valor menor significa uma taxa de fala mais lenta e um valor maior significa uma taxa de fala mais rápida. Isso se aplica a qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash. O exemplo a seguir define esse parâmetro como 1.2:
Modalidade de saída
Use o parâmetro modalities para controlar o tipo de conteúdo da saída do modelo:
["audio", "text"](padrão): gera tanto áudio quanto texto.["text"]: gera apenas texto, sem gerar áudio. Adequado para depuração, registro em log ou cenários que exigem apenas respostas em texto.
response.modalities de response.create.
Configuração de VAD
Configure os parâmetros de VAD em session.turn_detection. threshold se aplica a server_vad, smart_turn e smart_turn_v2. silence_duration_ms se aplica apenas a server_vad.
Parâmetros | Tipo | Descrição |
|---|---|---|
| float | Sensibilidade do VAD. Um valor menor torna o VAD mais sensível, mais propenso a reconhecer sons fracos (incluindo ruído de fundo) como fala; um valor maior o torna menos sensível, exigindo uma fala mais clara e alta para acionar. O intervalo de valores é [-1.0, 1.0] e o valor padrão é 0.5. |
| integer | A duração mínima de silêncio (em milissegundos) que deve ser mantida após o término da fala; quando o tempo limite é atingido, a resposta do modelo é acionada. Um valor menor leva a respostas mais rápidas, mas pode causar acionamentos falsos durante pausas breves. O intervalo de valores é [200, 6000] e o valor padrão é 800. Para cenários de conversa, recomenda-se 400-800. |
Controle de turnos do histórico
Esta seção se aplica a qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash.
Use o parâmetro max_history_turns para controlar o número de turnos de perguntas e respostas do histórico que o modelo referencia durante a inferência. Um valor maior permite que o modelo revise mais histórico da conversa para entender o contexto, mas aumenta o consumo de tokens e a latência de inferência.
max_history_turns é 1-50 e o valor padrão é 20.
Sugestões de otimização:
- Cenários de conversas curtas (como perguntas e respostas rápidas): defina um valor menor (como 5-10) para reduzir a latência.
- Cenários de conversas longas (como atendimento ao cliente com múltiplos turnos): defina um valor maior (como 30-50) para garantir que o modelo entenda todo o contexto.
Recursos avançados
Function Calling
O Qwen-Audio oferece suporte à invocação de ferramentas por Function Calling, permitindo que o modelo decida de forma autônoma se chama ferramentas externas com base no contexto da conversa.
1. Registrar ferramentas
Configure tools por meio de session.update:
response.function_call_arguments.done, o cliente executa a função da ferramenta e grava o resultado de volta por meio de conversation.item.create:
response.create para acionar o modelo a continuar gerando uma resposta com base no resultado da ferramenta:
function_call e também pode incluir mensagens regulares e chamadas de função. A parte do Function Call não é enviada ao TTS para reprodução.realtime_demo.py do Início rápido. Antes de executá-lo, certifique-se de que B64PCMPlayer.py esteja no mesmo diretório.
realtime_fc_demo.py
realtime_fc_demo.py
python realtime_fc_demo.py e fale ao microfone para experimentar uma conversa em tempo real com Function Calling. Por exemplo, pergunte "Como está o tempo em Hangzhou" ou "Quanto custa uma passagem de trem de Pequim para Xangai", e o modelo chamará automaticamente a função de ferramenta correspondente e responderá com base no resultado.
Pesquisa na web
Ao consultar informações em tempo real, como clima ou notícias, você pode habilitar a pesquisa na web para que o modelo recupere informações em tempo real antes de gerar uma resposta. A pesquisa na web está desativada por padrão; depois de habilitada, o modelo decide de forma autônoma se uma pesquisa é necessária, e ela não é acionada em todos os turnos da conversa.
A pesquisa na web e o Function Calling podem ser habilitados na mesma sessão, e isso se aplica a qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash.
agent. Para informações de cobrança, consulte Detalhes de cobrança.session.update para definir os seguintes parâmetros em session:
enable_search: defina comotruepara habilitar a pesquisa na web.search_options.enable_source: defina comotruepara retornar as fontes dos resultados da pesquisa.
tools ao objeto session acima. Para saber como definir ferramentas e preencher os resultados das chamadas de volta, consulte Function Calling.
Para detalhes dos parâmetros, consulte session.update.
2. Ler as fontes e o uso da pesquisa
As respostas do modelo ainda são recebidas por meio de eventos de texto e áudio. Após a execução de uma pesquisa, você pode ler o seguinte do objeto response do evento response.done:
search_info.search_results: a lista de fontes dos resultados da pesquisa, cada uma contendo o índice da fonteindex, o títulotitlee o linkurl.usage.plugins.search.count: o número de pesquisas, que não deve ser substituído pelo número de fontes.usage.plugins.search.strategy: a política de pesquisa, cujo valor éagent.
Gerenciamento de contexto de conversa
O Qwen-Audio oferece suporte ao gerenciamento de itens de conversa no contexto de conversa por meio de eventos do cliente, que podem ser usados para injetar contexto histórico, complementar informações de texto ou limpar itens de conversa irrelevantes.
-
Criar um item de conversa (
conversation.item.create): insere um item de conversa no contexto de conversa. Os seguintes três valores deitem.typesão suportados:message: uma mensagem de conversa regular. Você deve especificarrole(system,user,assistant) e o arraycontent; é adequado para injetar conversas históricas ou instruções do sistema.function_call: uma solicitação de chamada de função. Você deve especificarcall_id,nameearguments(uma string JSON). Geralmente é gerado pelo servidor, e o cliente também pode usá-lo para complementar registros de chamadas de função no contexto histórico.function_call_output: o resultado da execução da ferramenta. Você deve especificarcall_ideoutput(uma string JSON). Após receberfunction_call, o cliente executa a ferramenta e grava o resultado da execução de volta com este tipo.
previous_item_idespecifica após qual item de conversa existente o novo item de conversa será inserido, permitindo a inserção de conteúdo em qualquer posição do histórico da conversa. Se esse parâmetro não for passado, o novo item de conversa será anexado ao final da conversa por padrão.- Inserir uma mensagem do usuário em uma posição especificada:
- Gravar de volta o resultado da execução do Function Calling:
item.id especificado por conversation.item.create já existir na conversa, um erro será retornado.- Recuperar um item de conversa (
conversation.item.retrieve): recupera um item de conversa armazenado no servidor. Para conteúdo do tipo áudio, apenas o texto transcrito é retornado, não os dados brutos de áudio.
- Excluir um item de conversa (
conversation.item.delete): exclui um item especificado do contexto de conversa.
Palavras-chave instantâneas
Nomes, nomes de produtos ou termos do setor são facilmente reconhecidos como homófonos. Depois que as palavras-chave instantâneas são configuradas, o modelo prioriza o reconhecimento dessas palavras ao transcrever o áudio de entrada. Por exemplo, o nome do projeto no mesmo trecho de áudio foi transcrito como "projeto 7yuan" antes de as palavras-chave serem configuradas. Depois que "Qiyuan" é definido como palavra-chave, o resultado da transcrição é "projeto Qiyuan".
Os modelos Plus e Flash do Qwen-Audio-Realtime 3.0 e 3.1 oferecem suporte a palavras-chave instantâneas, aplicáveis ao acesso por WebSocket, WebRTC e AOQ nas regiões de Pequim e Singapura. Antes de enviar o áudio, use o evento session.update a seguir para configurar as palavras-chave.
session.updated. Obtenha a transcrição final do campo transcript do evento conversation.item.input_audio_transcription.completed. Você pode enviar session.update novamente durante a sessão para passar um novo vocabulário completo. Definir vocabulary como {} limpa as palavras-chave.
Transcrição de áudio ambiente
Apenas modos smart_turn / smart_turn_v2. Quando o VAD detecta atividade de voz, mas determina semanticamente que não é um turno válido (como ruído ou conteúdo sem significado, como "uh" ou "ah"), o servidor não aciona um turno de conversa; em vez disso, passa o resultado do reconhecimento ASR para o cliente por meio do evento ambient_audio_transcription. Esse resultado de transcrição não é gravado no contexto da conversa.
delta e completed. Os desenvolvedores podem usar esse evento para implementar recursos como monitoramento de áudio ambiente e percepção do cenário de conversa.
Aprimoramento de falante
Apenas modos smart_turn / smart_turn_v2. Passe a URL do áudio pré-gravado pelo usuário-alvo em session.update, e o modelo fixará com precisão nesse falante na conversa duplex, ignorando efetivamente outras vozes e o ruído de fundo, permitindo uma interação duplex fluida em cenários abertos.
Configuração: passe URLs acessíveis publicamente do áudio de impressão vocal em turn_detection.voiceprint_audio_urls do primeiro session.update.
- São suportadas no máximo 5 URLs, e o formato do áudio deve ser PCM ou WAV de 16 kHz.
- Esse parâmetro surte efeito apenas no primeiro
session.update; entradas subsequentes são ignoradas.
voiceprint_audio_list.in_progress: o registro foi iniciado, enviado antes do retorno desession.updated, carregando umitem_idque identifica essa tarefa.voiceprint_audio_list.completed: registro bem-sucedido, com oitem_idcorrespondente ao dein_progress.voiceprint_audio_list.failed: falha no registro, com um camporeasonexplicando a causa (por exemplo, a URL do áudio está inacessível). Uma falha no registro não bloqueia a conversa normal.
Indo para produção
Configurar políticas de tolerância a falhas
- Reconexão do cliente: o cliente deve implementar um mecanismo de reconexão automática para lidar com instabilidades de rede. Recomendamos definir um sinal de reconexão no callback
on_errore tentar novamente com uma política de backoff exponencial (por exemplo, aguardar 1s → 2s → 4s). - Classificação e tratamento de erros: erros do cliente (
invalid_request_error) não interrompem a conexão; basta registrá-los em log ou ajustar os parâmetros. Erros do servidor (server_error) encerram a conexão e exigem reconexão. - Tratamento de barge-in: nos modos server_vad / smart_turn / smart_turn_v2, a nova fala do usuário interrompe automaticamente a resposta em andamento do modelo (
response.doneretornastatus=cancelled). O cliente deve parar imediatamente de reproduzir o áudio em buffer ao receberinput_audio_buffer.speech_startedpara evitar sobreposição de fala.
Ciclo de vida da conexão
Um ciclo de vida típico de uma sessão WebSocket é o seguinte:
- Estabelecer a conexão: o cliente inicia uma conexão WebSocket e o servidor retorna o evento
session.created. - Configurar: o cliente envia
session.updatepara definir parâmetros como o modo de interação, a voz e as ferramentas. Esta etapa deve ser concluída antes do envio do primeiro áudio. - Interagir: o cliente envia continuamente fluxos de áudio (
input_audio_buffer.append), e o servidor realiza a inferência acionada pela detecção do VAD ou por gatilhos manuais, retornando fala e texto de forma em streaming. - Fechar: o cliente fecha ativamente a conexão WebSocket. Se a conexão ficar ociosa por muito tempo, o servidor também pode desconectá-la ativamente.
item_id correspondente antes de fechar a conexão. response.done apenas indica que a resposta do modelo terminou; o resultado da transcrição pode ser retornado posteriormente.Otimização de latência
- Tamanho do bloco de áudio: recomendamos enviar 100 ms de dados de áudio por vez (16 kHz × 16 bits × mono = 3200 bytes por envio), o que garante o desempenho em tempo real e evita solicitações de rede excessivamente frequentes.
- Reprodução em streaming: decodifique e reproduza o áudio imediatamente após receber
response.audio.delta; não espereresponse.donepara reproduzir o segmento inteiro. - Limpar o buffer imediatamente no barge-in: ao receber
input_audio_buffer.speech_started, limpe imediatamente o buffer de reprodução local para impedir que áudio antigo continue sendo reproduzido e cause latência percebida.
Modelos e regiões suportados
- Singapura
- China (Pequim)
- qwen-audio-3.1-realtime-plus
- qwen-audio-3.1-realtime-flash
- qwen-audio-3.0-realtime-plus
- qwen-audio-3.0-realtime-flash