Skip to main content

SDK C# do Qwen-Audio-Realtime

Use o C# SDK para transmitir áudio para o Qwen-Audio-Realtime através do WebSocket e receber respostas em texto e áudio.

Instale o SDK

Baixe e extraia Bailian.DashScope-1.1.0.zip. O SDK é compatível com net8.0 e net10.0. Execute o seguinte comando a partir do diretório do seu projeto, usando o caminho para o diretório extraído do packages/.
dotnet add package Bailian.DashScope --version 1.1.0 --source "/path/to/Bailian.DashScope-1.1.0/packages"
Você também pode referenciar o DashScope.dll a partir do diretório extraído do sdk/net8.0/ ou sdk/net10.0/ que corresponde ao seu framework de destino. Mantenha o DashScope.xml ao lado do DLL para ver a documentação da API no seu IDE.

Início Rápido

  1. Obtenha uma chave de API e defina a variável de ambiente DASHSCOPE_API_KEY. Use uma chave de API da mesma região que seu espaço de trabalho.
  2. Crie um projeto de console .NET 10 e instale o SDK como descrito acima.
  3. Coloque input.pcm no diretório do projeto. Use áudio PCM bruto, mono, de 16 bits em little-endian com taxa de amostragem de 16 kHz. Converta os arquivos WAV em PCM bruto primeiro.
Configure o endpoint WebSocket do espaço de trabalho na região de Singapura. Substitua WorkspaceId pelo ID do seu espaço de trabalho. Consulte as regiões e os endpoints disponíveis em Acesso por WebSocket.
export DASHSCOPE_REALTIME_URL="wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"

Exemplo em C#

Este programa transmite em tempo real uma gravação raw PCM, aguarda a conclusão da resposta e escreve o áudio em output.pcm. Substitua Program.cs pelo código a seguir.
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 o arquivo raw PCM do início rápido no diretório do projeto e execute o exemplo.
dotnet run -- input.pcm qwen-audio-3.1-realtime-plus longanfengyue_v3.1

Referência da API

Tanto o Audio Realtime quanto o Omni Realtime usam o DashScope.Qwen.QwenRealtimeConversation. Passe o QwenRealtimeConversationOptions para o construtor. O padrão aponta para um modelo Audio Realtime. Para usar o Omni, defina explicitamente um ID de modelo Omni.

Opções de conexão e sessão

OpçãoTipoPadrãoDescrição
ApiKeystring?nullModel Studio chave de API. Se omitido, o SDK lê o DASHSCOPE_API_KEY.
Urlstringwss://dashscope.aliyuncs.com/api-ws/v1/realtimeEndpoint do WebSocket. O SDK anexa o Model como parâmetro de consulta model.
WorkspaceIdstring?nullID do workspace enviado no cabeçalho X-DashScope-WorkSpace. Para usar um endpoint específico do workspace, defina o endereço completo em Url.
ConnectTimeoutTimeSpan10 sTempo limite para abrir a conexão WebSocket.
StartTimeoutTimeSpan10 sTempo limite para receber o session.created.
StopTimeoutTimeSpan10 sTempo limite para receber o session.finished quando o modo de finalização espera por esse evento.
FinishModeQwenRealtimeFinishMode?nullQuando omitido, o SDK escolhe um modo de finalização com base no modelo. Leia o FinishMode na instância para ver qual modo está sendo usado.
Modelstringqwen-audio-3.1-realtime-plusID do modelo. Para Omni, defina isso explicitamente para o modelo Omni Realtime desejado.
ModalitiesIList<string>["text", "audio"]Modalidades de saída. Use ["text"] para saída apenas em texto.
Voicestring?nullVoz para saída de áudio. null deixa a escolha para o servidor. O exemplo de Áudio 3.1 define longanfengyue_v3.1 explicitamente.
EnableSpeechEmotionbool?nullHabilita fala emocional onde suportado. Consulte a referência de eventos do cliente para o modelo.
Instructionsstring?nullInstruções do sistema.
MaxHistoryTurnsint?nullNúmero de rodadas de conversa para manter, de 1 a 50.
ToolsJsonstring?nullDefinições de ferramentas funcionais como uma string JSON array no estilo OpenAI.
TurnDetectionModeQwenTurnDetectionModeServerVadModo de detecção de turno. ServerVad detecta limites de fala no servidor. Alguns modelos suportam SmartTurn. Com PushToTalk, o cliente confirma o áudio e solicita uma resposta.
VadThresholddouble?nullLimiar de VAD do servidor de -1,0 a 1,0. Aplica-se a ServerVad.
VadSilenceMsint?nullDuração de silêncio ao final da fala, de 200 a 6.000 milissegundos. Aplica-se a ServerVad. Quando omitido, o modelo usa seu valor padrão do servidor.
Defina Url para seu endpoint específico do workspace. Para endpoints regionais, veja Audio Realtime WebSocket access ou Omni Realtime WebSocket access.

Métodos

