ha-voice

Home Assistant 语音控制

配置 Assist 管道、自定义意图、唤醒词、语音处理和语音卫星，实现本地语音控制。

快速入门

设置 Assist 管道

# configuration.yaml
assist_pipeline:
  pipelines:
    - language: en
      name: Default Pipeline
      stt_engine: faster_whisper  # Local STT
      tts_engine: tts.piper       # Local TTS
      conversation_engine: conversation.home_assistant
      wake_word_entity: binary_sensor.wake_word

为何重要： 管道将所有组件（STT、TTS、意图、对话 Agent）连接起来，形成单一语音工作流。

创建自定义意图

# custom_sentences/en/turn_on.yaml
language: en
version: 1

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on the [area] {name:list}"
          - "turn on {name:list}"
          - "[please] activate {name:list}"
        lists:
          name: light_names

lists:
  light_names:
    - "bedroom light"
    - "kitchen overhead"
    - "living room"

为何重要： 自定义句式模式可启用自然语音命令，满足家庭场景需求。

配置文本转语音（TTS）

本地选项 - Piper：

tts:
  - platform: piper
    language: en_GB
    voice: jenny_dioco

云端选项 - OpenAI：

tts:
  - platform: tts
    service: google_translate_say  # or openai, google cloud
    language: en

为何重要： TTS 可提供语音反馈；本地选项无需依赖云服务。

配置语音转文本（STT）

本地选项 - Faster Whisper：

stt:
  - platform: faster_whisper
    language: en

云端选项 - Google Cloud Speech：

stt:
  - platform: google_cloud
    language_code: en-US

为何重要： STT 会将语音命令转换为文本；本地选项可保护隐私。

重要规则

✅ 务必做到

• ✅ 使用 custom_sentences/ 目录配置意图（不要使用已弃用的 sentences/）
• ✅ 部署前使用 Assist 开发者工具测试意图
• ✅ 使用 {name:list} 语法进行基于槽位的实体匹配
• ✅ 在同一管道中配置 STT 和 TTS 引擎
• ✅ 在管道中启用唤醒词前，确认对应实体存在
• ✅ 记录意图列表，方便用户发现可用的语音命令

❌ 绝不要做

• ❌ 不要在句式模式中硬编码实体 ID（请使用列表和槽位）
• ❌ 不要忘记在 custom_sentences YAML 文件中添加 version: 1
• ❌ 不要混用旧的 sentences/ 目录和新的 custom_sentences/ 目录（仅使用 custom_sentences/）
• ❌ 磁盘空间不足时不要启用 Piper TTS（模型大小超过 100 MB）
• ❌ 不要在每个槽位中都使用通配符 {query}（这会导致意图模糊不清）
• ❌ 不要跳过使用 Assist 开发者工具进行测试

常见错误

❌ 错误 - 硬编码实体 ID：

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on light.bedroom"
          - "turn on light.kitchen"

✅ 正确 - 使用槽位列表：

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on [the] {name:list}"
        lists:
          name: light_names

lists:
  light_names:
    - "bedroom"
    - "kitchen"

原因： 列表具有动态性，可通过 Home Assistant 实体以编程方式生成。

句式模式语法

槽位

命名槽位匹配列表值：

sentences:
  - "turn on {name:list}"  # Matches list value, captures as 'name' slot

列表

列表匹配提供槽位值：

lists:
  room:
    - "bedroom"
    - "kitchen"
    - "living room"

可选分组

方括号表示词语可选：

sentences:
  - "[please] turn on the {name:list}"
  - "activate [the] {device:list}"

通配符

通配符槽位可捕获任意文本：

sentences:
  - "remind me {reminder:text}"  # Captures any text as 'reminder'
  - "set a timer for {duration:text}"

组合模式示例

intents:
  TurnOn:
    data:
      - sentences:
          - "[please] [turn on | switch on | activate] [the] {area} {name:list}"
          - "[please] turn on {name:list}"
          - "activate {name:list} [in the] {room:list}"
        lists:
          name: light_names
          room: room_names

  Reminder:
    data:
      - sentences:
          - "remind me {reminder:text}"
          - "[please] [create | set] a reminder [for me] [to] {reminder:text}"

lists:
  light_names:
    - "bedroom light"
    - "kitchen overhead"
    - "living room lamps"
  room_names:
    - "bedroom"
    - "kitchen"
    - "living room"

为何重要： 灵活的模式既支持自然表达，也能确保意图识别准确度。

内置意图参考

Home Assistant 提供以下默认意图：

导航意图

• HassTurnOn / HassTurnOff - 控制设备
• HassToggle - 切换开关或灯的状态
• HassOpenCover / HassCloseCover - 控制窗帘
• HassSetClimate - 控制温度（制热/制冷）

信息意图

• HassGetState - 获取实体状态
• HassGetHistory - 查询自动化历史记录

家庭控制意图

• HassArmAlarm / HassDisarmAlarm - 布防/撤防警报
• HassLockDoor / HassUnlockDoor - 控制门锁

自定义意图

通过定义新的意图块，在 custom_sentences/ 中创建其他意图：

intents:
  CustomIntentName:
    data:
      - sentences: [...]

唤醒词配置

openWakeWord（本地）

conversation:
  engine: openai

# Enable openWakeWord
binary_sensor:
  - platform: openwakeword
    models:
      - alexa    # "Alexa, help"
      - hey_google  # "Hey Google, ..."
      - hey_siri

Porcupine（本地，付费）

binary_sensor:
  - platform: porcupine
    access_key: !secret porcupine_key
    keywords:
      - hey_home_assistant

