Skip to main content

Qwen-Omni-Realtime Java SDK

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.

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:
  1. 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.
  2. 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.
  3. 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:

  • Wilayah Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime

  • Wilayah Beijing: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime

Saat melakukan panggilan, ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya.

Alibaba Cloud Model Studio telah meluncurkan domain khusus workspace untuk wilayah China (Beijing) dan Singapura, yang memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami menyarankan migrasi ke domain baru:
  • Wilayah China (Beijing): migrasi dari wss://dashscope.aliyuncs.com ke wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Wilayah Singapura: migrasi dari wss://dashscope-intl.aliyuncs.com ke wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} adalah ID workspace Anda, yang dapat Anda lihat di halaman Detail Workspace di konsol Alibaba Cloud Model Studio. Qwen3.8-Omni-Flash-Realtime harus menggunakan domain khusus workspace di atas; model sebelumnya dapat terus menggunakan domain asli.
Parameter permintaan berikut dapat dikonfigurasi melalui metode berantai atau setter objek OmniRealtimeConfig, lalu diteruskan sebagai parameter ke API updateSession.
ParameterTipeDeskripsi
modalitiesList<OmniRealtimeModality>Pengaturan modalitas keluaran model, mendukung pengaturan [OmniRealtimeModality.TEXT] (keluaran teks saja) atau [OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO] (mengeluarkan audio dan teks).
voiceStringSuara audio yang dihasilkan oleh model. Untuk suara yang didukung, lihat daftar suara.Suara default:
  • Qwen3.5-Omni: "Tina"
  • qwen3-omni-flash-realtime-2025-09-15: "Cherry"
inputAudioFormatOmniRealtimeAudioFormatFormat audio input pengguna. Saat ini hanya dapat diatur ke PCM_16000HZ_MONO_16BIT, yang menunjukkan aliran audio PCM dengan laju sampel 16 kHz.
outputAudioFormatOmniRealtimeAudioFormatFormat 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.
instructionsStringPesan 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:
conversation.updateSession(OmniRealtimeConfig.builder()
        .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
        .voice("Tina")
        .enableTurnDetection(true)
        .enableInputAudioTranscription(true)
        .parameters(Map.of(
                "instructions", "你是个人助理小云"
        ))
        .build()
);
smooth_outputBooleanHanya qwen3-omni-flash-realtime-2025-09-15 yang mendukung pengaturan ini.
  • true: Mendapatkan respons percakapan
  • false: Mendapatkan respons yang lebih tertulis dan formal
    Namun, hasilnya mungkin kurang baik jika kontennya sulit dibacakan.
  • null: Nilai default. Model secara otomatis memilih gaya respons percakapan atau tertulis
smooth_output harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
enableInputAudioTranscriptionBooleanApakah mengaktifkan pengenalan suara untuk audio input.
InputAudioTranscriptionStringModel pengenalan suara yang digunakan untuk transkripsi audio input, ditetapkan ke qwen3-asr-flash-realtime, dan tidak dapat diubah
enableTurnDetectionBooleanApakah mengaktifkan deteksi aktivitas suara (VAD). Jika dinonaktifkan, pengguna mengirimkan audio secara manual untuk membuat respons omni.
turnDetectionTypeStringJenis VAD. Nilai yang valid:
  • server_vad (default): Mendeteksi akhir pembicaraan pengguna berdasarkan fitur akustik.
  • semantic_vad: Mendeteksi akhir pembicaraan pengguna berdasarkan validitas semantik, dan dapat menyaring ucapan tanpa makna (seperti kata penggugah dan kebisingan latar). Didukung oleh model seri Qwen3.8-Omni-Flash-Realtime dan Qwen3.5-Omni-Realtime.
turnDetectionThresholdFloatAmbang batas deteksi VAD. Disarankan untuk menaikkannya di lingkungan bising dan menurunkannya di lingkungan tenang.
  • Semakin dekat nilainya ke -1, semakin tinggi probabilitas kebisingan diklasifikasikan sebagai pembicaraan.
  • Semakin dekat nilainya ke 1, semakin rendah probabilitas kebisingan diklasifikasikan sebagai pembicaraan.
