HomeAssistant 接大模型，不是把 ChatGPT 塞进 HA 那么玄乎，本质就是让智能家居中枢多一个会自然语言对话、能理解传感器状态、还能在自动化里做判断的大脑。DeepSeek 因为提供 OpenAI 兼容接口、国内访问体验好、API 价格相对可控，是当前比较适合和 HA 一起用的云端大模型之一。如果你手上有 OpenAI 的 Key，也可以用同样的思路接入 ChatGPT。
这篇文章不打算讲复杂的概念，只回答几个实际问题：HA 接入大模型要准备什么，DeepSeek 和 ChatGPT 怎么选，API Key 拿到之后在哪里配，配完怎么验证，怎么接语音助手，怎么让大模型在自动化里干活，以及最容易踩的坑。
先给结论：如果你的 HA 已经跑在 Docker 或树莓派上，接入 DeepSeek 的配置成本大概只有几分钟。难点不在接入本身，而在安全边界和对话代理的权限控制。下面从核心能力开始，逐步拆解部署、配置、测试和排查。
1. HomeAssistant 接入 AI 大模型核心能力速览
| 能力项 | 说明 |
|---|---|
| 项目类型 | 智能家居平台 + 大模型对话能力接入 |
| 核心功能 | 自然语言控制设备、传感器问答、语音助手、自动化联动、家庭报告生成 |
| 支持模型 | ChatGPT（OpenAI 兼容接口）、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 本身是健康可用的。这里给一份通用的前置检查清单。
- 已经部署 HomeAssistant，Web 界面能正常访问，默认端口是 8123。
- 拥有 HA 管理员权限，可以打开“设置”和“开发者工具”。
- HA 所在机器能够访问大模型 API 地址。DeepSeek 在国内访问一般没问题；ChatGPT 需确认你的使用环境符合 OpenAI 的服务条款和当地法律法规。
- 准备好 API Key，并确定要使用的模型名称。
- 建议先准备独立的测试环境，不要在正式生产实例上直接改。Docker 是很方便的选择。
如果你还没有 HA，可以用 Docker 快速起一个实例。以下命令是常见写法，具体路径需要按你的机器调整。
docker run -d \ --name homeassistant \ --privileged \ --restart=unless-stopped \ -e TZ=Asia/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 URL：
https://api.deepseek.com - 接口路径：
/chat/completions（OpenAI 兼容格式） - 模型名：常见为
deepseek-chat，实际可用模型以官方模型列表为准 - 认证方式：
Authorization: Bearer <你的 API Key>
首次使用还需要确认账户余额。DeepSeek 是预付费模式，账户余额不足时会直接报鉴权或配额错误。
4.2 ChatGPT / OpenAI API 准备
OpenAI 平台中创建 API Key 后，需要注意以下信息：
- Base URL：
https://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 Key"4.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 / ChatGPT
HomeAssistant 自带的 OpenAI Conversation 集成，是用 OpenAI 兼容接口接入大模型最直接的方式。DeepSeek 因为兼容 OpenAI 接口，所以也可以用这个集成来对接，只是 Base URL 和模型名需要改成 DeepSeek 的。
5.1 UI 方式添加集成
操作路径：设置 -> 设备与服务 -> 添加集成 -> 搜索“OpenAI Conversation”。
添加时主要填写这几个字段：
- API Key：填写 DeepSeek 或 OpenAI 的 Key
- Base URL：DeepSeek 填官方 OpenAI 兼容地址，OpenAI 填官方地址
- Model：模型名称，如
deepseek-chat、gpt-4o-mini - Temperature：控制回答随机性，建议先默认
- 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": f"Bearer {API_KEY}", "Content-Type": "application/json", }, json={ "model": "deepseek-chat", "messages": [{"role": "user", "content": prompt}], "temperature": 0.7, }, timeout=timeout, ) 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 Unauthorized | API 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 found；Base URL 写成网页地址而忘了用 API 接口地址；rest_command返回的 JSON 字段解析方式不对。前两个用 curl 就能排查，第三个建议在开发者工具里逐层输出原始返回，再写解析模板。
后续可以继续扩展的方向不少。如果不想依赖云端，可以在 HA 里接本地 Ollama 模型，适合对隐私要求更高的场景；如果想做更复杂的 Agent 流程，可以配合 Node-RED 编排多轮对话和工具调用；如果希望 HA 自动生成每日设备报告、能耗分析、家庭日志，可以把第八节的 Python 批量脚本写成定时任务，和 HA REST API 联动。先把基础链路跑通，后面扩展会顺很多。
