Topik ini memperkenalkan API utama dan parameter permintaan untuk memanggil model realtime Qwen-Omni dengan DashScope Java SDK.
Untuk koneksi dan autentikasi, lihat Akses WebSocket; untuk bidang event dan contoh JSON, lihat event klien dan event server.
Versi Java SDK Anda harus v2.22.15 atau lebih baru. Baca terlebih dahulu Alur kerja interaksi multimodal real-time.
Saat menggunakan
Parameter permintaan berikut dapat dikonfigurasi melalui metode berantai atau setter objek
Parameter permintaan berikut dapat dikonfigurasi melalui metode berantai atau setter objek
OmniRealtimeConversation diimpor melalui
Server mengembalikan event dan data respons ke klien melalui callback. Anda perlu mengimplementasikan metode callback untuk memproses informasi atau data yang dikembalikan oleh server.
Impor melalui
Prasyarat
Versi Java SDK Anda harus v2.22.15 atau lebih baru. Baca terlebih dahulu Alur kerja interaksi multimodal real-time.
Mulai cepat
Saat menggunakan qwen3.8-omni-flash-realtime, atur parameter konstruksi sesi model ke nama model ini; suara default adalah Tina. Untuk contoh konfigurasi sesi Java SDK dan parameter agregasi video, lihat panduan pemanggilan realtime.
Kunjungi github untuk mengunduh kode contoh. Kami menyediakan kode contoh untuk tiga metode pemanggilan:
-
Contoh percakapan audio: menangkap input audio real-time dari mikrofon, mengaktifkan mode VAD (mendeteksi awal dan akhir pembicaraan secara otomatis), dan mendukung interupsi suara.
Parameter enableTurnDetection harus diatur ke
true.Kami menyarankan menggunakan headphone untuk pemutaran audio guna mencegah gema memicu interupsi suara.
-
Contoh percakapan audio dan video: menangkap input audio dan video real-time dari mikrofon dan kamera, mengaktifkan mode VAD (mendeteksi awal dan akhir pembicaraan secara otomatis), dan mendukung interupsi suara.
Parameter enableTurnDetection harus diatur ke
true.Kami menyarankan menggunakan headphone untuk pemutaran audio guna mencegah gema memicu interupsi suara.
-
Pemanggilan lokal: menggunakan audio dan gambar lokal sebagai input, dan mengaktifkan mode Manual (mengontrol kecepatan pengiriman secara manual).
Parameter enableTurnDetection harus diatur ke
false.
Parameter permintaan
Parameter permintaan berikut dapat dikonfigurasi melalui metode berantai atau setter objek OmniRealtimeParam, lalu diteruskan sebagai parameter ke konstruktor OmniRealtimeConversation.
Parameter | Tipe | Deskripsi |
|---|---|---|
model | String | Nama model realtime Qwen-Omni. Lihat Model. |
url | String | Titik akhir:
Saat melakukan panggilan, ganti |
OmniRealtimeConfig, lalu diteruskan sebagai parameter ke API updateSession.
| Parameter | Tipe | Deskripsi |
|---|---|---|
| modalities | List<OmniRealtimeModality> | Pengaturan modalitas keluaran model, mendukung pengaturan [OmniRealtimeModality.TEXT] (keluaran teks saja) atau [OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO] (mengeluarkan audio dan teks). |
| voice | String | Suara audio yang dihasilkan oleh model. Untuk suara yang didukung, lihat daftar suara.Suara default:
|
| inputAudioFormat | OmniRealtimeAudioFormat | Format audio input pengguna. Saat ini hanya dapat diatur ke PCM_16000HZ_MONO_16BIT, yang menunjukkan aliran audio PCM dengan laju sampel 16 kHz. |
| outputAudioFormat | OmniRealtimeAudioFormat | Format audio keluaran model. Saat ini hanya dapat diatur ke PCM_24000HZ_MONO_16BIT, yang menunjukkan aliran audio PCM dengan laju sampel 24 kHz. Laju sampel keluaran kustom saat ini tidak didukung. |
| instructions | String | Pesan sistem, digunakan untuk menetapkan tujuan atau peran model.Contoh: Anda adalah agen layanan pelanggan AI di hotel bintang lima. Jawab pertanyaan pelanggan tentang jenis kamar, fasilitas, harga, dan kebijakan pemesanan secara akurat dan ramah. Selalu merespons dengan sikap profesional dan membantu, dan jangan pernah memberikan informasi yang tidak terverifikasi atau informasi di luar lingkup layanan hotel.instructions harus diatur melalui metode parameters dari instance OmniRealtimeConfig: |
| smooth_output | Boolean | Hanya qwen3-omni-flash-realtime-2025-09-15 yang mendukung pengaturan ini.
|
| enableInputAudioTranscription | Boolean | Apakah mengaktifkan pengenalan suara untuk audio input. |
| InputAudioTranscription | String | Model pengenalan suara yang digunakan untuk transkripsi audio input, ditetapkan ke qwen3-asr-flash-realtime, dan tidak dapat diubah |
| enableTurnDetection | Boolean | Apakah mengaktifkan deteksi aktivitas suara (VAD). Jika dinonaktifkan, pengguna mengirimkan audio secara manual untuk membuat respons omni. |
| turnDetectionType | String | Jenis VAD. Nilai yang valid:
|
| turnDetectionThreshold | Float | Ambang batas deteksi VAD. Disarankan untuk menaikkannya di lingkungan bising dan menurunkannya di lingkungan tenang.
|
| turnDetectionSilenceDurationMs | Integer | Durasi keheningan untuk mendeteksi berhentinya pembicaraan; setelah terlampaui, respons model dipicu. Default 800. Rentang nilai: [200, 6000]. |
| turnDetectionParam | Map | Parameter ekstensi VAD, digunakan untuk meneruskan item konfigurasi tambahan untuk turn_detection. Saat ini, idle_timeout_ms (Integer) didukung: periode habis waktu keheningan (dalam milidetik). Hanya berlaku saat menggunakan modelqwen3.5-omni-plus-realtimeatauqwen3.5-omni-flash-realtimedengan jenis VAD diatur keserver_vad. Setelah server selesai memutar audio dan pengguna tetap hening lebih lama dari durasi ini (tanpa speech.started terpicu), model akan secara proaktif memicu giliran respons untuk membimbing pengguna melanjutkan percakapan berdasarkan konteks saat ini. Rentang nilai: [5000, 30000].Contoh: turnDetectionParam(Map.of("idle_timeout_ms", 5000)) |
| enable_search | Boolean | Berlaku untuk model seri Qwen3.8-Omni-Flash-Realtime dan Qwen3.5-Omni-Realtime.Apakah mengaktifkan fitur pencarian web. Atur ke true untuk mengaktifkan; default adalah false. Saat diaktifkan, model dapat secara mandiri memutuskan apakah akan melakukan pencarian untuk menjawab pertanyaan langsung pengguna.
Pemanggilan alat (tools) dan pencarian web (enable_search) tidak kompatibel dan tidak dapat diaktifkan bersamaan. |
| search_options | Object | Konfigurasi opsi pencarian web. Hanya berlaku setelah enable_search diaktifkan. Saat ini, enable_source (Boolean) didukung, yang menunjukkan apakah akan mengembalikan daftar sumber hasil pencarian. Atur ke true untuk mengaktifkan.
|
| tools | List<Map<String, Object>> | Berlaku untuk model seri Qwen3.8-Omni-Flash-Realtime dan Qwen3.5-Omni-Realtime.Daftar definisi alat. Saat diaktifkan, model dapat secara mandiri memutuskan apakah akan memanggil alat eksternal untuk menjawab pertanyaan pengguna. Saat Function Calling terpicu, model tidak menghasilkan audio dan hanya mengembalikan parameter pemanggilan alat.Qwen3.8-Omni-Flash-Realtime dapat dikonfigurasi dengan alat Function Calling dan MCP dalam sesi yang sama. Untuk bidang konfigurasi MCP, lihat Event klien; untuk batasan pemanggilan, lihat Batasan pemanggilan MCP. tools dan enable_search tidak dapat diaktifkan bersamaan, dan batasan ini juga berlaku untuk MCP.Bidang berikut mendeskripsikan alat Function Calling. Setiap alat adalah Map yang berisi bidang berikut:
|
| temperature | Float | Suhu sampling, yang mengontrol keragaman konten yang dihasilkan model.Semakin tinggi suhu, semakin beragam konten yang dihasilkan; sebaliknya, semakin deterministik konten yang dihasilkan.Rentang nilai: [0, 2)Karena temperature dan top_p keduanya dapat mengontrol keragaman konten yang dihasilkan, kami menyarankan Anda hanya mengatur salah satunya.Nilai default temperature:
|
| top_p | Float | Ambang batas probabilitas untuk nucleus sampling, yang mengontrol keragaman konten yang dihasilkan model.Semakin tinggi top_p, semakin beragam konten yang dihasilkan; sebaliknya, semakin deterministik konten yang dihasilkan.Rentang nilai: (0, 1.0]Karena temperature dan top_p keduanya dapat mengontrol keragaman konten yang dihasilkan, kami menyarankan Anda hanya mengatur salah satunya.Nilai default top_p:
|
| top_k | Integer | Ukuran kumpulan kandidat sampling selama generasi. Misalnya, saat nilainya 50, hanya 50 token dengan skor tertinggi dalam satu proses generasi yang membentuk kumpulan kandidat untuk pengambilan acak. Nilai lebih besar meningkatkan keacakan generasi; nilai lebih kecil meningkatkan determinisme generasi. Nilai None, atau top_k lebih besar dari 100, berarti kebijakan top_k dinonaktifkan; dalam kasus ini hanya kebijakan top_p yang berlaku.Nilai harus lebih besar dari atau sama dengan 0.Nilai default top_k:
|
| max_tokens | Integer | Jumlah maksimum token yang dikembalikan oleh permintaan ini.Pengaturan qwen3.8-omni-flash-realtime menerima nilai dalam rentang [1, 65536]. Untuk model lain, nilai default dan nilai maksimum keduanya adalah panjang output maksimum model. Untuk panjang output maksimum setiap model, lihat Model.Parameter max_tokens berguna untuk skenario di mana Anda perlu membatasi jumlah kata (seperti menghasilkan ringkasan atau kata kunci), mengontrol biaya, atau mengurangi waktu respons.
|
| repetition_penalty | Float | Tingkat pengulangan dalam urutan berturut-turut selama generasi model. Meningkatkan repetition_penalty mengurangi pengulangan output model, dan 1.0 berarti tanpa penalti. qwen3.8-omni-flash-realtime mendukung nilai 0; model lain tidak memiliki rentang nilai ketat, asalkan nilainya lebih besar dari 0.Nilai default repetition_penalty:
|
| presence_penalty | Float | Mengontrol tingkat pengulangan konten yang dihasilkan model.Rentang nilai: [-2.0, 2.0]. Nilai positif mengurangi pengulangan, sedangkan nilai negatif meningkatkan pengulangan.Nilai default presence_penalty:
|
| seed | Integer | Mengatur parameter seed membuat proses generasi model lebih deterministik, dan biasanya digunakan agar model mengembalikan hasil yang konsisten pada setiap eksekusi.Jika Anda meneruskan nilai seed yang sama (yang Anda tentukan) pada setiap panggilan model dan menjaga parameter lain tetap tidak berubah, model akan mengembalikan hasil yang sama sebisa mungkin.Rentang nilai: 0 hingga 231−1, nilai default -1.
|
Referensi API
Kelas OmniRealtimeConversation
OmniRealtimeConversation diimpor melalui import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;.
| Tanda tangan metode | Event respons sisi server (dikirim melalui callback) | Deskripsi |
|---|---|---|
Event sisi serverSesi dibuatsession.updated Konfigurasi sesi diperbarui | Membangun koneksi dengan server. | |
session.updatedKonfigurasi sesi diperbarui | Memperbarui konfigurasi default untuk interaksi sesi ini. Untuk konfigurasi parameter, lihat bagian Parameter permintaan.Setelah Anda membangun koneksi, server segera mengembalikan konfigurasi input dan output default untuk sesi ini. Jika Anda perlu memperbarui konfigurasi sesi default, kami menyarankan Anda selalu memanggil API ini segera setelah membangun koneksi.Setelah menerima event session.update, server memvalidasi parameter. Jika ada parameter yang tidak valid, kesalahan dikembalikan; jika tidak, konfigurasi sesi sisi server diperbarui. | |
| Tidak ada | Menambahkan fragmen data audio yang dikodekan base64 ke buffer audio input sisi cloud. Buffer audio adalah penyimpanan sementara yang dapat Anda tulis dan kirim (commit) nanti.
| |
| Tidak ada | Menambahkan data gambar yang dikodekan base64 ke buffer video sisi cloud. Data gambar dapat berupa gambar lokal atau data gambar yang diambil secara real-time dari aliran video.Batasan berikut saat ini berlaku untuk input gambar:
| |
input_audio_buffer.clearedMenghapus audio yang diterima oleh server | Menghapus audio di buffer cloud saat ini. | |
input_audio_buffer.committedServer telah menerima audio yang dikirim (commit) | Mengirim (commit) audio dan video yang sebelumnya ditambahkan ke buffer cloud melalui append. Kesalahan terjadi jika buffer audio input kosong.
| |
Event sisi serverServer mulai menghasilkan responsresponse.output_item.added Konten output baru selama responsEvent sisi server Item percakapan dibuatresponse.content_part.added Konten output baru ditambahkan ke item pesan asistenresponse.audio_transcript.delta Teks transkripsi yang dihasilkan secara bertahapresponse.audio.delta Audio yang dihasilkan secara bertahap oleh modelresponse.audio_transcript.done Transkripsi teks selesairesponse.audio.done Pembuatan audio selesairesponse.content_part.done Streaming konten teks atau audio dari pesan Asisten selesairesponse.output_item.done Streaming seluruh item output dari pesan Asisten selesairesponse.done Respons selesai | Menginstruksikan server untuk membuat respons model.Saat sesi dikonfigurasikan dengan "turn_detection" diaktifkan, server secara otomatis membuat respons model. | |
| Tidak ada | Membatalkan respons yang sedang berlangsung. Jika tidak ada respons untuk dibatalkan, server merespons dengan kesalahan. | |
| Tidak ada | Mengirim event conversation.item.create ke server.Saat mengembalikan hasil alat Function Calling, item adalah JsonObject yang berisi bidang berikut:
item.type adalah mcp_approval_response; untuk bidangnya, lihat Respons persetujuan MCP di event klien. | |
| Tidak ada | Menghentikan tugas dan menutup koneksi. | |
| Tidak ada | Mendapatkan session_id dari tugas saat ini. | |
| Tidak ada | Mendapatkan response_id dari respons terbaru. |
Antarmuka Callback (OmniRealtimeCallback)
Server mengembalikan event dan data respons ke klien melalui callback. Anda perlu mengimplementasikan metode callback untuk memproses informasi atau data yang dikembalikan oleh server.
Impor melalui import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;.
| Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
| Tidak ada | Tidak ada | Metode ini dipanggil kembali segera setelah koneksi dengan server dibangun. | |
| message: event respons server. | Tidak ada | Termasuk respons terhadap panggilan API serta teks dan audio yang dihasilkan oleh model. Untuk informasi lebih lanjut, lihat Event server. | |
| code: kode status penutupan websocket.reason: alasan penutupan websocket. | Tidak ada | Metode ini dipanggil kembali setelah server menutup koneksi. |