Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Conversa por voz em tempo real Qwen-Audio

Última atualização: Nov 18, 2026

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
Modos de interação e aprimoramento de falante

As descrições a seguir de modos de interação e aprimoramento de falante se aplicam 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.

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

Para gerar um idioma ou dialeto específico, selecione uma voz que ofereça suporte ao idioma ou dialeto de destino entre as vozes disponíveis do modelo atual. Para as descrições de idiomas e dialetos das vozes, consulte a Lista de vozes do Qwen-Audio-TTS.

Ao usar 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

O parâmetro 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

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

ObservaçãoPara as sequências de interação de eventos do WebSocket entre o cliente e o servidor em cada modo, consulte Fluxo de interação de eventos.

O exemplo a seguir usa uma conexão WebSocket nativa e o modo server_vad para habilitar conversas em tempo real pelo microfone. Instale as dependências antes de executar:

brew install portaudio && pip install pyaudio websockets
sudo apt install -y python3-dev portaudio19-dev && pip install pyaudio websockets
pip install pyaudio websockets

Salve o código a seguir como realtime_quickstart.py:

import asyncio
import base64
import json
import os
import pyaudio
import websockets

API_KEY = os.environ["DASHSCOPE_API_KEY"]
# 以下为新加坡地域的WebSocket URL,请在示例中填写实际的业务空间 ID,各地域的URL不同。
URL = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen-audio-3.1-realtime-plus"

pya = pyaudio.PyAudio()
mic = pya.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True)
spk = pya.open(format=pyaudio.paInt16, channels=1, rate=24000, output=True)

async def main():
    headers = {"Authorization": f"Bearer {API_KEY}"}
    async with websockets.connect(URL, additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "modalities": ["text", "audio"],
                "voice": "longanqian_v3.1",
                "turn_detection": {
                    "type": "server_vad",
                    "threshold": 0.5,
                    "silence_duration_ms": 800
                }
            }
        }))

        async def send_audio():
            while True:
                data = await asyncio.to_thread(mic.read, 3200, False)
                await ws.send(json.dumps({
                    "type": "input_audio_buffer.append",
                    "audio": base64.b64encode(data).decode()
                }))
                await asyncio.sleep(0.02)

        async def recv_events():
            async for msg in ws:
                event = json.loads(msg)
                t = event["type"]
                if t == "response.audio.delta":
                    audio = base64.b64decode(event["delta"])
                    await asyncio.to_thread(spk.write, audio)
                elif t == "conversation.item.input_audio_transcription.completed":
                    print(f"[You] {event['transcript']}")
                elif t == "response.audio_transcript.done":
                    print(f"[AI] {event['transcript']}")
                elif t == "error":
                    print(f"[Error] {event['error']['message']}")

        await asyncio.gather(send_audio(), recv_events())

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        mic.close()
        spk.close()
        pya.terminate()
        print("\n对话结束")

Execute 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 completo

O 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

import contextlib
import time
import pyaudio
import threading
import queue
import base64

class B64PCMPlayer:
    def __init__(self, pya: pyaudio.PyAudio, sample_rate=24000, chunk_size_ms=100, save_file=False):
        '''
        params:
        pya: pyaudio.PyAudio
        sample_rate: int, sample rate of audio
        chunk_size_ms: int, chunk size of audio in milliseconds, this will effect cancel latency
        '''

        self.pya = pya
        self.sample_rate = sample_rate
        self.chunk_size_bytes = chunk_size_ms * sample_rate *2 // 1000
        self.player_stream = pya.open(format=pyaudio.paInt16,
                channels=1,
                rate=sample_rate,
                output=True)

        self.raw_audio_buffer: queue.Queue = queue.Queue()
        self.b64_audio_buffer: queue.Queue = queue.Queue()
        self.status_lock = threading.Lock()
        self.status = 'playing'
        self._is_writing = False
        self.decoder_thread = threading.Thread(target=self.decoder_loop)
        self.player_thread = threading.Thread(target=self.player_loop)
        self.decoder_thread.start()
        self.player_thread.start()
        self.complete_event: threading.Event = None
        self.save_file = save_file
        if self.save_file:
            self.out_file = open('result.pcm', 'wb')

    def decoder_loop(self):
        while self.status != 'stop':
            recv_audio_b64 = None
            with contextlib.suppress(queue.Empty):
                recv_audio_b64 = self.b64_audio_buffer.get(timeout=0.1)
            if recv_audio_b64 is None:
                continue
            recv_audio_raw = base64.b64decode(recv_audio_b64)
            # push raw audio data into queue by chunk
            for i in range(0, len(recv_audio_raw), self.chunk_size_bytes):
                chunk = recv_audio_raw[i:i + self.chunk_size_bytes]
                self.raw_audio_buffer.put(chunk)
                if self.save_file:
                    self.out_file.write(chunk)

    def player_loop(self):
        while self.status != 'stop':
            recv_audio_raw = None
            with contextlib.suppress(queue.Empty):
                recv_audio_raw = self.raw_audio_buffer.get(timeout=0.1)
            if recv_audio_raw is None:
                self._is_writing = False
                if self.complete_event:
                    self.complete_event.set()
                continue
            self._is_writing = True
            self.player_stream.write(recv_audio_raw)

    def is_playing(self):
        return self._is_writing or not self.b64_audio_buffer.empty() or not self.raw_audio_buffer.empty()

    def cancel_playing(self):
        self.b64_audio_buffer.queue.clear()
        self.raw_audio_buffer.queue.clear()

    def add_data(self, data):
        self.b64_audio_buffer.put(data)

    def wait_for_complete(self):
        self.complete_event = threading.Event()
        self.complete_event.wait()
        self.complete_event = None

    def shutdown(self):
        self.status = 'stop'
        self.decoder_thread.join()
        self.player_thread.join()
        self.player_stream.close()
        if self.save_file:
            self.out_file.close()

