Skip to main content

SDK de C# de Qwen-Audio-Realtime

Utilice el C# SDK para transmitir audio a Qwen-Audio-Realtime a través de WebSocket y recibir respuestas de texto y audio.

Requisitos previos

Obtenga una clave de API y configure la variable de entorno DASHSCOPE_API_KEY. Use una clave de API de la misma región que su espacio de trabajo.

Instalar el SDK

Descargue y extraiga Bailian.DashScope-1.1.0.zip. El SDK está dirigido a net8.0 y net10.0. Ejecute el siguiente comando desde su directorio de proyecto, utilizando la ruta al directorio extraído de packages/.
dotnet add package Bailian.DashScope --version 1.1.0 --source "/path/to/Bailian.DashScope-1.1.0/packages"
También puede hacer referencia a DashScope.dll desde el directorio extraído de sdk/net8.0/ o sdk/net10.0/ que coincida con su marco objetivo. Mantenga DashScope.xml junto al DLL para ver la documentación de la API en su IDE.

Inicio rápido

Ejecutar el ejemplo incluido

  1. Cree un proyecto de consola .NET 10 e instale el SDK como se describe arriba.
  2. Coloque input.pcm en el directorio del proyecto. Use PCM sin encabezado, mono, de 16 bits en orden little-endian, con una frecuencia de muestreo de 16 kHz. Convierta primero los archivos WAV a PCM sin encabezado.
Configure el punto de conexión WebSocket del espacio de trabajo en la región Singapur. Sustituya WorkspaceId por el ID de su espacio de trabajo. Para consultar las regiones y los puntos de conexión disponibles, vea Acceso por WebSocket.
export DASHSCOPE_REALTIME_URL="wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"

Llamar al SDK desde un proyecto

Este programa transmite en tiempo real una grabación de PCM sin encabezado, espera a que finalice la respuesta y escribe el audio en output.pcm. Reemplace Program.cs por el siguiente código.
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}");
Coloque el archivo PCM sin encabezado del inicio rápido en su directorio de proyecto y ejecute el ejemplo.
dotnet run -- input.pcm qwen-audio-3.1-realtime-plus longanfengyue_v3.1

Parámetros de solicitud

OpciónTipoPredeterminadoDescripción
ApiKeystring?nullModel Studio clave de API. Si se omite, el SDK lee DASHSCOPE_API_KEY.
Urlstringwss://dashscope.aliyuncs.com/api-ws/v1/realtimePunto final de WebSocket. El SDK anexa Model como parámetro de consulta model.
WorkspaceIdstring?nullID de espacio de trabajo enviado en el encabezado X-DashScope-WorkSpace. Para usar un punto final específico del espacio de trabajo, establezca la dirección completa en Url.
ConnectTimeoutTimeSpan10 sTiempo de espera para abrir la conexión de WebSocket.
StartTimeoutTimeSpan10 sTiempo de espera para recibir session.created.
StopTimeoutTimeSpan10 sTiempo de espera para recibir session.finished cuando el modo de finalización espera ese evento.
FinishModeQwenRealtimeFinishMode?nullCuando se omite, el SDK elige un modo de finalización según el modelo. Lea FinishMode en la instancia para ver qué modo utiliza.
Modelstringqwen-audio-3.1-realtime-plusID del modelo. Para Omni, establezca este valor explícitamente al ID de modelo Omni Realtime deseado.
ModalitiesIList<string>["text", "audio"]Modalidades de salida. Use ["text"] para una salida solo de texto.
Voicestring?nullVoz para salida de audio. null deja la elección al servidor. El ejemplo de Audio 3.1 establece longanfengyue_v3.1 explícitamente.
EnableSpeechEmotionbool?nullHabilita el habla emocional cuando está disponible. Consulte la referencia de eventos del cliente para el modelo.
Instructionsstring?nullInstrucciones del sistema.
MaxHistoryTurnsint?nullNúmero de turnos de conversación que se conservarán, desde 1 hasta 50.
ToolsJsonstring?nullDefiniciones de herramientas funcionales como una cadena JSON de herramientas con estilo OpenAI.
TurnDetectionModeQwenTurnDetectionModeServerVadModo de detección de turno. ServerVad detecta los límites de habla en el servidor. Algunos modelos admiten SmartTurn. Con PushToTalk, el cliente confirma el audio y solicita una respuesta.
VadThresholddouble?nullUmbral de detección de actividad vocal (VAD) del servidor de -1.0 a 1.0. Aplica a ServerVad.
VadSilenceMsint?nullDuración de silencio al final de la frase, de 200 a 6.000 milisegundos. Aplica a ServerVad. Cuando se omite, el modelo utiliza su valor predeterminado del servidor.
Establezca Url a su punto de acceso específico de espacio de trabajo. Para puntos de acceso regionales, consulte Acceso por WebSocket a Audio Realtime o Acceso por WebSocket a Omni Realtime.

Referencia de la API

Tanto Audio Realtime como Omni Realtime utilizan DashScope.Qwen.QwenRealtimeConversation. Pase QwenRealtimeConversationOptions al constructor. El valor predeterminado apunta a un modelo Audio Realtime. Para utilizar Omni, establezca explícitamente un ID de modelo Omni.

Métodos

