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/.
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
- 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. - Crie um projeto de console .NET 10 e instale o SDK como descrito acima.
- Coloque
input.pcmno 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.
WorkspaceId pelo ID do seu espaço de trabalho. Consulte as regiões e os endpoints disponíveis em Acesso por WebSocket.
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.
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ção | Tipo | Padrão | Descrição |
|---|---|---|---|
ApiKey | string? | null | Model Studio chave de API. Se omitido, o SDK lê o DASHSCOPE_API_KEY. |
Url | string | wss://dashscope.aliyuncs.com/api-ws/v1/realtime | Endpoint do WebSocket. O SDK anexa o Model como parâmetro de consulta model. |
WorkspaceId | string? | null | ID do workspace enviado no cabeçalho X-DashScope-WorkSpace. Para usar um endpoint específico do workspace, defina o endereço completo em Url. |
ConnectTimeout | TimeSpan | 10 s | Tempo limite para abrir a conexão WebSocket. |
StartTimeout | TimeSpan | 10 s | Tempo limite para receber o session.created. |
StopTimeout | TimeSpan | 10 s | Tempo limite para receber o session.finished quando o modo de finalização espera por esse evento. |
FinishMode | QwenRealtimeFinishMode? | null | Quando 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. |
Model | string | qwen-audio-3.1-realtime-plus | ID do modelo. Para Omni, defina isso explicitamente para o modelo Omni Realtime desejado. |
Modalities | IList<string> | ["text", "audio"] | Modalidades de saída. Use ["text"] para saída apenas em texto. |
Voice | string? | null | Voz para saída de áudio. null deixa a escolha para o servidor. O exemplo de Áudio 3.1 define longanfengyue_v3.1 explicitamente. |
EnableSpeechEmotion | bool? | null | Habilita fala emocional onde suportado. Consulte a referência de eventos do cliente para o modelo. |
Instructions | string? | null | Instruções do sistema. |
MaxHistoryTurns | int? | null | Número de rodadas de conversa para manter, de 1 a 50. |
ToolsJson | string? | null | Definições de ferramentas funcionais como uma string JSON array no estilo OpenAI. |
TurnDetectionMode | QwenTurnDetectionMode | ServerVad | Modo 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. |
VadThreshold | double? | null | Limiar de VAD do servidor de -1,0 a 1,0. Aplica-se a ServerVad. |
VadSilenceMs | int? | null | Duraçã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. |
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étodo | Descriçã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. |
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
| Evento | Argumento do evento | Quando é disparado |
|---|---|---|
SessionReady | string? | A sessão está pronta. O valor é session.id. |
UserSpeechStarted | QwenSpeechEventArgs | O VAD do servidor detectou o início da fala do usuário. |
UserSpeechStopped | QwenSpeechEventArgs | O VAD do servidor detectou o fim da fala do usuário. |
UserTranscriptUpdated | QwenTranscriptEventArgs | Transcrição atual de entrada, que pode mudar. |
UserTranscriptCompleted | QwenTranscriptEventArgs | Transcrição final de uma utterance de entrada. |
AssistantTextDelta | QwenTextDeltaEventArgs | Delta de texto da resposta. Concatene os deltas na ordem. |
AssistantTextCompleted | QwenTranscriptEventArgs | Texto completo da resposta. |
AssistantAudioChunk | QwenAudioChunkEventArgs | Trecho de áudio da resposta em 24 kHz mono 16-bit little-endian raw PCM. |
AssistantAudioCompleted | EventArgs | Todo o áudio da resposta para a rodada chegou. |
FunctionCallReceived | QwenFunctionCallEventArgs | O modelo solicitou uma chamada de ferramenta e forneceu o ID da chamada, o nome da função e os argumentos JSON. |
ResponseCompleted | QwenResponseSummary | response.done chegou com status e uso. |
RawServerEvent | QwenServerEventArgs | Evento bruto do servidor com seu tipo e objeto JSON. |
ErrorOccurred | DashScopeErrorEventArgs | Ocorreu um erro no servidor ou falha na conexão. |
Tipos de resultado
| Tipo | Propriedades | Descrição |
|---|---|---|
QwenResponseSummary | Status: 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. |
QwenSpeechEventArgs | AudioMs: long, ItemId: string? | Limite de fala em milissegundos e o ID do item de entrada. |
QwenTranscriptEventArgs | Text: string, ItemId: string? | Transcrição atual ou texto final e o ID do item. |
QwenTextDeltaEventArgs | Delta: string, ItemId: string? | Delta de texto e o ID do item. |
QwenAudioChunkEventArgs | Pcm: byte[] | Trecho de áudio. |
QwenFunctionCallEventArgs | CallId: string, Name: string?, ArgumentsJson: string? | ID da chamada de ferramenta, nome e argumentos. Use o CallId original ao retornar o resultado. |
QwenServerEventArgs | Type: string?, Root: JsonObject | Tipo de evento e JSON completo. |
DashScopeErrorEventArgs | Code: 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ão | Comportamento |
|---|---|
FinishWithoutWait | Envia session.finish e fecha a conexão. Este é o padrão para Audio Realtime. |
CloseOnly | Fecha a conexão. Este é o padrão para Omni Realtime. |
FinishAndWait | Envia session.finish e aguarda session.finished. O servidor também pode encerrar a sessão fechando a conexão. |