Skip to main content

Qwen-ASR-Realtime Python SDK - Referensi API

Kirimkan audio secara streaming ke Qwen-ASR-Realtime melalui WebSocket dan terima hasil transkripsi real-time menggunakan DashScope Python SDK.

Prasyarat

Sebelum memulai, pastikan Anda telah memiliki:
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah Tiongkok (Beijing) dan Singapura. Domain khusus baru ini menawarkan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru berikut:
  • Tiongkok (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya. Domain lama tetap berfungsi sepenuhnya.

Mulai cepat

Kode contoh membaca your_audio_file.pcm (PCM16, 16 kHz, mono). Jika Anda hanya memiliki format MP3, WAV, atau serupa, konversi dengan ffmpeg:
ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm
Python
import logging
import os
import signal
import sys
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor

# Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/model-studio/get-api-key
# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Alibaba Cloud Model Studio Anda: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # Berikut adalah konfigurasi untuk wilayah Singapura (ap-southeast-1). Saat memanggil, ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Konfigurasi berbeda berdasarkan wilayah.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

def setup_logging():
    """Konfigurasi output log"""
    logger = logging.getLogger('dashscope')
    logger.setLevel(logging.DEBUG)
    handler = logging.StreamHandler(sys.stdout)
    handler.setLevel(logging.DEBUG)
    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    logger.propagate = False
    return logger

def handle_event(event):
    """Menangani satu event dari sisi server"""
    kind = event.get('type')
    if kind == 'session.created':
        print(f"Start session: {event['session']['id']}")
    elif kind == 'conversation.item.input_audio_transcription.completed':
        print(f"Final recognized text: {event['transcript']}")
    elif kind == 'conversation.item.input_audio_transcription.text':
        print(f"Got transcription result: {event['text'] + event['stash']}")
    elif kind == 'input_audio_buffer.speech_started':
        print('======Speech Start======')
    elif kind == 'input_audio_buffer.speech_stopped':
        print('======Speech Stop======')

def receive_events(session):
    """Menerima dan memproses event dari sisi server"""
    for event in session.events():
        handle_event(event)

def read_audio_chunks(file_path, chunk_size=3200):
    """Membaca file audio dalam chunk"""
    with open(file_path, 'rb') as f:
        while chunk := f.read(chunk_size):
            yield chunk

def send_audio(session, file_path, delay=0.1):
    """Kirim data audio"""
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"File audio {file_path} tidak ada.")

    print("Memproses file audio... Tekan 'Ctrl+C' untuk berhenti.")
    for chunk in read_audio_chunks(file_path):
        session.append_audio(chunk)  # bytes otomatis dikodekan Base64 sebelum dikirim
        time.sleep(delay)

def main():
    setup_logging()

    audio_file_path = "./your_audio_file.pcm"

    # Memasuki konteks with otomatis membuat koneksi
    with client.audio.realtime.connect(
        model='qwen3-asr-flash-realtime',
    ) as session:
        def handle_exit(sig, frame):
            print('Ctrl+C ditekan, keluar...')
            session.close()
            sys.exit(0)

        signal.signal(signal.SIGINT, handle_exit)

        # Perbarui konfigurasi sesi: hanya output teks, dengan transkripsi input audio diaktifkan
        session.update_session(
            output_modalities=['text'],
            enable_input_audio_transcription=True,
            transcription_params={
                'language': 'zh',
                'sample_rate': 16000,
                'input_audio_format': 'pcm',
            },
        )
        # Baca hingga session.updated untuk memastikan konfigurasi telah berlaku
        for event in session.events():
            if event.get('type') == 'session.updated':
                break

        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            try:
                send_audio(session, audio_file_path)
                # kirim session.finish dan tunggu hingga selesai lalu tutup
                session.end_session()
                receiver.result()
            finally:
                # close harus dijalankan di dalam konteks pool agar receiver tidak terblokir
                session.close()
        print("Pemrosesan audio selesai.")

if __name__ == '__main__':
    main()

