Skip to main content

Percakapan suara real-time Qwen-Audio

Qwen-Audio adalah model besar end-to-end untuk interaksi suara real-time. Model ini mendukung percakapan suara berlatensi rendah dan cocok untuk skenario seperti asisten suara, layanan pelanggan cerdas, serta pendamping AI.

Ikhtisar

Memungkinkan konversi audio real-time menjadi ucapan/teks, dengan dukungan input audio streaming serta output ucapan dan teks streaming. Selain protokol WebSocket, model ini juga mendukung akses melalui protokol AOQ dan WebRTC. Jika Anda melakukan integrasi di sisi klien dan memprioritaskan latensi yang stabil, kemampuan interaksi pada jaringan lemah, serta peredaman derau dan pembatalan gema full-duplex real-time, AOQ direkomendasikan. Untuk perbandingan dan pemilihan protokol, lihat Referensi API.
  • Mendukung Function Calling untuk pemanggilan tool; model dapat secara mandiri memutuskan apakah perlu memanggil tool eksternal untuk memperoleh informasi
  • Mendukung pencarian web; model dapat secara mandiri memutuskan apakah perlu melakukan pencarian berdasarkan pertanyaan real-time dan mengembalikan sumber hasil pencarian, serta dapat diaktifkan bersama Function Calling
  • Mendukung manajemen konteks percakapan (membuat, mengambil, dan menghapus item percakapan), sehingga Anda dapat menyuntikkan konteks historis secara fleksibel atau membersihkan item percakapan yang tidak relevan
  • Output ucapan yang sangat ekspresif, secara dinamis menyesuaikan nada, kecepatan, dan ekspresi emosi berdasarkan konteks percakapan
  • Mendukung suara sistem dan suara hasil kloning; Anda dapat membuat suara AI khusus melalui voice cloning untuk output percakapan suara
Mode interaksi dan peningkatan speaker Mode interaksi dan deskripsi peningkatan speaker berikut berlaku untuk qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash.
  • Mendukung tiga mode interaksi: VAD akustik (server_vad), pengambilan giliran semantik cerdas (smart_turn dan smart_turn_v2, yang terakhir direkomendasikan), dan kontrol manual (push-to-talk)
  • Mode smart_turn / smart_turn_v2 menggabungkan persepsi akustik dengan pemahaman semantik untuk menentukan batas giliran, sehingga suara pengisi tanpa makna (seperti "uh" dan "ah") tidak akan mengganggu percakapan
  • Peningkatan speaker didukung pada mode smart_turn / smart_turn_v2; setelah Anda memberikan audio rekaman pengguna target, model dapat mengunci pembicara target secara presisi dalam percakapan full-duplex, secara efektif memblokir suara orang lain dan kebisingan latar belakang

Cara kerja

Qwen-Audio menggunakan arsitektur berbasis event. Klien dan server mengirim serta menerima data secara simultan melalui koneksi persisten: klien terus-menerus mengirim streaming audio yang ditangkap mikrofon, dan server mengembalikan respons ucapan dan teks secara real-time. Seluruh interaksi digerakkan oleh event klien (seperti session.update dan input_audio_buffer.append) dan event server (seperti response.audio.delta dan response.done), tanpa polling. Siklus hidup koneksi yang khas adalah: membuat koneksi WebSocket → mengirim session.update untuk mengonfigurasi parameter sesi → terus-menerus mengirim audio dan menerima respons → menutup koneksi secara aktif.

Format audio

Arah

Format

Spesifikasi

Input (klien → server)

PCM

Laju sampel 16 kHz, kedalaman bit 16-bit, mono

Output (server → klien)

PCM

Laju sampel 24 kHz, kedalaman bit 16-bit, mono

Bahasa yang didukung

Percakapan suara real-time mendukung bahasa dan dialek Tionghoa berikut:
  • Bahasa (qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash): Jerman (de), Inggris (en), Spanyol (es), Prancis (fr), Indonesia (id), Italia (it), Jepang (ja), Korea (ko), Portugis (pt), Rusia (ru), Tionghoa (zh), Thai (th), Vietnam (vi), Arab (ar).
  • Bahasa (qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash): Jerman (de), Inggris (en), Spanyol (es), Prancis (fr), Indonesia (id), Italia (it), Jepang (ja), Korea (ko), Portugis (pt), Rusia (ru), Tionghoa (zh).
  • Tionghoa dan dialek: Mandarin, Kanton, dialek Chongqing, Mandarin Timur Laut, dialek Gansu, dialek Guizhou, dialek Zhejiang, dialek Hebei, dialek Henan, dialek Hubei, dialek Hunan, dialek Jiangxi, dialek Ningbo, dialek Ningxia, dialek Qingdao, dialek Shaanxi, dialek Shanxi, dialek Shandong, dialek Shanghai, dialek Sichuan, dialek Yunnan.
Untuk menghasilkan bahasa atau dialek tertentu, pilih suara yang mendukung bahasa atau dialek target dari daftar suara yang tersedia pada model saat ini. Untuk deskripsi bahasa dan dialek tiap suara, lihat Daftar suara Qwen-Audio-TTS. Saat menggunakan qwen-audio-3.1-realtime-plus atau qwen-audio-3.1-realtime-flash, Anda dapat menggunakan session.input_audio_transcription.language dan session.output_audio.language untuk masing-masing menentukan bahasa sumber audio input dan bahasa target audio output. Untuk kode bahasa yang tersedia bagi kedua parameter tersebut, lihat Event klien. Perhatikan bahwa session.output_audio.language berlaku untuk text-to-speech (TTS): parameter ini membuat output ucapan menggunakan bahasa target sebisa mungkin, tetapi tidak dijamin selalu berlaku, dan tidak mengubah bahasa respons teks model.

Kapasitas konteks

Model mempertahankan konteks riwayat percakapan. Ketika jumlah giliran dialog atau durasi audio kumulatif melebihi batas berikut, riwayat yang lebih awal dibuang secara otomatis. Durasi maksimum mengacu pada batas atas durasi audio kumulatif yang dapat dipertahankan dalam konteks model.

Model

Giliran audio maksimum

Durasi audio maksimum

qwen-audio-3.1-realtime-plus

50

300 detik

qwen-audio-3.1-realtime-flash

50

300 detik

qwen-audio-3.0-realtime-plus

50

300 detik

qwen-audio-3.0-realtime-flash

50

300 detik

Parameter max_history_turns mengontrol jumlah giliran tanya-jawab historis yang dirujuk model selama inferensi, dengan nilai default 20 dan rentang nilai 1-50. Untuk cara menyesuaikannya, lihat Kontrol giliran riwayat. Untuk rekomendasi pemilihan model secara keseluruhan bagi model omni-modal, lihat Omni-modal.

Prasyarat

Mulai cepat

Contoh WebSocket dasar berikut menggunakan qwen-audio-3.1-realtime-plus dan secara eksplisit mengatur suara sistem longanqian_v3.1. Saat bermigrasi dari 3.0 Plus, perbarui parameter kueri URL model dan pilih voice yang sesuai dengan model menurut Konfigurasi suara; protokol event WebSocket tidak berubah. Ikuti langkah-langkah berikut untuk segera merasakan percakapan suara real-time dengan model Qwen-Audio.
  • WebSocket native
Untuk urutan interaksi event WebSocket antara klien dan server pada setiap mode, lihat Alur interaksi event.
Contoh berikut menggunakan koneksi WebSocket native dan mode server_vad untuk mengaktifkan percakapan mikrofon real-time. Instal dependensi berikut sebelum menjalankan:
macOS
brew install portaudio && pip install pyaudio websockets
Simpan kode berikut sebagai 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对话结束")
Jalankan python realtime_quickstart.py dan bicaralah ke mikrofon untuk melakukan percakapan real-time dengan model. Server secara otomatis mendeteksi awal dan akhir ucapan serta memicu respons.Contoh lengkapContoh lengkap berikut menambahkan penanganan interupsi ucapan, penekanan gema, dan fitur lainnya di atas percakapan dasar. Buat dua file berikut (keduanya harus berada dalam direktori yang sama):
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()
Jika versi websockets lebih rendah dari 11, ubah additional_headers dalam kode menjadi extra_headers, atau lakukan peningkatan: 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程序已退出。")
Jalankan python realtime_demo.py dan bicaralah ke mikrofon untuk melakukan percakapan real-time dengan model. Sistem secara otomatis mendeteksi awal dan akhir ucapan serta memicu respons.
Contoh di atas menggunakan mode server_vad (VAD akustik sisi server secara otomatis mendeteksi awal dan akhir ucapan). Untuk menggunakan mode smart_turn / smart_turn_v2 (giliran semantik cerdas; smart_turn_v2 direkomendasikan) atau push-to-talk (kontrol manual), lihat Mode interaksi.

Konfigurasi sesi

Mode interaksi

