ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

用 ElevenLabs TTS + Scribe v2 构建实时语音 Agent:Vision Agents 实战指南

用 ElevenLabs TTS + Scribe v2 构建实时语音 Agent:Vision Agents 实战指南 用 ElevenLabs TTS Scribe v2 构建实时语音 AgentVision Agents 实战指南【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Streams edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents本篇技术指南围绕 Vision Agents 仓库中 plugins/elevenlabs/example/README.md 展开完整讲解如何用 ElevenLabs 的高质量语音合成TTS与 Scribe v2 实时语音识别STT搭建一个可对话的 AI Agent并串联 GetStream 边缘实时通信、Gemini LLM 与智能轮次检测Smart Turn Detection。读完本文你将掌握该示例的环境搭建、运行方式、TTS/STT 的源码级配置参数以及如何自定义音色、识别语言与对话节奏。示例概览一条完整的语音 Agent 链路示例目录plugins/elevenlabs/example展示了一个端到端的语音 AI 代理用户开口说话Agent 实时识别、理解并用自然语音回应。它聚合了以下能力与 示例 README 的 Features 列表一致ElevenLabs TTS高音质、自然的文本转语音支持自定义音色ElevenLabs Scribe v2实时语音转文本低延迟约 150ms支持 99 种语言GetStream实时通信基础设施负责边缘网络的音视频传输Smart Turn Detection自然的对话节奏管理决定何时该结束用户发言、何时轮到 Agent 回应Gemini LLM负责生成智能回复。从 elevenlabs_example.py 可以看到 Agent 的组装方式——所有组件通过声明式配置注入async def create_agent(**kwargs) - Agent: Create the agent with ElevenLabs TTS and STT. agent Agent( edgegetstream.Edge(), agent_userUser(nameFriendly AI, idagent), instructionsYoure a friendly voice AI assistant. Keep your replies conversational, ttselevenlabs.TTS(), # Uses ElevenLabs for text-to-speech sttelevenlabs.STT(), # Uses ElevenLabs Scribe v2 for speech-to-text llmgemini.LLM(gemini-flash-lite-latest), turn_detectionsmart_turn.TurnDetection(), ) return agent这里的elevenlabs.TTS()与elevenlabs.STT()分别对应插件包vision_agents.plugins.elevenlabs中导出的两个类见 插件init.py全部使用默认参数即可开箱即用。环境准备与安装1. 安装依赖示例目录采用 uv 管理依赖example/pyproject.toml 声明了vision-agents-plugins-elevenlabs、vision-agents-plugins-getstream、vision-agents-plugins-smart-turn、vision-agents-plugins-gemini与核心库vision-agents。进入示例目录并同步依赖cd plugins/elevenlabs/example uv sync如果你要在自己的项目中引入该插件也可以直接安装uv add vision-agents[elevenlabs] # 或直接添加插件包 uv add vision-agents-plugins-elevenlabs插件包本体plugins/elevenlabs/pyproject.toml要求 Python 3.10并依赖elevenlabs2.38.1,3与核心库vision-agents。2. 配置环境变量在示例目录下创建.env文件填入三个服务的 API Key# Required for ElevenLabs TTS and STT ELEVENLABS_API_KEYyour_elevenlabs_api_key # Required for GetStream (real-time communication) STREAM_API_KEYyour_stream_api_key STREAM_API_SECRETyour_stream_api_secret # Required for Gemini LLM GEMINI_API_KEYyour_gemini_api_key其中ELEVENLABS_API_KEY是关键源码中 TTS 与 STT 在未显式传入api_key时都会自动回退读取该环境变量见 tts.py 与 stt.py。示例脚本开头会调用load_dotenv()自动加载.env。运行示例安装依赖并配置好密钥后执行uv run elevenlabs_example.py run根据 示例 READMEAgent 会依次执行连接到 GetStream 边缘网络初始化 ElevenLabs TTS 与 Scribe v2 STT加入通话并主动向你问好示例中会先说一句 tell me something interesting in a short sentence实时聆听并回应你的语音输入。对应到 elevenlabs_example.py 的join_call流程核心调用链是create_call创建房间 →agent.join(call)加入通话 →simple_response(...)触发首轮发言 →agent.finish()持续运行直到通话结束async def join_call(agent: Agent, call_type: str, call_id: str, **kwargs) - None: call await agent.create_call(call_type, call_id) logger.info( Starting ElevenLabs Agent...) # Have the agent join the call/room async with agent.join(call): await agent.simple_response(tell me something interesting in a short sentence) await agent.finish() # Run till the call ends源码级解析TTS 与 STT 插件的工作原理TTS流式合成 16kHz PCM 音频ElevenLabs TTS 插件实现在 plugins/elevenlabs/vision_agents/plugins/elevenlabs/tts.py构造参数api_key可选默认读环境变量、voice_id默认VR6AewLTigWG4xSOukaG、model_id默认eleven_multilingual_v2、client可选可传入自定义的AsyncElevenLabs实例输出格式固定为pcm_1600016kHz 单声道 PCMstream_audio()方法调用client.text_to_speech.stream(...)拉取音频流并用PcmData.from_response(...)包装为 16kHz、单声道、S16 格式的音频块tts.py。这意味着合成结果可以直接进入 GetStream 的音频轨道播放无需二次转码close()会通过内部封装关闭底层 httpx 客户端避免资源泄漏。STTScribe v2 实时识别带 VAD 提交与自动重连STT 插件实现在 plugins/elevenlabs/vision_agents/plugins/elevenlabs/stt.py是本文的技术重点。它有四个值得关注的设计1. WebSocket 实时连接 VAD 提交策略。start()建立与 ElevenLabs 的实时识别连接audio_format固定为PCM_16000提交策略为CommitStrategy.VAD——即由 ElevenLabs 服务端的语音活动检测决定何时提交一段完整的转录stt.py。同时注册了PARTIAL_TRANSCRIPT实时部分结果与COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS最终结果含词级时间戳等事件回调。2. 统一的 16kHz 重采样。process_audio()会把任意采样率/声道数的入站音频统一resample(16_000, 1)为 16kHz 单声道stt.py这也是示例 README 建议使用 16kHz 音频以获得最佳识别效果的原因。3. 静音保活机制。_send_audio_loop()会以keepalive_interval_ms默认 5000ms为周期在队列空闲时发送预生成的 1 秒 16-bit PCM 静音帧防止 WebSocket 因长时间无数据被服务端关闭stt.py。这正是对应测试test_connection_survives_idle_after_audio验证的场景。4. 指数退避自动重连。_attempt_reconnect()在连接出错或关闭后以2**attempt秒的退避间隔最多重试 3 次stt.py提升长时间通话场景的稳定性。此外STT 的事件回调会把部分转录replacement 模式与最终转录final 模式转发为TranscriptResponse并自动发出TurnStarted/TurnEnded轮次事件——这部分行为有专门的单元测试覆盖见 tests/test_elevenlabs_stt.py例如多次 partial 只触发一次 TurnStarted、每个已提交语句都产生成对且有序的起止事件。自定义配置音色、识别语言与对话节奏音色与合成模型示例 README 给出两种常用自定义方式# Use a specific voice ID tts elevenlabs.TTS(voice_idyour_voice_id) # Use a different model tts elevenlabs.TTS(model_ideleven_flash_v2_5)voice_id对应 ElevenLabs 语音库中的某个音色 ID可在 ElevenLabs 平台创建/挑选model_id决定合成质量与速度的取舍见下文模型清单。STT 识别配置Scribe v2 实时识别支持以下关键参数# Use a different language stt elevenlabs.STT(language_codees) # Spanish # Adjust VAD settings stt elevenlabs.STT( vad_threshold0.5, vad_silence_threshold_secs2.0, )对照 stt.py 的构造签名完整参数及默认值如下参数默认值说明language_codeen识别语言代码如en、esmodel_idscribe_v2_realtime识别模型vad_silence_threshold_secs0.3VAD 判定静音的时长阈值秒vad_threshold0.4VAD 语音检测阈值min_speech_duration_ms100最小语音时长毫秒min_silence_duration_ms100最小静音时长毫秒audio_chunk_duration_ms100发送音频块时长建议 100–1000mskeepalive_interval_ms5000空闲时发送静音帧的间隔毫秒防止 WebSocket 超时断开示例 README 中的写法把vad_threshold调高到0.5、静音阈值放宽到2.0秒适用于对误触发敏感、允许更长时间停顿的对话场景。轮次检测Turn Detection示例 README 给出的调节方式是turn_detection smart_turn.TurnDetection( buffer_in_seconds2.0, # How long to wait for speech confidence_threshold0.5, # How confident to be before ending turn )需要说明的是该写法是示例中的示意性参数Smart Turn 插件当前源码smart_turn_detection.py中TurnDetection实际暴露的构造参数为vad_reset_interval_seconds默认 5.0周期性重置 VAD 内部状态防止漂移speech_probability_threshold默认 0.5判定为语音的最低概率0.0–1.0即示例中confidence_threshold对应的概念pre_speech_buffer_ms默认 200触发语音检测前预缓冲的音频时长毫秒即示例中buffer_in_seconds对应的概念silence_duration_ms默认 3000判定一轮发言结束所需的尾部静音时长毫秒。你可以按需将上述参数传入smart_turn.TurnDetection(...)。缩短pre_speech_buffer_ms/silence_duration_ms可让 Agent 更快抢话反之则更耐心等待用户说完。ElevenLabs 模型选择根据 示例 README 的模型清单可按场景取舍TTS 模型模型 ID特点适用场景eleven_multilingual_v2高音质、富有情感默认选择追求自然听感的对话eleven_flash_v2_5超快响应、低延迟约 75ms对首字延迟敏感的场景eleven_turbo_v2_5质量与速度均衡通用场景STT 模型scribe_v2_realtime实时转录支持 99 种语言配合 VAD 提交策略可在低延迟约 150ms下获得稳定的流式识别结果。端到端工作流从用户发声到听到回应整条链路如下架构图引自 示例 READMEUser Voice Input ↓ ElevenLabs Scribe v2 STT (Real-time transcription) ↓ Gemini LLM (Generate response) ↓ ElevenLabs TTS (Synthesize speech) ↓ User Hears Response结合前文源码可进一步细化事件流音频帧经 GetStream 边缘网络进入 STT →process_audio重采样入队 → WebSocket 分批发送 → 服务端返回 partial 转录触发TurnStarted→ LLM 在轮次内生成回复 → TTS 流式合成 16kHz PCM → 通过音频轨道播放给用户。测试 tests/test_tts.py 验证了send_iter能持续产出非空音频块并以final结尾tests/test_elevenlabs_stt.py 则覆盖了 16kHz/48kHz 音频、分块流式输入、多次静音分段等真实通话场景的转录正确性。故障排查以下为 示例 README 中 Troubleshooting 章节的完整内容并补充源码依据无音频输出确认ELEVENLABS_API_KEY有效——TTS 在无显式api_key时会读取该环境变量tts.py检查音频设备设置确保 GetStream 连接已建立Agent 需成功join通话。转录质量不佳使用 16kHz 采样率音频以获得最佳效果——STT 虽会自动重采样到 16kHzstt.py但源头质量仍会影响识别吐字清晰、避免背景噪音必要时调整vad_threshold——阈值过高可能漏检轻声过低则容易把噪音当语音。延迟偏高换用eleven_flash_v2_5模型进行 TTS可将合成延迟降至约 75ms 量级检查网络连接质量减小轮次检测中的缓冲参数如pre_speech_buffer_ms缩短 Agent 判定你说完了的时间。延伸阅读想深入了解本文涉及的组件可以在仓库中继续查阅插件完整说明plugins/elevenlabs/README.md含独立使用示例、默认音色与模型 ID示例源码plugins/elevenlabs/example/elevenlabs_example.pySTT 实现plugins/elevenlabs/vision_agents/plugins/elevenlabs/stt.pyTTS 实现plugins/elevenlabs/vision_agents/plugins/elevenlabs/tts.py测试用例plugins/elevenlabs/tests/test_elevenlabs_stt.py 与 plugins/elevenlabs/tests/test_tts.py轮次检测插件plugins/smart_turn/README.md。以 elevenlabs_example.py 为起点替换voice_id、language_code与模型 ID即可快速搭建属于自己的多语言实时语音 Agent。【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Streams edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表