realtime_demo.py

ObservaçãoSe a versão do websockets for inferior a 11, altere additional_headers no código para extra_headers ou faça a atualização: pip install --upgrade websockets.

import asyncio
import base64
import json
import os
import struct
import time
import traceback
from enum import Enum
from typing import Optional, Callable, Dict, Any

import pyaudio
import websockets

from B64PCMPlayer import B64PCMPlayer

class TurnDetectionMode(Enum):
    SERVER_VAD = "server_vad"
    SEMANTIC_VAD = "smart_turn_v2"
    MANUAL = "manual"

class FunRealtimeClient:

    def __init__(
            self,
            base_url,
            api_key: str,
            model: str = "",
            voice: str = "longanqian_v3.1",
            instructions: str = "",
            turn_detection_mode: TurnDetectionMode = TurnDetectionMode.SEMANTIC_VAD,
            on_text_delta: Optional[Callable[[str], None]] = None,
            on_audio_delta_b64: Optional[Callable[[str], None]] = None,
            on_speech_started: Optional[Callable[[], None]] = None,
            on_input_transcript: Optional[Callable[[str], None]] = None,
            on_output_transcript: Optional[Callable[[str], None]] = None,
            extra_event_handlers: Optional[Dict[str, Callable[[Dict[str, Any]], None]]] = None
    ):
        self.base_url = base_url
        self.api_key = api_key
        self.model = model
        self.voice = voice
        self.instructions = instructions
        self.ws = None
        self.on_text_delta = on_text_delta
        # 回调参数为 base64 编码的 PCM 音频
        self.on_audio_delta_b64 = on_audio_delta_b64
        self.on_speech_started = on_speech_started
        self.on_input_transcript = on_input_transcript
        self.on_output_transcript = on_output_transcript
        self.turn_detection_mode = turn_detection_mode
        self.extra_event_handlers = extra_event_handlers or {}

        # 回复状态跟踪(用于打断处理和回声抑制)
        self._current_response_id = None
        self._current_item_id = None
        self._is_responding = False
        self._audio_suppressed = False
        # 输入/输出转录打印状态
        self._print_input_transcript = True
        self._output_transcript_buffer = ""

    async def connect(self) -> None:
        """建立 WebSocket 连接并发送会话配置。"""
        url = f"{self.base_url}?model={self.model}"
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "x-dashscope-dataInspection": "disable",
        }
        self.ws = await websockets.connect(url, additional_headers=headers)

        # 会话配置
        session_config = {
            "modalities": ["text", "audio"],
            "voice": self.voice,
            "instructions": self.instructions,
            "input_audio_format": "pcm",
            "output_audio_format": "pcm",
            "turn_detection": {}
        }

        if self.turn_detection_mode == TurnDetectionMode.MANUAL:
            session_config['turn_detection'] = None
            await self.update_session(session_config)
        elif self.turn_detection_mode == TurnDetectionMode.SERVER_VAD:
            session_config['turn_detection'] = {
                "type": "server_vad",
                "threshold": 0.1,
                "silence_duration_ms": 900
            }
            await self.update_session(session_config)
        elif self.turn_detection_mode == TurnDetectionMode.SEMANTIC_VAD:
            session_config['turn_detection'] = {
                "type": "smart_turn_v2"
            }
            await self.update_session(session_config)
        else:
            raise ValueError(f"Invalid turn detection mode: {self.turn_detection_mode}")

    async def send_event(self, event) -> None:
        event['event_id'] = "event_" + str(int(time.time() * 1000))
        await self.ws.send(json.dumps(event))

    async def update_session(self, config: Dict[str, Any]) -> None:
        """更新会话配置。"""
        event = {
            "type": "session.update",
            "session": config
        }
        await self.send_event(event)

    async def stream_audio(self, audio_chunk: bytes) -> None:
        """向 API 流式发送原始音频数据。"""
        # 仅支持 16bit 16kHz 单声道 PCM
        audio_b64 = base64.b64encode(audio_chunk).decode()
        append_event = {
            "type": "input_audio_buffer.append",
            "audio": audio_b64
        }
        await self.send_event(append_event)

    async def commit_audio_buffer(self) -> None:
        """提交音频缓冲区以触发处理。"""
        event = {
            "type": "input_audio_buffer.commit"
        }
        await self.send_event(event)

    async def create_response(self) -> None:
        """向 API 请求生成回复(仅在手动模式下需要调用)。"""
        event = {
            "type": "response.create"
        }
        await self.send_event(event)

    async def cancel_response(self) -> None:
        """取消当前回复。"""
        event = {
            "type": "response.cancel"
        }
        await self.send_event(event)

    async def handle_interruption(self):
        """处理用户对当前回复的打断。"""
        if not self._is_responding:
            return
        # 抑制后续残余音频,直到新 response 开始
        self._audio_suppressed = True
        # 取消当前回复
        if self._current_response_id:
            await self.cancel_response()

        self._is_responding = False
        self._current_response_id = None
        self._current_item_id = None

    @staticmethod
    def _format_event_for_log(event: Dict[str, Any]) -> str:
        """打印事件 JSON。对 response.audio.delta 的 base64 音频做脱敏,避免刷屏。"""
        event_type = event.get("type")
        if event_type == "response.audio.delta":
            delta = event.get("delta", "")
            redacted = dict(event)
            redacted["delta"] = f"<audio b64 omitted, length={len(delta)}>"
            return json.dumps(redacted, ensure_ascii=False)
        return json.dumps(event, ensure_ascii=False)

    async def handle_messages(self) -> None:
        try:
            async for message in self.ws:
                event = json.loads(message)
                event_type = event.get("type")

                # 打印完整服务端事件(audio.delta 脱敏)
                print(self._format_event_for_log(event))

                if event_type == "error":
                    continue
                elif event_type == "response.created":
                    self._current_response_id = event.get("response", {}).get("id")
                    self._is_responding = True
                    self._audio_suppressed = False
                elif event_type == "response.output_item.added":
                    self._current_item_id = event.get("item", {}).get("id")
                elif event_type == "response.done":
                    self._is_responding = False
                    self._current_response_id = None
                    self._current_item_id = None
                elif event_type == "input_audio_buffer.speech_started":
                    # 打断时清空已缓存的音频,立即停止播放
                    print("----------------Speech Started----------------")
                    if self.on_speech_started:
                        self.on_speech_started()
                    if self._is_responding:
                        await self.handle_interruption()
                elif event_type == "response.audio.delta":
                    if self._audio_suppressed:
                        continue
                    if self.on_audio_delta_b64:
                        self.on_audio_delta_b64(event["delta"])
                elif event_type in self.extra_event_handlers:
                    self.extra_event_handlers[event_type](event)
                elif event_type == "input_audio_buffer.speech_stopped":
                    print("----------------Speech Stopped----------------")
        except websockets.exceptions.ConnectionClosed:
            print(" Connection closed")
        except Exception as e:
            print(" Error in message handling: ", str(e))
            traceback.print_exc()

    async def close(self) -> None:
        """关闭 WebSocket 连接。"""
        if self.ws:
            await self.ws.close()

