Azure语音交互免费版

概述

Azure语音交互免费版是一款面向个人开发者的轻量级实时语音AI工具，基于Azure VoiceLive SDK构建。通过WebSocket双向通信实现实时语音交互，支持文本与音频双模态输出。几行Python代码即可建立实时语音会话，适合语音助手原型开发与学习实践.

核心能力

核心功能执行

用input_params参数进行配置.

处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志.

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置.

处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志.

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置.

处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志.

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Azure、VoiceLive、构建基础实时语音、音频输出与基本会、话管理、语音交互免费版、面向个人开发者的、轻量级实时语音、支持文本与音频双、基本会话配置、模态设置、音频流发送与接收、多种语音选择等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景一：基础语音助手

构建一个简单的语音问答助手，用户说话后AI语音回复.

import asyncio
import os
from azure.ai.voicelive.aio import connect
from azure.core.credentials import AzureKeyCredential
# ...
async def voice_assistant():
    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": "你是一个友好的中文语音助手，简洁回答问题。",
            "modalities": ["text", "audio"],
            "voice": "alloy"
        })
# ...
        # 发送音频输入
        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)
        await conn.input_audio_buffer.commit()
# ...
        # 接收响应
        async for event in conn:
            if event.type == "response.audio_transcript.done":
                print(f"AI回复: {event.transcript}")
            elif event.type == "response.audio.delta":
                audio_bytes = base64.b64decode(event.delta)
                await play_audio(audio_bytes)
type == "response.done":
                break
# ...
asyncio.run(voice_assistant())

场景二：文本转语音对话

将文本输入转换为AI语音输出.

async def text_to_speech():
    async with connect(
        endpoint=os.environ["AZURE_COGNITIVE_SERVICES_ENDPOINT"],
environ["AZURE_COGNITIVE_SERVICES_KEY"]),
        model="gpt-4o-realtime-preview"
    ) as conn:
        await conn.session.update(session={
            "instructions": "用中文回答，语速适中。",
            "modalities": ["text", "audio"],
            "voice": "shimmer"
        })
# ...
        # 通过文本创建对话项
        await conn.conversation.item.create(item={
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "你好，请介绍一下你自己。"}]
        })
# ...
        # 触发响应
        await conn.response.create()
# ...
        # 接收音频响应
        async for event in conn:
type == "response.audio_transcript.delta":
                print(event.delta, end="", flush=True)
type == "response.audio.delta":
                audio = base64.b64decode(event.delta)
                await play_audio(audio)
type == "response.done":
                break
# ...
asyncio.run(text_to_speech())

场景三：语音记录与转写

实时语音输入并获取文字转写结果.

async def voice_transcription():
    async with connect(
        endpoint=os.environ["AZURE_COGNITIVE_SERVICES_ENDPOINT"],
environ["AZURE_COGNITIVE_SERVICES_KEY"]),
        model="gpt-4o-realtime-preview"
    ) as conn:
        await conn.session.update(session={
            "instructions": "转录用户的语音内容。",
            "modalities": ["text"],
            "voice": "alloy"
        })
# ...
        # 持续发送音频
        audio_chunk = await read_audio_from_microphone()
        await conn.input_audio_buffer.append(audio=b64_audio)
# ...
        # 接收转写结果
        async for event in conn:
type == "conversation.item.input_audio_transcription.completed":
                print(f"你说: {event.transcript}")
type == "input_audio_buffer.speech_stopped":
                break
# ...
asyncio.run(voice_transcription())

不适用场景

以下场景Azure语音交互免费版不适合处理：

• 无明确技术栈的模糊需求
• 纯架构设计决策
• 运维部署管理

触发条件

需要代码生成、编程辅助、调试测试、开发部署时使用。不适用于非本工具能力范围的需求.

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

依赖详情

pip install azure-ai-voicelive aiohttp azure-identity

2. 配置环境变量

export AZURE_COGNITIVE_SERVICES_ENDPOINT="https://<region>.api.cognitive.microsoft.com"
export AZURE_COGNITIVE_SERVICES_KEY="配置值"

3. 建立第一个语音会话

import asyncio
import 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"],
environ["AZURE_COGNITIVE_SERVICES_KEY"]),
        model="gpt-4o-realtime-preview"
    ) as conn:
        await conn.session.update(session={
            "instructions": "你是一个有帮助的助手。",
            "modalities": ["text", "audio"],
            "voice": "alloy"
        })
# ...
        async for event in conn:
type == "response.audio_transcript.done":
                print(f"回复: {event.transcript}")
type == "response.done":
                break
# ...
asyncio.run(main())

示例

环境变量配置

# .env 文件
AZURE_COGNITIVE_SERVICES_ENDPOINT=https://myresource.api.cognitive.microsoft.com
AZURE_COGNITIVE_SERVICES_KEY=your_api_key_here

语音选项

连接资源说明

最佳实践

1. 音频格式：使用PCM16 24kHz格式，获得最佳识别与合成质量
2. 会话指令：提供清晰简洁的instructions，引导AI行为
3. 资源释放：会话结束后及时关闭连接，释放资源
4. 错误处理：添加连接异常与API错误的处理逻辑
5. 音频缓冲：合理设置音频缓冲区大小，避免延迟或丢数据
6. 模态选择：仅需文本时关闭音频模态，减少带宽消耗

常见问题

Q1：连接失败提示认证错误怎么办？

检查 AZURE_COGNITIVE_SERVICES_KEY 是否正确，确认端点URL格式无误。免费版使用API Key认证.

Q2：语音延迟较高怎么办？

确保网络连接稳定，减少音频缓冲区大小。使用PCM16格式避免转码延迟.

Q3：免费版支持函数调用吗？

免费版不支持函数调用（Function Tools）。如需此功能，请升级至PRO版本.

Q4：如何选择合适的语音？

通用场景选alloy，聊天场景选echo，商务场景选shimmer，可根据应用调性选择.

Q5：支持哪些音频格式？

免费版默认支持PCM16 24kHz格式。如需电话音频格式（8kHz），请使用PRO版本.

依赖说明

运行环境

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

第三方依赖

API Key 配置

• AZURE_COGNITIVE_SERVICES_ENDPOINT：Azure认知服务端点URL
• AZURE_COGNITIVE_SERVICES_KEY：Azure认知服务API密钥
• 免费版使用API Key认证（AzureKeyCredential）

可用性分类

• 分类: MD+EXEC（纯Markdown指令，核心功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行实时语音交互任务。核心功能通过Python异步SDK调用Azure VoiceLive服务实现.
• API Key通过环境变量配置: export API_KEY=your_key

错误处理

已知限制

• 需要API Key，无Key环境无法使用
• 依赖云服务，需要网络连接

输出格式

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