家庭 LLM

使用 完全本地 的大型语言模型控制您的 Home Assistant 智能家居。无需云服务，也无需订阅。只需在您自己的硬件上运行注重隐私的人工智能即可。

什么是 Home LLM？

Home LLM 是为 Home Assistant 添加人工智能驱动的语音和聊天控制的完整解决方案。它由两部分组成：

1. 本地 LLM 集成 – 一个将本地语言模型连接到您智能家居的 Home Assistant 自定义组件
2. 家庭模型 – 经过专门微调、适用于智能家居控制的小型高效 AI 模型

主要特性

• 🏠 完全本地化 – 所有内容都在您的硬件上运行。您的数据永远不会离开您的掌控（除非您愿意！）
• 🗣️ 语音与聊天控制 – 可作为对话代理，与语音助手或聊天界面配合使用
• 🤖 AI 任务自动化 – 为自动化生成动态内容和结构化数据
• 🌍 多语言支持 – 内置对英语、德语、法语、西班牙语和波兰语的支持（欢迎提供更多语言的翻译！）
• ⚡ 可在低功耗设备上运行 – 模型可以在树莓派和其他普通硬件上运行——无需 GPU！
• 🔌 灵活的后端 – 您可以将模型作为 Home Assistant 的一部分在本地运行，也可以连接到外部模型提供商。

快速入门

请参阅 设置指南 以获取详细的安装说明。

要求： Home Assistant 2025.7.0 或更高版本

---

本地 LLM 集成

该集成将语言模型连接到 Home Assistant，使它们能够理解您的请求并控制您的智能设备。

支持的后端

您可以选择如何以及在哪里运行您的模型：

后端	最适合场景
Llama.cpp（内置）	直接在 Home Assistant 中运行模型
Ollama	在独立的 GPU 设备上轻松设置
通用 OpenAI API	LM Studio、LocalAI、vLLM 等兼容 OpenAI 的服务器
llama.cpp 服务器	异构（非均匀）GPU 计算环境，包括 CPU + GPU 推理
OpenAI 'Responses' 风格 API	支持 'responses' 风格 API 的云服务
Anthropic 'Messages' 风格 API	支持 'messages' 风格 API 的云服务
text-generation-webui	适用于已有相关设置的高级用户

注意：当使用 外部 API 或模型提供商时，您的数据将通过互联网传输，并与相应的服务提供商共享。请确保您了解使用这些第三方服务可能带来的隐私影响，因为这些服务提供商可以看到您 Home Assistant 实例中所有公开实体的状态，其中可能包含您的当前位置。

支持的设备类型

该集成可控制以下设备：灯光、开关、风扇、遮阳帘、门锁、气候控制、媒体播放器、吸尘器、按钮、定时器、待办事项列表和脚本

使用该集成

作为对话代理：

• 通过 Home Assistant 界面与您的助手聊天
• 连接到带有语音转文本和文本转语音功能的语音管道
• 支持语音流式传输，以获得更快的响应

作为 AI 任务处理者：

• 创建利用 AI 处理数据并生成结构化响应的自动化
• 非常适合动态内容生成、数据提取和智能决策
• 请参阅 AI 任务文档 以获取示例

---

Home LLM 模型

“Home”系列模型是经过专门微调、用于智能家居控制的小型语言模型（参数量低于 50 亿）。它们能够理解自然语言指令，并将其转换为 Home Assistant 服务调用。

最新模型

模型家族	参数量	链接
Llama 3.2	30 亿	acon96/Home-Llama-3.2-3B
Gemma	2.7 亿	acon96/Home-FunctionGemma-270m

历史模型版本

稳定模型：

• 30 亿 v3（StableLM-Zephyr-3B）：acon96/Home-3B-v3-GGUF
• 10 亿 v3（TinyLlama-1.1B）：acon96/Home-1B-v3-GGUF
• 30 亿 v2（Phi-2）：acon96/Home-3B-v2-GGUF
• 10 亿 v2（Phi-1.5）：acon96/Home-1B-v2-GGUF
• 10 亿 v1（Phi-1.5）：acon96/Home-1B-v1-GGUF

多语言实验：

• 德语、法语和西班牙语（30 亿）：acon96/stablehome-multilingual-experimental
• 波兰语（10 亿）：acon96/tinyhome-polish-experimental

注意： v1（30 亿）及更早版本的模型仅兼容 0.2.17 及更早版本的集成。

使用其他模型

没有专用硬件？您也可以使用任何经过指令微调、具备上下文学习能力（ICL）的模型。该集成提供了示例，教会通用模型（如 Qwen3、Llama 3、Mistral）如何控制您的智能家居。有关配置详情，请参阅 设置指南。

训练您自己的模型

本仓库包含微调数据集和训练脚本：

• 数据集： HuggingFace 上的 Home-Assistant-Requests-V2
• 源代码： data/ 目录
• 训练： 请参阅 train/README.md

---

文档

• 设置指南 – 安装与配置
• 后端配置 – 详细的后端选项
• 模型提示 – 自定义系统提示
• AI 任务 – 在自动化中使用 AI

---

版本历史

