swellweb/reame 源代码: https://github.com/swellweb/reame

一个基于 llama.cpp (https://github.com/ggml-org/llama.cpp) 构建的轻量、经过全面测试的 LLM 推理服务器——专为你已有的硬件设计：共享 vCPU、免费套餐、2 核 ARM 盒子。

Reame 并非首个推理服务器。它是第一个将廉价 CPU 硬件视为一等公民而非后备方案的产品。其核心理念很简单：

在 CPU 上，永不重复计算同一件事。

Reame 的用途

Reame 专为 对你自己的数据执行狭窄、重复的 AI 工作负载而构建，在你已经付费的硬件上运行 —— 答案存在于你提供的上下文中，而非模型的一般知识中。这正是小模型能与前沿模型匹敌的场景（我们在免费的 2 核 ARM 盒子上用 7B 模型在长上下文提取中测得了 100% 准确率），也是 Reame 的内存使得第 100 次请求的成本仅为第 1 次请求的一个零头。

Reame 不适用于什么 —— 直截了当地说，因为信任在此建立：通用的 ChatGPT 替代品（前沿推理和广泛知识需要前沿参数量）、代理式编码助手、大规模创意长文写作。如果你的任务需要 100B 级别的大脑，那就买一个；如果它需要 私有地、永久地、零边际成本地处理你的文档 —— 那是一个你可以拥有的领域。

• 🗂️ 持久化的共享前缀 KV 缓存 — 提示前缀被快照到磁盘（zstd、校验和、LRU 预算限制），并在不同的提示、重启和进程之间复用。系统提示由第一个用户付费一次。
• 📜 Palimpsest：服务器记住它生成的内容 — 每个完整的生成都反馈到磁盘上的 n-gram 档案中；未来请求以零成本从中起草。领域工作负载会重复自身——让它们得到回报。
• 🎭 Il Suggeritore：语法作为草稿源 — 约束解码利用结构来禁止 token；Reame 将其反转，利用结构来提议 token。列表编号、项目符号和格式 token 在从未有人生成过的内容上免费推测。
• 🔮 自调节推测解码 — 一个小草稿模型或零成本 n-gram 查找提议 token；目标模型在一次批处理中验证它们。Reame 测量推测是否在你的硬件上带来收益，并在无收益时自行关闭。
• 🏛️ The Conclave：共识作为质量旋钮 — --best-of N 在一次交错批次中为同一提示生成 N 个候选答案（一次 prefill，通过 KV 复制克隆到其他候选；每次权重读取共享），并通过最终结果的多数投票选出胜者。一旦绝对多数达成一致，掉队者被停止。经过诚实测量：它大约从你已经在运行的模型中为每个测验挤压出额外一个正确答案——它不会让一个 1.5B 超越 3B 的推理能力（共识修复方差，而非偏差）。
• 👥 交错式多用户服务 — N 个并发生成在单个多序列批次中一起推进，共享模型权重的每次读取（这是在内存受限的 CPU 解码中占主导地位的成本）。
• 🌐 OpenAI 兼容的 REST API — /v1/completions、/v1/chat/completions、SSE 流式传输、会话、bearer 认证、指标。任何 OpenAI 客户端都可指向它。
• ⚡ 零配置 CLI — reame run qwen2.5-1.5b 一次下载模型，为主机自动配置线程/KV/缓存，并进入聊天模式（或使用 --serve）。在你想要之前无需配置文件。
• 🧪 210 个隔离测试用例 — 每一层都可模拟并在无模型情况下测试；多序列、推测和 KV 克隆路径的正确性在集成测试中针对真实模型固定。

架构

经验证而非空口承诺

下面的每个数字都是由已发布的二进制文件在所列硬件上产生的——包括那些塑造了设计的负面结果。

两个有意义的负面结果。在严重超卖的共享 vCPU 上，草稿模型运行速度与其目标模型一样慢，因此推测适得其反——Reame 检测到这一点并在运行时禁用它。而 Conclave 并未在硬推理上弥合与两倍大小模型之间的差距：多数投票纠正随机失误，而非系统性误解——我们测得 1.5B ×5 的表现介于 1.5B 和 3B 之间，从未超过 3B。只展示胜利的基准测试是广告；这些是工程。

工作原理

共享前缀磁盘缓存。提示被分割成固定 token 块；一个链式哈希在每个块边界处对 KV 快照进行键控。一个共享前缀的不同提示会恢复最长的缓存边界，并仅解码自己的尾部。与 GPU 驻留的前缀缓存不同，快照存于 NVMe：它们能在重启后幸存。

共享前缀缓存

自调节推测解码。经典的 Leviathan/Chen 接受方案（被拒绝的 token 从残差分布中重新采样，因此输出分布恰好是目标模型的分布），加上两个 CPU 优先的改进：草稿源可以是免费地从提示本身挖掘出的 n-gram 查找——这对于提取和重写工作负载非常理想——并且一个反馈控制器会调整草稿长度，并在测量到的接受率或草稿经济性为负时关闭推测。

推测解码

The Conclave。--best-of N 向交错调度器提交 N 次同一提示的尝试：尝试 0 是未触及的锚点（贪心保持贪心），探索者改变种子并加热。调度器注意到相同的提示，并克隆提示 KV 而不是预填充 N 次（复制捐赠者的缓存，仅解码最后一个提示 token——通过 argmax 验证与完整预填充一致）。选举是对每个候选最终结果进行精确多数投票，对散文则采用 Jaccard 文本中值备选方案；一旦存在多数派，其余候选在生成中途被停止，CLI 报告 CONCLAVE consensus=k/N，以便调用方仅在 Conclave 分裂时升级。将其用作质量旋钮：从你的硬件所能负担的模型中获得更多准确性，代价是空闲的交错计算，而非更大模型的 RAM。

快速开始

reame list                                    # 模型目录 + 磁盘上已有内容
reame run qwen2.5-1.5b                        # 一次下载，自动配置，聊天
reame run qwen2.5-1.5b "Explain mmap"         # 一次性回答
reame run qwen2.5-1.5b --serve                # 在 :8080 上运行 OpenAI 兼容 API
reame run qwen2.5-1.5b "12*13-50?" --best-of 5  # 使用 Conclave

run 解析目录名称（或任何本地 GGUF 路径），首次使用下载到 ~/.reame/models，并为主机选择线程、KV 量化和缓存目录。仅当你需要控制时才需要配置文件。

安装

Homebrew（macOS / Linux）：

brew tap swellweb/reame
brew install reame

预构建二进制文件——Linux x64/arm64 和 macOS arm64 位于发布页面 (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 构建 + 210 个测试用例
./scripts/download_models.sh  # TinyLlama（测试模型，约 670 MB）
./build/src/reame --config config/reame.conf --prompt "Hello" --max-tokens 32
./build/src/reame --config config/reame.conf --serve  # OpenAI 兼容 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         # 总 KV 预算（parallel > 1 时跨用户共享）
threads = 4                   # 在共享 vCPU 上更少有时更快——请测量！

[memory]
kv_cache_type = q8_0          # f16 | q8_0 | q4_0 —— 将上下文 RAM 减半/减至四分之一

[speculative]
enabled = true
mode = lookup                 # model（需要 draft_model_path）| lookup（无需第二个模型）

[cache]
directory = /opt/reame/cache
max_size_mb = 4096            # 磁盘上的 LRU 字节预算

[server]
port = 8080
api_key =                     # 设置后启用 bearer 认证
parallel = 1                  # >1 = 交错多用户服务

API

关于能耗的一点说明

Reame 的功耗在瓦级，而非千瓦级：它针对的是已经存在且已经通电的机器——无需为运行你的模型部署新的硅片。我们并未声称比饱和的数据中心 GPU 拥有更好的每 token 焦耳数——我们声称你不需要 GPU。

现状与范围

Reame 还很年轻，并故意坚持有观点且专注：仅 CPU 服务、每进程一个模型、每层通过测试固定正确性。非目标：GPU 卸载、训练、模型管理 UX。llama.cpp 子模块固定在一个已知良好的提交上，并谨慎地升级。

意大利语文档：docs/README.it.md。

为什么是 Reame 而非 Ollama？

笔记本上的故事是一样的单个命令：reame run qwen2.5-1.5b 下载、自动配置并聊天——无需学习任何东西。从那里起，两个项目分道扬镳：Ollama 优化了轻松运行许多模型；Reame 优化了在零成本硬件上认真服务一个工作负载。区别在于一句话：

Ollama 运行模型。Reame 记得曾经运行过它们。

通用服务器将每个请求视为全新：计算、丢弃、重复。在 GPU 上，这没问题——计算很便宜。在廉价 CPU 上，计算是你拥有的最昂贵的东西，而丢弃它是致命的罪过。Reame 中的一切都针对这一点：磁盘前缀缓存、生成档案、语法提示器、自调节推测、交错多用户批次、Conclave。所有这些在 Ollama 中都不存在。

实际结果是：**Reame 服务器运行时间越长越快。**第 100 次请求的成本仅为第一次的一个零头——系统提示已付费一次，相似答案从档案中自行起草，结构免费推测。没有其他服务器拥有这一特性。

支持

Reame 是免费的，采用 MIT 许可，并利用夜晚和免费套餐硬件构建。如果它为你节省了 API 账单或 GPU 租用费，请考虑赞助 (https://github.com/sponsors/swellweb) 这项工作——赞助用于资助路线图：ARCA（共享内存守护进程）、预热 prefill 和一流 MoE 服务。

致谢

Reame 站在 llama.cpp (https://github.com/ggml-org/llama.cpp) 的肩膀上（所有张量内核；MIT）。磁盘优先缓存的理念受 antirez 的 DwarfStar4 思路启发；推测管道受 DeepSeek 的 DSpark 工作以及 Leviathan/Chen 推测采样定理启发；档案起草是基于检索的推测（REST）的一种已交付的持久化实现；格式起草反转了语法约束解码。想法被引用，数字是我们的。

许可证

MIT。建立在 llama.cpp (https://github.com/ggml-org/llama.cpp) 的肩膀上（MIT）。