LLM Proxy：让 Home Assistant 无缝拥抱本地大模型的透明桥梁

一款用 Go 写的"翻译官"，解决了 Home Assistant 无法直连 llama.cpp 的世纪难题

想象这样一个场景：你在树莓派上跑着 Home Assistant 智能家居系统，想要接入本地大模型实现语音助手功能，却发现 Home Assistant 的 Ollama 集成根本不支持 llama.cpp——后者恰恰是本地部署最流行的推理引擎。怎么办？重新编译？换后端？都不是好方案。

LLM Proxy 正是为解决这个问题而生：它以一个轻量级 Go 服务的形式，夹在 Home Assistant（Ollama 客户端）和 llama.cpp（OpenAI 兼容后端）之间，既充当"翻译官"把 Ollama 协议翻译成 OpenAI 格式，又充当"账房先生"把每一次请求和响应完整记录下来，供你日后调试分析。

这个项目最初的作者 stevelittlefish 在 2026 年 1 月搭建自己的 Home Assistant 环境时，遇到上述困境，于是花了大半天时间、用 $25 的 Claude API 调用费用，自己动手撸出了这个工具。项目代码质量出奇地高——多阶段 Dockerfile、完整的 Web UI、内嵌静态资源、自动化 Release 流水线一应俱全，完全不像是"临时解决方案"的粗糙产物。

核心功能：四层能力叠加

第一层：协议翻译（Ollama → OpenAI）
LLM Proxy 同时暴露 Ollama 兼容 API（/api/chat、/api/generate）和 OpenAI 兼容 API（/v1/chat/completions），自动把前端发来的请求翻译成后端能理解的格式。无论你用的是 Home Assistant、Open WebUI 还是其他 Ollama 客户端，它都能扮演好"中间人"的角色，将请求转发给任何 OpenAI 兼容的后端——llama.cpp、vLLM、LocalAI 均可。

第二层：全链路日志
所有请求和响应都会存入 SQLite 数据库，包括完整的消息内容、系统提示词、延迟时间、错误信息。内置 Web UI（/logs）提供分页浏览，单条记录详情页（/logs/details）可以下载为 Markdown，方便你在调试 Prompt 工程时回溯每一次模型的输入输出。

第三层：智能文本注入
通过配置文件启用 chat_text_injection，可以往用户消息里自动追加特定文本。例如设置 text = "/nothink"、mode = "last"，就能在每条用户消息末尾悄悄加上禁用思考模型的指令，而无需修改任何客户端代码。

第四层：工具黑名单
如果你的后端模型意外支持了一些危险工具（比如代码执行、网络搜索），可以在 tool_blacklist 列表里把它们列出来，Proxy 会在转发请求前把这些工具从请求中剔除，防止模型做出意料之外的操作。

技术架构：清晰的 Handler 模式

项目用 Go 语言编写，采用经典的 Handler 分层架构：

• main.go 负责服务启动和路由注册
• backend/ 目录实现后端抽象，openai.go 和 ollama.go 分别处理两种后端类型
• handlers/ 目录按功能拆分为多个独立文件：generate.go 处理文本补全，chat.go 处理对话，openai_frontend.go 处理 OpenAI 风格前端接口，logs_api.go 提供 JSON 查询接口，web.go 驱动内置 Web UI
• database/sqlite.go 封装数据库连接和初始化，queries.go 封装查询逻辑
• config/config.go 负责 TOML 配置解析

整个项目没有引入任何 C 依赖（使用纯 Go 的 SQLite 驱动），CGO_ENABLED=0 编译出的静态二进制可以直接拷贝到任何 Linux 机器上运行，部署体验极为干净。

部署体验：Docker 三步曲

项目提供完整的多阶段 Dockerfile，编译产物在 builder 阶段构建，运行阶段使用 debian:bookworm-slim 精简镜像，最终产物仅约 20MB。Docker Compose 配置开箱即用，默认暴露 11434 端口（Ollama 默认端口），对 Home Assistant 用户非常友好——只需把 Home Assistant 的 Ollama 集成 base_url 指向本机 11434，无需修改任何配置。

# 一行命令拉起
docker-compose up -d
# 访问 Web UI
curl http://localhost:11434/
# 查看请求日志
curl http://localhost:11434/logs

代码质量评估

项目代码组织清晰，模块边界明确，注释和 README 文档非常详尽。GoReleaser 自动化 Release 流水线配合 GitHub Actions，每次打 Tag 自动构建 Linux 二进制和 Docker 镜像。单元测试覆盖不详，但从目录结构和代码风格判断属于"工程化程度较高"的个人项目。

局限与风险

需要坦诚说明几点：项目目前没有内置任何认证机制，如果暴露在公网环境下，任何人都可以调用接口，在生产环境使用务必配合 Nginx/Caddy 做访问控制。另外作者本人也坦言项目最初是"用 AI 辅助编码"快速构建的，虽然最终代码质量不错，但后续维护主要靠社区贡献，长期活跃度有待观察。

行业意义

在本地大模型部署生态中，llama.cpp 凭借纯 CPU 运行、跨平台、GGUF 格式支持等优势积累了庞大的用户群，而 Home Assistant 等生态的 Ollama 集成却无法直接对接。LLM Proxy 用最轻量的方式填补了这个生态鸿沟——它不需要改造任何一端，只需在中间加一层透明的代理，即可让两端无缝协作。随着本地 AI 智能家居场景的持续升温，这类"协议桥接"工具的价值会越来越凸显。