AI 自动化建议工具

这是一个基于 AI 的助手，专为 Home Assistant 打造。它利用大型语言模型来理解您独特的智能家居环境——包括您的实体、区域、设备以及现有的自动化规则。该工具会根据您的具体配置，提出智能且可操作的 YAML 建议，帮助您充分发挥家居系统的潜力。

---

✨ 为什么需要这个工具？（目的与问题陈述）

随着 Home Assistant 配置的不断扩展，管理其复杂性并发现新的自动化机会可能会变得颇具挑战。您可能会遇到以下情况：

• 可能性太多： 每新增一个设备，都会带来无数潜在的交互方式。
• 自动化“写作障碍”： 将复杂的构想转化为可用的 YAML 代码往往令人望而却步。
• 潜力未被充分利用： 许多设备长期闲置或需手动控制，因为尚未想到或创建合适的自动化方案。
• 维护负担过重： 随着家居环境的变化，保持现有自动化规则的相关性也十分困难。

最终结果往往是，尽管硬件功能强大，但家庭自动化程度仍然较低。

解决方案——您的个性化自动化助手

AI 自动化建议工具通过充当您的私人自动化顾问，解决了上述难题。它能够智能地分析您的 Home Assistant 实例，从而：

1. 分析家居状态： 了解您的设备、功能、位置以及现有自动化规则。
2. 识别机会： 发现潜在的不足、协同效应以及在节能、安全、舒适和便利方面的改进空间。
3. 生成可直接使用的 YAML 代码： 提供具体的、量身定制的自动化建议，以 YAML 片段的形式呈现，您可以直接查看、调整并实施。

简而言之， 这一集成将庞大的 Home Assistant 环境中的复杂性转化为切实可行的洞察与实际收益，引导您打造更加高效、舒适和安全的智能家居。

---

🚀 工作原理（解决方案）

该集成遵循一个简单而有效的流程：

步骤	具体操作	详情
1 · 快照	收集家居数据。	在手动触发或按计划运行时，该集成会收集关于您的实体（包括属性）、设备、区域以及现有自动化规则的信息。您可以通过过滤器和限制来控制数据范围。
2 · 构建提示	将数据整理成适合 AI 处理的格式。	这些数据会被嵌入到一个详细的系统提示中，用于描述您的特定 Home Assistant 设置。您还可以添加 自定义提示，以引导建议朝向特定目标（例如：“专注于存在感应照明”）。
3 · 调用 AI 服务	将提示发送至 AI 服务提供商。	构建好的提示会被发送到您配置的 AI 服务提供商处（OpenAI、Anthropic、Google、Groq、LocalAI、Ollama、Mistral、Perplexity 等）。
4 · 解析响应	处理 AI 返回的结果。	AI 的原始响应会被解析，提取关键信息：人类可读的建议 description、实际的 yaml_block 代码，以及其他可能的详细信息。这些信息会被存储在传感器属性中。
5 · 展示建议	向用户展示建议。	建议将以 Home Assistant 的持久化通知形式呈现。您也可以使用传感器属性，在自定义仪表盘上显示建议，方便查看和实施。

随机选择实体的功能（可配置）有助于确保每次分析都能提供新的想法，而不是重复相同的建议。

---

📸 使用效果（截图）

建议会直接以 Home Assistant 通知的形式呈现：

   
AI 建议直接呈现在 Home Assistant 中

您还可以通过传感器属性构建自定义仪表盘卡片来展示建议：

   
仪表盘显示人类可读的描述和提取出的 YAML 代码块

以下是一个在仪表盘上展示建议的示例：

   
仪表盘展示 AI 建议的自动化规则示例

---

🏆 优势

使用 AI 自动化建议工具具有多项重要优势：

• 节省时间： 减少设计复杂自动化规则所需的努力和试错过程。
• 上下文感知的建议： 建议会考虑您的具体设备、区域和当前设置，从而提供更贴近实际需求的个性化推荐。
• 模型无关的灵活性： 支持云端和本地 AI 模型，您可以根据成本、隐私和性能偏好进行选择。
• 提升易用性： 即使对 YAML 不太熟悉的用户，也能更轻松地创建自动化规则。
• 持续激发灵感： 随着家居环境和设备的变化，工具会不断提供新的创意，让您的自动化始终保持活力。
• 高度可控： 通过自定义提示、实体数量限制和域过滤器，您可以完全掌控建议生成的过程。
• 安全可靠： 所有建议均需您亲自审核确认后方可实施，不会自动执行任何操作。

