Azure Voicelive Tool Free

使用Azure VoiceLive构建基础实时语音AI应用，支持文本/音频输出与基本会话管理。

Azure语音交互免费版

概述

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

核心能力

能力	说明
实时语音通信	通过WebSocket建立双向实时语音连接
双模态输出	同时支持文本与音频输出
会话配置	设置指令、语音类型、模态等基本参数
音频流处理	发送与接收Base64 PCM16音频流
多语音选择	支持alloy、echo、shimmer等多种语音
API Key认证	简单的API Key认证方式
技术实现要点：核心能力基于input_params参数与output_format配置实现,支持创建/查询/修改/删除等操作模式,通过config_options进行运行时配置。

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 按照skill规范执行核心功能执行操作,遵循单一意图原则。 输出: 返回核心功能执行的执行结果,包含操作状态和输出数据。

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

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 按照skill规范执行参数配置与调用操作,遵循单一意图原则。 输出: 返回参数配置与调用的执行结果,包含操作状态和输出数据。

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

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 按照skill规范执行结果处理与输出操作,遵循单一意图原则。 输出: 返回结果处理与输出的执行结果,包含操作状态和输出数据。

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

使用场景

场景一：基础语音助手

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

python

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)
            elif event.type == "response.done":
                break

asyncio.run(voice_assistant())

场景二：文本转语音对话

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

python

async def text_to_speech():
    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": "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:
            if event.type == "response.audio_transcript.delta":
                print(event.delta, end="", flush=True)
            elif event.type == "response.audio.delta":
                audio = base64.b64decode(event.delta)
                await play_audio(audio)
            elif event.type == "response.done":
                break

asyncio.run(text_to_speech())

场景三：语音记录与转写

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

python

async def voice_transcription():
    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"],
            "voice": "alloy"
        })

        # 持续发送音频
        audio_chunk = await read_audio_from_microphone()
        b64_audio = base64.b64encode(audio_chunk).decode()
        await conn.input_audio_buffer.append(audio=b64_audio)

        # 接收转写结果
        async for event in conn:
            if event.type == "conversation.item.input_audio_transcription.completed":
                print(f"你说: {event.transcript}")
            elif event.type == "input_audio_buffer.speech_stopped":
                break

asyncio.run(voice_transcription())

不适用场景

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

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

触发条件

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

快速开始

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

依赖详情

bash

pip install azure-ai-voicelive aiohttp azure-identity

2. 配置环境变量

bash

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

3. 建立第一个语音会话

python

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"],
        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"
        })

        async for event in conn:
            if event.type == "response.audio_transcript.done":
                print(f"回复: {event.transcript}")
            elif event.type == "response.done":
                break

asyncio.run(main())

示例

环境变量配置

bash

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

语音选项

语音	描述	适用场景
alloy	中性平衡	通用场景
echo	温暖对话	聊天助手
shimmer	清晰专业	商务应用
sage	沉稳权威	知识问答
coral	友好活泼	娱乐互动

连接资源说明

资源	用途	关键方法
conn.session	会话配置	update(session=...)
conn.response	模型响应	create(), cancel()
conn.input_audio_buffer	音频输入	append(), commit(), clear()
conn.output_audio_buffer	音频输出	clear()
conn.conversation	对话状态	item.create(), item.delete()

最佳实践

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及以上

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供
Python 3	运行时	必需	python.org 下载安装
azure-ai-voicelive	Python SDK	必需	pip install azure-ai-voicelive
aiohttp	Python库	必需	pip install aiohttp
azure-identity	Python库	必需	pip install azure-identity
Azure认知服务	云服务	必需	Azure门户创建资源

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

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

已知限制

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