hearth：为本地推理服务器提供队列调度与容量共享的 OpenAI 兼容接入层

核心能力与快速开始

★ 2 · TypeScript

能做什么

面向本地推理服务器的排队与调度接入层： - 队列：命名通道（lanes）、优先级、老化机制防止饿死、按调用方上限，并优先选择已加载的模型以避免换权重开销。 - OpenAI 兼容接口：/v1/chat/completions 与 /v1/models，支持流式；请求体按字节透传，工具调用、视觉输入等能力不受影响。 - 联邦/共享：可将某个模型的请求指向受信同伴节点，这些请求不占用本地 GPU 槽位；支持出借与借用闲置容量（按模型可选开启）。 - 路由规则（可选）：客户端请求的名称可视为类型（如 chat、chat:fast），用简短的 if/else 行根据提示词长度、请求头、调用方、时间、当前已加载模型等决定由哪个模型应答。 - 控制台（可选）：/ui 展示节点、硬件、调用方与规则拓扑，显示队列和最近请求，并可在写入前复核地编辑配置。 - 密钥（可选）：每个调用方可持有独立密钥，配置各自可用模型、有效期、速率与每日限额，并统计 token 与金额用量。 - 多后端（可选）：可接入多个服务器、多张显卡、局域网内其他机器，以及不兼容 OpenAI API 的后端，按各自硬件情况排队。 - 云端 provider（可选）：将兼容 OpenAI 或 Anthropic API 的云服务作为后端，使规则可把部分请求外发、其余保留在本地。 - 金丝雀（可选）：定期向各模型提问，对已不再正常作答的模型拒绝服务。

适用场景

适合在一台或多台本地 GPU 机器上跑多个模型、又被多个客户端或调用方同时使用时的接入与调度场景： - 作为 llama-swap / llama.cpp / ollama 等本地推理服务前面的统一入口，避免不同请求争抢同一张卡导致模型反复加载卸载。 - 在不改动现有客户端的前提下平滑接入：把客户端 base URL 从原后端改为 hearth 的地址即可。 - 多用户或多应用共享本地算力：通过 API Key、速率与每日限额区分调用方并统计用量。 - 混合部署：用路由规则把一部分请求分流到云端 provider，其余留在本地。 - 与可信的人共享算力：把某个模型出借给朋友的节点，或借用对方的模型。

项目形态

可直接使用的工具

部署方式

npm 全局安装（npm i -g @vcvzgbzz/hearth），通过 hearth init 探测 llama-swap / llama.cpp / ollama 并生成 hearth.yaml，再以 hearth serve 启动；默认绑定 127.0.0.1。文档中另有「Running it on a server」一节涉及 systemd、重启与需要被监管的内容。无 GPU 时可克隆仓库运行 npm install && npm run demo 在本地演示环境（http://127.0.0.1:4300/ui）中体验。

主要依赖

需要 Node.js 环境（npm 安装与 npm 脚本）与 TypeScript 构建流程；node 与本地推理后端（llama-swap / llama.cpp / ollama 等）及 GPU 资源。具体版本要求、显存与硬件规格未说明。

使用限制

队列保存在内存中：SIGTERM 会在 shutdownGraceMs（默认 30 秒）内排空在途及排队请求，超出宽限的部分会丢失，需由监督进程避免频繁重启。重试只发生在首字节之前，若同伴节点在流式中途失效，请求会失败以避免重放导致的响应损坏。fastest 只比较队列深度，不是预测时长的模型。没有重平衡：已入队的任务留在原处，除队列深度与已加载模型外没有其他后端权衡。没有终端用户级认证，apiKeys 只是粗粒度闸门，按账户的公平性需在应用层实现。只有 chat completions 以及后端在 routes 中声明的路径会被排队，/v1/embeddings、/v1/completions 等默认原样透传。安全默认假定私有网络，不要在它前面放反向代理；扩大 listen 前应阅读安全文档。

许可证

MIT

最近推送

2026-10-14 02:23

资料检查：2026-10-14 07:00 · 卡片整理：2026-10-14 07:00
卡片由 AI 根据仓库资料整理，未进行安装或运行验证

职业应用

程序员

在本地推理服务器前部署 OpenAI 兼容的接入与调度层，为多个客户端请求不同模型时提供带优先级、防饿死、按调用方限额的队列，并优先复用已加载模型，避免单张 GPU 反复换权重；客户端只需把地址指向该服务即可继续使用现有 OpenAI 接口。

官方使用入口 ↗

由 AI 根据来源材料整理，未进行安装或运行验证