Alibaba Cloud Model Studio:Connecting to models and applications

Connectez-vous aux modèles et applications de l'API Realtime via les protocoles AOQ, WebRTC et WebSocket. Cette rubrique détaille le flux de connexion, les diagrammes de séquence et des exemples de code pour chaque protocole.

Prérequis

• Avant toute connexion, consultez la rubrique Modèles et applications pris en charge.
• Familiarisez-vous avec l'Authentification par jeton.

Connexion AOQ

Le protocole AOQ repose sur une personnalisation approfondie de QUIC. Adapté aux applications mobiles natives, il prend en charge la transmission mixte de données audio, vidéo et textuelles, et intègre une résilience native aux réseaux faibles. L'exemple suivant s'appuie sur la démo iOS Real-time omni (Omni) pour illustrer le flux de connexion AOQ. Pour plus de détails sur l'API du SDK AOQ, reportez-vous au SDK client AOQ.

Diagramme de séquence global

Créer le moteur et configurer les callbacks

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

Implémentez le protocole AoqEngineDelegate pour écouter les callbacks tels que onConnectionStatusChange, onDataMsg et onError.

Démarrer la capture et la lecture audio

// Audio capture
let capCfg = AoqAudioCaptureConfig()
capCfg.channel = 1; capCfg.isExternal = false
engine.startAudioCapture(capCfg)

// Audio playback
let playCfg = AoqAudioPlaybackConfig()
playCfg.channel = 1; playCfg.isExternal = false
engine.startAudioPlayer(playCfg)

// Video capture (optional)
let vidCfg = AoqVideoCaptureConfig()
vidCfg.width = 720; vidCfg.height = 1280; vidCfg.fps = 15
engine.startVideoCapture(vidCfg)

Obtenir les identifiants de connexion

L'AppServer métier relaie la requête vers Model Studio. Consultez la rubrique Authentification par jeton.

Configurer les codecs et établir la connexion

Configurez les paramètres du codec, puis appelez la méthode connect :

// Audio codec configuration
let encCfg = AoqAudioCodecConfig()
encCfg.codecType = .audioPCM; encCfg.sampleRate = 16000; encCfg.channel = 1
engine.setAudioEncoderConfig(encCfg)
engine.setAudioDecoderConfig(encCfg)

// Disable media sending before connect; enable it after 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)

Configurer la session IA

Une fois la connexion établie, envoyez un événement session.update. Pour plus de détails, consultez la rubrique Événements client :

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

private func sendSessionUpdate() {
    let json = """
    {
      // The ID of this event, generated by the client
      "event_id": "event_ToPZqeobitzUJnt3QqtWg",
      // Event type, fixed to session.update
      "type": "session.update",
      // Session configuration
      "session": {
          // Output modalities. Set to ["text"] (text only) or ["text","audio"] (text and audio).
          "modalities": [
              "text",
              "audio"
          ],
          // Voice for the output audio
          "voice": "Ethan",
          // Input audio format. Only pcm is supported. The input audio is a PCM audio stream with a 16 kHz sample rate.
          "input_audio_format": "pcm",
          // Output audio format. Only pcm is supported. The output audio is a PCM audio stream with a 24 kHz sample rate.
          "output_audio_format": "pcm",
          // System message that sets the model's goal or role.
          "instructions": "You are an AI customer service agent at a five-star hotel. Accurately and courteously answer customer questions about room types, facilities, prices, and booking policies. Always respond in a professional and helpful manner, and never provide unverified information or information beyond the scope of the hotel's services.",
          // Whether to enable voice activity detection. To enable it, pass a configuration object; the server then automatically detects when speech starts and stops.
          // Set to null to let the client decide when to trigger a model response.
          "turn_detection": {
              // VAD type: server_vad or semantic_vad. semantic_vad is recommended for qwen3.5-omni-realtime series models.
              "type": "semantic_vad",
              // VAD detection threshold. Increase it in noisy environments and decrease it in quiet environments.
              "threshold": 0.5,
              // Silence duration for detecting the end of speech. A model response is triggered after this duration is exceeded
              "silence_duration_ms": 800
          }
      }
    }
    """
    let msg = AoqDataMsg()
    msg.data = json.data(using: .utf8)!
    engine.send(msg)
}

Activer l'envoi multimédia après réception de session.updated

L'exemple ci-dessous traite la réponse session.updated du modèle. Pour plus de détails, consultez la rubrique Événements serveur :

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)
    }
}

Se déconnecter et détruire le moteur

engine.disconnect()
AoqClientEngine.destroy()

Connexion WebRTC

WebRTC ne dispose pas de SDK dédié. Sur le web, connectez-vous directement via l'API JavaScript native du navigateur. Pour les autres clients, utilisez une bibliothèque WebRTC open source ou un service RTC tiers compatible avec le protocole WebRTC standard. L'exemple suivant utilise JavaScript dans un environnement web.

Diagramme de flux global

Établir la connexion

# 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=[]))

    # Add an audio track so that the Offer SDP contains m=audio (required by the server)
    pc.addTrack(AudioStreamTrack())

    # Create a DataChannel to trigger SDP negotiation (the name is customizable; the server pushes events through a channel named "txt")
    pc.createDataChannel("oai-events")

    # SDP exchange: create an Offer and send it to the 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"SDP exchange failed: {resp.status} {await resp.text()}")
            answer_sdp = await resp.text()

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

    # ICE connection setup completes automatically
    await pc.setRemoteDescription(RTCSessionDescription(sdp=answer_sdp, type="answer"))
    print("WebRTC connection established")
    return pc

Configurer les paramètres du modèle

Écoutez les messages renvoyés par le modèle via le DataChannel pour garantir la bonne séquence d'interaction :

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);
      // Start pushing audio and video
      audioSender?.replaceTrack(audioTrack);
      videoSender?.replaceTrack(videoTrack);
    }
  };
};

Envoyer et recevoir des données multimédias

Les pistes audio et vidéo ajoutées lors de l'initialisation de la connexion (canaux multimédias RTP) transmettent automatiquement les données au serveur.

• Audio : transmis directement via la piste audio (RTP). Aucun événement input_audio_buffer.append n'est nécessaire.
• Images : les trames transitent par la piste vidéo (RTP). Les événements input_image_buffer.append ne sont pas pris en charge.

Code source de la démo

Prérequis

• Un navigateur moderne compatible WebRTC (tel que Chrome, Edge, Firefox ou Safari).
• Autorisation d'accès au microphone accordée au navigateur.
• En raison des politiques de sécurité cross-origin, le navigateur ne peut pas envoyer directement la requête de connexion au serveur. Exécutez la commande curl dans un terminal pour établir la connexion.

Exécuter la démo

Créez un fichier HTML nommé webrtc_demo.html et copiez-y le code suivant :

webrtc_demo.html.

Ouvrez ce fichier dans un navigateur et suivez les étapes ci-après :

1. Cliquez sur Start session. La page génère automatiquement l'offre SDP et la commande curl correspondante.
2. Cliquez sur Copy curl command, puis exécutez cette commande dans un terminal. Elle renvoie la réponse SDP (Answer SDP).
3. Collez la réponse SDP dans la zone de texte Answer SDP de la page, puis cliquez sur Set Answer pour établir la connexion et démarrer la conversation vocale.

Connexion WebSocket

La méthode et le flux de connexion varient selon le modèle. Pour plus de détails, consultez :

• Real-time omni
• Traduction audio en temps réel
• Reconnaissance vocale en temps réel
• Synthèse vocale en temps réel
• Conversation vocale en temps réel