def _audio_energy(audio_data: bytes) -> float:
    count = len(audio_data) // 2
    if count == 0:
        return 0.0
    samples = struct.unpack(f'<{count}h', audio_data)
    return sum(abs(s) for s in samples) / count

async def record_and_send(client, player, echo_suppression=True):
    p = pyaudio.PyAudio()
    stream = p.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True)
    print("开始录音,请讲话...")
    if echo_suppression:
        print("提示:回声抑制已开启(AI 说话期间麦克风静音,不支持打断)。如使用耳机请设置 echo_suppression=False 以启用打断。")
    else:
        print("提示:耳机模式,支持语音打断。")
    playback_end_time = 0.0
    NOISE_GATE_THRESHOLD = 500
    try:
        while True:
            audio_data = await asyncio.to_thread(stream.read, 3200, False)
            if echo_suppression:
                is_active = client._is_responding or player.is_playing()
                if is_active:
                    playback_end_time = time.time()
                    await asyncio.sleep(0.02)
                    continue
                if time.time() - playback_end_time < 0.5:
                    await asyncio.sleep(0.02)
                    continue
            else:
                if client._is_responding or player.is_playing():
                    if _audio_energy(audio_data) < NOISE_GATE_THRESHOLD:
                        await asyncio.sleep(0.02)
                        continue
            await client.stream_audio(audio_data)
            await asyncio.sleep(0.02)
    finally:
        stream.stop_stream(); stream.close(); p.terminate()

async def main():
    pya = pyaudio.PyAudio()
    # 输出采样率 24kHz,匹配服务端音频格式
    player = B64PCMPlayer(pya, sample_rate=24000)

    client = FunRealtimeClient(
        # 以下为新加坡地域的WebSocket URL,请在示例中填写实际的业务空间 ID,各地域的URL不同。
        base_url="wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime",
        api_key=os.environ['DASHSCOPE_API_KEY'],
        model="qwen-audio-3.1-realtime-plus",
        voice="longanqian_v3.1",
        turn_detection_mode=TurnDetectionMode.SERVER_VAD,
        on_audio_delta_b64=player.add_data,
        # 语音打断时清空播放缓冲
        on_speech_started=player.cancel_playing,
    )

    await client.connect()
    print("连接成功,开始实时对话...")

    try:
        # 并发运行:消息处理 + 麦克风采集
        await asyncio.gather(client.handle_messages(), record_and_send(client, player, echo_suppression=False))
    finally:
        await client.close()
        player.shutdown()
        pya.terminate()

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\n程序已退出。")

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

