HomeAssistant本地接入大模型语音控制实操清单

前期要确认的环境条件

• HomeAssistant版本升级到2024.6及以上，现有接入的Zigbee、Wi-Fi、蓝牙设备不用重新配对，直接兼容
• 部署主机只要能跑Docker就行，树莓派4、闲置小主机、甚至刷机后的玩客云都能带得动，性能够不够看你选云端API还是本地大模型
• 用云端API的话提前去DeepSeek或其他大模型平台申请API Key，跑本地模型的话提前装好Ollama环境

Docker部署对接组件的命令

# 拉取最新稳定版对接组件镜像
docker pull ghcr.io/zhujisheng/ha-voice-assist:latest
# 启动容器，记得替换尖括号里的内容为你自己的配置
docker run -d -p 8125:8123 \
  -e HA_URL="http://<你的HA内网IP>:8123" \
  -e HA_TOKEN="" \
  -e LLM_PROVIDER="deepseek" \
  -e DEEPSEEK_API_KEY="<你申请的大模型API Key>" \
  --restart always \
  ghcr.io/zhujisheng/ha-voice-assist:latest

• HA长期访问令牌在个人资料页面最底部生成，权限只勾选设备控制相关的就行，别给全开的管理员权限
• 要是对接本地Ollama模型，把LLM_PROVIDER参数改成"ollama"，再加一行-e OLLAMA_MODEL="<你本地拉取的模型名>"就行，不用改其他配置
• 容器启动后先访问http://<部署主机IP>:8125/health，页面返回ok就是服务正常，不用翻密密麻麻的启动日志

HomeAssistant端的配置操作

• 打开HA的集成页面，搜索添加「Assist Pipeline」集成，地址填刚才部署的组件服务地址，端口8125
• 默认唤醒词是“小夏”，要自定义的话直接在组件配置页填写新的唤醒词，不用自己额外训练模型
• 把同区域的设备归到对应的房间分组里，大模型会自动匹配控制意图，不用手动给每个设备写触发指令

别把这个服务的端口映射到公网，所有配置都走内网就行，本地链路的响应速度大概几百毫秒，日常用基本感觉不到延迟，映射公网不仅有设备被恶意控制的风险，绕一层公网传输反而会变卡。

要是遇到语音识别没反应的情况，先调麦克风的拾音增益，别上来就换更大参数的模型，十有八九是硬件拾音的问题。