Alibaba Cloud Model Studio:Menghubungkan ke model dan aplikasi

Hubungkan ke model dan aplikasi Realtime API melalui protokol AOQ, WebRTC, dan WebSocket. Topik ini mencakup alur koneksi, diagram sekuens, serta contoh kode untuk masing-masing protokol.

Prasyarat

• Sebelum menghubungkan, periksa Model dan aplikasi yang didukung.
• Pelajari tentang Otentikasi token.

Coba demo

Gunakan demo Android dari Alibaba Cloud Model Studio untuk memverifikasi konektivitas AOQ secara cepat. Unduh APK dan konfigurasikan Kunci API serta workspaceId untuk mencoba model yang dipilih.

Pindai kode QR berikut untuk mengunduh demo:

Koneksi AOQ

AOQ merupakan kustomisasi mendalam di atas protokol QUIC. Protokol ini cocok untuk aplikasi mobile native, mendukung transmisi campuran audio, video, dan data, serta memiliki ketahanan bawaan terhadap jaringan lemah. Contoh berikut menggunakan demo iOS Real-time omni (Omni) untuk menjelaskan alur koneksi AOQ. Untuk detail API SDK AOQ, lihat SDK client AOQ.

Diagram sekuens keseluruhan

Buat engine dan atur callback

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

Implementasikan protokol AoqEngineDelegate untuk mendengarkan callback seperti onConnectionStatusChange, onDataMsg, dan onError.

Mulai penangkapan dan pemutaran audio

// Penangkapan audio
let capCfg = AoqAudioCaptureConfig()
capCfg.channel = 1; capCfg.isExternal = false
engine.startAudioCapture(capCfg)

// Pemutaran audio
let playCfg = AoqAudioPlaybackConfig()
playCfg.channel = 1; playCfg.isExternal = false
engine.startAudioPlayer(playCfg)

// Penangkapan video (opsional)
let vidCfg = AoqVideoCaptureConfig()
vidCfg.width = 720; vidCfg.height = 1280; vidCfg.fps = 15
engine.startVideoCapture(vidCfg)

Dapatkan kredensial koneksi

Aplikasi AppServer bisnis meneruskan permintaan ke Model Studio. Lihat Otentikasi token.

Konfigurasi kodek dan bangun koneksi

Konfigurasikan parameter kodek, lalu panggil connect:

// Konfigurasi kodek audio
let encCfg = AoqAudioCodecConfig()
encCfg.codecType = .audioPCM; encCfg.sampleRate = 16000; encCfg.channel = 1
engine.setAudioEncoderConfig(encCfg)
engine.setAudioDecoderConfig(encCfg)

// Nonaktifkan pengiriman media sebelum connect; aktifkan setelah session.updated
engine.enableSendMediaStream(.audio, enable: false)

let config = AoqConnectConfig()
config.token = token
config.sid = sid
config.certFingerprint = certificate
config.relayEndpoints = relayEndpoints
config.workspaceIdHash = workspaceIdHash
config.publishTracks = [audioTrack, dataTrack]
config.subscribeTracks = [audioTrack, dataTrack]
engine.connect(config)

Konfigurasi sesi AI

Setelah koneksi berhasil, kirim event session.update. Untuk detailnya, lihat Event client:

func onConnectionStatusChange(_ status: AoqConnectionStatus) {
    if status == .connected { sendSessionUpdate() }
}

private func sendSessionUpdate() {
    let json = """
    {
      // ID event ini, dihasilkan oleh client
      "event_id": "event_ToPZqeobitzUJnt3QqtWg",
      // Jenis event, tetap sebagai session.update
      "type": "session.update",
      // Konfigurasi sesi
      "session": {
          // Modalitas output. Atur ke ["text"] (hanya teks) atau ["text","audio"] (teks dan audio).
          "modalities": [
              "text",
              "audio"
          ],
          // Voice untuk output audio
          "voice": "Ethan",
          // Format audio input. Hanya pcm yang didukung. Audio input adalah aliran audio PCM dengan laju sampel 16 kHz.
          "input_audio_format": "pcm",
          // Format audio output. Hanya pcm yang didukung. Audio output adalah aliran audio PCM dengan laju sampel 24 kHz.
          "output_audio_format": "pcm",
          // Pesan sistem yang menetapkan tujuan atau peran model.
          "instructions": "Anda adalah agen layanan pelanggan AI di hotel bintang lima. Jawab pertanyaan pelanggan secara akurat dan sopan mengenai tipe kamar, fasilitas, harga, dan kebijakan pemesanan. Selalu tanggapi dengan cara profesional dan membantu, serta jangan pernah memberikan informasi yang tidak diverifikasi atau di luar cakupan layanan hotel.",
          // Apakah akan mengaktifkan deteksi aktivitas suara. Untuk mengaktifkannya, kirim objek konfigurasi; server kemudian secara otomatis mendeteksi kapan ucapan dimulai dan dihentikan.
          // Atur ke null agar client yang menentukan kapan memicu respons model.
          "turn_detection": {
              // Jenis VAD: server_vad atau semantic_vad. semantic_vad direkomendasikan untuk model seri qwen3.5-omni-realtime.
              "type": "semantic_vad",
              // Ambang batas deteksi VAD. Tingkatkan nilainya di lingkungan bising dan turunkan di lingkungan tenang.
              "threshold": 0.5,
              // Durasi diam untuk mendeteksi akhir ucapan. Respons model dipicu setelah durasi ini terlampaui
              "silence_duration_ms": 800
          }
      }
    }
    """
    let msg = AoqDataMsg()
    msg.data = json.data(using: .utf8)!
    engine.send(msg)
}