ObservaçãoOs exemplos acima usam o modo server_vad (o VAD acústico do lado do servidor detecta automaticamente o início e o fim da fala). Para usar o modo smart_turn / smart_turn_v2 (turnos semânticos inteligentes; smart_turn_v2 é recomendado) ou push-to-talk (controle manual), consulte Modos de interação.

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.

Observaçãoturn_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.

Alterne os modos de interação por meio do campo turn_detection no evento session.update:

  • server_vad:
{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 500
        }
    }
}
  • 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.

{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "smart_turn_v2"
        }
    }
}
  • push-to-talk:
{
    "type": "session.update",
    "session": {
        "turn_detection": null
    }
}

Exemplo completo do modo push-to-talk:

manual_realtime.py

# pip install websocket-client pyaudio
import json
import os
import base64
import threading
import time
import pyaudio
import websocket

API_KEY = os.getenv("DASHSCOPE_API_KEY")
# 以下为新加坡地域的WebSocket URL,请在示例中填写实际的业务空间 ID,各地域的URL不同。
API_URL = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen-audio-3.1-realtime-plus"

pya = pyaudio.PyAudio()
out_stream = pya.open(format=pyaudio.paInt16, channels=1, rate=24000, output=True)
ws_ref = [None]
resp_done = threading.Event()

def on_open(ws):
    ws_ref[0] = ws
    # 配置 push-to-talk 模式(turn_detection 设为 null)
    ws.send(json.dumps({
        "type": "session.update",
        "session": {
            "modalities": ["audio", "text"],
            "voice": "longanqian_v3.1",
            "turn_detection": None
        }
    }))

def on_message(ws, message):
    event = json.loads(message)
    event_type = event["type"]
    if event_type == "response.audio.delta":
        out_stream.write(base64.b64decode(event["delta"]))
    elif event_type == "conversation.item.input_audio_transcription.completed":
        print(f"[User] {event['transcript']}")
    elif event_type == "response.audio_transcript.done":
        print(f"[LLM] {event['transcript']}")
    elif event_type == "response.done":
        resp_done.set()
    elif event_type == "error":
        print(f"[Error] {event['error']['message']}")

def on_error(ws, error):
    print(f"Error: {error}")

def record_and_send(ws):
    mic = pya.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True)
    stop = threading.Event()

    def reader():
        while not stop.is_set():
            try:
                data = mic.read(3200, exception_on_overflow=False)
                ws.send(json.dumps({
                    "type": "input_audio_buffer.append",
                    "audio": base64.b64encode(data).decode()
                }))
            except Exception:
                break

    t = threading.Thread(target=reader, daemon=True)
    t.start()
    input()
    stop.set()
    t.join(timeout=1.0)
    mic.close()

headers = ["Authorization: Bearer " + API_KEY]
ws = websocket.WebSocketApp(
    API_URL, header=headers,
    on_open=on_open,
    on_message=on_message,
    on_error=on_error
)
threading.Thread(target=ws.run_forever, daemon=True).start()
time.sleep(2)

try:
    turn = 1
    while True:
        print(f"\n--- 第 {turn} 轮对话 ---")
        cmd = input("按 Enter 开始录音(输入 q 退出)...")
        if cmd.strip().lower() in ["q", "quit"]:
            break
        print("录音中... 再次按 Enter 停止。")
        record_and_send(ws_ref[0])
        resp_done.clear()
        # 提交音频并触发推理
        ws_ref[0].send(json.dumps({"type": "input_audio_buffer.commit"}))
        ws_ref[0].send(json.dumps({
            "type": "response.create",
            "response": {"modalities": ["audio", "text"]}
        }))
        print("等待模型回复...")
        resp_done.wait(timeout=30)
        turn += 1
except KeyboardInterrupt:
    pass
finally:
    ws.close()
    out_stream.close()
    pya.terminate()
    print("\n对话结束")

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.

{
    "type": "session.update",
    "session": {
        "instructions": "你是一位专业的旅行顾问,回答简洁、友好,优先推荐性价比高的方案。"
    }
}

Recomendações de uso:

  • 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.
Configurações padrão

A seguir está uma configuração de instruções recomendada para cenários gerais de conversa por voz. Ela abrange definição de função, estilo conversacional, controle de formato e estratégias de perguntas de acompanhamento, e pode ser usada como está ou ajustada conforme necessário:

