Alibaba Cloud Model Studio:Koneksi AOQ

Pelajari alur SDK klien AOQ: memperoleh kredensial, menginisialisasi SDK, mengatur arah media, membuat koneksi, bertukar peristiwa model, dan melepas sumber daya.

AOQ mengirim audio, video, dan peristiwa model melalui trek terpisah. SDK menangani pengambilan, encoding, decoding, pengiriman, dan pemutaran media. Aplikasi Anda mengirim peristiwa model dan menangani respons melalui trek Data. Pilih arah media dan protokol peristiwa yang diperlukan model tujuan.

Prasyarat

• Selesaikan persiapan dalam Ringkasan koneksi dan pastikan model tujuan, wilayah, serta dukungan AOQ.

• Impor SDK untuk platform Anda dari Unduhan SDK. Jika menggunakan Opus, impor plugin yang sesuai.

• Terapkan Autentikasi token di server aplikasi (AppServer). Simpan API key di AppServer dan berikan kredensial koneksi sementara kepada klien.

Alur kerja

1. Dapatkan kredensial koneksi melalui AppServer.
2. Buat mesin SDK dan daftarkan callback.
3. Atur trek media dan Data, lalu nonaktifkan pengiriman media upstream.
4. Buat koneksi AOQ dan tunggu hingga tersambung.
5. Konfigurasikan model sesuai protokolnya. Setelah dikonfirmasi, aktifkan media upstream yang diperlukan.
6. Putuskan koneksi dan lepas sumber daya setelah interaksi selesai.

1. Memperoleh kredensial koneksi

Klien meminta kredensial dari AppServer. AppServer memilih endpoint koneksi Realtime atau Inference untuk model tujuan, lalu mengirim API key dan header x-dashscope-rtc-transport: moq ke gateway. Untuk endpoint, permintaan, dan kolom, lihat Autentikasi token.

Petakan respons ke AoqConnectConfig:

Respons gateway	Konfigurasi SDK
aoqTokenForClient	token
sid	sid
clientRelayCertFingerprint	certFingerprint
clientRelayEndpoints	relayEndpoints: konversikan setiap endpoint ke struktur yang diperlukan
extraInfo.workspaceIdHash	workspaceIdHash

Dapatkan kredensial baru untuk setiap koneksi baru. Penggunaan ulang sesi atau memulai tugas lain pada koneksi yang sama bergantung pada protokol model tujuan.

2. Menginisialisasi SDK dan mendaftarkan callback

Buat mesin dan daftarkan callback untuk status koneksi, pesan Data, dan kesalahan. Contoh berikut menggunakan Swift di iOS:

let createConfig = AoqCreateConfig()
createConfig.workDir = workDir
createConfig.enableDumpAudio = false
engine = AoqClientEngine.createEngine(createConfig, delegate: self)

Terapkan AoqEngineDelegate: kelola status koneksi di onConnectionStatusChange, uraikan peristiwa model di onDataMsg, dan tangani kesalahan SDK di onError. Tangani peristiwa kesalahan model secara terpisah dalam penangan pesan Data. Untuk antarmuka dan kesalahan SDK, lihat SDK klien AOQ.

3. Mengonfigurasi SDK

Memilih arah media

Arah dilihat dari sisi klien. Konfigurasikan hanya modalitas input dan output yang diperlukan aplikasi. Jangan tambahkan trek untuk arah yang tidak digunakan.

Arah	Konfigurasi	Penggunaan umum
Mengirim audio	Publikasikan trek Audio, atur encoder, dan gunakan pengambilan bawaan atau eksternal	Pengenalan ucapan, percakapan, dan penerjemahan
Menerima audio	Berlangganan trek Audio, atur decoder, dan gunakan pemutaran bawaan atau eksternal	Sintesis ucapan dan respons suara
Mengirim video	Publikasikan trek Video dan atur kamera atau input eksternal serta encoding	Berikan gambar ke model yang mendukung input visual
Menerima video	Atur langganan dan penerimaan hanya jika model atau aplikasi secara eksplisit mendukung output video	Ikuti dokumentasi model atau aplikasi tujuan

Trek Data terpisah dari keempat arah ini: publikasikan trek Data untuk mengirim peristiwa model dan berlangganan untuk menerima respons. Input dan output teks juga memerlukan trek Data.

Memilih arah untuk model Anda