Os métodos abaixo retornam Task, exceto por DisposeAsync. ct é um token de cancelamento opcional.
MétodoDescrição
ConnectAsync(CancellationToken ct = default)Abre a conexão, aguarda session.created e envia session.update.
AppendAudioAsync(ReadOnlyMemory<byte> pcm, CancellationToken ct = default)Envia um quadro de áudio. O SDK Base64-encoda os bytes e envia um evento input_audio_buffer.append.
CommitAudioAsync(CancellationToken ct = default)Confirma o áudio armazenado em buffer com input_audio_buffer.commit no modo PushToTalk.
CreateResponseAsync(JsonObject? responseOptions = null, CancellationToken ct = default)Solicita uma resposta com response.create. responseOptions fornece substituições opcionais para a resposta atual.
SendItemAsync(JsonObject item, CancellationToken ct = default)Adiciona item à conversa usando conversation.item.create.
SendFunctionCallOutputAsync(string callId, string outputJson, CancellationToken ct = default)Retorna resultados de ferramentas usando o callId do evento e a string JSON de saída.
SendRawEventAsync(string frameJson, CancellationToken ct = default)Envia o JSON completo do evento do cliente conforme fornecido. Use este método para eventos sem um método dedicado no SDK.
FinishAsync(CancellationToken ct = default)Encerra a sessão usando o FinishMode ativo.
AbortAsync()Fecha a conexão imediatamente e descarta resultados pendentes.
DisposeAsync()Libera recursos de forma assíncrona e retorna um ValueTask.
No modo PushToTalk, chame CommitAudioAsync e depois CreateResponseAsync após enviar áudio. Para lidar com uma chamada de ferramenta, execute a ferramenta após FunctionCallReceived e retorne seu resultado. Chame CreateResponseAsync novamente se o modelo dever continuar respondendo.

Eventos

EventoArgumento do eventoQuando é disparado
SessionReadystring?A sessão está pronta. O valor é session.id.
UserSpeechStartedQwenSpeechEventArgsO VAD do servidor detectou o início da fala do usuário.
UserSpeechStoppedQwenSpeechEventArgsO VAD do servidor detectou o fim da fala do usuário.
UserTranscriptUpdatedQwenTranscriptEventArgsTranscrição atual de entrada, que pode mudar.
UserTranscriptCompletedQwenTranscriptEventArgsTranscrição final de uma utterance de entrada.
AssistantTextDeltaQwenTextDeltaEventArgsDelta de texto da resposta. Concatene os deltas na ordem.
AssistantTextCompletedQwenTranscriptEventArgsTexto completo da resposta.
AssistantAudioChunkQwenAudioChunkEventArgsTrecho de áudio da resposta em 24 kHz mono 16-bit little-endian raw PCM.
AssistantAudioCompletedEventArgsTodo o áudio da resposta para a rodada chegou.
FunctionCallReceivedQwenFunctionCallEventArgsO modelo solicitou uma chamada de ferramenta e forneceu o ID da chamada, o nome da função e os argumentos JSON.
ResponseCompletedQwenResponseSummaryresponse.done chegou com status e uso.
RawServerEventQwenServerEventArgsEvento bruto do servidor com seu tipo e objeto JSON.
ErrorOccurredDashScopeErrorEventArgsOcorreu um erro no servidor ou falha na conexão.

Tipos de resultado

TipoPropriedadesDescrição
QwenResponseSummaryStatus: string?, FailureReason: string?, TotalTokens: int?, InputTokens: int?, OutputTokens: int?, AudioInputTokens: int?, AudioOutputTokens: int?Status da resposta, motivo da falha e uso. Status pode ser completed, failed ou incomplete. O uso da conversa é por rodada. O uso da tradução é cumulativo para a sessão.
QwenSpeechEventArgsAudioMs: long, ItemId: string?Limite de fala em milissegundos e o ID do item de entrada.
QwenTranscriptEventArgsText: string, ItemId: string?Transcrição atual ou texto final e o ID do item.
QwenTextDeltaEventArgsDelta: string, ItemId: string?Delta de texto e o ID do item.
QwenAudioChunkEventArgsPcm: byte[]Trecho de áudio.
QwenFunctionCallEventArgsCallId: string, Name: string?, ArgumentsJson: string?ID da chamada de ferramenta, nome e argumentos. Use o CallId original ao retornar o resultado.
QwenServerEventArgsType: string?, Root: JsonObjectTipo de evento e JSON completo.
DashScopeErrorEventArgsCode: int, ServerErrorCode: string?, ServerErrorMessage: string?, TaskId: string?, InnerException: Exception?Código de erro do SDK, código de erro do servidor e mensagem, ID da tarefa ou sessão e a exceção subjacente.

Encerramento da sessão

Reutilize a conexão para múltiplas rodadas de conversa. Chame FinishAsync após o evento final ResponseCompleted para evitar truncar a resposta.
Modo de conclusãoComportamento
FinishWithoutWaitEnvia session.finish e fecha a conexão. Este é o padrão para Audio Realtime.
CloseOnlyFecha a conexão. Este é o padrão para Omni Realtime.
FinishAndWaitEnvia session.finish e aguarda session.finished. O servidor também pode encerrar a sessão fechando a conexão.