企业官网建设流程全解析

为什么Colibrì越用越快？路由热度学习缓存与专家自动固定机制深度解析

【免费下载链接】colibriRun frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦项目地址: https://gitcode.com/GitHub_Trending/colibri3/colibri

Colibrì 是一款纯 C 语言、零依赖的前沿 MoE 模型推理引擎，专家权重从磁盘流式加载。它内置一套路由热度学习缓存：引擎会记录你实际访问过哪些专家，并在下次启动时自动固定（pin）最热的专家到内存，因此使用越久、推理越快。本文将用通俗的方式，拆解这套"越用越快"机制的三个层次：使用历史积累、自动固定策略与实时热度置换。

先理解背景：三层存储架构下的"冷热专家"

MoE（混合专家）模型每层都有成百上千个专家权重，但每个 token 只会激活其中一小部分。Colibrì 把专家按访问热度分成三层：

由于冷专家需要走磁盘，速度瓶颈就变成缓存命中率——预测得准，专家提前在内存里，速度就快。而 Colibrì 的"学习缓存"正是解决这个预测问题的核心：它不靠猜测，而是靠你真实的使用记录。

路由热度学习缓存：.coli_usage 是怎么积累起来的

引擎在每次路由决策时，都会把"第几层选了哪个专家"累加进内存计数器，并在每个对话回合结束时把结果原子写回模型目录旁的 .coli_usage 文件。文件格式极其精简，稀疏存储（只记被选过的专家）：

-1 <层数> <专家数> -2 <格式版本> <引擎标识> <层> <专家> <被选次数>

两个负数开头的头记录是刻意为之：老版本的读取循环遇到"层号为负"的行会直接跳过，所以今天写入的历史，几个月前的旧二进制也照样能读——几周积累下来的使用历史，正是这套机制的全部价值。格式细节、跨引擎互斥校验（防止 A 引擎误读 B 引擎的历史）都记录在 docs/routing-telemetry.md，实现集中在 c/route_trace.h。

几个值得了解的设计：

• 信任规则：PIN=auto发现的历史路径要接受全量校验；用户亲手输入的PIN=<file>才被视为"可信"，可以豁免身份检查。
• 只影响放置，不影响计算：pin 决定哪些字节驻留内存，永远不会改变模型输出。
• 可选衰减：设置COLI_USAGE_DECAY=0.99可给历史加约 69 回合的"半衰期"，让排名跟上工作负载变化，默认关闭、逐字节兼容。

专家自动固定：AUTOPIN 启动时就把热专家装进内存

这是"越用越快"的第一道来源。启动时引擎读取.coli_usage，自动把最热专家固定到空闲内存。策略非常克制（见 c/colibri.c）：

• 信任配额：固定量 = 专家内存预算 × 50% × 置信度，置信度 = 历史条数 ÷ 200,000（封顶 1.0）。刚用几小时就只 pin 一小块，积累够几小时聊天才放开到预算的一半——数据越少，越不敢乱 pin。
• 保留 LRU 余地：自动 pin 会给自适应 LRU 缓存留出预留空间，绝不挤占温层容量。
• 显式优先：手动设置PIN=stats.txt或PIN_GB时，自动 pin 让位。

换句话说，冷启动时 Colibrì 只能靠 LRU"现学现换"，而重启后它已经"记住"了你的使用习惯——同样问代码问题，第二次启动时热路径上的专家早就躺在 RAM 里了。

实时重固定：REPIN 让热层跟着会话走

自动固定解决的是"启动时"，REPIN 解决的是"会话中途"。开启REPIN=n（--policy balanced默认开启REPIN=64，即每输出 n 个 token 检查一次），引擎会在安全边界（请求之间，没有前向计算在飞）执行置换：

1. 每个会话内的专家都有一张衰减热度图，热度随时间减半（c/tier.h 中tier_decay）。
2. 用LFRU 分数排序：频率是主信号（一次计数值 256），最近性只是平局裁决（最多 255 分），"刚用过的"专家无法挤掉"真正热"的专家。
3. 25% 迟滞 + 单次最多 4 次置换：热专家必须比冷专家高出 25%+4 次才准换入，防止两个专家来回抖动（ping-pong），也避免一次换太多造成层抖动。
4. 置换可以是"磁盘 → RAM"甚至"RAM → VRAM"的升级，冷专家则被逐出。

[REPIN] RAM layer 12: evict 4021 (heat=3) <- admit 118 (heat=57) in 8 ms

设置REPIN_VERBOSE=1就能看到这样的置换日志。

进阶玩法：把路由"可预测性"榨干

路由热度学习不止用于放置，还能反过来加速 I/O，两个实验开关（见 docs/tuning.md）：

• PILOT=1路由前瞻预取：GLM 类模型第 L+1 层的路由，用第 L 层的注意力输出提前预测，可召回71.6%的真实 top-8 专家（对照"沿用上一 token 专家"只有 41.3%）。引擎在专门 I/O 线程上预读下一层专家，当前层计算时磁盘读取已在进行。
• CACHE_ROUTE=1缓存感知路由：在 top-K 选择时，优先从已驻留（pin ∪ LRU）的专家里补位，直接提升命中率。细节见 docs/CACHE_ROUTE.md。

此外ROUTE_TRACE=<path>可以把每次路由决策（层、专家、门控值）落成文本流，配合 c/tools/route_pairs.py 生成.coli_pairs跨层共现表，供COUPLE=做跨层预取——纯测量开关，不改变任何计算。

如何观测效果：仪表盘与命中率

内置 Web 仪表盘可以直观看到专家缓存的实时命中率、层级分布与硬件面板，验证"越用越快"最直接的指标就是hit N%的磁盘驻留命中率随使用时间的爬升曲线。

快速上手建议：

./coli chat # 默认即开启学习缓存与 AUTOPIN，无需任何配置 REPIN=64 ./coli chat # 显式开启会话级热层自适应 PIN=auto ./coli run ... # 强制以实时使用历史做启动固定

总结：三层学习，层层递进

Colibrì 的"越用越快"不是玄学，而是用你的真实路由历史去预测未来的访问模式：历史越丰富，固定的专家越准，磁盘命中越少，速度越快。对新手来说最好的消息是——这一切默认开启，你只要正常使用，它就在默默变快。

【免费下载链接】colibriRun frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦项目地址: https://gitcode.com/GitHub_Trending/colibri3/colibri