1. 项目概述为Home Assistant打造一个本地化、可扩展的AI大脑如果你和我一样是个喜欢折腾智能家居的玩家那你肯定对Home Assistant简称HA的对话助手Conversation Agent功能又爱又恨。爱的是它能让你的智能家居真正“开口说话”恨的是它要么依赖云端服务有隐私和延迟问题要么本地模型支持有限功能单一。今天要聊的这个项目hass_local_openai_llm就是来解决这个痛点的。它本质上是一个HA的自定义集成Custom Integration让你能把几乎任何兼容OpenAI API格式的本地或远程大语言模型LLM服务无缝接入到你的HA系统中作为对话助手、AI任务执行器的“大脑”。简单来说它就像给你的HA装了一个万能的“驱动适配器”。无论你是用自己电脑跑的llama.cpp、Ollama还是用性能更强的vLLM服务器甚至是像LM Studio这样的图形化工具或者是OpenRouter、Scaleway这样的第三方API服务只要它们对外提供的是OpenAI兼容的API接口这个集成就能把它们“认”成HA的官方OpenAI服务来用。这意味着你可以用上最新、最强的开源模型享受完全本地的隐私保护还能解锁像图片生成、联网搜索需配合其他工具、甚至知识库增强RAG等高级功能。对于追求隐私、可定制性和极致性能的HA高级用户来说这几乎是目前最完美的本地AI助手解决方案。2. 核心功能与设计思路拆解2.1 为什么需要这样一个集成在深入细节之前我们先聊聊“为什么”。HA官方虽然支持OpenAI但其配置是硬编码的主要针对ChatGPT等少数几个服务。如果你想用本地模型传统方法非常麻烦要么修改HA核心代码不现实要么通过复杂的反向代理和API重写来“欺骗”HA。hass_local_openai_llm集成正是为此而生它的设计哲学是最大化的兼容性与灵活性。它基于HA官方的OpenRouter集成进行深度改造和增强。OpenRouter本身就是一个聚合多种模型API的服务其集成已经部分实现了OpenAI API的兼容层。这个项目在此基础上做了几个关键性的、面向本地化部署的改进必填项变可选将服务器URLServer URL设置为配置向导中的必填项因为本地服务地址千变万化同时将API密钥API Key改为可选。这对于很多无需鉴权的本地LLM服务比如单纯在本地局域网部署的llama.cpp服务器来说配置过程瞬间清爽。流式响应与TTS流式支持集成了流式响应Streamed Responses。这意味着当你和HA助手对话时它的回答会像ChatGPT一样一个字一个字地“流”出来而不是等整个句子生成完才显示体验更自然。更重要的是它支持将流式文本直接喂给TTS文字转语音引擎进行流式语音合成实现了“边想边说”的实时对话感延迟大幅降低。深度适配HA生态不仅仅是简单的API桥接。它主动处理HA对话场景中的特殊需求比如自动剥离响应中的think标签HA用于控制设备响应的标记避免这些内部标记被误读或朗读出来支持为AI任务实体AI Task Entities配置图片输入和生成甚至允许你动态地重新配置已创建的对话助手代理而无需删除重建。2.2 超越基础对话高级功能一览这个集成的强大之处在于它把一些在AI应用开发中才常见的“高级货”带到了HA这个智能家居平台里。我们来重点看几个上下文历史修剪Trim Conversation History大模型有上下文窗口限制比如4K、8K、32K tokens。HA助手在长期对话中会把历史记录都塞进提示词很容易“爆窗”导致模型遗忘或出错。这个功能允许你设置保留最近N轮对话自动修剪掉更早的历史是保证长期对话稳定性的关键。温度Temperature控制与表情符号过滤温度参数控制模型输出的随机性创造性。你可以根据场景调整比如执行严谨的自动化任务时调低如0.2闲聊时调高如0.8。过滤表情符号则是个很实用的细节有些模型特别喜欢在回答里加在语音播报时读出来会很奇怪这个选项可以一键清理。并行工具调用Parallel Tool Calling这是OpenAI API的一个高级特性。当用户指令涉及多个操作时例如“打开客厅的灯并把空调调到24度”支持此功能的模型可以同时理解并规划这两个工具调用然后“并行”执行理论上比串行调用更快。但这需要模型和推理服务器双双支持。实验性检索增强生成RAG这是我认为最“黑科技”的部分。它允许你将助手连接到一个本地的Weaviate向量数据库。你可以把家庭手册、设备说明书、自定义场景规则等文本资料“喂”给数据库。当用户提问时系统会先在数据库里搜索相关片段然后把这些“参考资料”连同问题一起交给模型让它的回答更有依据、更准确。这相当于给助手装了一个“外部知识库”。图片生成支持通过AI任务实体你可以创建专门用于文生图Text-to-Image的“工具”。它遵循OpenAI的DALL·E API规范因此理论上兼容任何提供同类API的图片生成服务。作者已测试过StableDiffusion.cpp这意味着你可以在HA里用本地的Stable Diffusion模型来生成图片并通过自动化在仪表盘展示或发送通知。注意RAG和图片生成功能被标记为“实验性”意味着它们可能还在积极开发中配置相对复杂且高度依赖后端服务Weaviate、StableDiffusion.cpp等的正确部署。普通用户建议先从基础的对话功能玩起。3. 部署与配置全流程指南纸上谈兵终觉浅我们来一步步把它装进你的HA。我将以最推荐的HACS安装方式为例并假设你已经在本地例如同一台NAS或另一台电脑上部署好了一个llama.cpp服务器其API地址是http://192.168.1.100:8080/v1。3.1 安装准备与HACS集成添加首先确保你的HA已经安装了 HACS 。HACS是HA的社区商店管理第三方集成和插件无比方便。打开HA的Web界面侧边栏进入HACS。在右上角点击“集成”一个带加号的圆圈图标。在打开的页面右下角点击“浏览并下载存储库”。这里你有两种方式添加本集成便捷方式如果可用直接点击作者提供的快速添加按钮一个显示“HACS存储库”的徽章。这通常会弹出一个确认窗口引导你完成添加。手动方式如果按钮失效点击右上角的三个点菜单选择“自定义存储库”。在弹出窗口中存储库: 填入https://github.com/skye-harris/hass_local_openai_llm类别: 选择“集成”点击“添加”。添加成功后在HACS的集成页面搜索 “Local OpenAI LLM”你应该能看到它。点击进入然后点击右下角的“下载”按钮。下载完成后务必重启Home Assistant。这是让HA核心加载新集成代码的关键一步。你可以通过HA的“配置 - 系统 - 重启”来完成。3.2 核心服务配置详解重启后真正的配置才开始。进入“配置” - “设备与服务”。点击右下角的“添加集成”按钮。在搜索框中输入“Local OpenAI LLM”并选择它。接下来会进入配置向导。这里每一步都至关重要服务器URLServer URL这是核心中的核心。填入你的LLM服务的完整API地址。对于标准的OpenAI兼容API如llama.cpp, vLLM, Ollama这个地址通常以/v1结尾。例如http://你的服务器IP:端口/v1。请确保你的HA主机能通过网络访问到这个地址。API密钥API Key对于纯本地无需鉴权的服务这里可以留空。如果你使用的是OpenRouter、Scaleway等在线服务或者你在本地服务器上设置了API密钥则在此处填入。模型名称Model这里需要填写你的服务器上可用的具体模型名称。例如如果你在llama.cpp服务器上加载了Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf模型你可能需要填入类似Meta-Llama-3.1-8B-Instruct-Q4_K_M的名称具体名称需查看你的服务器文档或API端点。这个字段通常用于在请求中指定使用哪个模型。点击提交后集成会尝试连接你配置的服务器。如果一切正常你会看到配置成功的提示并在“设备与服务”列表中看到一个新的“Local OpenAI LLM”实体。3.3 创建并调优你的对话助手Conversation Agent服务配置好只是第一步我们还需要创建一个真正能和你对话的“助手”。在成功添加集成后系统通常会提示你创建对话助手。如果没有你可以手动前往“配置” - “语音助手” - “对话助手”。点击“添加助手”在“选择集成”步骤中你应该能看到刚刚添加的“Local OpenAI LLM”作为一个选项。选择它。为你的助手起个名字比如“本地AI管家”。接下来是关键的助手配置页面这里有很多选项决定了助手的行为配置项说明与建议值背后原理与注意事项模型Model下拉选择你在上一步配置的LLM服务器实体。一个HA可以配置多个不同的LLM服务器比如一个快速小模型用于简单指令一个强大模型用于复杂问答在这里选择当前助手用哪个。温度Temperature建议初始值0.7。可根据场景在0.2(严谨) 到0.9(创意) 间调整。控制输出随机性。值越低回答越确定、保守值越高回答越多样、有创意。对于智能家居控制偏低的值可能更可靠。最大历史消息数Max History Messages强烈建议设置如10。这是“上下文修剪”功能。只保留最近N轮对话作为历史上下文防止超出模型的令牌限制。对于8K上下文的模型设10-20轮是安全的起点。从响应中移除表情符号根据喜好勾选。如果启用模型回复中的,等Unicode表情符号会被过滤掉避免TTS朗读时出现奇怪读音。并行工具调用如果模型和服务器支持可以勾选。启用后助手可能同时处理多个设备操作请求。需要后端如vLLM开启相应支持。日期/时间上下文注入实验性功能。建议先尝试“工具结果Tool Result”角色。将当前日期时间作为上下文注入帮助模型回答“今天天气如何”这类问题。不同模型对不同注入方式工具结果/助手/用户接受度不同需测试。Weaviate配置仅当启用RAG功能并完成Weaviate部署后配置。用于连接向量数据库实现知识库增强。需要在此填写Weaviate服务器地址、API密钥、要查询的对象类名等。配置完成后保存。现在你就可以通过HA的对话界面Web界面搜索框、移动App、或语音唤醒来和你的本地AI助手聊天了。实操心得在初次配置LLM服务器时最容易出错的就是上下文长度Context Length。HA的助手功能会携带大量系统提示词包括你的设备列表、工具定义很容易就占去2K-4K的tokens。因此为你的本地模型选择或配置一个足够长的上下文窗口至少8K推荐16K或以上是成功运行的基础。这个参数通常在启动模型服务器时设置如llama.cpp的-c 16384参数而不是在HA集成里配置。4. 高级玩法与实验性功能实战4.1 搭建检索增强生成RAG私人知识库RAG功能能将你的助手变成“百事通”。假设你想让助手熟知你家所有智能设备的特殊用法和故障排除步骤。第一步部署Weaviate数据库项目贴心地提供了一个docker-compose.yml文件。你只需要有一台运行Docker的设备可以是HA主机本身也可以是同一网络下的NAS。从项目GitHub仓库的weaviate目录下获取docker-compose.yml文件。在存放该文件的目录下打开终端运行docker-compose up -d。这会启动Weaviate数据库和一个简易的管理Web界面端口9090。访问http://你的服务器IP:9090你应该能看到一个简单的界面用于管理数据。第二步配置集成连接Weaviate回到HA找到之前创建的LLM服务器实体注意是服务器实体不是对话助手实体。点击实体进入配置页面。展开“Weaviate配置”部分。填写Weaviate服务器的地址如http://192.168.1.100:8080注意这里不是Web界面端口、API密钥如果使用提供的docker-compose默认是homeassistant。保存配置。第三步向知识库添加数据你可以通过HA的服务Service来添加数据。进入“开发者工具” - “服务”。服务:local_openai.add_to_weaviate服务数据:integration_id: 你的LLM服务器实体ID # 例如 local_openai.xxxx agent_id: 你的对话助手实体ID # 例如 conversation.local_ai_butler query: 客厅吸顶灯的智能场景 content: 客厅的吸顶灯支持‘观影模式’和‘阅读模式’。对Siri说‘打开观影模式’灯光会调至20%亮度、2700K色温。说‘打开阅读模式’灯光会调至80%亮度、4000K色温。如果灯闪烁三次表示网络连接异常请检查路由器。点击“调用服务”。这里的query是搜索关键词content是关联的详细内容。当用户提问中包含“客厅吸顶灯”、“场景”、“闪烁”等与query语义相近的词汇时系统就会将对应的content作为参考信息插入到给模型的提示词中。第四步在助手配置中启用RAG编辑你的对话助手在配置中找到Weaviate部分如果已全局配置这里可能继承或允许覆盖。你可以调整最大返回结果数每次搜索返回几条最相关的记录。通常2-3条足够。分数阈值相关性分数低于此值的结果将被忽略。0.9是一个较高的要求确保只注入高度相关的内容避免噪音。现在当你问助手“客厅吸顶灯的阅读模式怎么开”时它就会先检索知识库找到你录入的说明然后给出准确的回答。4.2 配置AI任务实体进行图片生成这个功能让你在HA自动化中调用文生图模型。部署图片生成服务你需要一个兼容OpenAI Images API的服务。按照作者指引可以部署StableDiffusion.cpp。假设部署好后API地址是http://192.168.1.101:7860/v1。在HA中配置第二个LLM服务器重复3.2的步骤但这次服务器URL填你的图片生成服务地址。模型名称需要填写该服务支持的模型名如stable-diffusion-v1.5。创建AI任务实体进入“配置” - “设备与服务” - “助手” - “AI任务”。点击“创建AI任务”。任务类型选择“生成数据”。在“操作”配置中选择你刚刚创建的图片生成服务器实体作为“LLM提供者”。配置提示词、图片尺寸如1024x1024、生成数量等参数。为这个AI任务实体起个名字比如generate_landscape_image。在自动化中调用现在你可以创建一个自动化当满足某些条件比如每天早晨、或收到特定指令时调用服务ai_task.execute并指定实体ID为ai_task.generate_landscape_image传入提示词参数。生成的图片URL会保存在实体的状态属性中你可以用它来更新仪表盘图片元素、或通过通知发送。5. 常见问题排查与实战技巧本地化部署总会遇到各种“坑”。下面是我在长期使用中总结的一些典型问题和解决方法。5.1 连接与响应问题问题现象可能原因排查步骤与解决方案配置集成时提示“无法连接”或超时。1. 服务器URL错误。2. 网络不通。3. 本地LLM服务未启动或崩溃。1.检查URL确保是完整的http://ip:port/v1格式末尾的/v1常被遗漏。2.测试连通性从HA主机上用curl http://ip:port/v1/models命令测试看是否能返回模型列表。3.查看服务日志检查你的llama.cpp或Ollama服务器日志确认服务已正常启动并监听端口。助手能回复但回复内容杂乱、包含奇怪代码或think标签。模型未能正确理解HA的系统提示词或集成后处理未生效。1.确认模型能力你使用的模型必须是指令微调Instruct Tuned版本而非基础预训练模型。例如应选择Llama-3.1-8B-Instruct而不是Llama-3.1-8B。2.检查集成版本确保使用的是最新版集成自动剥离think标签是核心功能之一。3.简化测试先尝试一个非常简单的指令如“你好”看基础回复是否正常。助手在处理复杂指令涉及多个设备时反应慢或失败。1. 上下文过长达到模型限制。2. 模型本身推理能力不足。3. 未启用或支持并行工具调用。1.启用历史修剪在助手配置中将“最大历史消息数”设置为一个较小的值如5。2.升级模型尝试更大参数规模或更强能力的指令模型。3.检查工具调用支持查阅你的推理服务器如vLLM文档确认是否已启用工具调用功能并在HA助手中尝试开启/关闭“并行工具调用”进行对比测试。5.2 性能与资源优化选择适合的模型在树莓派或低功耗设备上运行HA又想跑本地模型优先考虑量化到4-bit或5-bit的小尺寸模型如7B、8B参数。llama.cpp和Ollama对资源优化很好。vLLM性能更高但资源消耗也大适合有独立GPU的服务器。关注提示词令牌数HA的系统提示词很长。你可以通过HA的开发者工具中的“检查助手”功能查看每次请求的原始提示词。如果发现令牌数经常接近模型上限除了修剪历史还可以考虑精简HA中的设备名称和实体ID避免使用过长、复杂的名称。流式响应的取舍流式响应提升体验但可能增加服务器负载。如果发现响应变慢可以尝试在集成的配置中关闭流式响应如果选项可用进行对比。5.3 实验性功能避坑指南RAG搜索无结果首先确保数据已成功添加。通过Weaviate的Web界面端口9090查询确认。其次检查助手中的“分数阈值”是否设得过高尝试调低至0.7。最后query字段的撰写很关键应使用自然语言的关键词或短语而不是整段句子这样向量匹配更准确。日期/时间注入导致模型“发疯”如果开启此功能后模型开始胡言乱语或重复时间信息说明它不适应这种注入方式。依次尝试“工具结果”、“助手”、“用户”三种角色如果都不行果断关闭此功能。模型对系统提示词的适应能力差异很大。图片生成服务返回错误99%的问题在于API兼容性。确保你的图片生成服务严格遵循OpenAI的Images API规范。使用curl或Postman直接向该服务的/v1/images/generations端点发送请求进行测试比对响应格式。StableDiffusion.cpp是经过验证的选择其他服务需要自行测试。折腾本地AI与HA的结合是一个不断调试和优化的过程。从选择一个合适的模型开始逐步配置基础对话再根据需求尝试高级功能。这个hass_local_openai_llm集成提供了前所未有的灵活性和强大功能让Home Assistant的智能化水平直接提升了一个维度。最重要的是一切都在你的掌控之中数据不出家门响应速度飞快这才是智能家居该有的样子。