之前在一个智能家居项目里想给 Home Assistant 加上“能聊天、能控制设备”的 AI 大脑市面上资料大多是讲某个单一插件的安装位置分散版本一换就失效。本文把整套思路重新梳理了一遍先讲清楚接入原理再给两条可落地的路线——一条是调用 DeepSeek 在线 API一条是本地 Ollama 部署最后补充设备控制、常见报错和工程实践。不管你是刚开始接触 Home Assistant 的新手还是已经跑了一段时间想升级的中级玩家这篇都能按步骤操作。1. 为什么要让 Home Assistant 接入 AI 大模型1.1 Home Assistant 是什么Home Assistant简称 HA是一个开源的家庭自动化平台可以把不同品牌、不同协议的智能设备统一接入到一个界面中集中管理。它的核心能力有两个设备接入支持 Zigbee、MQTT、Wi-Fi、蓝牙等多种协议。自动化通过触发器、条件、动作实现“温度过高自动开风扇”“有人移动自动亮灯”这类场景。传统上HA 的交互方式主要是手机 App、仪表盘和语音助手。用户想控制某个设备要么手动点击要么提前写死自动化规则。这种方式的问题在于规则是预设的遇到“帮我调暗一点”“我出门了”这类模糊指令自动化规则很难灵活处理。1.2 ChatGPT、DeepSeek 与 AI 大模型ChatGPT 是 OpenAI 推出的对话式 AI 服务背后是 GPT 系列大语言模型。DeepSeek 是深度求索推出的大模型产品同样具备对话、代码生成、逻辑推理等能力并且对外提供了 OpenAI 兼容的 API 接口意味着很多原本为 OpenAI 生态开发的工具只要修改 base_url 和模型名就能直接切换。从接入家庭自动化的角度看AI 大模型带来的最大变化是“意图理解”。以前用户要精确说出“打开客厅灯”现在可以自然地说“太暗了帮我把灯调亮一点”模型可以根据语义判断出要操作哪个实体、调用哪个服务。1.3 接入后能做哪些事把 Home Assistant 接入 ChatGPT 或 DeepSeek 后最常见的应用场景包括场景说明自然语言控制设备通过对话让 AI 帮你开关灯、调节空调、查询传感器状态家庭状态查询“现在客厅温度多少”“今天家里有人回家过吗”故障诊断与提示AI 根据日志和传感器数据提示设备异常或给出维护建议语音助手升级配合 HA Voice 或第三方音箱把默认的命令式语音换成大模型对话场景自动化建议让 AI 分析家庭使用习惯生成自动化规则草稿这篇文章会集中解决其中最关键的两件事一是把大模型的“对话能力”接入 HA二是让 AI 具备“真正控制设备”的能力。2. 接入方案选型2.1 方案总览目前 Home Assistant 接入 AI 大模型主要分为在线 API 和本地部署两大类再往下细分有四种常见路线。方案模型位置网络依赖配置复杂度灵活性方案 AHA 官方 OpenAI Conversation 集成云端需要能访问 API低中方案 B自定义脚本 / REST API云端需要能访问 API中高方案 COllama 本地部署本机 / 内网无外网依赖中高方案 D自定义对话组件云端或本地取决于模型高最高2.2 为什么要重点推荐 DeepSeek在写这篇文章时DeepSeek 开放平台提供了兼容 OpenAI 格式的 API模型调用方式与 OpenAI 基本一致很多工具只要换一下 base_url 和 api_key 就能使用。如果你在国内服务器或家庭内网环境运行 HADeepSeek 在访问效率和稳定性上通常更省心。ChatGPT 的官方 API 同样是 OpenAI 兼容格式接入思路完全一致区别在于账号体系、模型名称和访问网络环境不同。本文示例会以 DeepSeek 为主但方案 A 和方案 B 对 ChatGPT 同样适用只需替换对应的 base_url 和模型名即可。2.3 我的选型建议第一步建议先走“方案 A”用 HA 官方 OpenAI Conversation 集成把 DeepSeek 作为对话模型整个流程半小时内能跑通。如果想要更精细的控制输出、批量调用或对接自己的业务逻辑再升级到“方案 B”脚本方式。如果你在意隐私或者家里网络对外访问不稳定建议直接看“方案 C”本地部署。方案 D 适合熟悉 HA 二次开发的同学可以作为后续进阶方向。3. 环境准备与版本说明3.1 Home Assistant 环境要求本文的操作步骤不区分 HA 的具体安装方式。无论你是用 HAOS、Home Assistant Container、还是 Supervised 安装只要能进入配置目录、能添加集成就可以继续。版本方面建议使用较新的 Home Assistant 版本。AI 相关能力和对话 Agent 机制在近几个版本中迭代较快越新版本对 OpenAI 兼容 API 和本地大模型的支持越好。如果你使用的是 2023 年以前的版本界面和配置项可能有差异建议先升级到当前稳定版。需要准备的硬件和系统一台运行 HA 的主机树莓派、NAS、旧的 x86 小主机都可以。能访问 HA 的 Web 界面。如果走在线 API确保 HA 主机可以访问对应 API 服务。如果走本地部署建议 GPU 有 8GB 以上显存或者使用内存较大的 CPU 机器运行量化小模型。3.2 获取 DeepSeek API Key在 DeepSeek 开放平台注册账号后进入“API Keys”页面创建一个新的 API Key。创建完成后Key 只显示一次一定要先复制保存后面配置 HA 时会用到。不同模型平台的 API Key 格式不同DeepSeek 的 Key 通常以sk-开头。OpenAI 的 Key 同样是sk-开头但两者不能混用需要严格区分。3.3 本地 Ollama 准备思路如果选择本地部署不需要注册任何云平台账号。Ollama 是一个开源的本地大模型运行工具安装后可以通过命令行拉取模型并提供一个本地 HTTP API 供 HA 调用。Ollama 的模型下载和磁盘占用比较大建议先确认上面 3.1 里的硬件条件。拉取模型时可以选择量化版本比如deepseek-r1:7b这类模型文件相对小家用主机更容易跑起来。4. 方案一在线接入 DeepSeekOpenAI 兼容 API4.1 OpenAI 兼容 API 的基本概念OpenAI 兼容 API 并不是一个官方标准而是一套事实上的接口规范。很多大模型平台为了让已有生态工具能快速接入会实现与 OpenAI/chat/completions接口一致的请求格式。对 HA 这类支持 OpenAI 格式的集成来说只要把 API 地址指向第三方平台的地址就能把模型切成 DeepSeek。一个完整的 chat/completions 请求包含三部分URLAPI 地址通常是{base_url}/chat/completionsHeaders认证信息Authorization: Bearer sk-xxxBody模型名、消息列表、温度等参数很多报错都出在这三个环节上后面排查部分会详细展开。4.2 快速验证 API 是否可用在动 HA 之前先用命令行验证 API 是否可用。下面是一个最简单的 curl 示例请把YOUR_API_KEY替换成你自己的 Key。这里使用的模型名是deepseek-chat具体支持哪些模型名以 DeepSeek 开放平台文档为准。curl 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: 你好请介绍下你自己}], stream: false }如果 API Key 和网络配置正常返回内容中会有一个choices数组里面是模型生成的回复。如果返回 401说明 Key 有问题如果返回 404说明模型名或者 URL 路径不对。4.3 在 HA 中接入对话 Agent当 API 验证通过后就可以在 Home Assistant 中添加集成。推荐使用 UI 方式添加打开 HA进入“设置 - 设备与服务”。点击右下角的“添加集成”。搜索OpenAI Conversation。填写 DeepSeek 的 API Key。在模型名称中填deepseek-chat。在支持自定义 API Base URL 的版本中将地址填为 DeepSeek 的 base_url也就是https://api.deepseek.com。如果你的版本没有该字段说明当前 UI 不支持自定义地址请参考 4.4 使用脚本方案。不同 HA 版本的集成配置项会有差异。核心思路是API Key 填 DeepSeek 的 Key模型名填 DeepSeek 的模型名API Base URL 填 DeepSeek 的地址。这三项都正确模型就能被成功调用。4.4 使用脚本方式接入跨版本通用方案如果 HA 版本不支持在 OpenAI Conversation 集成里修改 base_url可以退一步用脚本方式把 DeepSeek 封装成一个 HA 服务。这里以 Python 脚本为例演示如何使用requests库调用 DeepSeek API。在 HA 配置目录下创建scripts/ask_deepseek.py#!/usr/bin/env python3 import requests import sys API_KEY YOUR_DEEPSEEK_API_KEY BASE_URL https://api.deepseek.com/chat/completions MODEL deepseek-chat def ask_deepseek(message: str) - str: headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { model: MODEL, messages: [ {role: system, content: 你是一个智能家居助手请用简洁的中文回答用户问题。}, {role: user, content: message} ], temperature: 0.7, stream: False } resp requests.post(BASE_URL, jsonpayload, headersheaders, timeout30) resp.raise_for_status() data resp.json() return data[choices][0][message][content] if __name__ __main__: if len(sys.argv) 2: print(Usage: ask_deepseek.py message) sys.exit(1) print(ask_deepseek(sys.argv[1]))然后在configuration.yaml中注册一个shell_commandshell_command: ask_deepseek: /config/scripts/ask_deepseek.py {{ message }}重启 HA 后可以在“开发者工具 - 服务”里找到shell_command.ask_deepseek服务调用时传入参数message: 今天适合开窗吗服务会返回 DeepSeek 的回复。这种方法虽然不能直接在 Assist 面板中形成连续对话但把大模型能力封装成了 HA 的标准化服务后续做自动化联动时会非常方便。4.5 验证对话效果配置完成后在 HA 概览页点击右下角的对话按钮进入 Assist 面板。在左上角选择刚才配置的对话 Agent输入测试内容。如果一切正常会收到 DeepSeek 的文本回复。如果收到的回复来自默认的 HA 助手、而不是 DeepSeek说明 Assist 仍然绑定在原对话 Agent 上需要在对话 Agent 下拉菜单中切换到新的模型。5. 方案二通过 Ollama 本地部署 DeepSeek 接入5.1 本地部署的核心价值在线 API 虽然方便但有一个天然特点所有对话内容和设备状态数据都会发送到云厂商服务器。对于注重隐私的家庭场景这是一道坎。本地部署后模型运行在自己的机器上外部网络中断也不影响家庭自动化使用长期运行成本也更可控。代价是硬件要求和响应速度。一个 7B 量级模型在普通 CPU 机器上思考速度较慢推理一个完整回答可能需要几秒到几十秒。如果你对响应延迟敏感在线 API 体验会更好。5.2 安装 Ollama 并拉取模型Ollama 的安装方式以官方文档为准。安装完成后先确认服务状态ollama --version ollama serve然后拉取 DeepSeek 模型ollama pull deepseek-r1:7b拉取完成后可以通过命令行简单测试ollama run deepseek-r1:7b 你好介绍一下你自己如果命令行能正常回答说明 Ollama 模型已经可用。Ollama 默认监听在11434端口HTTP API 地址为http://主机IP:11434稍后 HA 配置时要用到。5.3 在 HA 中配置 Ollama ConversationHome Assistant 官方提供了 Ollama 集成配置过程相对简单进入“设置 - 设备与服务”。添加集成搜索Ollama。填写 Ollama 服务地址比如http://192.168.1.100:11434。选择要使用的模型比如deepseek-r1:7b。在对话 Agent 中选择该模型并测试。如果你希望用 YAML 配置也可以参考下面这段思路ollama: host: http://192.168.1.100:11434注意HA 不同版本对 Ollama 集成的配置字段支持不同。如果 YAML 配置不生效优先使用 UI 添加集成。5.4 验证本地对话在 Assist 面板选择 Ollama 对应的对话 Agent输入一段自然语言测试。由于本地模型没有联网搜索能力问题最好集中在常识问答、语义理解类内容不要提问实时新闻或需要外部资料的问题。如果 HA 提示连接失败优先检查 Ollama 服务是否运行以及 HA 主机到 Ollama 主机的网络是否连通。可以在 HA 主机上用 curl 测试 Ollama 接口curl http://192.168.1.100:11434/api/tags能正常返回模型列表说明网络层没有障碍。6. 进阶让 AI 真正控制你的智能家居6.1 从“聊天”到“控制”的架构变化让 AI 回复文本只是第一步真正有价值的是让 AI 根据用户意图去控制设备。在 Home Assistant 中这通常依赖“工具调用”能力。简单说大模型不仅可以生成文字还可以输出一个结构化的调用指令随后由 HA 执行对应的服务调用。例如用户说“把客厅灯调暗一点”模型可能返回一个调用light.turn_on服务的指令参数为entity_id: light.living_room和brightness: 100。HA 拿到这个指令后真正执行开关动作的是 HA 自己模型只负责决策不直接接触硬件。需要注意工具调用能力是否可用取决于两个因素模型本身是否支持 function calling。HA 版本是否将服务列表和实体信息传入给对话模型。DeepSeek 是否支持工具调用、以及在当前 HA 版本中是否能正确传参建议以官方文档和实际测试为准。如果模型不支持自动工具调用可以退一步使用“意图映射”方案见 6.3。6.2 通过 Prompt 约束 Agent 行为不管模型是否支持自动工具调用Prompt 都是整个接入方案的关键。在 OpenAI Conversation 或 Ollama Conversation 中通常可以设置系统提示词。下面是一个家庭助手场景的 Prompt 示例你现在是家庭智能管家。你可以控制以下实体 - 客厅灯switch.living_room_light - 卧室空调climate.bedroom_ac - 阳台窗帘cover.balcony_curtain 规则 1. 用户请求操作设备时先确认是非常明确的指令。 2. 如果用户表达模糊请先询问清楚再执行。 3. 禁止执行任何涉及门锁、燃气、热水器等高风险设备的操作。 4. 回答尽量简洁使用中文。这段 Prompt 的核心作用是划定 AI 的“行动边界”。没有边界时模型可能会在不确定的情况下执行动作非常危险。建议把可控制实体的清单写在系统提示词里而不是让模型自己猜测。6.3 通过自动化脚本实现“语义控制”如果你觉得自动工具调用不够可靠还有一种更可控的思路让模型只做“意图理解”由 HA 自动化执行动作。具体做法是创建一个自动化监听文本类型的传感器或输入框。当有新的用户指令进来时调用 DeepSeek API让它输出固定的 JSON 格式指令例如{intent: turn_on, entity: living_room_light}在自动化脚本中解析 JSON映射到 HA 服务调用。这种方式的优点是逻辑完全可控模型即使偶尔抽风也不会直接触发危险操作。缺点是需要自己写解析脚本。下面是一个简单的解析思路import json raw_output {intent: turn_on, entity: living_room_light} try: action json.loads(raw_output) intent action.get(intent) entity action.get(entity) print(f要执行的动作: {intent}, 实体: {entity}) except json.JSONDecodeError: print(模型输出不是合法 JSON需要重新请求)6.4 安全边界设计接入 AI 控制设备后安全边界必须优先设计。首先模型不应该拥有全部设备的控制权限。在 HA 中可以给对话 Agent 配置可访问的实体范围建议按房间或设备类型分组授权。其次高风险设备要单独处理。指纹锁、燃气阀门、烘干机这类设备无论模型如何理解都不建议交给 AI 自动执行。可以在自动化中增加二次确认机制比如 AI 控制前先发送确认消息用户回复“确认”后才真正执行。最后所有 AI 触发的执行动作都要留日志。可以在自动化里添加事件记录或者把调用内容发送到群晖、Telegram 等通知渠道。这样做不是多此一举而是为了出问题时能快速定位。7. 常见问题与排查7.1 高频报错排查表下面这张表汇总了接入过程中最常见的几类问题先看表了解大概方向再继续看具体展开。问题现象常见原因解决思路返回 401 UnauthorizedAPI Key 错误、过期或复制多了空格重新创建 Key粘贴时检查前后空格返回 402 Payment Required账户余额不足给模型平台账户充值返回 404 Not FoundURL 路径错误、模型名不存在核对 base_url 和模型名返回 429 Too Many Requests请求频率过高或额度用完降低请求频率检查限流策略请求超时网络无法访问 API或代理配置异常检查 HA 主机到 API 服务的连通性HA 无法找到集成HA 版本过旧升级 HA 到最新稳定版Ollama 连接失败Ollama 服务未启动、端口不同、网络不通检查 ollama serve 状态和网络连接7.2 模型不回复或回答奇怪如果 API 调用成功但返回内容为空或回答内容跟问题完全不相关通常是 Prompt 问题或模型参数问题。先检查温度参数。温度太高会导致回答随机性变大建议控制在0.7以下。再检查系统提示词是否与用户问题冲突。如果系统提示词要求“只能回答关于天气的问题”用户问“帮我把灯打开”模型当然答非所问。在 HA 中接入对话 Agent 后如果模型始终不调用工具可以在开发者工具中查看模型返回的完整内容确认是模型没有生成工具调用还是 HA 没有正确解析。这个排查方向非常关键。7.3 关于“配置文件无法加载”的问题很多使用本地客户端或命令行工具接入大模型的同学会遇到config.toml无法加载、对话串无法恢复的问题。这类问题本质上是配置文件中model字段填写的模型名与当前模型平台不匹配。举例来说如果你在本地工具中写的是 ChatGPT 之外的模型名但 API 地址仍然是 ChatGPT 的地址工具会认为模型不受支持从而拒绝加载配置。修正方法是让“模型名”和“base_url”保持对应关系调用 DeepSeek 时使用 DeepSeek 的 base_url 和deepseek-chat等模型名。调用 OpenAI 时使用 OpenAI 的 base_url 和对应的 GPT 模型名。这个原理在 HA 中同样适用因此在排查 HA 对话 Agent 问题时先确认“模型名 base_url API Key”三者是否来自同一个模型平台。8. 最佳实践与工程建议8.1 API Key 与敏感信息管理API Key 是敏感信息永远不要直接硬编码在configuration.yaml中。HA 提供了secrets.yaml机制用来集中管理密钥。# configuration.yaml shell_command: ask_deepseek: /config/scripts/ask_deepseek.py {{ message }}对应的secrets.yaml中虽然存储的是 shell_command 参数但更好的做法是把 Python 脚本中的 API Key 也读取自环境变量或单独的秘密文件避免明文出现在可被其他人读到的配置里。import os API_KEY os.getenv(DEEPSEEK_API_KEY, fallback-key)如果你的 HA 有备份同步到 Git 仓库务必通过.gitignore把秘密文件排除掉。8.2 成本与 Token 控制在线 API 按 Token 计费虽然单次对话成本很低但家庭环境 7x24 小时运行大量自动化调用累积起来也是一笔费用。控制成本的关键在于“减少不必要的上下文”。每次调用 API 时不需要把整个家庭历史对话都发给模型只传递最近的几轮对话即可。在 Prompt 设计上尽量让模型使用简洁回复风格。在 API 请求参数中设置max_tokens上限避免模型生成超长回答也是有效的成本控制手段。DeepSeek 开放平台支持查看调用量和余额消耗建议定期关注。8.3 Prompt 与上下文工程Prompt 设计的核心不是“让模型更强”而是“让模型知道边界”。同样的 DeepSeek 模型在不同 Prompt 下的行为差异会非常明显。家庭场景中建议把以下内容固化到系统提示词中可控制的实体清单和对应的 entity_id。禁止操作的设备和命令。模糊指令时的默认处理方式先询问不执行。回复语言风格。回答中是否允许输出 JSON。在实际项目里Prompt 不是写一次就结束了。你可能会遇到模型在某些场景下表现不稳定这时候要针对失败案例不断迭代 Prompt。建议为每次调用保留日志记录用户问题、模型回复、以及是否成功执行动作。8.4 可用性与容灾设计在线 API 和本地模型各有优势实际使用时可以设计成双通道。比如默认走 DeepSeek 在线 API当 API 连续调用失败时自动降级到本地 Ollama 模型。在 HA 中实现这种降级可以在自动化中检测 API 调用的返回状态。如果返回 429 或超时再调用本地模型接口。这样既保证了日常体验也避免外部服务抖动导致整套智能家居对话能力瘫痪。要注意不要让自动化进入死循环。建议在降级方案中增加“熔断”机制即短时间连续失败 N 次后停止自动重试等待人工介入或延迟一段时间后再恢复。9. 总结与下一步学习建议这篇文章围绕 Home Assistant 接入 AI 大模型做了完整的方案拆解核心内容可以概括为四点在线方案通过 OpenAI 兼容 API 接入 DeepSeek适合快速体验和大多数家庭场景。本地方案通过 Ollama 本地部署 DeepSeek 模型适合隐私敏感或网络不稳定的环境。控制能力让 AI 从“聊天”升级为“控制设备”关键在于工具调用、Prompt 边界和自动化兜底。工程实践API Key 管理、成本控制、安全边界和容灾设计决定了这个功能能否长期稳定运行。如果你目前还没有在 HA 中接入过任何大模型建议先从第 4 节的在线 API 方案开始跑通后再去尝试本地部署。等这两条路线都熟悉了再研究 HA 的自定义对话组件开发、Function Calling 的高级用法以及通过 RAG 让 AI 更理解你的家庭设备配置。接入大模型不是终点让它在合适的场景里帮你做正确的事才是更有意思的部分。如果这篇文章帮到了你可以收藏备用后续遇到报错也可以回来对照排查。
Home Assistant接入DeepSeek大模型：在线API与本地Ollama部署全攻略
之前在一个智能家居项目里想给 Home Assistant 加上“能聊天、能控制设备”的 AI 大脑市面上资料大多是讲某个单一插件的安装位置分散版本一换就失效。本文把整套思路重新梳理了一遍先讲清楚接入原理再给两条可落地的路线——一条是调用 DeepSeek 在线 API一条是本地 Ollama 部署最后补充设备控制、常见报错和工程实践。不管你是刚开始接触 Home Assistant 的新手还是已经跑了一段时间想升级的中级玩家这篇都能按步骤操作。1. 为什么要让 Home Assistant 接入 AI 大模型1.1 Home Assistant 是什么Home Assistant简称 HA是一个开源的家庭自动化平台可以把不同品牌、不同协议的智能设备统一接入到一个界面中集中管理。它的核心能力有两个设备接入支持 Zigbee、MQTT、Wi-Fi、蓝牙等多种协议。自动化通过触发器、条件、动作实现“温度过高自动开风扇”“有人移动自动亮灯”这类场景。传统上HA 的交互方式主要是手机 App、仪表盘和语音助手。用户想控制某个设备要么手动点击要么提前写死自动化规则。这种方式的问题在于规则是预设的遇到“帮我调暗一点”“我出门了”这类模糊指令自动化规则很难灵活处理。1.2 ChatGPT、DeepSeek 与 AI 大模型ChatGPT 是 OpenAI 推出的对话式 AI 服务背后是 GPT 系列大语言模型。DeepSeek 是深度求索推出的大模型产品同样具备对话、代码生成、逻辑推理等能力并且对外提供了 OpenAI 兼容的 API 接口意味着很多原本为 OpenAI 生态开发的工具只要修改 base_url 和模型名就能直接切换。从接入家庭自动化的角度看AI 大模型带来的最大变化是“意图理解”。以前用户要精确说出“打开客厅灯”现在可以自然地说“太暗了帮我把灯调亮一点”模型可以根据语义判断出要操作哪个实体、调用哪个服务。1.3 接入后能做哪些事把 Home Assistant 接入 ChatGPT 或 DeepSeek 后最常见的应用场景包括场景说明自然语言控制设备通过对话让 AI 帮你开关灯、调节空调、查询传感器状态家庭状态查询“现在客厅温度多少”“今天家里有人回家过吗”故障诊断与提示AI 根据日志和传感器数据提示设备异常或给出维护建议语音助手升级配合 HA Voice 或第三方音箱把默认的命令式语音换成大模型对话场景自动化建议让 AI 分析家庭使用习惯生成自动化规则草稿这篇文章会集中解决其中最关键的两件事一是把大模型的“对话能力”接入 HA二是让 AI 具备“真正控制设备”的能力。2. 接入方案选型2.1 方案总览目前 Home Assistant 接入 AI 大模型主要分为在线 API 和本地部署两大类再往下细分有四种常见路线。方案模型位置网络依赖配置复杂度灵活性方案 AHA 官方 OpenAI Conversation 集成云端需要能访问 API低中方案 B自定义脚本 / REST API云端需要能访问 API中高方案 COllama 本地部署本机 / 内网无外网依赖中高方案 D自定义对话组件云端或本地取决于模型高最高2.2 为什么要重点推荐 DeepSeek在写这篇文章时DeepSeek 开放平台提供了兼容 OpenAI 格式的 API模型调用方式与 OpenAI 基本一致很多工具只要换一下 base_url 和 api_key 就能使用。如果你在国内服务器或家庭内网环境运行 HADeepSeek 在访问效率和稳定性上通常更省心。ChatGPT 的官方 API 同样是 OpenAI 兼容格式接入思路完全一致区别在于账号体系、模型名称和访问网络环境不同。本文示例会以 DeepSeek 为主但方案 A 和方案 B 对 ChatGPT 同样适用只需替换对应的 base_url 和模型名即可。2.3 我的选型建议第一步建议先走“方案 A”用 HA 官方 OpenAI Conversation 集成把 DeepSeek 作为对话模型整个流程半小时内能跑通。如果想要更精细的控制输出、批量调用或对接自己的业务逻辑再升级到“方案 B”脚本方式。如果你在意隐私或者家里网络对外访问不稳定建议直接看“方案 C”本地部署。方案 D 适合熟悉 HA 二次开发的同学可以作为后续进阶方向。3. 环境准备与版本说明3.1 Home Assistant 环境要求本文的操作步骤不区分 HA 的具体安装方式。无论你是用 HAOS、Home Assistant Container、还是 Supervised 安装只要能进入配置目录、能添加集成就可以继续。版本方面建议使用较新的 Home Assistant 版本。AI 相关能力和对话 Agent 机制在近几个版本中迭代较快越新版本对 OpenAI 兼容 API 和本地大模型的支持越好。如果你使用的是 2023 年以前的版本界面和配置项可能有差异建议先升级到当前稳定版。需要准备的硬件和系统一台运行 HA 的主机树莓派、NAS、旧的 x86 小主机都可以。能访问 HA 的 Web 界面。如果走在线 API确保 HA 主机可以访问对应 API 服务。如果走本地部署建议 GPU 有 8GB 以上显存或者使用内存较大的 CPU 机器运行量化小模型。3.2 获取 DeepSeek API Key在 DeepSeek 开放平台注册账号后进入“API Keys”页面创建一个新的 API Key。创建完成后Key 只显示一次一定要先复制保存后面配置 HA 时会用到。不同模型平台的 API Key 格式不同DeepSeek 的 Key 通常以sk-开头。OpenAI 的 Key 同样是sk-开头但两者不能混用需要严格区分。3.3 本地 Ollama 准备思路如果选择本地部署不需要注册任何云平台账号。Ollama 是一个开源的本地大模型运行工具安装后可以通过命令行拉取模型并提供一个本地 HTTP API 供 HA 调用。Ollama 的模型下载和磁盘占用比较大建议先确认上面 3.1 里的硬件条件。拉取模型时可以选择量化版本比如deepseek-r1:7b这类模型文件相对小家用主机更容易跑起来。4. 方案一在线接入 DeepSeekOpenAI 兼容 API4.1 OpenAI 兼容 API 的基本概念OpenAI 兼容 API 并不是一个官方标准而是一套事实上的接口规范。很多大模型平台为了让已有生态工具能快速接入会实现与 OpenAI/chat/completions接口一致的请求格式。对 HA 这类支持 OpenAI 格式的集成来说只要把 API 地址指向第三方平台的地址就能把模型切成 DeepSeek。一个完整的 chat/completions 请求包含三部分URLAPI 地址通常是{base_url}/chat/completionsHeaders认证信息Authorization: Bearer sk-xxxBody模型名、消息列表、温度等参数很多报错都出在这三个环节上后面排查部分会详细展开。4.2 快速验证 API 是否可用在动 HA 之前先用命令行验证 API 是否可用。下面是一个最简单的 curl 示例请把YOUR_API_KEY替换成你自己的 Key。这里使用的模型名是deepseek-chat具体支持哪些模型名以 DeepSeek 开放平台文档为准。curl 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: 你好请介绍下你自己}], stream: false }如果 API Key 和网络配置正常返回内容中会有一个choices数组里面是模型生成的回复。如果返回 401说明 Key 有问题如果返回 404说明模型名或者 URL 路径不对。4.3 在 HA 中接入对话 Agent当 API 验证通过后就可以在 Home Assistant 中添加集成。推荐使用 UI 方式添加打开 HA进入“设置 - 设备与服务”。点击右下角的“添加集成”。搜索OpenAI Conversation。填写 DeepSeek 的 API Key。在模型名称中填deepseek-chat。在支持自定义 API Base URL 的版本中将地址填为 DeepSeek 的 base_url也就是https://api.deepseek.com。如果你的版本没有该字段说明当前 UI 不支持自定义地址请参考 4.4 使用脚本方案。不同 HA 版本的集成配置项会有差异。核心思路是API Key 填 DeepSeek 的 Key模型名填 DeepSeek 的模型名API Base URL 填 DeepSeek 的地址。这三项都正确模型就能被成功调用。4.4 使用脚本方式接入跨版本通用方案如果 HA 版本不支持在 OpenAI Conversation 集成里修改 base_url可以退一步用脚本方式把 DeepSeek 封装成一个 HA 服务。这里以 Python 脚本为例演示如何使用requests库调用 DeepSeek API。在 HA 配置目录下创建scripts/ask_deepseek.py#!/usr/bin/env python3 import requests import sys API_KEY YOUR_DEEPSEEK_API_KEY BASE_URL https://api.deepseek.com/chat/completions MODEL deepseek-chat def ask_deepseek(message: str) - str: headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { model: MODEL, messages: [ {role: system, content: 你是一个智能家居助手请用简洁的中文回答用户问题。}, {role: user, content: message} ], temperature: 0.7, stream: False } resp requests.post(BASE_URL, jsonpayload, headersheaders, timeout30) resp.raise_for_status() data resp.json() return data[choices][0][message][content] if __name__ __main__: if len(sys.argv) 2: print(Usage: ask_deepseek.py message) sys.exit(1) print(ask_deepseek(sys.argv[1]))然后在configuration.yaml中注册一个shell_commandshell_command: ask_deepseek: /config/scripts/ask_deepseek.py {{ message }}重启 HA 后可以在“开发者工具 - 服务”里找到shell_command.ask_deepseek服务调用时传入参数message: 今天适合开窗吗服务会返回 DeepSeek 的回复。这种方法虽然不能直接在 Assist 面板中形成连续对话但把大模型能力封装成了 HA 的标准化服务后续做自动化联动时会非常方便。4.5 验证对话效果配置完成后在 HA 概览页点击右下角的对话按钮进入 Assist 面板。在左上角选择刚才配置的对话 Agent输入测试内容。如果一切正常会收到 DeepSeek 的文本回复。如果收到的回复来自默认的 HA 助手、而不是 DeepSeek说明 Assist 仍然绑定在原对话 Agent 上需要在对话 Agent 下拉菜单中切换到新的模型。5. 方案二通过 Ollama 本地部署 DeepSeek 接入5.1 本地部署的核心价值在线 API 虽然方便但有一个天然特点所有对话内容和设备状态数据都会发送到云厂商服务器。对于注重隐私的家庭场景这是一道坎。本地部署后模型运行在自己的机器上外部网络中断也不影响家庭自动化使用长期运行成本也更可控。代价是硬件要求和响应速度。一个 7B 量级模型在普通 CPU 机器上思考速度较慢推理一个完整回答可能需要几秒到几十秒。如果你对响应延迟敏感在线 API 体验会更好。5.2 安装 Ollama 并拉取模型Ollama 的安装方式以官方文档为准。安装完成后先确认服务状态ollama --version ollama serve然后拉取 DeepSeek 模型ollama pull deepseek-r1:7b拉取完成后可以通过命令行简单测试ollama run deepseek-r1:7b 你好介绍一下你自己如果命令行能正常回答说明 Ollama 模型已经可用。Ollama 默认监听在11434端口HTTP API 地址为http://主机IP:11434稍后 HA 配置时要用到。5.3 在 HA 中配置 Ollama ConversationHome Assistant 官方提供了 Ollama 集成配置过程相对简单进入“设置 - 设备与服务”。添加集成搜索Ollama。填写 Ollama 服务地址比如http://192.168.1.100:11434。选择要使用的模型比如deepseek-r1:7b。在对话 Agent 中选择该模型并测试。如果你希望用 YAML 配置也可以参考下面这段思路ollama: host: http://192.168.1.100:11434注意HA 不同版本对 Ollama 集成的配置字段支持不同。如果 YAML 配置不生效优先使用 UI 添加集成。5.4 验证本地对话在 Assist 面板选择 Ollama 对应的对话 Agent输入一段自然语言测试。由于本地模型没有联网搜索能力问题最好集中在常识问答、语义理解类内容不要提问实时新闻或需要外部资料的问题。如果 HA 提示连接失败优先检查 Ollama 服务是否运行以及 HA 主机到 Ollama 主机的网络是否连通。可以在 HA 主机上用 curl 测试 Ollama 接口curl http://192.168.1.100:11434/api/tags能正常返回模型列表说明网络层没有障碍。6. 进阶让 AI 真正控制你的智能家居6.1 从“聊天”到“控制”的架构变化让 AI 回复文本只是第一步真正有价值的是让 AI 根据用户意图去控制设备。在 Home Assistant 中这通常依赖“工具调用”能力。简单说大模型不仅可以生成文字还可以输出一个结构化的调用指令随后由 HA 执行对应的服务调用。例如用户说“把客厅灯调暗一点”模型可能返回一个调用light.turn_on服务的指令参数为entity_id: light.living_room和brightness: 100。HA 拿到这个指令后真正执行开关动作的是 HA 自己模型只负责决策不直接接触硬件。需要注意工具调用能力是否可用取决于两个因素模型本身是否支持 function calling。HA 版本是否将服务列表和实体信息传入给对话模型。DeepSeek 是否支持工具调用、以及在当前 HA 版本中是否能正确传参建议以官方文档和实际测试为准。如果模型不支持自动工具调用可以退一步使用“意图映射”方案见 6.3。6.2 通过 Prompt 约束 Agent 行为不管模型是否支持自动工具调用Prompt 都是整个接入方案的关键。在 OpenAI Conversation 或 Ollama Conversation 中通常可以设置系统提示词。下面是一个家庭助手场景的 Prompt 示例你现在是家庭智能管家。你可以控制以下实体 - 客厅灯switch.living_room_light - 卧室空调climate.bedroom_ac - 阳台窗帘cover.balcony_curtain 规则 1. 用户请求操作设备时先确认是非常明确的指令。 2. 如果用户表达模糊请先询问清楚再执行。 3. 禁止执行任何涉及门锁、燃气、热水器等高风险设备的操作。 4. 回答尽量简洁使用中文。这段 Prompt 的核心作用是划定 AI 的“行动边界”。没有边界时模型可能会在不确定的情况下执行动作非常危险。建议把可控制实体的清单写在系统提示词里而不是让模型自己猜测。6.3 通过自动化脚本实现“语义控制”如果你觉得自动工具调用不够可靠还有一种更可控的思路让模型只做“意图理解”由 HA 自动化执行动作。具体做法是创建一个自动化监听文本类型的传感器或输入框。当有新的用户指令进来时调用 DeepSeek API让它输出固定的 JSON 格式指令例如{intent: turn_on, entity: living_room_light}在自动化脚本中解析 JSON映射到 HA 服务调用。这种方式的优点是逻辑完全可控模型即使偶尔抽风也不会直接触发危险操作。缺点是需要自己写解析脚本。下面是一个简单的解析思路import json raw_output {intent: turn_on, entity: living_room_light} try: action json.loads(raw_output) intent action.get(intent) entity action.get(entity) print(f要执行的动作: {intent}, 实体: {entity}) except json.JSONDecodeError: print(模型输出不是合法 JSON需要重新请求)6.4 安全边界设计接入 AI 控制设备后安全边界必须优先设计。首先模型不应该拥有全部设备的控制权限。在 HA 中可以给对话 Agent 配置可访问的实体范围建议按房间或设备类型分组授权。其次高风险设备要单独处理。指纹锁、燃气阀门、烘干机这类设备无论模型如何理解都不建议交给 AI 自动执行。可以在自动化中增加二次确认机制比如 AI 控制前先发送确认消息用户回复“确认”后才真正执行。最后所有 AI 触发的执行动作都要留日志。可以在自动化里添加事件记录或者把调用内容发送到群晖、Telegram 等通知渠道。这样做不是多此一举而是为了出问题时能快速定位。7. 常见问题与排查7.1 高频报错排查表下面这张表汇总了接入过程中最常见的几类问题先看表了解大概方向再继续看具体展开。问题现象常见原因解决思路返回 401 UnauthorizedAPI Key 错误、过期或复制多了空格重新创建 Key粘贴时检查前后空格返回 402 Payment Required账户余额不足给模型平台账户充值返回 404 Not FoundURL 路径错误、模型名不存在核对 base_url 和模型名返回 429 Too Many Requests请求频率过高或额度用完降低请求频率检查限流策略请求超时网络无法访问 API或代理配置异常检查 HA 主机到 API 服务的连通性HA 无法找到集成HA 版本过旧升级 HA 到最新稳定版Ollama 连接失败Ollama 服务未启动、端口不同、网络不通检查 ollama serve 状态和网络连接7.2 模型不回复或回答奇怪如果 API 调用成功但返回内容为空或回答内容跟问题完全不相关通常是 Prompt 问题或模型参数问题。先检查温度参数。温度太高会导致回答随机性变大建议控制在0.7以下。再检查系统提示词是否与用户问题冲突。如果系统提示词要求“只能回答关于天气的问题”用户问“帮我把灯打开”模型当然答非所问。在 HA 中接入对话 Agent 后如果模型始终不调用工具可以在开发者工具中查看模型返回的完整内容确认是模型没有生成工具调用还是 HA 没有正确解析。这个排查方向非常关键。7.3 关于“配置文件无法加载”的问题很多使用本地客户端或命令行工具接入大模型的同学会遇到config.toml无法加载、对话串无法恢复的问题。这类问题本质上是配置文件中model字段填写的模型名与当前模型平台不匹配。举例来说如果你在本地工具中写的是 ChatGPT 之外的模型名但 API 地址仍然是 ChatGPT 的地址工具会认为模型不受支持从而拒绝加载配置。修正方法是让“模型名”和“base_url”保持对应关系调用 DeepSeek 时使用 DeepSeek 的 base_url 和deepseek-chat等模型名。调用 OpenAI 时使用 OpenAI 的 base_url 和对应的 GPT 模型名。这个原理在 HA 中同样适用因此在排查 HA 对话 Agent 问题时先确认“模型名 base_url API Key”三者是否来自同一个模型平台。8. 最佳实践与工程建议8.1 API Key 与敏感信息管理API Key 是敏感信息永远不要直接硬编码在configuration.yaml中。HA 提供了secrets.yaml机制用来集中管理密钥。# configuration.yaml shell_command: ask_deepseek: /config/scripts/ask_deepseek.py {{ message }}对应的secrets.yaml中虽然存储的是 shell_command 参数但更好的做法是把 Python 脚本中的 API Key 也读取自环境变量或单独的秘密文件避免明文出现在可被其他人读到的配置里。import os API_KEY os.getenv(DEEPSEEK_API_KEY, fallback-key)如果你的 HA 有备份同步到 Git 仓库务必通过.gitignore把秘密文件排除掉。8.2 成本与 Token 控制在线 API 按 Token 计费虽然单次对话成本很低但家庭环境 7x24 小时运行大量自动化调用累积起来也是一笔费用。控制成本的关键在于“减少不必要的上下文”。每次调用 API 时不需要把整个家庭历史对话都发给模型只传递最近的几轮对话即可。在 Prompt 设计上尽量让模型使用简洁回复风格。在 API 请求参数中设置max_tokens上限避免模型生成超长回答也是有效的成本控制手段。DeepSeek 开放平台支持查看调用量和余额消耗建议定期关注。8.3 Prompt 与上下文工程Prompt 设计的核心不是“让模型更强”而是“让模型知道边界”。同样的 DeepSeek 模型在不同 Prompt 下的行为差异会非常明显。家庭场景中建议把以下内容固化到系统提示词中可控制的实体清单和对应的 entity_id。禁止操作的设备和命令。模糊指令时的默认处理方式先询问不执行。回复语言风格。回答中是否允许输出 JSON。在实际项目里Prompt 不是写一次就结束了。你可能会遇到模型在某些场景下表现不稳定这时候要针对失败案例不断迭代 Prompt。建议为每次调用保留日志记录用户问题、模型回复、以及是否成功执行动作。8.4 可用性与容灾设计在线 API 和本地模型各有优势实际使用时可以设计成双通道。比如默认走 DeepSeek 在线 API当 API 连续调用失败时自动降级到本地 Ollama 模型。在 HA 中实现这种降级可以在自动化中检测 API 调用的返回状态。如果返回 429 或超时再调用本地模型接口。这样既保证了日常体验也避免外部服务抖动导致整套智能家居对话能力瘫痪。要注意不要让自动化进入死循环。建议在降级方案中增加“熔断”机制即短时间连续失败 N 次后停止自动重试等待人工介入或延迟一段时间后再恢复。9. 总结与下一步学习建议这篇文章围绕 Home Assistant 接入 AI 大模型做了完整的方案拆解核心内容可以概括为四点在线方案通过 OpenAI 兼容 API 接入 DeepSeek适合快速体验和大多数家庭场景。本地方案通过 Ollama 本地部署 DeepSeek 模型适合隐私敏感或网络不稳定的环境。控制能力让 AI 从“聊天”升级为“控制设备”关键在于工具调用、Prompt 边界和自动化兜底。工程实践API Key 管理、成本控制、安全边界和容灾设计决定了这个功能能否长期稳定运行。如果你目前还没有在 HA 中接入过任何大模型建议先从第 4 节的在线 API 方案开始跑通后再去尝试本地部署。等这两条路线都熟悉了再研究 HA 的自定义对话组件开发、Function Calling 的高级用法以及通过 RAG 让 AI 更理解你的家庭设备配置。接入大模型不是终点让它在合适的场景里帮你做正确的事才是更有意思的部分。如果这篇文章帮到了你可以收藏备用后续遇到报错也可以回来对照排查。