Home Assistant 接入 DeepSeek：OpenAI 兼容协议配置与设备控制实践

在实际的智能家居项目中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 CorePython 环境自定义配置目录需要自己管理运行环境和依赖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 集成接入 DeepSeek3.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_urlAPI 服务地址以平台文档为准不同服务端点决定能否调用成功同样决定能否调用成功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 UnauthorizedAPI Key 错误、被禁用或格式不对查看日志中 Authorization 头用 curl 验证重新创建 Key确认secrets.yaml中无多余空格402 Payment Required账户余额不足登录开放平台查看余额充值后再调用或配置降级策略404 Not Foundbase_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 面板中的基础对话再把自动化调用、成本控制和权限安全逐步补上避免一开始就堆复杂功能导致排查困难。