Vision Agents 集成 Pocket TTS基于 Kyutai 模型的本地 CPU 语音合成实践【免费下载链接】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本指南以仓库中 plugins/pocket/example/README.md 为骨架讲解如何在 Vision Agents 项目中接入 Pocket TTS一个完全运行在 CPU 上的轻量级文本转语音TTS插件。读完本文你将掌握 Pocket TTS 插件的安装方式、pocket.TTS的完整用法内置音色选择与自定义语音克隆、示例 Agent 的启动步骤以及其底层基于线程池与 PCM 流式输出的源码实现原理可直接复制运行一个本地语音合成 云端 STT/LLM的完整语音 Agent。Pocket TTS 是什么Pocket TTS 是 Kyutai 实验室开源的轻量级 TTS 模型约 1 亿参数由 Vision Agents 仓库中的 Pocket 插件plugins/pocket封装集成。其核心特点包括纯 CPU 运行不需要 GPU也不需要任何 TTS 云服务 API Key推理完全在本地完成低延迟约 200ms 即可输出首批音频比实时速度快 10 倍以上语音克隆支持传入自定义 wav 音频路径快速复刻目标音色内置音色选择开箱即用提供 8 个内置音色无需额外准备样本。插件依赖pocket-tts1.1.1与 PyTorch 2.5见 plugins/pocket/pyproject.toml并通过vision_agents.plugins.pocket命名空间对外暴露与仓库中其他插件Deepgram STT、Gemini LLM、GetStream edge保持一致的接口风格。安装与依赖Pocket 插件作为独立包发布支持两种安装方式见 plugins/pocket/README.md# 方式一通过 vision-agents 的 pocket extra 安装 uv add vision-agents[pocket] # 方式二直接安装独立插件包 uv add vision-agents-plugins-pocket项目要求 Python 3.10plugins/pocket/pyproject.toml。安装后即可从顶层命名空间导入from vision_agents.plugins import pocket核心 APIpocket.TTS 的初始化与音色配置插件唯一的对外入口是pocket.TTSplugins/pocket/vision_agents/plugins/pocket/init.py 中导出。构造参数与取值如下plugins/pocket/README.md 配置表参数描述取值voice内置音色名或自定义 wav 文件路径alba默认、marius、javert、jean、fantine、cosette、eponine、azelma或任意自定义路径client可选预初始化的TTSModel实例通常不需要手动传入留空由插件自管理三种典型初始化方式from vision_agents.plugins import pocket # 1. 默认音色alba tts pocket.TTS() # 2. 指定内置音色 tts pocket.TTS(voicemarius) # 3. 自定义 wav 路径实现语音克隆 tts pocket.TTS(voicepath/to/your/voice.wav)从源码看plugins/pocket/vision_agents/plugins/pocket/tts.pyvoice参数既可以是内置音色名也可以是任意路径内置音色名会被VOICE_PATHS字典解析为 Hugging Face 上的参考音频地址如hf://kyutai/tts-voices/alba-mackenna/casual.wav而传入的路径值含hf://形式的远程路径则原样作为get_state_for_audio_prompt的输入这正是语音克隆能力的来源——通过参考音频提取说话人特征状态。内置音色一览插件预置了 8 个内置音色plugins/pocket/README.md 与源码VOICE_PATHS定义一致音色名说明alba默认音色marius内置音色javert内置音色jean内置音色fantine内置音色cosette内置音色eponine内置音色azelma内置音色各音色对应的参考音频均托管于 Kyutai 的tts-voices模型仓库plugins/pocket/vision_agents/plugins/pocket/tts.py首次使用时由pocket-tts底层自动下载缓存。运行官方示例本地 TTS 语音 Agent示例位于 plugins/pocket/example/pocket_example.py构建了一个完整的多组件语音 AgentPocket TTS文本转语音本地 CPU 运行Deepgram STT语音转文本vision_agents.plugins.deepgram启用eager_turn_detectionGemini LLM对话大脑gemini-3-flash-preview模型GetStream Edge实时音视频通信vision_agents.plugins.getstream。环境变量运行前需配置以下环境变量plugins/pocket/example/README.md环境变量用途DEEPGRAM_API_KEYDeepgram 语音识别STTSTREAM_API_KEY与STREAM_API_SECRETGetStream 实时通信GOOGLE_API_KEYGemini LLM注意Pocket TTS 本身不需要任何 API Key——这正是它的价值所在语音合成环节完全本地化。启动命令cd plugins/pocket/example uv run pocket_example.py run示例入口通过Runner(AgentLauncher(create_agentcreate_agent, join_calljoin_call)).cli()启动 CLIplugins/pocket/example/pocket_example.pyjoin_call中创建呼叫并让 Agent 入会等待 3 秒后调用agent.simple_response(textHello! Im running Pocket TTS locally.)播报一句本地合成语音最后finish()结束会话。示例工程的依赖与本地源码映射见 plugins/pocket/example/pyproject.toml其中通过[tool.uv.sources]将各插件以可编辑模式editable指向仓库内的兄弟目录。在自定义 Agent 中接入示例的 Agent 构造核心代码plugins/pocket/example/pocket_example.py展示了标准接入方式from vision_agents.core import Agent, Runner, User from vision_agents.core.agents import AgentLauncher from vision_agents.plugins import deepgram, gemini, getstream, pocket agent Agent( edgegetstream.Edge(), agent_userUser(namePocket AI, idagent), instructionsYou are a helpful voice assistant. Keep responses brief and conversational., ttspocket.TTS(voicealba), sttdeepgram.STT(eager_turn_detectionTrue), llmgemini.LLM(gemini-3-flash-preview), )只需将tts参数替换为pocket.TTS(...)即可让 Agent 的语音输出完全走本地 CPU 推理无需改动其他任何组件。源码级实现解析懒加载与预热Warmuppocket.TTS同时继承自核心的tts.TTS抽象基类与Warmableagents-core/vision_agents/core/tts/tts.py实现了on_warmup/on_warmed_up预热协议plugins/pocket/vision_agents/plugins/pocket/tts.py模型与音色状态采用懒加载首次合成前才调用TTSModel.load_model()加载模型再通过model.get_state_for_audio_prompt(voice_path)提取音色状态已加载的(model, voice_state)会缓存在实例上后续调用直接复用避免重复加载如果构造时传入了client则跳过模型加载、仅加载音色状态。线程池桥接阻塞推理Pocket TTS 的模型推理是同步阻塞操作而 Agent 运行在 asyncio 事件循环中。插件使用ThreadPoolExecutor(max_workers4)将模型加载与音频生成投递到工作线程执行通过loop.run_in_executor异步等待结果plugins/pocket/vision_agents/plugins/pocket/tts.py既避免了阻塞事件循环又让 CPU 推理与网络 IO 并行。PCM 音频输出stream_audio是核心合成方法plugins/pocket/vision_agents/plugins/pocket/tts.py其处理链路为model.generate_audio(voice_state, text)生成浮点音频张量将张量转为 numpy 数组经np.clip(audio_np, -1.0, 1.0) * 32767.0归一化后量化为 16-bit 整数 PCM调用PcmData.from_numpy(samples, sample_ratesample_rate, channels1, formatAudioFormat.S16)封装为 GetStream 音频帧格式供 edge 实时传输。打断与资源回收stop_audio()为幂等空操作Pocket 合成不可中途打断日志记录 no-opclose()会调用基类清理并关闭线程池plugins/pocket/vision_agents/plugins/pocket/tts.py。测试验证插件附带的集成测试plugins/pocket/tests/test_tts.py验证了两个关键场景默认音色合成对Hello from Pocket TTS.调用tts.send_iter(text)断言输出非空、out[0].data存在且final为 True自定义音色克隆传入hf://kyutai/tts-voices/alba-mackenna/casual.wav作为voice验证自定义路径同样能完成合成。测试标记为integration并通过skip_if_huggingface_model_unavailable在 Hugging Face 模型不可达时优雅跳过首次运行需要联网下载模型与音色文件后续走本地缓存。同时测试中的tts.warmup()印证了 Warmable 预热协议在真实使用中的调用方式。使用建议与限制模型下载首次使用需联网从 Hugging Face 下载 Pocket TTS 模型与所选音色的参考音频无 GPU 也可运行但合成耗时取决于 CPU 性能10x 快于实时与~200ms 延迟为官方 README 声称的典型指标一次性输出从源码与测试可见 Pocket 合成是整段输出的单 chunkfinalTrue非流式增量合成适合短句、问答型对话场景打断语义stop_audio为空操作若你的场景需要抢占式打断barge-in可结合核心 TTS 基类的interrupt()机制与上层会话控制来丢弃过期音频密钥管理示例通过python-dotenv的load_dotenv()加载环境变量plugins/pocket/example/pocket_example.py建议将密钥置于本地.env文件并加入版本控制忽略列表。总体而言Pocket 插件是 Vision Agents 生态中零密钥、纯本地语音合成的低成本选项将 TTS 从云端 API 下沉到 CPU 推理与 Deepgram、Gemini、GetStream 等云端组件组合即可在保持实时对话体验的同时大幅降低 TTS 环节的延迟与成本。【免费下载链接】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），仅供参考