Utilisez le C# SDK pour diffuser audio vers Qwen-Audio-Realtime via WebSocket et recevoir des réponses textuelles et audio.
Prérequis
Obtenez une clé API et définissez la variable d’environnement DASHSCOPE_API_KEY. Utilisez une clé API de la même région que votre espace de travail.
Installer le SDK
Téléchargez et extrayez Bailian.DashScope-1.1.0.zip. Le SDK cible net8.0 et net10.0. Exécutez la commande suivante depuis votre répertoire de projet, en utilisant le chemin vers le répertoire extrait de packages/.
DashScope.dll à partir du répertoire extrait de sdk/net8.0/ ou sdk/net10.0/ correspondant à votre framework cible. Placez DashScope.xml à côté du DLL pour afficher la documentation d'API dans votre IDE.
Démarrage rapide
Exécuter l’exemple fourni
- Créez un projet console .NET 10 et installez le SDK selon les instructions ci-dessus.
- Placez
input.pcmdans le répertoire du projet. Utilisez un fichier PCM brut, mono, 16 bits, petit-boutiste, à 16 kHz. Convertissez d’abord les fichiers WAV en PCM brut.
WorkspaceId par l’identifiant de votre espace de travail. Pour les régions et adresses prises en charge, consultez Accès WebSocket.
Appeler le SDK dans un projet
Ce programme diffuse en temps réel un enregistrement raw PCM, attend la fin de la réponse, puis écrit l'audio dans output.pcm. Remplacez Program.cs par le code suivant.
Paramètres de requête
| Option | Type | Valeur par défaut | Description |
|---|---|---|---|
ApiKey | string? | null | Model Studio clé API. Si omis, l'SDK lit DASHSCOPE_API_KEY. |
Url | string | wss://dashscope.aliyuncs.com/api-ws/v1/realtime | Endpoint WebSocket. Le SDK ajoute Model comme paramètre de requête model. |
WorkspaceId | string? | null | ID d'espace de travail envoyé dans l'en-tête X-DashScope-WorkSpace. Pour utiliser un endpoint spécifique à l'espace de travail, définissez l'adresse complète dans Url. |
ConnectTimeout | TimeSpan | 10 s | Délai d'attente pour l'ouverture de la connexion WebSocket. |
StartTimeout | TimeSpan | 10 s | Délai d'attente pour la réception de session.created. |
StopTimeout | TimeSpan | 10 s | Délai d'attente pour la réception de session.finished lorsque le mode finish attend cet événement. |
FinishMode | QwenRealtimeFinishMode? | null | Lorsqu'il est omis, le SDK choisit un mode finish en fonction du modèle. Lisez FinishMode sur l'instance pour connaître le mode utilisé. |
Model | string | qwen-audio-3.1-realtime-plus | ID du modèle. Pour Omni, définissez-le explicitement sur l'ID de modèle Omni Realtime souhaité. |
Modalities | IList<string> | ["text", "audio"] | Modalités de sortie. Utilisez ["text"] pour une sortie uniquement texte. |
Voice | string? | null | Voix pour la sortie audio. null laisse le choix au serveur. L'exemple Audio 3.1 définit explicitement longanfengyue_v3.1. |
EnableSpeechEmotion | bool? | null | Active la parole émotionnelle lorsque cela est pris en charge. Consultez la référence d'événement client du modèle. |
Instructions | string? | null | Instructions système. |
MaxHistoryTurns | int? | null | Nombre de tours de conversation à conserver, compris entre 1 et 50. |
ToolsJson | string? | null | Définitions d'outils fonctionnels sous forme de chaîne JSON array au style OpenAI. |
TurnDetectionMode | QwenTurnDetectionMode | ServerVad | Mode de détection des tours. ServerVad détecte les limites de parole sur le serveur. Certains modèles prennent en charge SmartTurn. Avec PushToTalk, le client confirme l'audio et demande une réponse. |
VadThreshold | double? | null | Seuil de VAD serveur compris entre -1,0 et 1,0. S'applique à ServerVad. |
VadSilenceMs | int? | null | Durée de silence à la fin de la parole, comprise entre 200 et 6 000 millisecondes. S'applique à ServerVad. Si omis, le modèle utilise sa valeur par défaut serveur. |
Url sur votre point de terminaison spécifique à l'espace de travail. Pour les points de terminaison régionaux, consultez Audio Realtime WebSocket accès ou Omni Realtime WebSocket accès.
Référence de l’API
Audio Realtime et Omni Realtime utilisent tous deux DashScope.Qwen.QwenRealtimeConversation. Passez QwenRealtimeConversationOptions au constructeur. La valeur par défaut pointe vers un modèle Audio Realtime. Pour utiliser Omni, définissez explicitement un ID de modèle Omni.
Méthodes
Les méthodes ci-dessous renvoient Task, sauf DisposeAsync. ct est un jeton d'annulation facultatif.
| Méthode | Description |
|---|---|
ConnectAsync(CancellationToken ct = default) | Ouvre la connexion, attend session.created, puis envoie session.update. |
AppendAudioAsync(ReadOnlyMemory<byte> pcm, CancellationToken ct = default) | Envoie un cadre audio. Le SDK Base64-encode les octets et envoie un événement input_audio_buffer.append. |
CommitAudioAsync(CancellationToken ct = default) | Confirme l'audio mis en mémoire tampon avec input_audio_buffer.commit en mode PushToTalk. |
CreateResponseAsync(JsonObject? responseOptions = null, CancellationToken ct = default) | Demande une réponse avec response.create. responseOptions fournit des substitutions facultatives pour la réponse actuelle. |
SendItemAsync(JsonObject item, CancellationToken ct = default) | Ajoute item à la conversation en utilisant conversation.item.create. |
SendFunctionCallOutputAsync(string callId, string outputJson, CancellationToken ct = default) | Renvoie les résultats d'outil en utilisant le callId provenant de l'événement et la chaîne JSON de sortie. |
SendRawEventAsync(string frameJson, CancellationToken ct = default) | Envoie intégralement le JSON d'événement client tel qu'il est fourni. Utilisez cette méthode pour les événements sans méthode dédiée dans le SDK. |
FinishAsync(CancellationToken ct = default) | Termine la session en utilisant le FinishMode actif. |
AbortAsync() | Ferme la connexion immédiatement et rejette les résultats en attente. |
DisposeAsync() | Libère les ressources de manière asynchrone et renvoie un ValueTask. |
PushToTalk, appelez CommitAudioAsync puis CreateResponseAsync après avoir envoyé l'audio. Pour gérer un appel d'outil, exécutez l'outil après FunctionCallReceived et renvoyez son résultat. Appelez CreateResponseAsync à nouveau si le modèle doit continuer à répondre.
Événements
| Événement | Argument d'événement | Quand il se déclenche |
|---|---|---|
SessionReady | string? | La session est prête. La valeur est session.id. |
UserSpeechStarted | QwenSpeechEventArgs | Le VAD serveur a détecté le début de la parole utilisateur. |
UserSpeechStopped | QwenSpeechEventArgs | Le VAD serveur a détecté la fin de la parole utilisateur. |
UserTranscriptUpdated | QwenTranscriptEventArgs | Transcription actuelle de l'entrée, qui peut évoluer. |
UserTranscriptCompleted | QwenTranscriptEventArgs | Transcription définitive d'une utterance d'entrée. |
AssistantTextDelta | QwenTextDeltaEventArgs | Delta de texte de réponse. Concaténez les deltas dans l'ordre. |
AssistantTextCompleted | QwenTranscriptEventArgs | Texte complet de la réponse. |
AssistantAudioChunk | QwenAudioChunkEventArgs | Tronçon audio de réponse en format brut mono 24 kHz 16 bits little-endian PCM. |
AssistantAudioCompleted | EventArgs | Tout l'audio de réponse pour le tour est arrivé. |
FunctionCallReceived | QwenFunctionCallEventArgs | Le modèle a demandé un appel d'outil et a fourni l'ID d'appel, le nom de la fonction et les arguments JSON. |
ResponseCompleted | QwenResponseSummary | response.done est arrivé avec son statut et son utilisation. |
RawServerEvent | QwenServerEventArgs | Événement serveur brut avec son type et son objet JSON. |
ErrorOccurred | DashScopeErrorEventArgs | Une erreur serveur ou une défaillance de connexion s'est produite. |
Types de résultats
| Type | Propriétés | Description |
|---|---|---|
QwenResponseSummary | Status: string?, FailureReason: string?, TotalTokens: int?, InputTokens: int?, OutputTokens: int?, AudioInputTokens: int?, AudioOutputTokens: int? | Statut de réponse, raison de l'échec et utilisation. Status peut être completed, failed ou incomplete. L'utilisation de la conversation est par tour. L'utilisation de traduction est cumulée pour la session. |
QwenSpeechEventArgs | AudioMs: long, ItemId: string? | Frontière de parole en millisecondes et l'identifiant de l'élément d'entrée. |
QwenTranscriptEventArgs | Text: string, ItemId: string? | Transcription courante ou texte final et l'identifiant de l'élément. |
QwenTextDeltaEventArgs | Delta: string, ItemId: string? | Delta de texte et l'identifiant de l'élément. |
QwenAudioChunkEventArgs | Pcm: byte[] | Tronçon audio. |
QwenFunctionCallEventArgs | CallId: string, Name: string?, ArgumentsJson: string? | ID d'appel d'outil, nom et arguments. Utilisez le CallId d'origine lors du retour du résultat. |
QwenServerEventArgs | Type: string?, Root: JsonObject | Type d'événement et JSON complet. |
DashScopeErrorEventArgs | Code: int, ServerErrorCode: string?, ServerErrorMessage: string?, TaskId: string?, InnerException: Exception? | Code d'erreur SDK, code d'erreur serveur et message, identifiant de tâche ou de session, et exception sous-jacente. |
Terminer la session
Réutiliser la connexion pour plusieurs tours de conversation. Appelez FinishAsync après l'événement ResponseCompleted final afin d'éviter de tronquer la réponse.
| Mode de fin | Comportement |
|---|---|
FinishWithoutWait | Envoie session.finish et ferme la connexion. C'est le comportement par défaut pour Audio Realtime. |
CloseOnly | Ferme la connexion. C'est le comportement par défaut pour Omni Realtime. |
FinishAndWait | Envoie session.finish et attend session.finished. Le serveur peut également terminer la session en fermant la connexion. |