---

📦 功能

• 多提供商支持： 可连接 OpenAI、OpenAI Azure、Anthropic、Google、Groq、LocalAI、Ollama、Mistral、Perplexity 或 OpenRouter，并提供完整的配置选项：
  • 所有提供商的温度控制（0.0 - 2.0）
  • 模型选择，附带提供商特定的默认设置
  • 安全的 API 密钥存储
  • 兼容提供商的自定义端点
  • 高级选项，如 Ollama 的思考模式控制
• 可自定义的提示与过滤器： 使用系统提示、领域过滤器和实体数量限制来定制建议。
• 随机实体选择： 防止重复性建议，发现新的可能性。
• 丰富的上下文信息： 结合设备和区域信息，生成更智能、更相关的创意。
• 持久化通知： 直接在 Home Assistant 界面中接收建议。
• 服务调用集成： 通过 ai_automation_suggester.generate_suggestions 服务手动触发建议，并完全控制参数。
• 诊断传感器： 监控建议状态和提供商连接健康状况。
• 示例自动化： 包含用于新实体检测和每周回顾的内置示例。- 这些内容位于代码库中
• 仪表板友好输出： 传感器属性提供描述和 YAML 块，可直接用于 Lovelace 卡片。

---

🛠️ 前置条件

• Home Assistant： 版本 2023.5 或更高。
• AI 提供商设置： 您需要访问一个 AI 模型。
  • 对于云提供商（OpenAI、Anthropic、Google、Groq、Mistral、Perplexity），您需要 API 密钥。
  • 对于本地模型（LocalAI、Ollama），请确保本地服务器正在运行，并且可以从 Home Assistant 访问。

---

⬇️ 安装

HACS（推荐）

1. 如果您尚未安装 HACS，请先安装。
2. 在 HACS → 集成 中，点击 + 按钮。
3. 搜索 AI Automation Suggester。
4. 选择该集成并点击 下载。
5. 重启 Home Assistant。
6. 转到设置 → 设备与服务 → + 添加集成，搜索 AI Automation Suggester。

手动安装

1. 下载 此仓库的内容。
2. 复制 custom_components/ai_automation_suggester 文件夹到您的 Home Assistant custom_components 目录。

   <homeassistant_config_dir>/
   └── custom_components/
       └── ai_automation_suggester/
           ├── __init__.py
           └── ... (其他文件)
   

3. 重启 Home Assistant。
4. 转到设置 → 设备与服务 → + 添加集成，搜索 AI Automation Suggester。

---

⚙️ 配置

1. 通过 Home Assistant UI 添加集成：设置 → 设备与服务 → + 添加集成 → AI Automation Suggester。
2. 按照设置向导操作：
   • 选择您的 AI 提供商： 从下拉列表中选择。
   • 输入 API 密钥或端点： 根据您选择的提供商，提供必要的凭据或本地服务器 URL。
   • 选择模型： 选择您希望使用的具体模型版本。
   • 设置最大 token 数： 定义 AI 响应的最大长度（影响建议的长度）。
   • （可选）自定义系统提示： 提供初始提示以引导 AI 的整体视角（例如：“您是智能家居节能自动化方面的专家。”）。

您可以在稍后通过设置 → 设备与服务中的集成选项调整这些设置。

---

🛠️ 高级配置

全局设置

• 温度控制：

  • 适用于所有提供商
  • 范围：0.0（更专注）至 2.0（更具创造性）
  • 默认值：0.7
  • 可在初始设置和选项中进行配置

• Token 管理：

  • 分别设置输入和输出 token 上限
  • 防止过度使用 API
  • 优化响应长度

---

✍️ 使用方法

自动建议

该集成附带一些示例自动化，您可以启用或调整：

• 新增实体时： 当 Home Assistant 中添加新实体时，自动生成功能建议，帮助您快速将其集成。
• 每周回顾： 每周（或您在自动化中自定义的时间间隔）触发一次全面分析，持续提供创意。

