Instale e configure o SDK C# do Model Studio, escolha o cliente da família de modelos e saiba como lidar com a conclusão de tarefas, tempos limite e erros.
Primeiros passos
Pré-requisitos
- Instale o SDK do .NET 8 ou do .NET 10.
- Obter uma API key e defina a variável de ambiente
DASHSCOPE_API_KEY.
Instalar o SDK
Baixe e extraia Bailian.DashScope-1.1.1.zip.
O pacote NuGet chama-se Bailian.DashScope, o assembly é DashScope.dll e o namespace raiz é DashScope. Não há dependências nativas ou transitivas do NuGet.
- Fonte NuGet local (recomendado)
- Referenciar a DLL diretamente
Use o diretório
packages/ extraído como fonte NuGet local.Os exemplos usam .NET 8. Para .NET 10, substitua
net8.0 por net10.0 nos comandos e caminhos.Configurar a conexão
Parâmetros comuns
| Parâmetro | Tipo | Descrição |
|---|---|---|
ApiKey | string? | API key; se omitida, lê DASHSCOPE_API_KEY. |
WorkspaceId | string? | ID do workspace, enviado em X-DashScope-WorkSpace. |
Url | string | URL completo do endpoint. |
Configurar a URL do endpoint
WorkspaceId adiciona o cabeçalho do workspace, sem alterar o endpoint. Defina o endpoint completo do workspace em Url.
Na interação multimodal, na conversa por voz e na tradução de áudio e vídeo em tempo real, o SDK adiciona o nome do modelo à URL do WebSocket como parâmetro de consulta model. No reconhecimento de fala, na síntese de fala e na geração de áudio, o nome é enviado no corpo da requisição.
| Recurso | URL |
|---|---|
| Qwen-Audio / Fun-ASR-Realtime / CosyVoice / Qwen-Audio-TTS-Next | wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference |
| Multimodal em tempo real / Conversa por voz em tempo real / Tradução de áudio e vídeo em tempo real | wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime |
| Qwen-Audio-ASR-Filetrans / Fun-ASR | https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription |
| Qwen-Audio-ASR / Fun-ASR-Flash | https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation |
| Paraformer · Reconhecimento de fala em tempo real | wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference |
| Paraformer · Reconhecimento de fala não em tempo real | https://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription |
Verificar a instalação e a configuração
Execute os comandos no diretório demo/DashScope.Cli/ extraído. O exemplo converte o áudio em PCM mono de 16 kHz para reconhecimento de fala em tempo real. Substitua WorkspaceId pelo ID do workspace da chave de API.
Recursos e modelos compatíveis
Este SDK .NET gerenciado envia áudio ou texto e recebe resultados. Ele não oferece captura, codecs, detecção de palavras de ativação, VAD local ou cancelamento de eco.
| Tipo | Modelos compatíveis | Cliente C# |
|---|---|---|
| Multimodal em tempo real |
| QwenRealtimeConversation |
| Reconhecimento de fala em tempo real |
| FunAsrSpeechTranscriber |
| Síntese de fala em tempo real |
| CosyVoiceSpeechSynthesizer |
| Geração de Áudio |
| CosyVoiceSpeechSynthesizer |
| Conversa por voz em tempo real |
| QwenRealtimeConversation |
| Tradução de áudio e vídeo em tempo real |
| QwenLiveTranslator |
| Reconhecimento de fala não em tempo real (assíncrono) |
| FunAsrFileTranscriber |
| Reconhecimento de fala não em tempo real (requisição única) |
| FunAsrFlashFileTranscriber |
Observações de uso
Compatibilidade entre modelos e vozes
Se várias famílias de modelos usarem a mesma classe de cliente, defina Model explicitamente. Caso contrário, o SDK usará o modelo padrão da classe. Os métodos ModelRouting do SDK identificam algumas famílias de modelos pelo nome. Para escolher o cliente, consulte a tabela de modelos compatíveis desta página.
Ao trocar o modelo de síntese, escolha uma voz compatível com ele. Qwen-Audio-TTS e CosyVoice usam o mesmo cliente, mas não a mesma lista de vozes. Para escolher uma voz, consulte Lista de vozes do Qwen-Audio-TTS e Lista de vozes do CosyVoice.
Concluir ou cancelar uma chamada
- Reconhecimento de fala em tempo real
- Conversa por voz em tempo real
- Reconhecimento de fala não em tempo real
Em reconhecimento em tempo real e síntese duplex, aguarde
StopAsync() para receber os resultados finais. Chamadas repetidas não disparam outro evento de conclusão. CancelAsync() encerra a conexão sem esperar e pode ser chamado mais de uma vez.Cancelar durante a espera de StopAsync() faz essa chamada falhar com 240069. Chamar StopAsync() após o cancelamento resulta em 240014. Liberar uma tarefa inacabada gera 240069 no evento Failed.Códigos de erro
Se uma chamada falhar, aguardar seu resultado pode lançar DashScopeException. No reconhecimento e na síntese de fala em tempo real, o evento Failed também informa erros de conexão.
Use ServerErrorCode e ServerErrorMessage para diagnosticar erros do servidor. Ao contatar o suporte técnico, informe o TaskId e o RequestId retornados pela chamada, se disponíveis.
| Código de erro | DashScopeErrorCode | Descrição |
|---|---|---|
| 240001 | ConfigInvalid | Configuração inválida. |
| 240002 | IllegalParam | Parâmetro inválido ou ausente. |
| 240014 | StateInvalid | Operação não permitida no estado atual. |
| 240051 | UpdateAudioError | Falha no envio de áudio. |
| 240062 | NetworkError | Erro de rede ou conexão. |
| 240069 | SocketClosed | Conexão encerrada; consulte a mensagem para distinguir cancelamento local de fechamento remoto. |
| 240070 | AuthFailed | Falha de autenticação. |
| 240072 | HttpSendFailed | Falha no envio da solicitação HTTP. |
| 240073 | HttpReceiveFailed | O corpo da resposta HTTP está vazio. |
| 240074 | HttpResponseInvalid | JSON inválido ou campo obrigatório ausente. |
| 240075 | HttpServerError | O servidor retornou um erro; consulte os campos de erro do servidor. |
| 240080 | ServerError | O serviço retornou task-failed. Consulte ServerErrorCode. |
| 240091 | ConnectionTimeout | Tempo limite de conexão. |
| 240092 | StartTimeout | Tempo limite de espera pelo evento de início da tarefa. |
| 240093 | StopTimeout | Tempo limite de espera pela conclusão da tarefa. |