Home Assistant AI Task 的 Generate data 动作：从自由文本到结构化输出的 AI 数据生成实战
Home Assistant AI Task 的 Generate data 动作从自由文本到结构化输出的 AI 数据生成实战【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.ioai_task.generate_data是 Home AssistantAI Task集成source/_integrations/ai_task.markdown2025.7 引入提供的核心动作它调用 AI 模型按你给出的指令执行一次生成数据任务并把结果以响应数据response data的形式返回供模板传感器、自动化、脚本或通知消费。你可以在不写任何复杂脚本的前提下让 AI 生成一段自由文本例如车库门没关的幽默提醒也可以定义字段、描述和取值类型强制模型输出结构化数据例如摄像头画面里的鸟类数量、屋内舒适度评估。本文以 source/_actions/ai_task.generate_data.markdown 为骨架结合 AI Task 集成文档与仓库中的完整示例讲解 UI 配置、YAML 参数、响应数据格式并给出可直接复制的自动化与模板实体示例。一、动作定位不是控制设备而是产出数据与其他面向实体的动作不同ai_task.generate_data不支持 targets——它没有目标实体可供选择。它的工作方式是你描述一个任务task_name并给出具体指令instructions动作在某个 AI task 实体上执行该任务模型返回的结果作为响应数据写回 Home Assistant供后续模板引用。如果省略entity_id动作会使用该任务的首选 AI task 实体preferred AI task entity。这一点在集成文档中有明确定义你可以为不同用途生成文本、汇总信息、甚至控制设备配置不同的 AI task 实体从而让不同任务走不同模型source/_integrations/ai_task.markdown。AI task 实体的状态state是一个时间戳记录该实体上次被使用的日期时间source/_integrations/ai_task.markdown。需要先决条件你的 Home Assistant 中必须先配置一个能提供 AI task 实体的集成如 OpenAI、Anthropic、Google、Ollama 或 OpenRouter才能使用本动作。相关背景可参考官方博客 source/_posts/2025-09-11-ai-in-home-assistant.markdown。二、在 UI 中配置Automations scenes 中的可视化步骤该动作支持纯可视化配置无需编写 YAMLsource/_includes/actions/ui_header.md。步骤如下进入Settings Automations scenes打开现有自动化或脚本或选择Create automationCreate new automation新建自动化时在When部分添加触发器脚本不需要触发器它们由其他东西调用时才会运行在Then do部分选择Add action在搜索框中搜索并选择AI Task: Generate data填写Task name和Instructions并按需设置其他选项在Response variable字段中输入一个名称来保存结果例如generated_text选择Save。UI 选项一览选项说明是否必填Task name标识任务类型的名称例如 home summary 或 alert notification必填Instructions供 AI 生成数据时遵循的具体指令必填Entity ID执行任务的 AI task 实体留空则使用首选 AI task 实体可选Structured output设置后AI 返回你定义字段的结构化数据每个字段可含描述、选择器selector和可选的 required 属性可选Attachments用于多模态 AI 分析的文件列表例如摄像头快照可选这些选项在页面中由 plugins/options_ui.rb 插件渲染它会为每个选项生成标签、Required/Optional 徽标Required (true)/Optional (false)以及 slug 锚点且强制要求每个选项必须有非空描述。三、YAML 中的完整参数参考该动作在 YAML 中写作ai_task.generate_datasource/_includes/actions/yaml_header.md。字段由 plugins/options_yaml.rb 中的OptionsYamlBlock继承自ConfigurationBlock渲染复用统一的config-vars布局与类型链接。完整字段如下action: ai_task.generate_data data: task_name: garage door left open comment # 必填string instructions: Generate a funny notification that the garage door was left open # 必填string entity_id: # 可选string留空用首选 AI task 实体 structure: {} # 可选map结构化输出定义 attachments: [] # 可选list多模态分析附件 response_variable: generated_text # 保存结果的变量名参数详解task_name必填string标识任务类型的名称例如 home summary 或 alert notification。在模板实体示例中甚至可以动态使用{{ this.entity_id }}作为任务名让每个实体拥有独立任务身份。instructions必填string供 AI 遵循的具体指令。可以是单行字符串也可以用 YAML 块标量-/|书写多行指令例如给 AI 提供温度、天气、湿度等上下文并规定输出要求。entity_id可选string要执行任务的 AI task 实体。留空时使用首选 AI task 实体。structure可选map结构化输出定义键是字段名值包含description、selector和可选的required属性。设置后AI 返回的不是自由文本而是与这些字段对齐的结构化数据。示例structure: birds: selector: number:这里定义了一个名为birds的字段通过number选择器要求模型把结果整理成数值从而可以直接用于模板传感器详见下文模板实体统计摄像头画面示例。attachments可选list用于多模态 AI 分析的文件列表例如摄像头快照。每个附件是 Media selector 的输出典型形态为media_content_idmedia-source URImedia_content_typeMIME 类型attachments: media_content_id: media-source://camera/camera.chicken_coop media_content_type: image/jpeg媒体源media sourceURI 由 Media source 集成 提供形如media-source://media_source/media_dir/path默认媒体目录为local。四、响应数据如何使用生成的结果动作执行后结果会写入你在response_variable中指定的变量。响应数据是一个映射mapping包含以下字段source/_actions/ai_task.generate_data.markdowndata生成的数据。未设置structure时是自由文本设置后是结构化数据可用result.data.birds之类的方式逐字段访问。conversation_id本次任务所使用的会话conversationID。在模板中访问的方式为{{ response_variable.data }}自由文本或{{ response_variable.data.field }}结构化字段。快速试跑可以在Settings Tools Actions中搜索该动作直接填字段并点击Perform action无需编写任何 YAML 即可在当前实体上验证效果source/_includes/actions/try_it.md。五、实战示例三个开箱即用的完整配置以下示例均来自 source/_integrations/ai_task.markdown 的 Examples 章节可直接复制到configuration.yaml中。示例 1模板实体统计摄像头画面中的物体这个模板实体每 5 分钟把鸡舍摄像头快照发给 AI让它数出画面里的鸡、鹅、鸭数量并把结果作为数值暴露成传感器template: - triggers: - trigger: homeassistant event: start - trigger: time_pattern minutes: /5 # update every 5 minutes actions: - action: ai_task.generate_data data: task_name: {{ this.entity_id }} instructions: - This is the inside of my goose coop. How many birds (chickens, geese, and ducks) are inside the coop? structure: birds: selector: number: attachments: media_content_id: media-source://camera/camera.chicken_coop media_content_type: image/jpeg response_variable: result sensor: - name: Chickens state: {{ result.data.birds }} state_class: total关键点触发器组合homeassistant事件在重启时立即执行一次time_pattern每 5 分钟刷新一次structurenumber选择器保证了输出可被解析为数值从而能赋值给state_class: total的传感器附件使用 media-source URI指向camera.chicken_coop实体提供的图像源。同样的思路可以迁移到检测可用停车位数量、统计房间人数、判断门是否打开等场景。社区中类似数鸡舍里的鸡与检测停车位的创意也因此可以在 Home Assistant 内直接实现无需额外脚本、附加组件或 HACS 集成。示例 2结构化输出生成天气与室内舒适度报告这个脚本把当前室内外传感器数据注入指令让 AI 生成幽默天气描述与舒适度评估两个结构化字段再用持久化通知展示script: - alias: Weather and comfort report sequence: - action: ai_task.generate_data data: task_name: weather comfort report instructions: | Based on the current conditions: - Outdoor temperature: {{ states(sensor.outdoor_temperature) }}°C - Weather condition: {{ states(weather.home) }} - Indoor temperature: {{ states(sensor.living_room_temperature) }}°C - Indoor humidity: {{ states(sensor.living_room_humidity) }}% Generate a funny weather description and assess indoor comfort level. structure: weather_description: description: A humorous description of the current weather outside required: true selector: text: indoor_comfort: description: Assessment of how comfortable it is inside compared to outside required: true selector: text: response_variable: comfort_report - action: notify.persistent_notification data: title: Home climate report message: | ️ **Weather outside:** {{ comfort_report.data.weather_description }} ️ **Indoor comfort:** {{ comfort_report.data.indoor_comfort }}可以看到structure中每个字段的完整形态description告诉模型该字段的含义、required: true强制模型必须填充与selector约束取值类型这里是text。示例 3自由文本生成——车库门未关通知最简单的自由文本用法车库门打开超过 10 分钟后让 AI 生成一条幽默通知automation: - alias: Garage door notification triggers: - trigger: state entity_id: cover.garage_door to: on for: minutes: 10 actions: - action: ai_task.generate_data data: task_name: garage door left open comment instructions: Generate a funny notification that garage door was left open response_variable: generated_text - action: notify.persistent_notification data: message: {{ generated_text.data }}未设置structure因此generated_text.data直接是 AI 生成的文本。六、与相邻动作及生态的关系相关动作与本文动作配套的是ai_task.generate_imagesource/_actions/ai_task.generate_image.markdown它根据指令生成图片并把图片保存到第一个媒体目录中供 Media source 浏览两个动作在各自的related_actions中互相引用source/_includes/actions/related.md。若你的自动化既需要 AI 分析又需要 AI 配图可将两者串联使用。模型来源AI task 实体由支持该集成的对话/推理服务提供官方博客提到 OpenRouter 从发布起即支持 AI Tasks可让用户在 Home Assistant 中直接接入大量模型source/_posts/2025-09-11-ai-in-home-assistant.markdown。首选实体与迁移在Settings System General的 AI Task 偏好面板中选定首选实体后省略entity_id的动作会自动使用它这也使得批量迁移到最新模型、以及分享依赖 AI Tasks 的蓝图变得非常方便source/_posts/2025-09-11-ai-in-home-assistant.markdown。七、常见问题排查如果动作没有按预期返回结果可以从以下几点入手首选实体是否已配置省略entity_id前请确认已在系统设置中配置了 AI task 实体前提是至少配置了一个能提供该实体的集成如 OpenAI、Anthropic、Google、Ollama、OpenRouter 等。指令是否足够具体instructions中提供明确上下文如传感器值、设备状态通常能显著提升输出质量多行指令建议使用块标量语法。结构化字段是否匹配使用structure后模板里引用字段名必须与 YAML 中的键一致如result.data.birds并且选择器类型应与你期望的数据类型匹配数值用number文本用text。附件是否可访问attachments中的media_content_id必须是 Home Assistant 可解析的 media-source URI例如media-source://camera/entity_idmedia_content_type填对应 MIME 类型。响应变量拼写response_variable中定义的名称必须在后续{{ ... }}中完全一致。如果仍未解决可带着正在调用的动作与预期结果到社区寻求帮助或用自然语言描述需求让 AI 助手给出建议source/_includes/actions/stuck.md。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考