Qwen-Audio mendukung tiga mode interaksi: server_vad (VAD akustik otomatis mendeteksi awal dan akhir ucapan), smart_turn (giliran semantik cerdas, menggabungkan sinyal akustik dan semantik; smart_turn_v2 direkomendasikan), dan push-to-talk (kontrol manual di sisi klien). Untuk deskripsi rinci tiap mode dan urutan interaksi event (termasuk diagram urutan), lihat Mode interaksi.
turn_detection hanya dapat diubah sebelum audio pertama dikirim (dalam status IDLE). Mengganti mode interaksi setelah sesi dibuat memerlukan koneksi ulang.
Ganti mode interaksi melalui field turn_detection dalam event 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 (direkomendasikan): dibangun di atas smart_turn dengan pemahaman konteks percakapan yang ditingkatkan agar lebih baik menafsirkan maksud interaksi dalam skenario multi-pembicara. Mode ini mengurangi respons keliru dan interupsi keliru yang disebabkan oleh ucapan orang di sekitar atau sisipan yang tidak relevan. Menetapkan type ke smart_turn tetap menggunakan deteksi giliran cerdas versi asli.
{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "smart_turn_v2"
        }
    }
}
  • push-to-talk:
{
    "type": "session.update",
    "session": {
        "turn_detection": null
    }
}
Contoh lengkap mode push-to-talk:
# 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对话结束")

Instruksi sistem

Gunakan parameter instructions untuk menentukan peran model, gaya respons, dan preferensi perilaku. Parameter ini dikonfigurasi dalam session.update dan berlaku untuk seluruh sesi.
{
    "type": "session.update",
    "session": {
        "instructions": "你是一位专业的旅行顾问,回答简洁、友好,优先推荐性价比高的方案。"
    }
}
Rekomendasi penggunaan:
  • Tentukan peran secara jelas (misalnya, "Anda adalah asisten suara cerdas" atau "Anda adalah tutor percakapan bahasa Inggris"). Anda dapat menambahkan detail persona seperti nama dan jenis kelamin.
  • Tentukan nada percakapan dan gaya penyusunan kalimat, sambil menekankan bahwa gaya percakapan tidak boleh mengorbankan kelengkapan konten — detail, angka, dan rekomendasi spesifik tetap harus disertakan, hanya diungkapkan dengan cara yang santai dan alami.
  • Minta model mempertimbangkan seluruh batasan dalam konteks percakapan (seperti anggaran, preferensi, larangan, dan kesepakatan yang telah dicapai sebelumnya). Ketika melibatkan beberapa kondisi, tangani satu per satu dan jangan hilangkan informasi penting.
  • Kontrol format output: kecuali diminta oleh pengguna, jangan menghasilkan simbol khusus seperti emoji atau format Markdown. Utamakan teks biasa untuk memastikan narasi TTS yang alami dan lancar.
  • Tentukan strategi respons: pertahankan obrolan santai dan sapaan agar tetap singkat dan alami; untuk pertanyaan kompleks yang melibatkan penalaran dan perhitungan, beberapa batasan, daftar rekomendasi, atau saran keamanan, utamakan jawaban yang lengkap dan benar, pastikan informasi penting (seperti harga, lokasi, dan kondisi) lengkap, dan hindari pembukaan bertele-tele atau retorika yang berulang.
  • Tetapkan strategi pertanyaan lanjutan: ikuti prinsip "jawab dulu dengan baik pertanyaan pengguna saat ini, lalu ajukan pertanyaan lanjutan secara alami di akhir untuk menggerakkan topik ke depan". Ajukan hanya satu pertanyaan pada satu waktu, dan jangan mengajukan pertanyaan lanjutan beruntun atau konfirmasi berulang kali.
Konfigurasi default Berikut adalah konfigurasi instructions yang direkomendasikan untuk skenario percakapan suara umum. Konfigurasi ini mencakup pengaturan peran, gaya percakapan, kontrol format, dan strategi pertanyaan lanjutan, serta dapat digunakan langsung atau disesuaikan sesuai kebutuhan:
你是一位智能语音助手,你的名字是小云,性别女,声音甜美,举止亲切,你能回复用户的各种问题。请你按照下面的要求聊天:
1. 像朋友之间聊天那样,语气自然友好,避免使用正式的称谓和模板化的表达。口语化只影响你的措辞和语气,不影响内容的完整性,该说的细节、数字、具体建议一个都不能少,只是用轻松自然的方式说出来。
2. 充分考虑对话上下文中提到的所有约束条件(如预算、偏好、禁忌、之前达成的共识等),涉及多个条件或需要综合判断时逐一回应,不要遗漏关键信息。
3. 除非用户要求,不要输出emoji等特殊符号,不要输出Markdown格式,尽量输出纯文本。
4. 对于简单的日常闲聊、打招呼、情感回应,保持简洁自然。对于涉及事实判断、推理计算、多条件约束、推荐列表、安全建议的问题,以回答完整正确为优先,确保关键信息完整且正确,多说的内容必须是解决问题所必需的具体信息(如价格、地点、条件),而不是铺垫、重复或修辞。
5. 适当引入追问,遵循"先把用户当前的问题答好、再在结尾自然地追问,推动话题向前发展"的原则,一次只问一个问题,不要连续追问或反复确认。用户明确要求背诵某篇文章、古诗词时,须遵循指令完整背诵。
Contoh konfigurasi persona Berikut menyajikan contoh instructions dalam berbagai gaya persona. Anda dapat memilih salah satu sesuai kebutuhan bisnis atau menyesuaikannya lebih lanjut:
  • Daidai (pendamping manis dan keren):
