Alibaba Cloud Model Studio:Connexion AOQ à Qwen-Audio-Realtime

Connexion AOQ à Qwen-Audio-Realtime

AOQ transmet les médias audio et les événements du modèle sur des pistes distinctes. Le SDK gère la capture audio, l’encodage et le décodage, la transmission et la lecture ; l’application envoie les événements du modèle sur la piste Data et traite les réponses. Cette page utilise les directions de transmission des médias et le protocole d’événements de Qwen-Audio-Realtime.

Périmètre d’application

Ce document concerne Qwen-Audio-Realtime. Les instructions d’intégration existantes couvrent qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus et qwen-audio-3.0-realtime-flash. Le modèle de l’exemple est qwen-audio-3.1-realtime-plus.

• Utilisez l’API Key et l’ID de l’espace de travail correspondant à la région et à l’espace de travail sélectionnés.

• Domaine de Pékin : {WorkspaceId}.cn-beijing.maas.aliyuncs.com ; domaine de Singapour : {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com.

• Stockez l’API Key uniquement sur le serveur. Ne l’intégrez pas à une application mobile ou à un navigateur.

• Lors de la capture audio avec un microphone, demandez l’autorisation d’accès au microphone conformément aux exigences de la plateforme.

• Téléchargez le SDK de votre plateforme depuis Téléchargement du SDK.

Authentification et informations de connexion

Envoyez la requête suivante depuis votre AppServer. Commencez par configurer l’API Key comme variable d’environnement. Remplacez {WorkspaceId} dans le domaine par l’ID de votre espace de travail. Pour une autre région, utilisez le domaine correspondant indiqué ci-dessus. clientIp est facultatif. S’il est omis, la passerelle utilise l’adresse IP depuis laquelle elle reçoit la requête.

export ENDPOINT="{WorkspaceId}.cn-beijing.maas.aliyuncs.com"
curl -X POST \
  "https://${ENDPOINT}/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "x-dashscope-rtc-transport: moq" \
  -d '{}'

Pour préciser l’adresse IP publique du client, remplacez -d '{}' dans le corps de la requête par -d '{"clientIp":"<CLIENT_PUBLIC_IP>"}'.

Champs de la requête

Exemple de réponse

{
    "sid": "1d06b55683db49bba67a407902f62d02:1782706970:69aecdc5...",
    "aoqTokenForClient": "ecc1a46015d5496ca4ff7a48281eb739",
    "clientRelayEndpoints": [{"endpoint": "121.199.XX.XX", "port": 8443, "route_index": 0}],
    "clientRelayCertFingerprint": "sha256/99843495...",
    "sidExpiresInSecs": 7200,
    "extraInfo": {"workspaceIdHash": "2021b6f98cea4cff"}
}

Champs de la réponse

Exemple de connexion du SDK client AOQ

let resp = try JSONDecoder().decode(AllocateResponse.self, from: responseData)

let config = AoqConnectConfig()
config.token = resp.aoqTokenForClient
config.sid = resp.sid
config.certFingerprint = resp.clientRelayCertFingerprint
config.relayEndpoints = resp.clientRelayEndpoints.enumerated().map { index, item in
    let ep = AoqRelayEndpoint()
    // Fall back to the array index when route_index is missing
    ep.routeIndex = item.routeIndex ?? index
    ep.endpoint = item.endpoint
    ep.port = item.port
    return ep
}
config.workspaceIdHash = resp.extraInfo?.workspaceIdHash ?? ""

let audioTrack = AoqTrackParam()
audioTrack.trackType = .audio
let dataTrack = AoqTrackParam()
dataTrack.trackType = .data
config.publishTracks = [audioTrack, dataTrack]
config.subscribeTracks = [audioTrack, dataTrack]

engine.connect(config)

JSONObject obj = new JSONObject(responseText);
AoqClientEngine.AoqConnectConfig cfg = new AoqClientEngine.AoqConnectConfig();
cfg.token = obj.optString("aoqTokenForClient", "");
cfg.sid = obj.optString("sid", "");
cfg.certFingerprint = obj.optString("clientRelayCertFingerprint", "");

JSONArray arr = obj.optJSONArray("clientRelayEndpoints");
if (arr != null) {
    for (int i = 0; i < arr.length(); i++) {
        JSONObject o = arr.optJSONObject(i);
        AoqClientEngine.AoqRelayEndpoint ep = new AoqClientEngine.AoqRelayEndpoint();
        // Fall back to the array index when route_index is missing
        ep.routeIndex = o.has("route_index") ? o.optInt("route_index", i) : i;
        ep.endpoint = o.optString("endpoint", "");
        ep.port = o.optInt("port", 0);
        cfg.relayEndpoints.add(ep);
    }
}

JSONObject ext = obj.optJSONObject("extraInfo");
cfg.workspaceIdHash = ext != null ? ext.optString("workspaceIdHash", "") : "";

AoqClientEngine.AoqTrackParam audio = new AoqClientEngine.AoqTrackParam();
audio.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
AoqClientEngine.AoqTrackParam data = new AoqClientEngine.AoqTrackParam();
data.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
cfg.publishTracks.add(audio);
cfg.publishTracks.add(data);
cfg.subscribeTracks.add(audio);
cfg.subscribeTracks.add(data);

engine.connect(cfg);

const obj = JSON.parse(responseText) as Record<string, Object | undefined>;
const cfg: AoqConnectConfig = {
    token: String(obj['aoqTokenForClient'] ?? ''),
    sid: String(obj['sid'] ?? ''),
    certFingerprint: String(obj['clientRelayCertFingerprint'] ?? ''),
    // Fall back to the array index when route_index is missing
    relayEndpoints: (obj['clientRelayEndpoints'] as Array<any>).map((item, index) => ({
        routeIndex: Number(item['route_index'] ?? index),
        endpoint: String(item['endpoint'] ?? ''),
        port: Number(item['port'] ?? 0)
    })),
    workspaceIdHash: String((obj['extraInfo'] as any)?.['workspaceIdHash'] ?? ''),
    publishTracks: [
        { trackType: AoqTrackType.AoqTrackTypeAudio },
        { trackType: AoqTrackType.AoqTrackTypeData }
    ],
    subscribeTracks: [
        { trackType: AoqTrackType.AoqTrackTypeAudio },
        { trackType: AoqTrackType.AoqTrackTypeData }
    ]
};
engine.connect(cfg);

Déroulement

1. Obtenez les informations de connexion via AppServer.
2. Créez le moteur SDK et enregistrez les callbacks.
3. Configurez les pistes de médias et Data, puis désactivez la transmission des médias en amont.
4. Établissez la connexion AOQ et attendez qu’elle soit connectée.
5. Configurez le modèle selon son protocole. Après confirmation, activez les médias en amont nécessaires.
6. Déconnectez-vous et libérez les ressources une fois l’interaction terminée.

1. Obtenir les identifiants de connexion

Le client demande les informations de connexion à votre AppServer. AppServer appelle le point de terminaison de connexion Realtime de ce modèle et inclut l’API Key et x-dashscope-rtc-transport: moq dans la requête à la passerelle. Pour le point de terminaison complet, la requête et la description des champs, consultez Authentification par jeton.

Associez la réponse à AoqConnectConfig :

Obtenez de nouvelles informations de connexion à chaque nouvelle connexion. La possibilité de réutiliser une session ou de lancer une autre tâche dans la même connexion dépend du protocole du modèle cible.

2. Initialiser le SDK et enregistrer les rappels

Créez le moteur et enregistrez les callbacks pour l’état de la connexion, les messages Data et les erreurs. L’exemple suivant utilise Swift sur iOS :

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

Implémentez AoqEngineDelegate ; gérez l’état de la connexion dans onConnectionStatusChange ; analysez les événements du modèle cible dans onDataMsg ; traitez les erreurs du SDK dans onError. Les événements d’erreur renvoyés par le modèle doivent également être traités séparément dans la logique de traitement des messages Data. Pour les interfaces du SDK et la description des erreurs, consultez SDK par plateforme et Référence des fonctionnalités.

3. Configurer le SDK

Sélectionner la direction des médias

Les directions sont définies du point de vue du client. Configurez uniquement les modalités d’entrée et de sortie nécessaires à votre application. N’ajoutez pas de pistes pour les directions inutilisées.

La piste Data est indépendante de la direction audio : publiez-la pour envoyer les événements du modèle et abonnez-vous à cette piste pour recevoir les réponses. Les entrées ou sorties purement textuelles nécessitent également la piste Data.

Directions des médias pour ce modèle

Le tableau suivant présente les directions de transmission des médias pour ce modèle. Consultez le Périmètre d’application pour connaître les modèles concernés ; pour les autres méthodes de connexion, consultez Qwen-Audio-Realtime.

Configurer les paramètres et pistes média

Configurez séparément l’audio en amont et en aval : utilisez setAudioEncoderConfig pour l’audio en amont et setAudioDecoderConfig pour l’audio en aval. Ces paramètres contrôlent la transmission réseau ; la passerelle convertit l’audio au format requis par le modèle. Configurez l’encodage du transport et le format audio des événements du modèle selon les exigences du SDK et du modèle cible, respectivement.

Démarrez startAudioCapture ou startAudioPlayer selon la direction. Les entrées et sorties personnalisées sont décrites dans la section des fonctionnalités avancées ci-dessous.

Les pistes publishTracks sont envoyées par le client, et les pistes subscribeTracks sont reçues par le client :

Désactivez les médias en amont avant la connexion pour éviter que les entrées n’atteignent le modèle avant qu’il soit prêt :

engine.enableSendMediaStream(.audio, enable: false)

La capture, la publication des pistes et l’autorisation d’envoi sont des opérations distinctes. La désactivation de la transmission n’arrête pas la capture locale et n’affecte pas les événements Data. L’activation de la transmission ne crée pas de pistes qui n’ont pas été ajoutées.

4. Établir la connexion

Renseignez les informations de connexion et la configuration des pistes dans AoqConnectConfig, puis appelez :

engine.connect(connectConfig)

Attendez que onConnectionStatusChange renvoie .connected, puis procédez à l’initialisation du modèle. Le retour de l’appel à connect ne signifie pas que la connexion a réussi.

5. Échanger les événements du modèle et les médias

Envoyer et analyser les événements du modèle

Le client envoie les événements sur la piste Data. Voici un extrait de code Swift pour iOS ; pour les autres interfaces, consultez Référence du SDK iOS :

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

Analysez la réponse dans onDataMsg. Ce modèle identifie les types d’événements par le champ type. Les champs complets, les paramètres et les conditions de fin doivent suivre la documentation du modèle cible.

Activer les médias lorsque le modèle est prêt

Une fois les conditions de disponibilité du modèle, de la session ou de la tâche actuels remplies, activez uniquement les directions en amont configurées. Pour l’entrée vocale, appelez :

engine.enableSendMediaStream(.audio, enable: true)

L’audio est transmis sur la piste Audio ; les événements du modèle et le texte sont transmis sur la piste Data. N’utilisez pas input_audio_buffer.append pour envoyer une deuxième fois les données audio. L’audio en aval est traité par le lecteur configuré ou par la logique de lecture externe.

6. Terminer l’interaction et libérer les ressources

Lorsque la connexion n’est plus nécessaire, appelez les interfaces de déconnexion et de libération des ressources d’AOQ SDK depuis votre application :

engine.disconnect()
AoqClientEngine.destroy()

Après une déconnexion inattendue, effacez l’état de disponibilité de l’application et suivez Gestion de l’état de la connexion. Initialisez à nouveau le modèle après la reconnexion.

Envoyer et recevoir des événements sur le canal Data

Le client envoie et reçoit les événements du modèle sur la piste Data d’AOQ SDK. Pendant la connexion, la publication de la piste Data et l’abonnement à celle-ci sont tous deux nécessaires ; pour l’envoi, sérialisez l’événement du modèle dans AoqDataMsg et appelez l’interface d’envoi Data de la plateforme ; à la réception, analysez le message dans le callback onDataMsg. Pour le détail des interfaces, consultez SDK par plateforme.

Les noms, champs, paramètres et moments d’envoi des événements suivent les définitions des événements client du modèle cible ; l’analyse, les changements d’état, les résultats et la gestion des erreurs après réception suivent les définitions des événements serveur du modèle. Les événements d’initialisation sont envoyés selon les exigences du modèle, puis les événements textuels et de contrôle selon les besoins métier.

Respectez également les règles suivantes :

• Utilisez le champ type des événements pour identifier les événements du modèle et traitez les identifiants associés selon la référence des événements de ce modèle.

• Les opérations requises par le modèle, telles que la confirmation de l’initialisation, la soumission des entrées, l’annulation des réponses et la fin des tâches, sont toutes traitées sur le canal Data selon le protocole correspondant ; elles définissent les interactions du modèle et sont distinctes de la déconnexion du transport.

• Avant de terminer, achevez la soumission des entrées et la réception des résultats selon la documentation des événements de ce modèle ; si une lecture complète est nécessaire, ne libérez la connexion qu’après avoir traité l’audio restant dans la file locale.

• Les données audio sont transmises sur les pistes de médias. Lorsque vous utilisez la référence des événements du modèle, suivez cette page pour l’encapsulation des médias et les modes d’interaction disponibles. N’appliquez pas directement la méthode WebSocket d’envoi des médias.

Fonctionnalités avancées

Pour les interfaces vidéo générales d’AOQ SDK, consultez Fonctions vidéo courantes (SDK général) et Entrée vidéo personnalisée (SDK général) ; ce modèle ne prend pas en charge l’entrée ni la sortie vidéo.

Les commandes de transmission des médias affectent uniquement les médias. L’annulation des réponses du modèle et la soumission des tours nécessitent toujours les événements du modèle cible.

Exemple de configuration de session

{
  "type": "session.update",
  "session": {
    "voice": "longanqian_v3.1"
  }
}

Téléchargement du SDK AOQ

Les notes de version ci-dessous décrivent les fonctionnalités générales d’AOQ SDK ; les médias pris en charge par ce modèle sont détaillés dans Directions de transmission des médias pour ce modèle ci-dessus.

Références des événements

• Événements client
• Événements serveur

Tutoriels par scénario

• Créer des conversations vocales en temps réel avec qwen-audio-3.1-realtime-plus via AOQ