HomeAssistant 接入 ChatGPT、DeepSeek 这类 AI 大模型，核心链路其实只有三步：把设备状态整理成文本，把文本发给大模型接口，再把返回结果用起来。我按自己实际调试时的顺序来拆，从环境准备、最小请求、自然语言控制到安全边界都会过一遍。适合已经把 HomeAssistant 跑起来、但还没接过外部 API 的读者，也适合想给自动化加一个能说话、能分析、能给建议的入口的人。
很多人以为“接入大模型”就是让 HA 界面上多一个聊天框，其实更准确地说，是给自动化增加一个新的服务接口。HA 原本的自动化是固定规则：传感器超过阈值就开灯。接入大模型之后，可以把规则变成“用自然语言问一段上下文，拿返回结果”，再决定下一步。所以最该关注的不是聊天框，而是你有没有稳定的设备状态文本，以及能否安全地把结果转换成动作。
1. 先搞清楚：HA 接大模型，到底接的是什么
1.1 三种典型用法，先选一种落地
第一种是自然语言问答和建议。比如“我现在感冒了，卧室温度合适吗”“这周能耗有没有异常”。这种场景只需要 HA 把关键实体状态拼成一段文本，发给大模型，再把模型返回的文本显示出来。工程量最小，适合第一次打通流程。
第二种是半自动控制指令。模型不直接回答“好的”，而是返回结构化指令，比如把“客厅灯太亮”转换成“把亮度调到 60%”。HA 拿到这段结构后，再调用对应服务去执行。这种形式体验更好，但需要模型输出稳定、需要指令校验，还要处理解析失败的情况。
第三种是日志分析和通知改写。把传感器历史、报警信息或设备异常状态喂给模型，让它生成一段简明摘要或下发通知。这种做起来不难，但要特别注意上下文长度。历史数据动不动就会超过几千 token，成本高不说，响应也慢。
我的建议是：先选第一种，跑通后再考虑第二种。不要一开始就把三种需求混在一起做，否则出了问题很难判断是接口问题、数据问题还是控制逻辑问题。
1.2 哪些场景不该硬上大模型
大模型不是万能开关。低延迟控制、安全关键控制、离线也必须可用的设备控制，不应该依赖外部 API 来完成。比如门锁、报警器、燃气阀这类设备，必须保留原有的自动化、物理开关或本地规则。
原因很直接：外部 API 有网络延迟、服务商限流、模型输出不稳定。一次请求正常一到十几秒，中间还可能超时或返回格式错乱。这个特性决定了它更适合做“慢决策”，而不是“实时保护”。
如果只是想用语音助手执行固定指令，比如“打开客厅灯”“关空调”，HA 内置的意图和场景已经够用，不一定要接大模型。接大模型意味着引入不确定性和外部依赖，同时也要承担对应成本。
1.3 ChatGPT 和 DeepSeek 在接入层怎么选
在 HA 接入层，这两个不是“两个完全不同的世界”，而是同一个调用模式下的不同服务商。它们都提供 HTTP API，都需要 API Key、模型名、请求体。差异通常在于模型上下文长度、价格、响应速度、是否支持函数调用，以及你的服务账号是否可用。
我的建议是：初期不要同时接多个。先选一个能顺利拿到 Key、文档看得明白、成本可控的，把“发请求-拿结果-显示结果”这条链路跑通。跑通之后再增加第二个模型。不要因为听别人说某个模型效果好，就直接从最复杂的对话方案开始。接入成功与否，更多取决于你的环境配置，而不是模型名气。
2. 接入前，把环境、Key 和路径整理好
2.1 HA 部署方式和网络连通性
需要先确认三件事。
第一，HA 当前版本能正常使用。无论是 HAOS、Docker 还是 Supervised，只要能编辑configuration.yaml或安装集成，就可以继续。
第二，HA 所在机器能访问模型服务商的 API 地址。你可以在 HA 宿主机上先用curl测一下，能拿到返回再回 HA 配置。如果curl都连不上，那就是网络链路的问题，不是 HA 配置的问题。
第三，系统时间同步正常。时间偏差过大会导致 TLS 证书校验失败，报错看起来像网络问题，实际是证书过期或时间不对。
curl -X POST "https://api.example.com/v1/chat/completions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "your-model-name", "messages": [{"role": "user", "content": "ping"}]}'这里的地址、模型名、Key 都要替换成你实际服务商提供的值。能正常返回 JSON，再往下走。
2.2 准备 API Key 和三个关键信息
去模型服务商控制台创建 API Key，建议记下三个信息：
- API Base URL：用于拼接聊天补全接口。示例里我会用
https://api.example.com/v1，落地时换成服务商文档提供的地址。 - Model 名称：服务商控制台里点开的具体模型标识。很多接入失败都是模型名写错。
- API Key：请求头
Authorization: Bearer <key>里使用。
Key 不要写进自动化配置文件的公开部分。HA 支持secrets.yaml，把 Key 放进去，configuration.yaml里用!secret xxx引用。我见过一些示例把 Key 直接贴在配置里，然后整个仓库被提交到 git 上，过几天就被扫描工具盗刷。这个问题一定要避免。
官方文档如果没有明确说明某个参数，以你当前服务商的接口文档为准。我没法给你一个所有平台通用的版本号或模型名，因为这类信息变化太快。稳妥做法是拿到账号后先做一次最小调用，确认字段格式。
2.3 三条接入路径，先低配后高配
| 路径 | 适合场景 | 优点 | 缺点 |
|---|---|---|---|
| REST Command | 快速验证、单轮调用 | 配置简单，任何 HA 版本都能用 | 无对话记忆，文本解析弱 |
| Conversation / Assist | 自然语言对话、语音助手 | 交互体验完整，可扩展 | 自定义设备控制需要额外配置 |
| Node-RED / 自建服务 | 多轮对话、工具调用、批量处理 | 灵活，可做鉴权和限流 | 开发和维护成本高 |
新手路径我建议这样走：先用 REST Command 证明链路能通，再用 Conversation 提升体验，最后才考虑自建服务。很多场景根本还没到需要独立服务那一步，过早引入复杂架构反而增加排错难度。
3. 第一步：用一条 HTTP 请求把大模型拉进 HA
3.1 在 configuration.yaml 中定义 rest_command
以 OpenAI 兼容接口为例，最小配置如下。不同服务商的字段名可能略有差异，但基本结构都是 URL、Header、Payload。
# configuration.yaml rest_command: ask_ai: url: "https://api.example.com/v1/chat/completions" method: "POST" headers: Authorization: "Bearer YOUR_API_KEY" Content-Type: "application/json" payload: >- {"model": "your-model-name", "messages": [{"role": "user", "content": "{{ message }}"}], "max_tokens": 300}配置完成后重启 HA，或者重新加载配置。如果加载成功，在开发者工具-服务里应该能看到rest_command.ask_ai。
这里我要解释一下为什么用rest_command而不是直接在 shell 里写curl。因为rest_command会把 HTTP 请求封装成 HA 服务，之后可以被自动化、脚本、前端按钮反复调用，也会进入 HA 的日志系统。排查时能看到调用记录，比散落在系统里的 curl 命令干净很多。
3.2 用 automation 或 script 完成一次真实调用
先写一个测试脚本，不要加任何复杂逻辑。
alias: Test Ask AI sequence: - service: rest_command.ask_ai data: message: "请用一句话介绍 HomeAssistant"如果你的 HA 版本支持response_variable，可以把响应内容写入一个input_text实体，这样能在前端直接看到结果。
alias: Test Ask AI and Show sequence: - service: rest_command.ask_ai data: message: "请用一句话介绍 HomeAssistant" response_variable: ai_result - service: input_text.set_value data: entity_id: input_text.ai_result value: "{{ ai_result.content }}"如果版本不支持response_variable，也不需要卡住。最简单的替代方案是先把返回内容打印到日志，或者用command_line传感器定期执行 curl，把输出写到传感器里。核心目标只有一个：先看到一行真实返回，再继续做后续优化。
3.3 怎么判断这一步已经成功
成功标准不是“不报错”，而是同时满足几个条件：
- HA 日志中没有 timeout、401、404 这类错误。
- 在 HA 前端能看到模型返回的具体文本。
- 服务商控制台能查到一次成功调用记录。
- 连续调用两三次，返回正常，不存在偶发为空或卡住。
这里要多说一句：不要一上来就调复杂提示词。我一般会先用“一句话介绍自己”这种极简输入验证链路。链路通了，再逐步加上设备状态和场景描述，每一步都好定位问题。
4. 从“能返回文本”到“能自然语言对话”
4.1 理解 HA 的会话流程
HA 的 Assist 本质上处理的是：输入文本、识别意图、返回回答或执行服务。如果接入大模型，就是把中间的意图识别换成了一次模型调用。
如果你只是想要一个聊天入口，常见做法是安装支持 OpenAI 兼容接口的对话集成。在集成配置里填三个字段：Base URL、API Key、Model 名称。有些集成可能还会要求填系统提示词。
系统提示词里我建议明确写清楚两件事：一是设备状态如何组织，二是模型只能建议、不能直接执行安全操作。比如“你是一个智能家居助手，只能回答和建议，不能声称自己已经执行了门锁操作”。这句话能在早期避免很多误判。
4.2 使用 OpenAI 兼容配置时的注意事项
很多服务商都提供 OpenAI 兼容的聊天补全接口，但 HA 里的第三方对话集成质量参差不齐，配置字段可能不统一。常见问题有：
- 把服务商文档里的“模型名称”和集成界面上的“模型 ID”填混。
- Base URL 末尾带不带
/v1，导致拼接出来的路径错误。 - 系统提示词太长，导致每次请求 token 数飙升，响应变慢。
我建议先用外部工具验证接口，把参数确认无误，再填到 HA 里。这样做可以把问题分成两类：一类是接口本身的问题，另一类是 HA 集成配置的问题。如果你直接依赖 HA 页面去试错，日志信息通常不够直观。
4.3 让模型真的能“操作设备”：工具调用思路
严格说，让模型直接发一句“好的，已开灯”是不可靠的。它可能把灯名写成你从没定义过的别名，也可能生成一个不存在的参数。更稳妥的方案是走工具调用或函数调用。
第一步，提供一份设备状态摘要给模型，比如“客厅灯: on, 亮度: 80, 空调温度: 24”。
第二步，提供一组可供调用的函数，比如set_light(entity_id, brightness)和set_climate_temperature(entity_id, temperature)。
第三步，让模型返回结构化 JSON，例如：
{ "action": "set_light", "params": { "entity_id": "light.living_room", "brightness": 60 } }第四步，HA 侧先校验entity_id是否在白名单里，再执行服务。如果解析失败，直接丢弃并记录日志，不要试图硬解析。
这一步是整个接入中最花时间的地方。前两步用提示词和模板能解决，第三步要求模型支持工具调用，第四步需要你在 HA 自动化或 Node-RED 里写一个解析校验节点。建议从“只允许操作客厅灯、窗帘”这种低风险设备开始，不要一上来放开所有服务。
5. 真正长期跑，要管住频率、成本和权限
5.1 别让自动化变成“无限制 API 调用器”
自动化触发的频率可能远大于你的预期。比如温湿度传感器每五分钟变化一次，如果你写了“湿度变化超过 5% 就调用模型分析”，一天可能几十次。
有三个保护手段比较有效：
- 调用前判断设备状态是否真的变化到了需要分析的程度。
- 用
input_boolean做总开关，或者用时间窗口做节流，防止短时间重复调用。 - 在服务商后台设置调用量和预算告警。
如果是语音助手场景，也要注意。用户每说一句话，系统都可能把之前的多轮上下文重新带给模型，长上下文会让 token 消耗很快。这个不像自动化那么好控制，需要定期看用量。
5.2 缩短上下文，是控制成本和稳定性的关键
接入大模型后，很多问题其实不是“模型不好”，而是“喂给模型的文本太乱”。设备状态可以自动拼，但绝不是拼得越长越好。
建议这样做：
- 只挑选当前场景相关的实体，不要把几百个实体全部塞进去。
- 状态模板尽量精简，比如“客厅灯亮度 80%”，而不是
sensor.living_room_light_brightness = 80。 - 长时间历史数据用聚合摘要代替，避免把几万 token 的原文直接发给模型。
每次请求的 token 既包括输入，也包括输出。输入越长，费用越高，响应也可能越慢。早期测试最好把上下文控制在 1000 token 左右，先把效果调对，再去扩展上下文长度。
5.3 安全边界：模型返回结果必须被校验
我坚持一个原则：大模型的输出只能作为“建议”，不能作为唯一决策来源，尤其是在安全相关设备上。
具体落地时：
- API Key 放
secrets.yaml，不要在日志和前端页面里明文展示。 - 解析模型返回的 JSON 时，用白名单校验 action 和
entity_id。 - 模型返回无法解析或不在白名单内，直接丢弃并记录日志，不要尝试“智能修正”。
- 门锁、报警、燃气、遮阳设备保留原有自动化，不把控制权交给模型。
这不是保守，而是外部大模型的 API 特性决定了它会有不稳定输出、限流和中断。工程上必须把这种不确定性隔离在安全边界之外。
6. 报错排障和边界：多数问题不在模型，而在配置
6.1 一套通用的排查顺序
| 现象 | 先查什么 | 再查什么 |
|---|---|---|
| 调用后日志无反应 | rest_command是否加载，服务名是否正确 | 自动化是否真的触发，触发条件有没有满足 |
| 401 Unauthorized | API Key 是否正确，有没有 Bearer 前缀 | Key 是否过期，服务商账号是否有余额 |
| 404 Not Found | API Base URL 拼接是否正确 | 模型名是否在服务商模型列表里 |
| 429 Too Many Requests | 调用频率是否太高 | 账号额度、限流策略 |
| 超时 | 网络连通性、DNS 解析、防火墙 | 上下文长度、模型负载 |
| 返回空内容 | 请求体 messages 格式是否正确 | 返回结果里取值字段是不是写错 |
我自己的习惯是：先翻home-assistant.log，如果有红字就直接看时间和服务名。如果日志干净，再在开发者工具里手动调用服务，看它到底返回了什么。最后再用独立 REST 工具复现一遍，把 HA 隔离在外。这个顺序能最快定位问题。
6.2 几个容易被忽略的坑
YAML 缩进错误是最常见的。payload 写错层级时，加载配置可能不立刻报错，调用时才发现。
中文字符编码也可能出问题。在自动化里拼接中文时，确保 HA 配置文件使用 UTF-8 编码，否则模板渲染后可能出现乱码。
模型名写错是另一个高频问题。服务商控制台显示的名字和代码里的模型 ID 不一定完全一样，必须从官方接口文档里复制。
还要注意时间同步。HA 宿主机时间不对，TLS 证书校验会失败，报错却像网络超时。检查系统时间，比反复改超时配置更有效。
如果 HA 前端提示服务不存在，大多数时候不是 API 问题，而是集成没加载或 YAML 没有生效。先看配置是否正确加载，再查调用。
6.3 边界：HA 是自动化平台，不是模型网关
如果你只是给自己家里用，在 HA 里直接配置完全够用。但如果你想做一个对外服务，给多个用户或 App 使用，不要把 HA 当成模型网关。它没有内置熔断、计费、多租户、精细限流这些能力。
更合理的做法是在 HA 外面单独跑一个轻量服务，把模型调用、日志、鉴权和限流都放在那层，HA 只作为自动化前端。这样即使模型接口出问题，也不会影响智能家居核心状态。
另外，多个模型同时接入不是必须的。很多团队先接一个模型验证，再切另一个。切换时重点关注模型名、Base URL、上下文长度和函数调用格式，不要只凭响应文本的观感判断。
我自己调这类接入时，通常会把目标拆成三个阶段：第一步让日志里出现一次成功的 HTTP 返回，第二步让返回文本出现在 HA 面板上，第三步才考虑多轮对话和设备控制。很多卡住的情况，复盘时都会发现是前期同时改了太多环节。先把单个请求跑稳，再逐步加复杂度，这个顺序在 HomeAssistant 接入大模型的场景里，比任何具体参数都重要。
