Pipecat voice assistant

何时使用

• 需要搭建实时、对话式的本地语音 Agent（麦克风进、扬声器出）。
• 使用 Pipecat 框架做「流水线式」AI 编排，需要对每一级（STT/LLM/TTS）单独可控。
• 需要把多家服务商拼到同一条语音回路里（如 STT/TTS 用 OpenAI、LLM 用 Google Gemini）。
• 想做战术风/角色化（如 Iron Man 式）的语音助手。

不该用的边界：

• 追求极致整体延迟、不需要分级控制时，优先考虑端到端 speech-to-speech 一体模型，而非本流水线。
• 需要电话、WebRTC、浏览器远程等非本地音频接入时，本骨架默认走本地硬件 Transport，需另换 transport。
• 非 Pipecat 框架、或只想做纯文本对话时不适用。
• 任务范围与上文不符、缺少 API Key / 硬件权限 / 成功标准时，停下来先确认。

步骤

1. 安装依赖

pip install pipecat-ai[openai,google,silero] python-dotenv

silero 提供本地 VAD（语音活动检测），openai/google 为对应服务商扩展。

2. 配置环境变量

新建 .env：

OPENAI_API_KEY=your_openai_key
GOOGLE_API_KEY=your_google_key

3. 运行 Agent

python scripts/friday_agent.py

指令

组装一条线性流水线：Mic -> VAD -> STT -> LLM -> TTS -> Speaker。各级推荐配置：

• STT：OpenAI Whisper（whisper-1）或 gpt-4o-transcribe。
• LLM：Google Gemini 2.5 Flash（经兼容垫片接入）。
• TTS：OpenAI TTS（nova 音色），输出 24kHz。
• VAD：Silero（本地硬件鲁棒，抑制背景噪声误触发 LLM）。
• Transport：本地音频（硬件麦克风/扬声器）。

Gemini 兼容垫片（关键约束）： Gemini 的消息格式与 Pipecat 聚合器默认期望的 OpenAI 标准不同，脚本须提供 GoogleSafeContext 与 GoogleSafeMessage 两个类，把 OpenAI 风格的 dict 翻译成 Gemini 的 schema，否则会报「Validation error」。

示例

战术风系统提示与开场白（数据密集、零寒暄，便于压低延迟）：

• 开场：Systems nominal. Ready for commands.
• 反例（避免）：Hello, how can I help you today?

要点：响应要短、信息密度高，省去礼貌性填充语，直接压缩端到端延迟。

注意事项

• 采样率必须对齐：OpenAI TTS 输出 24kHz，务必让 audio_out_sample_rate 与之匹配，否则音频会变尖（过快）或拖慢。
• 优先用 Silero VAD：避免背景噪声触发 LLM，节省 token 与延迟。
• 音频卡顿/延迟：检查 OUTPUT_DEVICE 索引；用类似 test_audio_output.py 的脚本枚举出本机正确的硬件设备索引。
• 消息格式校验报错：确认 GoogleSafeContext 垫片正确地把 OpenAI 风格 dict 转成 Gemini schema。
• 产出不能替代针对具体环境的验证、测试与专家评审。

互见

• voice-agents — 语音 AI 的通用原则。
• agent-tool-builder — 给语音助手挂工具（搜索、控灯等）。
• llm-architect — LLM 层优化。

---

采编自 sickn33/antigravity-awesome-skills（MIT）。