企业官网建设流程全解析

VoiceStudio 如何接入 pipecat 构建本地语音 Agent？

【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio

本文解决的问题是：你已经有一个自己的 agent 运行时（客服对话、桌面助手、Discord 人格等），想让它说话和听音都走本地的 VoiceStudio，用你自己的克隆音色，且语音数据不出本机。VoiceStudio 在此角色下是一个 OpenAI 兼容的本地语音提供方（agentic v1）：它只做 TTS/STT provider，不管编排——VAD、turn-taking 和 LLM 由你的 pipecat pipeline 负责。前提是本机有一个正在运行的 VoiceStudio，服务根地址默认为http://localhost:3900。

接入依据的文档是 docs/agentic-voice.md，配套的最小可运行示例在 examples/agentic/pipecat_minimal.py。

准备条件

1. VoiceStudio 后端已在本地运行，默认监听http://localhost:3900。OpenAI 兼容客户端的 base URL 要写成http://localhost:3900/v1，而机器可读的 discovery 端点留在服务根http://localhost:3900/.well-known/voicestudio-speech。
2. pipecat 作为 Python 库运行在你自己的进程内，不需要额外起服务。安装命令来自示例文件头部：

uv pip install "pipecat-ai[openai,silero]"

接入前先核对端点

VoiceStudio 对 OpenAI 兼容路线的支持面如下（来自 docs/agentic-voice.md）：

先用 discovery 端点确认服务在跑，再取一次声音列表用于后面的voice参数：

curl http://localhost:3900/.well-known/voicestudio-speech curl http://localhost:3900/v1/audio/voices

discovery 文档返回voicestudio.speech.v1。这个契约请求形状由 tests/test_agentic_provider_contract.py 在 CI 中固定，保证POST /v1/audio/speech接受{model, input, voice, response_format, speed}并返回裸音频。

配置 pipecat 的 TTS/STT 服务

把 pipecat 的 OpenAI TTS/STT 服务指向 VoiceStudio（摘自 docs/agentic-voice.md）：

from pipecat.services.openai.tts import OpenAITTSService from pipecat.services.openai.stt import OpenAISTTService tts = OpenAITTSService( base_url="http://localhost:3900/v1", api_key="not-needed-locally", # any string; VoiceStudio ignores it unless OMNIVOICE_API_KEY is set voice="<your-voice-profile-id>", # from GET /v1/audio/voices, or "default" model="omnivoice", # or any installed engine id sample_rate=24000, # matches VoiceStudio's default output ) stt = OpenAISTTService( base_url="http://localhost:3900/v1", api_key="not-needed-locally", )

参数说明（均依据文档）：

• base_url必须是服务根加上/v1。
• api_key本地时是任意字符串，VoiceStudio 会忽略它——除非远端后端设置了OMNIVOICE_API_KEY，那时要传同一个值。
• voice替换为GET /v1/audio/voices返回的 profile id，或直接用"default"。
• model填引擎 id，示例用omnivoice，也可以换成你已安装的其他引擎 id。
• sample_rate=24000匹配 VoiceStudio 默认输出采样率。

把这两个服务塞进任意 pipecat pipeline 即可，VAD、turn-taking 和 LLM 都留在本地。

运行仓库自带的最小示例

examples/agentic/pipecat_minimal.py 是一个刻意保持很小的骨架：它只把 VoiceStudio 的 TTS/STT 服务接进 pipecat，transport 和 LLM 留给你自己选。先启动 VoiceStudio（默认http://localhost:3900），然后：

python examples/agentic/pipecat_minimal.py

示例读三个环境变量，均有本地默认值，按需替换：

按脚本自身说明，成功时终端会打印类似下面的内容（示例输出）：

VoiceStudio STT + TTS services constructed against http://localhost:3900/v1 Wire `stt` and `tts` into your pipecat Pipeline with a transport and an LLM service. See docs/agentic-voice.md.

看到第一行说明两个服务对象已按正确 base URL 构造成功；transport + LLM 的接入由你在自己的 pipeline 中完成，这也是 "agentic v1" 的分工边界——示例本身不跑电话、不起服务器。

用自己的克隆音色

想让 agent 用你的声音说话，把voice设为克隆 profile 的 id。文档建议优先使用你已标记verified own voice的 profile（Settings → 某个 voice profile → Voice ownership）。这个 consent 锁是后续更重的 agentic 功能上线时的门槛，也是"AI 用我的声音说话"的默认立场。

可选分支：远端 GPU 后端

如果 VoiceStudio 跑在另一台 GPU 机器上（见 docs/remote-gpu.md），把该后端服务根 URL 加上/v1作为 OpenAI 客户端的base_url，并把它配置的OMNIVOICE_API_KEY作为api_key传入——与 app 其余部分使用同一个 bearer。discovery 的/.well-known/voicestudio-speech保持使用未修改的服务根。文档明确要求远端后端留在你的 tailnet 内，不要暴露到公网。

LiveKit Agents 也走同样的base_url（docs/agentic-voice.md），但它额外需要 LiveKit 媒体服务器；只有需要 WebRTC/SIP 规模时才选它，单个本地 agent 用 pipecat 更轻。

限制

• 这是 "agentic v1"：VoiceStudio 只是 provider，不是编排者，agent 运行时由你自己带。
• 外呼电话（PSTN）是文档中明确推迟的里程碑，需要付费运营商，没有全本地路径，且只在显式 consent 护栏下提供——本文路径不包含。
• 若 pipecat 侧升级后行为异常，先对照POST /v1/audio/speech的请求形状是否仍为{model, input, voice, response_format, speed}，该形状由契约测试固定。

【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio