企业官网建设流程全解析

智能家居发展到今天，很多玩家已经不再满足于“灯按时开关”“温度过高自动开空调”这类固定逻辑自动化。真正让 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 为例；ChatGPT（OpenAI）的接入方式也完全兼容，只需替换相关参数即可。

2. 技术选型与整体方案设计

在 Home Assistant 中调用大模型 API，常见有下面几种方案。

从稳定性、可维护性、灵活性三个角度综合考虑，比较推荐下面这条落地路径：

1. 先用curl或shell_command验证 API Key 和模型名是否可用。
2. 再用python_script把大模型调用封装成一个 HA 服务。
3. 然后在自动化里调用这个服务，把回复写入input_text实体，或者发送到手机通知。
4. 如果后续想接入 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_command

shell_command是 HA 内置的集成方式，它允许你在configuration.yaml里定义一个命令，然后在开发者工具或自动化中调用。最简单的模型请求本质上就是一个 HTTP POST，所以用curl就能直接完成。

这种方式的优点是配置简单、不需要写代码文件，适合验证 API 是否连通。缺点是：

• 命令拼接容易遇到引号转义问题；
• 复杂入参（比如多轮对话、JSON 数组）不好处理；
• 返回结果不适合直接写入实体。

所以它更适合做“连通性测试”，而不是作为长期方案。

4.2 方式二：python_script

python_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"], data=json.dumps(payload).encode("utf-8"), headers=headers, method="POST", ) try: with urllib.request.urlopen(req, timeout=30) 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", data=json.dumps(payload).encode("utf-8"), headers={ "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY", }, ) with urllib.request.urlopen(req, timeout=30) as resp: result = json.loads(resp.read().decode("utf-8")) reply = result["choices"][0]["message"]["content"] # 将结果发送到手机通知，或通过 TTS 播报 notify.persistent_notification(title="AI 回复", message=reply)

由于 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 前端做一个问答输入框

如果你不想依赖手机通知，也可以在前端放一个输入框。思路是：

1. 在configuration.yaml中定义input_text.deepseek_query作为用户输入。
2. 写一个自动化监听input_text.deepseek_query的状态变化。
3. 当用户输入新文本后，自动调用python_script.deepseek_chat，并把结果写入input_text.deepseek_result。
4. 在 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. 常见问题与排查思路

接入过程中，最常遇到的错误可以按下面表格快速排查。

如果你是用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，设计更复杂的上下文模板，让模型能基于家庭设备数据做更精准的判断。

接入大模型只是开始，真正有价值的，是让它在真实家庭环境中稳定、安全、低成本地运行。建议先从“每日简报”“语音问答”这类低风险场景开始，逐步积累经验后再接入设备控制逻辑。欢迎动手实践，遇到问题也可以回到这篇文章对照排查。