智能家居发展到今天很多玩家已经不再满足于“灯按时开关”“温度过高自动开空调”这类固定逻辑自动化。真正让 Home Assistant简称 HA变得“聪明”的是让它能理解自然语言、能根据家里实时状态生成回复和建议。近几年 ChatGPT、DeepSeek 这类大模型 API 越来越成熟而 HA 恰好是一个设备接入和自动化的中枢把两者结合起来就可以打造一个真正能对话、能思考的智能家居大脑。本文将围绕“Home Assistant 接入 ChatGPT / DeepSeek 大模型”这条主线从原理讲到落地提供两种可复现的接入方式一种是适合快速验证的shell_command方案另一种是更适合日常使用的python_script封装方案。同时会补充自动化调用、对话交互、常见报错排查和工程安全建议。无论你用的是 HAOS、Docker 还是 Core 方式安装只要会改configuration.yaml都能跟着操作。1. 背景为什么要在 Home Assistant 中接入大模型Home Assistant 的自动化能力很强但传统自动化有一个明显瓶颈所有规则都是预先写死的。比如你需要手动定义“当湿度大于 70% 时打开除湿机”这个逻辑本身没有任何智能成分。它不会根据天气预报、家庭成员习惯、当前时间段综合判断也不会生成一段自然语言来解释它为什么要这样做。接入 AI 大模型之后HA 可以实现下面几类能力自然语言交互用户可以说“我今天下班后想去跑步帮我看看合适吗”HA 可以通过大模型理解意图并结合天气和设备状态生成回复。动态内容生成比如每天早上生成一份“天气通勤家庭设备状态”的简报再用通知推送到手机。非规则型决策建议当家里检测到有人活动时让大模型结合温度、湿度、空气质量给出建议而不是只执行一条固定的自动化。语音助手大脑HA 自带的 Assist 语音助手支持配置对话代理接入大模型后语音交互的准确度和自然度会明显提升。为什么示例中同时提到 ChatGPT 和 DeepSeek因为大多数大模型平台目前都提供了 OpenAI 兼容接口也就是说请求路径、请求体格式非常接近。你只需要更换 API 地址、模型名和 API Key就能在不同大模型之间切换。DeepSeek 在国内可以直接访问接入成本低所以本文的完整代码示例会优先以 DeepSeek 为例ChatGPTOpenAI的接入方式也完全兼容只需替换相关参数即可。2. 技术选型与整体方案设计在 Home Assistant 中调用大模型 API常见有下面几种方案。实现方式难度适用场景依赖shell_command低快速测试 API 连通性、写一次性脚本HA 内置要求系统有 curlpython_script中处理复杂逻辑、回写 HA 实体、发送通知HA 内置标准库即可pyscript中高更灵活的 Python 服务开发需要安装 pyscript 插件社区 conversation 集成低直接让 Assist 语音助手接入大模型需要安装第三方集成从稳定性、可维护性、灵活性三个角度综合考虑比较推荐下面这条落地路径先用curl或shell_command验证 API Key 和模型名是否可用。再用python_script把大模型调用封装成一个 HA 服务。然后在自动化里调用这个服务把回复写入input_text实体或者发送到手机通知。如果后续想接入 Assist 语音助手再考虑安装社区 conversation 集成。整体数据流可以概括为HA 自动化 / 前端输入 / 语音助手 ↓ HA 内置服务python_script / shell_command ↓ 发起 HTTPS 请求OpenAI 兼容接口 ↓ ChatGPT / DeepSeek / 其他大模型 ↓ 返回 JSON 文本 ↓ 写入 input_text 实体 / 发送通知 / TTS 播报这种设计的好处是核心逻辑集中在 Python 脚本里排查问题、替换模型、增加参数都方便。3. 环境准备与版本说明本文示例需要的环境并不复杂先统一说明一下Home Assistant 安装方式HAOS、Supervised、Docker、Core 都可以配置目录统一为/config。如果你用的是 HAOS推荐用自带 Samba 或 File editor 插件编辑配置。Home Assistant 版本本文以常见稳定版为例不同版本界面细节可能略有差异但配置和代码思路基本一致。大模型 API示例使用 DeepSeek API模型名为deepseek-chat。如果你接入 OpenAI模型名可使用gpt-4o-mini这类常见模型但具体以你账号可用的模型列表为准。Python 环境python_script不需要额外安装第三方依赖示例代码使用 Python 标准库urllib避免因为 HA 环境中缺少requests导致运行失败。命令行工具shell_command示例依赖系统自带的curl常见 HA 镜像一般自带。有一点需要提前确认调用大模型 API 会产生费用不同平台计费方式不同同时如果你使用的是 OpenAI 服务请确保你的账号状态、网络环境符合 OpenAI 服务条款与当地法律法规。国内用户可优先选择 DeepSeek 这类可以直接访问的平台整体更省事。4. 核心思路HA 中调用大模型 API 的几种方式在编写实战之前先把 HA 中几种可选方案的适用场景说清楚避免你复制完代码后仍然不理解为什么这样写。4.1 方式一shell_commandshell_command是 HA 内置的集成方式它允许你在configuration.yaml里定义一个命令然后在开发者工具或自动化中调用。最简单的模型请求本质上就是一个 HTTP POST所以用curl就能直接完成。这种方式的优点是配置简单、不需要写代码文件适合验证 API 是否连通。缺点是命令拼接容易遇到引号转义问题复杂入参比如多轮对话、JSON 数组不好处理返回结果不适合直接写入实体。所以它更适合做“连通性测试”而不是作为长期方案。4.2 方式二python_scriptpython_script同样是 HA 内置能力。在configuration.yaml中启用python_script:后你只需要把.py文件放在/config/python_scripts/目录下文件名就是服务名。例如创建python_scripts/deepseek_chat.py后HA 中会自动出现python_script.deepseek_chat服务。脚本可以通过全局变量data拿到服务调用时传入的参数通过hass.services.call调用其他 HA 服务通过logger.error输出日志。相比shell_command它更适合组装复杂的 JSON 请求体对返回结果做解析和异常处理把回复写入input_text、发送通知、TTS 播报等。4.3 方式三社区 conversation 集成如果你不想写代码只想让 HA 的 Assist 语音助手直接与大模型对话可以在社区集成库中搜索支持 OpenAI 兼容 API 的 conversation 集成。安装后在 HA 的语音助手配置里把对话代理切换成这个集成填入 API Key 和模型名即可。由于这类集成迭代很快不同版本配置项可能不同这里不展开界面细节。只要理解一个原则它们底层也是在调用 OpenAI 兼容接口只是帮你把“对话代理”这个 HA 原生接口实现了所以在语音助手入口可以直接选择。理解了这三种方式下面进入实战。5. 实战一使用 shell_command 快速调用 DeepSeek API这个章节的目标是先用最轻量的方式验证 API 是否可用并建立对请求格式的直观认识。5.1 准备 API Key登录 DeepSeek 开放平台在控制台中创建一个 API Key。注意复制后立刻保存不要泄露给任何人也不要提交到 Git 仓库。本文中的YOUR_API_KEY都需要替换成你自己的 Key。5.2 编写 shell_command 配置在/config/configuration.yaml中追加以下内容shell_command: deepseek_shell_chat: - curl -s -X POST https://api.deepseek.com/chat/completions -H Content-Type: application/json -H Authorization: Bearer YOUR_API_KEY -d {model:deepseek-chat,messages:[{role:user,content:{{ prompt }}}],temperature:0.7}这里需要注意几点deepseek_shell_chat是服务后缀之后调用服务名是shell_command.deepseek_shell_chat。{{ prompt }}是 HA 模板变量调用服务时传入的prompt参数会替换到该位置。 -是 YAML 折叠块表示把多行合并成一个字符串方便阅读。model使用deepseek-chat这是 DeepSeek 面向通用对话场景的模型。修改配置后在 HA 中检查配置并重启 Home Assistant。5.3 测试调用打开“开发者工具 → 服务”选择shell_command.deepseek_shell_chat服务数据填{ prompt: 你好请用一句话介绍你自己 }调用后返回的 JSON 会出现在 HA 的日志中。正常情况能看到类似下面的内容{ id: chatcmpl-xxx, object: chat.completion, model: deepseek-chat, choices: [ { index: 0, message: { role: assistant, content: 你好我是 DeepSeek一个由深度求索公司开发的 AI 助手。 } } ] }如果日志提示命令不存在或报错先回到 HA 日志页面查看具体错误信息。5.4 切换到 ChatGPT / OpenAI如果你要测试 OpenAI只需要把 URL 和模型名换掉shell_command: openai_shell_chat: - curl -s -X POST https://api.openai.com/v1/chat/completions -H Content-Type: application/json -H Authorization: Bearer YOUR_OPENAI_API_KEY -d {model:gpt-4o-mini,messages:[{role:user,content:{{ prompt }}}],temperature:0.7}再次强调具体可用模型名要以你的 OpenAI 账号为准。5.5 shell_command 的局限性虽然上面的命令可以成功调用但你会发现它存在几个问题prompt内容一旦包含单引号、双引号或换行curl 的 JSON 字符串很容易被截断。返回结果只能通过日志查看不能直接存到实体里。没有异常处理机制网络超时或 API 报错时日志可读性差。因此真正用于日常自动化时更推荐使用python_script来封装。6. 实战二用 python_script 封装大模型调用服务这一节是文章的核心我们会实现一个可以复用的 HA 服务调用 DeepSeek / ChatGPT API把回复写入input_text实体并可选发送通知。6.1 开启 python_script 并创建文本实体在configuration.yaml中追加python_script: input_text: deepseek_result: name: DeepSeek 回复 max: 4096说明python_script:启用 HA 内置的 Python 脚本功能。input_text.deepseek_result用于保存模型回复前端可以直接显示。重启 HA 后在“开发者工具 → 状态”里应该能看到input_text.deepseek_result。6.2 编写 python 脚本在/config/python_scripts/目录下新建文件deepseek_chat.py内容如下# 文件路径python_scripts/deepseek_chat.py # 通过 OpenAI 兼容接口调用大模型支持 DeepSeek / ChatGPT 等 import json import os import urllib.request # 从服务数据中读取参数 prompt data.get(prompt, 你好请用一句话介绍你自己。) model data.get(model, deepseek-chat) temperature data.get(temperature, 0.7) max_tokens data.get(max_tokens, 1024) notify_service data.get(notify_service, ) # 不同模型对应的 Endpoint 配置 # 如果你使用的模型不在列表里可按相同格式补充 MODEL_ENDPOINTS { deepseek-chat: { url: https://api.deepseek.com/chat/completions, model: deepseek-chat, }, deepseek-reasoner: { url: https://api.deepseek.com/chat/completions, model: deepseek-reasoner, }, gpt-4o-mini: { url: https://api.openai.com/v1/chat/completions, model: gpt-4o-mini, }, } endpoint MODEL_ENDPOINTS.get(model) if endpoint is None: logger.warning(未知模型 %s使用默认 deepseek-chat, model) endpoint MODEL_ENDPOINTS[deepseek-chat] model deepseek-chat # 优先从环境变量中读取 API Key避免把密钥写死在脚本中 api_key os.environ.get(DEEPSEEK_API_KEY, ) or os.environ.get(OPENAI_API_KEY, ) if not api_key: # 也可以临时通过服务参数传入适合快速测试 api_key data.get(api_key, ) if not api_key: logger.error(未配置 API Key请在环境变量或服务参数中传入) reply API Key 未配置请检查环境变量或服务参数。 else: payload { model: endpoint[model], messages: [ { role: system, content: 你是一个智能家居 AI 助手。请用简洁、友好、准确的中文回答用户问题。, }, {role: user, content: prompt}, ], temperature: temperature, max_tokens: max_tokens, } headers { Content-Type: application/json, Authorization: Bearer api_key, } req urllib.request.Request( endpoint[url], datajson.dumps(payload).encode(utf-8), headersheaders, methodPOST, ) try: with urllib.request.urlopen(req, timeout30) as resp: result json.loads(resp.read().decode(utf-8)) reply result[choices][0][message][content] except Exception as e: logger.error(大模型 API 调用失败: %s, e) reply 抱歉我暂时无法连接大模型服务请稍后重试。 # 写入 input_text 实体方便在前端展示 hass.services.call(input_text, set_value, { entity_id: input_text.deepseek_result, value: reply, }) # 如果传入了 notify_service直接把结果推送到手机或音箱 if notify_service: hass.services.call(notify, notify_service, { title: AI 助手回复, message: reply, })这段脚本有几个设计点说明一下使用data.get读取调用服务时传入的参数并为每个参数提供默认值。MODEL_ENDPOINTS字典用模型名映射 API 地址切换模型时不需要修改脚本主流程。优先从环境变量中读取 API Key实在没有才允许通过服务参数传入这样可以避免 Key 被写死到脚本文件。请求体使用 UTF-8 编码防止中文乱码。异常捕获后返回固定提示语避免服务直接报错导致自动化中断。通过hass.services.call(input_text, set_value, ...)写入实体比直接修改状态更符合 HA 的设计。可选的通知服务会在收到回复后直接推送省去在自动化中写delay等待。6.3 调用封装好的服务重启 HA 后在“开发者工具 → 服务”中选择python_script.deepseek_chat服务数据可以填{ prompt: 帮我规划一份今晚在家锻炼 30 分钟的计划不需要器材, model: deepseek-chat, temperature: 0.7, max_tokens: 800 }调用后input_text.deepseek_result的状态会变成模型返回的文本。如果你传入了notify_service比如mobile_app_iphone手机通知也会收到同样的内容。6.4 在自动化中生成定期简报封装成服务后自动化调用就很简洁了。下面是一个每天早上 8 点生成天气提醒的示例automation: - alias: 每天早上生成 AI 天气简报 trigger: platform: time at: 08:00:00 action: - service: python_script.deepseek_chat data: prompt: 请根据以下信息生成一段今天早上的天气和出行提示要求语言亲切 当前室外温度{{ states(sensor.outdoor_temperature) }}°C 当前天气{{ states(weather.forecast_home) }} 提醒用户注意穿衣和出行。 model: deepseek-chat notify_service: mobile_app_iphone这里需要注意sensor.outdoor_temperature、weather.forecast_home、mobile_app_iphone都是示例实体和服务你要替换成自己 HA 中实际存在的实体。prompt 中使用了 HA 模板语法自动化执行时会先渲染成真实设备状态再传给脚本。这样每天早上的通知内容就不再是固定文案而是结合当前设备状态的动态内容。7. 进阶对话交互与自动化场景有了基础服务之后可以进一步把大模型接入到更贴近“对话”的场景。7.1 接入 Assist 语音助手如果你希望说一句话就能得到大模型回复可以安装社区提供的 conversation 集成。这些集成通常会提供一个对话代理你需要在 HA 的语音助手配置中把代理切换成该集成并填入 API Key、模型名等参数。配置完成后在 HA 的对话框、App 语音入口甚至实体音箱上都可以直接与大模型对话。这种方式体验最接近“智能家居大脑”但因为第三方集成更新频繁建议安装后以集成仓库的说明为准。7.2 使用 pyscript 开发更灵活的服务pyscript 是一个第三方插件允许你用 Python 直接写 HA 自动化逻辑并且可以更方便地注册自定义服务。如果你已经安装了 pyscript可以把刚才的python_script逻辑改写成 pyscript 服务还可以在脚本中自由读取 HA 状态、调用更多服务。pyscript 也能实现类似功能# 这段代码只是思路示意具体方法名以你安装的 pyscript 版本为准 import json import urllib.request service def deepseek_ask(prompt: str ): payload { model: deepseek-chat, messages: [{role: user, content: prompt}], } req urllib.request.Request( https://api.deepseek.com/chat/completions, datajson.dumps(payload).encode(utf-8), headers{ Content-Type: application/json, Authorization: Bearer YOUR_API_KEY, }, ) with urllib.request.urlopen(req, timeout30) as resp: result json.loads(resp.read().decode(utf-8)) reply result[choices][0][message][content] # 将结果发送到手机通知或通过 TTS 播报 notify.persistent_notification(titleAI 回复, messagereply)由于 pyscript 版本差异较大这段代码只用于展示思路。实际使用时应参考你安装版本的文档并优先把 API Key 放到安全的位置。7.3 把设备状态作为上下文喂给大模型大模型能否给出有价值的建议很大程度上取决于 prompt 是否包含了足够的上下文。比如下面的自动化在人进入客厅时把温度、湿度、天气状态都传给大模型让它生成生活建议automation: - alias: 客厅有人时生成生活建议 trigger: - platform: state entity_id: binary_sensor.living_room_motion to: on condition: - condition: time after: 18:00:00 before: 23:00:00 action: - service: python_script.deepseek_chat data: prompt: 今晚客厅检测到有人活动请根据下面的信息给出 2 条简短建议。 当前客厅温度{{ states(sensor.living_room_temperature) }}°C 客厅湿度{{ states(sensor.living_room_humidity) }}% 室外天气{{ states(weather.forecast_home) }}。 请控制在 80 字以内。 notify_service: mobile_app_iphone这种写法的核心是把 HA 当作家里的“感知层”大模型作为“决策和表达层”两者各司其职。7.4 在 Lovelace 前端做一个问答输入框如果你不想依赖手机通知也可以在前端放一个输入框。思路是在configuration.yaml中定义input_text.deepseek_query作为用户输入。写一个自动化监听input_text.deepseek_query的状态变化。当用户输入新文本后自动调用python_script.deepseek_chat并把结果写入input_text.deepseek_result。在 Lovelace 中用实体卡片展示这两个实体用户就能完成输入和查看回复。对应自动化如下automation: - alias: 前端输入框触发 AI 问答 trigger: - platform: state entity_id: input_text.deepseek_query action: - service: python_script.deepseek_chat data: prompt: {{ states(input_text.deepseek_query) }}需要注意为了避免输入框内容被重复触发你可以在自动化里增加条件判断新状态不是空字符串或者配合input_boolean做开关控制。8. 常见问题与排查思路接入过程中最常遇到的错误可以按下面表格快速排查。问题现象常见原因解决思路401 UnauthorizedAPI Key 错误或已失效检查环境变量/服务参数中的 Key到开放平台重新生成model not found 或 404模型名不匹配或账号无权限到官方文档确认模型名例如 deepseek-chat、gpt-4o-mini请求超时网络不通或 API 响应慢先用 curl 手动测试增大 timeout检查网络和 DNSJSON 解析失败API 返回了错误信息而不是标准回复先打印原始响应内容查看 error 字段python_script 中 import requests 报错HA 环境缺少第三方库改用标准库 urllib或在 HA 虚拟环境中 pip install中文乱码编码不一致确保请求体encode(utf-8)读取时decode(utf-8)shell_command 报错引号、模板变量转义问题先用固定文本测试复杂入参改用 python_script自动化触发后没有回复实体名写错、服务失败、通知渠道不可用先手动调用服务查看日志单独测试 notify费用增长快调用频繁、max_tokens 过大限制调用频率、使用便宜模型、增加结果缓存如果你是用shell_command方式排查问题建议先不传中文、不传长文本固定一个简单 prompt 试试curl -s -X POST https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {model:deepseek-chat,messages:[{role:user,content:hello}],temperature:0.7}这个请求如果正常返回说明 API Key、网络和模型名都没有问题问题大概率出在 HA 模板渲染或引号转义上。9. 最佳实践与工程建议把大模型接入智能家居不只是“能通”就行生产环境还需要考虑安全、费用和维护成本。9.1 API Key 安全管理永远不要把 API Key 写死在前端代码、自动化 yaml 或 Python 脚本里。推荐方式有两种在configuration.yaml中使用!secret引用secrets.yaml中的变量。在 Python 脚本中通过环境变量读取 API Key。例如secrets.yaml中可以这样写deepseek_api_key: sk-xxxxxxxx然后shell_command里使用shell_command: deepseek_shell_chat: - curl -s -X POST https://api.deepseek.com/chat/completions -H Content-Type: application/json -H Authorization: Bearer !secret deepseek_api_key -d {model:deepseek-chat,messages:[{role:user,content:{{ prompt }}}],temperature:0.7}注意!secret必须放在 HA 配置文件解析层生效Python 脚本中不能直接用所以脚本优先考虑环境变量。9.2 错误处理与兜底逻辑任何网络请求都可能失败。在 Python 脚本中除了 try-except还应提供固定兜底文案比如“抱歉我暂时无法连接大模型服务”。这样自动化流程不会因为 API 异常而中断。9.3 费用控制大模型 API 按 token 计费使用成本容易被忽略。建议做到以下几点给max_tokens设置合理上限避免模型生成超长文本。不要在自动化里频繁调用比如不要每秒轮询一次 API。对相同问题可以缓存结果避免重复请求。优先使用价格更低的模型。9.4 隐私保护调用大模型时用户输入和上下文会被发送到第三方服务。不要把门锁密码、摄像头画面描述、通话音量等高度敏感信息不加处理地放进 prompt。如果模型需要控制设备建议先输出“建议执行操作”由用户确认后再执行避免误操作。9.5 权限最小化如果后续你开发自定义集成不要使用管理员级别的长期令牌来做普通查询。尽量给 API Key 分配最小权限并且定期轮换。HA 中涉及设备控制的服务调用要增加条件判断不能完全信任模型输出。9.6 版本升级验证Home Assistant 升级频率很高python_script和shell_command这类内置能力一般比较稳定但第三方 conversation 集成可能会在大版本升级后失效。升级前先做备份升级后第一时间测试关键自动化。10. 总结与下一步学习路线本文从 Home Assistant 的实际交互痛点出发完整介绍了接入 ChatGPT、DeepSeek 等大模型 API 的方案。你可以先通过shell_command快速验证 API 连通性再用python_script封装出一个可复用的 HA 服务最后通过自动化和前端输入框把它接入日常使用。核心路径是配置 API Key → 发起 OpenAI 兼容请求 → 解析返回值 → 写入实体或发送通知 → 接入自动化。如果已经完成了这篇文章的示例下一步可以沿着几个方向继续深入学习 HA 自定义集成开发把大模型调用写成一个真正的conversation代理。研究大模型的 function calling 能力让模型能够调用 HA 服务来控制设备实现“AI 帮你关灯、调温度”的完整闭环。研究本地部署大模型方案把数据完全留在家庭内网从而更好地保护隐私。学习 prompt engineering设计更复杂的上下文模板让模型能基于家庭设备数据做更精准的判断。接入大模型只是开始真正有价值的是让它在真实家庭环境中稳定、安全、低成本地运行。建议先从“每日简报”“语音问答”这类低风险场景开始逐步积累经验后再接入设备控制逻辑。欢迎动手实践遇到问题也可以回到这篇文章对照排查。 Home Assistant接入ChatGPT/DeepSeek大模型：打造智能家居AI对话大脑
智能家居发展到今天很多玩家已经不再满足于“灯按时开关”“温度过高自动开空调”这类固定逻辑自动化。真正让 Home Assistant简称 HA变得“聪明”的是让它能理解自然语言、能根据家里实时状态生成回复和建议。近几年 ChatGPT、DeepSeek 这类大模型 API 越来越成熟而 HA 恰好是一个设备接入和自动化的中枢把两者结合起来就可以打造一个真正能对话、能思考的智能家居大脑。本文将围绕“Home Assistant 接入 ChatGPT / DeepSeek 大模型”这条主线从原理讲到落地提供两种可复现的接入方式一种是适合快速验证的shell_command方案另一种是更适合日常使用的python_script封装方案。同时会补充自动化调用、对话交互、常见报错排查和工程安全建议。无论你用的是 HAOS、Docker 还是 Core 方式安装只要会改configuration.yaml都能跟着操作。1. 背景为什么要在 Home Assistant 中接入大模型Home Assistant 的自动化能力很强但传统自动化有一个明显瓶颈所有规则都是预先写死的。比如你需要手动定义“当湿度大于 70% 时打开除湿机”这个逻辑本身没有任何智能成分。它不会根据天气预报、家庭成员习惯、当前时间段综合判断也不会生成一段自然语言来解释它为什么要这样做。接入 AI 大模型之后HA 可以实现下面几类能力自然语言交互用户可以说“我今天下班后想去跑步帮我看看合适吗”HA 可以通过大模型理解意图并结合天气和设备状态生成回复。动态内容生成比如每天早上生成一份“天气通勤家庭设备状态”的简报再用通知推送到手机。非规则型决策建议当家里检测到有人活动时让大模型结合温度、湿度、空气质量给出建议而不是只执行一条固定的自动化。语音助手大脑HA 自带的 Assist 语音助手支持配置对话代理接入大模型后语音交互的准确度和自然度会明显提升。为什么示例中同时提到 ChatGPT 和 DeepSeek因为大多数大模型平台目前都提供了 OpenAI 兼容接口也就是说请求路径、请求体格式非常接近。你只需要更换 API 地址、模型名和 API Key就能在不同大模型之间切换。DeepSeek 在国内可以直接访问接入成本低所以本文的完整代码示例会优先以 DeepSeek 为例ChatGPTOpenAI的接入方式也完全兼容只需替换相关参数即可。2. 技术选型与整体方案设计在 Home Assistant 中调用大模型 API常见有下面几种方案。实现方式难度适用场景依赖shell_command低快速测试 API 连通性、写一次性脚本HA 内置要求系统有 curlpython_script中处理复杂逻辑、回写 HA 实体、发送通知HA 内置标准库即可pyscript中高更灵活的 Python 服务开发需要安装 pyscript 插件社区 conversation 集成低直接让 Assist 语音助手接入大模型需要安装第三方集成从稳定性、可维护性、灵活性三个角度综合考虑比较推荐下面这条落地路径先用curl或shell_command验证 API Key 和模型名是否可用。再用python_script把大模型调用封装成一个 HA 服务。然后在自动化里调用这个服务把回复写入input_text实体或者发送到手机通知。如果后续想接入 Assist 语音助手再考虑安装社区 conversation 集成。整体数据流可以概括为HA 自动化 / 前端输入 / 语音助手 ↓ HA 内置服务python_script / shell_command ↓ 发起 HTTPS 请求OpenAI 兼容接口 ↓ ChatGPT / DeepSeek / 其他大模型 ↓ 返回 JSON 文本 ↓ 写入 input_text 实体 / 发送通知 / TTS 播报这种设计的好处是核心逻辑集中在 Python 脚本里排查问题、替换模型、增加参数都方便。3. 环境准备与版本说明本文示例需要的环境并不复杂先统一说明一下Home Assistant 安装方式HAOS、Supervised、Docker、Core 都可以配置目录统一为/config。如果你用的是 HAOS推荐用自带 Samba 或 File editor 插件编辑配置。Home Assistant 版本本文以常见稳定版为例不同版本界面细节可能略有差异但配置和代码思路基本一致。大模型 API示例使用 DeepSeek API模型名为deepseek-chat。如果你接入 OpenAI模型名可使用gpt-4o-mini这类常见模型但具体以你账号可用的模型列表为准。Python 环境python_script不需要额外安装第三方依赖示例代码使用 Python 标准库urllib避免因为 HA 环境中缺少requests导致运行失败。命令行工具shell_command示例依赖系统自带的curl常见 HA 镜像一般自带。有一点需要提前确认调用大模型 API 会产生费用不同平台计费方式不同同时如果你使用的是 OpenAI 服务请确保你的账号状态、网络环境符合 OpenAI 服务条款与当地法律法规。国内用户可优先选择 DeepSeek 这类可以直接访问的平台整体更省事。4. 核心思路HA 中调用大模型 API 的几种方式在编写实战之前先把 HA 中几种可选方案的适用场景说清楚避免你复制完代码后仍然不理解为什么这样写。4.1 方式一shell_commandshell_command是 HA 内置的集成方式它允许你在configuration.yaml里定义一个命令然后在开发者工具或自动化中调用。最简单的模型请求本质上就是一个 HTTP POST所以用curl就能直接完成。这种方式的优点是配置简单、不需要写代码文件适合验证 API 是否连通。缺点是命令拼接容易遇到引号转义问题复杂入参比如多轮对话、JSON 数组不好处理返回结果不适合直接写入实体。所以它更适合做“连通性测试”而不是作为长期方案。4.2 方式二python_scriptpython_script同样是 HA 内置能力。在configuration.yaml中启用python_script:后你只需要把.py文件放在/config/python_scripts/目录下文件名就是服务名。例如创建python_scripts/deepseek_chat.py后HA 中会自动出现python_script.deepseek_chat服务。脚本可以通过全局变量data拿到服务调用时传入的参数通过hass.services.call调用其他 HA 服务通过logger.error输出日志。相比shell_command它更适合组装复杂的 JSON 请求体对返回结果做解析和异常处理把回复写入input_text、发送通知、TTS 播报等。4.3 方式三社区 conversation 集成如果你不想写代码只想让 HA 的 Assist 语音助手直接与大模型对话可以在社区集成库中搜索支持 OpenAI 兼容 API 的 conversation 集成。安装后在 HA 的语音助手配置里把对话代理切换成这个集成填入 API Key 和模型名即可。由于这类集成迭代很快不同版本配置项可能不同这里不展开界面细节。只要理解一个原则它们底层也是在调用 OpenAI 兼容接口只是帮你把“对话代理”这个 HA 原生接口实现了所以在语音助手入口可以直接选择。理解了这三种方式下面进入实战。5. 实战一使用 shell_command 快速调用 DeepSeek API这个章节的目标是先用最轻量的方式验证 API 是否可用并建立对请求格式的直观认识。5.1 准备 API Key登录 DeepSeek 开放平台在控制台中创建一个 API Key。注意复制后立刻保存不要泄露给任何人也不要提交到 Git 仓库。本文中的YOUR_API_KEY都需要替换成你自己的 Key。5.2 编写 shell_command 配置在/config/configuration.yaml中追加以下内容shell_command: deepseek_shell_chat: - curl -s -X POST https://api.deepseek.com/chat/completions -H Content-Type: application/json -H Authorization: Bearer YOUR_API_KEY -d {model:deepseek-chat,messages:[{role:user,content:{{ prompt }}}],temperature:0.7}这里需要注意几点deepseek_shell_chat是服务后缀之后调用服务名是shell_command.deepseek_shell_chat。{{ prompt }}是 HA 模板变量调用服务时传入的prompt参数会替换到该位置。 -是 YAML 折叠块表示把多行合并成一个字符串方便阅读。model使用deepseek-chat这是 DeepSeek 面向通用对话场景的模型。修改配置后在 HA 中检查配置并重启 Home Assistant。5.3 测试调用打开“开发者工具 → 服务”选择shell_command.deepseek_shell_chat服务数据填{ prompt: 你好请用一句话介绍你自己 }调用后返回的 JSON 会出现在 HA 的日志中。正常情况能看到类似下面的内容{ id: chatcmpl-xxx, object: chat.completion, model: deepseek-chat, choices: [ { index: 0, message: { role: assistant, content: 你好我是 DeepSeek一个由深度求索公司开发的 AI 助手。 } } ] }如果日志提示命令不存在或报错先回到 HA 日志页面查看具体错误信息。5.4 切换到 ChatGPT / OpenAI如果你要测试 OpenAI只需要把 URL 和模型名换掉shell_command: openai_shell_chat: - curl -s -X POST https://api.openai.com/v1/chat/completions -H Content-Type: application/json -H Authorization: Bearer YOUR_OPENAI_API_KEY -d {model:gpt-4o-mini,messages:[{role:user,content:{{ prompt }}}],temperature:0.7}再次强调具体可用模型名要以你的 OpenAI 账号为准。5.5 shell_command 的局限性虽然上面的命令可以成功调用但你会发现它存在几个问题prompt内容一旦包含单引号、双引号或换行curl 的 JSON 字符串很容易被截断。返回结果只能通过日志查看不能直接存到实体里。没有异常处理机制网络超时或 API 报错时日志可读性差。因此真正用于日常自动化时更推荐使用python_script来封装。6. 实战二用 python_script 封装大模型调用服务这一节是文章的核心我们会实现一个可以复用的 HA 服务调用 DeepSeek / ChatGPT API把回复写入input_text实体并可选发送通知。6.1 开启 python_script 并创建文本实体在configuration.yaml中追加python_script: input_text: deepseek_result: name: DeepSeek 回复 max: 4096说明python_script:启用 HA 内置的 Python 脚本功能。input_text.deepseek_result用于保存模型回复前端可以直接显示。重启 HA 后在“开发者工具 → 状态”里应该能看到input_text.deepseek_result。6.2 编写 python 脚本在/config/python_scripts/目录下新建文件deepseek_chat.py内容如下# 文件路径python_scripts/deepseek_chat.py # 通过 OpenAI 兼容接口调用大模型支持 DeepSeek / ChatGPT 等 import json import os import urllib.request # 从服务数据中读取参数 prompt data.get(prompt, 你好请用一句话介绍你自己。) model data.get(model, deepseek-chat) temperature data.get(temperature, 0.7) max_tokens data.get(max_tokens, 1024) notify_service data.get(notify_service, ) # 不同模型对应的 Endpoint 配置 # 如果你使用的模型不在列表里可按相同格式补充 MODEL_ENDPOINTS { deepseek-chat: { url: https://api.deepseek.com/chat/completions, model: deepseek-chat, }, deepseek-reasoner: { url: https://api.deepseek.com/chat/completions, model: deepseek-reasoner, }, gpt-4o-mini: { url: https://api.openai.com/v1/chat/completions, model: gpt-4o-mini, }, } endpoint MODEL_ENDPOINTS.get(model) if endpoint is None: logger.warning(未知模型 %s使用默认 deepseek-chat, model) endpoint MODEL_ENDPOINTS[deepseek-chat] model deepseek-chat # 优先从环境变量中读取 API Key避免把密钥写死在脚本中 api_key os.environ.get(DEEPSEEK_API_KEY, ) or os.environ.get(OPENAI_API_KEY, ) if not api_key: # 也可以临时通过服务参数传入适合快速测试 api_key data.get(api_key, ) if not api_key: logger.error(未配置 API Key请在环境变量或服务参数中传入) reply API Key 未配置请检查环境变量或服务参数。 else: payload { model: endpoint[model], messages: [ { role: system, content: 你是一个智能家居 AI 助手。请用简洁、友好、准确的中文回答用户问题。, }, {role: user, content: prompt}, ], temperature: temperature, max_tokens: max_tokens, } headers { Content-Type: application/json, Authorization: Bearer api_key, } req urllib.request.Request( endpoint[url], datajson.dumps(payload).encode(utf-8), headersheaders, methodPOST, ) try: with urllib.request.urlopen(req, timeout30) as resp: result json.loads(resp.read().decode(utf-8)) reply result[choices][0][message][content] except Exception as e: logger.error(大模型 API 调用失败: %s, e) reply 抱歉我暂时无法连接大模型服务请稍后重试。 # 写入 input_text 实体方便在前端展示 hass.services.call(input_text, set_value, { entity_id: input_text.deepseek_result, value: reply, }) # 如果传入了 notify_service直接把结果推送到手机或音箱 if notify_service: hass.services.call(notify, notify_service, { title: AI 助手回复, message: reply, })这段脚本有几个设计点说明一下使用data.get读取调用服务时传入的参数并为每个参数提供默认值。MODEL_ENDPOINTS字典用模型名映射 API 地址切换模型时不需要修改脚本主流程。优先从环境变量中读取 API Key实在没有才允许通过服务参数传入这样可以避免 Key 被写死到脚本文件。请求体使用 UTF-8 编码防止中文乱码。异常捕获后返回固定提示语避免服务直接报错导致自动化中断。通过hass.services.call(input_text, set_value, ...)写入实体比直接修改状态更符合 HA 的设计。可选的通知服务会在收到回复后直接推送省去在自动化中写delay等待。6.3 调用封装好的服务重启 HA 后在“开发者工具 → 服务”中选择python_script.deepseek_chat服务数据可以填{ prompt: 帮我规划一份今晚在家锻炼 30 分钟的计划不需要器材, model: deepseek-chat, temperature: 0.7, max_tokens: 800 }调用后input_text.deepseek_result的状态会变成模型返回的文本。如果你传入了notify_service比如mobile_app_iphone手机通知也会收到同样的内容。6.4 在自动化中生成定期简报封装成服务后自动化调用就很简洁了。下面是一个每天早上 8 点生成天气提醒的示例automation: - alias: 每天早上生成 AI 天气简报 trigger: platform: time at: 08:00:00 action: - service: python_script.deepseek_chat data: prompt: 请根据以下信息生成一段今天早上的天气和出行提示要求语言亲切 当前室外温度{{ states(sensor.outdoor_temperature) }}°C 当前天气{{ states(weather.forecast_home) }} 提醒用户注意穿衣和出行。 model: deepseek-chat notify_service: mobile_app_iphone这里需要注意sensor.outdoor_temperature、weather.forecast_home、mobile_app_iphone都是示例实体和服务你要替换成自己 HA 中实际存在的实体。prompt 中使用了 HA 模板语法自动化执行时会先渲染成真实设备状态再传给脚本。这样每天早上的通知内容就不再是固定文案而是结合当前设备状态的动态内容。7. 进阶对话交互与自动化场景有了基础服务之后可以进一步把大模型接入到更贴近“对话”的场景。7.1 接入 Assist 语音助手如果你希望说一句话就能得到大模型回复可以安装社区提供的 conversation 集成。这些集成通常会提供一个对话代理你需要在 HA 的语音助手配置中把代理切换成该集成并填入 API Key、模型名等参数。配置完成后在 HA 的对话框、App 语音入口甚至实体音箱上都可以直接与大模型对话。这种方式体验最接近“智能家居大脑”但因为第三方集成更新频繁建议安装后以集成仓库的说明为准。7.2 使用 pyscript 开发更灵活的服务pyscript 是一个第三方插件允许你用 Python 直接写 HA 自动化逻辑并且可以更方便地注册自定义服务。如果你已经安装了 pyscript可以把刚才的python_script逻辑改写成 pyscript 服务还可以在脚本中自由读取 HA 状态、调用更多服务。pyscript 也能实现类似功能# 这段代码只是思路示意具体方法名以你安装的 pyscript 版本为准 import json import urllib.request service def deepseek_ask(prompt: str ): payload { model: deepseek-chat, messages: [{role: user, content: prompt}], } req urllib.request.Request( https://api.deepseek.com/chat/completions, datajson.dumps(payload).encode(utf-8), headers{ Content-Type: application/json, Authorization: Bearer YOUR_API_KEY, }, ) with urllib.request.urlopen(req, timeout30) as resp: result json.loads(resp.read().decode(utf-8)) reply result[choices][0][message][content] # 将结果发送到手机通知或通过 TTS 播报 notify.persistent_notification(titleAI 回复, messagereply)由于 pyscript 版本差异较大这段代码只用于展示思路。实际使用时应参考你安装版本的文档并优先把 API Key 放到安全的位置。7.3 把设备状态作为上下文喂给大模型大模型能否给出有价值的建议很大程度上取决于 prompt 是否包含了足够的上下文。比如下面的自动化在人进入客厅时把温度、湿度、天气状态都传给大模型让它生成生活建议automation: - alias: 客厅有人时生成生活建议 trigger: - platform: state entity_id: binary_sensor.living_room_motion to: on condition: - condition: time after: 18:00:00 before: 23:00:00 action: - service: python_script.deepseek_chat data: prompt: 今晚客厅检测到有人活动请根据下面的信息给出 2 条简短建议。 当前客厅温度{{ states(sensor.living_room_temperature) }}°C 客厅湿度{{ states(sensor.living_room_humidity) }}% 室外天气{{ states(weather.forecast_home) }}。 请控制在 80 字以内。 notify_service: mobile_app_iphone这种写法的核心是把 HA 当作家里的“感知层”大模型作为“决策和表达层”两者各司其职。7.4 在 Lovelace 前端做一个问答输入框如果你不想依赖手机通知也可以在前端放一个输入框。思路是在configuration.yaml中定义input_text.deepseek_query作为用户输入。写一个自动化监听input_text.deepseek_query的状态变化。当用户输入新文本后自动调用python_script.deepseek_chat并把结果写入input_text.deepseek_result。在 Lovelace 中用实体卡片展示这两个实体用户就能完成输入和查看回复。对应自动化如下automation: - alias: 前端输入框触发 AI 问答 trigger: - platform: state entity_id: input_text.deepseek_query action: - service: python_script.deepseek_chat data: prompt: {{ states(input_text.deepseek_query) }}需要注意为了避免输入框内容被重复触发你可以在自动化里增加条件判断新状态不是空字符串或者配合input_boolean做开关控制。8. 常见问题与排查思路接入过程中最常遇到的错误可以按下面表格快速排查。问题现象常见原因解决思路401 UnauthorizedAPI Key 错误或已失效检查环境变量/服务参数中的 Key到开放平台重新生成model not found 或 404模型名不匹配或账号无权限到官方文档确认模型名例如 deepseek-chat、gpt-4o-mini请求超时网络不通或 API 响应慢先用 curl 手动测试增大 timeout检查网络和 DNSJSON 解析失败API 返回了错误信息而不是标准回复先打印原始响应内容查看 error 字段python_script 中 import requests 报错HA 环境缺少第三方库改用标准库 urllib或在 HA 虚拟环境中 pip install中文乱码编码不一致确保请求体encode(utf-8)读取时decode(utf-8)shell_command 报错引号、模板变量转义问题先用固定文本测试复杂入参改用 python_script自动化触发后没有回复实体名写错、服务失败、通知渠道不可用先手动调用服务查看日志单独测试 notify费用增长快调用频繁、max_tokens 过大限制调用频率、使用便宜模型、增加结果缓存如果你是用shell_command方式排查问题建议先不传中文、不传长文本固定一个简单 prompt 试试curl -s -X POST https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {model:deepseek-chat,messages:[{role:user,content:hello}],temperature:0.7}这个请求如果正常返回说明 API Key、网络和模型名都没有问题问题大概率出在 HA 模板渲染或引号转义上。9. 最佳实践与工程建议把大模型接入智能家居不只是“能通”就行生产环境还需要考虑安全、费用和维护成本。9.1 API Key 安全管理永远不要把 API Key 写死在前端代码、自动化 yaml 或 Python 脚本里。推荐方式有两种在configuration.yaml中使用!secret引用secrets.yaml中的变量。在 Python 脚本中通过环境变量读取 API Key。例如secrets.yaml中可以这样写deepseek_api_key: sk-xxxxxxxx然后shell_command里使用shell_command: deepseek_shell_chat: - curl -s -X POST https://api.deepseek.com/chat/completions -H Content-Type: application/json -H Authorization: Bearer !secret deepseek_api_key -d {model:deepseek-chat,messages:[{role:user,content:{{ prompt }}}],temperature:0.7}注意!secret必须放在 HA 配置文件解析层生效Python 脚本中不能直接用所以脚本优先考虑环境变量。9.2 错误处理与兜底逻辑任何网络请求都可能失败。在 Python 脚本中除了 try-except还应提供固定兜底文案比如“抱歉我暂时无法连接大模型服务”。这样自动化流程不会因为 API 异常而中断。9.3 费用控制大模型 API 按 token 计费使用成本容易被忽略。建议做到以下几点给max_tokens设置合理上限避免模型生成超长文本。不要在自动化里频繁调用比如不要每秒轮询一次 API。对相同问题可以缓存结果避免重复请求。优先使用价格更低的模型。9.4 隐私保护调用大模型时用户输入和上下文会被发送到第三方服务。不要把门锁密码、摄像头画面描述、通话音量等高度敏感信息不加处理地放进 prompt。如果模型需要控制设备建议先输出“建议执行操作”由用户确认后再执行避免误操作。9.5 权限最小化如果后续你开发自定义集成不要使用管理员级别的长期令牌来做普通查询。尽量给 API Key 分配最小权限并且定期轮换。HA 中涉及设备控制的服务调用要增加条件判断不能完全信任模型输出。9.6 版本升级验证Home Assistant 升级频率很高python_script和shell_command这类内置能力一般比较稳定但第三方 conversation 集成可能会在大版本升级后失效。升级前先做备份升级后第一时间测试关键自动化。10. 总结与下一步学习路线本文从 Home Assistant 的实际交互痛点出发完整介绍了接入 ChatGPT、DeepSeek 等大模型 API 的方案。你可以先通过shell_command快速验证 API 连通性再用python_script封装出一个可复用的 HA 服务最后通过自动化和前端输入框把它接入日常使用。核心路径是配置 API Key → 发起 OpenAI 兼容请求 → 解析返回值 → 写入实体或发送通知 → 接入自动化。如果已经完成了这篇文章的示例下一步可以沿着几个方向继续深入学习 HA 自定义集成开发把大模型调用写成一个真正的conversation代理。研究大模型的 function calling 能力让模型能够调用 HA 服务来控制设备实现“AI 帮你关灯、调温度”的完整闭环。研究本地部署大模型方案把数据完全留在家庭内网从而更好地保护隐私。学习 prompt engineering设计更复杂的上下文模板让模型能基于家庭设备数据做更精准的判断。接入大模型只是开始真正有价值的是让它在真实家庭环境中稳定、安全、低成本地运行。建议先从“每日简报”“语音问答”这类低风险场景开始逐步积累经验后再接入设备控制逻辑。欢迎动手实践遇到问题也可以回到这篇文章对照排查。