您可以在设置 → 自动化中找到并启用这些示例。

手动触发

您可以通过服务调用来手动触发建议生成：

1. 转到开发者工具 → 服务。
2. 选择服务 ai_automation_suggester.generate_suggestions。
3. 调用该服务。您可以传递参数来自定义请求：
   • all_entities（布尔值，默认为 false）：设置为 true 以考虑所有符合条件的实体，设置为 false 以仅考虑自上次成功运行以来新增的实体。
   • domains（字符串列表，可选）：将分析范围限制在特定领域的实体上（例如，['light', 'sensor']）。
   • entity_limit（整数，可选）：设置本次运行中 AI 应考虑的最大实体数量。有助于控制提示长度和成本。
   • custom_prompt（字符串，可选）：为本次运行添加特定指令（例如，“为门窗提出安全自动化建议。”）。

仪表板片段

主传感器（sensor.ai_automation_suggestions_<provider_name>）暴露了可用于仪表板显示的有用属性。将 <provider_name> 替换为您为集成实例指定的名称（例如，openai、ollama）。

• 显示描述：

  {{ state_attr('sensor.ai_automation_suggestions_<provider_name>', 'description') }}
  

• 显示 YAML 块：

  {{ state_attr('sensor.ai_automation_suggestions_<provider_name>', 'yaml_block') }}
  

  您可以使用 Markdown 卡片或其他类型的卡片，在 Home Assistant 仪表板上整洁地呈现这些信息。

---

📊 监控与诊断

该集成提供了多个传感器用于监控：

• AI 自动化建议： (sensor.ai_automation_suggestions_<provider_name>)

  • 状态：无建议、有新建议、有建议
  • 属性：
    • description：人类可读的建议描述
    • yaml_block：可直接使用的自动化 YAML
    • last_update：上次更新的时间戳
    • entities_processed：已分析实体列表
    • entities_processed_count：已分析实体数量

• AI 提供商状态： (sensor.ai_provider_status_<provider_name>)

  • 状态：已连接、错误、已断开、初始化中
  • 属性：
    • last_error_message：任何错误的详细信息
    • last_attempted_update：上次尝试更新的时间戳

• 最大输入/输出 Token 数： (sensor.max_input_tokens_<provider_name>、sensor.max_output_tokens_<provider_name>)

  • 显示配置的 Token 限制
  • 帮助监控 API 使用情况

• AI 模型： (sensor.ai_model_in_use_<provider_name>)

  • 显示当前模型配置
  • 对于多实例设置非常有用

• 上次错误： (sensor.last_error_message_<provider_name>)

  • 详细的错误跟踪
  • 包括意外错误的堆栈跟踪

---

🔍 错误处理与故障排除

• 堆栈跟踪：

  • 针对意外问题的详细错误日志记录
  • 可在 Home Assistant 日志中查看
  • 有助于调试 API 问题

• 常见错误场景：

  • API 认证失败
  • 网络连接问题
  • 超出 Token 限制
  • 模型不可用
  • 响应解析错误

• 错误监控：

  • 使用“上次错误”传感器进行实时错误跟踪
  • 查看 Home Assistant 日志以获取堆栈跟踪
  • 监控提供商状态传感器以检测连接问题

---

🔒 安全注意事项

• 所有 API 密钥均使用 Home Assistant 的安全存储功能进行安全保存
• UI 中的密码字段已正确遮蔽
• 可使用本地提供商（Ollama、LocalAI）以确保完全的数据隐私

---

自定义与高级用法

除了基本配置和服务调用参数外，您还可以进一步自定义该集成的行为：

随机实体选择

默认情况下，当 all_entities 设置为 true 时（或每周自动扫描运行时），该集成会采用随机实体选择。这有助于确保建议的多样性，并防止 AI 只关注同一组初始实体。

域过滤

在服务调用或自动化配置中使用 domains 参数来缩小关注范围。这对于获取特定领域的建议非常有效（例如，仅分析 living_room 区域中的 light 和 switch 实体——尽管区域过滤是基于所选实体隐含的）。

实体数量限制

entity_limit 参数对于管理提示大小至关重要，尤其是在对输入长度或成本敏感的模型上。请通过实验找到一个既能提供良好建议又不会触及 Token 限制或产生过高成本的限制值。