Parameter permintaan

  • Parameter berikut diatur melalui metode client.audio.realtime.connect.
    # Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Alibaba Cloud Model Studio Anda: api_key="sk-xxx"
    client = dashscope.Client(
        api_key=os.environ.get('DASHSCOPE_API_KEY'),
        # Berikut adalah konfigurasi untuk wilayah Singapura (ap-southeast-1). Saat memanggil, ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Konfigurasi berbeda berdasarkan wilayah.
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
    )
    
    # Buat sesi pengenalan real-time: memasuki konteks with otomatis membuat koneksi
    session = client.audio.realtime.connect(
        model='qwen3-asr-flash-realtime',
    )
    

    Parameter

    Tipe

    Wajib

    Deskripsi

    model

    str

    Ya

    Nama model yang akan digunakan.

    ws_url

    str

    Tidak

    Endpoint WebSocket lengkap; jika tidak ditentukan, endpoint dipilih otomatis berdasarkan workspace dan region dari Client:

    • Wilayah Tiongkok (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime. Saat memanggil, ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya.

    • Wilayah Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya.

  • Parameter berikut diatur melalui metode update_session milik RealtimeSession.
    session.update_session(
        output_modalities=['text'],
        enable_turn_detection=True,
        turn_detection_type="server_vad",
        turn_detection_threshold=0.0,
        turn_detection_silence_duration_ms=400,
        enable_input_audio_transcription=True,
        transcription_params={
            'language': 'zh',
            'sample_rate': 16000,
            'input_audio_format': 'pcm',
        },
    )
    

    Parameter

    Tipe

    Wajib

    Deskripsi

    output_modalities

    List[str]

    Ya

    Modalitas output model, tetap diatur sebagai ["text"].

    enable_turn_detection

    bool

    Tidak

    Mengaktifkan atau menonaktifkan Voice Activity Detection (VAD) di sisi server. Jika dinonaktifkan, Anda harus memanggil metode commit() secara manual untuk memicu pengenalan.

    Nilai default: True.

    Rentang nilai:

    • True: aktif

    • False: nonaktif

    turn_detection_type

    str

    Tidak

    Jenis VAD sisi server, tetap diatur sebagai server_vad.

    turn_detection_threshold

    float

    Tidak

    Ambang batas deteksi VAD. Disarankan mengatur nilai ini ke 0.0.

    Nilai default: 0.5.

    Rentang nilai: [-1, 1].

    Ambang batas yang lebih rendah meningkatkan sensitivitas VAD dan dapat salah mendeteksi kebisingan latar sebagai ucapan. Ambang batas yang lebih tinggi menurunkan sensitivitas dan membantu mengurangi pemicuan salah di lingkungan yang bising.

    turn_detection_silence_duration_ms

    int

    Tidak

    Ambang batas durasi diam (ms) untuk segmentasi VAD. Diam yang berlangsung melebihi ambang batas ini dianggap sebagai akhir pernyataan. Disarankan mengatur nilai ini ke 400.

    Nilai default: 800.

    Rentang nilai: [200, 6000].

    Nilai yang lebih rendah (misalnya 300 ms) membuat model merespons lebih cepat, tetapi dapat menyebabkan segmentasi yang tidak wajar pada jeda alami. Nilai yang lebih tinggi (misalnya 1200 ms) lebih baik menangani jeda dalam kalimat panjang, tetapi menambah latensi respons keseluruhan.

    transcription_params

    dict

    Tidak

    Konfigurasi terkait pengenalan ucapan.

  • Parameter berikut diatur melalui dictionary transcription_params pada update_session.
    session.update_session(
        output_modalities=['text'],
        enable_input_audio_transcription=True,
        transcription_params={
            'language': 'zh',
            'sample_rate': 16000,
            'input_audio_format': 'pcm',
        },
    )
    

    Parameter

    Tipe

    Wajib

    Deskripsi

    language

    str

    Tidak

    Bahasa sumber audio.

    • zh: Tionghoa (Mandarin, Sichuan, Minnan, Wu)

    • yue: Kanton

    • en: Inggris

    • ja: Jepang

    • de: Jerman

    • ko: Korea

    • ru: Rusia

    • fr: Prancis

    • pt: Portugis

    • ar: Arab

    • it: Italia

    • es: Spanyol

    • hi: Hindi

    • id: Indonesia

    • th: Thai

    • tr: Turki

    • uk: Ukraina

    • vi: Vietnam

    • cs: Ceko

    • da: Denmark

    • fil: Filipino

    • fi: Finlandia

    • is: Islandia

    • ms: Melayu

    • no: Norwegia

    • pl: Polandia

    • sv: Swedia

    sample_rate

    int

    Tidak

    Laju sampel audio (Hz). Mendukung 16000 dan 8000.

    Nilai default: 16000.

    Saat diatur ke 8000, server akan melakukan upsampling ke 16000 Hz terlebih dahulu sebelum pengenalan, yang dapat menimbulkan sedikit latensi. Disarankan hanya digunakan saat audio sumber berformat 8000 Hz (misalnya saluran telepon).

    input_audio_format

    str

    Tidak

    Format audio. Mendukung pcm dan opus.

    Nilai default: pcm.

Referensi API

RealtimeSession (client.audio.realtime.connect)

Sesi pengenalan real-time dibuat melalui client.audio.realtime.connect(model=...): koneksi dibuat setelah memasuki konteks with (atau memanggil metode connect() milik sesi).
Signature metodeEvent respons server (dikirim melalui events())Deskripsi
def connect(self) -> RealtimeSession
session.created
Sesi telah dibuat
session.updated
Konfigurasi sesi telah diperbarui
Membuat koneksi dengan server. Otomatis dipanggil saat memasuki konteks with; jangan memanggil connect() terlebih dahulu lalu memasuki with pada sesi yang sama.
def update_session(self,
                   output_modalities: List[str] = ...,
                   *,
                   voice: str = ...,
                   input_audio_format: str = ...,
                   output_audio_format: str = ...,
                   enable_input_audio_transcription: bool = ...,
                   input_audio_transcription_model: str = ...,
                   enable_turn_detection: bool = ...,
                   turn_detection_type: str = ...,
                   prefix_padding_ms: int = ...,
                   turn_detection_threshold: float = ...,
                   turn_detection_silence_duration_ms: int = ...,
                   turn_detection_param: dict = ...,
                   translation_params: dict = ...,
                   transcription_params: dict = ...,
                   ...) -> None
session.updated
Konfigurasi sesi telah diperbarui
Digunakan untuk memperbarui konfigurasi sesi; disarankan memanggil metode ini terlebih dahulu setelah koneksi dibuat. Jika metode ini tidak dipanggil, sistem akan menggunakan konfigurasi default. Cukup perhatikan parameter yang tercantum dalam Parameter permintaan.
def append_audio(self, audio_b64: Union[str, bytes]) -> None
Tidak adaMenambahkan potongan data audio ke buffer input audio di sisi cloud. str dianggap sebagai Base64 yang telah dikodekan; bytes otomatis dikodekan Base64.
  • Saat Parameter permintaan enable_turn_detection diatur ke True, buffer audio digunakan untuk mendeteksi ucapan dan server menentukan kapan commit dilakukan.
  • Saat Parameter permintaan enable_turn_detection diatur ke False, klien dapat memilih berapa banyak audio yang ditempatkan dalam setiap event, maksimal 15 MiB. Misalnya, streaming data berukuran lebih kecil dari klien dapat membuat VAD merespons lebih cepat.
def commit(self) -> None
input_audio_buffer.committed
Server menerima audio yang di-commit
Melakukan commit atas audio yang sebelumnya ditambahkan ke buffer cloud melalui append; jika buffer input audio kosong akan menghasilkan error.Skenario dilarang: saat Parameter permintaan enable_turn_detection diatur ke True.
def end_session(self) -> None
session.finished
Server menyelesaikan pengenalan ucapan dan mengakhiri sesi
Memberi tahu server untuk mengakhiri sesi; setelah menerima pemberitahuan akhir sesi, server akan menyelesaikan pengenalan ucapan terakhir.Waktu pemanggilan:
  • Pada mode VAD (default), panggil metode ini setelah selesai mengirim audio
  • Pada mode Manual, panggil metode ini setelah memanggil metode commit
def close(self) -> None
Tidak adaMenghentikan tugas dan menutup koneksi (idempoten, tidak mengirim session.finish).
session.session_id
session.last_response_id
Tidak adaMendapatkan session_id tugas saat ini dan response_id dari response terakhir (atribut).

Iterasi event (events())

Server mengembalikan event dan data responsnya ke klien melalui event. Anda perlu mengiterasi events() milik sesi pada thread penerima, dan mendistribusikan penanganan berdasarkan event["type"] (daftar event lengkap lihat event server).
def receive_events(session):
    for event in session.events():
        kind = event.get('type')
        if kind == 'session.created':
            print(f"Start session: {event['session']['id']}")
        elif kind == 'conversation.item.input_audio_transcription.completed':
            print(f"Final recognized text: {event['transcript']}")
        elif kind == 'conversation.item.input_audio_transcription.text':
            print(f"Got transcription result: {event['text'] + event['stash']}")
Signature metodeParameterDeskripsi
def events(self) -> Iterator[Dict]
event: event serverMembaca secara berkelanjutan dan menghasilkan event server (dict) satu per satu. Iterasi berakhir saat koneksi ditutup atau setelah menerima session.finished.
def recv_event(self) -> Optional[Dict]
Tidak adaMembaca satu event server secara blocking, tanpa perulangan otomatis; mengembalikan None saat tidak ada event (koneksi ditutup).