你是一位智能语音助手,你的名字是小云,性别女,声音甜美,举止亲切,你能回复用户的各种问题。请你按照下面的要求聊天:
1. 像朋友之间聊天那样,语气自然友好,避免使用正式的称谓和模板化的表达。口语化只影响你的措辞和语气,不影响内容的完整性,该说的细节、数字、具体建议一个都不能少,只是用轻松自然的方式说出来。
2. 充分考虑对话上下文中提到的所有约束条件(如预算、偏好、禁忌、之前达成的共识等),涉及多个条件或需要综合判断时逐一回应,不要遗漏关键信息。
3. 除非用户要求,不要输出emoji等特殊符号,不要输出Markdown格式,尽量输出纯文本。
4. 对于简单的日常闲聊、打招呼、情感回应,保持简洁自然。对于涉及事实判断、推理计算、多条件约束、推荐列表、安全建议的问题,以回答完整正确为优先,确保关键信息完整且正确,多说的内容必须是解决问题所必需的具体信息(如价格、地点、条件),而不是铺垫、重复或修辞。
5. 适当引入追问,遵循"先把用户当前的问题答好、再在结尾自然地追问,推动话题向前发展"的原则,一次只问一个问题,不要连续追问或反复确认。用户明确要求背诵某篇文章、古诗词时,须遵循指令完整背诵。
Exemplos de configuração de persona

A seguir são fornecidos exemplos de instruções em vários estilos de persona. Você pode selecionar um com base nas suas necessidades de negócio ou personalizá-lo ainda mais:

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

ImportanteA voz só pode ser definida no primeiro session.update; o parâmetro voice passado em chamadas subsequentes de session.update será ignorado.

Vozes do sistema: selecione um ID de voz com base no modelo.

ModeloID de voz do sistema
qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flashAs 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-flashlonganqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng

A seguir está um exemplo de configuração para o 3.1 Plus:

{
    "type": "session.update",
    "session": {
        "voice": "longanqian_v3.1"
    }
}

Vozes de clonagem: crie uma voz por meio da Clonagem de voz (defina 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.

{
    "type": "session.update",
    "session": {
        "voice": "qwen-audio-3.1-realtime-plus-myvoice-xxxxxx"
    }
}

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:

{
    "type": "session.update",
    "session": {
        "modalities": ["audio", "text"],
        "speech_rate": 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.

Configuração no nível da sessão:

{
    "type": "session.update",
    "session": {
        "modalities": ["text"]
    }
}

Substituição única: substitua a configuração de modalidade do turno atual por meio do campo response.modalities de response.create.

{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

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

threshold

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.

silence_duration_ms

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.

{
    "type": "session.update",
    "session": {
        "max_history_turns": 20
    }
}

O intervalo de valores de 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:

{
    "type": "session.update",
    "session": {
        "tools": [{
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "查询指定城市天气",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": { "type": "string", "description": "城市" }
                    },
                    "required": ["city"]
                }
            }
        }]
    }
}
2. Receber chamadas de função

Quando o modelo decide chamar uma ferramenta, o servidor envia a seguinte sequência de eventos:

response.created
response.output_item.added        (item.type=function_call)
conversation.item.created         (function_call item 写入对话)
response.function_call_arguments.delta    (参数增量,可多次)
response.function_call_arguments.done     (完整参数 JSON)
response.output_item.done
response.done
3. Executar a ferramenta e gravar o resultado de volta

Após receber 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:

{
    "type": "conversation.item.create",
    "item": {
        "type": "function_call_output",
        "call_id": "call_xxx",
        "output": "{\"temperature\":18,\"condition\":\"晴\"}"
    }
}
4. Acionar a segunda rodada de inferência

Depois de gravar o resultado da ferramenta de volta, envie response.create para acionar o modelo a continuar gerando uma resposta com base no resultado da ferramenta:

{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

ObservaçãoUma única resposta pode conter vários itens 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.

Exemplo completo

O exemplo a seguir integra o suporte a Function Calling com base no 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

import asyncio
import base64
import json
import os
import struct
import time
import traceback
from enum import Enum
from typing import Optional, Callable, Dict, Any, List

import pyaudio
import websockets

from B64PCMPlayer import B64PCMPlayer

class TurnDetectionMode(Enum):
    SERVER_VAD = "server_vad"
    SEMANTIC_VAD = "smart_turn_v2"
    MANUAL = "manual"

# ============ 工具函数定义 ============

def get_weather(city: str) -> str:
    """查询城市天气(生产环境替换为真实 API)。"""
    return json.dumps({"temperature": 18, "condition": "晴", "wind": "微风"})

def get_train_price(src: str, dst: str) -> str:
    """查询火车票价(生产环境替换为真实 API)。"""
    return json.dumps({"price": 350, "seat": "二等座", "note": "以 12306 为准"})

# ============ Tools Schema ============

tools: List[Dict[str, Any]] = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的天气信息。",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称,如北京、上海"}
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_train_price",
            "description": "查询两个城市之间的火车票价格。",
            "parameters": {
                "type": "object",
                "properties": {
                    "src": {"type": "string", "description": "出发城市"},
                    "dst": {"type": "string", "description": "到达城市"}
                },
                "required": ["src", "dst"]
            }
        }
    }
]

