从源码开始colibri纯C引擎的编译、权重转换与.bin直映射实战【免费下载链接】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当社区热议“25GB内存跑744B参数大模型”“纯C零依赖推理引擎”时多数讨论止步于“能跑”这个结果。但对一名工程师而言真正有价值的问题是另一串引擎是怎么编译出来的、372GB的权重是如何被重新组织成引擎可以按字节直读的容器、所谓“直映射”与“嵌入式C runtime”到底对应源码里的哪些文件与哪些函数。colibricolibrì正是这样一个适合“从源码开始”学习的项目它的引擎是一个单文件 C 程序构建系统能在四种平台工具链间自动切换它的权重容器没有格式序号全靠字节算术推断它的推理路径把“加载权重”做成了内存管理问题而不是显存容量问题。本文将以仓库真实源码为据走完编译、转换、直映射、运行时验证这条完整链路把宣传性描述还原为可复现的工程事实。零依赖编译从 clone 到出二进制项目的仓库结构把“引擎”与“工具链”物理隔离引擎本体是纯 CPython 只出现在一次性转换器c/tools/convert_glm53.py与可选 API 网关c/openai_server.py中运行时没有任何 Python 依赖。九个模型家族各有一个引擎文件——c/colibri.cGLM-5.212738 行、c/inkling.c、c/kimi_k3.c、c/glm53.c、c/qwen36.c、c/olmoe.c、c/deepseek_v4.c——共享同一批头文件safetensors 读取器c/st.h、量化解码c/quant.h、分词器c/tok.h、专家缓存c/expert_store.h。这个“一个模型一个 .c、共享单头文件”的布局见 README.md 的 Repo layout 小节意味着修复一个机制即可惠及所有引擎。编译入口是根目录 Makefile它只做一件事把目标委派给 c/Makefile。后者真正的精巧之处在于平台检测它不用uname而是用$(CC) -dumpmachine读编译器自身的 target triple因此无论是原生 Windows shell没有uname、MSYS2 还是交叉编译判断都跟随工具链而非宿主TRIPLET : $(shell $(DETECT_CC) -dumpmachine 2/dev/null) MINGW : $(findstring mingw,$(TRIPLET)) DARWIN : $(findstring darwin,$(TRIPLET)) LINUX : $(findstring linux,$(TRIPLET))随后按平台分化出四条构建分支Linux x86-64 默认ARCHnative-marchnative解锁 AVX2/AVX-VNNI 点积核Windows 默认ARCHx86-64-v3以得到可移植的 AVX2 二进制Apple Silicon 用 clang Homebrew/MacPorts libomp找不到就退化为单线程并明确警告aarch64 Linux 甚至会对__ARM_FEATURE_MATMUL_INT8做编译探测——如果编译器无法为当前核生成 i8mm 指令就自动回退到更保守的-marcharmv8-a对应 c/Makefile 中的 #631 修复。CUDA/HIP/Metal/Vulkan 全部是CUDA1、METAL1、VK1之类的显式开关默认不编译CPU 构建零第三方依赖。实际动手只需要两步。./setup.shc/setup.sh会检查 make、gcc/clang、OpenMP然后执行make -s colibri ARCH${ARCH:-native}并跑自检cd colibri/c ./setup.sh # 检查 gcc/OpenMP构建引擎运行 tiny 自检构建系统还有一个值得注意的细节.build-config配置戳c/Makefile 中 #306 的修复。它记录$(CC)|$(CFLAGS)|$(LDFLAGS)|CUDA...|ARCH...仅在配置变化时重写并触发重链避免了“先make colibri.exe再make colibri.exe CUDA_DLL1却静默得到旧二进制”这类看似成功实则错误的构建。自检环节更有意思——它不是简单的“能启动”而是对照一个随机初始化的小模型做逐位置 token 级验证SNAP./glm_tiny TF1 ./colibri 64 16 16 # engine self-test: 30-32/32 positions (FP near-ties 与工具链相关属正常)这个 tiny oracle 由 c/tools/make_glm_oracle.py 生成先在 FP8 上做一次权重 round-trip再计算ref_glm.json的 greedy 参考输出确保转换器读到的模型与引擎解码的模型是同一个从而把“编译器改变浮点收缩顺序导致 token 漂移”这类回归挡在 CI 之外。这正是 README 里“no SLA on speed, hard guarantee on semantics”的落地方式速度没有承诺语义正确性是硬约束。权重转换从 756GB FP8 到按字节直读的 int4 容器拿到引擎二进制之后真正的重头戏是权重。社区情报反复强调的“.bin 权重直映射”值得拆开讲它不是一个单一格式而是一整套“布局即 ABI”的设计——权重的字节布局就是 C 引擎可以直接消费的结构省去了运行时解码索引层。转换入口是./coli convert --model dir底层脚本是 c/tools/convert_glm53.py 与 c/tools/convert_fp8_to_int4.py。两条硬性工程约束决定了它的写法。第一磁盘安全。脚本逐 shard 下载、逐 shard 转换、转完即删源文件全程不需要 756GB 同时落地--min-free-gb在每 shard 前检查剩余空间空间不足就[WAIT]轮询而不是失败。第二可续传。.converted.json记录已完成 shard中断后重跑自动跳过这正是 WSL2 部署实践中“转换耗时数小时但可随时中断”说法的源码出处。真正决定“直映射”品质的是量化器 quant_int4_groupeddef quant_int4_grouped(w, gs64): qmax 7 ngroups (I gs - 1) // gs ... q np.clip(np.rint(wr / s), -8, qmax).astype(np.int32) v0 (q[:, 0::2] 8).astype(np.uint8) # 偶数列进低 nibble out[:, :v0.shape[1]] v0 v1 (q[:, 1::2] 8).astype(np.uint8) out[:, :v1.shape[1]] | (v1 4) # 奇数列进高 nibble注意文件头注释的承诺“Copia bit-identica … stesso np.rint, stesso packing dei nibble”——转换器与引擎共享完全相同的舍入np.rint对应 C 侧lrintf与 nibble 打包规则因此转换产物无需任何对齐修正即可被 c/quant.h 的matmul_i4_grouped直接消费。转换器还按张量名分类路由.mlp.experts.*走 int4 量化每 64 元素一个 f32 scaleembed_tokens、各 proj 权重保持 BF16dt_bias、norm.weight等保留 F32因为后者只占约 3% 参数量不值得为它们付出精度代价。引擎读取这些容器的方式是“直映射”的第二层含义没有格式序号格式从字节数推断。权威读取器qt_resolve_fmtc/colibri.c只凭“权重字节数 scale 字节数与[O,I]形状的关系”即可判定张量属于 fmt0…8 中的哪一种。c/../docs/FORMATS.md 维护了完整的格式注册表0 f32、1 int8-row、2 int4-row、3 int2-row、4 int4-grouped、5 int3-g64、6 E8/IQ3、7 MXFP4、8 fp8-e4m3-b128。容器在磁盘上仍是 safetensors但读取路径是 c/st.h 的pread直接按偏移读字节——刻意不用 mmap配合posix_fadvise(DONTNEED)防止页面常驻进程这是修复“mmap 导致 RSS 爆炸”历史 bug 的关键决策O_DIRECT双胞胎 fd 则让大块流式读绕过 page cache在 ext4-in-VHDX 上实测从 0.8 GB/s 提升到 2.3 GB/s。路由专家的“直映射”到达极致体现在 c/expert_ffn.h 的 planar 布局上。一个 64 元素的块是 32 字节字节 k 的低 nibble 存元素 k、高 nibble 存元素 k32全部以v8无符号形式存储。这样 SIMD 解包时and 0x0F就能按序得到 0..31srli 4得到 32..63——永远不需要付出 unpack 指令而无符号 nibble 又恰好原生喂给vpdpbusddot(u,x) dot(u,x) - 8*sum(x)。这就是为什么 Qwen3.6 全驻留实测中MoE 权重读取与计算能从“int8 解包展开”的 34ms/token 降到“int4 原始字节”的 9ms/token见 c/expert_ffn.h 头注释。至于字面意义上的.bin文件它们承担的是缓存状态直映射学习到的热专家固定清单写入hot_pinned.binc/olmoe.c、Kimi K3 的循环状态检查点写为k3_ckpt_*.binc/kimi_k3.c、DeepSeek V4 的磁盘前缀检查点是ckpt_fingerprint_n.binc/deepseek_v4.c而每 turn 更新的路由热度落在.coli_usage、跨重启的 KV 状态落在.coli_kv。这些侧车文件不是模型权重却决定了下一次推理的延迟——热专家被固定后解码可以从“每次从磁盘拉取”变为“命中常驻集”。嵌入式 C runtime从单机流式到端到端低延迟验证权重容器设计好了剩下的问题是如何在“25GB 内存 一块 NVMe”上把 744B 参数跑成低延迟服务。答案藏在两处源码里。第一处是流式推理的核心路径。每个 token 的每一层都走同一套五步route → union → place → overlap → learn。路由决定激活哪些专家被激活专家做 batch-union同一 batch 内每个专家只读一次放置决定专家从哪个 tier 取重叠让磁盘读取与计算并行学习把高频路由写回.coli_usage。支撑这五步的机制分别在 c/st.h单个 expert 的三张矩阵相邻存放、一次pread读完、c/expert_store.h有界异步 I/O 池PIPE1、以及 router-lookahead 线程PILOT1路由可预测性实测 71.6%。多层级的放置关系用一张图就能说清稠密部分attention、共享专家、embedding约 17B 参数以 int4 常驻 RAM约 9.9GB19456 个路由专家75 MoE 层 × 256int4 下每个约 19MB躺在磁盘上按需流入LRU 缓存 学习到的固定热集 可选的 VRAM tier 构成三级安置。第二处是嵌入式 ABI。社区情报提到的“嵌入式 C runtime”对应 c/segment_runtime.h 与 c/edge_runtime.h 两个引擎中立边界make -C c segment-edge-library产出c/build/segment/libcolibri_segment_edge.a外部消费者链接该静态库后就能驱动一个“只跑中间层段”的引擎——tokenizer、embedding、final head 在边界进程中间层在 Segment 引擎里两者通过coli_segment_run传递边界激活与状态快照。七个模型家族都提供了注册即用的适配器c/segment_adapters.h、c/edge_adapters.h而普通 CLI 默认不链接这些适配器存量推理路径完全不受影响——这是“嵌入式”而非“侵入式”的关键。端到端低延迟的验证体系同样扎实。正确性维度tiny 夹具把引擎输出与 transformers oracle 逐 token 对比c/tests/glm53_tiny_harness.pyteacher-forcing 与 greedy 双通道都精确到 tokenMLA 注意力把每个 token 的 KV 状态从 32768 浮点压到 57657× 压缩并持久化到.coli_kv跨重启的对话无需重新 prefill 即可“温启动”字节级等同未中断会话。延迟维度ladder 图给出了同一容器在不同硬件上的诚实刻度——6×RTX 5090 全驻留 5.8–6.8 tok/s、128GB CPU 桌面约 1.8 tok/s、25GB 开发机冷启动 0.05–0.1 tok/s。项目明确把最后这个数字当作“诚实的下限基线”而非成绩因为它的设计哲学是放置只改变速度绝不悄悄改变模型语义。在端到端路径上还有一层低延迟优化与“生成”解耦Brio 模式不生成 token而是直接读取候选答案的概率并输出熵completion_tokens为 0文档阅读一次、答案必须在允许集合内实测在同一 CPU 机器上比生成式回答快 2.4×四字段 schema到 5.7×四问一文档详见 c/../docs/brio.md。当“低延迟”的诉求是快速判定而非生成文本时这是引擎给出的另一个答案。结语把社区情报与仓库源码对照后会发现colibri 最稀缺的不是“744B 能跑”这个结果而是它把每个性能论断都做成了可测量的工程承诺编译器切换用 target triple 而不是宿主名量化器与解码器共享同一套舍入数学格式身份靠字节算术而非协调出来的序号正确性靠 tiny oracle 的逐 token 对比而非抽样印象。对于想研究 MoE 推理系统的人这条“编译 → 转换 → 直映射 → 端到端验证”的链路本身就是一份完整且可复现的教材。【免费下载链接】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），仅供参考