Model Studio C# SDK のインストールと設定、モデルに応じたクライアントの選択、タスクの終了、タイムアウト、エラーの処理方法を説明します。
利用を開始する
事前準備
- .NET 8 SDK または .NET 10 SDK をインストールします。
- API キーの取得の手順に従い、環境変数
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 キー。未設定時は DASHSCOPE_API_KEY を使用。 |
WorkspaceId | string? | X-DashScope-WorkSpace ヘッダーで送信するワークスペース ID。 |
Url | string | 完全なエンドポイント URL。 |
エンドポイント URL の設定
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 キーに対応するワークスペース ID に置き換えてください。
対応機能とモデル
このマネージド .NET SDK は音声やテキストを送信して結果を受信します。録音、コーデック、ウェイクワード検出、端末側の VAD やエコーキャンセルは提供しません。
| 種類 | 対応モデル | C# クライアント |
|---|---|---|
| リアルタイムマルチモーダル |
| QwenRealtimeConversation |
| リアルタイム音声認識 |
| FunAsrSpeechTranscriber |
| リアルタイム音声合成 |
| CosyVoiceSpeechSynthesizer |
| 音声生成 |
| CosyVoiceSpeechSynthesizer |
| リアルタイム音声対話 |
| QwenRealtimeConversation |
| リアルタイム音声・動画翻訳 |
| QwenLiveTranslator |
| 非リアルタイム音声認識(非同期) |
| FunAsrFileTranscriber |
| 非リアルタイム音声認識(単一リクエスト) |
| FunAsrFlashFileTranscriber |
利用上の注意
モデルと音色の互換性
複数のモデル系列が同じクライアントクラスを使用する場合は、Model を明示的に指定してください。省略するとクラスの既定モデルが使用されます。SDK の ModelRouting メソッドは、一部のモデル系列を名前で判定します。モデルに対応するクライアントは、このページの対応モデル表で確認してください。
合成モデルを切り替える際は、選択した音色にそのモデルが対応しているか確認してください。Qwen-Audio-TTS と CosyVoice はクライアントを共有しますが、音色一覧は共通ではありません。音色の選択については Qwen-Audio-TTS の音声リスト と CosyVoice voice list を参照してください。
呼び出しの終了とキャンセル
- リアルタイム音声認識
- リアルタイム音声対話
- 非リアルタイム音声認識
リアルタイム認識と双方向合成では
StopAsync() で最終結果を待ちます。再度呼んでも完了イベントは再発生しません。結果を待たずに切断する CancelAsync() は複数回呼べます。StopAsync() の待機中にキャンセルすると待機中の呼び出しは 240069、キャンセル後に呼ぶと 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 | タスク完了の待機タイムアウト。 |