Colibri CACHE_ROUTE 缓存感知路由指南在 disk-streamed MoE 上以 max-rank 算法平衡命中率与路由质量【免费下载链接】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/colibriCACHE_ROUTE 是 Colibri 中一项默认关闭OFF、需显式开启的缓存感知 MoE 路由实验特性在保留真正 top-J 专家的前提下用已在内存中驻留pin ∪ LRU且排名仍在 top-M 窗口内的专家填充剩余路由槽位从而在磁盘流式加载 MoE 的硬件上降低专家 I/O 并提升缓存命中率。本文基于 docs/CACHE_ROUTE.md 展开结合 c/colibri.c 的源码实现完整讲解六个路由旋钮CACHE_ROUTE/ROUTE_J/ROUTE_M/ROUTE_P/ROUTE_ALPHA/ROUTE_AGREE的语义、max-rank 填充算法与 swap 换入/换出账本、以及如何通过 CLI 一行命令与 PILOT 做 A/B 对比。读完你可以在自己的机器上复现实验、解读 footer 与STAT帧中的swap_pct/route_agree/route_kl指标并判断该杠杆是否值得合入默认路径。为什么需要缓存感知路由Colibri 的核心定位是用手上已有的硬件运行前沿 MoE 模型纯 C 实现、零依赖、专家权重按需从磁盘流式加载见项目 README 与 docs/tuning.md 的PILOT一节。在这种架构下专家缓存命中率直接决定解码速度——每次 miss 都意味着一次磁盘读取而路由器在每层每个 token 上挑选的 top-K 专家若恰好在内存中驻留pin 的常驻专家 ∪ LRU 缓存专家就可以省下整条加载链路。但缓存命中优先与路由质量优先天然存在张力完全按 router logits 选出的 top-K 未必都在缓存里反过来一味迁就缓存则会偏离模型原始的路由决策损害输出质量。CACHE_ROUTE 给出的答案是带约束的最大排名max-rank选择——论文风格paper-style对应 arXiv:2412.00099的折中方案真正 top-J 永远保留即使未缓存也宁可去磁盘加载剩余槽位优先填充已经驻留pin ∪ LRU且仍排名在 top-M 窗口内的专家。也就是说它不会为了命中而牺牲最高质量的 J 个槽位只把中段排名J..M 区间作为可交换空间换取更高的命中率。需要强调这是**路由侧routing-side**的改动会改变实际运行的专家 ID它与PILOT下一层的权重预取不改变专家 ID正交互补二者可以叠加 A/B。六个路由旋钮环境变量与默认值CACHE_ROUTE 全部通过环境变量控制默认行为与标准全 top-K 路由完全一致CACHE_ROUTE0因此对任何机器都安全。参数解析位于 c/colibri.c环境变量默认值含义CACHE_ROUTE01 启用 max-rank 缓存感知填充pin∪LRU 优先0 标准全 top-K 路由ROUTE_J2神圣排名sacred ranks始终取真正 top-J即使未缓存也要加载ROUTE_M12驻留偏好的最大排名窗口只在 top-M 内挑已驻留专家做替换ROUTE_P0可选累计质量窗口0时用累计 router 质量覆盖固定 M0 用固定 MROUTE_ALPHA1归一化前对被替换专家的 gate 质量做缩放1 关闭即不惩罚ROUTE_AGREEauto与真正 top-K 的重叠百分比 KL 散度统计CACHE_ROUTE1时自动开启源码中的全局状态与之对应c/colibri.cstatic int g_route_j2; /* ROUTE_J: sacred top ranks (always take, even uncached) */ static int g_route_m12; /* ROUTE_M: max-rank window for cache-preferring fill */ static float g_route_p0; /* ROUTE_P: if 0, choose M from cumulative router mass instead */ static float g_route_alpha1.f; /* ROUTE_ALPHA: scale gate mass of CACHE_ROUTE substitutes before renorm (1off) */ static int g_route_agree0; /* ROUTE_AGREE1: footer overlap% mean KL vs true top-K */启动时CACHE_ROUTE1会在 stderr 打印一行配置确认且自动开启ROUTE_AGREE遥测这是判断质量退化的廉价领先指标if(g_cache_route) fprintf(stderr,[CACHE_ROUTE] on J%d M%d P%.2f alpha%.2f (pin∪LRU prefer; never default)\n, ...); /* Auto-enable agree telemetry when CACHE_ROUTE is on (cheap quality leading indicator). */ if(g_cache_route !getenv(ROUTE_AGREE)) g_route_agree1;注意这里有个容易踩的坑如果显式设置ROUTE_AGREE0且同时开启CACHE_ROUTE1自动开启逻辑会被getenv(ROUTE_AGREE)存在性检查拦截从而保持关闭——源码以是否显式设置过而非设置的值作为判断依据。一行命令开始实验三种典型启动方式见 docs/CACHE_ROUTE.md# Stock full-K可与 leaderboard 对比的标准路由 CACHE_ROUTE0 ./coli chat # 实验性 CACHE_ROUTE CACHE_ROUTE1 ROUTE_J2 ROUTE_M12 ./coli chat # 更宽的偏好窗口更多命中但可能更多 swap CACHE_ROUTE1 ROUTE_J2 ROUTE_M16 ./coli chatROUTE_M是核心调参对象M 越大可用来挑驻留专家的候选池越大、命中率越高但偏离真实 top-K 的空间也越大。ROUTE_J则是不允许触碰的底线——实验时建议先固定J2观察再单独移动M。max-rank 填充算法源码级拆解核心实现在 c/colibri.c 的moe()内。开启CACHE_ROUTE时每个位置的路由从纯 top-K 贪心切换为五阶段流程choice sigmoid logits router biasrank_buf按质量降序保存前rank_cap个专家rank_cap max(M, K)并截断到专家总数 E阶段 0建立全量排名缓冲。对每个位置用 O(E·M) 的朴素选择带seen去重把前rank_cap个专家按choice降序填入rank_buf/rank_w。router_best_or_fallback()处理 logits 非有限NaN/Inf的退化场景避免idx-1这类越界写该问题由c/tests/test_logit_nan.c文档化。阶段 1神圣 top-J 无条件保留。从rank_buf[0..J)依次取J被 clamp 到[0, Ksel]区间int Jg_route_j; if(J0) J0; if(JKsel) JKsel; for(int kk0;kkJ chosenKsel;kk){ idx[chosen]rank_buf[kk]; w[chosen]rank_w[kk]; chosen; }阶段 2驻留偏好填充。扫描排名区间[J, Mwin)跳过已选专家只接纳当前驻留的专家。驻留判定由expert_is_resident()完成c/colibri.c/* pin ∪ LRU residency probe (used by CACHE_ROUTE max-rank fill). */ static int expert_is_resident(Model *m, int layer, int eid){ return pin_indexed(m,layer,eid)!NULL || ecache_indexed(m,layer,eid,0)!NULL; }即专家要么在显式 pin 的常驻索引中要么在LRU 专家缓存索引中——这正是pin ∪ LRU的语义来源。阶段 3余量回填。若槽位仍未满极端情形下驻留专家不足 K 个按真正排名顺序从rank_buf[0..Mwin)回填保证每个位置恰好选出Ksel个专家for(int r0;rMwin chosenKsel;r){ int erank_buf[r]; int already0; for(int j0;jchosen;j) if(idx[j]e){already1;break;} if(already) continue; idx[chosen]e; w[chosen]rank_w[r]; chosen; }阶段 4质量修正与账本。若ROUTE_ALPHA在(0,1)区间被替换专家不在真实 top-K 中的 gate 质量在归一化前乘以alpha降权随后累加 swap 计数与ROUTE_AGREE统计重叠数、KL 散度详见下文。从源码结构可以推断swap 账本route_slots/route_swaps按position×K 槽位累计而非按专家累计因此swap%表示被替换的槽位占全部槽位的比例与模型层数无关可跨模型比较。ROUTE_P用累计质量替代固定 M 窗口固定 M 窗口对长尾质量分布不敏感当 router 前几名就占掉绝大多数质量时M12 的窗口其实只贡献了少量边际。ROUTE_P提供累计质量变体c/colibri.c先把候选窗扩展到max(M, 4·Ksel)截断到 E 与 rank_cap按正质量归一化后累加直到累计占比达到ROUTE_P以此刻的排名位置作为实际窗口Mwin并保证不小于Kselint Mmaxg_route_mKsel*4?g_route_m:Ksel*4; if(MmaxE) MmaxE; if(Mmaxrank_cap) Mmaxrank_cap; ... float tot1e-20f; for(int kk0;kkMmax;kk) totrank_w[kk]0?rank_w[kk]:0; float cum0; MwinKsel; for(int kk0;kkMmax;kk){ cumrank_w[kk]0?rank_w[kk]:0; if(cumg_route_p*tot){ Mwinkk1; break; } Mwinkk1; } if(MwinKsel) MwinKsel;典型用法如ROUTE_P0.95窗口自动收窄到覆盖 95% 累计质量的最小排名集质量敏感时比固定ROUTE_M更精细。ROUTE_P0时走固定 M 路径。如何读懂命中与换入指标CACHE_ROUTE 的遥测分两个出口交互/生成模式的 footer与serve 模式的STAT帧。Footerc/colibri.c在CACHE_ROUTE1时追加| swap 3.2% (412/12800) | route_agree 96.8% | route_kl 0.0012 | CACHE_ROUTE J2 M12 P0.00 alpha1.00serve 模式的STAT帧c/colibri.c在CACHE_ROUTE开启或存在计数时追加swap_pct/route_swaps/route_slots/route_agree/route_kl字段注意STAT帧是机器可解析的 framing 协议字段顺序固定追加字段在行尾STAT 128 42.50 91.2 6.40 512 1 swap_pct3.2 route_swaps412 route_slots12800 route_agree96.8 route_kl0.0012各指标语义与 docs/CACHE_ROUTE.md 的 Stats 节一一对应计数由Model结构持有见 c/colibri.c指标来源字段含义swap N%/swap_pctroute_swaps / route_slots被替换槽位不在真实 top-K 中占总槽位比例route_swaps/route_slots计数器换入次数 / 总槽位数原始计数可做累积窗口route_agreeroute_agree_hit / route_agree_tot|选中的专家 ∩ 真实 top-K| / K重叠率越高越接近原始路由route_klroute_kl_sum / route_kl_n质量 KL 散度均值真实 top-K 质量分布 vs 选中分布hit N%m-hits / (hitsmiss)专家缓存命中率磁盘驻留命中与路由联动解读要点swap%是命中率的代价侧route_agree是质量的保真侧。理想实验曲线是swap% 明显上升的同时 agree% 仍 95%、KL 保持很小说明换入的多是中段排名、几乎没有损害质量。route_kl比agree更敏感即使专家 ID 完全重叠gate 质量重新归一化后也会产生非零 KL。ROUTE_ALPHA正是用来压低这个 KL 的旋钮。STAT帧基于每次请求窗口做差分route_slots-rs0之类因此可以作为 serve 端的实时质量探针按请求粒度监控路由漂移。与 PILOT 的 A/B路由侧 vs 预取侧CACHE_ROUTE 与 PILOT 是两条互补的省盘路径官方推荐的对比实验docs/CACHE_ROUTE.md 的 A/B 节# A: 仅缓存感知路由改变专家 ID CACHE_ROUTE1 PILOT0 ... # B: 仅前瞻预取不改变专家 IDPILOT 用 L1 层的 router 预测专家并预读权重 CACHE_ROUTE0 PILOT1 ... # C: 两者叠加 CACHE_ROUTE1 PILOT1 ...两者的边界在源码中非常清晰PILOT 是权重预取——在运行当前层时由专用 I/O 线程预读下一层g_pilot见 c/colibri.c可能用到的专家权重不动 router 输出的专家 IDCACHE_ROUTE 则是路由侧替换——改变实际运行的专家集合。docs/tuning.md 记录的背景数据显示GLM-5.2 的路由可提前预测性很高用 L1 层 router 预测 L 层 post-attention 状态可召回 71.6% 的真实 top-8这让 PILOT 的预取命中率可观而 CACHE_ROUTE 走的是另一条路既然中段排名可以换那就换成已经在内存里的。A/B 实验建议用swap%hit%双轴评估方案 A 应看到 hit% 上升且 swap% 可控方案 B 应看到 hit% 上升但 swap% 恒为 0ID 不变方案 C 若出现 hit% 提升而 agree% 回落则说明两个杠杆在缓存上竞争需要收窄ROUTE_M。实验范围与质量门禁按 docs/CACHE_ROUTE.md 的 Scope 节本次特性刻意保持路由侧纯改动 遥测 本文档刻意不引入 CUDA/fuse/device-tier 补丁CPU 流式加载 pin/LRU 驻留机制expert_is_resident依赖的pin_indexed/ecache_indexed是既有的两级驻留索引足以支撑对 PILOT 及#119的 A/B 验证。因此它可以在任何后端包括纯 CPU 流式路径上独立开关。使用前提与限制务必遵守默认关闭实验性质在质量门禁如./coli bench基准通过前CACHE_ROUTE1不能成为默认值——它改变了模型原始的路由决策输出质量存在未经全面验证的风险永远保留 top-JROUTE_J是质量底线调参时先固定 J 再动 M逐机测量命中收益取决于你的磁盘速度、驻留预算与模型路由的中段可换性不同模型GLM / Kimi K3 / DeepSeek V4 / OLMoE 等对应 c/colibri.c 的多引擎入口表现可能不同配套的完整变量清单见 docs/ENVIRONMENT.md 与 docs/SETTINGS.md运行时旋钮总览见 docs/tuning.md学习型驻留缓存与.coli_usage的历史信号语义见 docs/routing-telemetry.md。小结CACHE_ROUTE 把缓存命中从一个隐式的运气问题变成了一个可显式调优的约束最优化问题ROUTE_J划定不可触碰的质量底线ROUTE_M或累计质量变体ROUTE_P界定可交换的窗口ROUTE_ALPHA抑制替换引入的质量漂移ROUTE_AGREE提供可机器解析的质量回读。在磁盘流式 MoE 的部署形态下它是与 PILOT 预取正交的第二个省盘杠杆——一个从路由侧、一个从 I/O 侧共同服务于用你已有的硬件跑更大的模型这一核心目标。在将CACHE_ROUTE1纳入日常启动之前请务必在自己的模型与磁盘上完成./coli bench质量门禁与 A/B 测量。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考