在实际的智能家居项目中，Home Assistant 通常已经解决了“设备接入、自动化、统一控制”的问题，但“用自然语言和家里对话”这件事，长期以来只能靠固定的语音指令模板完成。把 ChatGPT、DeepSeek 这类 AI 大模型接入 Home Assistant 之后，对话能力会发生本质变化：用户可以说“家里现在适合开哪个房间的灯”“把客厅调到温馨一点”，AI 会结合当前设备状态给出回复，甚至直接调用设备服务。本文会围绕 Home Assistant 接入 AI 大模型这条主线，重点说明基于 OpenAI 兼容协议接入 DeepSeek 的完整过程，包括环境准备、YAML 配置、设备控制、日志排查和生产环境建议。
很多刚接触这个方向的开发者会把“接入大模型”理解成“给 Home Assistant 装一个聊天框”。实际上，Home Assistant 真正需要的是 conversation agent 能力：它允许外部大模型以标准方式接收用户文本、识别用户意图、返回回复文本或触发设备服务。ChatGPT 官方服务和 DeepSeek 这类兼容服务都能通过 OpenAI 兼容接口完成这个过程，区别主要在 API 地址、模型名和密钥管理上。理解这条链路后，配置就不再是抄代码，而是一套可以自己排查和扩展的工程能力。
1. 先理解 Home Assistant 接入大模型到底在解决什么问题
1.1 conversation agent 是接入大模型的核心入口
Home Assistant 内置的 Assist 功能专门负责“对话式交互”。在 Assist 的体系里，conversation agent 是处理用户文本的代理模块：它接收原始文字，经过意图识别、槽位提取、设备调用等流程，最终返回一段可读文本或执行结果。
在默认情况下，Assist 使用的是本地内置 agent，它能识别的是有限的固定指令，例如“打开客厅灯”。一旦用户说出“客厅灯太亮了，帮我调暗一点并且过十五分钟再关闭”，本地规则基本无法处理。接入大模型后，conversation agent 可以把整段文本交给大模型，由大模型生成回复，同时在回复中使用工具调用语义，Home Assistant 再把这些语义转换为实际设备服务。这就是接入 ChatGPT、DeepSeek 之后的核心价值：从“命令匹配”升级为“理解与生成”。
1.2 ChatGPT 与 DeepSeek 在接入方式上的差异
在 Home Assistant 社区中，OpenAI 集成是最常用的官方 AI 接入方式。它原生支持 OpenAI 官方接口，也允许通过base_url指向任意兼容 OpenAI 协议的服务端点。这让 DeepSeek 这类兼容服务可以复用同一套集成配置，不需要自己维护完整插件。
需要特别区分两个概念：
- ChatGPT 订阅账号：用于网页版或官方 App 对话，不提供可用于第三方集成的 API Key。
- OpenAI API Key：在 OpenAI 平台创建，面向开发者，用于程序调用。Home Assistant 要接的是 API Key，不是网页账号。
DeepSeek 的接入方式与 OpenAI API 非常相似，同样需要注册开放平台、创建 API Key、调用/chat/completions接口，只是 API 地址和模型名不同。因此在 Home Assistant 中，最稳妥的做法是把 DeepSeek 当作“兼容 OpenAI 协议的服务”来配置。
1.3 两种常见接入路径对比
| 接入路径 | 实现方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|
| 官方 OpenAI 集成 | 在configuration.yaml或 UI 中填写api_key、base_url、model | 配置简单，自动支持 Assist、媒体播放器、设备上下文 | 依赖 HA 内置逻辑，高级工具调用需要版本支持 | 大多数用户，推荐优先尝试 |
| 自定义集成 / REST API | 自己写集成或使用rest_command调用大模型接口，再结合conversation平台注册 agent | 完全可控，可以自定义 prompt、工具、降级逻辑 | 开发量大，需要维护 | 需要特定功能或私有化部署 |
对大多数项目来说，第一条路径已经足够。本文接下来的配置也以官方 OpenAI 集成接入 DeepSeek 为例子。
2. 环境准备与前置条件确认
2.1 Home Assistant 版本与安装方式
接入 AI 大模型之前，先确认 Home Assistant 的版本和安装方式。以下配置在较新的稳定版本中可用，但界面文案和字段位置可能随版本变化，落地前应以当前安装版本的官方文档为准。
实际操作建议：
- 打开 Home Assistant 的“设置 - 关于”，确认当前版本。
- 确认版本在正式发布通道，不要使用长期滞后的分支。
- 确认 Home Assistant 能够访问外网，因为大模型 API 属于云端服务，需要 HTTPS 出站流量。
- 如果使用 Docker 安装，确认容器 DNS 和出网策略正常。
Home Assistant 的安装方式会影响后续配置路径：
| 安装方式 | 配置文件位置 | 注意事项 |
|---|---|---|
| Home Assistant OS | /config/configuration.yaml | 可直接通过 Samba 或“加载项”编辑 |
| Home Assistant Container | 挂载目录下的configuration.yaml | 修改后需要重启容器 |
| Home Assistant Core（Python 环境） | 自定义配置目录 | 需要自己管理运行环境和依赖 |
2.2 获取 DeepSeek API Key
要接入 DeepSeek，首先需要注册 DeepSeek 开放平台账号并创建 API Key。这个 Key 是程序调用大模型接口的身份凭证。创建时的步骤大致为：
- 登录 DeepSeek 开放平台。
- 在 API Keys 页面创建一个新的 Key。
- 复制保存 Key，关闭页面后通常无法查看完整内容。
- 根据平台要求完成充值或余额确认，因为 API 调用会按 token 计费。
创建之后不要直接把 Key 写到博客或公开仓库中。在 Home Assistant 中推荐放到secrets.yaml文件里，避免配置文件和自动化代码一起提交到 Git 仓库后泄露。
2.3 用 curl 验证 API 可访问
在配置 Home Assistant 之前，先用命令行直接验证 DeepSeek API 是否可访问，这样可以把“API 本身的问题”和“Home Assistant 配置的问题”分离开来。
curl https://api.deepseek.com/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-在这里填写你的API Key" \ -d '{ "model": "deepseek-chat", "messages": [ { "role": "user", "content": "你好，请用一句话介绍你自己" } ] }'正常响应会返回一段 JSON，其中包含choices数组和模型生成的content内容。如果这一步出现 401 或 404，说明 API Key、模型名或 API 地址存在问题，需要先在命令行修复，再回到 Home Assistant 中配置。curl 验证的好处是所见即所得，它能直接排除 Home Assistant 版本、集成字段和网络策略的干扰。
3. 配置 OpenAI 集成接入 DeepSeek
3.1 在 configuration.yaml 中声明 OpenAI 集成
Home Assistant 的 OpenAI 集成支持通过 YAML 配置。在configuration.yaml中添加以下内容：
# configuration.yaml openai: api_key: !secret deepseek_api_key base_url: https://api.deepseek.com model: deepseek-chat max_tokens: 500 temperature: 0.7 top_p: 1这段配置的含义：
api_key引用secrets.yaml中保存的密钥，不要在配置文件里直接写明文。base_url指向 DeepSeek API 地址，常见为https://api.deepseek.com。不同版本可能需要带/v1或不带，要按 DeepSeek 官方文档确定。model指定使用的模型名。DeepSeek 开放平台常见的模型名有deepseek-chat和deepseek-reasoner，具体以平台文档为准。max_tokens限制单次回复的最大输出 token 数，避免回复过长消耗太多 token。temperature控制随机性，家庭自动化场景推荐 0.7 以下，避免输出飘忽不定。top_p与 temperature 配合使用，默认 1 即可。
修改configuration.yaml后，在“开发者工具 - YAML”中检查配置，或者直接重启 Home Assistant。如果 YAML 缩进错误，Home Assistant 会拒绝加载配置并写入日志。
3.2 在 secrets.yaml 中保存 API Key
在configuration.yaml同目录下创建或编辑secrets.yaml：
# secrets.yaml deepseek_api_key: sk-在这里填写你的真实API Key保存后确认文件权限。如果使用 Home Assistant OS，建议通过文件编辑器或 Samba 修改；如果使用容器，需要注意容器用户对文件的读取权限。
3.3 关键参数说明
| 参数 | 作用 | 推荐值 | 调大影响 | 调小影响 |
|---|---|---|---|---|
api_key | 调用 API 的身份凭证 | 真实 Key | 无 | 无 |
base_url | API 服务地址 | 以平台文档为准 | 不同服务端点决定能否调用成功 | 同样决定能否调用成功 |
model | 使用的模型名称 | deepseek-chat | 模型越强，理解和推理越好，成本也越高 | 模型越轻，响应越快，但复杂指令可能理解不准确 |
max_tokens | 单次回复最大 token 数 | 300 到 800 | 能生成更长回复，成本增加 | 回复更短，可能被截断 |
temperature | 回复随机性 | 0.5 到 0.7 | 回复更发散 | 回复更稳定、更保守 |
top_p | 候选词概率累计阈值 | 1 | 更多样 | 更集中 |
这里要特别注意max_tokens并不是最大整体对话长度，而是模型单次回复的最大输出长度。Home Assistant 会把设备列表、对话历史等作为上下文发送给模型，这部分输入也计入 token 消耗。
3.4 通过 UI 添加集成
如果不想写 YAML，也可以在“设置 - 设备与服务 - 添加集成”中搜索 OpenAI 或 OpenAI Conversation，然后填写 API Key 等字段。不同版本的 Home Assistant 对base_url的暴露程度不同，如果 UI 表单里没有base_url字段，可以继续使用 YAML 方式配置。
无论是 UI 还是 YAML，添加完成后会在“设备与服务”列表中看到一个对话实体，实体名通常是conversation.openai或conversation.deepseek。这个实体名在后续自动化调用、Assist 选择和 prompt 配置中都会用到。
4. 让对话 AI 真正控制家居设备
4.1 在 Assist 对话面板中直接使用
配置完成并重启 Home Assistant 后，打开主页右下角的 Assist 对话图标，在对话输入框中输入一段自然语言请求，选择刚才创建的对话 agent，然后发送。
例如输入：
晚上十点之后把客厅灯调暗到 30%，并且播放轻音乐如果大模型能正确理解，Home Assistant 会把其中的意图转换成可执行的服务调用，比如light.turn_on配合亮度参数、media_player.play_media等。这个过程不需要用户自己编写任何自动化规则，模型的工具调用能力会帮助完成设备操作。
第一次使用时建议从简单指令开始，比如“打开客厅灯”“关闭卧室空调”，先确认设备调用是否成功，再逐步增加复杂条件。
4.2 实体暴露与调用权限
控制设备的前提是 Home Assistant 知道要操作哪些实体。在 Assist 的实体暴露配置中，可以选择哪些实体允许被对话 agent 控制。默认情况下，部分实体可能没有暴露。
配置路径大致为：
- 打开“设置 - 语音助手 - Assist”。
- 找到对话 agent 关联的实体暴露配置。
- 勾选允许控制设备，例如灯、开关、空调、窗帘等。
- 对门锁、电热设备、燃气阀门等高风险实体，建议不要暴露给大模型。
这一步非常关键。大模型能正确识别设备名称，不代表它一定能做出安全判断。把门锁也暴露给大模型后，一旦 prompt 被注入或用户误触，后果会非常严重。安全边界应该在实体暴露层面提前设好。
4.3 在自动化中主动调用大模型
除了用户在 Assist 面板中主动发起对话，还可以在 automation 中调用conversation.process服务，让 Home Assistant 在特定条件下主动向大模型提问。
例如每天早晨固定时刻让 AI 汇总当前设备状态：
# automations.yaml automation: - alias: "早晨汇总家中设备状态" trigger: - platform: time at: "08:00:00" action: - service: conversation.process data: agent_id: conversation.openai text: > 请根据当前设备状态，用三句话总结家中哪些灯还开着、 空调是否在运行，并给出建议。这里的agent_id要改成实际集成生成的实体名。如果不确定，可以在“开发者工具 - 状态”中搜索conversation进行确认。
这种模式适合做定时汇报、离家后的安全检查、能耗分析提示等场景。在自动化中调用大模型时，要注意不要设置过短的触发间隔，否则会持续产生 API 调用费用。
4.4 用系统提示词约束 AI 行为
OpenAI 集成允许自定义 prompt，也就是系统提示词。系统提示词能显著影响大模型的行为方式。一个适合家庭场景的 prompt 示例：
openai: api_key: !secret deepseek_api_key base_url: https://api.deepseek.com model: deepseek-chat prompt: | 你是家庭智能助手，负责帮助用户管理家中设备。 回答要求： 1. 使用简短、自然的日常语言。 2. 如果不确定用户意图，先向用户确认。 3. 不要主动操作门锁、燃气、电热等高危设备。 4. 回答中不要输出设备原始 ID，使用用户容易理解的名称。 5. 如果用户请求无法完成，直接说明原因，不要编造执行结果。好的 prompt 能减少误操作，也能控制回复长度。实际项目中可以根据家庭成员的表达习惯不断调整。prompt 修改后需要重启 Home Assistant 才会重新加载。
5. 运行验证与日志排错
5.1 正常调用链路与预期结果
配置完成后，可以通过一段简单对话验证调用链路是否正常。在 Assist 面板输入“现在客厅温度怎么样”这类问题，正常流程为：
- Home Assistant 收集当前设备状态。
- 将设备状态组成上下文，连同用户文本发送到 DeepSeek API。
- DeepSeek 返回自然语言回复，或者触发工具调用。
- Home Assistant 展示回复，并在必要时执行设备服务。
查看日志时，如果看到类似Error doing LLM conversation的错误，说明 Home Assistant 和大模型服务之间出现了调用异常。正常情况下不会出现这类错误，API 调用完成后日志中会有对应记录。
5.2 常见错误现象与处理方案
| 错误现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| 401 Unauthorized | API Key 错误、被禁用或格式不对 | 查看日志中 Authorization 头；用 curl 验证 | 重新创建 Key，确认secrets.yaml中无多余空格 |
| 402 Payment Required | 账户余额不足 | 登录开放平台查看余额 | 充值后再调用，或配置降级策略 |
| 404 Not Found | base_url路径不对，或模型名不存在 | 用 curl 直接调用/chat/completions测试 | 按文档修正 API 地址和模型名 |
| 429 Too Many Requests | 触发限流或并发过高 | 查看响应头Retry-After | 降低调用频率，增加重试时间 |
| 500 / 502 / 超时 | 服务端波动、网络不稳定或响应生成过慢 | 查看日志完整错误；curl 测试 | 延长超时时间，稍后重试 |
| 模型不存在 | model名称写错 | 调用/models接口查看可用模型 | 改为平台支持的模型名 |
5.3 按顺序排查配置问题
遇到接入失败时，不建议直接反复重启 Home Assistant，而是按以下顺序排查：
- 查看 Home Assistant 日志，确认错误发生在“集成初始化”还是“调用 API”阶段。
- 检查
configuration.yaml缩进和字段名，错误缩进会导致配置整个不加载。 - 检查
secrets.yaml中的 Key 是否存在多余引号或空格。 - 用 curl 验证 API 地址、Key、模型名是否可用，这能直接排除外部服务问题。
- 确认 Home Assistant 能访问外网，容器环境可先执行
curl或wget测试出网。 - 确认 Home Assistant 版本对 OpenAI 集成的字段支持情况，必要时查看官方集成文档。
- 如果配置在 UI 中添加，删除集成后重新添加，观察提示信息。
注意：不要只验证“配置加载成功”，还要实际发一段对话验证模型返回。很多配置问题要到第一次真实调用时才会暴露。
5.4 模型返回不稳定时到哪里查
如果大模型能返回结果，但设备控制经常失败，需要把问题拆分来看：
- 如果返回文本正常，但设备没有变化，可能是实体未暴露给 Assist，或者设备服务参数不对。
- 如果设备执行了但不完全符合要求，说明模型对实体名称或状态理解不准，需要在 prompt 中补充更明确的设备说明。
- 如果连续出现不同结果，可能是 temperature 设置过高，建议调低到 0.3 到 0.5。
设备控制相对稳定后，再处理复杂逻辑，不要一开始就让模型处理多设备联动。
6. 生产环境使用建议与扩展方向
6.1 控制 token 成本和调用频率
接入大模型后，成本控制可能成为日常运营的一部分。实用方法包括：
- 将
max_tokens控制在合理范围，家庭日常问答通常 300 到 500 足够。 - 不要在自动化中高频调用大模型，固定触发频率要设计成分钟级以上。
- 对话历史会随轮次增长，长会话后 token 消耗明显上升，可定期清空或设计简短对话。
- 如果 DeepSeek 平台提供余额预警或额度限制，建议提前配置，避免额度耗尽后自动化静默失败。
- 对固定格式的请求，例如“检查所有灯是否关闭”，可以先用本地自动化完成，只有无法规则化时才调用大模型。
6.2 权限与安全边界
在家庭自动化环境中，权限设计比功能开发更重要。实际部署时建议：
- 严格限制实体暴露范围，高风险设备不要出现在大模型上下文中。
- 不要在单纯文本对话中携带密码、家庭住址、证件号等敏感信息，因为设备状态和用户消息都会发送到模型 API。
- API Key 必须通过
secrets.yaml或环境变量管理，不要硬编码。 - 对外提供 webhook 或语音入口时，确认调用来源可信，避免外部人员向对话 agent 发送恶意指令。
- 定期查看调用日志，关注异常高频调用或异常文本内容。
6.3 降级与异常兜底
大模型是可用性较强的服务，但不是永远可用。生产环境必须考虑降级方案。
可以设计一个 fallback：
- 当 API 调用失败时，由本地默认 conversation agent 处理。
- 当超时或网络异常时，返回固定提示“智能助手暂时不可用，请稍后再试”，而不是让用户陷入长时间等待。
- 在自动化中调用大模型时，在
action里加入retry或错误检测逻辑，失败后进入预设的本地指令分支。
例如在 automation 中可以用condition和choose判断对话结果，但最简单的做法还是把失败处理放在模板或脚本里面。实际项目中建议先跑通“成功路径”，再逐步加入“失败路径”。
6.4 扩展方向：从对话到自动化智能体
接入 DeepSeek 或 ChatGPT 只是开始。后续可以考虑以下方向：
- 使用 DeepSeek 的推理模型处理更复杂的决策，例如根据天气、电价、家庭成员作息制定空调节能策略。
- 将 Function Calling 能力封装成自定义工具，让大模型不仅控制设备，还能查询天气、拉取日历、记录事件。
- 在局域网内部署本地模型，通过 Ollama 或 vLLM 提供 OpenAI 兼容接口，减少对云端服务的依赖并保护隐私。
- 结合 TTS 引擎把大模型回复转为语音播报，让家庭助手具备完整的语音交互体验。
注意：本地模型对硬件要求较高，部署前要先确认设备内存和显卡资源，不要为了“私有化”而牺牲家庭服务的稳定性。
在智能家居里，大模型接入最有价值的地方不是“能聊天”，而是“能根据上下文做判断并安全地执行”。配置好 API 地址和模型名只是第一步，真正决定体验的是实体暴露范围、系统提示词、调用频率和降级策略。建议新手先跑通 Assist 面板中的基础对话，再把自动化调用、成本控制和权限安全逐步补上，避免一开始就堆复杂功能导致排查困难。