Los métodos siguientes devuelven Task, excepto DisposeAsync. ct es un token de cancelación opcional.
MétodoDescripción
ConnectAsync(CancellationToken ct = default)Abre la conexión, espera session.created y envía session.update.
AppendAudioAsync(ReadOnlyMemory<byte> pcm, CancellationToken ct = default)Envía un marco de audio. El SDK codifica los bytes con Base64 y envía un evento input_audio_buffer.append.
CommitAudioAsync(CancellationToken ct = default)Confirma el audio almacenado en búfer con input_audio_buffer.commit en modo PushToTalk.
CreateResponseAsync(JsonObject? responseOptions = null, CancellationToken ct = default)Solicita una respuesta con response.create. responseOptions proporciona anulaciones opcionales para la respuesta actual.
SendItemAsync(JsonObject item, CancellationToken ct = default)Agrega item a la conversación usando conversation.item.create.
SendFunctionCallOutputAsync(string callId, string outputJson, CancellationToken ct = default)Devuelve resultados de herramientas utilizando el callId del evento y la cadena JSON de salida.
SendRawEventAsync(string frameJson, CancellationToken ct = default)Envía el JSON completo del evento del cliente tal como se proporciona. Utilice este método para eventos sin un método dedicado del SDK.
FinishAsync(CancellationToken ct = default)Finaliza la sesión usando el FinishMode activo.
AbortAsync()Cierra la conexión inmediatamente y descarta los resultados pendientes.
DisposeAsync()Libera recursos de forma asincrónica y devuelve un ValueTask.
En modo PushToTalk, llame a CommitAudioAsync y luego a CreateResponseAsync después de enviar audio. Para manejar una llamada a herramienta, ejecute la herramienta después de FunctionCallReceived y devuelva su resultado. Llame a CreateResponseAsync nuevamente si el modelo debe continuar respondiendo.

Eventos

EventoArgumento del eventoCuando se dispara
SessionReadystring?La sesión está lista. El valor es session.id.
UserSpeechStartedQwenSpeechEventArgsEl VAD del servidor detectó el inicio de la habla del usuario.
UserSpeechStoppedQwenSpeechEventArgsEl VAD del servidor detectó el final de la habla del usuario.
UserTranscriptUpdatedQwenTranscriptEventArgsTranscripción actual de la entrada, que puede cambiar.
UserTranscriptCompletedQwenTranscriptEventArgsTranscripción final de una utterance de entrada.
AssistantTextDeltaQwenTextDeltaEventArgsIncremento de texto de respuesta. Concatene los incrementos en orden.
AssistantTextCompletedQwenTranscriptEventArgsTexto completo de la respuesta.
AssistantAudioChunkQwenAudioChunkEventArgsFragmento de audio de respuesta en PCM sin encabezado, mono, de 16 bits little-endian, a 24 kHz.
AssistantAudioCompletedEventArgsSe ha recibido todo el audio de respuesta para el turno.
FunctionCallReceivedQwenFunctionCallEventArgsEl modelo solicitó una llamada a herramienta y proporcionó el ID de llamada, el nombre de la función y los argumentos JSON.
ResponseCompletedQwenResponseSummaryresponse.done llegó con estado y uso.
RawServerEventQwenServerEventArgsEvento del servidor sin procesar con su tipo y objeto JSON.
ErrorOccurredDashScopeErrorEventArgsOcurrió un error del servidor o una falla de conexión.

Tipos de resultado

TipoPropiedadesDescripción
QwenResponseSummaryStatus: string?, FailureReason: string?, TotalTokens: int?, InputTokens: int?, OutputTokens: int?, AudioInputTokens: int?, AudioOutputTokens: int?Estado de la respuesta, razón de fallo y uso. Status puede ser completed, failed o incomplete. El uso de conversación es por turno. El uso de traducción es acumulativo para la sesión.
QwenSpeechEventArgsAudioMs: long, ItemId: string?Límite de habla en milisegundos y el ID del elemento de entrada.
QwenTranscriptEventArgsText: string, ItemId: string?Transcripción actual o texto final y el ID del elemento.
QwenTextDeltaEventArgsDelta: string, ItemId: string?Incremento de texto y el ID del elemento.
QwenAudioChunkEventArgsPcm: byte[]Fragmento de audio.
QwenFunctionCallEventArgsCallId: string, Name: string?, ArgumentsJson: string?ID de llamada a herramienta, nombre y argumentos. Utilice el CallId original al devolver el resultado.
QwenServerEventArgsType: string?, Root: JsonObjectTipo de evento y JSON completo.
DashScopeErrorEventArgsCode: int, ServerErrorCode: string?, ServerErrorMessage: string?, TaskId: string?, InnerException: Exception?Código de error del SDK, código de error del servidor y mensaje, ID de tarea o sesión, y la excepción subyacente.

Finalizar la sesión

Reutilice la conexión para múltiples turnos de conversación. Llame a FinishAsync después del evento final ResponseCompleted para evitar truncar la respuesta.
Modo de finalizaciónComportamiento
FinishWithoutWaitEnvía session.finish y cierra la conexión. Este es el valor predeterminado para Audio Realtime.
CloseOnlyCierra la conexión. Este es el valor predeterminado para Omni Realtime.
FinishAndWaitEnvía session.finish y espera session.finished. El servidor también puede finalizar la sesión cerrando la conexión.