pipecat-homeassistant

align="center"> <img src="https://raw.githubusercontent.com/kyvaith/pipecat-homeassistant/main/addons/pipecat_assist/logo.png" alt="Pipecat Assist" width="420"> </p> # Pipecat Home Assistant <p align="center"> <a href="https://github.com/kyvaith/pipecat-homeassistant/actions/workflows/ci.yml"> <img alt="CI" src="https://github.com/kyvaith/pipecat-homeassistant/actions/workflows/ci.yml/badge.svg?branch=main"> </a> <a href="https://github.com/kyvaith/pipecat-homeassistant/actions/workflows/publish.yml"> <img alt="Publish add-on image" src="https://github.com/kyvaith/pipecat-homeassistant/actions/workflows/publish.yml/badge.svg"> </a> <a href="https://github.com/kyvaith/pipecat-homeassistant/releases"> <img alt="Latest release" src="https://img.shields.io/github/v/release/kyvaith/pipecat-homeassistant?label=release"> </a> <a href="LICENSE"> <img alt="License" src="https://img.shields.io/github/licensevaith/pipecat-homeassistant"> </a> a href="https://www.home-assistant.io/ <img alt="Home Assistant" src="https://img/badge/Home%20Assistant-add--on%20%%20integration-41BDF5?logo=homeColor=white"> </a> <a href="https://github.com/pipecat-ai/pipecat"> img alt="Pipecat" src="https://img/badge/Pipecat-realtime%20voice- </a> </p> Pipecat Assist、多模态的 Pipec助手带到 Home Assistant您与实时语音模型进行对话，构建自定义pecat 管道，并通过 MCP 控制 Home Assistant 设备。 pecat Assist 提供 - **实时语音助手**，通过 WebRTC，提供 Gemini Live 作为默认的实时语音转文本管道。 - **自定义管道构建器**，用于语音转实时流程：混合 STT、LLM、TTS、内存、网络搜索、Home Assistant 工具和 Pipecat一个运行时配置文件中。 - **云服务集成**，支持 Gemini、OpenAI、Soniox、Deepgram、、Cartesia、Gradium、ElevenLabs、GoogleTS、AWS Bedrock、AWS Nova Sonic 和 OpenAI 兼容的端点。 - **本地 AI 选项**，通过 Ollama、本地运行时端点和自定义 OpenAI 兼容服务。 - **多个 MCP 服务器**，包括内置的 Home Assistant MCP 服务器、Home Assistant MCP 插件和额外的自定义 MCP 端点。 - **可视化 Pipecat Flow，用于实时管道，包括条件对话图和 MCP 支持的工具调用。 - **音频调试、会话内存和网络搜索**，作为一流的运行时功能，而不是隐藏的提供者切换。 - **Home Assistant AI 任务支持**，用于生成数据和图像生成任务，使用专用的图像提供者，如 Google Imagen 或 fal。 ## 您可以在哪里使用它 - **Pipecat Assist 插件 UI**：一个全宽助手卡，用于快速浏览器测试和管道开发。 - **Lovelace 仪表盘卡**：一个专用的 WebRTC 卡，带有实时转录、平滑滚动和最响应的全双工对话路径。 - **Home Assistant Assist**：自定义组件将 Pipecat Assist 暴露为对话、语音转文本和文本转语音。 - **Home Assistant AI 任务 / AI 操作**：Pipecat Assist 可以被选为生成数据和图像生成任务的 LLM 任务处理，在您的 Home Assistant 版本中暴露 AI 任务实体。 - **Pipecat ESP32 卫星**暴露了一个 SmallWebRTC 端点，用于卫星客户端。 Home Assistant Assist 路径使用高级 Pipecat Live Bridge，以便 HA Assist 可以与 Gemini Live 和 OpenAI Realtime 等实时语音助手对话。由于 HA Assist 本身仍然不是全双工 WebRTC 客户端，因此该桥接器无法在助手说话时提供真正的打断。L 卡和插件助手卡仍然是更响应的实时体验。 ## 安装 1. 将此存储库 URL 添加 Assistant **设置 > 插件 > 插件商店 >**： ```text https://github.comvaith/pipecat-homeassistant ``` 2. 将相同的存储库 URL 添加HACS > 自定义** 作为 **集成**. 从 Home Assistant 插件商店安装 **Pipecat Assist** 插件/应用程序。 4. 从 HACS 安装 **Pipecat Assist** 自定义组件，然后在 HACS时重启 Home Assistant。 5. 在 **设置 > 设备和服务** 中添加 Pipecat Assist 集成。集成应自动检测插件 URL；除非您在自定义网络布局中运行插件，否则请保留检测到的值。 6. 在 **设置 > 语音助手** 中，在所有三个类别中选择 **Pipecat Assist**： - 对话代理 / LLM - 语音转文本 - 文本转语音 使用单个 Pipecat Assist 语言条目。实际的语音、语言和提供者设置在插件管道中配置。 7. 可选：如果您的 Home Assistant 版本公开 **AI 任务** 或 **AI 操作**，请选择 **Pipecat Assist** 进行 LLM 任务处理、生成的数据和图像生成。在插件中配置 **集成 > Google Imagen** 或 **集成 > fal 图像生成**，然后在您想要特定后端时，在 **运行时 > 图像任务提供者** 中提供者。 8. 打开 Pipecat Assist 插件 UI 并配置提供者： - 最简单的开始：创建 Google AI Studio API 密钥并将其粘贴到 **集成 > Google Gemini Live**。 - 高级设置：使用您首选的云提供者、本地 AI 端点和 MCP 服务器创建或编辑自定义9. 将pecat Assist**ace 卡添加到仪表开始对话。 ## 截图Pipecat Assistace 卡在 Home Assistant 仪表盘上](creenshots/lovelace-card-dashboard.png)   ## 存储库布局 - `addons/pipecat_assist` - Home Assistant 应用程序/插件。它运行 Pipecat，公开一个通过 Ingress 的配置 UI，提供 `/api/offer` 用于 Pipecat ESP32 SmallWebRTC 客户端，并连接到 Home Assistant MCP。 - `pecat_assist/ui-src` - 随插件作为静态资产提供的管道编辑器的 React 源代码。 - `custom_components/pipecist` - Home集成，公开 Pipecat Assist 作为对话、STTTS、AI 任务实体和 Lovelace WebRTC 卡资产。 - `.github/workflows` - 用于多架构 Home Assistant 镜像的 CI 和 GHCR 发布工作流。 ## 架构 ```mermaid flowchart LR ESP32["Pipecat ESP32 卫星"] -->|"SmallWebRTC /api/offer"| Addon["Pipecat Assist 插件"] Browser["HA Ingress UI"] --> Addon HAConv["HA Assist 桥接"] -->|"对话 / STT / TTS HTTP 桥接"| Addon Lovelace["Lovelace 卡"] -->|"WebRTC /api/offer"| Addon Addon -->|"Pipecat S2S"| Realtime["Gemini Live / OpenAI Realtime / AWS Nova Sonic"] Addon -->|"Pipecat 复合实时"| Cascade["STT + LLM + TTS"] Cascade --> Flow["Pi Flows"] Addon -->|"可流式 HTTP /api/mcp"| HAMCP["Home Assistant MCP 服务器"] HAMCP --> Assist["HA Assist API 和暴露的实体"] ``` ## 安装后快速启动 1. 启动插件并打开 Web UI。 2. 打开 **集成 > Home Assistant MCP** 并点击 **测试 MCP**。在正常的 Home Assistant 插件安装中，Pipecat Assist 自动使用 Supervisor 代币。 3. 配置模型提供者。Gemini Live 是默认的，OpenAI、Soniox、Deepgram、Cartesia、Gradium、Speechmatics、AWS、ElevenLabs、Google Cloud HTTP 流媒体、Open兼容端点、ama、本地运行时搜索等其他提供从 **集成**。 4. 选择或创建管道。内置目录包括实时语音转语音配置文件和复合实时配置文件，例如 `Soniox + OpenAI + Cartesia`、`Deepgram + Google TTS`Speechmatics + AWS Nova Pro + ElevenLabs`。 5. 使用生成的 `PIPECAT_SMALLWEBRTC_URL构建 Pipecat ESP32 固件。 Home Assistant MCP 访问默认使用插件的 Supervisor 代币。使用 **集成 > Home Assistant MCP > 自动默认值** 清除自定义 MCP 重写并返回到 Supervisor 支持的默认值。手动粘贴的长期访问代币仅在 Supervisor 路径之外的自定义安装中需要。 **HA MCP 服务器插件** 集成通过 Home Assistant Supervisor API 自动检测。Pipecat Assist 读取插件密 MCP URL，不需要此集成的 Bearer 代币 代币仅适用于明确需要它的自定义 MCP 服务器。 Gemini Live 是默认的首次运行管道。在 ** Google Gemini Live** 中添加 Google AI Studio `models/gemini-3.1-flash-live-preview` 作为实时模型，并使用 **助手 >测试** 验证浏览器语音Home Assistant Assist 桥接器与经典 路径具有最佳兼容配置 STT/TTS管道，安装 `custom_components/pipecat_assist`，添加 **at Assist** 集成，并为对话、语音和文本转语音选择 **Pipecat Assist## 管道和 Pipecat Flows Pi Assist 支持两类实时运行时： - **语音转语音实时**：Gemini Live、OpenAI Realtime 和 AWS Nova Sonic 直接接收音频并直接返回音频。这些是最低摩擦的配置文件，Gemini Live 仍然是首次运行的默认配置文件。 - **复合实时**：流式 STT、流式 LLM 和流式 TTS 由 Pipecat 链接。这些管道在 WebRTC 上仍然是实时的，但每个阶段都可以使用不同的提供者。兼容的 TTS 提供者可以合成句子或令牌块中的流式 LLM 输出。 提供者集成为有意按功能拆分。OpenAI 和 Gemini Live 是语音转语音提供者；OpenAI Cloud 和 Google Gemini Cloud 是复合/文本提供者。会话内存和网络搜索是单独的管道步骤。网络搜索选择 OpenAI Cloud 或 Google Gemini Cloud 等云 LLM 提供者，而 Home Assistant 设备控制仍在 MCP 上。 官方 `pipecat-ai-flows` 支持用于复合实时管道。流程编辑器存储节点、转换函数、JSON 模式和可选的 Home Assistant MCP 工具调用。对于语音转语音UI 禁用 Pi Flow 磁贴，因为 Pipecat Flows 目前不支持 Gemini Live 或 OpenAI Realtime S2S API。 ## Home Assistant Assist 和 Lovelace 自定义组件在 Home Assistant Assist 的三个插槽中公开 Pipecat Assist：对话、语音转文本和文本转语音。选择单个 `pipecat-assist` 语言条目；实际的口语语言和语音仍在插件管道和提供者集成中配置。HA Assist 桥接器不是像 Pipecat WebRTC 路径双工，但它允许标准 HA Assist 入口点调用活动 Pi 管道，其中提供请求的桥接操作。 Lovelace 卡由 `/pipecat_assist/pipecat-assist-card.js` 处提供，由自定义组件加载，并使用与插件演示相同的 WebRTC 助手路径。它默认调用自定义组件代理，因此仪表盘 YAML 不需要 Ingress 代币或流程 ID。 有用的卡选项： ```yaml type: custom:pipecat-assist-card name: Pipecat Assist animation_on_idle: true compact_mode: false accent_color: "#206cff" audio_buffer_ms: 120 ``` `compact_mode` 隐藏转录。`audio_buffer_ms` 提示浏览器 WebRTC 抖动缓冲区；较高的值可以平滑播放，但延迟略有增加。 ## 音频调试 打开 **运行时**，启用 **录制输入/输出音频**，保存，然后运行浏览器语音测试或连接卫星。插件在 `/data` 下写入麦克风输入和助手输出的单独 WAV 文件，并在运行时面板中提供下载链接。调试后使用 **清除**，因为这些文件可能包含私密的家庭音频。 ## Pipecat ESP32 Pipecat ESP32 需要一个 SmallWebRTC 提供端点： ```bash export PIPECAT_SMALLWEBRTC_URL="http://<home-assistant-lan-ip>:7860/api/offer?token=<卫星密钥>" ``` 该存储库暂时将 ESP32件单独存放。 Pipecat ESP32 集成到 ESPHome 中，以便设备端和 Home Assistant 插件成为一个生态系统。在此过程中，直接 ESP32 身份验证路径将转向标准 Home Assistant 代币流。 ## 视觉服务 Moondream 是一个 Pipecat 视觉服务，用于图像理解和视觉问题回答，而不是文本到图像生成器。因此，它在此版本中不作为 Home Assistant 后端公开，但分析图像附件的 AI 任务的有力候选者。 ## 开发 插件源代码位于 `addons/pipecat_assist`。 ```bash python -m compileall addons/pipecat_assist/app custom_components/pipecat_assist ``` 对于 React UI： ```bash cd addons/pipecat_assist/ui-src pnpm install pnpm build ``` 对于容器构建： ```bash docker build -t pipecat-assist:dev addons/pipecat_assist ``` ## 参考 - Pipecat：https://github.com/pipecat-ai/pipecat - Pipecat Flows：https://github.com/pipecat-ai/pipecat-flows - Pipecat Flows 编辑器：https://github.com/pipecat-ai/pipecat-flows-editor - Pipecat ESP32：https://github.com/pipecat-ai/pipecat-esp32 - Pipecat Google 图像生成：https://docs.pipecat.ai/api-reference/server/services/image-generation/google - Pipecat fal 图像生成：https://docs.pipecat.ai/api-reference/server/services/image-generation/fal - Pipecat Moondream 视觉服务：https://docs.pipecat.ai/api-reference/server/services/vision/moondream - Home Assistant MCP 服务器：https://www.home-assistant.io/integrations/mcp_server/ - Home Assistant 应用程序文档：https://developers.home-assistant.io/docs/apps/configuration/