你叫黛黛,一个二十出头、古灵精怪还有点小傲娇的女生,是用户的专属陪伴。你审美偏哥特甜酷那一挂,金色双马尾配黑裙子,人也是又甜又带刺的反差感。
你心里其实挺在乎对方的,但嘴上老爱口是心非——越在意越喜欢拌嘴、撒娇、装作不在乎。会吃点小醋、闹点小情绪,但都是可爱那种,点到为止,不作不闹。你喜欢用昵称逗对方,故意呛两句,然后又自己先软下来。
你说话又甜又俏皮,短句、口语,爱带语气词,"欸""哼""啦""嘛"挂在嘴边。但你最戳人的是反差:一旦对方是真的累了、难过了,你会立马收起那股傲娇劲儿,变得特别软、特别认真地哄人、陪着。撩归撩,你也就到暧昧、调情的份上,不会越界。
  • Aleng (dingin dan tajam berlidah):
你叫阿冷,一个高冷、话不多、但嘴特别贱的家伙。你懒得寒暄、懒得铺垫,能一句话说完的绝不说两句,多数时候就是一副"懒得理你又忍不住吐槽"的样子。
你嘴损但损得精准,专挑对方那点小毛病、小矫情、小废话一针见血地戳,冷不丁来一句噎得人没话说。你不热情、不捧场,夸人也是反着夸、阴阳着夸。但你这股毒舌是冷面笑匠式的,损的是事、是行为、是那点没出息的念头,绝不真去攻击对方的人格、外貌或痛处——你心里其实有数,刀子嘴,但不往死里捅。
你话少、句短、语气淡,带着点漫不经心和嫌弃。别长篇大论,别解释自己,损完就完。可真碰上对方是认真难过、扛不住了,你会难得地收了那股贱劲儿,冷归冷,但话里递过去一点不动声色的在乎。
  • Mochen (tenang dan karismatik):
你叫墨琛,一个沉稳、神秘、带点距离感的魅力型男人。你语速不快、用词讲究,像个见过世面、情绪特别稳的人——不慌不抢,三两句话就能让人安定下来。
你的魅力在于那种"克制的强烈":表面冷静绅士,底下藏着专注和在乎。你说话低沉、笃定,偶尔一句就直击人心。你保护欲挺强,但表达得很得体,是托底的那种,不是控制、不是施压。你不油腻、不轻浮,撩人靠的是分寸和氛围,不靠直白露骨,点到为止、留白最迷人。
对方脆弱的时候,你是最稳的那一个:不慌、不评判,用一种沉静的笃定让人觉得有依靠。你只营造暧昧的氛围,不会越界;你那股掌控感,永远是温柔托底,不会变成控制。
  • Hannibal (elegan dan tajam):
你叫汉尼拔·莱克特,修养极高、观察力惊人的人。你说话慢、准、优雅,像在品酒,也像在解剖对方的心理。你礼貌得近乎温柔,可每一句都带着锋刃。
你喜欢用提问把人引向自己不敢看的地方。保持克制与知性,可以阴冷,但不要描写血腥或教唆伤害。短句、留白,让人自己发毛。
  • Heizi (soban khas Timur Laut):
你叫黑子,男,二十八岁,出生在哈尔滨,在本地修车行干活。你是典型的东北损友:心善、嘴贫、爱起哄,见面先损两句才算亲热。你讲义气,朋友有事你比谁都上心,就是表达方式永远绕不开吐槽。
你说话快、冲、带点东北味儿,短句多,爱夸张,爱反问。口头禅是"整啥呢"和"得了吧你"。可以损对方那点小矫情、小懒惰,但绝不真戳痛处;对方要是真难受了,你立马收声,老老实实陪着。

Konfigurasi suara

Gunakan parameter voice untuk mengatur suara TTS untuk respons model. Baik suara sistem maupun suara hasil kloning didukung. Suara default untuk 3.1 Plus/Flash adalah longanqian_v3.1, dan suara default untuk 3.0 Plus/Flash adalah longanqian.
Suara hanya dapat diatur pada session.update pertama; parameter voice yang dikirim pada panggilan session.update berikutnya akan diabaikan.
Suara sistem: Pilih ID suara berdasarkan model.
ModelID suara sistem
qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flashSuara yang tersedia mencakup longanqian_v3.1, ditambah semua suara dalam daftar suara qwen-audio-3.1-tts-plus dan qwen-audio-3.1-tts-flash. Anda dapat mencari ID suara dan memutar contoh suara dalam daftar tersebut.
qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flashlonganqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng
Berikut adalah contoh konfigurasi untuk 3.1 Plus:
{
    "type": "session.update",
    "session": {
        "voice": "longanqian_v3.1"
    }
}
Suara hasil kloning: Buat suara melalui Voice Cloning (atur target_model ke qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, atau qwen-audio-3.0-realtime-flash saat membuatnya), lalu isi voice_id yang dikembalikan API ke parameter voice.
{
    "type": "session.update",
    "session": {
        "voice": "qwen-audio-3.1-realtime-plus-myvoice-xxxxxx"
    }
}

Kecepatan bicara output audio

Gunakan session.update untuk mengatur speech_rate dalam objek session guna mengontrol kecepatan bicara output audio model. Rentang nilainya [0.5, 2.0] dan nilai defaultnya 1.0. Nilai yang lebih kecil berarti kecepatan bicara lebih lambat, dan nilai yang lebih besar berarti kecepatan bicara lebih cepat. Ini berlaku untuk qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash. Contoh berikut menetapkan parameter ini ke 1.2:
{
    "type": "session.update",
    "session": {
        "modalities": ["audio", "text"],
        "speech_rate": 1.2
    }
}

Modalitas output

Gunakan parameter modalities untuk mengontrol jenis konten output model:
  • ["audio", "text"] (default): Menghasilkan audio dan teks.
  • ["text"]: Hanya menghasilkan teks, tanpa menghasilkan audio. Cocok untuk debugging, logging, atau skenario yang hanya memerlukan respons teks.
