Hermes Agent可本地接入HomeAssistant实现离线语音控制。需在Debian 12/Ubuntu 22.04系统上部署Docker环境，配置ALSA音频驱动、独立MQTT Broker及正确环境变量；支持MQTT自动发现或Intent Script手动联动；需用Vosk训练本地ASR模型并正确挂载路径。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
用Hermes Agent接入HomeAssistant，让语音指令直接控制灯光、空调、窗帘等设备，无需依赖云端语音平台，所有处理在本地完成，响应快、隐私强、断网也能用。
准备本地运行环境
确保树莓派或x86小主机已安装Docker和docker-compose，系统为Debian 12或Ubuntu 22.04 LTS。旧版内核可能缺少ALSA音频模块支持，会导致麦克风无法初始化。
执行 sudo apt update && sudo apt install -y alsa-utils pulseaudio，然后运行 arecord -l 确认USB麦克风或Respeaker设备被识别为card 1。
这一步不可跳过：若未加载音频驱动，后续Hermes Agent启动时会静默失败，日志里只显示“no audio input”，无其他报错提示。
部署HomeAssistant与Hermes Agent服务
创建 docker-compose.yml 文件，内容包含 【homeassistant】、【hermes-agent】 和 【mqtt-broker】 三个服务。MQTT必须作为独立broker运行，HomeAssistant内置的Mosquitto插件不支持Hermes协议所需的QoS 2订阅。
在Hermes Agent服务配置中，将 SNIPS_AUDIO_SERVER 环境变量设为 localhost:12101，否则语音流无法路由到ASR模块。
运行 docker-compose up -d 启动全部容器。等待约90秒，检查 docker-compose logs hermes-agent | grep "Connected to MQTT" 输出是否出现连接成功标记。
配置HomeAssistant设备联动
方法一：通过MQTT Discovery自动注册
在HomeAssistant的 configuration.yaml 中启用MQTT集成，并添加 discovery: true。Hermes Agent启动后会向 homeassistant/sensor/xxx 主题发布设备描述，HomeAssistant自动创建对应实体。
方法二：手动定义Intent Script
进入HomeAssistant → 设置 → 自动化与脚本 → 脚本 → 创建脚本，名称填“打开主卧灯”，动作类型选“调用服务”，服务填 light.turn_on，服务数据填 {"entity_id": "light.master_bedroom"}。
接着在Hermes Agent的 intent-handlers 目录下新建 open_master_light.py，内容调用HomeAssistant REST API发送POST请求到 /api/services/light/turn_on，Header必须带 X-Auth-Token（从HomeAssistant长寿命令牌页面生成）。
【注意：令牌权限必须勾选“控制所有设备”，否则调用失败且无明确错误返回】
训练本地语音识别模型
第一步：收集至少30条带标注的唤醒词录音（如“小智”），每条时长1.2～2.5秒，保存为16kHz单声道WAV。
第二步：用Vosk训练工具打包成 model.zip，解压路径需与Hermes Agent配置中的 asr_model_path 完全一致，路径末尾不能有多余斜杠。
第三步：修改 hermes.conf，将 asr_engine 设为 vosk，并确认 model_path 指向解压后的文件夹（含 model.json 和 graph/ 子目录）。
重启Hermes Agent容器，运行 docker-compose logs -f hermes-agent，看到 Loaded Vosk model from /opt/models/vosk-small 即表示加载成功。
