azure-ai-voicelive-py-free

Azure VoiceLive 实时语音AI (免费版)

输入参数

前置条件

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

能力清单

• 通过 azure.ai.voicelive.aio.connect 建立与Azure认知服务的WebSocket双向流式连接,使用 gpt-4o-realtime-preview 实时模型进行语音对话
• 使用 AzureKeyCredential API密钥认证,通过 AZURE_COGNITIVE_SERVICES_ENDPOINT 与 AZURE_COGNITIVE_SERVICES_KEY 环境变量配置
• 支持 session.update 配置 instructions、modalities、voice 与 input_audio_format/output_audio_format
• 内置 alloy、echo、shimmer 三种基础OpenAI音色,默认音频格式 pcm16 (24kHz)
• 监听 response.audio.delta 接收base64 PCM音频,response.audio_transcript.done 接收完整文字转写
• 支持服务端VAD (server_vad) 自动检测话音起止,默认 threshold 0.5、silence_duration_ms 500ms

实操说明

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

适用范围

• 语音助手原型: 快速搭建可对话的语音助手Demo,验证Azure实时模型效果
• 文字转写验证: 通过 modalities=["text","audio"] 同时获取音频与转写文本,用于校验识别准确率

安装与环境

pip install azure-ai-voicelive aiohttp

必要环境变量:

AZURE_COGNITIVE_SERVICES_ENDPOINT=https://.api.cognitive.microsoft.com
AZURE_COGNITIVE_SERVICES_KEY=

基础用法

import asyncio, os
from azure.ai.voicelive.aio import connect
from azure.core.credentials import AzureKeyCredential
# ...
async def main():
    async with connect(
        endpoint=os.environ["AZURE_COGNITIVE_SERVICES_ENDPOINT"],
        credential=AzureKeyCredential(os.environ["AZURE_COGNITIVE_SERVICES_KEY"]),
        model="gpt-4o-realtime-preview"
    ) as conn:
        await conn.session.update(session={
            "instructions": "You are a helpful assistant.",
            "modalities": ["text", "audio"],
            "voice": "alloy"
        })
# ...
        async for event in conn:
            if event.type == "response.audio_transcript.done":
                print(f"Transcript: {event.transcript}")
            elif event.type == "response.done":
                break
# ...
asyncio.run(main())

案例展示

案例一： 接收音频流并解码播放

监听 response.audio.delta 事件,将base64音频块解码为PCM字节送入扬声器:

import base64
# ...
async for event in conn:
    if event.type == "response.audio.delta":
        audio_bytes = base64.b64decode(event.delta)
        # 将audio_bytes写入音频播放设备
    elif event.type == "response.audio.done":
        print("Audio playback complete")
    elif event.type == "response.done":
        break

案例二： 发送麦克风音频

读取麦克风PCM块,base64编码后通过 input_audio_buffer.append 上行:

import base64
# ...
audio_chunk = await read_audio_from_microphone()
b64_audio = base64.b64encode(audio_chunk).decode()
await conn.input_audio_buffer.append(audio=b64_audio)

异常应对

WebSocket连接中断

现象: 抛出 ConnectionClosed 异常,带 code 与 reason. 原因: 网络抖动、服务端超时、长时间无音频收发. 处理: 捕获异常后重新调用 connect() 建立连接并重新 session.update,简单场景可外层 while True 检查网络连接和配置后重试3次.

鉴权失败 (401)

现象: 事件流收到 error 事件,code 为 unauthorized. 原因: AZURE_COGNITIVE_SERVICES_KEY 错误或已轮换、endpoint区域与资源不匹配. 处理: 在Azure门户复核密钥,确认endpoint域名中的region与资源部署区域一致;密钥通过环境变量注入,避免硬编码.

音色不可用

现象: session.update 返回 voice_not_found. 原因: 免费版仅支持 alloy/echo/shimmer 三种基础音色,其他音色需付费版. 处理: 切换到三种基础音色之一;若需 sage/coral/ash/ballad/verse 或Azure原生音色,请升级付费版.

事件流无响应

