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.
AvisoMantenha as chaves de API de longa duração no servidor. Não as inclua em aplicativos de desktop, dispositivos móveis ou navegador que você distribui. Consulte Proteger a chave de API.
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)
Use o diretório packages/ extraído como fonte NuGet local.
ObservaçãoOs exemplos usam .NET 8. Para .NET 10, substitua net8.0 por net10.0 nos comandos e caminhos.
dotnet new console --framework net8.0 --name SpeechExample
cd SpeechExample
dotnet add package Bailian.DashScope --version 1.1.1 --source "/path/to/Bailian.DashScope-1.1.1/packages"
Referenciar a DLL diretamente
Para referências diretas a DLL, escolha sdk/net8.0/DashScope.dll ou sdk/net10.0/DashScope.dll conforme o framework de destino. Mantenha DashScope.xml junto à DLL para documentação no IDE.
<ItemGroup>
<Reference Include="DashScope">
<HintPath>/path/to/Bailian.DashScope-1.1.1/sdk/net8.0/DashScope.dll</HintPath>
</Reference>
</ItemGroup>
Para verificar os arquivos, execute este comando no diretório do pacote extraído:
shasum -a 256 -c SHA256SUMS.txt
Configurar a conexão
Parâmetros comuns
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
| API key; se omitida, lê |
|
| ID do workspace, enviado em |
|
| 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 |
|
Multimodal em tempo real / Conversa por voz em tempo real / Tradução de áudio e vídeo em tempo real |
|
Qwen-Audio-ASR-Filetrans / Fun-ASR |
|
Qwen-Audio-ASR / Fun-ASR-Flash |
|
Paraformer · Reconhecimento de fala em tempo real |
|
Paraformer · Reconhecimento de fala não em tempo real |
|
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.
dotnet build -p:TargetFrameworks=net8.0
curl -fL "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav" -o input.wav
ffmpeg -i input.wav -f s16le -ac 1 -ar 16000 input.pcm
dotnet bin/Debug/net8.0/DashScope.Cli.dll asr --audio input.pcm --model qwen-audio-3.1-asr-flash-streaming --url "wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference"
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 |
|
|
Reconhecimento de fala em tempo real |
|
|
Síntese de fala em tempo real |
|
|
Geração de Áudio |
|
|
Conversa por voz em tempo real |
|
|
Tradução de áudio e vídeo em tempo real |
|
|
Reconhecimento de fala não em tempo real (assíncrono) |
|
|
Reconhecimento de fala não em tempo real (requisição única) |
|
|
No diretório do projeto de demonstração já compilado, execute o comando a seguir para listar os IDs de modelo incluídos na demonstração.
dotnet bin/Debug/net8.0/DashScope.Cli.dll models --names-only
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
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.
Conversa por voz em tempo real
Em conversas ou traduções, chame FinishAsync() após a última resposta. O cliente escolhe o FinishMode conforme o modelo.
Reconhecimento de fala não em tempo real
Cancelar a espera local não cancela a transcrição remota; use CancelTaskAsync(taskId) enquanto a tarefa estiver na fila.
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 |
| Configuração inválida. |
240002 |
| Parâmetro inválido ou ausente. |
240014 |
| Operação não permitida no estado atual. |
240051 |
| Falha no envio de áudio. |
240062 |
| Erro de rede ou conexão. |
240069 |
| Conexão encerrada; consulte a mensagem para distinguir cancelamento local de fechamento remoto. |
240070 |
| Falha de autenticação. |
240072 |
| Falha no envio da solicitação HTTP. |
240073 |
| O corpo da resposta HTTP está vazio. |
240074 |
| JSON inválido ou campo obrigatório ausente. |
240075 |
| O servidor retornou um erro; consulte os campos de erro do servidor. |
240080 |
| O serviço retornou |
240091 |
| Tempo limite de conexão. |
240092 |
| Tempo limite de espera pelo evento de início da tarefa. |
240093 |
| Tempo limite de espera pela conclusão da tarefa. |