Skip to main content

Qwen-Omni-Realtime Python SDK

Topik ini menjelaskan antarmuka utama dan parameter permintaan untuk memanggil Qwen-Omni-Realtime menggunakan DashScope Python SDK.

Untuk koneksi dan autentikasi, lihat Akses WebSocket. Untuk bidang peristiwa dan contoh JSON, lihat Peristiwa klien dan Peristiwa server.

Prasyarat

Versi SDK Anda harus 1.23.9 atau yang lebih baru. Sebelum memulai, tinjau Alur interaksi multimodal waktu nyata.

Mulai cepat

Kunjungi GitHub untuk mengunduh kode contoh. Kami menyediakan kode contoh untuk tiga metode pemanggilan:
  1. Contoh percakapan audio: Menangkap input audio waktu nyata dari mikrofon, mengaktifkan mode Deteksi Aktivitas Suara (VAD), dan mendukung interupsi suara.
    enable_turn_detection diatur menjadi True.
    Gunakan headphone untuk pemutaran audio agar mencegah gema yang memicu interupsi suara.
  2. Contoh percakapan audio dan video: Menangkap input audio dan video waktu nyata dari mikrofon dan Kamera, mengaktifkan mode VAD, dan mendukung interupsi suara.
    enable_turn_detection diatur menjadi True.
    Gunakan headphone untuk pemutaran audio agar mencegah gema yang memicu interupsi suara.
  3. Pemanggilan lokal: Menggunakan audio dan gambar lokal sebagai input dan mengaktifkan mode Manual, yang memungkinkan Anda mengontrol kecepatan pengiriman secara manual.
    enable_turn_detection diatur menjadi False.

Parameter permintaan

Anda dapat menyetel parameter permintaan berikut menggunakan metode konstruktor (init) dari kelas OmniRealtimeConversation.

Parameter

Tipe

Deskripsi

model

str

Nama model Qwen-Omni. Untuk informasi lebih lanjut, lihat Daftar Model.

url

str

Alamat panggilan:

  • Wilayah Singapura: wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime

  • Wilayah Beijing: wss://dashscope.aliyuncs.com/api-ws/v1/realtime

Anda dapat mengonfigurasi parameter permintaan berikut menggunakan antarmuka update_session.
ParameterTipeDeskripsi
output_modalitieslist[MultiModality]Modalitas output model. Setel ke [MultiModality.TEXT] untuk menghasilkan hanya teks, atau [MultiModality.TEXT, MultiModality.AUDIO] untuk menghasilkan baik audio maupun teks.
voicestrSuara untuk audio yang dihasilkan oleh model. Untuk daftar suara yang didukung, lihat Daftar Suara.Suara default:
  • qwen3-omni-flash-realtime-2025-09-15: "Cherry"
input_audio_formatAudioFormatFormat audio input pengguna. Saat ini, hanya PCM_16000HZ_MONO_16BIT yang didukung.
output_audio_formatAudioFormatFormat audio output model. Saat ini, hanya PCM_24000HZ_MONO_16BIT yang didukung.
smooth_outputboolParameter ini hanya didukung oleh qwen3-omni-flash-realtime-2025-09-15.
  • True: Dapatkan respons percakapan.
  • False: Dapatkan respons gaya formal tertulis.
    Namun, ini dapat menghasilkan kualitas buruk jika kontennya sulit dibaca dengan lantang.
  • None: Model secara otomatis memilih gaya respons percakapan atau formal.
