JustVugg/lumabri

来源：https://github.com/JustVugg/lumabri

在一群对等节点中运行巨大的混合专家（MoE）模型，使用 colibri（https://github.com/JustVugg/colibri）引擎。纯 C 实现，无依赖。一台机器共享一个模型，任何其他机器都可以与它聊天。不需要预先下载任何内容：推理实际触及的字节在首次使用时从对等节点到达，并留在本地镜像中，因此第二个问题从本地磁盘以全速提供。引擎二进制文件永远不会被修改。任何机器都可以加入，无论有没有 GPU。该引擎首先为 CPU 和 SSD 构建；GPU 只会让它更快，绝不会改变行为，而且无论哪种方式输出都逐字节完全相同。汇集 GPU 的网络从少数人中招募。lumabri 从所有人中招募。

快速开始

make

在拥有模型的机器上（任何 colibri 模型目录）：

./lumabri serve --model /path/to/model

在想要聊天的机器上（它需要一个 colibri 构建来提供引擎）：

./lumabri chat --tracker :7300 --engines-dir /path/to/colibri/c

就这样。第一个答案较慢，因为工作集需要穿越网络。之后，~/.lumabri 中的镜像会继续提供服务，即使服务器离线。手头没有模型？make fixture 会构建一个微小的合成模型，因此上面的每个步骤都是真实的，只是规模小。

仅终端 UI

lumabri

不带参数。它会询问 swarm 地址，并询问一次操作者公钥，自行找到引擎，并将所有内容保存在 ~/.lumabri/config 中。第二次只需按 Enter、Enter 即可进入。当你提供标志时，标志仍然优先，因此脚本永远不会继承某人的已保存答案。在聊天中，/swarm 实时且匿名地显示网络（对等节点被编号，从不命名），/model 列出 swarm 上的模型并可随时切换。

工作原理

共享字节。 serve 运行两个小程序：一个 tracker，它只是谁持有哪些文件的索引；以及一个 maintainer，它回答对模型目录的字节范围读取。一个 maintainer 可以持有模型的一个切片，多个 maintainer 可以共享一个模型。

读取字节。 chat 通过 liblumabri.so 挂载模型，这是一个 LD_PRELOAD 垫片，拦截引擎对模型目录所做的那少数 libc 调用（open、fopen、opendir、pread）。文件以真实大小的稀疏本地镜像形式出现，因此 fstat、readdir 和页面缓存可以原生工作。缺失的块从对等节点获取，写入镜像，然后引擎自己的 pread 继续执行。热读取是表查找加上正常的本地读取：没有 FUSE，读取路径上没有守护进程。每个经过验证的 MiB 也会按 sha256 存储在本地内容寻址存储中。默认 CLI 路径 ~/.lumabri/cas 被每个检查点共享，因此相等的块只下载一次，并且可以在没有字节服务器的情况下重建不同的稀疏镜像。

一条规则，继承自 colibri： 网络可以改变字节来自哪里，但绝不能改变是哪些字节。写入模型文件返回 EROFS。没有对等节点能提供的块是响亮的 EIO，绝不是静默的零。字节身份在冷、热以及所有对等节点死亡时都经过验证。

专家在对等节点上运行。 对于混合专家模型，聊天端只保留稠密权重、路由器和 KV 缓存，并将 4 KB 激活发送给持有每个被路由专家的对等节点。专家权重永远不会到达聊天端。双方都由引擎自己的源码构建，因此本地运行和分布式运行是同一代码路径，并产生相同的 token。对等节点还会通告其确切构建（引擎、源码哈希、ISA、编译器、量化、模型根目录），聊天端在发送任何激活之前，会拒绝构建不同的对等节点，因为 -march=native 重新构建可能会改变最后一位，而这绝不能静默发生。