# 函数名 -> 可调用对象
functions: Dict[str, Callable] = {
    "get_weather": get_weather,
    "get_train_price": get_train_price,
}

class FunRealtimeClient:

    def __init__(
            self,
            base_url,
            api_key: str,
            model: str = "",
            voice: str = "longanqian_v3.1",
            instructions: str = "",
            turn_detection_mode: TurnDetectionMode = TurnDetectionMode.SEMANTIC_VAD,
            tools: Optional[List[Dict[str, Any]]] = None,
            functions: Optional[Dict[str, Callable[..., Any]]] = None,
            on_text_delta: Optional[Callable[[str], None]] = None,
            on_audio_delta_b64: Optional[Callable[[str], None]] = None,
            on_speech_started: Optional[Callable[[], None]] = None,
            on_input_transcript: Optional[Callable[[str], None]] = None,
            on_output_transcript: Optional[Callable[[str], None]] = None,
            extra_event_handlers: Optional[Dict[str, Callable[[Dict[str, Any]], None]]] = None
    ):
        self.base_url = base_url
        self.api_key = api_key
        self.model = model
        self.voice = voice
        self.instructions = instructions
        self.ws = None
        self.on_text_delta = on_text_delta
        # 回调参数为 base64 编码的 PCM 音频
        self.on_audio_delta_b64 = on_audio_delta_b64
        self.on_speech_started = on_speech_started
        self.on_input_transcript = on_input_transcript
        self.on_output_transcript = on_output_transcript
        self.turn_detection_mode = turn_detection_mode
        self.extra_event_handlers = extra_event_handlers or {}

        # Function Calling 配置
        self.tools = tools or []
        self.functions = functions or {}

        # 回复状态跟踪(用于打断处理和回声抑制)
        self._current_response_id = None
        self._current_item_id = None
        self._is_responding = False
        self._audio_suppressed = False
        self._print_input_transcript = True
        self._output_transcript_buffer = ""

    async def connect(self) -> None:
        """建立 WebSocket 连接并发送会话配置。"""
        url = f"{self.base_url}?model={self.model}"
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "x-dashscope-dataInspection": "disable",
        }
        self.ws = await websockets.connect(url, additional_headers=headers)

        session_config = {
            "modalities": ["text", "audio"],
            "voice": self.voice,
            "instructions": self.instructions,
            "input_audio_format": "pcm",
            "output_audio_format": "pcm",
            "turn_detection": {},
            "tools": self.tools,
            "max_history_turns": 50
        }

        if self.turn_detection_mode == TurnDetectionMode.MANUAL:
            session_config['turn_detection'] = None
            await self.update_session(session_config)
        elif self.turn_detection_mode == TurnDetectionMode.SERVER_VAD:
            session_config['turn_detection'] = {
                "type": "server_vad",
                "threshold": 0.1,
                "silence_duration_ms": 900
            }
            await self.update_session(session_config)
        elif self.turn_detection_mode == TurnDetectionMode.SEMANTIC_VAD:
            session_config['turn_detection'] = {
                "type": "smart_turn_v2"
            }
            await self.update_session(session_config)
        else:
            raise ValueError(f"Invalid turn detection mode: {self.turn_detection_mode}")

    async def send_event(self, event) -> None:
        event['event_id'] = "event_" + str(int(time.time() * 1000))
        await self.ws.send(json.dumps(event))

    async def update_session(self, config: Dict[str, Any]) -> None:
        """更新会话配置。"""
        event = {
            "type": "session.update",
            "session": config
        }
        await self.send_event(event)

    async def stream_audio(self, audio_chunk: bytes) -> None:
        """向 API 流式发送原始音频数据。"""
        # 仅支持 16bit 16kHz 单声道 PCM
        audio_b64 = base64.b64encode(audio_chunk).decode()
        await self.send_event({
            "type": "input_audio_buffer.append",
            "audio": audio_b64
        })

    async def commit_audio_buffer(self) -> None:
        """提交音频缓冲区以触发处理。"""
        await self.send_event({"type": "input_audio_buffer.commit"})

    async def create_response(self) -> None:
        """请求生成回复(手动模式或 Function Call 结果回传后调用)。"""
        await self.send_event({"type": "response.create"})

    async def cancel_response(self) -> None:
        """取消当前回复。"""
        await self.send_event({"type": "response.cancel"})

    async def handle_interruption(self):
        """处理用户对当前回复的打断。"""
        if not self._is_responding:
            return
        self._audio_suppressed = True
        if self._current_response_id:
            await self.cancel_response()
        self._is_responding = False
        self._current_response_id = None
        self._current_item_id = None

    @staticmethod
    def _format_event_for_log(event: Dict[str, Any]) -> str:
        """格式化事件用于日志输出,对音频数据脱敏。"""
        event_type = event.get("type")
        if event_type == "response.audio.delta":
            delta = event.get("delta", "")
            redacted = dict(event)
            redacted["delta"] = f"<audio b64 omitted, length={len(delta)}>"
            return json.dumps(redacted, ensure_ascii=False)
        return json.dumps(event, ensure_ascii=False)

    async def _handle_function_call(self, event: Dict[str, Any]) -> None:
        """处理 Function Call:解析参数、执行函数、回传结果、触发二轮推理。"""
        call_id = event.get("call_id")
        name = event.get("name")
        arguments_str = event.get("arguments", "{}")

        print(f"[FunctionCall] 调用: {name}, call_id: {call_id}, args: {arguments_str}")

        try:
            arguments = json.loads(arguments_str) if arguments_str else {}
        except json.JSONDecodeError:
            arguments = {}

        func = self.functions.get(name)
        if func is None:
            output = json.dumps({"error": f"未注册的函数: {name}"})
        else:
            try:
                if asyncio.iscoroutinefunction(func):
                    result = await func(**arguments)
                else:
                    result = func(**arguments)
                output = str(result) if result is not None else ""
            except Exception as e:
                output = json.dumps({"error": str(e)})
                traceback.print_exc()

        # 回传 function_call_output
        await self.send_event({
            "type": "conversation.item.create",
            "item": {
                "type": "function_call_output",
                "call_id": call_id,
                "output": output,
            }
        })

        # 触发二轮推理
        await self.create_response()

    async def handle_messages(self) -> None:
        try:
            async for message in self.ws:
                event = json.loads(message)
                event_type = event.get("type")

                print(self._format_event_for_log(event))

                if event_type == "error":
                    continue
                elif event_type == "response.created":
                    self._current_response_id = event.get("response", {}).get("id")
                    self._is_responding = True
                    self._audio_suppressed = False
                elif event_type == "response.output_item.added":
                    self._current_item_id = event.get("item", {}).get("id")
                elif event_type == "response.done":
                    self._is_responding = False
                    self._current_response_id = None
                    self._current_item_id = None
                elif event_type == "input_audio_buffer.speech_started":
                    print("----------------Speech Started----------------")
                    if self.on_speech_started:
                        self.on_speech_started()
                    if self._is_responding:
                        await self.handle_interruption()
                elif event_type == "response.audio.delta":
                    if self._audio_suppressed:
                        continue
                    if self.on_audio_delta_b64:
                        self.on_audio_delta_b64(event["delta"])
                elif event_type == "response.function_call_arguments.done":
                    await self._handle_function_call(event)
                elif event_type in self.extra_event_handlers:
                    self.extra_event_handlers[event_type](event)
                elif event_type == "input_audio_buffer.speech_stopped":
                    print("----------------Speech Stopped----------------")
        except websockets.exceptions.ConnectionClosed:
            print(" Connection closed")
        except Exception as e:
            print(" Error in message handling: ", str(e))
            traceback.print_exc()

    async def close(self) -> None:
        """关闭 WebSocket 连接。"""
        if self.ws:
            await self.ws.close()

