SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场azure-ai-voicelive-dotnet

azure-ai-voicelive-dotnet

智能体与模型

查看项目

更新于 10-16 02:50

技能介绍

Azure.AI.VoiceLive（.NET）是用于构建与 Azure AI 进行双向语音交互的实时语音 AI SDK，适合开发实时语音助手类应用。

用途 该 SDK 面向需要实时、双向语音通信的 .NET 应用，通过 WebSocket 连接 Azure AI 服务，实现语音输入、语音输出以及文本交互。

安装 可通过 NuGet 安装以下包： 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

可选：不使用 Entra ID 时使用 API 密钥

AZURE_VOICELIVE_API_KEY=<your-api-key>

认证 推荐使用 Microsoft Entra ID： using Azure.Identity; using Azure.AI.VoiceLive;

Uri endpoint = new Uri("https://your-resource.cognitiveservices.azure.com"); DefaultAzureCredential credential = new DefaultAzureCredential(); VoiceLiveClient client = new VoiceLiveClient(endpoint, credential); 所需角色：Cognitive Services User（在 Azure 门户 → 访问控制中分配）。

也可使用 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. 启动会话并配置：创建 VoiceLiveClient，调用 StartSessionAsync 启动会话，并通过 VoiceLiveSessionOptions 配置模型、指令、语音、轮次检测、输入/输出音频格式以及模态（文本与音频）。
  2. 处理事件：通过 GetUpdatesAsync 异步遍历 SessionUpdate 事件，处理音频增量、文本增量、函数调用参数完成、错误以及响应完成等事件。
  3. 发送用户消息：使用 AddItemAsync 添加 UserMessageItem，再调用 StartResponseAsync。
  4. 函数调用：定义 VoiceLiveFunctionDefinition 并加入会话选项，在事件循环中处理 SessionUpdateResponseFunctionCallArgumentsDone，调用外部服务后通过 FunctionCallOutputItem 返回结果并再次 StartResponseAsync。

语音选项 支持 Azure Standard（如 "en-US-AvaNeural"）、Azure HD（如 "en-US-Ava:DragonHDLatestNeural"）以及 Azure Custom（带端点 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（文本块事件）。

最佳实践 始终同时设置文本与音频两种模态；使用 AzureSemanticVadTurnDetection 以获得自然对话流；配置合适的静音时长（典型 500ms，避免过早截断）；使用 using 语句确保会话正确释放；处理所有事件类型（错误、音频、文本、函数调用）；使用 DefaultAzureCredential，避免硬编码 API 密钥。

错误处理 在事件循环中检查 SessionUpdateError；若错误消息包含 "Cancellation failed: no active response" 可视为良性错误忽略，否则输出错误信息。

音频配置 输入格式：InputAudioFormat.Pcm16（16 位 PCM）；输出格式：OutputAudioFormat.Pcm16；推荐采样率 24kHz；单声道。

相关 SDK Azure.AI.VoiceLive（本 SDK，实时语音）、Microsoft.CognitiveServices.Speech（语音转文本、文本转语音）、NAudio（音频采集/播放）。

参考链接 NuGet 包：https://www.nuget.org/packages/Azure.AI.VoiceLive API 参考：https://learn.microsoft.com/dotnet/api/azure.ai.voicelive GitHub 源码：https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.VoiceLive 快速入门：https://learn.microsoft.com/azure/ai-services/speech-service/voice-live-quickstart

适用场景 适用于需要实时双向语音交互的 .NET 应用，例如语音助手、实时对话系统等。

限制 仅在任务明确匹配上述范围时使用；不应将输出视为环境特定验证、测试或专家评审的替代；若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。