对等节点不被信任。 每个 maintainer 为其持有的每 MiB 计算 sha256，并在注册时发送。源可以使用它离线持有的 ed25519 密钥签署该事实；tracker 只携带签名，无法铸造新签名，因此聊天端会根据自己持有的密钥验证每个块。说谎的对等节点的字节会被拒绝并从其他地方重新获取。远程计算只能以唯一可能的方式进行验证：LUMABRI_VERIFY=N 在第二个副本上重新运行 N% 的专家调用，并要求输出完全相同。两个诚实的对等节点不可能不一致，因此不一致就是撒谎的证据，运行会停止。Prefill 和目标验证在到达 MoE 时已经是多行的。lumabri 保持该并集完整，并为每个选定的专家发送一个多行 EXEC，包括投机解码验证；它绝不会将批次串行化为行大小的请求。LUMABRI_HEDGE_MS=N 可选地在最近的对等节点在 N 毫秒后未回复时向下一个副本发送重复请求，并使用第一个有效的确定性结果。固定延迟是故意公开的机制，而不是自动 SLA 策略。

引擎

colibri 提供多个引擎，它们的形状不同，因此专家端是每个引擎特定的：一个挂钩 MoE 函数的小补丁，以及一个从该引擎自身源码构建的专家节点二进制文件。引擎永远不会被修改，补丁应用于副本，并且从源码锚点重新生成，因此它会大声失败，而不是在错误的地方应用。

“证明”指的是实验，而不是声明：同一个引擎和同一个提示，生成两次，一次专家在本地，一次所有专家都在对等节点上，然后逐位比较 token。该测试曾经捕获过一个真实 bug。GLM 一次对其所有路由行计算一个专家，因此一次向对等节点提供一行会产生不同的浮点数，并且 token 在四个位置后发生漂移。只有实际运行才能发现这一点。使用 make engines 构建对等节点，使用 make chatters 构建打过补丁的聊天引擎，或者使用 make phase2-all ENGINE=/path/to/colibri/c 同时构建两者，具体取决于你的 colibri 检出实际拥有的引擎。

运行一个 swarm

完整的服务器演练（systemd、防火墙、操作者密钥、客户端）位于 DEPLOY.md。简短版本：

make && make phase2-all ENGINE=/path/to/colibri/c  # phase2-all 可选
sudo make install  # 或 PREFIX=$HOME/.local

在服务器上，lumabri serve --model /srv/model 打开 TCP 7300 到 7302（tracker、maintainer、executor）。添加 --advertise <IP> 以获得最快的直接路径，并添加 --key swarm.key 签署模型。如果字节或计算捐赠者无法接受入站流量，其出站心跳可以兼作 tracker 中继。直接 P2P 仍然是首选；对称 NAT 不再将其排除在 swarm 之外。

在每台其他机器上，选择一个角色：

磁盘捐赠者由 tracker 告知要持有哪些文件，最稀有的优先。计算捐赠者只说它能携带多少个专家（--hold N），tracker 会给它其他人都不覆盖的集合。两者都不需要知道其他捐赠者的存在。在生成回复期间，你可以杀掉一个捐赠者：你会得到一行故障转移日志，token 会继续，完全相同。

对于手动签名密钥轮换，分发一个每行包含一个公钥的密钥环。--pubkey keyring 和 LUMABRI_PUBKEY=keyring 接受其中的所有密钥（最多 16 个）。首先部署 old+new，然后使用新私钥重启源进行签名，只有在客户端和捐赠者都迁移后才移除旧行。将最新密钥放在最后：tracker 保留由最高优先级（最新）密钥做出的有效签名，因此旧捐赠者心跳无法将其回滚。也接受逗号分隔的公钥；底层 tracker 和 maintainer 命令也接受重复的 --pubkey。每个对象仍然只有一个签名；重叠部分属于验证者，因此在轮换期间线上格式不会改变。

加密传输和对等节点身份

在每个 tracker、maintainer、专家节点和聊天端上设置 LUMABRI_ENCRYPT=1，以使用经过身份验证的 X25519/Ed25519 握手和 ChaCha20-Poly1305 帧加密 token、模型块和激活。如果对等节点密钥无法加载或创建，网络会安全失败，而不会回退到明文。每台机器将其私有端点身份保存在 ~/.lumabri/peer.key 中，并使用 lumabri peer-key 打印公钥部分。出站端点记录在 ~/.lumabri/known_hosts 中；稍后连接时更改的密钥会被拒绝。