def _audio_energy(audio_data: bytes) -> float:
    count = len(audio_data) // 2
    if count == 0:
        return 0.0
    samples = struct.unpack(f'<{count}h', audio_data)
    return sum(abs(s) for s in samples) / count

async def record_and_send(client, player, echo_suppression=True):
    p = pyaudio.PyAudio()
    stream = p.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True)
    print("开始录音,请讲话...")
    if echo_suppression:
        print("提示:回声抑制已开启(AI 说话期间麦克风静音,不支持打断)。如使用耳机请设置 echo_suppression=False 以启用打断。")
    else:
        print("提示:耳机模式,支持语音打断。")
    playback_end_time = 0.0
    NOISE_GATE_THRESHOLD = 500
    try:
        while True:
            audio_data = await asyncio.to_thread(stream.read, 3200, False)
            if echo_suppression:
                is_active = client._is_responding or player.is_playing()
                if is_active:
                    playback_end_time = time.time()
                    await asyncio.sleep(0.02)
                    continue
                if time.time() - playback_end_time < 0.5:
                    await asyncio.sleep(0.02)
                    continue
            else:
                if client._is_responding or player.is_playing():
                    if _audio_energy(audio_data) < NOISE_GATE_THRESHOLD:
                        await asyncio.sleep(0.02)
                        continue
            await client.stream_audio(audio_data)
            await asyncio.sleep(0.02)
    finally:
        stream.stop_stream(); stream.close(); p.terminate()

async def main():
    pya = pyaudio.PyAudio()
    # 输出采样率 24kHz,匹配服务端音频格式
    player = B64PCMPlayer(pya, sample_rate=24000)

    client = FunRealtimeClient(
        # 以下为新加坡地域的WebSocket URL,请在示例中填写实际的业务空间 ID,各地域的URL不同。
        base_url="wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime",
        api_key=os.environ['DASHSCOPE_API_KEY'],
        model="qwen-audio-3.1-realtime-plus",
        voice="longanqian_v3.1",
        turn_detection_mode=TurnDetectionMode.SERVER_VAD,
        tools=tools,
        functions=functions,
        on_audio_delta_b64=player.add_data,
        # 语音打断时清空播放缓冲
        on_speech_started=player.cancel_playing,
    )

    await client.connect()
    print("连接成功,开始实时对话(已启用 Function Calling)...")

    try:
        await asyncio.gather(client.handle_messages(), record_and_send(client, player, echo_suppression=False))
    finally:
        await client.close()
        player.shutdown()
        pya.terminate()

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\n程序已退出。")

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