Aktifkan pengiriman media setelah menerima session.updated

Contoh berikut menangani balasan session.updated dari model. Untuk detailnya, lihat Event server:

func onDataMsg(_ msg: AoqDataMsg) {
    guard let obj = try? JSONSerialization.jsonObject(with: msg.data) as? [String: Any],
          let type = obj["type"] as? String else { return }
    if type == "session.updated" {
        engine.enableSendMediaStream(.audio, enable: true)
        engine.enableSendMediaStream(.video, enable: true)
    }
}

Putuskan koneksi dan hapus engine

engine.disconnect()
AoqClientEngine.destroy()

Koneksi WebRTC

WebRTC tidak memiliki SDK khusus. Di web, hubungkan langsung menggunakan API JavaScript native browser. Di client lain, hubungkan melalui library WebRTC open source atau layanan RTC pihak ketiga yang mendukung protokol WebRTC standar. Contoh berikut menggunakan JavaScript di web.

Diagram alur keseluruhan

Bangun koneksi

# pip install aiortc aiohttp certifi
import asyncio, aiohttp, ssl, certifi
from aiortc import RTCPeerConnection, RTCConfiguration, RTCSessionDescription
from aiortc.mediastreams import AudioStreamTrack

API_KEY = "your-api-key"
MODEL = "target-model"
SIGNALING_URL = f"https://{{endpoint}}/api/v1/webrtc/realtime?model={MODEL}"

async def connect():
    pc = RTCPeerConnection(RTCConfiguration(iceServers=[]))

    # Tambahkan track audio agar Offer SDP berisi m=audio (diperlukan oleh server)
    pc.addTrack(AudioStreamTrack())

    # Buat DataChannel untuk memicu negosiasi SDP (nama dapat dikustomisasi; server mendorong event melalui channel bernama "txt")
    pc.createDataChannel("oai-events")

    # Pertukaran SDP: buat Offer dan kirim ke server
    offer = await pc.createOffer()
    await pc.setLocalDescription(offer)

    async with aiohttp.ClientSession() as session:
        async with session.post(
            SIGNALING_URL,
            ssl=ssl.create_default_context(cafile=certifi.where()),
            data=offer.sdp.encode("utf-8"),
            headers={
                "Content-Type": "application/sdp",
                "Authorization": f"Bearer {API_KEY}",
            },
        ) as resp:
            if not resp.ok:
                raise Exception(f"Pertukaran SDP gagal: {resp.status} {await resp.text()}")
            answer_sdp = await resp.text()

    print("=== Offer SDP ===")
    print(offer.sdp)
    print("=== Answer SDP ===")
    print(answer_sdp)

    # Penyiapan koneksi ICE selesai secara otomatis
    await pc.setRemoteDescription(RTCSessionDescription(sdp=answer_sdp, type="answer"))
    print("Koneksi WebRTC berhasil dibangun")
    return pc

Konfigurasi parameter model

Dengarkan pesan yang dikembalikan model melalui DataChannel untuk menjaga urutan interaksi tetap benar:

pc.ondatachannel = (event) => {
  const ch = event.channel;
  ch.onmessage = (e) => {
    let obj;
    try { obj = JSON.parse(e.data); }
    catch (err) {
      return;
    }
    if (obj?.type === "session.created") {
      sendUpdate(event.channel);
      // Mulai mendorong audio dan video
      audioSender?.replaceTrack(audioTrack);
      videoSender?.replaceTrack(videoTrack);
    }
  };
};

Kirim dan terima data media

Track audio dan video yang ditambahkan selama penyiapan koneksi (saluran media RTP) secara otomatis mengirimkan data ke server.

• Audio: dikirim langsung melalui track audio (RTP). Tidak diperlukan event input_audio_buffer.append.
• Gambar: frame dikirim melalui track video (RTP). Event input_image_buffer.append tidak didukung.

Kode sumber demo

Prasyarat

• Browser modern yang mendukung WebRTC (seperti Chrome, Edge, Firefox, atau Safari).
• Izin mikrofon telah diberikan ke browser.
• Browser tidak dapat mengirim permintaan koneksi langsung ke server karena kebijakan keamanan cross-origin. Jalankan perintah curl di terminal untuk membangun koneksi.

Jalankan demo

Buat file HTML bernama webrtc_demo.html dan salin kode berikut ke dalamnya:

webrtc_demo.html.

Buka file tersebut di browser dan ikuti langkah-langkah berikut:

1. Klik Start session. Halaman secara otomatis menghasilkan Offer SDP dan perintah curl yang sesuai.
2. Klik Copy curl command dan jalankan perintah tersebut di terminal. Perintah tersebut akan mengembalikan Answer SDP.
3. Tempel Answer SDP ke kotak teks Answer SDP di halaman, lalu klik Set Answer untuk membangun koneksi dan memulai percakapan suara.

Koneksi WebSocket

Metode dan alur koneksi bervariasi tergantung model. Untuk detailnya, lihat:

• Real-time omni
• Terjemahan audio real-time
• Pengenalan ucapan real-time
• Sintesis suara real-time
• Percakapan suara real-time