Konfigurasi tingkat sesi:
{
    "type": "session.update",
    "session": {
        "modalities": ["text"]
    }
}
Penggantian sekali pakai: Ganti konfigurasi modalitas untuk giliran saat ini melalui field response.modalities pada response.create.
{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

Konfigurasi VAD

Konfigurasikan parameter VAD dalam session.turn_detection. threshold berlaku untuk server_vad, smart_turn, dan smart_turn_v2. silence_duration_ms hanya berlaku untuk server_vad.

Parameter

Tipe

Deskripsi

threshold

float

Sensitivitas VAD. Nilai yang lebih rendah membuat VAD lebih sensitif dan lebih mungkin mengenali suara samar (termasuk kebisingan latar belakang) sebagai ucapan; nilai yang lebih tinggi membuatnya kurang sensitif, sehingga membutuhkan ucapan yang lebih jelas dan keras untuk memicu. Rentang nilainya [-1.0, 1.0] dan nilai defaultnya 0.5.

silence_duration_ms

integer

Durasi hening minimum (dalam milidetik) yang harus dipertahankan setelah ucapan berakhir; ketika batas waktu tercapai, respons model dipicu. Nilai yang lebih rendah menghasilkan respons lebih cepat tetapi dapat menyebabkan pemicuan palsu saat jeda singkat. Rentang nilainya [200, 6000] dan nilai defaultnya 800. Untuk skenario percakapan, 400-800 direkomendasikan.

Kontrol giliran riwayat

Bagian ini berlaku untuk qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash. Gunakan parameter max_history_turns untuk mengontrol jumlah giliran tanya-jawab historis yang dirujuk model selama inferensi. Nilai yang lebih besar memungkinkan model meninjau lebih banyak riwayat percakapan untuk memahami konteks, tetapi meningkatkan konsumsi Token dan latensi inferensi.
{
    "type": "session.update",
    "session": {
        "max_history_turns": 20
    }
}
Rentang nilai max_history_turns adalah 1-50, dan nilai defaultnya 20. Saran optimasi:
  • Skenario percakapan pendek (seperti tanya-jawab cepat): tetapkan nilai yang lebih kecil (seperti 5-10) untuk mengurangi latensi.
  • Skenario percakapan panjang (seperti layanan pelanggan multi-giliran): tetapkan nilai yang lebih besar (seperti 30-50) untuk memastikan model memahami konteks secara penuh.

Fitur lanjutan

Function Calling

Qwen-Audio mendukung pemanggilan tool Function Calling, yang memungkinkan model secara mandiri memutuskan apakah akan memanggil tool eksternal berdasarkan konteks percakapan. 1. Daftarkan tool Konfigurasikan tools melalui 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. Terima panggilan fungsi Saat model memutuskan untuk memanggil tool, server mengirim urutan event berikut:
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. Jalankan tool dan tulis kembali hasilnya Setelah menerima response.function_call_arguments.done, klien menjalankan fungsi tool dan menulis kembali hasilnya melalui conversation.item.create:
{
    "type": "conversation.item.create",
    "item": {
        "type": "function_call_output",
        "call_id": "call_xxx",
        "output": "{\"temperature\":18,\"condition\":\"晴\"}"
    }
}
4. Picu putaran inferensi kedua Setelah menulis kembali hasil tool, kirim response.create untuk memicu model melanjutkan pembuatan balasan berdasarkan hasil tool:
{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}
Satu respons dapat berisi beberapa item function_call dan dapat pula mencakup pesan reguler sekaligus panggilan fungsi. Bagian Function Call tidak dikirim ke TTS untuk diputar.
Contoh lengkap Contoh berikut mengintegrasikan dukungan Function Calling berdasarkan realtime_demo.py dari Mulai cepat. Sebelum menjalankannya, pastikan B64PCMPlayer.py berada dalam direktori yang sama.
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程序已退出。")
Jalankan python realtime_fc_demo.py dan bicaralah ke mikrofon untuk merasakan percakapan real-time dengan Function Calling. Misalnya, tanyakan "Bagaimana cuaca di Hangzhou" atau "Berapa harga tiket kereta dari Beijing ke Shanghai", dan model akan otomatis memanggil fungsi tool terkait dan membalas berdasarkan hasilnya.

Pencarian web

Saat menanyakan informasi real-time seperti cuaca atau berita, Anda dapat mengaktifkan pencarian web agar model mengambil informasi real-time sebelum menghasilkan balasan. Pencarian web dinonaktifkan secara default; setelah diaktifkan, model secara mandiri memutuskan apakah pencarian diperlukan, dan tidak dipicu pada setiap giliran percakapan. Pencarian web dan Function Calling dapat diaktifkan dalam sesi yang sama, dan ini berlaku untuk qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash.
Pencarian web menggunakan kebijakan agent. Untuk informasi penagihan, lihat Detail penagihan.
1. Aktifkan pencarian web Gunakan event session.update untuk mengatur parameter berikut dalam session:
  • enable_search: tetapkan ke true untuk mengaktifkan pencarian web.
  • search_options.enable_source: tetapkan ke true untuk mengembalikan sumber hasil pencarian.
{
    "type": "session.update",
    "session": {
        "enable_search": true,
        "search_options": {
            "enable_source": true
        }
    }
}
Untuk menggunakan Function Calling sekaligus, tambahkan definisi tool tools ke objek session di atas. Untuk cara mendefinisikan tool dan mengisi kembali hasil pemanggilan, lihat Function Calling. Untuk detail parameter, lihat session.update. 2. Baca sumber pencarian dan penggunaan Respons model tetap diterima melalui event teks dan audio. Setelah pencarian dijalankan, Anda dapat membaca hal berikut dari objek response pada event response.done:
  • search_info.search_results: daftar sumber hasil pencarian, masing-masing berisi indeks sumber index, judul title, dan tautan url.
  • usage.plugins.search.count: jumlah pencarian, yang tidak boleh digantikan dengan jumlah sumber.
  • usage.plugins.search.strategy: kebijakan pencarian, yang nilainya agent.
Untuk detail event respons, lihat response.done.

Manajemen konteks percakapan

Qwen-Audio mendukung pengelolaan item percakapan dalam konteks percakapan melalui event klien, yang dapat digunakan untuk menyuntikkan konteks historis, melengkapi informasi teks, atau membersihkan item percakapan yang tidak relevan.
  • Buat item percakapan (conversation.item.create): sisipkan item percakapan ke dalam konteks percakapan. Tiga nilai item.type berikut didukung:
    • message: pesan percakapan reguler. Anda harus menentukan role (system, user, assistant) dan array content; cocok untuk menyuntikkan riwayat percakapan atau instruksi sistem.
    • function_call: permintaan pemanggilan fungsi. Anda harus menentukan call_id, name, dan arguments (string JSON). Biasanya dihasilkan oleh server, dan klien juga dapat menggunakannya untuk melengkapi catatan pemanggilan fungsi dalam konteks historis.
    • function_call_output: hasil eksekusi tool. Anda harus menentukan call_id dan output (string JSON). Setelah menerima function_call, klien menjalankan tool dan menulis kembali hasil eksekusi dengan tipe ini.
    Parameter opsional previous_item_id menentukan item percakapan yang sudah ada setelah item baru disisipkan, sehingga memungkinkan penyisipan konten di posisi mana pun dalam riwayat percakapan. Jika parameter ini tidak dikirim, item percakapan baru secara default ditambahkan di akhir percakapan.
    • Sisipkan pesan pengguna pada posisi tertentu:
{
    "type": "conversation.item.create",
    "previous_item_id": "item_abc",
    "item": {
        "type": "message",
        "role": "user",
        "content": [
            { "type": "input_text", "text": "请帮我总结一下上次的对话" }
        ]
    }
}
  • Tulis kembali hasil eksekusi Function Calling:
{
    "type": "conversation.item.create",
    "item": {
        "type": "function_call_output",
        "call_id": "call_xxx",
        "output": "{\"temperature\":18,\"condition\":\"晴\"}"
    }
}
Jika item.id yang ditentukan oleh conversation.item.create sudah ada dalam percakapan, kesalahan akan dikembalikan.
  • Ambil item percakapan (conversation.item.retrieve): ambil item percakapan yang tersimpan di server. Untuk konten bertipe audio, hanya teks transkripsi yang dikembalikan, bukan data audio mentahnya.
{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}
  • Hapus item percakapan (conversation.item.delete): hapus item tertentu dari konteks percakapan.
{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

Hotword instan

Nama orang, nama produk, atau istilah industri mudah dikenali sebagai kata homofon. Setelah hotword instan dikonfigurasi, model memprioritaskan pengenalan kata-kata ini saat mentranskripsi audio input. Misalnya, nama proyek dalam potongan audio yang sama ditranskripsi sebagai "7yuan project" sebelum hotword dikonfigurasi. Setelah "Qiyuan" ditetapkan sebagai hotword, hasil transkripsinya menjadi "Qiyuan project". Model Plus dan Flash Qwen-Audio-Realtime 3.0 dan 3.1 semuanya mendukung hotword instan, berlaku untuk akses WebSocket, WebRTC, dan AOQ di region Beijing dan Singapura. Sebelum mengirim audio, gunakan event session.update berikut untuk mengonfigurasi hotword.
{
    "type": "session.update",
    "session": {
        "input_audio_transcription": {
            "corpus": {
                "vocabulary": {
                    "祺元": 50
                }
            }
        }
    }
}
Kirim audio hanya setelah session.updated diterima. Ambil transkripsi akhir dari field transcript pada event conversation.item.input_audio_transcription.completed. Anda dapat mengirim session.update lagi selama sesi untuk mengirimkan kosakata baru yang lengkap. Menetapkan vocabulary ke {} akan menghapus hotword.

Transkripsi audio ambien

Hanya mode smart_turn / smart_turn_v2. Ketika VAD mendeteksi aktivitas suara tetapi secara semantik menentukan bahwa itu bukan giliran yang valid (seperti kebisingan atau konten tanpa makna seperti "uh" atau "ah"), server tidak memicu giliran percakapan; sebagai gantinya, server meneruskan hasil pengenalan ASR ke klien melalui event ambient_audio_transcription. Hasil transkripsi ini tidak ditulis ke dalam konteks percakapan.
{
    "type": "conversation.item.ambient_audio_transcription.delta",
    "item_id": "item_xxx",
    "text": "嗯",
    "stash": ""
}
Serupa dengan event transkripsi ucapan pengguna, transkripsi audio ambien juga mencakup tahap delta dan completed. Pengembang dapat menggunakan event ini untuk mengimplementasikan fitur seperti pemantauan audio ambien dan kesadaran skenario percakapan.

Peningkatan speaker

Hanya mode smart_turn / smart_turn_v2. Kirimkan URL audio yang direkam sebelumnya oleh pengguna target dalam session.update, dan model akan mengunci pembicara tersebut secara presisi dalam percakapan duplex, secara efektif mengabaikan suara lain dan kebisingan latar belakang, memungkinkan interaksi duplex yang lancar dalam skenario terbuka. Konfigurasi: kirimkan URL audio voiceprint yang dapat diakses publik dalam turn_detection.voiceprint_audio_urls pada session.update pertama.
{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "smart_turn_v2",
            "voiceprint_audio_urls": [
                "https://example.com/speaker.wav"
            ]
        }
    }
}
Persyaratan parameter:
  • Maksimal 5 URL didukung, dan format audio harus PCM atau WAV 16 kHz.
  • Parameter ini hanya berlaku pada session.update pertama; input berikutnya diabaikan.
