安裝並設定百煉 C# SDK,依模型系列選擇用戶端,瞭解任務結束、逾時與錯誤處理方式。
開始使用
準備工作
- 安裝 .NET 8 SDK 或 .NET 10 SDK。
- 取得 API Key,並設定環境變數
DASHSCOPE_API_KEY。
安裝 SDK
下載並解壓縮 Bailian.DashScope-1.1.1.zip。
NuGet 套件名稱是 Bailian.DashScope,組件是 DashScope.dll,根命名空間為 DashScope。無須安裝原生程式庫或其他 NuGet 相依套件。
- 本機 NuGet 來源(建議)
- 直接參考 DLL
以解壓縮後的
packages/ 目錄作為本機 NuGet 來源。以下範例使用 .NET 8。如使用 .NET 10,請將命令及路徑中的
net8.0 替換為 net10.0。設定連線
公共參數
| 參數 | 類型 | 說明 |
|---|---|---|
ApiKey | string? | API Key;未設定時讀取 DASHSCOPE_API_KEY。 |
WorkspaceId | string? | 業務空間 ID,透過 X-DashScope-WorkSpace 請求標頭傳送。 |
Url | string | 完整介面位址。 |
設定端點網址
設定 WorkspaceId 僅新增業務空間請求標頭,不會修改介面位址。使用業務空間專屬網域時,透過 Url 設定完整位址。
在即時多模態互動、即時語音對話及即時音視訊翻譯中,SDK 會將模型名稱加入 WebSocket URL 的 model 查詢參數。語音辨識、語音合成和音訊產生則透過請求主體傳遞模型名稱。
| 能力 | URL |
|---|---|
| Qwen-Audio / Fun-ASR-Realtime / CosyVoice / Qwen-Audio-TTS-Next | wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference |
| 即時多模態 / 即時語音對話 / 即時音訊與視訊翻譯 | 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 · 即時語音辨識 | wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference |
| Paraformer · 非即時語音辨識 | https://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription |
驗證安裝與設定
在解壓縮後的 demo/DashScope.Cli/ 目錄執行以下命令。範例將音訊轉為 16 kHz 單聲道 PCM,再進行即時語音辨識。請將 WorkspaceId 替換為與 API Key 對應的工作空間 ID。
適用範圍與支援模型
此 SDK 是純受控的 .NET 用戶端,負責向百鍊傳送音訊或文字並接收結果,不提供本機擷取、編解碼、喚醒、端側 VAD 或回音消除。
| 類型 | 支援模型 | C# 用戶端 |
|---|---|---|
| 即時多模態 |
| QwenRealtimeConversation |
| 即時語音辨識 |
| FunAsrSpeechTranscriber |
| 即時語音合成 |
| CosyVoiceSpeechSynthesizer |
| 音訊產生 |
| CosyVoiceSpeechSynthesizer |
| 即時語音對話 |
| QwenRealtimeConversation |
| 即時音訊與視訊翻譯 |
| QwenLiveTranslator |
| 非即時語音辨識(非同步) |
| FunAsrFileTranscriber |
| 非即時語音辨識(單次請求) |
| FunAsrFlashFileTranscriber |
注意事項
模型與音色相容性
多個模型系列共用一個用戶端類別時,請明確設定 Model,否則 SDK 會使用該類別的預設模型。SDK 的 ModelRouting 方法會依名稱比對部分模型系列。請以本頁的支援模型表確認適用的用戶端。
更換合成模型時,請一併確認該模型支援所選音色。Qwen-Audio-TTS 與 CosyVoice 共用一個用戶端,但不共用音色清單。選擇音色請參閱Qwen-Audio-TTS音色列表和CosyVoice音色列表。
結束或取消呼叫
- 即時語音辨識
- 即時語音對話
- 非即時語音辨識
即時辨識與雙工合成使用
StopAsync() 等待最終結果。重複呼叫不會再次觸發完成事件。若要捨棄傳輸中的結果,呼叫 CancelAsync() 立即中斷連線;此方法可重複呼叫。在 StopAsync() 等待期間取消,等待中的呼叫會收到 240069;取消後再呼叫 StopAsync() 會收到 240014。未正常結束就直接釋放,會透過 Failed 事件回報 240069。錯誤碼
呼叫失敗時,等候結果可能會擲出 DashScopeException。即時語音辨識與語音合成也可透過 Failed 事件接收連線錯誤。
可使用 ServerErrorCode 和 ServerErrorMessage 排查伺服器端錯誤。聯絡技術支援時,請提供該次呼叫傳回的 TaskId 與 RequestId(如有)。
| 錯誤碼 | DashScopeErrorCode | 說明 |
|---|---|---|
| 240001 | ConfigInvalid | 設定無效。 |
| 240002 | IllegalParam | 參數無效或缺少參數。 |
| 240014 | StateInvalid | 目前狀態不允許此操作。 |
| 240051 | UpdateAudioError | 傳送音訊失敗。 |
| 240062 | NetworkError | 網路或連線錯誤。 |
| 240069 | SocketClosed | 連線已關閉;從錯誤訊息區分本機取消或遠端關閉。 |
| 240070 | AuthFailed | 驗證失敗。 |
| 240072 | HttpSendFailed | HTTP 請求傳送失敗。 |
| 240073 | HttpReceiveFailed | HTTP 回應本文為空。 |
| 240074 | HttpResponseInvalid | 回應不是有效的 JSON,或缺少必要欄位。 |
| 240075 | HttpServerError | 服務端傳回錯誤,請查看服務端錯誤欄位。 |
| 240080 | ServerError | 伺服器傳回 task-failed,請查看 ServerErrorCode。 |
| 240091 | ConnectionTimeout | 建立連線的逾時。 |
| 240092 | StartTimeout | 等待任務啟動事件的逾時。 |
| 240093 | StopTimeout | 等待任務完成的逾時。 |