Ha Gemini Live

家庭助理实时AI音频——Gemini Live

重要： 此组件使用定制的UI来启用实时语音功能。在安装或配置集成之前，请仔细阅读此README。

与集成的家庭助理自定义组件 谷歌Gemini Live API 用于实时语音和文本对话，具有可选的MCP（模型上下文协议）服务器支持。

🎯 包含集成

以最小的延迟提供本机语音转语音功能。

特性

• 实时对话： 基于WebSocket的低延迟响应
• 母语语音转换： 直接音频处理，无需单独的STT/TTS管道
• 语音支持： 多种语音选项，可配置设置
• 家庭助理集成： 用于控制智能家居设备的内置工具
• 对话代理： 担任家庭助理对话代理
• 媒体播放器实体： 直接控制音频输入/输出
• 二进制传感器： 监控连接、听、说和处理状态
• 自定义Lovelace卡： 基于浏览器的麦克风，配备实时可视化功能

建筑

与默认的家庭助理语音管道（STT）不同→ AI → TTS），这种集成使用本地语音到语音API：

Default HA Pipeline: Mic -> STT -> AI -> TTS -> Speaker

Gemini Live Pipeline: Mic -> Gemini Live Realtime API -> Speaker

需求

• 家庭助理2024.1.0或更高版本
• 谷歌人工智能API密钥（Gemini API）
• Python 3.11或更高版本

有关其他设置详细信息，请参阅Gemini特定文档：

• 定制组件/gemini_live/GOOGLE_DOC.md

快速配置（最少示例）

Gemini Live-快速配置

在集成UI中或在适用的情况下通过YAML公开的核心选项：

• api_key / google_api_key：双子座的谷歌人工智能密钥
• model：Gemini模型（示例： gemini-2.0-flash-exp)
• voice：语音名称（示例： Puck)
• ephemeral_token （可选）：用于客户端身份验证
• enable_session_resumption：真/假
• enable_affective_dialog：真/假（v1alpha）
• enable_proactive_audio：真/假（v1alpha）

最小设置示例（面向UI）：

# Gemini Live basic settings
model: gemini-2.5-flash-native-audio-preview-12-2025
voice: Kore
enable_session_resumption: true

对于高级功能（会话恢复句柄、主动音频、图像输入），请打开组件文件夹中的Gemini文档： 定制组件/gemini_live/GOOGLE_DOC.md

安装

HACS（推荐）

1. 在家庭助理中打开HACS
2. 点击“集成”
3. 单击右上角的三个点→ “自定义存储库”
4. 添加此存储库URL: https://github.com/SJang1/ha-gemini-live
5. 安装“家庭助理实时AI音频”
6. 重启 Home Assistant

手动安装

1. 下载存储库
2. 复制 custom_components/gemini_live 文件夹到您的家庭助理 custom_components 目录
3. 重启 Home Assistant

Gemini Live集成

配置

1. 首选 设置 → 设备和服务 → 添加集成
2. 搜索“Gemini Live”
3. 输入您的Google AI API密钥
4. 配置设置：

- 模型：选择模型（默认值： gemini-2.0-flash-exp) - 语音：选择音频响应的声音 - 说明：自定义系统说明

Gemini语音选项

可用语音：

• Puck -活泼、精力充沛
• Charon -深邃而神秘
• Kore -热情友好
• Fenrir -坚强、自信
• Aoede -清晰、优美

双子座爱情卡

添加Lovelace资源

1. 首选 设置 → 仪表盘 → ⋮（三个点） → 资源
2. 点击 添加资源
3. 输入：

- 统一资源定位符: /gemini_live/gemini-live-card.js?v=1 - 资源类型：JavaScript模块

1. 点击 创建

将卡片添加到仪表板

type: custom:gemini-live-card
title: Gemini Live
show_transcript: true
keep_mic_when_hidden: true

# Clone the repository
git clone https://github.com/SJang1/ha-gemini-live.git

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Link to Home Assistant custom_components
ln -s $(pwd)/custom_components/gemini_live ~/.homeassistant/custom_components/

|--------|------|---------|-------------| | title |string |“Gemini Live”|卡片标题|

Gemini服务

gemini_live.send_message

发送短信并获得回复。

service: gemini_live.send_message
data:
  message: "What's the weather like?"

gemini_live.send_audio

将音频数据直接发送到API。

service: gemini_live.send_audio
data:
  audio_data: ""

gemini_live.start_listening

启动音频会话。

service: gemini_live.start_listening

gemini_live.stop_listening

停止音频处理。

service: gemini_live.stop_listening

Gemini二进制传感器

Gemini定价

Gemini 2.0 Flash目前处于预览阶段，具有慷慨的免费等级限制。检查 谷歌人工智能定价 以目前的价格。

故障排除

启用调试日志记录

添加到您的 configuration.yaml:

logger:
  default: info
  logs:
    custom_components.gemini_live: debug

然后重新启动家庭助理。

常见问题

• 确保您的 google_api_key 有效，可以访问Gemini。
• 麦克风需要HTTPS和浏览器权限。
• 有关会话恢复和高级功能，请参阅 定制组件/gemini_live/GOOGLE_DOC.md.

发展

# Clone the repository
git clone https://github.com/your-username/ha-realtime-ai-audio.git

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Link to Home Assistant custom_components
ln -s $(pwd)/custom_components/gemini_live ~/.homeassistant/custom_components/

许可证

MIT许可证-请参阅 许可证 了解详情。