Local OpenAI LLM（Home Assistant 自定义集成）
让 Home Assistant 通过任意 OpenAI 兼容接口接入本地或云端 LLM，实现语音助手对话、AI 任务和检索增强生成。
证据显示这是一个标准的 Home Assistant 自定义集成，权限范围随 HA Assist/LLM API 而定，未见恶意行为；扣分点：API 密钥与用户对话内容的存储/传输处理仅有 README 级描述，Weaviate 会将用户消息写入向量库但对敏感数据（如对话中可能含家庭布局信息）的防护无具体说明；无 CHANGELOG/发布签名，回滚仅依赖 HACS 常规机制；来源归属清晰（fork 自 OpenRouter 集成，注明原作者）。用户确认机制未在证据中体现。
pyproject 配置了 mypy 严格模式、pytest 覆盖率与 pytest-socket 禁网测试，自洽性尚可；README 明确说明上下文长度、工具调用、并行工具调用等外部依赖前提，可用性文档充分；扣分点：错误处理与用户可见的失败提示在提供的文件中无证据，测试仅覆盖 config_flow 辅助函数，核心请求路径未见测试。
目标受众（自托管/多提供商 OpenAI 兼容服务的 HA 用户）与场景描述充分，支持 10+ 服务端类型并逐一说明差异；扣分点：多数高级能力标注为实验性或依赖服务端支持，能力边界部分靠用户自行测试（如日期/时间注入方式需用户试验），触发精度（ Assist 工具调用行为）仅有间接说明。
文档结构清晰：安装（HACS/手动）、配置说明、各服务端专属配置、实验特性、致谢齐备；限制说明详尽（上下文要求、并行工具调用限制、Weaviate 不支持云端等）；Apache-2.0 LICENSE 完整。扣分点：无 CHANGELOG 文件，版本管理仅指向 GitHub releases；命名稳定性与升级路径无明确承诺；维护集中于单一作者，可持续性有不确定性。
README 输出可用性高，配置注意事项具体可操作；相对 fork 源（OpenRouter 集成）边际价值明确：流式、TTS、图像输入/生成、RAG、多服务端支持等；扣分点：成本收益缺乏量化数据，RAG 需额外运行 Weaviate + 管理 WebApp，部署成本上升但收益测试仅为作者自述的模型列表，无独立验证。
README 声称的变更清单、各服务端配置与 config_flow 测试可部分互证（如 request body 参数 denylist、Weaviate 类创建、温度字段均有测试对应）；外部链接指向 vLLM/llama.cpp/LocalAI 官方文档可交叉验证；扣分点：RAG 测试结论仅为作者自述，核心运行时代码未在证据中提供，多数行为声明无法在静态审查中核实；事实与推断基本区分（实验性、依赖服务端等均有标注）。
- 静态审查仅基于 README、LICENSE、构建配置与 config_flow 测试，核心运行时代码不在证据中，所有行为声明未经执行验证。
- 发布者身份未经认证；安装前请自行核对仓库与发布版本的一致性。
- 对话内容与可能的敏感家庭上下文会发送到所配置的 LLM 服务端，RAG 模式还会写入 Weaviate 向量库，请在暴露实体与历史长度上自行收紧。
- RAG 为实验特性，其有效性仅为作者自述的测试结论，建议在低风险场景先行验证。
- 无 CHANGELOG，升级请通过 HACS 谨慎进行并准备好回退路径。
这个 Agent 能做什么，适合哪些场景？
Local OpenAI LLM 是一个 Home Assistant 自定义集成，由 skye-harris 从官方 OpenRouter 集成分叉而来，用于连接任何 OpenAI 兼容的 LLM 服务，包括 llama.cpp、vLLM、Ollama、LM Studio、LocalAI、OpenRouter、DeepSeek、Google Gemini、Scaleway 等。它提供 Assist 对话代理（支持流式响应、TTS 流式输出、并行工具调用）和 AI Task 实体（支持文本、图像输入及图像生成）。集成还附带实验性功能：基于 Weaviate 向量数据库的检索增强生成（RAG）、日期时间上下文注入、思考标签剥离、表情符号剥离、对话历史裁剪和温度控制。安装通过 HACS 完成，配置全部在 Home Assistant UI 中进行，API Key 可留空以适配无需鉴权的本地服务器。它适合已运行 Home Assistant 并希望用自托管推理服务驱动家庭助手的用户。
该集成在 Home Assistant 内注册 'Local OpenAI LLM' 集成项，向用户配置的 OpenAI 兼容服务器（以 /v1 结尾的 URL）发送 chat completion 请求，并使用流式响应。它提供两类实体：Conversation Agent（用于 Assist 语音/文字对话，支持 TTS 流式输出、工具调用与并行工具调用、对话历史裁剪、温度调节、'always continue conversation' 语音续聊）和 AI Task 实体（文本与图像生成，图像走 Images API，已用 StableDiffusion.cpp 测试）。针对不同服务器类型提供专属配置：llama.cpp 的 enable_thinking、Slot ID、已加载模型优先、采样参数（Top-P/Min-P/Top-K/Repeat Penalty/Presence Penalty）；vLLM 的 thinking_token_budget；DeepSeek Cloud 的 Reasoning Effort；LocalAI 通过 metadata 字段传递 chat template 参数。还支持 chat_template_kwargs 自定义参数、自定义 HTTP 头、请求体附加参数、<think> 标签自动剥离，以及实验性的 Weaviate RAG：用户消息先查询 Weaviate（默认对象类 Homeassistant、最多 2 条结果、分数阈值 0.9、混合检索 alpha 0.5），命中内容注入当前对话上下文，并提供 local_openai.add_to_weaviate 服务动作向库中写入数据。
- 已在 NAS 或本地机器上运行 llama.cpp / vLLM / Ollama 的家庭实验室用户，想让 Home Assistant 的 Assist 用本地模型响应语音命令而不依赖云服务。
- 没有 API Key 的本地推理服务器用户：该集成的初始配置允许 API Key 留空。
- 希望语音助手具备基于私有知识的回答能力，愿意自托管 Weaviate 并通过 add_to_weaviate 服务灌入家庭文档的用户。
- 使用带推理能力模型（如 Qwen3）并希望控制思考行为（开关 enable_thinking、限制 vLLM thinking token 预算）的用户。
- 想让 AI Task 实体根据提示词生成或分析图片，且图像服务支持 Images API（如 StableDiffusion.cpp）的用户。
- 需要针对不同推理后端微调采样参数、chat template 参数或自定义请求头的进阶用户。
这个 Agent 有哪些优点和局限？
- 通吃多种 OpenAI 兼容后端（llama.cpp、vLLM、Ollama、LM Studio、LocalAI、OpenRouter、DeepSeek、Gemini、Scaleway 等），并可针对 llama.cpp、vLLM、LocalAI、DeepSeek 做专属调优。
- 相比被分叉的官方 OpenRouter 集成，增加了流式响应、TTS 流式输出、API Key 可选、图像输入/生成、并行工具调用、思考标签剥离、历史裁剪等大量实用能力。
- 实验性 Weaviate RAG 直接内置，附带 docker-compose 和专用 WebApp 管理工具，并提供 local_openai.add_to_weaviate 服务动作。
- 提供 llama.cpp 细粒度控制（Slot ID 缓存复用、已加载模型优先、Top-P/Min-P/Top-K/惩罚项采样参数），适合追求低延迟的本地部署。
- 依赖 Home Assistant 生态：必须已运行 Home Assistant（并建议安装 HACS），无法脱离其作为独立代理使用。
- 上下文长度无法通过 OpenAI 兼容 API 设置，必须直接配置推理服务器，且 Assist 的工具与实体定义要求至少约 10k 上下文，小上下文模型会遇到溢出问题。
- 部分功能标记为实验性（RAG、日期时间注入角色），效果因模型而异，需要自行测试选择。
- RAG 需要自行部署和维护 Weaviate（仅支持本地自托管，不支持 Weaviate Cloud），增加运维负担。
- 并行工具调用、thinking 参数、图像生成等特性依赖模型和服务器版本的配合，不同后端支持程度不一。
如何安装或部署这个 Agent？
推荐通过 HACS 安装：1) 确保已安装 HACS；2) 点击 README 中的 HACS 仓库按钮，或在 HACS 中以 Integration 类型添加自定义仓库 https://github.com/skye-harris/hass_local_openai_llm；3) 在 HACS 中安装 'Local OpenAI LLM'；4) 重启 Home Assistant。手动安装：将最新 release 中的 local_openai 文件夹复制到配置目录的 custom_components 文件夹下，然后重启 Home Assistant。
如何使用这个 Agent？
1) 进入 设置 → 设备与服务，点击 添加集成，搜索 'Local OpenAI LLM' 并按向导配置。2) Server URL 必须是完整指向 OpenAI 兼容 API 的 URL（通常以 /v1 结尾）；API Key 可留空。3) 建议推理服务器上下文长度至少 10k，并限制历史长度与暴露的实体数量以避免上下文溢出；上下文大小需在推理服务器侧配置，OpenAI 兼容 API 不支持此设置。4) 若需工具调用，须在推理引擎中启用（如 vLLM 的 tool calling、llama.cpp 的 function calling）；并行工具调用还需模型与服务器同时支持。5) 之后即可在 Assist 中使用配置的 Conversation Agent，或创建 AI Task 实体进行文本/图像生成。6) 可选：部署仓库 weaviate 目录提供的 docker-compose.yml（含 WebApp 管理界面，默认端口 9090），在 LLM Server 实体中填写 Weaviate 地址与 API Key（示例部署为 'homeassistant'）以启用 RAG。
这个 Agent 与同类方案有什么区别？
该集成明确分叉自 Home Assistant 官方的 OpenRouter 集成（由 @joostlek 开发）。相比原版，它移除了对 OpenRouter 的绑定，支持任意 OpenAI 兼容服务器与本地部署，并新增了流式响应、TTS 流式输出、可选 API Key、图像输入/生成、并行工具调用、RAG 等能力。若你只使用 OpenRouter 云服务，官方集成即可；若要接本地推理后端或需要上述增强功能，此分叉更合适。