Skip to main content
Multimodal Real-time

Python SDK

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

Prasyarat

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

Memulai

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: "Cherry"
  • Qwen-Omni-Turbo-Realtime: "Chelsie"
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 seri Qwen3-Omni-Flash-Realtime.
  • 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 yang digunakan untuk mentranskripsi input audio. Saat ini, hanya "gummy-realtime-v1" yang didukung.
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].

Antarmuka utama

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.

FAQ

Q: Bagaimana cara menyelaraskan input audio dan gambar?

Qwen-Omni-Realtime menggunakan audio sebagai garis waktu untuk inputnya. Gambar disisipkan ke dalam aliran audio berdasarkan waktu pengirimannya. Anda dapat menyisipkan gambar pada titik mana pun di garis waktu audio. Dalam skenario interaksi waktu nyata, Anda dapat mengaktifkan atau menonaktifkan input video kapan saja.

Q: Berapa frekuensi yang direkomendasikan untuk memasukkan gambar dan audio?

Dalam skenario interaksi waktu nyata, Anda dapat mengirim gambar pada laju frame 1 fps atau 2 fps dan audio dalam paket 100 ms.

Q: Apa perbedaan antara dua mode saklar turn_detection?

Saat ini, hanya mode server_vad yang didukung ketika turn_detection diaktifkan:
  • Jika "turn_detection" diaktifkan:
    • Keadaan input: VAD berbasis cloud menentukan akhir kalimat berdasarkan input audio. Kemudian secara otomatis memanggil model Qwen-Omni untuk inferensi dan mengirimkan respons teks dan audio.
    • Keadaan respons: Dalam keadaan ini, input audio dan video dapat terus berlanjut tanpa gangguan selama fase respons model. Setelah respons selesai, keadaan kembali ke keadaan input untuk menunggu masukan suara.
    • Interrupsi: Jika pengguna mulai berbicara selama respons model, interupsi dipicu. Layanan segera menghentikan respons saat ini dan beralih ke keadaan input.
  • Jika "turn_detection" dinonaktifkan:
    • Anda harus menentukan akhir giliran input audio dan video sendiri. Kemudian, Anda harus secara manual memicu inferensi model Qwen-Omni untuk mendapatkan respons menggunakan commit dan create_response.
    • Selama keadaan respons model, Anda harus menghentikan input audio dan video. Anda dapat melanjutkan input untuk giliran berikutnya hanya setelah model selesai merespons.
    • Anda harus menggunakan antarmuka cancel_response untuk menginterupsi respons model.
Catatan bahwa ketika "turn_detection" diaktifkan, Anda masih dapat secara aktif memicu respons menggunakan commit dan create_response, dan secara aktif menginterupsi menggunakan cancel_response.

Q: Mengapa memilih model lain untuk input_audio_transcription?

Qwen-Omni-Realtime adalah model multimodal ujung-ke-ujung. Karena output teksnya adalah respons terhadap input, ia tidak langsung menghasilkan transkripsi dari input audio. Anda perlu mengintegrasikan model Pengenalan Suara Otomatis (ASR) lain untuk transkripsi.
Penggunaan API
Generasi teks
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Real-time multimodal
Realtime API
Penyematan Teks
Lainnya Model
Toolkit/Framework
TokenPlan
Model production
Manajemen file
Penagihan
Manajemen Model
Lebih Banyak Tentang Model