Skip to content
DroidFlight Wiki

Home Assistant + 本地 LLM 中控 (OpenAI 兼容)

概念速览

  • Extended OpenAI Conversation：HA 社区集成，把 HA entity 暴露为 OpenAI Function Calling 工具
  • 支持后端：任何 OpenAI 兼容 API (Ollama / vLLM / LM Studio / OpenAI / Anthropic via proxy / 通义千问 / DeepSeek)
  • 核心能力：用自然语言控制全屋设备 + 查询历史 + 触发自动化

架构

flowchart LR
    HA["HA Entity / 自动化"] <--> Conv["Extended<br/>OpenAI Conversation"]
    Conv -->|"Function Call"| LLM["OpenAI 兼容 LLM<br/>Ollama / vLLM / LM Studio<br/>或云端 API"]
    LLM -->|"文本响应"| Action["HA 触发服务调用<br/>+ Piper TTS 播报"]
    Action --> HA

物料清单

物料最低配置推荐配置
主机树莓派 5 (8GB)Intel N100 mini-PC (16GB)
LLMLlama 3.2 3B Q4 (2.5 GB)Qwen 2.5 14B Q4 (8 GB)
内存占用4 GB12 GB
推理速度~2 tok/s~15 tok/s
适用测试 / 简单问答复杂多步任务

步骤 1：安装 Ollama (5 min)

Terminal window
# Mac / Linux 一行安装
curl -fsSL https://ollama.com/install.sh | sh


# 拉取模型 (Qwen 2.5 14B Q4 量化，约 8 GB)
ollama pull qwen2.5:14b-instruct-q4_K_M


# 测试
ollama run qwen2.5:14b-instruct-q4_K_M "你好"
# >>> 你好！有什么我可以帮你的吗？


# 让 Ollama 监听所有接口 (HA 在 Docker 中需访问)
# 编辑 /etc/systemd/system/ollama.service 中的 Environment
Environment="OLLAMA_HOST=0.0.0.0:11434"
systemctl daemon-reload
systemctl restart ollama

步骤 2：安装 HA 集成 (5 min)

安装 Extended OpenAI Conversation

  1. HA → 设置 → 加载项商店 → 添加仓库
  2. 仓库 URL：https://github.com/jekalmin/extended_openai_conversation
  3. 搜索 “Extended OpenAI Conversation” 集成并安装
  4. 重启 HA

配置

HA → 设置 → 设备与服务 → 添加集成 → Extended OpenAI Conversation：

Provider: Ollama
Base URL: http://localhost:11434/v1
API Key: ollama                            # Ollama 不需要真实 key，填任意
Model: qwen2.5:14b-instruct-q4_K_M
Context Window: 8192
Max Tokens: 1024
Temperature: 0.3

暴露的 entity 范围（建议白名单，避免 LLM 控制一切）：

Exposed Entities:
  - light.living_room_ceiling
  - light.bedroom_ceiling
  - switch.kitchen_plug
  - climate.living_room_ac
  - cover.bedroom_curtain
  - media_player.living_room_tv
  - fan.air_purifier

步骤 3：第一次对话 (2 min)

HA → 设置 → 语音助手 → 添加助手 → “OpenAI Conversation”：

User: "把客厅灯调到 50%，把卧室空调开到 24 度"

LLM 推理：

思考：用户要调两个设备
工具调用 1: light.turn_on
  target: light.living_room_ceiling
  brightness_pct: 50
工具调用 2: climate.turn_on
  target: climate.bedroom_ac
  temperature: 24

HA 触发服务调用，LLM 回复：

"已把客厅灯调到 50%，卧室空调已开到 24 度。"

步骤 4：接语音 (10 min)

4.1 安装 Piper TTS (本地语音合成)

Terminal window
# HA 添加 Piper 集成
# Settings → Voice assistants → Text-to-speech → Add → "Piper"
# 选中文模型: zh_CN-huayan-medium.onnx

4.2 安装 Wyoming + Whisper (STT)

Terminal window
# 在 HA 主机上跑 Wyoming Faster-Whisper
docker run -d \
  --name wyoming-whisper \
  --restart unless-stopped \
  -p 10300:10300 \
  rhasspy/wyoming-faster-whisper \
  --model tiny-int8 --language zh

4.3 配置语音助手

HA → 设置 → 语音助手 → 助手配置：

语音转文字 (STT): Wyoming Faster-Whisper
文字处理 (Agent): Extended OpenAI Conversation
文字转语音 (TTS): Piper
唤醒词: openWakeWord ("Hey Jarvis" / "你好米家")