Default 0.5. Rentang nilai: [-1.0, 1.0].
turnDetectionSilenceDurationMsIntegerDurasi keheningan untuk mendeteksi berhentinya pembicaraan; setelah terlampaui, respons model dipicu. Default 800. Rentang nilai: [200, 6000].
turnDetectionParamMapParameter 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_searchBooleanBerlaku 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.
enable_search dan search_options harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
Pemanggilan alat (tools) dan pencarian web (enable_search) tidak kompatibel dan tidak dapat diaktifkan bersamaan.
search_optionsObjectKonfigurasi 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.
search_options harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
toolsList<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:
  • type (String, wajib): Tetap "function".
  • function (Map, wajib): Definisi fungsi alat, berisi bidang berikut:
    • name (String, wajib): Nama kustom fungsi alat. Disarankan menggunakan nama yang sama dengan fungsi, seperti get_current_weather atau get_current_time.
    • description (String, opsional): Deskripsi kemampuan fungsi alat. Model merujuk bidang ini untuk memutuskan apakah akan menggunakan fungsi alat.
    • parameters (Map, opsional): Deskripsi parameter input fungsi alat. Model merujuk bidang ini untuk mengekstrak parameter input. Jika fungsi alat tidak memerlukan parameter input, Anda tidak perlu menentukan bidang ini. Bidang ini berisi bidang berikut:
      • type (String, wajib): Tetap "object".
      • properties (Map, opsional): Mendeskripsikan nama, tipe data, dan deskripsi setiap parameter input. Key adalah nama parameter input, dan Value adalah Map yang berisi tipe data (type) dan deskripsi (description).
      • required (List, opsional): Menentukan parameter input mana yang wajib.
search_options harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
temperatureFloatSuhu 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:
  • qwen3.8-omni-flash-realtime: 0.6
  • seri qwen3.5-omni-realtime: 0.7
  • qwen3-omni-flash-realtime-2025-09-15: 0.9
temperature harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
top_pFloatAmbang 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:
  • qwen3.8-omni-flash-realtime: 0.95
  • seri qwen3.5-omni-realtime: 0.8
  • qwen3-omni-flash-realtime-2025-09-15: 1.0
top_p harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
top_kIntegerUkuran 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:
  • qwen3.8-omni-flash-realtime: 20
  • seri qwen3.5-omni-realtime: 20
  • qwen3-omni-flash-realtime-2025-09-15: 50
top_k harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
max_tokensIntegerJumlah maksimum token yang dikembalikan oleh permintaan ini.
Pengaturan max_tokens tidak memengaruhi proses generasi model. Jika jumlah token yang dihasilkan model melebihi max_tokens, permintaan ini mengembalikan konten yang terpotong.
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.
max_tokens harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
repetition_penaltyFloatTingkat 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:
  • qwen3.8-omni-flash-realtime: 0
  • seri qwen3.5-omni-realtime: 1.0
  • Model lain: 1.05
repetition_penalty harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
presence_penaltyFloatMengontrol 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:
  • qwen3.8-omni-flash-realtime: 1
  • seri qwen3.5-omni-realtime: 1.5
  • Model lain: 0.0
Skenario yang berlaku:presence_penalty yang lebih tinggi cocok untuk skenario yang membutuhkan keragaman, keseruan, atau kreativitas, seperti penulisan kreatif atau curah gagasan.presence_penalty yang lebih rendah cocok untuk skenario yang membutuhkan konsistensi atau terminologi profesional, seperti dokumen teknis atau dokumen formal lainnya.
presence_penalty harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.
seedIntegerMengatur 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.
seed harus diatur melalui metode parameters dari instance OmniRealtimeConfig, dengan penggunaan yang sama seperti instructions.

Referensi API

Kelas OmniRealtimeConversation

OmniRealtimeConversation diimpor melalui import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;.
Tanda tangan metodeEvent respons sisi server (dikirim melalui callback)Deskripsi
public void connect() throws NoApiKeyException, InterruptedException
Event sisi server
Sesi dibuat
session.updated
Konfigurasi sesi diperbarui
Membangun koneksi dengan server.
public void updateSession(OmniRealtimeConfig config)
session.updated
Konfigurasi 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.
public void appendAudio(String audioBase64)
Tidak adaMenambahkan 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.
  • Saat "turn_detection" diaktifkan, buffer audio digunakan untuk deteksi pembicaraan, dan server memutuskan kapan harus mengirimkannya.
  • Saat "turn_detection" dinonaktifkan, klien dapat memilih jumlah audio yang ditempatkan dalam setiap event, hingga 15 MiB. Misalnya, streaming potongan yang lebih kecil dari klien dapat membuat VAD merespons lebih cepat.