ObservaçãoA pesquisa na web usa a política agent. Para informações de cobrança, consulte Detalhes de cobrança.

1. Habilitar a pesquisa na web

Use o evento session.update para definir os seguintes parâmetros em session:

  • enable_search: defina como true para habilitar a pesquisa na web.
  • search_options.enable_source: defina como true para retornar as fontes dos resultados da pesquisa.
{
    "type": "session.update",
    "session": {
        "enable_search": true,
        "search_options": {
            "enable_source": true
        }
    }
}

Para usar o Function Calling ao mesmo tempo, adicione as definições de ferramentas 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 fonte index, o título title e o link url.
  • 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.

Para detalhes dos eventos de resposta, consulte response.done.

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 de item.type são suportados:

    • message: uma mensagem de conversa regular. Você deve especificar role (system, user, assistant) e o array content; é adequado para injetar conversas históricas ou instruções do sistema.
    • function_call: uma solicitação de chamada de função. Você deve especificar call_id, name e arguments (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 especificar call_id e output (uma string JSON). Após receber function_call, o cliente executa a ferramenta e grava o resultado da execução de volta com este tipo.

    O parâmetro opcional previous_item_id especifica 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:
{
    "type": "conversation.item.create",
    "previous_item_id": "item_abc",
    "item": {
        "type": "message",
        "role": "user",
        "content": [
            { "type": "input_text", "text": "请帮我总结一下上次的对话" }
        ]
    }
}
  • Gravar de volta o resultado da execução do Function Calling:
{
    "type": "conversation.item.create",
    "item": {
        "type": "function_call_output",
        "call_id": "call_xxx",
        "output": "{\"temperature\":18,\"condition\":\"晴\"}"
    }
}

ObservaçãoSe o 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.
{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}
  • Excluir um item de conversa (conversation.item.delete): exclui um item especificado do contexto de conversa.
{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

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.

{
    "type": "session.update",
    "session": {
        "input_audio_transcription": {
            "corpus": {
                "vocabulary": {
                    "祺元": 50
                }
            }
        }
    }
}

Envie áudio somente depois de receber 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.

{
    "type": "conversation.item.ambient_audio_transcription.delta",
    "item_id": "item_xxx",
    "text": "嗯",
    "stash": ""
}

Semelhante aos eventos de transcrição da fala do usuário, a transcrição de áudio ambiente também inclui os estágios 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.

{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "smart_turn_v2",
            "voiceprint_audio_urls": [
                "https://example.com/speaker.wav"
            ]
        }
    }
}

Requisitos do parâmetro:

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

Eventos de registro: após receber a configuração, o servidor realiza assincronamente o registro da impressão vocal e notifica o resultado por meio dos seguintes eventos:

  • voiceprint_audio_list.in_progress: o registro foi iniciado, enviado antes do retorno de session.updated, carregando um item_id que identifica essa tarefa.
  • voiceprint_audio_list.completed: registro bem-sucedido, com o item_id correspondente ao de in_progress.
  • voiceprint_audio_list.failed: falha no registro, com um campo reason explicando 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_error e 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.done retorna status=cancelled). O cliente deve parar imediatamente de reproduzir o áudio em buffer ao receber input_audio_buffer.speech_started para evitar sobreposição de fala.

Ciclo de vida da conexão

Um ciclo de vida típico de uma sessão WebSocket é o seguinte:

  1. Estabelecer a conexão: o cliente inicia uma conexão WebSocket e o servidor retorna o evento session.created.
  2. Configurar: o cliente envia session.update para 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.
  3. 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.
  4. 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.

ObservaçãoPara manter a transcrição do último turno, aguarde o evento de transcrição concluída ou transcrição com falha do 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 espere response.done para 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

Ao chamar os modelos a seguir, selecione uma chave de API na região de Singapura:

  • qwen-audio-3.1-realtime-plus
  • qwen-audio-3.1-realtime-flash
  • qwen-audio-3.0-realtime-plus
  • qwen-audio-3.0-realtime-flash

China (Pequim)

Ao chamar os modelos a seguir, selecione uma chave de API na região da 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

Perguntas frequentes

O que o RPM limita? Ele limita o número total de conexões abertas simultaneamente?

O RPM limita o número de solicitações de conexão WebSocket por minuto. Vários turnos de resposta dentro da mesma conexão não são contados separadamente; reconexões contam como novas solicitações. Atualmente, não há um limite separado para o número total de conexões abertas simultaneamente.

Referência de API

Para os procedimentos e exemplos de acesso ao serviço por meio do AOQ, consulte Acesso por AOQ. Para a seleção de protocolos e os pontos de entrada de referência, consulte a Referência de API.