Utilisez le SDK vocal Node.js pour configurer les sessions Qwen-Audio-Realtime, échanger de l’audio et gérer la transcription et les appels de fonctions.
Prérequis
Obtenez une clé API dans la console et définissez-la dans la variable d’environnement DASHSCOPE_API_KEY.
Installer le SDK
Nécessite Node.js 18 ou ultérieur. Téléchargez le SDK 0.1.0, puis exécutez dans votre projet :
Démarrage rapide
Téléchargez l’audio d’exemple sous input.mp3 et convertissez-le en PCM mono 16 kHz, 16 bits :
example.mjs, puis exécutez node example.mjs.
Paramètres de requête
Options du constructeur de RealtimeClient :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
apiKey | string | Non | Clé API. Utilise DASHSCOPE_API_KEY par défaut. |
workspaceId | string | Non | ID de l’espace de travail. Utilise DASHSCOPE_WORKSPACE_ID par défaut. |
baseUrl | string | Non | Définissez l’hôte sur dashscope-intl.aliyuncs.com (Singapour). |
model | string | Oui | ID du modèle. |
voice | string | Non | ID de voix. Utilise la voix par défaut du service si omis. |
instructions | string | Non | Instructions système pour le rôle, le style et le comportement. |
turnDetection | TurnDetection | null | Non | Par défaut : { type: "server_vad" }. null active l’envoi manuel. Accepte aussi smart_turn et smart_turn_v2. |
modalities | Array<'text' | 'audio'> | Non | Modalités de sortie. Par défaut : ["text", "audio"]. |
maxHistoryTurns | number | Non | Tours d’historique : [1,50]. Par défaut : 20. |
tools | ToolDefinition[] | Non | Définitions d’outils. L’application les exécute et valide les arguments. |
inputTranscription | { model?: string; language?: string } | null | Non | Configuration de transcription d’entrée, par exemple { model: "fun-asr", language: "zh" } ; null la désactive. |
sessionExtras | SessionConfig | Non | Réglages supplémentaires, tels que speech_rate et enable_search. Remplacent les réglages correspondants de niveau supérieur ; consultez les événements client. |
connectTimeoutMs | number | Non | Délai de connexion en ms. Par défaut : 10000. |
Référence de l’API
Méthodes principales
| Méthode | Valeur de retour | Description |
|---|---|---|
connect() | Promise<void> | Se connecte et envoie les réglages. sessionUpdated confirme leur application. |
updateSession(session: SessionConfig) | void | Met à jour la session ; confirmez avec sessionUpdated. |
appendAudio(pcm: Buffer | Uint8Array) | void | Envoie du PCM mono 16 kHz, 16 bits. |
commit() | void | Valide le tampon audio en mode manuel. |
clearAudioBuffer() | void | Efface le tampon audio non validé. |
createResponse(response?: Record<string, unknown>) | void | Demande une réponse au modèle. |
cancelResponse() | void | Annule la réponse actuelle en conservant la session. |
createConversationItem(item: ConversationItem, previousItemId?: string) | void | Ajoute l’historique ou un résultat d’outil. previousItemId définit la position. |
submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean) | void | Soumet le résultat sous forme de chaîne. autoCreateResponse vaut true par défaut et demande la réponse suivante. |
deleteConversationItem(itemId: string) | void | Supprime un élément de conversation. |
retrieveConversationItem(itemId: string) | void | Récupère un élément via event. |
sendEvent(event: ClientEvent) | void | Envoie un événement client brut. |
close(code?: number, reason?: string) | void | Ferme la session et la connexion WebSocket. |
Événements de callback
Enregistrez les callbacks avec on(event, listener). Consultez les champs complets dans les événements serveur.
| Événement | Charge utile | Description |
|---|---|---|
open | void | Connexion établie et configuration initiale envoyée. |
sessionCreated / sessionUpdated | ServerEvent | Création de session ou confirmation de configuration. |
audio | Buffer | Bloc audio binaire ; peut être émis plusieurs fois. |
audioTranscriptDelta | { delta: string } | Texte incrémental de transcription de l’audio de sortie. |
outputTranscript | { transcript: string } | Transcription complète de l’audio de sortie. |
textDelta / textDone | { delta: string } / { text: string } | Texte incrémental ou complet en modalité texte seul. |
inputTranscriptDelta | { text: string; stash: string } | text est confirmé et stash provisoire. Remplacez l’affichage courant par leur combinaison au lieu de l’ajouter. |
inputTranscript | { transcript: string } | Transcription finale de l’audio d’entrée. |
speechStarted / speechStopped | ServerEvent | Début ou fin de parole utilisateur. |
responseCreated / responseDone | ServerEvent | Réponse commencée ou terminée. Vérifiez si responseDone.response.status est completed, annulé ou en échec. |
functionCall | { callId: string; name: string; arguments: string } | Arguments complets de l’appel. L’application analyse et valide la chaîne JSON arguments. |
ambientTranscript / ambientTranscriptCompleted | { text: string; stash: string } / { transcript: string } | Transcription courante ou finale de l’audio ambiant, exclue du contexte. |
event | ServerEvent | Message JSON brut du service. |
error | DashScopeError | Erreur de connexion ou de service. |
close | { code: number; reason: string } | Notification de fermeture de la connexion sous-jacente. |