colibrì 路由遥测全解析.coli_usage专家历史、ROUTE_TRACE追踪流与route_trace.h统一格式【免费下载链接】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/colibricolibrì 是一个以纯 C 实现、零依赖、把 MoE 专家从磁盘流式加载到自有硬件上的推理引擎。本文以 docs/routing-telemetry.md 为骨架深入讲解它的路由遥测层引擎如何记录每次路由决策.coli_usage专家历史文件与ROUTE_TRACE追踪流为何把格式收敛到单一头文件 c/route_trace.h以及这套格式如何支撑PINauto学习缓存、COUPLE跨层预取与AUTOPIN自动置顶。读完你会掌握历史文件与追踪流的字节级格式、三条不可违背的格式约束及其背后的兼容性理由、可信读取trusted read的边界、以及如何把遥测接入一个新引擎。为什么需要一个头文件colibrì 实际上是四个引擎的集合——c/colibri.cGLM-5.2、c/kimi_k3.c、c/inkling.c、c/olmoe.c另有 c/qwen36.c 与 c/deepseek_v4.c 等分支。docs/tuning.md 描述的学习缓存质量完全取决于它读到的历史数据而在route_trace.h出现之前这段历史是按引擎各自实现的colibri.c写稀疏文本inkling.c写带IKU1魔数的稠密二进制块其余引擎什么都不写导致PINauto在它们身上无史可读。更糟的是两个写入方默认使用同一个文件名于是同一个模型目录被两个引擎共享时会留下一个彼此拒读的历史文件——一个引擎写的历史另一个引擎拒绝读取。route_trace.h的定位是只承载格式不承载任何引擎类型。它只依赖 C 标准库和 c/compat.h没有Model、Cfg或st.h——因为一个引擎原本就知道自己的层索引、选中的专家 id 及其门控值这就是全部输入。compat.h不是可选项Windows 上 CRT 的rename()在目标已存在时会失败EEXIST没有它的 shim历史文件在首次写入后就会静默停止更新。compat.h 中的实现c/compat.h正是为此而存在static inline int compat_rename(const char *old, const char *new){ return MoveFileExA(old, new, MOVEFILE_REPLACE_EXISTING) ? 0 : -1; } #define rename(old,new) compat_rename(old,new)头文件注释里特别强调只 includestdio.h在 Linux 上能编译通过但这会重新引入那个 bug——这也是它把compat.h显式列入依赖的原因。任何引擎包括未来的新引擎只需几次调用就能获得历史与追踪流例如kimi_k3.c全程只需要五处调用见下文从新引擎中使用。历史文件.coli_usage、stats.txt与PINfile历史文件是文本格式每行一条记录稀疏存储——只有计数非零的专家才会出现-1 n_layers n_experts -2 format_version engine_id layer expert count layer expert count ...前两条记录携带维度信息与写入引擎的身份标识使来自另一个模型的历史会被按名拒绝而非误读[USAGE] /models/glm/.coli_usage: written by kimi_k3, this engine is glm_moe_dsa — refusing (pass PINpath to use it anyway)从源码看写入路径位于 c/route_trace.h 的rt_save()先写-1 n_layers n_experts再写-2 version engine_id随后逐层遍历计数器、仅输出非零的layer expert count三元组最后通过临时文件 rename()原子替换目标文件。头部记录为什么长这样层字段故意为负字段顺序也不是随意的。每一个按旧格式编写的读取器都是这种循环while(fscanf(f, %d %d %u, l, e, cnt) 3) if(l 0 ...) /* out-of-range records are discarded */一条层号为负的记录会被解析、被丢弃、然后循环继续进入数据区。这正是今天写出的历史文件在 header 出现之前构建的二进制里仍能加载的原因——而这一点至关重要因为积累了数周的.coli_usage就是PINauto的全部价值。编辑格式前必须知道的两个后果任何字段都不能是非数值。字符串会让fscanf返回 3从而终止循环并静默丢弃其后所有记录。因此引擎用哈希而非名字标识名字表保留在route_trace.h中rt_engine_names[]这样不匹配时仍能用文字报告。哈希必须待在第三个字段。旧读取器用%d解析第二个字段而 32 位哈希经常超过INT_MAX——那在%d下是未定义行为。版本号小数值放第二位哈希放第三位。glm_moe_dsa的哈希是3815245270高于INT_MAX所以这不是假设性问题。c/tests/test_route_trace.c 用旧读取器循环的逐字拷贝断言这份契约Case 8违反任一条规则都会让 CI 失败而不是损坏用户的历史文件。以后再加头部记录三条铁律负层号是一个通用机制不是两个特例。每个读取器——包括早于该头文件、仍随旧二进制发布的两个——都会在首字段为负时跳过该记录因为它们都是受l0保护的while(fscanf(f,%d %d %u,...)3)循环。所以只要遵守上面两条规则再追加一条规则就可以随时新增记录类型而旧构建会跳过而非报错恰好三个数值字段绝不多于三个。第三条规则是绝对的违反它的失败是静默的。四条字段的记录不会被跳过——它会留下一个未被消费的字段使读取器失步然后用这个残留值加上下一行的开头凭空捏造出一条记录file: 3 2 5 | -3 7 12 99 | 4 1 8 an old reader sees: 3 2 5 admitted (correct) -3 7 12 skipped (correct — the l0 guard works) 99 4 1 ADMITTED - invented: leftover 99, then two fields of the NEXT line真实的4 1 8被吞进垃圾数据而一个计数被记在了第 99 层。没有任何东西会报告它——测试是对旧循环逐字拷贝实测的而非靠阅读推断见test_route_trace.cCase 11逐行校验写出记录恰好三个字段。目前尚未定义-1、-2之外的任何具体记录。如果未来某策略需要逐专家计数无法表达的数据——例如 order-1 模型在(layer, expert)对上的逐转移计数——应在写入前商定其记录号与字段含义让格式只演进一次。三个数值字段是全部约束其余一切开放。空历史 零字节文件PINauto通过测试文件大小来判断历史是否可用文件为空时回退到stats.txt。因此一次没有路由任何东西的运行不会写任何头部从而保住这个回退逻辑。rt_save()的实现对应了这一语义当非零计数总数为 0 时它只创建空文件c/route_trace.h测试 Case 1 断言空历史写出的文件大小为 0。仍然兼容读取的旧布局旧文本无头部记录的三元组。原样接受——它无法被校验这正是头部记录被添加的原因。IKU1inkling的稠密二进制布局uint32 {magic, n_layers, n_experts}后接uint32[n_layers][n_experts]。只有inkling自己读取任何其他引擎按名拒绝而不是加载另一个模型的排名。读取器通过嗅探前 4 字节是否等于RT_IKU1_MAGIC0x31554B49u即IKU1分派c/route_trace.h测试 Case 7/7b 同时覆盖了非 inkling 拒绝与inkling 自身仍能解码两条路径。追踪流ROUTE_TRACEpath每一次moe 调用 × batch 行对应一行在层路由时写出call row layer expert:gate expert:gate ...call每调用一次moe()递增一次row是前向 batch 内的位置gates 是层实际应用归一化后的值。这正是 c/tools/route_pairs.py 的输入它把追踪流聚合成.coli_pairs表供COUPLE跨层预取使用。route_pairs.py对每个 conditioning 事件(L, dL, e)输出到 top-M默认 16的f:count排名头部为COLIPAIRS 1 n_lines消费端COUPLE用它做层 L 的专家集合的混合近似打分——这是文档中记录的 3.6~9.4pp 预取召回提升的来源。关键性质纯测量。启用它绝不改变模型计算的内容但它会禁用 device-side router否则会绕过追踪所记录的 CPU 端排序。在 c/colibri.c 中可以看到实际写入rt_trace(layer,s,idx,w,Ke); /* ROUTE_TRACE: one line per (position, layer) */ ... rt_trace_end();rt_trace()c/route_trace.h按%d %d %d写出 call/row/layer再逐个以%d:%.4f写出id:gate。rt_trace_open()在进程内只尝试一次幂等失败会打一条[ROUTE_TRACE] cannot open ...到 stderr而colibri.c特意在解析配置之前就调用它保持日志顺序与旧版一致c/colibri.c。从新引擎接入一个引擎接入遥测只需要这四类调用全部在 c/route_trace.h 中#include route_trace.h rt_init(my_engine, n_layers, n_experts); /* counters identity ROUTE_TRACE */ ... for(i) if(!layer_routes(i)) rt_drop_row(i); /* once sparsity is known — see below */ ... rt_route(layer, row, ids, gates, k); /* per routing decision: traces and counts */ ... rt_save(usage_path, 1); /* where the engine already persists */kimi_k3.c是五处调用的完整示例c/kimi_k3.crt_init(kimi_k3,m.c.n_layers,m.c.n_experts); /* counters, identity, ROUTE_TRACE */ for(int i0;im.c.n_layers;i) if(!m.L[i].sparse) rt_drop_row(i); rt_drop_row(m.c.n_layers); ... int64_t hrt_load(g_k3_usage);各引擎的实际接入点分布inkling在 c/inkling.c 的rt_init/rt_drop_rowolmoe在 c/olmoe.cdeepseek_v4在 c/deepseek_v4.c 以deepseek_v4身份接入其私有写入器已被移除#700 完成测试 Case 6 断言其哈希仍可解析回名字。没有计数器行的层就是无法记账的层rt_init按层各分配一行因为它被告知的是维度而非形状。引擎通常在建层的过程中、稍后才得知哪些层真正路由必须为不路由的层调用rt_drop_row(layer)——稠密层以及无 MTP 模型上的 MTP 行。这是加载准入规则不是清理工作。每个读取器把 NULL 行视为这里没有专家可以归因计数。跳过 drop指向稠密层的记录会被静默累计、加进报告总数、并在下次保存时写回——一条任何引擎都不会发出的记录。colibri.c在model_init末尾 drop 它的行c/colibri.c这是L[i].sparse与has_mtp都已定型、且任何历史被读取之前的第一个时点if(ilayer_begin||ilayer_end||!m-L[i].sparse) rt_drop_row(i); if(!m-has_mtp) rt_drop_row(c-n_layers);inkling额外rt_drop_row(c-n_layers)因为它没有 MTP 行olmoe同样在 c/olmoe.c 处理。测试 Case 12 验证drop 之后指向该层的记录不计入总数也不会被写回。可信读取信任跟随用户而不是文件rt_read(path, cb, ud)应用全部检查rt_read_ex(path, cb, ud, 1)将读取标记为可信恰好放宽其中一项。检查分两类只有第一类会弯曲身份identity——这份历史是谁的。拒绝信息写着passPINpathto use it anyway因此可信读取必须尊重该文件否则这句话会把用户引向死胡同这也是有意识地在另一个引擎上试用其放置先验的唯一途径。解析几何parse geometry——格式版本以及IKU1文件的维度其中记录的 layer/expert 来自其位置而非记录本身。永不放宽。信任说明用户接受哪份历史而不是这个构建能把字节切对按错误版本解读布局等于静默误读。声明的文本维度不匹配同样拒绝两种拒绝都从不提供绕过途径。判断读取可信的标准是路径如何到达而非文件内容PINfile由用户亲手输入所以可信PINauto与AUTOPIN历史是引擎自行发现的路径——没人担保它们因此承受完整检查。colibri.c把这个区别作为参数传入pin_loadc/colibri.c同一个函数读取两类路径而文件本身无法告诉你它属于哪一类。启动时PINfile走可信路径pin_named1AUTOPIN的自动发现则传 0c/colibri.c。回调自身的边界始终生效任何种类的读取都无法越界写入计数器。rt_read只累加被接受的记录总数——被替换的两个旧读取器是在同一次准入if内部计数的而形状不同的模型写出的历史会让报告给用户的数字虚高测试 Case 9 用一个含越界 layer/expert 的 legacy 文件验证总数为 5 而不是 305。身份拒绝后若用户显式PIN覆盖rt_say_override()会打印一次每次进程仅一次提示placement only; expert ids do not transfer between enginesc/route_trace.h并强调只会影响驻留字节、绝不会改变模型计算内容——最坏情况是自找的变慢而且体现在命中率里。分离计数与追踪以及回调边界需要两个动作发生在不同时点的引擎colibri.c在门控归一化前计数、在后追踪可以分别调用rt_count()与rt_trace()每个moe()调用后调用一次rt_trace_end()推进 call 计数器。rt_load(path)把历史读回计数器rt_read(path, cb, ud)则把记录流式交给排序型消费方。回调返回 1 表示接受记录rt_read只统计被接受的。别忘记把引擎名加入rt_engine_names[]这样涉及它的不匹配才能被点名。运行时环境变量一览相关变量在 docs/ENVIRONMENT.md 中有完整登记变量默认说明PIN未设指向.coli_usage/stats 文件的路径启动时将最热专家置入常驻 hot storePINauto从模型目录实时的.coli_usage播种每轮追加故每次重启的置顶跟随累积的真实负载空目录回退stats.txt两者皆无则本轮不置顶ROUTE_TRACE未设设为路径则把每次路由决策写入该文件测试/分析用COLI_USAGE_DECAY1.0不衰减排序前对已记录计数施加的每轮乘数即半衰期无衰减时约 1800 万次选择后排名冻结、一轮只移动 0.2%#780(0,1]之外的值被忽略USAGE_SAVE1开0为只读运行——历史只加载不写回供基准循环避免污染其正在测量的画像#1039AUTOPIN1开0关闭学习缓存的自动置顶COLI_USAGE_DECAY在rt_save()内部经rt_decay()实现c/route_trace.h默认 1.0 时字节级等同于现状0.99约为 69 轮半衰期舍入保活计数为 1 的专家——遗忘针对的是主导排名的大计数器而不是长尾。USAGE_SAVE0在rt_save()入口统一裁决#1039基准循环不得扭曲其正在测量的画像请求跳过视为成功而非保存失败测试 Case 8 验证文件字节数不变。测试与 CI 保障c/tests/test_route_trace.c 只 includeroute_trace.h不含Model/Cfg/st.h——这本身就是任何引擎都能用的证明。它覆盖的契约点Case 1全零历史保持零字节文件保住PINauto的stats.txt回退Case 2有计数时头部出现数据段为稀疏三元组且-1 5 8是首记录、-2 1 hash紧随其后Case 3/4往返读取恢复每次选择无头的 legacy 文本照常加载Case 4bWindows 写入的 CRLF 历史在rb打开下由fscanf按空白跳过\rMinGW CI 上亦断言Case 5/6错误维度、他引擎历史均被拒且写入者可被点名rt_engine_of(rt_hash(kimi_k3)) kimi_k3未知 id 返回 NULLCase 7/7bIKU1被非 inkling 引擎拒绝inkling 自身仍能解码并按位置落位Case 8旧读取器循环的逐字拷贝恢复完全相同的记录总数与条数THE CONTRACTCase 9总数只统计被接受的记录越界记录不虚增报告Case 10/10b可信读取放行身份、但不放行错误维度与未来格式版本Case 11写出记录恰好三个字段第三铁律Case 12dropped 行不吸收计数、不写回。c/tests/test_798_guards.c 额外对rt_save的临时路径构建做了 fork 级防护测试超长路径snprintf截断与负返回编码错误都必须在触碰文件系统之前拒绝——因为被截断的路径会 fopen/rename 到一个调用方根本没要求的路径静默地从未触及真正的历史文件。而rt_router_pick()c/route_trace.h把原先散落各引擎的路由器 NaN 保护收拢到这一个 header所有专家分数为 NaN 时best保持 -1若直接当索引用会在 release 构建里安静地写坏内存如今它确定性降级到槽位自身索引kk越界时回退 0警告只打一次——该保护随test_logit_nan.c的采样侧修复一起覆盖到全部四个引擎。总结一个格式四个引擎两类消费方route_trace.h把遥测收敛为一个头文件、一套字节格式让.coli_usage历史持久、累计、供PINauto/AUTOPIN排序与ROUTE_TRACE流逐行、逐路由决策、供route_pairs.py生成.coli_pairs供COUPLE预取在所有引擎间字节一致。格式设计的三条铁律——字段全数值、哈希在第三位、恰好三字段——保障了与 header 诞生前二进制的前向兼容可信读取把信任严格限定在用户亲手输入的PIN路径上USAGE_SAVE0与COLI_USAGE_DECAY则分别解决基准污染与历史冻结两个运维问题。对想要扩展 colibrì 的开发者而言接入遥测不过是一次rt_init、若干rt_drop_row、每层一次rt_route、收尾一次rt_save其余全部由这个自包含的头文件接管。【免费下载链接】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），仅供参考
