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 请求把大模型拉进 HA3.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 UnauthorizedAPI Key 是否正确有没有 Bearer 前缀Key 是否过期服务商账号是否有余额404 Not FoundAPI 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 接入大模型的场景里比任何具体参数都重要。