对于首次联系 MITM 防护，在连接之前分发一个操作者管理的文件：

SERVER:7300 64_HEX_PEER_KEY
SERVER:7301 64_HEX_PEER_KEY
SERVER:7302 64_HEX_PEER_KEY

然后设置 LUMABRI_PEER_PINS=/path/to/peer-pins。严格的 pin 文件必须列出进程可能联系的每个端点。LUMABRI_REQUIRE_PIN=1 将相同的“不学习”规则应用于预置的 known_hosts。端点密钥不是模型签名密钥：LUMABRI_PUBKEY 验证模型内容，而对等节点 pin 验证网络端点。

对于端点密钥轮换，为同一地址发布两行，包含旧密钥和新密钥，切换服务器，然后移除旧行。持久 TOFU 则需要在带外验证替换密钥后显式更新 known_hosts。Tracker 还会持久化每个 maintainer/executor 名称的第一个拥有密钥。重启会从心跳重建放置，但不会重新打开名称以供接管。按密钥和按源的实时名称配额限制了表耗尽；它们是准入控制，而不是声称解决分布式 Sybil 攻击。

服务器还会在整个模型上运行一个专家节点，因此一个新的 swarm 在第一天就能工作，服务器执行所有内容，后来加入的捐赠者会赢得它们最近的那些调用。最近的副本决定速度：一个专家在 2 ms 和 30 ms 处持有，运行速度为 10.5 tok/s，而不是 1.4，因为只有你最近的副本才重要。

测试

make test

运行核心套件：字节身份、捐赠者完整性、角色解析、安全性（路径逃逸、恶意帧长度、聚合接收内存、空闲连接、持久身份和准入配额）、协议输入验证、加密向量、加密传输和预取策略。每引擎专家身份使用 fixtures 运行（make test-engines），DeepSeek V4 针对真实模型运行（make test-phase2-deepseek MODEL=<path>）。分配、并发和签名有自己的脚本（assign_test.sh、concurrency_test.sh、sign_test.sh）。较新的机制有针对性目标：make test-cas test-key-rotation test-hedge test-relay-exec。中继 EXEC 需要 ENGINE 下的 OLMoE 引擎源码；当外部检出不存在时，其脚本会显式报告 SKIP。本 README 中的每个声明背后都有一个脚本。

比较

点对点 LLM 推理已存在；但这种组合并不存在。Petals（https://github.com/bigscience-workshop/petals）和 llama.cpp RPC 将连续的 transformer 层拆分到不同设备上，这要求每个切片都运行得很快，实际上需要 GPU。lumabri 改为按专家粒度拆分，这与 MoE 稀疏性匹配：每个专家只传输 4 KB，一个对等节点仅持有一个专家就有用，而没有 GPU 的 swarm 也是一个可工作的 swarm。输出在构造上逐字节相同，因为远程和本地是同一代码，这也使得对不受信任的对等节点进行抽检验证成为可能。

要求

Linux、gcc、GNU make。Python 3 和 numpy 仅用于测试 fixtures。colibri（https://github.com/JustVugg/colibri）构建提供引擎二进制文件。

状态

可部署的工作原型。开放 swarm 验证字节（每 MiB sha256 和签名的完整模型根目录，由聊天端根据其自己的信任集检查）和结果（在第二个副本上抽检）。私有 swarm 通过 LUMABRI_TOKEN 在所有地方添加邀请 token；LUMABRI_ENCRYPT=1 在传输过程中保护该 token 和激活，使用持久 TOFU 或严格的端点 pin。多行投机验证、固定延迟对冲、本地跨检查点 CAS、手动旧+新密钥轮换以及针对 READ 和 EXEC 的 NAT 中继都已实现。自动 SLA 调整、分布式/S3 CAS、KMS/HSM 集成和自动撤销有意不属于这个无依赖基础的一部分。专家执行通过副本一致性检查，而不是操作者签名。

许可证

Apache 2.0