Pipecat 语音 Agent 部署实战从一条本地命令到生产镜像的完整路径【免费下载链接】pipecatOpen Source framework for voice agents, multimodal apps, and realtime AI. Maintained by Daily and the community.项目地址: https://gitcode.com/GitHub_Trending/pi/pipecat第一次把 PipecatPython 语音与多模态 AI Agent 开源框架的 bot 交给真人用问题往往不在框架本身而是两处.env里漏了某个服务的 API key或者没装对应的 extra 依赖extra 是 PyPI 里按需加装的可选功能包比如用 Deepgram 就得装deepgram包。这篇按你马上要遇到的事来讲一条命令在本地跑通语音对话、用官方 Dockerfile 把 bot 打成可交付镜像、上线前开三个安全开关以及线上出故障时按哪条路径查。所有命令都对应仓库里的真实文件和参数。从最小可跑示例起步先用一条命令听见声音先讲一个概念Pipecat 里的transport是音频的进与出——用户声音怎么进来、回复声音怎么播出去。本地调试想快速验证选最简单的入口就好。examples/getting-started/01-say-one-thing.py 只做一件事TTS 说一句Hello there!。它只需要一个 keyCartesia 的是验证密钥 网络 框架都没问题的最小链路。git clone https://gitcode.com/GitHub_Trending/pi/pipecat cd pipecat cp env.example .env # 填入 CARTESIA_API_KEY 即可 uv run examples/getting-started/01-say-one-thing.py --transport webrtc启动后终端会打印一个浏览器 URL点开就能听到 TTS 开口。这条链路通了后面所有问题排查都有了基线。完整双工对话看 examples/getting-started/06-voice-agent.py需要三个 keyDEEPGRAM_API_KEY语音转文字、OPENAI_API_KEYLLM 生成回复、CARTESIA_API_KEY文字转语音。不想开浏览器也行06a-voice-agent-local.py直接用电脑麦克风和本地扬声器但要装localextra依赖 PyAudiouv add pipecat-ai[local] uv run examples/getting-started/06a-voice-agent-local.py这里有个经验01 跑通之前别急着调 06。一旦 06 出声音问题你能立刻分清是 STT 环节还是 transport 环节的事。transport 怎么选场景transport说明本地无浏览器调试local电脑麦扬声器需装localextra本地开浏览器调试webrtc终端打印 URL 直接访问正式交付给网页端daily或livekitWebRTC 云厂商装对应 extra电话/PSTNtwilio走 WebSocket 接 SIP 网关把 bot 打成 Docker 镜像官方模板的三处关键配置 镜像模板在 src/pipecat/cli/templates/server/Dockerfile.jinja2就十几行三处设计值得看懂再抄FROM dailyco/pipecat-base:latest # 官方基础镜像预装 Python uv ENV UV_COMPILE_BYTECODE1 # 预编译字节码缩短冷启动 ENV UV_LINK_MODEcopy RUN --mounttypecache,target/root/.cache/uv \ --mounttypebind,sourceuv.lock,targetuv.lock \ --mounttypebind,sourcepyproject.toml,targetpyproject.toml \ uv sync --locked --no-install-project --no-dev COPY ./bot.py bot.py三个点。第一--locked意味着镜像里装的是uv.lock锁定的依赖版本和开发机完全一致我本地能跑这句在镜像上才成立。第二--mounttypecache让 uv 的下载目录跨构建缓存改代码重建镜像不用重新拉包。第三基础镜像已经把 Python 3.11框架最低要求和 uv 装好了你自己的层只有代码。构建和启动docker build -t pipecat-bot -f Dockerfile . docker run -d --name pipecat-bot --env-file .env \ -p 8000:8000 pipecat-bot uv run bot.py --transport webrtc注意密钥走--env-file注入不要COPY .env进镜像——镜像一推仓库就等于泄密。生产建议用 Compose 管理 bot 和它的配套服务比如 examples/multi-worker/ 里的 worker并给 bot 暴露的 HTTP 端口配一个健康检查。上线前该动的三个安全开关 这三个开关的模板就在 env.example 底部的注释里取消注释填上值即可。WebSocket 会话认证。设PIPECAT_WEBSOCKET_AUTHtoken后客户端必须先 POST/start换一个短期 HMAC 签名 token 才能连/ws。不开这个任何拿到地址的人都能起会话你的 LLM 账单就是别人的游乐场。Origin 白名单。PIPECAT_ALLOWED_ORIGINS填逗号分隔的域名后不在列表里的页面连不上。你的 bot 页面部署在voice.example.com就只放这一个域名。密钥分层。.env进.gitignore生产密钥放 CI/CD 的 secret 存储开发和生产用两套独立 key。出事时这一步能帮你 30 秒定位是哪个环境的密钥暴露了。另外提一句PIPECAT_ICE_SERVERS控制 WebRTC 的 STUN/TURN 服务器NAT 穿透用公网部署建议配一个 TURN否则部分网络环境比如公司防火墙后用户连不上。线上第一次出故障按这条路径查先给一张管线图你脑子里有这张图查故障就是顺着箭头找断点排查从日志开始。框架用 loguru 把帧级日志打到 stderr每个 processor 收发帧都有记录把级别调到 debug 能逐帧看到卡在哪一级from loguru import logger logger.add(sys.stderr, levelDEBUG) # 06a 示例里就是这么开的指标层面06-voice-agent.py里PipelineParams(enable_metricsTrue, enable_usage_metricsTrue)已经打开了能拿到 LLM 首 token 延迟、TTS 首帧延迟这类数字。出故障时按现象对号入座现象先看哪里常见原因浏览器连不上transport 日志端口没通或 Origin 白名单把页面域名拦了听不清对方说话STT 日志采样率或网络抖动查识别置信度回复慢LLM 首 token 指标确认流式输出开着或换低延迟模型打断不灵敏VAD 参数调 Silero VAD 的灵敏度见 src/pipecat/audio/vad/偶发崩溃Sentry 接入参考 examples/observability/ 的 metrics 示例想加视觉换服务商都是三行以内的事Pipecat 的服务全是可插拔对象。给 bot 加视觉看 examples/vision/vision-moondream.py下面这张猫图就是它的演示素材——用户问图里是什么agent 会直接回答换服务商同理比如把 TTS 从 Cartesia 换成 OpenAI只需改 import 和实例化两行管道其余部分不动。全部服务实现在 src/pipecat/services/装对应 extra 就能跑。单进程扛不住并发时把 LLM/TTS 拆到独立 worker 进程主进程只收音频和发音频examples/multi-worker/ 里本地和分布式Redis/PGMQ 交接都有现成例子。上线前 30 秒过一遍的清单#检查项怎么验证1Python 版本 ≥ 3.11python --version2密钥齐全且在.gitignoregit status看不到.env3用到的 extra 都装了uv add pipecat-ai[deepgram,cartesia,openai,runner]4最小链路本地可跑01 示例能出声5镜像--locked构建构建日志无依赖解析告警6WebSocket token 认证开启PIPECAT_WEBSOCKET_AUTHtoken7Origin 白名单只放自家域名陌生域名连不上8生产日志级别 INFOdebug 只留给故障现场9metrics 开关打开能看到首 token / 首帧延迟 资源入口核心管道与 transportsrc/pipecat/分级示例从单句 TTS 到完整 Agentexamples/getting-started/服务实现STT/TTS/LLM/Transportsrc/pipecat/services/变更历史CHANGELOG.md下一篇想讲 Pipecat Flows 怎么处理用户说一半就挂这类多轮状态感兴趣的话我们在那篇见。【免费下载链接】pipecatOpen Source framework for voice agents, multimodal apps, and realtime AI. Maintained by Daily and the community.项目地址: https://gitcode.com/GitHub_Trending/pi/pipecat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Pipecat 语音 Agent 部署实战：从一条本地命令到生产镜像的完整路径
Pipecat 语音 Agent 部署实战从一条本地命令到生产镜像的完整路径【免费下载链接】pipecatOpen Source framework for voice agents, multimodal apps, and realtime AI. Maintained by Daily and the community.项目地址: https://gitcode.com/GitHub_Trending/pi/pipecat第一次把 PipecatPython 语音与多模态 AI Agent 开源框架的 bot 交给真人用问题往往不在框架本身而是两处.env里漏了某个服务的 API key或者没装对应的 extra 依赖extra 是 PyPI 里按需加装的可选功能包比如用 Deepgram 就得装deepgram包。这篇按你马上要遇到的事来讲一条命令在本地跑通语音对话、用官方 Dockerfile 把 bot 打成可交付镜像、上线前开三个安全开关以及线上出故障时按哪条路径查。所有命令都对应仓库里的真实文件和参数。从最小可跑示例起步先用一条命令听见声音先讲一个概念Pipecat 里的transport是音频的进与出——用户声音怎么进来、回复声音怎么播出去。本地调试想快速验证选最简单的入口就好。examples/getting-started/01-say-one-thing.py 只做一件事TTS 说一句Hello there!。它只需要一个 keyCartesia 的是验证密钥 网络 框架都没问题的最小链路。git clone https://gitcode.com/GitHub_Trending/pi/pipecat cd pipecat cp env.example .env # 填入 CARTESIA_API_KEY 即可 uv run examples/getting-started/01-say-one-thing.py --transport webrtc启动后终端会打印一个浏览器 URL点开就能听到 TTS 开口。这条链路通了后面所有问题排查都有了基线。完整双工对话看 examples/getting-started/06-voice-agent.py需要三个 keyDEEPGRAM_API_KEY语音转文字、OPENAI_API_KEYLLM 生成回复、CARTESIA_API_KEY文字转语音。不想开浏览器也行06a-voice-agent-local.py直接用电脑麦克风和本地扬声器但要装localextra依赖 PyAudiouv add pipecat-ai[local] uv run examples/getting-started/06a-voice-agent-local.py这里有个经验01 跑通之前别急着调 06。一旦 06 出声音问题你能立刻分清是 STT 环节还是 transport 环节的事。transport 怎么选场景transport说明本地无浏览器调试local电脑麦扬声器需装localextra本地开浏览器调试webrtc终端打印 URL 直接访问正式交付给网页端daily或livekitWebRTC 云厂商装对应 extra电话/PSTNtwilio走 WebSocket 接 SIP 网关把 bot 打成 Docker 镜像官方模板的三处关键配置 镜像模板在 src/pipecat/cli/templates/server/Dockerfile.jinja2就十几行三处设计值得看懂再抄FROM dailyco/pipecat-base:latest # 官方基础镜像预装 Python uv ENV UV_COMPILE_BYTECODE1 # 预编译字节码缩短冷启动 ENV UV_LINK_MODEcopy RUN --mounttypecache,target/root/.cache/uv \ --mounttypebind,sourceuv.lock,targetuv.lock \ --mounttypebind,sourcepyproject.toml,targetpyproject.toml \ uv sync --locked --no-install-project --no-dev COPY ./bot.py bot.py三个点。第一--locked意味着镜像里装的是uv.lock锁定的依赖版本和开发机完全一致我本地能跑这句在镜像上才成立。第二--mounttypecache让 uv 的下载目录跨构建缓存改代码重建镜像不用重新拉包。第三基础镜像已经把 Python 3.11框架最低要求和 uv 装好了你自己的层只有代码。构建和启动docker build -t pipecat-bot -f Dockerfile . docker run -d --name pipecat-bot --env-file .env \ -p 8000:8000 pipecat-bot uv run bot.py --transport webrtc注意密钥走--env-file注入不要COPY .env进镜像——镜像一推仓库就等于泄密。生产建议用 Compose 管理 bot 和它的配套服务比如 examples/multi-worker/ 里的 worker并给 bot 暴露的 HTTP 端口配一个健康检查。上线前该动的三个安全开关 这三个开关的模板就在 env.example 底部的注释里取消注释填上值即可。WebSocket 会话认证。设PIPECAT_WEBSOCKET_AUTHtoken后客户端必须先 POST/start换一个短期 HMAC 签名 token 才能连/ws。不开这个任何拿到地址的人都能起会话你的 LLM 账单就是别人的游乐场。Origin 白名单。PIPECAT_ALLOWED_ORIGINS填逗号分隔的域名后不在列表里的页面连不上。你的 bot 页面部署在voice.example.com就只放这一个域名。密钥分层。.env进.gitignore生产密钥放 CI/CD 的 secret 存储开发和生产用两套独立 key。出事时这一步能帮你 30 秒定位是哪个环境的密钥暴露了。另外提一句PIPECAT_ICE_SERVERS控制 WebRTC 的 STUN/TURN 服务器NAT 穿透用公网部署建议配一个 TURN否则部分网络环境比如公司防火墙后用户连不上。线上第一次出故障按这条路径查先给一张管线图你脑子里有这张图查故障就是顺着箭头找断点排查从日志开始。框架用 loguru 把帧级日志打到 stderr每个 processor 收发帧都有记录把级别调到 debug 能逐帧看到卡在哪一级from loguru import logger logger.add(sys.stderr, levelDEBUG) # 06a 示例里就是这么开的指标层面06-voice-agent.py里PipelineParams(enable_metricsTrue, enable_usage_metricsTrue)已经打开了能拿到 LLM 首 token 延迟、TTS 首帧延迟这类数字。出故障时按现象对号入座现象先看哪里常见原因浏览器连不上transport 日志端口没通或 Origin 白名单把页面域名拦了听不清对方说话STT 日志采样率或网络抖动查识别置信度回复慢LLM 首 token 指标确认流式输出开着或换低延迟模型打断不灵敏VAD 参数调 Silero VAD 的灵敏度见 src/pipecat/audio/vad/偶发崩溃Sentry 接入参考 examples/observability/ 的 metrics 示例想加视觉换服务商都是三行以内的事Pipecat 的服务全是可插拔对象。给 bot 加视觉看 examples/vision/vision-moondream.py下面这张猫图就是它的演示素材——用户问图里是什么agent 会直接回答换服务商同理比如把 TTS 从 Cartesia 换成 OpenAI只需改 import 和实例化两行管道其余部分不动。全部服务实现在 src/pipecat/services/装对应 extra 就能跑。单进程扛不住并发时把 LLM/TTS 拆到独立 worker 进程主进程只收音频和发音频examples/multi-worker/ 里本地和分布式Redis/PGMQ 交接都有现成例子。上线前 30 秒过一遍的清单#检查项怎么验证1Python 版本 ≥ 3.11python --version2密钥齐全且在.gitignoregit status看不到.env3用到的 extra 都装了uv add pipecat-ai[deepgram,cartesia,openai,runner]4最小链路本地可跑01 示例能出声5镜像--locked构建构建日志无依赖解析告警6WebSocket token 认证开启PIPECAT_WEBSOCKET_AUTHtoken7Origin 白名单只放自家域名陌生域名连不上8生产日志级别 INFOdebug 只留给故障现场9metrics 开关打开能看到首 token / 首帧延迟 资源入口核心管道与 transportsrc/pipecat/分级示例从单句 TTS 到完整 Agentexamples/getting-started/服务实现STT/TTS/LLM/Transportsrc/pipecat/services/变更历史CHANGELOG.md下一篇想讲 Pipecat Flows 怎么处理用户说一半就挂这类多轮状态感兴趣的话我们在那篇见。【免费下载链接】pipecatOpen Source framework for voice agents, multimodal apps, and realtime AI. Maintained by Daily and the community.项目地址: https://gitcode.com/GitHub_Trending/pi/pipecat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