Tabel berikut mencantumkan konfigurasi umum. Untuk model dan versi yang didukung, lihat Ringkasan Realtime API dan dokumentasi model.

Model atau aplikasi	Mengirim audio	Menerima audio	Mengirim video	Menerima video
Qwen-Omni-Realtime	Untuk input ucapan	Untuk respons suara	Untuk input visual	Tidak didukung
Qwen-Audio-Realtime	Untuk percakapan suara	Untuk respons suara	Tidak didukung	Tidak didukung
Qwen-Audio-TTS, CosyVoice	Tidak didukung	Diaktifkan	Tidak didukung	Tidak didukung
Qwen-Audio-ASR-Streaming, Qwen-Audio-ASR-Message	Diaktifkan	Tidak didukung	Tidak didukung	Tidak didukung
Fun-ASR-Realtime	Diaktifkan	Tidak didukung	Tidak didukung	Tidak didukung
Qwen-LiveTranslate-Realtime	Untuk input ucapan	Untuk terjemahan suara	Bergantung pada versi dan skenario	Tidak didukung
multimodal-dialog	Sesuai input aplikasi	Sesuai output aplikasi	Sesuai kemampuan aplikasi	Hanya jika didukung secara eksplisit oleh aplikasi

Mengatur parameter dan trek media

Atur audio upstream dan downstream secara terpisah: gunakan setAudioEncoderConfig untuk upstream dan setAudioDecoderConfig untuk downstream. Parameter ini mengendalikan transmisi jaringan; gateway mengonversi audio ke format yang diperlukan model. Atur encoding transport dan format audio dalam peristiwa model masing-masing sesuai persyaratan SDK dan model tujuan.

Jalankan startAudioCapture, startAudioPlayer, atau startVideoCapture sesuai kebutuhan. Untuk input dan output khusus, lihat fitur lanjutan di bawah.

publishTracks dikirim oleh klien, sedangkan subscribeTracks diterima oleh klien:

Skenario	publishTracks	subscribeTracks
Percakapan suara	Audio, Data	Audio, Data
Percakapan suara dengan input visual	Audio, Video, Data	Audio, Data
Pengenalan ucapan	Audio, Data	Data
Sintesis ucapan	Data	Audio, Data

Nonaktifkan media upstream sebelum terhubung agar input tidak sampai ke model sebelum model siap:

engine.enableSendMediaStream(.audio, enable: false)
engine.enableSendMediaStream(.video, enable: false)

Pengambilan, publikasi trek, dan izin pengiriman merupakan operasi terpisah. Menonaktifkan transmisi tidak menghentikan pengambilan lokal atau memengaruhi peristiwa Data. Mengaktifkan transmisi tidak membuat trek yang belum ditambahkan.

4. Membuat koneksi

Isi AoqConnectConfig dengan kredensial dan konfigurasi trek, lalu panggil:

engine.connect(connectConfig)

Tunggu .connected di onConnectionStatusChange sebelum menginisialisasi model. Kembalinya pemanggilan connect tidak berarti koneksi berhasil.

5. Bertukar peristiwa model dan media

Mengirim dan menguraikan peristiwa model

Kirim peristiwa melalui trek Data. Contoh Swift di iOS:

// Build eventJSON according to the target model client event protocol.
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)

Uraikan respons di onDataMsg. Jangan menganggap semua peristiwa menggunakan type: peristiwa Realtime biasanya menggunakan type, sedangkan peristiwa server Inference menggunakan header.event. Ikuti dokumentasi model untuk kolom, parameter, dan kondisi penyelesaian.

Mengaktifkan media setelah model siap

Setelah model, sesi, atau tugas saat ini memenuhi kondisi kesiapan, aktifkan hanya arah upstream yang telah dikonfigurasi. Untuk input ucapan, panggil:

engine.enableSendMediaStream(.audio, enable: true)

Aktifkan .video hanya jika input video diperlukan. TTS menerima input teks dan tidak memerlukan audio atau video upstream.

Kirim audio dan video melalui trek medianya, serta peristiwa model dan teks melalui trek Data. Misalnya, Omni melalui AOQ tidak memerlukan input_audio_buffer.append atau input_image_buffer.append untuk mengirim ulang media yang sama. Tangani audio downstream dengan pemutar yang dikonfigurasi atau logika pemutaran eksternal.

6. Mengakhiri interaksi dan melepas sumber daya

Saat koneksi tidak diperlukan lagi, panggil antarmuka pemutusan koneksi dan pelepasan sumber daya SDK AOQ dari aplikasi:

engine.disconnect()
AoqClientEngine.destroy()

Setelah koneksi terputus secara tidak terduga, hapus status kesiapan aplikasi dan ikuti Pengelolaan status koneksi. Inisialisasi kembali model setelah terhubung ulang.

Mengirim dan menerima peristiwa melalui trek Data

Publikasikan dan berlangganan trek Data saat terhubung. Untuk mengirim peristiwa, serialisasikan ke AoqDataMsg dan panggil engine.send(msg). Uraikan pesan yang diterima di onDataMsg.

Ikuti definisi peristiwa klien model tujuan untuk nama, kolom, parameter, dan waktu pengiriman. Ikuti definisi peristiwa server untuk penguraian respons, perubahan status, hasil, dan kesalahan. Kirim peristiwa inisialisasi sesuai persyaratan model, lalu peristiwa teks dan kontrol sesuai kebutuhan aplikasi.

Model atau aplikasi	Peristiwa klien (kirim)	Peristiwa server (terima)
Qwen-Omni-Realtime	Peristiwa klien	Peristiwa server
Qwen-Audio-Realtime	Peristiwa klien	Peristiwa server
Qwen-Audio-TTS, CosyVoice	Peristiwa klien	Peristiwa server
Qwen-Audio-ASR-Streaming	Peristiwa klien	Peristiwa server
Qwen-Audio-ASR-Message	Peristiwa klien	Peristiwa server
Fun-ASR-Realtime	Peristiwa klien	Peristiwa server
Qwen-LiveTranslate-Realtime	Peristiwa klien	Peristiwa server
multimodal-dialog	Input Message dalam protokol interaksi	Output Message dalam protokol interaksi

Paket interaksi multimodal mendefinisikan kedua arah dalam satu protokol interaksi. Pilih definisi peristiwa sesuai versi model yang digunakan; model tidak berbagi satu skema peristiwa tetap.

Ikuti juga aturan berikut:

• Identifikasi jenis peristiwa dan pengenal korelasi sesuai model. Realtime biasanya menggunakan type; klien Inference menggunakan header.action, server menggunakan header.event, dan tugas dikorelasikan melalui task_id.

• Tangani konfirmasi inisialisasi, pengiriman input, pembatalan respons, dan penyelesaian tugas melalui trek Data sesuai protokol. Operasi ini berbeda dari menutup koneksi transport.

• Misalnya, model Inference menggunakan finish-task untuk mengakhiri tugas dan task-finished untuk mengonfirmasi penyelesaiannya. Terima semua hasil yang tersisa sebelum melepas koneksi. Jika pemutaran harus lengkap, tunggu juga audio lokal yang tertunda selesai diputar.

• Media menggunakan trek media. Saat merujuk dokumentasi peristiwa model, ikuti halaman AOQ ini untuk transport media dan mode interaksi yang tersedia; jangan menyalin mekanisme unggah media WebSocket.

Fitur lanjutan

Kemampuan	Kasus penggunaan	Dokumentasi
Mengendalikan transmisi audio dan video secara terpisah	Menunggu model siap, menjeda media upstream, atau mengaktifkan video sesuai kebutuhan	Pengelolaan transmisi media
Perangkat dan pemrosesan audio	Encoding, decoding, speaker, pencampuran file, dan callback frame audio	Fitur audio umum
Input audio eksternal	Menggunakan sumber audio yang disediakan aplikasi	Pengambilan audio khusus
Output audio eksternal	Memproses atau memutar audio output di aplikasi	Pemutaran audio khusus
Pengambilan dan input video	Menggunakan kamera atau gambar yang disediakan aplikasi	Fitur video umum, Input video khusus

Kontrol transmisi hanya memengaruhi media. Pembatalan respons model dan pengiriman giliran tetap memerlukan peristiwa model tujuan.

Praktik terbaik

• Panggilan Omni real-time: input audio/video, respons suara, dan peristiwa sesi.

• Omni push-to-talk: input dengan tombol dan giliran manual.

• Percakapan suara Qwen-Audio: audio dua arah.

• Sintesis ucapan Qwen-Audio: input teks pada trek Data dan output suara pada trek Audio.

• Pengenalan ucapan Fun-ASR: input audio pada trek Audio dan hasil pengenalan pada trek Data.