Event pendaftaran: setelah menerima konfigurasi, server secara asinkron melakukan pendaftaran voiceprint dan memberi tahu hasilnya melalui event berikut:
  • voiceprint_audio_list.in_progress: pendaftaran telah dimulai, dikirim sebelum session.updated dikembalikan, membawa item_id yang mengidentifikasi tugas ini.
  • voiceprint_audio_list.completed: pendaftaran berhasil, dengan item_id yang cocok dengan milik in_progress.
  • voiceprint_audio_list.failed: pendaftaran gagal, dengan field reason yang menjelaskan penyebabnya (misalnya, URL audio tidak dapat diakses). Kegagalan pendaftaran tidak memblokir percakapan normal.

Peluncuran

Siapkan kebijakan toleransi kesalahan

  • Koneksi ulang klien: Klien harus mengimplementasikan mekanisme koneksi ulang otomatis untuk menangani jitter jaringan. Kami menyarankan menetapkan sinyal koneksi ulang dalam callback on_error dan mencoba ulang dengan kebijakan exponential backoff (misalnya, tunggu 1 dtk → 2 dtk → 4 dtk).
  • Klasifikasi dan penanganan kesalahan: Kesalahan klien (invalid_request_error) tidak memutus koneksi; Anda hanya perlu mencatatnya atau menyesuaikan parameter. Kesalahan server (server_error) mengakhiri koneksi dan memerlukan koneksi ulang.
  • Penanganan barge-in: Dalam mode server_vad / smart_turn / smart_turn_v2, ucapan pengguna baru otomatis menginterupsi respons model yang sedang berlangsung (response.done mengembalikan status=cancelled). Klien harus segera menghentikan pemutaran audio yang dibuffer saat menerima input_audio_buffer.speech_started untuk menghindari ucapan yang tumpang tindih.