public void appendVideo(String videoBase64)
Tidak adaMenambahkan 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:
  • Format gambar harus JPG atau JPEG. Resolusi gambar yang direkomendasikan adalah 480P atau 720P, dengan maksimum 1080P;
  • Satu gambar tidak boleh melebihi 256KB setelah pengkodean Base64. Kami menyarankan ukuran gambar asli sebelum pengkodean tidak melebihi 190KB;
  • Data gambar harus dikodekan Base64;
  • Kami menyarankan Anda mengirim gambar ke server dengan laju 1 gambar per detik;
public void clearAppendedAudio()
input_audio_buffer.cleared
Menghapus audio yang diterima oleh server
Menghapus audio di buffer cloud saat ini.
public void commit()
input_audio_buffer.committed
Server 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.
  • Saat "turn_detection" diaktifkan, klien tidak perlu mengirim event ini; server secara otomatis mengirim (commit) buffer audio.
  • Saat "turn_detection" dinonaktifkan, klien harus mengirim (commit) buffer audio untuk membuat item pesan pengguna.
Catatan:
  1. Jika input_audio_transcription dikonfigurasi untuk sesi untuk mentranskripsi audio, sistem akan mentranskripsi audio.
  2. Mengirim (commit) buffer audio input tidak menciptakan respons dari model.
public void createResponse(String instructions, List<OmniRealtimeModality> modalities)
Event sisi server
Server mulai menghasilkan respons
response.output_item.added
Konten output baru selama respons
Event sisi server
Item percakapan dibuat
response.content_part.added
Konten output baru ditambahkan ke item pesan asisten
response.audio_transcript.delta
Teks transkripsi yang dihasilkan secara bertahap
response.audio.delta
Audio yang dihasilkan secara bertahap oleh model
response.audio_transcript.done
Transkripsi teks selesai
response.audio.done
Pembuatan audio selesai
response.content_part.done
Streaming konten teks atau audio dari pesan Asisten selesai
response.output_item.done
Streaming seluruh item output dari pesan Asisten selesai
response.done
Respons selesai
Menginstruksikan server untuk membuat respons model.Saat sesi dikonfigurasikan dengan "turn_detection" diaktifkan, server secara otomatis membuat respons model.
public void cancelResponse()
Tidak adaMembatalkan respons yang sedang berlangsung. Jika tidak ada respons untuk dibatalkan, server merespons dengan kesalahan.
public void createItem(JsonObject item)
Tidak adaMengirim event conversation.item.create ke server.Saat mengembalikan hasil alat Function Calling, item adalah JsonObject yang berisi bidang berikut:
  • type: Tetap function_call_output.
  • call_id: Berkorespondensi dengan call_id dalam event response.function_call_arguments.done.
  • output: String hasil eksekusi alat.
Persetujuan MCP juga menggunakan event ini, tetapi item.type adalah mcp_approval_response; untuk bidangnya, lihat Respons persetujuan MCP di event klien.
public void close()
Tidak adaMenghentikan tugas dan menutup koneksi.
public String getSessionId()
Tidak adaMendapatkan session_id dari tugas saat ini.
public String getResponseId()
Tidak adaMendapatkan 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;.
MetodeParameterNilai kembaliDeskripsi
public void onOpen()
Tidak adaTidak adaMetode ini dipanggil kembali segera setelah koneksi dengan server dibangun.
public abstract void onEvent(JsonObject message)
message: event respons server.Tidak adaTermasuk respons terhadap panggilan API serta teks dan audio yang dihasilkan oleh model. Untuk informasi lebih lanjut, lihat Event server.
public abstract void onClose(int code, String reason)
code: kode status penutupan websocket.reason: alasan penutupan websocket.Tidak adaMetode ini dipanggil kembali setelah server menutup koneksi.