swellweb/reame

**一个精简且经过充分测试的 LLM 推理服务器，基于 [llama.cpp](https://github.com/ggml-org/llama.cpp) 构建 —— 专为已有硬件设计：共享 vCPU、免费套餐、双核 ARM 设备。** Reame 是一个优先为廉价 CPU 硬件打造的推理服务器 —— 而非 缺少 GPU 时的后备方案。其核心理念很简单：  ## Reame 的用途 Reame 专为**已有硬件和预算上，针对自有数据的狭窄、重复性 AI 工作负载**而构建 —— 在这种场景下，答案存在于 你提供的上下文中，而非模型的通用知识里。这正是 小模型媲美前沿模型的地方（我们在一台免费的 2 核 ARM 设备上，使用 7B 模型在长上下文提取中测得了 100% 的准确率），也是 Reame 的内存机制能让第 100 次请求的成本降至第 1 次请求的一小部分的地方。 | 用例 | 为什么适合 | 推荐模型 | |---|---|---| | 文档提取与分类（RAG、发票、工单、抓取） | 答案存在于上下文中；prompt 共享前缀 → 磁盘缓存发挥作用 | OLMoE 7B-A1B | | 批处理流水线（夜间为 1 万件商品打标签、生成元描述、邮件分流） | 天然具有重复性 → Palimpsest 负责起草；每 token 成本 €0，无速率限制 | Qwen2.5 1.5B–3B | | 薄利 SaaS 中的 AI 功能 | 一台 €5 的 VPS 替代计量收费的 API，维持健康的单位经济效益 | Qwen2.5 1.5B–7B | | 隐私敏感型工作（法律、医疗、公共部门） | 数据绝不离开你的服务器 —— 完全自主掌控 | OLMoE 7B-A1B | | 私有代码自动补全（Continue.dev + OpenAI 兼容 API） | 行级补全是一项狭窄任务；代码绝不离开笔记本电脑 | Qwen2.5-Coder 1.5B | | 对自有数据的判断（SEO/内容审计、评论分类） —— 批量处理 | 需要真正的推理能力：我们曾测得较小模型会捏造结论；而 9B 模型在笔记本电脑上仅用 73 秒就正确审计了一个实时网页 | Qwen3.5-9B | **Reame 不适用的场景**： 通用型 ChatGPT 替代品（前沿推理和广泛知识需要前沿级别的参数量）、智能体编程助手，或大规模创意长文写作。 - 🗂️ **持久化共享前缀 KV 缓存** —— prompt 前缀会被快照到磁盘 （zstd 压缩、校验和检查、基于 LRU 预算管理），并且**在不同的 prompt、重启 和进程之间重用**。系统 prompt 只需由首位用户支付一次。 - 📜 **Palimpsest：服务器记得它生成过什么** —— 每一次完整的 生成都会反馈到磁盘上的 n-gram 归档中；未来的请求会以 零成本从中提取草稿。领域工作负载总是不断重复的 —— 让它们自己产生回报。 - 🎭 **Il Suggeritore：将语法作为草稿源** —— 约束解码利用 结构来*禁止* token；Reame 反转了这一点，利用结构来 *提议* token。列表编号、项目符号和格式 token 可以在 从未生成过的内容上免费进行推测。 - 🔮 **自我调节的推测解码** —— 小型 draft 模型*或*零成本的 n-gram 查找负责提议 token；目标模型在一次批量传递中验证它们。 Reame 会*测量*在你的硬件上推测是否划算，并在不划算时 自动将其关闭。 - 🏛️ **The Conclave：作为质量调节旋钮的共识机制** —— `--best-of N` 在一个交错批次中对同一个 prompt 生成 N 个 候选答案（一次 prefill， 通过 KV 拷贝克隆到其他请求中；每一次权重读取都是共享的），并在最终结果上通过多数票决选出 获胜者。一旦出现绝对多数 一致同意，落后的候选者就会被停止。实测结果：它能从*你已在运行的模型*中，在每次测验里额外挤出大约 一个正确答案 —— 它并不能让 1.5B 的推理能力超过 3B 模型（共识机制解决的是方差，而非偏差）。 - 👥 **交错多用户服务** —— N 个并发生成任务在 单个多序列批次中共同推进，共享模型权重的每一次读取（这是在内存受限的 CPU 解码中占主导地位的成本）。 - 🏰 **ARCA：共享内存守护进程** —— `reame arca` 启动一个 Redis 兼容的 服务，任何语言的 Redis 客户端都可以在无需 SDK 的情况下访问它：这是一个精确响应 缓存（计算出的答案在约 0.02 秒内提供，而推理需要约 1 秒）和一个 全集群范围的生成语料库（一个节点的输出可以为其他节点提供草稿）。只需一行 配置 —— `[arca] remote = host:6420` —— 就能将一个 Reame 节点连接上去，并且 确定性请求会被自动缓存。已在免费的 ARM 设备上 使用真实的 `redis-cli` 得到验证。参见 [docs/ARCA.md](docs/ARCA.md)。 - 🌐 **兼容 OpenAI 的 REST API** —— `/v1/completions`、`/v1/chat/completions`、 SSE 流式传输、会话、Bearer 认证、指标。可将任何 OpenAI 客户端直接指向它。 - ⚡ **零配置 CLI** —— `reame run qwen2.5-1.5b` 下载一次模型， 自动为宿主机配置线程/KV/缓存，并进入聊天界面（或者 使用 `--serve`）。在你需要之前，无需任何配置文件。 - 🧪 **220+ 隔离测试用例** —— 每一层都可以在 无模型的情况下进行 mock 和测试；多序列、推测和 KV 克隆路径的 正确性已在与真实模型的集成测试中得到严格验证。  ## 实测，而非承诺 下方的每一个数据都是由最终发布的二进制程序在指定的硬件上产生的 —— 包括那些塑造了设计的负面结果。 | 亮点 | 实测结果 | 机器 | |---|---|---| | MoE 在 CPU 上击败稠密模型 | OLMoE 7B-A1B **26.7 tok/s**，而稠密 7B 为 3.3 tok/s，8/8 准确率相同 | Oracle 免费 (€0) | | 热缓存 vs 冷缓存 | **端到端 4.8 倍** | Contabo VPS | | 生成归档 (Palimpsest) | **2.3 倍** (22→51 tok/s) | M3 Pro | | 判断而不产生幻觉 | Qwen3.5-9B：**零捏造结论**，73 秒完成完整 SEO 审计 | M3 Pro | | 架构 > 规模 | 稠密 27B **~0.1 tok/s** —— 在同一台机器上比 7B MoE 慢 250 倍 | Oracle 免费 | **[完整基准测试、方法论及负面结果 → docs/BENCHMARKS.md](docs/BENCHMARKS.md)** 三个至关重要的负面结果。一个 30B 级别的 MoE 在拉满的最高级免费套餐上完美回答了同样的提取问题 —— 但比同样得分 100% 的 7B-A1B 慢了十倍：当答案存在于上下文中时，额外的参数毫无用处（MoE 在 prefill 时几乎触及每个专家，因此 3B 活跃参数的折扣在文档阅读时荡然无存）。请将 30B 级别的模型用于后台批处理中的硬核推理，而不是用于服务。在严重超载的共享 vCPU 上，draft 模型的运行速度与其目标模型一样慢，因此推测在那里适得其反 —— Reame 检测到这一点，并在运行时将其禁用。而 Conclave 并**不能**在硬核推理上填补 与两倍大小模型之间的差距：多数投票 纠正的是随机失误，而不是系统性的理解偏差 —— 我们测得 1.5B ×5 的结果 落在 1.5B 和 3B 之间，永远不会超过 3B。只展示胜利的基准测试 是广告；而这些是工程。 ## 工作原理 **共享前缀磁盘缓存。** Prompt 被分割成固定的 token 块；链式 哈希在每个块边界对 KV 快照进行索引。共享 相同前缀的*不同* prompt 会恢复最长缓存边界，并仅解码其自身的尾部。 与常驻 GPU 的前缀缓存不同，快照存在于 NVMe 上：它们能在重启后存活。  **自我调节推测。** 经典的 Leviathan/Chen 接收率（被拒绝的 token 会从残差分布中重新采样，因此输出分布 与目标模型完全一致），并带有两个针对 CPU 的改进：draft 源可以是从 prompt 本身挖掘的免费 n-gram 查找 —— 这对于提取和重写 工作负载非常理想 —— 并且反馈控制器会调整 draft 长度，并在 测得的接受率或 draft 经济效益变为负数时关闭推测。  **The Conclave。** `--best-of N` 向 交错调度器提交对同一 prompt 的 N 次尝试：尝试 0 是未改动的锚点（贪心策略保持贪心）， 探索者会改变种子并增加热度。调度器注意到相同的 prompt 并**克隆 prompt KV**，而不是进行 N 次 prefill（拷贝 捐赠者的缓存，仅解码最后一个 prompt token —— argmax 验证其等同于 完整的 prefill）。选举是对每个候选者最终 数字的绝对多数投票，对于散文则使用 Jaccard 文本中心点作为后备；一旦出现多数， 剩余的候选者就会在生成中途被停止，CLI 会报告 `CONCLAVE consensus=k/N`，这样调用方只有在 conclave 出现分歧时才需要升级处理。 将其作为质量旋钮使用：通过闲置的交错计算，而非更大模型的 RAM，从你硬件所能 承受的模型中获取更高的准确率。 ## 快速开始 ``` reame list # model catalog + what's on disk reame run qwen2.5-1.5b # download once, auto-config, chat reame run qwen2.5-1.5b "Explain mmap" # one-shot answer reame run qwen2.5-1.5b --serve # OpenAI-compatible API on :8080 reame run qwen2.5-1.5b "12*13-50?" --best-of 5 # the Conclave ``` `run` 会解析目录名（或任何本地 GGUF 路径），首次使用时将其下载到 `~/.reame/models`，并为主机配置线程、KV 量化和缓存 目录。只有当你想要更多控制权时才需要配置文件。 这是一个真实的判断任务 —— 模型从原始 HTML 审计一个实时网页（`head -c` 只是为了 将其放入上下文中；审计完全由模型完成）： ``` reame run qwen3.5-9b "Quick SEO audit of this page's HTML — title/meta \ quality, heading issues, images missing alt text, three concrete fixes: $(curl -s https://your-site.com | head -c 16000)" ``` ## 安装 **Homebrew** (macOS / Linux)： ``` brew tap swellweb/reame brew install reame ``` **预编译二进制文件** —— x64/arm64 架构的 Linux 和 arm64 架构的 macOS，可在 [发布页面](https://github.com/swellweb/reame/releases)获取 （运行时依赖：libzstd）。 **npm** (`npx reame`)：已计划中 —— 各平台二进制文件已经构建完成。 ## 从源码构建 ``` git clone https://github.com/swellweb/reame cd reame git submodule update --init --depth 1 third_party/llama.cpp ./build.sh # Release build + full test suite ./scripts/download_models.sh # TinyLlama (test model, ~670 MB) ./build/src/reame --config config/reame.conf --prompt "Hello" --max-tokens 32 ./build/src/reame --config config/reame.conf --serve # OpenAI-compatible API ``` 依赖项：CMake ≥ 3.16，一个 C++17 编译器，对于服务器还需要 Boost（头文件）、 nlohmann-json 和 zstd： ``` # Debian/Ubuntu sudo apt install build-essential cmake libboost-dev nlohmann-json3-dev libzstd-dev pkg-config # macOS brew install cmake boost nlohmann-json zstd pkg-config ``` ## 配置亮点 ``` [model] path = models/qwen2.5-7b-instruct-q4_k_m.gguf context_length = 4096 # total KV budget (shared across users when parallel > 1) threads = 4 # fewer is often faster on shared vCPUs — measure! [memory] kv_cache_type = q8_0 # f16 | q8_0 | q4_0 — halve/quarter context RAM [speculative] enabled = true mode = lookup # model (needs draft_model_path) | lookup (no 2nd model) [cache] directory = .reame-cache max_size_mb = 4096 # LRU byte budget on disk [server] port = 8080 api_key = # bearer auth when set parallel = 1 # >1 = interleaved multi-user serving ``` ## API | 端点 | 描述 | |---|---| | `POST /v1/completions` | 文本补全（带有 `"stream": true` 的 SSE） | | `POST /v1/chat/completions` | 对话补全 | | `POST /v1/sessions` · `.../save` · `.../load` · `DELETE .../{id}` | KV 会话快照 | | `GET /metrics` | 请求计数器 + 推测/缓存指标 | | `GET /health` | 存活检查（免身份验证） | ## 状态与范围 Reame 很年轻，并且刻意**保持主见和专注**：仅限 CPU 服务， 每个进程一个模型，每一层的正确性都由测试保证。非目标包括： GPU 卸载、训练、模型管理用户体验。llama.cpp 子模块被锁定在 一个已知良好的提交上，并有计划地进行升级。 意大利语文档：[docs/README.it.md](docs/README.it.md)。 ## 为什么选择 Reame 而不是 Ollama？ 笔记本电脑上的故事是相同的：只需一条命令：`reame run qwen2.5-1.5b` 就能下载、 自动配置并聊天 —— 无需学习任何东西。从这里，这两个项目 分道扬镳：Ollama 针对随意运行*多个*模型进行了优化；而 Reame 针对在免费硬件上*认真服务单一* 工作负载进行了优化。区别就在于一句话： 通用服务器将每个请求都视为全新的：计算，丢弃， 重复。在 GPU 上这没问题 —— 计算成本很低。但在廉价的 CPU 上，计算是 你最昂贵的资源。 Reame 的一切都在攻击这一点：磁盘前缀缓存、生成 归档、grammar 提示器、自我调节推测、交错 多用户批处理、Conclave。这些在 Ollama 中都不存在。 实际结果是：**Reame 服务器运行得越久，速度越快。** 第 100 次请求的成本只有第 1 次的一小部分 —— 系统 prompt 只需支付一次，相似的答案从归档中自动起草，结构 则是免费推测出来的。这个特性就是整个设计的核心。 ## 支持 Reame 是免费的，采用 MIT 许可证，并建立在无数个夜晚和免费套餐硬件之上。如果它 为你节省了 API 账单或 GPU 租金，请考虑 [赞助](https://github.com/sponsors/swellweb) 这项工作 —— 赞助将用于资助路线图：warm-ahead prefill、为 [ARCA 守护进程](docs/ARCA.md)提供语义 (L2) 缓存层，以及一流的 MoE 服务。 ## 致谢 Reame 站在 [llama.cpp](https://github.com/ggml-org/llama.cpp) 的肩膀上 （所有张量内核；MIT）。磁盘优先缓存的设想受到了 antirez 的 DwarfStar4 思路的启发；推测流水线受到了 DeepSeek 的 DSpark 工作以及 Leviathan/Chen 推测采样定理的启发；归档 起草是检索式推测 (REST) 的一个已发布且持久化的实现；表单 起草则是对语法约束解码的反转。思路皆有引用，数据 属于我们自己。 ## 许可证 [MIT](LICENSE)。建立在 [llama.cpp](https://github.com/ggml-org/llama.cpp) 的肩膀上 (MIT)。

标签：Bash脚本, CPU推理, DLL 劫持, llama.cpp, LLM推理服务, OpenAI兼容API, 大语言模型, 成本优化, 本地部署, 磁盘缓存