版本	亮点
v0.4.6	支持 Anthropic API，为 Llama.cpp 添加磁盘缓存，新增工具调用数据集
v0.4.5	AI 任务实体，同时支持多个 LLM API，官方 Ollama 软件包
v0.4	工具调用功能重写，语音流式传输，代理型工具使用循环，每个后端支持多组配置
v0.3	支持 Home Assistant LLM API，改进提示机制，自动检测 HuggingFace GGUF 格式

完整版本历史

版本	描述
v0.4.6	新增支持正确工具调用的数据集，添加 Anthropic “messages” 风格 API 支持，为 Llama.cpp 后端添加磁盘缓存
v0.4.5	增加对 AI 任务实体的支持，用官方 ollama-python 包替换自定义的 Ollama API 实现，支持同时使用多个 LLM API
v0.4.4	修复 OpenAI 后端在所有 URL 上自动添加 /v1 的问题
v0.4.3	修复安装过程中模型配置的创建问题
v0.4.2	修复默认模型设置、数值型配置字段以及 finish_reason 的处理问题
v0.4.1	修复从 HuggingFace 下载的 Llama.cpp 模型问题
v0.4	重写工具调用模型功能，引入代理型工具使用循环、语音流式传输以及每个后端支持多组配置
v0.3.11	错误修复及 llama.cpp 版本更新
v0.3.10	支持 OpenAI “Responses” API，兼容 HA 2025.7.0
v0.3.9	修复对话历史记录问题
v0.3.8	支持思考模型，兼容 HA 2025.4
v0.3.7	德语 ICL 示例，修复多轮对话相关问题
v0.3.6	小幅修复 llama.cpp 后端问题
v0.3.5	波兰语 ICL 示例
v0.3.4	完整波兰语翻译，提升语言支持
v0.3.3	通用 OpenAI 功能改进，区域处理功能优化
v0.3.2	修复脚本实体相关问题
v0.3.1	在提示中加入基本的区域支持
v0.3	支持 Home Assistant LLM API，改进提示机制
v0.2.x	支持 Ollama，上下文学习，闪存注意力机制，提示缓存
v0.1	初始发布

Home LLM 快速上手指南

Home LLM 是一个完全本地化的解决方案，旨在为 Home Assistant 添加基于大语言模型（LLM）的语音和聊天控制功能。所有数据均在本地硬件运行，无需云端服务或订阅，确保隐私安全。

环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

• Home Assistant 版本：必须为 2025.7.0 或更高版本。
• 硬件要求：
  • 支持在低功耗设备上运行（如 Raspberry Pi），无需专用 GPU。
  • 若使用内置 llama.cpp 后端，建议预留足够的内存和存储空间以存放模型文件。
• 网络访问：需要能够访问 Hugging Face 下载模型（若网络受限，请自行配置镜像源或使用离线传输）。
• 安装渠道：需已安装 HACS (Home Assistant Community Store)。

安装步骤

1. 通过 HACS 安装集成

点击以下按钮直接将仓库添加到您的 Home Assistant HACS 中，或手动添加仓库地址：

手动安装步骤：

1. 进入 Home Assistant 侧边栏，选择 HACS。
2. 点击右下角的 ... (菜单) -> 自定义存储库。
3. 添加仓库：acon96/home-llm，类别选择 Integration。
4. 搜索 "Home LLM" 并点击 下载。
5. 重启 Home Assistant。

2. 配置集成

1. 进入 设置 > 设备与服务。
2. 点击右下角的 添加集成，搜索 Home LLM。
3. 按照向导选择后端类型（推荐新手选择内置的 Llama.cpp 或外部的 Ollama）。
4. 输入模型路径或连接地址完成配置。

3. 下载模型

您需要下载专为智能家居微调的 "Home" 系列模型，或使用通用指令微调模型配合上下文学习（ICL）。

推荐模型（GGUF 格式）：

• Llama 3.2 (3B): acon96/Home-Llama-3.2-3B
• Gemma (270M): acon96/Home-FunctionGemma-270m

提示：将下载的 .gguf 模型文件放置在 Home Assistant 可访问的目录中（例如 /config/home_llm_models/），并在集成配置中指向该路径。

基本使用

安装配置完成后，您可以通过以下两种主要方式使用 Home LLM：

方式一：作为对话代理 (Conversation Agent)

这是最简单的用法，允许您通过文字或语音与智能家居交互。

1. 启用语音管道（可选）： 在 设置 > 语音助手 中，将默认助手更改为 Home LLM。
2. 测试对话： 进入 开发者工具 > 助手 (或在 Lovelace 仪表盘添加 "聊天" 卡片)，输入自然语言指令。

示例指令：

打开客厅的灯
把空调调到 24 度
今晚 8 点提醒我浇花

系统会自动将您的自然语言转换为 Home Assistant 的服务调用（Service Call），无需编写复杂的自动化脚本。

方式二：作为 AI 任务处理器 (AI Task Handler)

您可以在自动化中使用 AI 动态生成内容或处理数据。

自动化示例 (YAML)： 创建一个自动化，当触发时调用 home_llm.process_task 服务。

automation:
  - alias: "Generate Daily Summary"
    trigger:
      - platform: time
        at: "08:00:00"
    action:
      - service: home_llm.process_task
        data:
          prompt: "总结昨天的能源使用情况，并给出一个简短的建议。"
          target_entity: sensor.daily_energy_summary

此功能适用于动态内容生成、数据提取及智能决策场景。更多高级用法请参考官方文档中的 AI Tasks。