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/.
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
- Cree un proyecto de consola .NET 10 e instale el SDK como se describe arriba.
- Coloque
input.pcmen 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.
WorkspaceId por el ID de su espacio de trabajo. Para consultar las regiones y los puntos de conexión disponibles, vea Acceso por WebSocket.
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.
Parámetros de solicitud
| Opción | Tipo | Predeterminado | Descripción |
|---|---|---|---|
ApiKey | string? | null | Model Studio clave de API. Si se omite, el SDK lee DASHSCOPE_API_KEY. |
Url | string | wss://dashscope.aliyuncs.com/api-ws/v1/realtime | Punto final de WebSocket. El SDK anexa Model como parámetro de consulta model. |
WorkspaceId | string? | null | ID 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. |
ConnectTimeout | TimeSpan | 10 s | Tiempo de espera para abrir la conexión de WebSocket. |
StartTimeout | TimeSpan | 10 s | Tiempo de espera para recibir session.created. |
StopTimeout | TimeSpan | 10 s | Tiempo de espera para recibir session.finished cuando el modo de finalización espera ese evento. |
FinishMode | QwenRealtimeFinishMode? | null | Cuando se omite, el SDK elige un modo de finalización según el modelo. Lea FinishMode en la instancia para ver qué modo utiliza. |
Model | string | qwen-audio-3.1-realtime-plus | ID del modelo. Para Omni, establezca este valor explícitamente al ID de modelo Omni Realtime deseado. |
Modalities | IList<string> | ["text", "audio"] | Modalidades de salida. Use ["text"] para una salida solo de texto. |
Voice | string? | null | Voz para salida de audio. null deja la elección al servidor. El ejemplo de Audio 3.1 establece longanfengyue_v3.1 explícitamente. |
EnableSpeechEmotion | bool? | null | Habilita el habla emocional cuando está disponible. Consulte la referencia de eventos del cliente para el modelo. |
Instructions | string? | null | Instrucciones del sistema. |
MaxHistoryTurns | int? | null | Número de turnos de conversación que se conservarán, desde 1 hasta 50. |
ToolsJson | string? | null | Definiciones de herramientas funcionales como una cadena JSON de herramientas con estilo OpenAI. |
TurnDetectionMode | QwenTurnDetectionMode | ServerVad | Modo 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. |
VadThreshold | double? | null | Umbral de detección de actividad vocal (VAD) del servidor de -1.0 a 1.0. Aplica a ServerVad. |
VadSilenceMs | int? | null | Duració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. |
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étodo | Descripció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. |
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
| Evento | Argumento del evento | Cuando se dispara |
|---|---|---|
SessionReady | string? | La sesión está lista. El valor es session.id. |
UserSpeechStarted | QwenSpeechEventArgs | El VAD del servidor detectó el inicio de la habla del usuario. |
UserSpeechStopped | QwenSpeechEventArgs | El VAD del servidor detectó el final de la habla del usuario. |
UserTranscriptUpdated | QwenTranscriptEventArgs | Transcripción actual de la entrada, que puede cambiar. |
UserTranscriptCompleted | QwenTranscriptEventArgs | Transcripción final de una utterance de entrada. |
AssistantTextDelta | QwenTextDeltaEventArgs | Incremento de texto de respuesta. Concatene los incrementos en orden. |
AssistantTextCompleted | QwenTranscriptEventArgs | Texto completo de la respuesta. |
AssistantAudioChunk | QwenAudioChunkEventArgs | Fragmento de audio de respuesta en PCM sin encabezado, mono, de 16 bits little-endian, a 24 kHz. |
AssistantAudioCompleted | EventArgs | Se ha recibido todo el audio de respuesta para el turno. |
FunctionCallReceived | QwenFunctionCallEventArgs | El modelo solicitó una llamada a herramienta y proporcionó el ID de llamada, el nombre de la función y los argumentos JSON. |
ResponseCompleted | QwenResponseSummary | response.done llegó con estado y uso. |
RawServerEvent | QwenServerEventArgs | Evento del servidor sin procesar con su tipo y objeto JSON. |
ErrorOccurred | DashScopeErrorEventArgs | Ocurrió un error del servidor o una falla de conexión. |
Tipos de resultado
| Tipo | Propiedades | Descripción |
|---|---|---|
QwenResponseSummary | Status: 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. |
QwenSpeechEventArgs | AudioMs: long, ItemId: string? | Límite de habla en milisegundos y el ID del elemento de entrada. |
QwenTranscriptEventArgs | Text: string, ItemId: string? | Transcripción actual o texto final y el ID del elemento. |
QwenTextDeltaEventArgs | Delta: string, ItemId: string? | Incremento de texto y el ID del elemento. |
QwenAudioChunkEventArgs | Pcm: byte[] | Fragmento de audio. |
QwenFunctionCallEventArgs | CallId: string, Name: string?, ArgumentsJson: string? | ID de llamada a herramienta, nombre y argumentos. Utilice el CallId original al devolver el resultado. |
QwenServerEventArgs | Type: string?, Root: JsonObject | Tipo de evento y JSON completo. |
DashScopeErrorEventArgs | Code: 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ón | Comportamiento |
|---|---|
FinishWithoutWait | Envía session.finish y cierra la conexión. Este es el valor predeterminado para Audio Realtime. |
CloseOnly | Cierra la conexión. Este es el valor predeterminado para Omni Realtime. |
FinishAndWait | Envía session.finish y espera session.finished. El servidor también puede finalizar la sesión cerrando la conexión. |