HomeAssistant 接大模型不是把 ChatGPT 塞进 HA 那么玄乎本质就是让智能家居中枢多一个会自然语言对话、能理解传感器状态、还能在自动化里做判断的大脑。DeepSeek 因为提供 OpenAI 兼容接口、国内访问体验好、API 价格相对可控是当前比较适合和 HA 一起用的云端大模型之一。如果你手上有 OpenAI 的 Key也可以用同样的思路接入 ChatGPT。这篇文章不打算讲复杂的概念只回答几个实际问题HA 接入大模型要准备什么DeepSeek 和 ChatGPT 怎么选API Key 拿到之后在哪里配配完怎么验证怎么接语音助手怎么让大模型在自动化里干活以及最容易踩的坑。先给结论如果你的 HA 已经跑在 Docker 或树莓派上接入 DeepSeek 的配置成本大概只有几分钟。难点不在接入本身而在安全边界和对话代理的权限控制。下面从核心能力开始逐步拆解部署、配置、测试和排查。1. HomeAssistant 接入 AI 大模型核心能力速览能力项说明项目类型智能家居平台 大模型对话能力接入核心功能自然语言控制设备、传感器问答、语音助手、自动化联动、家庭报告生成支持模型ChatGPTOpenAI 兼容接口、DeepSeek、其他 OpenAI 兼容大模型推荐部署环境HAOS 主机、Docker、树莓派 4B 及以上、NAS、x86 小主机内存要求取决于实例规模和附加组件数量建议至少 2GB 以上空闲内存启动方式HomeAssistant 常规启动默认 Web 端口 8123接口能力HA 侧提供 REST / WebSocket API大模型侧使用 OpenAI 兼容 Chat Completions API批量任务可在自动化中定时批量调用对话服务需要自行设计限流和重试适合场景智能家居本地控制、语音交互、传感器数据分析、自动化决策辅助这张表想说明的是HA 接入大模型并不是把模型“装”进 HA 里而是让 HA 作为调度中枢通过 API 调外部大模型。模型部署在云端还是本地只影响延迟和成本不影响 HA 的配置结构。2. 适用场景与使用边界先说适合谁。已经在用 HomeAssistant、但觉得原生语音助手和自动化条件判断不够灵活的人是这类方案最直接的受益者。接入大模型后你可以对 HA 说“把客厅灯调到适合看电影的亮度”“今天室外空气质量怎么样”“根据当前室温给我一句开窗建议”HA 会把设备状态和传感器数据拼进提示词再由大模型给出回答或动作建议。其次是做自动化增强。传统自动化写的是“温度大于 28 度就开空调”这种确定性规则但很多决定需要上下文。大模型可以把天气、日历、人员在家状态、能耗数据综合起来生成一条更自然的建议再通过 HA 发通知或语音播报。家庭日志、能耗分析、每周设备使用报告这类任务也很适合批量交给大模型处理。再说边界。如果你的目标是低延迟和高可靠性大模型接入不一定合适。云端 API 有网络延迟和限流极端情况下可能超时本地跑模型则会明显占用 CPU 和内存。大模型还可能给出错误指令所以涉及门锁、摄像头、燃气阀等高危设备时不建议直接把控制权完全交给 AI。合规层面调用 OpenAI 或 DeepSeek 服务要遵守对应平台条款和你所在地区的法律法规不要把麦克风录音、摄像头画面、个人敏感信息直接提交到云端模型。API Key 一旦泄露可能造成费用损失和隐私问题必须当作密码管理。3. 环境准备与前置条件在配置大模型之前先确保 HA 本身是健康可用的。这里给一份通用的前置检查清单。已经部署 HomeAssistantWeb 界面能正常访问默认端口是 8123。拥有 HA 管理员权限可以打开“设置”和“开发者工具”。HA 所在机器能够访问大模型 API 地址。DeepSeek 在国内访问一般没问题ChatGPT 需确认你的使用环境符合 OpenAI 的服务条款和当地法律法规。准备好 API Key并确定要使用的模型名称。建议先准备独立的测试环境不要在正式生产实例上直接改。Docker 是很方便的选择。如果你还没有 HA可以用 Docker 快速起一个实例。以下命令是常见写法具体路径需要按你的机器调整。docker run -d \ --name homeassistant \ --privileged \ --restartunless-stopped \ -e TZAsia/Shanghai \ -v /path/to/your/config:/config \ -p 8123:8123 \ ghcr.io/home-assistant/home-assistant:stable启动后用浏览器访问http://主机IP:8123完成初始化配置确认 HA 能正常读取传感器和设备列表。这一步没跑通的话后面所有大模型配置都无从谈起。4. 获取大模型 API Key 与接口信息4.1 DeepSeek API 准备DeepSeek 开放平台注册后在控制台创建 API Key。DeepSeek 提供的是 OpenAI 兼容接口所以 HA 里很多以 OpenAI 为底座设计的集成都能直接复用。常用参数如下具体以 DeepSeek 官方文档为准Base URLhttps://api.deepseek.com接口路径/chat/completionsOpenAI 兼容格式模型名常见为deepseek-chat实际可用模型以官方模型列表为准认证方式Authorization: Bearer 你的 API Key首次使用还需要确认账户余额。DeepSeek 是预付费模式账户余额不足时会直接报鉴权或配额错误。4.2 ChatGPT / OpenAI API 准备OpenAI 平台中创建 API Key 后需要注意以下信息Base URLhttps://api.openai.com/v1接口路径/chat/completions模型名如gpt-4o-mini、gpt-4o具体以 OpenAI 官方可用列表为准认证方式Authorization: Bearer 你的 API Key无论使用 DeepSeek 还是 ChatGPT都要把 API Key 保存到 HA 的secrets.yaml中不要直接写在configuration.yaml里。这样既方便统一管理也避免配置分享时泄露密钥。# secrets.yaml 示例 deepseek_api_key: 这里填你的DeepSeek API Key openai_api_key: 这里填你的OpenAI API Key4.3 用 curl 验证 API 连通性配置 HA 之前先在命令行确认 API Key 和接口地址能通。下面是一个 DeepSeek 的连通性测试示例Windows 的 PowerShell 和 Linux/macOS 终端都可执行。curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的API Key \ -d { model: deepseek-chat, messages: [{role: user, content: 用一句话介绍你自己}] }返回结果里包含choices数组说明接口、Key 和模型名都没问题。这一步能帮你快速排除网络和鉴权问题避免后面把错误带到 HA 配置里。5. 通过 OpenAI Conversation 集成接入 DeepSeek / ChatGPTHomeAssistant 自带的 OpenAI Conversation 集成是用 OpenAI 兼容接口接入大模型最直接的方式。DeepSeek 因为兼容 OpenAI 接口所以也可以用这个集成来对接只是 Base URL 和模型名需要改成 DeepSeek 的。5.1 UI 方式添加集成操作路径设置 - 设备与服务 - 添加集成 - 搜索“OpenAI Conversation”。添加时主要填写这几个字段API Key填写 DeepSeek 或 OpenAI 的 KeyBase URLDeepSeek 填官方 OpenAI 兼容地址OpenAI 填官方地址Model模型名称如deepseek-chat、gpt-4o-miniTemperature控制回答随机性建议先默认Max Tokens限制回复长度需要注意的是不同 HA 版本对字段名称有差异有些版本用chat_model有些用model。如果你在 UI 里看不到某一个字段以你当前版本的界面为准。5.2 YAML 方式配置示例如果你更习惯用 YAML 管理配置可以参考下面的写法。实际键名需要根据 HA 版本微调这段用于说明配置思路。# configuration.yaml 示例片段 openai_conversation: - api_key: !secret deepseek_api_key base_url: https://api.deepseek.com chat_model: deepseek-chat temperature: 0.7 max_tokens: 500YAML 配置修改后需要点击“开发者工具 - YAML - 重新加载核心配置”或者直接重启 HA。5.3 测试对话代理配置完成后进开发者工具 - 服务调用conversation.process服务测试。service: conversation.process target: entity_id: conversation.openai_conversation data: text: 客厅现在温度是多少帮我简单回答。如果返回结果里能看到大模型生成的文本说明整个链路已经打通。如果没有优先检查 Base URL、模型名、API Key 三个位置。6. 通过 RESTful Command 实现自定义大模型接口调用官方 OpenAI Conversation 集成适合日常对话但它的返回结果不直接暴露给自动化解析。如果你想要更自由的控制比如把一堆传感器数据拼成提示词、调用大模型后把结果存成实体或发通知可以使用 HA 的 RESTful Command 集成。RESTful Command 本质上就是让 HA 在自动化里发 HTTP 请求。DeepSeek 和 OpenAI 都提供标准 Chat Completions 接口所以完全可以用这种方式自定义调用。6.1 定义 RESTful Command在configuration.yaml中添加如下配置。rest_command: ask_deepseek: url: https://api.deepseek.com/chat/completions method: post content_type: application/json headers: Authorization: Bearer !secret deepseek_api_key payload: - { model: deepseek-chat, messages: [{role: user, content: {{ prompt }}}], temperature: 0.7 }这里使用{{ prompt }}作为模板变量调用服务时动态传入用户问题。如果你同时接多个模型可以定义多个rest_command。6.2 在开发者工具中调用添加完成后重新加载 YAML 配置然后在开发者工具 - 服务中调用。service: rest_command.ask_deepseek data: prompt: 用一句话介绍 HomeAssistant 是什么调用成功后服务会返回大模型 API 的原始 JSON 字符串。你需要在模板中解析出回答内容。下面是一个常见的解析模板示例。{{ response_result.content[0].text }}这里有一点需要特别注意rest_command的返回值本质是字符串如果 API 返回的是转义后的 JSON你可能需要先判断是否能直接访问字段再用from_json等模板函数处理。实际字段结构以 API 返回为准。6.3 把设备状态拼进提示词RESTful Command 的优势是可以在提示词模板里直接读取 HA 状态。下面是一个把温度和湿度拼进提示词的例子。service: rest_command.ask_deepseek data: prompt: - 客厅温度当前是 {{ states(sensor.living_room_temperature) }} 度 湿度是 {{ states(sensor.living_room_humidity) }}%。 请用 30 字以内给我一句体感建议。这样 HA 就不再只是固定回答而是能根据实时传感器数据生成个性化建议。之后你可以把返回结果接入通知服务。下面是一个通知示例。service: notify.mobile_app_phone data: title: AI 环境建议 message: {{ response_result.content[0].text }}7. 语音助手与自动化场景联动HomeAssistant 原生语音助手由 Assist Pipeline 组成分为语音识别、对话代理、语音合成三段。把大模型接入对话代理之后语音交互自然就带上了大模型能力。7.1 配置 Assist Pipeline设置 - 语音助手 - Assist Pipeline新建或编辑一个管道。在“对话代理”中选择你已经配置好的 OpenAI Conversation 实体。语音识别和语音合成可以使用 HA 内置的本地组件也可以接你已经在用的云服务。配置完成后HA 的语音助手实体就可以使用。你可以在 HA 手机 App 里按住对话按钮说话也可以用 ESPHome 语音卫星或支持 Assist 的语音硬件来交互。7.2 自动化触发语音播报除了主动说话你还可以在自动化里触发语音播报。比如每天早间让大模型基于天气和通勤状态给出建议再用 TTS 播报到音箱。automation: - alias: Morning AI Briefing trigger: - platform: time at: 07:30:00 action: - service: rest_command.ask_deepseek data: prompt: - 现在是早上室外天气是 {{ states(weather.forecast_home) }} 请用 50 字以内给我今天的出行建议。 - service: tts.speak data: cache: true media_player_entity_id: media_player.living_room_speaker message: {{ response_result.content[0].text }}这个流程看起来不长但实际落地时有一个常见问题rest_command的返回值在自动化模板中不一定能直接取到content[0].text。新建自动化之前先在开发者工具里把模板解析跑通再接入语音播报会省去很多调试时间。7.3 大模型触发设备控制语音助手默认只回答文本。如果想让大模型真正控制设备比如听到“打开客厅灯”后执行light.turn_on通常有两种思路。第一种是让大模型输出结构化指令比如 JSON然后 HA 用模板解析指令后调用对应服务。第二种是结合 HA 的 Assist 能力让对话代理返回意图HA 再把意图映射到设备服务。实际配置会比较复杂这里不展开建议先跑通纯文本对话再逐步加控制逻辑同时做好权限控制。8. 接口 API 调用与批量任务设计8.1 HA 与大模型侧的接口关系你需要区分两组 API。第一组是 HA 对外提供的 API比如 HTTP REST API 和 WebSocket API可以让外部程序读取 HA 状态、触发服务。第二组是 HA 调用大模型的 API也就是 OpenAI 兼容的 Chat Completions 接口。平时大家讨论的“HA 接入 ChatGPT / DeepSeek”指的都是第二组。如果你希望其他程序也能向 HA 发起大模型对话可以直接调用 HA 的 REST API。下面是 curl 调用 HAconversation.process服务的通用示例需要把访问令牌替换成你自己的。curl -X POST \ -H Authorization: Bearer 你的HA长期访问令牌 \ -H Content-Type: application/json \ -d {text:客厅温度是多少} \ http://localhost:8123/api/services/conversation/process这个接口能跑通说明 HA 本地 API 和对话代理都正常。之后就可以把 HA 作为一个“会调用大模型的中枢”嵌入到更多系统里。8.2 批量任务设计批量任务最常见的需求是定期把一批传感器状态、设备变化、能耗数据汇总起来交给大模型生成报告。HA 的自动化定时触发器配合 RESTful Command已经能满足轻度批量场景。更复杂的批量任务建议用一个外部 Python 脚本配合 HA API 或直接调用大模型 API。下面是一个 Python 批量调用 DeepSeek 的通用示例实际运行时请把 API Key 放到环境变量中不要硬编码在代码里。import os import requests API_KEY os.environ.get(DEEPSEEK_API_KEY) URL https://api.deepseek.com/chat/completions def ask(prompt: str, timeout: int 30) - str: resp requests.post( URL, headers{ Authorization: fBearer {API_KEY}, Content-Type: application/json, }, json{ model: deepseek-chat, messages: [{role: user, content: prompt}], temperature: 0.7, }, timeouttimeout, ) resp.raise_for_status() return resp.json()[choices][0][message][content] if __name__ __main__: prompts [ 请总结今天客厅的温度变化趋势50字以内。, 请总结今天卧室的湿度变化趋势50字以内。, 请给出明天省电建议50字以内。, ] for prompt in prompts: try: print(ask(prompt)) except requests.exceptions.RequestException as e: print(f调用失败: {e})批量任务一定要设计限流和重试。常见做法是控制并发数为 1 到 5超时时间设置在 15 到 60 秒之间失败后指数退避重试。同时记录每次请求的 token 消耗和费用避免长时间跑批后账单超预期。9. 资源占用与性能观察HomeAssistant 本身是 Python 应用资源占用取决于实例规模、集成数量、传感器数量和历史数据库大小。如果你只是接云端大模型HA 本地增加的 CPU 和内存开销非常有限主要消耗发生在 HTTP 请求等待和 JSON 解析阶段。云端 API 的性能瓶颈通常在网络延迟和模型响应时间。DeepSeek 的响应时间会随着模型负载和提示词长度变化实测时应该重点观察两个指标从发起请求到返回结果的整体延迟以及大模型 API 返回的 token 使用量。HA 不会主动降低响应时间所以如果对话卡顿优先排查网络和 API 服务状态。如果你想观察 HA 容器的资源占用用 Docker 部署时可以直接执行docker stats homeassistant这个命令会输出 CPU、内存、网络 I/O 等信息。如果是 HAOS 或虚拟机部署可以在 HA 页面的“系统 - 诊断”里查看资源使用情况。接入本地模型则另说本地模型推理会持续占用 CPU 或 GPU显存和内存占用会明显升高。如果硬件不强还是建议用云端 API。10. 常见问题与排查方法问题现象可能原因排查方式解决方案conversation.process 返回“未配置对话代理”没有成功添加 OpenAI Conversation 或 agent_id 不对检查“设备与服务”中对应集成是否存在重新添加集成确认对话代理实体 ID报错 401 UnauthorizedAPI Key 错误或被撤销用 curl 单独测试 API重新生成 API Key更新到 secrets.yaml报错 model not found模型名填写错误对比官方模型列表修改为可用模型名如 deepseek-chat请求超时网络不通、API 过载或提示词过长curl 测试接口响应时间优化提示词、增加超时时间、错峰调用rest_command 解析不出 content返回报文不是预期结构或文本被二次转义在开发者工具里查看返回原文调整模板先输出原始返回值再逐步解析HA 页面打不开8123 端口被占用或服务未启动检查容器状态和端口占用换端口或重启 HA语音助手没有声音STT 或 TTS 组件未正确配置检查 Assist Pipeline更换 TTS 服务或检查音箱连接自动化调用大模型后没有后续动作rest_command 返回值在模板中解析失败在自动化里增加调试日志先用临时 notify 输出原始返回值很多人在把 DeepSeek 接入各类 OpenAI 兼容客户端时会遇到model、base_url或本地配置文件不匹配的问题。HA 里的思路其实是相通的先定位是 API Key 问题、接口地址问题还是模型名问题再用 curl 逐层验证比在 HA 页面里反复重试更高效。如果你正好在看 ChatGPT 桌面客户端或 Codex 之类的工具可能会遇到config.toml相关报错这通常是因为工具默认找的是 OpenAI 官方配置接入 DeepSeek 时需要把模型名和 Base URL 改过来。这个排查思路可以迁移到 HA只是配置文件的位置和格式不同。11. 最佳实践与合规使用建议API Key 管理是第一优先级。建议统一放到secrets.yaml不要提交到代码仓库更不要直接截图发到群里。对外分享 HA 配置片段时把 Key 换成占位符。建议先在小范围测试。接好大模型后不要立刻把所有高危设备都交给 AI 控制。可以先让大模型回答传感器状态、天气和日历问题确认行为稳定后再逐步增加设备控制。门锁、摄像头、燃气阀这类设备要单独做人工确认环节或者干脆不让大模型直接操作。调用频率要控制。云端大模型按 token 计费自动化如果设计成每分钟调一次成本会快速累积。建议给自动化增加冷却时间比如同一类报告每天只生成一次或者当传感器数据变化超过阈值时才触发大模型调用。日志和审计不能省。记录每次大模型请求的时间、提示词摘要、返回结果既方便排查问题也能在出问题时追溯。HA 的 logbook 只能记录自动化动作提示词本身不会自动记录需要你主动把调用参数写入文件或数据库。隐私和合规问题要重视。不要把家庭内网 IP、麦克风录音、摄像头画面、密码、身份证信息等发送到云端模型。使用 OpenAI 和 DeepSeek 等平台服务时要确认你所在地区对这些服务的使用要求遵守平台条款和当地法律法规。大模型的生成内容只能作为辅助判断涉及人身安全和财产安全的决定必须保留人工决策环节。12. 总结与下一步这套方案最值得尝试的点是 DeepSeek 的 OpenAI 兼容接口和 HA 的 OpenAI Conversation 集成能直接对接。只要你按顺序完成 API Key、Base URL、模型名三个配置再调用一次conversation.process验证链路整个接入就算跑通了。先验证对话再接语音助手最后再做自动化和批量任务这个顺序最不容易踩坑。最容易踩的坑有三个模型名写错导致model not foundBase URL 写成网页地址而忘了用 API 接口地址rest_command返回的 JSON 字段解析方式不对。前两个用 curl 就能排查第三个建议在开发者工具里逐层输出原始返回再写解析模板。后续可以继续扩展的方向不少。如果不想依赖云端可以在 HA 里接本地 Ollama 模型适合对隐私要求更高的场景如果想做更复杂的 Agent 流程可以配合 Node-RED 编排多轮对话和工具调用如果希望 HA 自动生成每日设备报告、能耗分析、家庭日志可以把第八节的 Python 批量脚本写成定时任务和 HA REST API 联动。先把基础链路跑通后面扩展会顺很多。