自定义提示

custom_prompt 参数允许您针对特定运行明确指定所需的建议类型。将其与域过滤结合使用，可以获得高度定向的结果（例如，domains: ['climate']，custom_prompt: "根据人员存在和天气情况，建议优化供暖/制冷的自动化方案。"）。

---

实施自动化

1. 查看建议： 检查持久通知或仪表板卡片以获取新建议。
2. 复制 YAML： 建议以可直接使用的 Home Assistant YAML 片段形式提供。复制 yaml_block 内容。
3. 添加到 Home Assistant：
   • 将 YAML 粘贴到 automations.yaml 文件中并重启 Home Assistant。
   • 或者，使用 Home Assistant 自动化编辑器界面：创建新自动化，切换到 YAML 模式，然后粘贴代码片段。
4. 根据需要调整： 虽然建议已经过定制，但您可能仍需对触发器、条件、延迟或动作进行小幅调整，以完美匹配您的偏好和设备。
5. 测试： 在依赖新自动化之前，务必对其进行测试，以确保其按预期工作。

---

传感器

该集成提供了两个关键传感器用于监控：

• AI 自动化建议传感器： sensor.ai_automation_suggestions_<provider_name>
  • 状态指示当前状态（如 空闲、生成中、有建议）。
  • 属性包含最新建议，包括 description、yaml_block，以及可能根据 AI 提供商响应格式而提供的其他详细信息。
• AI 提供商状态传感器： sensor.ai_provider_status_<provider_name>
  • 状态指示连接健康状况（如 已连接、错误、不可用）。
  • 属性可能提供有关提供商状态或遇到的任何错误的更多细节。

请监控这些传感器，以确保集成正常运行。

---

⚠️ 重要提示

• 隐私考虑： 如果使用基于云的 AI 提供商，请注意实体数据（名称、状态、属性）会被发送到其服务器。如果隐私是主要顾虑，可考虑使用本地 AI 模型（LocalAI、Ollama）以完全掌控数据。
• API 成本： 一些云提供商会根据处理的 Token 数量收取 API 使用费用。请注意这一点，并使用 entity_limit 和计划运行频率等功能来管理潜在成本。同时，请留意提供商的账单。
• 无保证： AI 的建议基于所提供数据中的模式和逻辑推断。它们并不保证在每种情况下都是完美或最高效的解决方案。在将建议实施到实际系统之前，务必仔细审查。
• AI 的局限性： 大型语言模型有时可能会产生幻觉或给出不合逻辑的建议。在审查时，请结合您的判断力和对家庭环境的了解。
• Home Assistant 依赖安全性： 该集成使用普通的 HTTP 调用，无需 Python 的 openai 包。请避免在 HA 环境中安装或固定 openai 版本，因为 SDK 版本不匹配可能会导致官方 OpenAI 对话集成失效。

---

🧩 故障排除

症状	检查/操作
没有可用的建议	- 验证 API 密钥是否正确。 - 检查 AI Provider Status 传感器是否有错误。 - 检查 Home Assistant 日志中与该集成相关的错误。 - 尝试手动触发服务，设置较小的 entity_limit 并不使用领域过滤器。 - 确保您有足够的实体/设备以获得有意义的建议。
AI 提供商状态显示 error	- 检查 Home Assistant 日志 (home-assistant.log) 以获取详细的错误信息（查找 ai_automation_suggester 和 processing error）。 - 检查您与提供商服务器（如果是云端）或本地服务器的网络连接。 - 确认您的 API 密钥处于激活状态且具有相应权限。 - 确保您的本地 AI 服务器正在运行并可访问。
建议提示过长	- 在触发服务或配置自动化时，减少 entity_limit 参数。 - 使用 domains 过滤器缩小分析的实体范围。 - 如果您使用了自定义提示，请缩短或简化它。
出现意外启动的建议	- 检查您的 Home Assistant 自动化和脚本，确保没有配置在启动时或通过您未预期的事件调用 ai_automation_suggester.generate_suggestions。
建议重复	- 确保使用 all_entities（例如在每周自动化中），并考虑启用随机实体选择。 - 尝试不同的 custom_prompt 值，引导 AI 朝新的方向发展。 - 在提示长度允许的情况下，增加 entity_limit 以提供给 AI 更多数据点。
HACS/GitHub 中图片链接失效	此问题已在本 README 版本中修复。请确保您仓库中的 README 文件使用提供的修正 URL。清除浏览器缓存或等待 GitHub/HACS 刷新。