instructionsstrPesan sistem yang menetapkan tujuan atau peran model.Sebagai contoh: Anda adalah agen AI untuk hotel bintang lima. Jawab pertanyaan pelanggan tentang jenis kamar, fasilitas, harga, dan kebijakan pemesanan. Bersikaplah akurat dan ramah. Selalu tanggapi dengan sikap profesional dan membantu. Jangan memberikan informasi yang tidak diverifikasi atau informasi di luar cakupan layanan hotel.
enable_input_audio_transcriptionboolMenentukan apakah akan mengaktifkan pengenalan suara untuk input audio.
input_audio_transcription_modelstrModel pengenalan suara untuk mentranskripsi input audio ditetapkan ke qwen3-asr-flash-realtime dan tidak dapat diubah.
turn_detection_typestrJenis VAD sisi server. Ini tetap pada "server_vad".
turn_detection_thresholdfloatAmbang batas deteksi VAD. Tingkatkan nilai ini di lingkungan bising dan turunkan di lingkungan tenang.
  • Semakin dekat nilai ke -1, semakin besar kemungkinan kebisingan terdeteksi sebagai suara.
  • Semakin dekat nilai ke 1, semakin kecil kemungkinan kebisingan terdeteksi sebagai suara.
Nilai default: 0,2. Nilai valid: [-1,0, 1,0].
turn_detection_silence_duration_msintDurasi keheningan yang menandakan akhir pembicaraan. Jika durasi ini terlampaui, model memicu respons. Nilai default: 800. Nilai valid: [200, 6000].

Referensi API

Kelas OmniRealtimeConversation

Anda dapat mengimpor kelas OmniRealtimeConversation menggunakan pernyataan from dashscope.audio.qwen_omni import OmniRealtimeConversation.
Signature MetodeEvent respons server (dikirim melalui callback)Deskripsi
def connect(self,) -> None
session.created
Sesi dibuat
session.updated
Konfigurasi sesi diperbarui
Membuat koneksi dengan server.
def update_session(self,
                       output_modalities: list[MultiModality],
                       voice: str,
                       input_audio_format: AudioFormat = AudioFormat.
                       PCM_16000HZ_MONO_16BIT,
                       output_audio_format: AudioFormat = AudioFormat.
                       PCM_24000HZ_MONO_16BIT,
                       enable_input_audio_transcription: bool = True,
                       input_audio_transcription_model: str = None,
                       enable_turn_detection: bool = True,
                       turn_detection_type: str = 'server_vad',
                       prefix_padding_ms: int = 300,
                       turn_detection_threshold: float = 0.2,
                       turn_detection_silence_duration_ms: int = 800,
                       turn_detection_param: dict = None,
                       smooth_output: bool = True
                       **kwargs) -> None
session.updated
Konfigurasi sesi diperbarui
Memperbarui konfigurasi default untuk interaksi sesi saat ini. Untuk konfigurasi parameter, lihat bagian "Parameter permintaan".Setelah Anda membuat koneksi, server segera mengembalikan konfigurasi input dan output default untuk sesi. Untuk memperbarui konfigurasi sesi default, panggil antarmuka ini segera setelah koneksi dibuat.Setelah server menerima event session.update, ia melakukan verifikasi parameter. Jika parameter tidak valid, kesalahan dikembalikan. Jika tidak, konfigurasi sesi di sisi server diperbarui.
def append_audio(self, audio_b64: str) -> None
NoneMenambahkan segmen data audio yang dikodekan Base64 ke buffer audio cloud input. Buffer audio adalah penyimpanan sementara yang dapat Anda tulis dan commit nanti.
  • Jika "turn_detection" diaktifkan, buffer audio digunakan untuk deteksi suara, dan server memutuskan kapan harus commit.
  • Jika "turn_detection" dinonaktifkan, klien dapat memilih jumlah audio yang ditempatkan dalam setiap event, hingga maksimum 15 MiB. Misalnya, streaming blok data yang lebih kecil dari klien dapat membuat VAD lebih responsif.
