“你好小爱同学把客厅空调调到 24 度。”——这句话本身不新鲜但如果你折腾过智能家居一定懂这里的痛小爱同学偶尔听岔、离线就断、复杂的复合指令直接“对不起我还没有学会”。传统智能家居的语音助手本质上只是一张“命令映射表”它不理解“我有点热”意味着什么更不会主动问你要不要打开风扇。最近一两年越来越多 HomeAssistant 玩家在折腾一件事把 ChatGPT、DeepSeek 这类 AI 大模型接进 HA让智能家居从一个“听指令的开关”变成“能对话的管家”。这不是炫技而是智能家居交互逻辑的一次实质性变化。今天这篇内容我会把 HomeAssistant 接入 ChatGPT 和 DeepSeek 的完整思路、配置方法、验证方式和排错路径讲清楚尽量让你看完能直接照着做。1. 为什么偏偏是 HomeAssistant 接入大模型先给一个明确判断HomeAssistant 是目前最适合接入大模型的智能家居平台没有太多争议。原因有三个维度。第一HA 的设备接入层已经足够统一。无论是米家、涂鸦、HomeKit、Sonoff 还是 Zigbee/蓝牙设备都能通过不同的集成接入 HA。设备到了 HA 之后抽象成了统一的 entity 对象。这意味着大模型不需要直连几十个品牌的 API只需要面向 HA 的实体 API 工作。第二HA 有一个天然的 AI 载体Assist 语音助手管道。Assist 是 HA 自带的智能语音助手框架它可以接收用户的语音文本交给一个“conversation agent”处理返回文本再由 TTS 播报。大模型接入 HA 的实质就是让大模型扮演这个 conversation agent而不是像某些厂商那样封闭在云端。第三HA 的自动化能力足够强。接入大模型不是只是“问天气、答废话”它需要通过 HA 提供的工具调用接口去执行开关灯、调温度、查传感器状态等真实动作。HA 长期积累的 service 调用、模板、自动化机制正好支撑这一点。从生态趋势看OpenAI 官方已经通过其 Conversation 集成原生支持 HA而 DeepSeek 这类国产模型则通过自定义对话集成或本地代理接入。这个背景下接入大模型不再是小圈子玩家的玩具而是很多家庭自动化项目里真正提升体验的实用方案。你读完这篇文章能得到什么你能理解 HA 对话管道的运行机制知道 ChatGPT 和 DeepSeek 两种接入方式的差异并且拿到一份可以沿用到自己环境的配置示例。文章不会涉及复杂的模型训练或 new 算法专注“接入”这件事。2. HA 接入大模型前的核心概念在动手配置之前有几个概念必须建立清晰认知否则后面会经常绕晕。2.1 Conversation Agent对话代理HA 的 Assist 架构里conversation agent 是处理用户文本的中心。它接收“请把卧室灯关掉”这句话解析出意图通过 service 调用完成操作然后返回给用户“好的卧室灯已关闭”。传统 HA 默认的 conversation agent 是本地按规则解析的能力有限。接入大模型后agent 变成一个 LLM 实例它不仅能解析意图还能根据对话历史判断用户上下文甚至主动询问“您是想打开大灯还是床头灯”。2.2 实体、设备和 Service实体EntityHA 中最小的可控对象如light.living_room表示客厅灯。设备Device由一个或多个实体组成的物理设备如一个智能插座带电量统计实体和开关实体。Service服务HA 执行动作的接口如light.turn_on、climate.set_temperature。大模型接入 HA 的核心能力就是把自然语言翻译成 service 调用。这一步在代码层面是通过 HA 的工具Tool机制实现的LLM 收到用户请求后会申请调用指定 serviceHA 执行后把结果返回给模型模型再把最终回复组织成自然语言。2.3 提示词与系统指令所有大模型接入都绕不开 system prompt。HA 接入大模型时开发者可以自定义系统指令让它知道“你现在是家庭的智能管家你可以控制某些设备请用简洁的中文回答”。同一个大模型引擎提示词写得好不好使用体验相差很大。2.4 语音管道Voice PipelineHA Assist 的语音管道包含语音唤醒词引擎 → STT语音转文字→ conversation agent → TTS文字转语音。接入大模型只改中间一环conversation agent。实际使用中你仍然可以用“小爱同学”等硬件做唤醒和 TTS只是把“大脑”换成了 LLM。这种架构的好处是你不必为了用大模型而把整套语音硬件都换掉。2.5 官方集成与自定义集成的区别ChatGPT 的接入相对简单因为 HA 官方提供了openai_conversation集成集成名可能有版本差异请以当前官方文档为准。DeepSeek 则不一样它可能没有对应的官方 HA 集成社区一般采用自定义集成或“本地代理中转”的方式把 DeepSeek 的 API 兼容层包装成 OpenAI 兼容接口供 HA 调用。理解这一点很重要因为它决定了你的配置维护成本。用官方集成的升级体验更平滑用自定义方案则需要你跟进代理的版本变动。3. 环境准备与前置条件开始配置之前先核对环境。本文的示例以 HA 2024 年之后的版本为基准重点演示通用思路具体小版本差异不会写死。3.1 硬件与系统一台运行 HomeAssistant 的主机。常见方式有 HA OS 硬件盒子、树莓派、NAS 的 Docker 容器。如果你使用 Docker需要保证网络能正常访问外网的模型 API 服务。建议预留至少 2GB 内存给 HA 和附属组件模型 API 不在本地跑对算力要求低。3.2 模型服务账号接入 ChatGPT 需要一个 OpenAI API Key接入 DeepSeek 需要在 DeepSeek 开放平台注册账号并创建 API Key。有一点必须强调API Key 是按使用量计费的请理解你的用量和费用控制方式。建议在开放平台设置消费上限或定期查看用量防止异常的自动调用产生高额费用。3.3 HomeAssistant 的前期准备HA 已正常启动并能通过 Web 界面登录。已经接入了至少一个可控设备比如一个智能灯泡或智能插座。建议提前在 HA 界面测试手动开关设备正常再开始接入大模型。4. HA 接入大模型的架构与数据流不看整体架构配置起来容易“照着抄还报错”。这里先把数据流梳理清楚。传统链路用户说话 → 语音硬件 → STT 转文本 → Assist 意图解析 → 执行 service → TTS 回复。接入大模型后的链路与之类似区别在 Assist 引擎把意图解析交给了 LLM用户在 Android/iOS HA App 或语音硬件上说“客厅灯太亮了” → STT 把语音转成文本 → HA 把文本、当前设备状态快照、可用工具列表一起发给模型 API → 模型返回意图调用light.turn_on并设置亮度 → HA 执行调用并回传结果 → 模型生成自然语言回复 → TTS 播报。需要特别注意HA 发送给模型的 prompt 里包含了当前设备的状态信息这是 LLM 能够“看到”家庭里有哪些设备的前提。所以接入大模型之后HA 会向模型端传输一部分设备名称、状态、实体 ID 等元数据。这里存在隐私边界问题我会在最佳实践环节展开。还有一个关键点HA 的对话管道调用模型 API 时是同步阻塞等待模型返回的。如果你的模型 API 网络延迟很高用户会感觉语音助手“反应迟钝约 3 到 5 秒”。这也是实际部署中很多人最终选择把接入条件放在“外网访问质量尚可”的环境或选择国内可直连模型服务的原因。5. 接入 ChatGPT 的配置步骤OpenAI 官方 Conversation 集成的优势是配置简单、官方维护、文档完整。由于 HA 版本之间的差异集成名称可能出现过调整下面按最通用的方式写配置方法。5.1 安装集成在 HA 的侧边栏中进入“设置 → 设备与服务 → 添加集成”搜索 “OpenAI Conversation”。如果搜索结果没有显示注意检查你的 HA 版本是否较旧可以先升级 HA 再尝试。添加过程中系统会要求你输入API KeyOpenAI 平台生成的密钥注意复制完整内容不要带多余空格。模型名称。CHATGPT 系列的模型名称请以 OpenAI 当前文档为准如gpt-4o-mini或同日其他可用型号。如果你没有把握优先选择官方推荐的轻量型号成本和响应速度都更友好。对话上下文数量。这是控制发送给模型的历史对话轮数配置过大会增加 token 消耗配置过小则上下文记忆不足。5.2 通过 configuration.yaml 配置除了通过 UI 添加集成也可以直接在configuration.yaml中配置。# configuration.yaml openai_conversation: api_key: sk-xxxxxxxxxxxxxxxx model: gpt-4o-mini temperature: 0.6 max_tokens: 400这段配置的含义api_keyOpenAI API 密钥请用真实的 Key 替换。model要使用的模型 ID请以 OpenAI 官方列表为准不要随意填一个不存在的历史版本名。temperature采样温度0 到 1 之间。数值越低回复越保守越高越有发散性。对于家庭自动化控制类任务建议设置在 0.4 到 0.7 之间不要太高否则它可能给出控制灯具亮度时偏离预期的回复。max_tokens单次回复的最大 token 数量。家庭助手回复不需要太长300 到 500 足够设太大的话浪费 token。配置完成后重启 HA 或通过“开发者工具 → YAML → 重新加载核心配置”使配置生效。5.3 配置 Assist 默认代理光有集成还不够你还得让 Assist 管道使用它作为默认对话代理。在 HA 界面进入“设置 → 语音助手”选择你正在使用的 Assist 语音助手在“对话代理”一栏选择刚才添加的 OpenAI Conversation 集成。保存后测试对话时会优先走这个模型。如果这一步不配置即使集成了 OpenAI话音助手还是用旧的意图解析引擎效果不会有任何变化。这是新手最容易误以为“接入失败”的原因之一。5.4 测试对话在 HA 首页点击右上角的 Assist 图标输入文字“现在客厅灯开着吗”如果配置正确模型会基于 HA 发送的设备状态返回一句话比如“客厅灯目前处于开启状态亮度为 80%”。也可以尝试控制性指令“帮我把卧室灯调暗一点。”模型会调用light.turn_on之类的 service。如果模型没有完成操作而是返回“我没有权限”或“我不知道怎么操作”多半是设备没有暴露给 Assist或者是实体名称不够明确。这个问题在排错章节集中讲。6. 接入 DeepSeek 的配置步骤DeepSeek 是国产大模型里性价比和可用性都比较突出的一个选择API 定价比许多国外模型低吸引了不少 HA 玩家。但接入方式和 ChatGPT 略有不同官方 HA 集成不一定是现成的一般通过 OpenAI 兼容接口或社区集成接入。从当前材料看DeepSeek 提供了 OpenAI 兼容的 API 接口因此 HA 项目中多数采用“自定义对话集成”或“本地代理服务”的方式让 HA 把 DeepSeek 认作一个标准对话接口来调用。6.1 方案一自定义 OpenAI 兼容集成推荐在 HA 中部分第三方集成专门用于接入 OpenAI 兼容服务。配置思路是把 DeepSeek 的base_url指向它的 API 地址填入你的 DeepSeek API Key然后选择模型名称如deepseek-chat。如果你使用的自定义集成支持configuration.yaml方式配置典型的写法如下集成名和字段请以你实际安装的集成说明为准# configuration.yaml 示例具体集成名可能不同 custom_openai_conversation: api_key: sk-deepseek-xxxxxxxx base_url: https://api.deepseek.com model: deepseek-chat temperature: 0.5需要注意base_url的路径格式取决于集成实现有的需要写成https://api.deepseek.com/v1。请优先参考你选择的集成项目的 README。6.2 方案二本地代理中转另一种方式是在本地跑一个 OpenAI API 兼容的代理服务然后把 HA 的 OpenAI 集成指到本地代理再由代理转发给 DeepSeek。这样做的优势在于HA 与本地代理之间走的是 OpenAI 标准协议HA 的官方集成可以直接用无须修改 HA 配置。代理是本地进程便于调试和控制日志。代理的选型和技术细节比较多这里不把某个代理的安装命令展开写成“死命令”更建议你在搜索时使用关键词“DeepSeek OpenAI 兼容 本地代理”找一个维护活跃度高的项目按它的 README 配置即可。6.3 直接调用 DeepSeek API 验证连通性无论采用哪种 HA 接入方式建议先确认你的 DeepSeek API Key 和接口能正常返回。用下面的 curl 命令做快速验证curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-deepseek-xxxxxxxx \ -d { model: deepseek-chat, messages: [ {role: user, content: 你好请用一句话介绍智能家居} ] }预期会返回一个 JSON 响应其中choices[0].message.content字段就是模型生成的文本。如果返回 401 或 404说明 API Key 或 base_url 填错了需要先在这里解决不要直接去改 HA 配置。curl 验证通过后再去 HA 里配置自定义集成问题定位会清晰很多。7. 运行结果与效果验证接入完成之后不能只看“能打字回复”就以为是成功了。真正的验证应该包括三层对话层、控制层和语音层。7.1 对话层验证验证模型是否能正确回答家庭环境相关的问题。在 Assist 对话框里输入“当前卧室温度是多少”。预期行为模型查看 HA 提供的传感器状态回复类似“卧室温度为 26.3 摄氏度”。如果模型说“抱歉我无法获取实时数据”那说明设备的传感器状态没有传给模型或者实体名称没有被正确暴露。7.2 控制层验证输入带明确指令的句子“打开客厅灯并设置亮度 50%”。验证方法是观察 HA 的日志和实体状态。运行命令查看 HA 日志docker logs homeassistant --tail 50如果日志中出现类似light.turn_on的 service 调用记录说明模型成功触发了 HA 的 service。如果没有任何调用记录模型可能只是“嘴上说说”没有真正控制设备。7.3 语音层验证如果你配置了语音管道在手机上按住 Assist 按钮说出指令听 TTS 的回复是否正常。语音链路涉及 STT 识别、LLM 理解和 TTS 播报任何一环出问题现象可能是“识别出来了但没反应”或“耳朵能听懂但始终不回答”。这一步验证的是端到端体验。7.4 HA 日志中的常见关键词配置失败时HA 日志是定位问题的第一入口。在 HA 界面进入“设置 → 系统 → 日志”或在 Docker 环境使用docker logs查看。关注这些关键词日志关键词含义401/unauthorizedAPI Key 无效或无权限404/not found请求路径或模型名称错误timeout模型 API 响应超时多为网络原因stream_timeout流式响应超时或网络不稳定service not found模型试图调用不存在的 service说明提示词约束不够或 HA 侧集成缺失8. 常见问题与排查思路从社区常见的反馈来看下面这些问题出现频率最高。问题现象可能原因排查方式解决方案配置之后 Assist 还是原来的行为Assist 没有切换对话代理检查“设置 → 语音助手”中的代理选项手动选择刚才接入的 OpenAI/DeepSeek 代理模型能对话但无法控制设备设备实体没有暴露给 Assist打开设备实体的 Assist 开关或在语音助手中选择允许控制的实体在实体设置中启用“语音控制”并配置允许区域模型回复内容中带 Markdown 符号提示词中未约束回复格式查看 HA 发送给模型的 system prompt在配置中增加“使用纯文本中文回复不使用 Markdown 符号”调用 DeepSeek 时一直 401API Key 错误或 base_url 不对先 curl 验证再看 HA 日志中的请求地址重新复制 Key按集成文档核对 base_url模型响应太慢网络延迟或模型本身排队测试 API 延迟观察日志消耗时间换轻量模型或选择更稳定的访问链路频繁消耗大量 token上下文轮数设置过大或设备状态快照过长查看用量统计检查对话历史轮数配置降低上下文轮数限制暴露实体数量自定义集成升级后配置失效集成作者变更了配置字段查看项目更新日志和 README按新版本文档调整配置必要时先备份原配置这里重点展开两个容易踩坑的点。坑一Assistant 能说话但语言指令无法操作设备。这通常不是模型的问题而是 HA 没有把设备的控制权暴露给 Assist。HA 的对话代理能调用的 service受到实体的暴露范围限制。如果某个灯泡没有在助手界面中开启控制权限模型即使理解了意图也无法真正执行。解决方式是让模型具备“工具调用”能力同时确保对应实体的 Assist 权限开启。坑二DeepSeek 自定义集成加载失败。自定义集成开发版本参差不齐有时是因为 HA 版本太旧缺少集成依赖的接口有时是因为 YAML 缩进格式不对。遇到这种情况先去下载页面看是否支持你的 HA 版本再检查日志和配置的字段名。不要同时安装多套互相覆盖的自定义对话集成可能产生不可预知的冲突。9. 隐私、成本与最佳实践接入大模型不是“把 Key 填进去”就完事下面这些工程和隐私层面的建议越早了解越省心。9.1 隐私边界哪些数据被发送给了模型 APIHA 发送给模型的对话请求中通常包含用户的问题、所选对话代理的配置、以及 HA 当前实体状态快照。实体状态快照里可能包含设备名称、区域、状态值、单位等。对大多数家庭来说这些信息不算极敏感但如果你家里有一些不应让第三方模型处理的数据就需要在实体暴露层面做好隔离。给你的实操建议是在 Assist 的实体暴露范围中只勾选需要语音控制或者需要通过模型控制的设备不要无脑全选。比如摄像头、门锁、家庭地理位置这类敏感实体尽量不要暴露给云端模型服务。如果实在需要控制也要在 prompt 中明确限制“不要主动播报门锁或摄像头的详细信息”。另外如果使用第三方语音硬件 云端 STT通常还有一层音频数据交互。这部分属于语音链路的问题可以在 HA 的语音管道配置中单独选择本地 STT 或本地 TTS 来降低隐私风险。9.2 成本控制让大模型接入可长期使用ChatGPT API 和 DeepSeek API 都是按 token 计费。模型回复时HA 会把设备状态快照作为一个较大的上下文输入这意味着每次请求都可能消耗数百 token。真实使用中一天几十次请求、每次几百个 token成本可控但如果有人频繁测试或设置不当也可能产生不必要的费用。控制成本的方法把max_tokens限制在 300 到 500。把上下文对话轮数限制在 2 到 4 轮避免无限累积历史。在 HA 的对话代理配置中限制暴露给模型的实体范围和数量。定期检查模型平台的费用记录设置预算上限。尽量使用轻量模型。DeepSeek 的轻量对话模型和 ChatGPT 的轻量型号通常足够处理家庭控制指令不需要追求最强推理能力。9.3 Prompt 设计的工程层面同样一个模型工程级的 prompt 和随手写的 prompt效果可能相差很多。推荐的做法是在对话代理配置中编写一份“系统角色说明”明确约束以下几点角色定位“你是家庭智能助手负责控制以下设备并回答问题。”回复风格“回复要简洁友好中文为主不使用 Markdown 符号。”动作边界“当用户请求控制设备时优先调用 service如果设备状态异常请说明原因。”安全约束“涉及摄像头、门锁等敏感设备时只执行明确指令不主动播报细节。”这些约束会随每次请求一起发送给模型虽然会增加一点 token 消耗但能显著提升体验和安全性。9.4 自动化联动让大模型做更高层决策接入大模型的真正价值不只是回答“现在几度”而是让它参与自动化的高层决策。例如你可以在 HA 自动化中用一句话总结家庭成员的需求然后调用 conversation 服务让模型给出执行建议。一个简单的自动调用示例# automations.yaml 示例 alias: 用 AI 总结离家前的设备状态 description: 当有人离开家时调用大模型提醒未关闭的设备 trigger: - platform: state entity_id: person.me to: away action: - service: conversation.process data: agent_id: openai_conversation text: 我现在离开了家请帮我检查是否有灯、空调或窗户设备还开着然后用一句简短的话总结给我。这个自动化触发后HA 会把当前的家庭状态快照发给大模型由模型识别出未关闭的设备并生成提示语。虽然实际触发场景有延迟受 API 响应时间影响但作为“信息摘要设备管理”的辅助工具体验已经比传统自动化做模板拼接自然很多。需要说明的是agent_id的具体取值取决于你安装的对话代理集成建议先在 HA 的开发者工具里查看conversation.process服务的参数再复制到自动化中。9.5 生产环境与长期维护如果你决定把大模型接入作为家庭环境长期运行的功能建议遵循以下原则不要把 API Key 明文写在配置文件里提交到公开仓库。HA 配置目录通常是私有目录但如果你有配置同步工具建议使用环境变量或 secrets.yaml 管理密钥。升级 HA 或自定义集成之前先备份配置目录。大版本升级后对话代理集成可能需要重新配置。关注使用的第三方自定义对话集成的更新动态。隔几个月不更新HA 升级后很可能出现兼容性问题。网络质量是体验下限。HA 调用云端大模型依赖外网访问部署位置在外网访问不通的环境中建议考虑本地可访问的模型部署方案或在安全合规的前提下选择可达的模型服务。10. 总结与下一步实践方向从整体来看HomeAssistant 接入 ChatGPT 和 DeepSeek 的路径已经非常清晰。ChatGPT 走官方集成胜在稳定省心DeepSeek 走 OpenAI 兼容方案胜在成本更低、模型中文能力也不错。两者共用的核心其实是同一条链路HA 的设备抽象 Assist 管道 LLM 的对话与工具调用能力。这篇文章帮你梳理清楚了三件事一是 HA 接入大模型的数据流和核心概念二是两种主流模型的配置步骤和验证方法三是隐私、成本和长期维护层面的工程建议。你现在需要做的不是急着把所有设备都暴露给模型而是先安装一个对话集成接上一两个不敏感的灯或传感器测试一轮完整的“提问—分析—控制—回复”流程。接下来值得深入的方向有三个一是研究 HA 的 Assist 自定义句子和意图识别机制让本地意图解析与大模型配合使用二是尝试本地部署小参数模型作为低成本备选三是探索大模型与 HA 多模态能力的结合比如把摄像头图像交给视觉模型判断。如果你从零开始建议先跑通本文第 5 章或第 6 章的任意一条路径剩下的就交给日常使用中的真实反馈来驱动迭代。