4.4 加装 ESP32-S3 语音卫星

详见 语音卫星硬件 — 配对后每房间 1 个。

步骤 5：MCP 桥接 (高级)

让 LLM 不只通过 HA 调用设备，还能调用任何 MCP 工具 (日历、邮件、网页)：

[Extended OpenAI Conversation]
        │
        ▼ Function Call
[本地 LLM]
        │
        ▼ 选择工具
        ├─ HA Service (灯光/空调)
        ├─ MCP Server (日历/天气)
        └─ HTTP API (通知推送)

详见 Robot MCP Agent 协议 和 智能家居 MCP 协议。

性能调优

问题调优手段
LLM 响应慢 (> 5s)换更小模型 / 开 vLLM 加速 / 减少暴露 entity
幻觉调用不存在的服务在 Extended 集成中开启 Strict Function Call
TTS 中文发音差换 Piper zh_CN-huayan-medium 模型
Whisper 误识别改用 small-int8 模型 (更准但更慢)
多人共用互相干扰配置 conversation_id 按说话人路由

进阶：本地多模态

用 Qwen2-VL 替代文本 LLM，支持图片理解（“看看厨房现在什么样”）：

Terminal window
# 拉取视觉模型
ollama pull qwen2-vl:7b-instruct-q4_K_M


# HA 中添加摄像头 entity
camera.kitchen
# Extended 集成会自动包含摄像头快照到 LLM 上下文

故障排查

📋 复现条件

类别必备可选 / 备注
硬件Home Assistant 主机 · 跑 LLM 的 GPU 服务器或 N100 mini PC (16GB)双机部署 (HA + LLM 分离)
操作系统HAOS 14+ / Debian 12 · LLM 端 Ubuntu 22.04+macOS 14 (开发测试)
软件版本HA 2024.10+ · Ollama 0.3+ · Qwen 2.5 14B Q4 · Extended OpenAI Conversation 1.0+vLLM 0.6+ (生产)
网络HA ↔ LLM 主机千兆网 (延迟 < 5ms)GPU 服务器可走 WAN
账号无 (本地推理)OpenAI API key (备选云端)
时间Ollama 装 + 拉模型 20 min · HA 集成 15 min · 调 entity 白名单 30 min全自动化测试 +1 h
难度⭐⭐⭐ 进阶Prompt 工程需要迭代
前置知识HA 基础 · 了解 LLM tool-call 概念网络配置 / YAML

⛔ 别这么做 (Anti-patterns)

经验证的坑 —— 跳过 = 至少浪费半天，严重的烧板 / 锁机。

❌ 错误做法💥 后果⚠️ 风险范围
不要在断电前直接拔 Valetudo 改装中的 USB-TTL刷机中途断电 = 变砖。先 dmesg 确认串口没掉再操作。🟡智米扫拖一体 / Roborock S5 Max
不要把米家设备 token 上传到任何第三方云token = 设备控制权，泄漏 = 任何人可远程开门。🔴所有米家 / Aqara 设备
不要在生产 HA 配置里直接编辑 configuration.yaml 后 check_config 不通过就 reload错的 reload 会让 HA 启动失败 → 所有自动化停摆。用 configuration.yaml 备份 + git 版本化。🟢Home Assistant
不要给 Frigate 摄像头内网用 admin/admin 默认密码RTSP / ONVIF 默认账号 = 局域网裸奔。先改密码。🟡海康 / 大华摄像头
不要在 ESPHome 设备上直接 OTA 升级到主版本 (major)主版本常改 NVS 分区。OTA 升级后启动失败 = 拆壳刷机。先 flash USB 一次。🟡ESP32-S3 语音卫星 / 智能开关
不要在智能家居自动化里写死设备 IPDHCP 重启后 IP 变 = 自动化失效。用 hostname / mDNS / 静态租约。🟢Home Assistant / Hubitat
不要在 Matter 设备首次配对时关掉手机蓝牙Matter 配对 = BLE → WiFi handover，全程需要蓝牙。🟢Aqara M3 / Apple Home

🚨 风险总览 (Risk Matrix)

风险等级含义例子
🟢 低改错可回滚 / 几分钟恢复pip 全局装包、DHCP IP 写死
🟡 中需要重新刷机 / 重装 / 1-2 小时恢复装错 ROS 2 版本、没 OTA 升级看版本
🔴 高不可逆 / 烧板 / 安全风险电池反接、micro-ROS 没看门狗、刷机中途断电

参考资料