Skip to main content

SDK C# de Qwen-Audio-Realtime

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/.
dotnet add package Bailian.DashScope --version 1.1.0 --source "/path/to/Bailian.DashScope-1.1.0/packages"
Vous pouvez également référencer 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

  1. Créez un projet console .NET 10 et installez le SDK selon les instructions ci-dessus.
  2. Placez input.pcm dans 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.
Configurez l’adresse WebSocket de votre espace de travail dans la région Singapour. Remplacez WorkspaceId par l’identifiant de votre espace de travail. Pour les régions et adresses prises en charge, consultez Accès WebSocket.
export DASHSCOPE_REALTIME_URL="wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"

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.
using DashScope.Qwen;

if (args.Length < 2)
    throw new ArgumentException("Usage: <input.pcm> <model> [voice]");

using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(60));
var ct = timeout.Token;
await using var client = new QwenRealtimeConversation(new QwenRealtimeConversationOptions
{
    Model = args[1],
    Voice = args.Length > 2 ? args[2] : null,
    Url = Environment.GetEnvironmentVariable("DASHSCOPE_REALTIME_URL")
        ?? throw new InvalidOperationException("Set DASHSCOPE_REALTIME_URL to your workspace WebSocket endpoint."),
    Modalities = ["text", "audio"],
    TurnDetectionMode = QwenTurnDetectionMode.ServerVad,
});

using var output = File.Create("output.pcm");
var completed = new TaskCompletionSource<string?>(TaskCreationOptions.RunContinuationsAsynchronously);
client.AssistantTextCompleted += (_, e) => Console.WriteLine(e.Text);
client.AssistantAudioChunk += (_, e) => output.Write(e.Pcm);
client.ResponseCompleted += (_, e) => completed.TrySetResult(e.Status);
client.ErrorOccurred += (_, e) => completed.TrySetException(
    new InvalidOperationException($"{e.ServerErrorCode}: {e.ServerErrorMessage}"));

await client.ConnectAsync(ct);
using var input = File.OpenRead(args[0]);
var frame = new byte[640];
int size;
while ((size = await input.ReadAsync(frame.AsMemory(), ct)) > 0)
{
    await client.AppendAudioAsync(frame.AsMemory(0, size), ct);
    await Task.Delay(20, ct);
}

Array.Clear(frame);
for (var i = 0; i < 60; i++)
{
    await client.AppendAudioAsync(frame, ct);
    await Task.Delay(20, ct);
}

var status = await completed.Task.WaitAsync(ct);
await client.FinishAsync(ct);
if (status != "completed" || output.Length == 0)
    throw new InvalidOperationException($"Status: {status}, audio bytes: {output.Length}");
Placez le fichier raw PCM issu du guide rapide dans votre répertoire de projet et exécutez l'exemple.
dotnet run -- input.pcm qwen-audio-3.1-realtime-plus longanfengyue_v3.1

Paramètres de requête

OptionTypeValeur par défautDescription
ApiKeystring?nullModel Studio clé API. Si omis, l'SDK lit DASHSCOPE_API_KEY.
Urlstringwss://dashscope.aliyuncs.com/api-ws/v1/realtimeEndpoint WebSocket. Le SDK ajoute Model comme paramètre de requête model.
WorkspaceIdstring?nullID 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.
ConnectTimeoutTimeSpan10 sDélai d'attente pour l'ouverture de la connexion WebSocket.
StartTimeoutTimeSpan10 sDélai d'attente pour la réception de session.created.
StopTimeoutTimeSpan10 sDélai d'attente pour la réception de session.finished lorsque le mode finish attend cet événement.
FinishModeQwenRealtimeFinishMode?nullLorsqu'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é.
Modelstringqwen-audio-3.1-realtime-plusID du modèle. Pour Omni, définissez-le explicitement sur l'ID de modèle Omni Realtime souhaité.
ModalitiesIList<string>["text", "audio"]Modalités de sortie. Utilisez ["text"] pour une sortie uniquement texte.
Voicestring?nullVoix pour la sortie audio. null laisse le choix au serveur. L'exemple Audio 3.1 définit explicitement longanfengyue_v3.1.
EnableSpeechEmotionbool?nullActive la parole émotionnelle lorsque cela est pris en charge. Consultez la référence d'événement client du modèle.
Instructionsstring?nullInstructions système.
MaxHistoryTurnsint?nullNombre de tours de conversation à conserver, compris entre 1 et 50.
ToolsJsonstring?nullDéfinitions d'outils fonctionnels sous forme de chaîne JSON array au style OpenAI.
TurnDetectionModeQwenTurnDetectionModeServerVadMode 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.
VadThresholddouble?nullSeuil de VAD serveur compris entre -1,0 et 1,0. S'applique à ServerVad.
VadSilenceMsint?nullDuré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.
Définissez 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éthodeDescription
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.
En mode 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énementArgument d'événementQuand il se déclenche
SessionReadystring?La session est prête. La valeur est session.id.
UserSpeechStartedQwenSpeechEventArgsLe VAD serveur a détecté le début de la parole utilisateur.
UserSpeechStoppedQwenSpeechEventArgsLe VAD serveur a détecté la fin de la parole utilisateur.
UserTranscriptUpdatedQwenTranscriptEventArgsTranscription actuelle de l'entrée, qui peut évoluer.
UserTranscriptCompletedQwenTranscriptEventArgsTranscription définitive d'une utterance d'entrée.
AssistantTextDeltaQwenTextDeltaEventArgsDelta de texte de réponse. Concaténez les deltas dans l'ordre.
AssistantTextCompletedQwenTranscriptEventArgsTexte complet de la réponse.
AssistantAudioChunkQwenAudioChunkEventArgsTronçon audio de réponse en format brut mono 24 kHz 16 bits little-endian PCM.
AssistantAudioCompletedEventArgsTout l'audio de réponse pour le tour est arrivé.
FunctionCallReceivedQwenFunctionCallEventArgsLe modèle a demandé un appel d'outil et a fourni l'ID d'appel, le nom de la fonction et les arguments JSON.
ResponseCompletedQwenResponseSummaryresponse.done est arrivé avec son statut et son utilisation.
RawServerEventQwenServerEventArgsÉvénement serveur brut avec son type et son objet JSON.
ErrorOccurredDashScopeErrorEventArgsUne erreur serveur ou une défaillance de connexion s'est produite.

Types de résultats

TypePropriétésDescription
QwenResponseSummaryStatus: 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.
QwenSpeechEventArgsAudioMs: long, ItemId: string?Frontière de parole en millisecondes et l'identifiant de l'élément d'entrée.
QwenTranscriptEventArgsText: string, ItemId: string?Transcription courante ou texte final et l'identifiant de l'élément.
QwenTextDeltaEventArgsDelta: string, ItemId: string?Delta de texte et l'identifiant de l'élément.
QwenAudioChunkEventArgsPcm: byte[]Tronçon audio.
QwenFunctionCallEventArgsCallId: string, Name: string?, ArgumentsJson: string?ID d'appel d'outil, nom et arguments. Utilisez le CallId d'origine lors du retour du résultat.
QwenServerEventArgsType: string?, Root: JsonObjectType d'événement et JSON complet.
DashScopeErrorEventArgsCode: 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 finComportement
FinishWithoutWaitEnvoie session.finish et ferme la connexion. C'est le comportement par défaut pour Audio Realtime.
CloseOnlyFerme la connexion. C'est le comportement par défaut pour Omni Realtime.
FinishAndWaitEnvoie session.finish et attend session.finished. Le serveur peut également terminer la session en fermant la connexion.