如果您遇到此处未涵盖的问题，请在 GitHub 仓库中提交包含 Home Assistant 日志详细信息的问题。

---

路线图

未来计划的功能和改进：

• 更具交互性的建议： 探索反馈机制，帮助 AI 根据用户对建议的接受或拒绝进行学习。
• 一键创建自动化： 简化从查看建议到在 Home Assistant 中创建自动化的流程。
• 扩展本地化支持： 通过社区贡献支持更多语言。
• 改善实体/设备上下文： 增强提供给 AI 的关于设备类型、功能和关系的信息。

---

许可证

本项目采用 MIT 许可证授权。详情请参阅 LICENSE 文件。

---

致谢

• Home Assistant 社区： 感谢其提供强大且可扩展的智能家居平台。
• AI 提供商： OpenAI、Anthropic、Google、Groq、LocalAI、Ollama、Mistral 和 Perplexity，感谢他们开发并提供强大的语言模型。
• 贡献者和用户： 感谢大家提供的宝贵反馈、测试以及有助于改进本项目的贡献。

---

贡献

我们欢迎任何形式的贡献！如果您有新功能、改进、错误修复或翻译方面的想法，请随时在 GitHub 仓库中提交问题或拉取请求。请遵循标准的开发流程。

---

免责声明

本组件为独立开发的自定义组件，与 Home Assistant、Nabu Casa 或任何提及的 AI 提供商均无关联、背书或官方支持。请根据自身判断谨慎使用。

---

🤝 支持本项目

如果您觉得此集成非常有用，并为您节省了自动化家居的时间和精力，请考虑支持其开发。您的支持将用于维护、添加新功能以及支付开发和测试的相关费用。

---

补充信息

如需进一步咨询、讨论或协助，请访问 GitHub 仓库或 Home Assistant 社区论坛主题帖（如有）。您的反馈对我们非常重要，将帮助我们规划本项目的未来发展方向。

---

❓ 常见问题解答

1. 如何更新该集成？ 如果通过 HACS 安装，可在 Home Assistant 的 HACS 界面中直接更新。如果手动安装，则从仓库下载最新版本的文件，替换您 custom_components/ai_automation_suggester 文件夹中的现有文件，然后重启 Home Assistant。

2. 我可以在没有云 API 密钥的情况下使用此集成吗？ 可以！您可以使用 LocalAI 或 Ollama 等在本地网络上运行的本地 AI 模型。这需要您单独设置并运行本地 AI 服务器。

3. 我的 Home Assistant 数据安全吗？ 当使用基于云的 AI 提供商时，特定的实体数据（名称、状态、属性）会被发送到提供商的 API 进行处理。请参考您所选 AI 提供商的隐私政策。使用本地模型则可将所有数据处理保留在您的本地网络内。

4. 我发现了一个 bug 或有一个功能需求，我该怎么办？ 请在 GitHub 仓库中提交一个问题。尽可能提供详细信息，包括重现 bug 的步骤、截图以及相关日志。对于功能需求，请清晰描述所需功能及其使用场景。

5. 我能否获得除英语之外其他语言的建议？ 其他语言下的建议质量高度依赖于所使用的 AI 模型。该集成会以英文构建提示，但您可以尝试使用其他语言的自定义提示，观察模型的响应情况。欢迎社区参与对该集成 UI 和文档的翻译工作！

---

借助 AI 自动化建议器，您将拥有一位由 AI 驱动的助手，帮助您充分发挥家居的潜力。与其被各种可能性压得喘不过气，不如获得经过深思熟虑、贴合情境的建议，让您的 Home Assistant 自动化更加高效、实用且充满乐趣。

AI Automation Suggester 快速上手指南

AI Automation Suggester 是一个专为 Home Assistant 设计的 AI 驱动助手。它能利用大语言模型分析你的智能家居环境（实体、区域、设备及现有自动化），并生成量身定制的 YAML 自动化建议，帮助你挖掘智能家居的潜力。