现象: 调用 response.create() 后长时间未收到任何事件. 原因: 会话未配置 modalities,或 instructions 为空导致模型无输出. 处理: 确认 session.update 已设置 modalities=["text","audio"] 与非空 instructions;检查 input_audio_buffer.commit() 是否在手动模式下被调用.

音频格式不匹配

现象: 上行音频被服务端丢弃,转写结果为空. 原因: 实际采样率与 input_audio_format 配置不一致. 处理: 免费版默认 pcm16 24kHz,麦克风采集需匹配该采样率;若设备为16kHz需付费版支持 pcm16-16000hz.

热门问题

Q1: 免费版支持哪些音色?

免费版仅支持 alloy、echo、shimmer 三种基础OpenAI音色。sage、coral、ash、ballad、verse 与Azure原生音色 (AzureStandardVoice/AzureCustomVoice/AzurePersonalVoice) 需升级付费版.

Q2: 免费版能用DefaultAzureCredential吗?

免费版仅支持 AzureKeyCredential API密钥认证。DefaultAzureCredential(托管身份/AAD令牌/Key Vault轮换)属付费版能力,适合生产环境.

Q3: 如何同时拿到音频和文字?

配置 modalities=["text","audio"] 后,同一响应会同时派发 response.audio.delta(base64 PCM)与 response.audio_transcript.delta(增量文本),response.audio_transcript.done 给出完整转写.

Q4: 免费版支持函数调用吗?

不支持。FunctionTool 工具集成、response.function_call_arguments.done 事件处理与 conversation.item.create 回填流程属付费版能力.

功能边界

• 仅支持 alloy/echo/shimmer 三种基础音色,不包含5种扩展音色与Azure原生音色
• 仅支持 AzureKeyCredential 认证,不包含 DefaultAzureCredential 托管身份
• 仅支持 server_vad 端点检测,不包含 azure_semantic_vad 系列语义VAD
• 不支持 FunctionTool 函数调用与多轮工具链
• 不支持手动轮次模式 (turn_detection: None) 与用户打断处理
• 默认音频格式 pcm16 24kHz,不包含8kHz/16kHz/G711电话格式

升级提示

当前为免费版,仅包含基础语音对话能力。升级付费版可获得:

• 完整8种OpenAI音色 + Azure原生音色 (AzureCustomVoice/AzurePersonalVoice)
• DefaultAzureCredential 托管身份认证,适配生产环境
• FunctionTool 函数调用与多轮工具链
• azure_semantic_vad 语义VAD与手动轮次模式
• pcm16-8000hz/pcm16-16000hz/g711_ulaw/g711_alaw 电话音频格式
• 用户打断处理与 transcription_session 纯转写模式

付费版slug: azure-ai-voicelive-py

输出说明

{
  "success": true,
  "data": {
    "result": "Azure实时语音AI免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "azure-ai-voicelive-py"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}

质量增强补充

可靠性增强(Reliability Enhancement)

已实现以下异常处理与可靠性保障:

• • 边界条件检查(空输入、超长输入等edge case)
• 降级策略与默认值(fallback/default value)处理

适用性增强(Adaptability Enhancement)

• • 限制说明(limitation)与不适用场景
• 触发条件(trigger)与激活方式

技术创新

效率提升量化分析

差异化对比

核心痛点解决

排障手册

安全告示

1. 确保API Key安全，避免泄露到版本控制系统。
2. 定期更新API Key，防止被恶意使用。
3. 限制API Key的使用范围，只允许必要的操作。
4. 使用HTTPS协议进行数据传输，确保数据安全。
5. 对敏感数据进行加密处理，防止数据泄露。

安全风险防范

能力一览

• 自动化执行: Azure VoiceLive SDK基础实时语音对话能力,支持API Key认证、流式音频与文字转写。
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果

用户问题集锦

Q1: Azure实时语音AI免费版支持哪些输入格式？

A1: Azure VoiceLive SDK基础实时语音对话能力,支持API Key认证、流式音频与文字转写。。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

错误恢复流程

针对Azure实时语音AI免费版使用中可能遇到的常见问题,提供以下排查方案:

Azure实时语音AI免费版通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

疑问解答集

异常恢复方案

针对Azure实时语音AI免费版使用中可能遇到的常见问题,提供以下排查方案: