Azure.AI.VoiceLive (.NET)
Azure AIによる双方向音声アシスタントを構築するためのリアルタイム音声AI SDK。
インストール
dotnet add package Azure.AI.VoiceLive
dotnet add package Azure.Identity
dotnet add package NAudio
現在のバージョン: 安定版 v1.0.0、プレビュー版 v1.1.0-beta.1
環境変数
AZURE_VOICELIVE_ENDPOINT=https://<resource>.services.ai.azure.com/
AZURE_VOICELIVE_MODEL=gpt-4o-realtime-preview
AZURE_VOICELIVE_VOICE=en-US-AvaNeural
AZURE_VOICELIVE_API_KEY=<your-api-key>
AZURE_TOKEN_CREDENTIALS=prod
認証
Microsoft Entra トークン資格情報
using Azure.Identity;
using Azure.AI.VoiceLive;
Uri endpoint = new Uri("https://your-resource.cognitiveservices.azure.com");
var credential = new DefaultAzureCredential(
DefaultAzureCredential.DefaultEnvironmentVariableName
);
VoiceLiveClient client = new VoiceLiveClient(endpoint, credential);
必要なロール: Cognitive Services ユーザー (Azure Portal → アクセス制御 で割り当て)
API キー
Uri endpoint = new Uri("https://your-resource.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("your-api-key");
VoiceLiveClient client = new VoiceLiveClient(endpoint, credential);
クライアント階層
VoiceLiveClient
└── VoiceLiveSession (WebSocket 接続)
├── ConfigureSessionAsync()
├── GetUpdatesAsync() → SessionUpdate イベント
├── AddItemAsync() → UserMessageItem, FunctionCallOutputItem
├── SendAudioAsync()
└── StartResponseAsync()
コアワークフロー
1. セッションの開始と設定
using Azure.Identity;
using Azure.AI.VoiceLive;
var endpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_VOICELIVE_ENDPOINT"));
var client = new VoiceLiveClient(endpoint, new DefaultAzureCredential());
var model = "gpt-4o-mini-realtime-preview";
using VoiceLiveSession session = await client.StartSessionAsync(model);
VoiceLiveSessionOptions sessionOptions = new()
{
Model = model,
Instructions = "あなたは親切なAIアシスタントです。自然に応答してください。",
Voice = new AzureStandardVoice("en-US-AvaNeural"),
TurnDetection = new AzureSemanticVadTurnDetection()
{
Threshold = 0.5f,
PrefixPadding = TimeSpan.FromMilliseconds(300),
SilenceDuration = TimeSpan.FromMilliseconds(500)
},
InputAudioFormat = InputAudioFormat.Pcm16,
OutputAudioFormat = OutputAudioFormat.Pcm16
};
sessionOptions.Modalities.Clear();
sessionOptions.Modalities.Add(InteractionModality.Text);
sessionOptions.Modalities.Add(InteractionModality.Audio);
await session.ConfigureSessionAsync(sessionOptions);
2. イベントの処理
await foreach (SessionUpdate serverEvent in session.GetUpdatesAsync())
{
switch (serverEvent)
{
case SessionUpdateResponseAudioDelta audioDelta:
byte[] audioData = audioDelta.Delta.ToArray();
break;
case SessionUpdateResponseTextDelta textDelta:
Console.Write(textDelta.Delta);
break;
case SessionUpdateResponseFunctionCallArgumentsDone functionCall:
break;
case SessionUpdateError error:
Console.WriteLine($"エラー: {error.Error.Message}");
break;
case SessionUpdateResponseDone:
Console.WriteLine("\n--- 応答完了 ---");
break;
}
}
3. ユーザーメッセージの送信
await session.AddItemAsync(new UserMessageItem("こんにちは、助けてくれますか？"));
await session.StartResponseAsync();
4. 関数呼び出し
var weatherFunction = new VoiceLiveFunctionDefinition("get_current_weather")
{
Description = "指定された場所の現在の天気を取得します",
Parameters = BinaryData.FromString("""
{
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "都市と州または国"
}
},
"required": ["location"]
}
""")
};
sessionOptions.Tools.Add(weatherFunction);
if (serverEvent is SessionUpdateResponseFunctionCallArgumentsDone functionCall)
{
if (functionCall.Name == "get_current_weather")
{
var parameters = JsonSerializer.Deserialize<Dictionary<string, string>>(functionCall.Arguments);
string location = parameters?["location"] ?? "";
string weatherInfo = $"{location}の天気は晴れ、75°Fです。";
await session.AddItemAsync(new FunctionCallOutputItem(functionCall.CallId, weatherInfo));
await session.StartResponseAsync();
}
}
音声オプション
| 音声タイプ | クラス | 例 |
|---|
| Azure 標準 | AzureStandardVoice | "en-US-AvaNeural" |
| Azure HD | AzureStandardVoice | "en-US-Ava:DragonHDLatestNeural" |
| Azure カスタム | AzureCustomVoice | エンドポイントID付きカスタム音声 |
サポートされているモデル
| モデル | 説明 |
|---|
gpt-4o-realtime-preview | リアルタイム音声対応 GPT-4o |
gpt-4o-mini-realtime-preview | 軽量、高速な対話 |
phi4-mm-realtime | コスト効率の高いマルチモーダル |
主要な型リファレンス
| 型 | 目的 |
|---|
VoiceLiveClient | セッションを作成するためのメインクライアント |
VoiceLiveSession | アクティブな WebSocket セッション |
VoiceLiveSessionOptions | セッション設定 |
AzureStandardVoice | 標準の Azure 音声プロバイダー |
AzureSemanticVadTurnDetection | 音声アクティビティ検出 |
VoiceLiveFunctionDefinition | 関数ツールの定義 |
UserMessageItem | ユーザーテキストメッセージ |
FunctionCallOutputItem | 関数呼び出しの応答 |
SessionUpdateResponseAudioDelta | 音声チャンクイベント |
SessionUpdateResponseTextDelta | テキストチャンクイベント |
ベストプラクティス
- 常に両方のモダリティを設定する — 音声アシスタントの場合は
Text と Audio を含める
AzureSemanticVadTurnDetection を使用する — 自然な会話フローを提供- 適切な無音時間を設定する — 通常500msで早期遮断を防止
using ステートメントを使用する — セッションの適切な破棄を保証- すべてのイベントタイプを処理する — エラー、音声、テキスト、関数呼び出しを確認
DefaultAzureCredential を使用する — APIキーをハードコードしない
エラーハンドリング
if (serverEvent is SessionUpdateError error)
{
if (error.Error.Message.Contains("Cancellation failed: no active response"))
{
}
else
{
Console.WriteLine($"エラー: {error.Error.Message}");
}
}
オーディオ設定
- 入力形式:
InputAudioFormat.Pcm16 (16ビット PCM)
- 出力形式:
OutputAudioFormat.Pcm16
- サンプルレート: 24kHz 推奨
- チャンネル数: モノラル
関連SDK
| SDK | 目的 | インストール |
|---|
Azure.AI.VoiceLive | リアルタイム音声 (このSDK) | dotnet add package Azure.AI.VoiceLive |
Microsoft.CognitiveServices.Speech | 音声認識、テキスト読み上げ | dotnet add package Microsoft.CognitiveServices.Speech |
NAudio | オーディオキャプチャ/再生 | dotnet add package NAudio |
参考リンク