环境准备

在开始之前，请确保满足以下前置条件：

• Home Assistant 版本：2023.5 或更高版本。
• AI 模型访问权限：你需要配置一个可用的 AI 服务提供商。
  • 云端服务：如 OpenAI, Anthropic (Claude), Google (Gemini), Groq, Mistral, Perplexity 等，需准备对应的 API Key。
  • 本地部署：如 Ollama, LocalAI 等，需确保本地服务已启动且 Home Assistant 能够访问其地址。

安装步骤

推荐使用 HACS (Home Assistant Community Store) 进行安装，操作最为简便。

方法一：通过 HACS 安装（推荐）

1. 确保已安装 HACS。
2. 进入 HACS 面板，点击左侧菜单的 集成 (Integrations)。
3. 点击右上角的 + 号按钮。
4. 搜索 AI Automation Suggester。
5. 选中该集成并点击 下载 (Download)。
6. 下载完成后，重启 Home Assistant。
7. 重启后，进入 设置 (Settings) -> 设备与服务 (Devices & Services) -> 右下角点击 + 添加集成 (Add Integration)。
8. 搜索 AI Automation Suggester 并按向导完成配置。

方法二：手动安装

如果无法使用 HACS，可手动复制文件：

1. 下载本项目的源代码压缩包。
2. 将解压后的 custom_components/ai_automation_suggester 文件夹复制到 Home Assistant 配置目录下的 custom_components 文件夹中。

   <homeassistant_config_dir>/
   └── custom_components/
       └── ai_automation_suggester/
           ├── __init__.py
           └── ... (其他文件)
   

3. 重启 Home Assistant。
4. 进入 设置 -> 设备与服务 -> + 添加集成，搜索并添加 AI Automation Suggester。

基本使用

安装完成后，通过以下步骤生成第一个自动化建议：

1. 配置集成

在添加集成的向导中，你需要提供以下信息：

• 选择 AI 提供商：从下拉列表中选择（如 OpenAI, Ollama 等）。
• 凭证/地址：输入 API Key 或本地服务器的 URL。
• 选择模型：指定要使用的具体模型名称。
• 最大 Token 数：限制 AI 回复的长度。
• (可选) 自定义系统提示词：例如输入 "你是一位专注于节能的智能家居专家"，以引导建议方向。

2. 手动触发建议生成

配置完成后，你可以立即通过服务调用手动测试：

1. 进入 开发者工具 (Developer Tools) -> 服务 (Services)。
2. 在服务列表中找到并选择 ai_automation_suggester.generate_suggestions。
3. 点击 调用服务 (Call Service)。

你也可以传递参数来定制本次请求（在 YAML 模式下编辑）：

service: ai_automation_suggester.generate_suggestions
data:
  all_entities: false # 设为 true 则分析所有实体，false 仅分析新增实体
  domains: ["light", "sensor"] # 仅分析特定领域的实体
  entity_limit: 20 # 限制分析的实体数量，控制成本和长度
  custom_prompt: "请为我的门窗传感器生成安全相关的自动化建议。"

3. 查看与应用建议

生成完成后，建议将通过以下两种方式呈现：

• 持久化通知：在 Home Assistant 主界面右上角的通知中心查看详细的建议描述和 YAML 代码。
• 仪表盘展示：集成了一个传感器（例如 sensor.ai_automation_suggestions_openai），你可以在 Lovelace 仪表盘中通过模板卡片展示建议内容。

示例：在仪表盘卡片中显示建议描述和 YAML 代码

type: markdown
content: |
  ### 🤖 AI 自动化建议
  
  **描述:**
  {{ state_attr('sensor.ai_automation_suggestions_<your_provider_name>', 'description') }}
  
  **YAML 代码:**
  ```yaml
  {{ state_attr('sensor.ai_automation_suggestions_<your_provider_name>', 'yaml_block') }}

*(请将 `<your_provider_name>` 替换为你配置集成时命名的实例名称，如 `openai` 或 `ollama`)*

审查建议无误后，你可以直接将 YAML 代码复制到 Home Assistant 的 `automations.yaml` 或通过 UI 的自动化编辑器导入使用。