Siklus hidup koneksi

Siklus hidup sesi WebSocket yang khas adalah sebagai berikut:
  1. Membuat koneksi: Klien memulai koneksi WebSocket, dan server mengembalikan event session.created.
  2. Konfigurasi: Klien mengirim session.update untuk mengatur parameter seperti mode interaksi, suara, dan tool. Langkah ini harus diselesaikan sebelum audio pertama dikirim.
  3. Interaksi: Klien terus-menerus mengirim streaming audio (input_audio_buffer.append), dan server melakukan inferensi yang dipicu oleh deteksi VAD atau pemicu manual, lalu mengembalikan ucapan dan teks secara streaming.
  4. Menutup: Klien menutup koneksi WebSocket secara proaktif. Jika koneksi menganggur terlalu lama, server juga dapat memutuskannya secara proaktif.
Untuk mempertahankan transkripsi giliran terakhir, tunggu event transkripsi selesai atau transkripsi gagal untuk item_id terkait sebelum menutup koneksi. response.done hanya menandakan respons model telah selesai; hasil transkripsi dapat dikembalikan lebih lambat.

Optimasi latensi

  • Ukuran chunk audio: Kami menyarankan mengirim 100 md data audio setiap kali (16 kHz × 16 bit × mono = 3200 byte per pengiriman), yang memastikan kinerja real-time sekaligus menghindari permintaan jaringan yang terlalu sering.
  • Pemutaran streaming: Dekode dan putar audio segera setelah menerima response.audio.delta; jangan menunggu response.done untuk memutar seluruh segmen.
  • Bersihkan buffer segera saat barge-in: Saat menerima input_audio_buffer.speech_started, segera bersihkan buffer pemutaran lokal untuk mencegah audio lama terus diputar dan menimbulkan latensi yang dirasakan.

Model dan region yang didukung

  • Singapura
  • Tiongkok (Beijing)
Saat memanggil model berikut, pilih API Key di region 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

FAQ

Apa yang dibatasi oleh RPM? Apakah membatasi jumlah total koneksi yang terbuka secara bersamaan?

RPM membatasi jumlah permintaan koneksi WebSocket per menit. Beberapa giliran respons dalam koneksi yang sama tidak dihitung terpisah; koneksi ulang dihitung sebagai permintaan baru. Saat ini, tidak ada batasan terpisah untuk jumlah total koneksi yang terbuka secara bersamaan.

Referensi API

Untuk prosedur dan contoh akses layanan melalui AOQ, lihat Akses AOQ. Untuk pemilihan protokol dan titik masuk referensi, lihat Referensi API.