def append_video(self, video_b64: str) -> None
NoneMenambahkan data gambar yang dikodekan Base64 ke buffer video cloud. Data gambar bisa berupa gambar lokal atau gambar yang ditangkap secara real-time dari aliran video.Berikut adalah batasan untuk input gambar:
  • Format gambar harus JPG atau JPEG. Resolusi gambar yang direkomendasikan adalah 480p atau 720p, dengan maksimum 1080p.
  • Ukuran satu gambar tidak boleh melebihi 500 KB (sebelum pengkodean Base64).
  • Data gambar harus dikodekan Base64.
  • Kirim gambar ke server dengan frekuensi 1 gambar/detik.
def clear_appended_audio(self, ) -> None
input_audio_buffer.cleared
Menghapus audio yang diterima oleh server
Menghapus audio dari buffer cloud saat ini.
def commit(self, ) -> None
input_audio_buffer.committed
Server menerima audio yang telah dicommit
Mengcommit audio dan video yang sebelumnya ditambahkan ke buffer cloud menggunakan append. Terjadi kesalahan jika buffer audio input kosong.
  • Jika "turn_detection" diaktifkan, klien tidak perlu mengirim event ini. Server secara otomatis mengcommit buffer audio.
  • Jika "turn_detection" dinonaktifkan, klien harus mengcommit buffer audio untuk membuat item pesan pengguna.
Catatan :
  1. Jika transkripsi audio dikonfigurasikan untuk sesi menggunakan input_audio_transcription, sistem mentranskripsi audio.
  2. Mengcommit buffer audio input tidak menciptakan respons dari model.
def create_response(self,
        instructions: str = None,
        output_modalities: list[MultiModality] = None) -> None
response.created
Server mulai menghasilkan respons
response.output_item.added
Konten output baru tersedia dalam respons
conversation.item.created
Item percakapan dibuat
response.content_part.added
Konten baru ditambahkan ke item pesan asisten
response.audio_transcript.delta
Teks transkripsi yang dihasilkan secara bertahap
response.audio.delta
Audio yang dihasilkan secara bertahap dari model
response.audio_transcript.done
Transkripsi teks selesai
response.audio.done
Pembuatan audio selesai
response.content_part.done
Streaming konten teks atau audio untuk pesan asisten selesai
response.output_item.done
Streaming seluruh item output untuk pesan asisten selesai
response.done
Respons selesai
Menginstruksikan server untuk membuat respons model.Ketika sesi dikonfigurasikan dengan mode "turn_detection" diaktifkan, server secara otomatis membuat respons model.
def cancel_response(self, ) -> None
NoneMembatalkan respons yang sedang berlangsung. Jika tidak ada respons untuk dibatalkan, server merespons dengan kesalahan.
def close(self, ) -> None
NoneMengakhiri tugas dan menutup koneksi.
def get_session_id(self) -> str
NoneMendapatkan session_id dari tugas saat ini.
def get_last_response_id(self) -> str
NoneMendapatkan response_id dari respons terakhir.
def get_last_first_text_delay(self)
NoneMendapatkan latensi teks paket pertama dari respons terakhir.
def get_last_first_audio_delay(self)
NoneMendapatkan latensi audio paket pertama dari respons terakhir.

OmniRealtimeCallback

Server menggunakan callback untuk mengembalikan event respons dan data ke klien. Anda harus mengimplementasikan metode callback untuk menangani informasi atau data yang dikembalikan oleh server. Impor antarmuka menggunakan pernyataan from dashscope.audio.qwen_omni import OmniRealtimeCallback.
MetodeParameterNilai kembaliDeskripsi
def on_open(self) -> None
NoneNoneMetode ini dipanggil segera setelah koneksi dengan server dibuat.
def on_event(self, message: str) -> None
message: Event respons server.NoneTermasuk respons terhadap panggilan antarmuka dan teks serta audio yang dihasilkan oleh model. Untuk informasi lebih lanjut, lihat Event server
def on_close(self, close_status_code, close_msg) -> None
close_status_code: Kode status untuk menutup WebSocket.close_msg: Pesan penutupan untuk WebSocket.NoneMetode ini dipanggil setelah layanan menutup koneksi.