语音卫星设置

硬件要求

• 麦克风： INMP441（I2S 数字麦克风）或类似产品
• 扬声器： MAX98357A 放大器或类似产品
• 开发板： ESP32-S3，推荐使用 ESP32-S3-BOX-3
• 连接： 需要 WiFi

ESPHome 语音助手配置

# ESPHome device
packages:
  voice_assistant: !include packages/voice_assistant.yaml

# Or inline configuration:
i2s_audio:
  i2s_lrclk_pin: GPIO33
  i2s_bclk_pin: GPIO34
  i2s_mclk_pin: GPIO32

microphone:
  - platform: i2s_audio
    id: mic
    adc_type: external
    i2s_din_pin: GPIO35
    pdm: false

speaker:
  - platform: i2s_audio
    id: speaker
    dac_type: external
    i2s_dout_pin: GPIO36
    mode: mono

voice_assistant:
  microphone: mic
  speaker: speaker
  noise_suppression_level: 2
  auto_gain: 80dB
  volume_multiplier: 0.8

为何重要： 语音卫星可将 Assist 扩展到多个房间，并在本地进行处理。

语音处理配置

语言支持

完整支持（20 多种语言）： en、de、fr、it、es、nl、pl、pt、ru、sv、tr、uk、zh、ja、ko 等

部分支持（40 多种语言）： 区域变体及其他语言，STT/TTS 支持情况各不相同

社区支持（80 多种语言）： 社区贡献的句式模板

语言配置：

assist_pipeline:
  pipelines:
    - language: de  # German
      name: Deutsche Pipeline
      tts_engine: tts.piper  # Set voice per language

性能调优

STT（Faster Whisper）：

stt:
  - platform: faster_whisper
    language: en
    model: base  # tiny, base, small, medium, large
    acceleration: gpu  # CPU or GPU

TTS（Piper）：

tts:
  - platform: piper
    voice: en_GB-jenny
    rate: 11025  # Audio sample rate
    volume_normalize: true

对话 Agent 集成

内置 Agent：

conversation:
  engine: home_assistant

OpenAI Agent：

conversation:
  engine: openai
  api_key: !secret openai_api_key
  model: gpt-4

自定义对话 Agent：

conversation:
  engine: custom
  module: custom_components.my_agent

常见意图模式

设备控制模式

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on [the] {name:list}"
          - "[please] activate {name:list}"
        lists:
          name: light_names

气候控制模式

intents:
  SetClimate:
    data:
      - sentences:
          - "set [the] {room:list} [thermostat] to {temp:number} degrees"
          - "make it {temp:number} in [the] {room:list}"
        lists:
          room: room_names

查询模式

intents:
  GetState:
    data:
      - sentences:
          - "what is the temperature [in the] {room:list}"
          - "is [the] {name:list} on"
        lists:
          room: room_names
          name: device_names

使用开发者工具进行测试

1. 前往 开发者工具 → Assist
2. 输入测试句子：“turn on the bedroom light”
3. 检查：
   • ✅ 意图是否正确匹配
   • ✅ 槽位是否正确提取
   • ✅ 音频是否播放（如果已配置 TTS）
4. 通过以下方式排查不匹配问题：
   • 检查句子模式
   • 检查列表值
   • 确认槽位名称

故障排除

未识别意图

症状： 语音命令未匹配任何意图

解决方案：

# Check custom_sentences directory structure
ls -R config/custom_sentences/

# Verify YAML syntax
cat config/custom_sentences/en/custom.yaml

# Test in Assist Developer Tools with exact phrase
# Adjust sentence patterns to match expected phrasing

TTS/STT 引擎无法工作

症状： Assist 中出现“Engine not available”错误

解决方案：

# Verify engine is configured
service: tts.piper  # Must exist

# Check dependencies installed
pip install piper-tts  # for Piper
pip install faster-whisper  # for Whisper

# Restart Home Assistant to load engines

未触发唤醒词

症状： 尽管有噪声，二进制传感器仍保持关闭

解决方案：

# Verify entity_id is correct
service: homeassistant.update_entity
target:
  entity_id: binary_sensor.wake_word

# Check binary sensor configuration
# Review noise levels and model sensitivity
# Test microphone separately

语音卫星连接问题

症状： ESP32 与 WiFi 或 Assist 管线断开连接

解决方案：

# Check WiFi signal strength in ESPHome logs
# Reduce WiFi distance or add access point
# Update ESPHome firmware
esphome run voice_assistant.yaml --upload-speed 115200

依赖项

必需

组件	版本	用途
Home Assistant	2024.1+	Assist 平台
Faster Whisper	0.5+	本地 STT 引擎
Piper TTS	1.0+	本地 TTS 引擎

可选

组件	版本	用途
OpenWakeWord	0.3+	唤醒词检测
Porcupine	Latest	高级唤醒词
ESPHome	2024.1+	语音卫星设备

官方文档

• Home Assistant 语音控制
• Assist 管线配置
• 意图识别指南
• 对话集成

设置检查清单

使用语音命令前，请确认：

• Assist 管线已配置 STT、TTS 和对话引擎
• 已创建包含意图定义的 custom_sentences/en/ 目录
• 已在 Assist 开发者工具中测试句子模式
• 唤醒词实体已存在（如果使用唤醒词）
• 麦克风和扬声器工作正常（通过开发者工具测试）
• 意图列表包含正确的实体别名
• 语言设置与配置相符
• 所有 YAML 语法均有效（无制表符，缩进正确）