如何用 Colibrì 在 25 GB 内存主机上跑起 975B 的 Inkling？

如何用 Colibrì 在 25 GB 内存主机上跑起 975B 的 Inkling？

【免费下载链接】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ì 用「专家从磁盘流式读取」的方式，把 Thinking Machines 的 Inkling（975B 总参 / 41B 激活，Apache 2.0）放到普通主机上运行。但官方预转换的 int4 容器里，routed experts 虽然是 int4，dense 权重仍是 bf16：这部分必须常驻内存（每个 token 都要用到全部），实测占 49.4 GB，且加载时load_w会把 bf16 展开成 f32，峰值约 99 GB。文档明确：低于约 64 GB 内存的机器，进程会在生成任何东西之前就被杀掉。

要让 975B 在 25 GB 内存的主机上跑起来，文档给出的路径是把 dense 部分单独量化成 int4-gs64——从 49.4 GB 降到 15.3 GB——引擎会自动识别这个容器。本文按 docs/inkling.md 的流程走一遍：下载预转换快照 → 量化 dense 并放入容器目录 → 构建引擎 → 生成并验证。

开始前需要准备什么

来自 docs/inkling.md 的硬性前提：

• 构建引擎：C 编译器 +make（纯 CPU 构建无其他依赖）；转换脚本需要python3与 numpy；
• 存储：NVMe 磁盘存放快照。预转换容器约469 GiB，dense 量化会再写出约 15.3 GB 的新文件，确认磁盘余量足够；
• 内存：25 GB 主机走的是 int4 dense 容器路径；bf16 dense 的标准构建要求约 120 GB 内存，不适用于本场景。

Inkling 引擎由c/inkling.c实现（构建目标见 c/Makefile），支持音频输入；vision 编码器与 MTP 头不加载。

第 1 步：获取预转换的 int4 快照

在仓库根目录执行（命令直接来自 docs/inkling.md）：

hf download nbeerbower/Inkling-colibri-int4 --local-dir ~/Models/inkling_i4

~/Models/inkling_i4是文档示例路径，可换成你主机上任意 NVMe 目录，后文命令需同步替换。

如果手头有原始 bf16 checkpoint 而不是下载预转换容器，可以自行转换（--watch可在下载进行中边下边转）：

python3 c/tools/convert_inkling_int4.py --indir <bf16-checkpoint> --outdir ~/Models/inkling_i4

其中<bf16-checkpoint>替换为你本地 bf16 checkpoint 的路径。这条路径是原文档给出的替代方案，下载预转换容器是最短路径。

第 2 步：把 dense 权重量化为 int4-gs64

这一步是本场景的核心。脚本 c/tools/convert_inkling_dense_int4.py 的工作方式（摘自脚本头部注释）：只读取各 shard 的 header 建索引；逐张量按 4096 行分块量化，峰值内存约 1 GB；只写一个新文件，464 GB 的 routed experts 分片完全不碰；原始文件以只读方式打开，失败可以重跑。文档给出的整轮耗时约 14 分钟。

先跑--plan估算，它只打印计划、不写任何文件：

python3 c/tools/convert_inkling_dense_int4.py --dir ~/Models/inkling_i4 --plan

输出包含待转换张量数、bf16 输入大小、预估输出大小和磁盘剩余空间。确认磁盘剩余量足够（脚本要求剩余空间不小于预估输出的 1.15 倍，否则直接以[ERR]退出）后，去掉--plan正式执行：

python3 c/tools/convert_inkling_dense_int4.py --dir ~/Models/inkling_i4

成功后生成~/Models/inkling_i4/dense-int4g64.safetensors，脚本还会打印按类别统计的量化误差（相对 L2，在真实权重上实测），例如 attention/shared experts/dense MLP 约 11%、embed/lm_head 约 0.9%。

最后按文档要求把文件放进固定位置，引擎才能识别：

mkdir -p ~/Models/inkling_i4/dense-int4g64 mv ~/Models/inkling_i4/dense-int4g64.safetensors \ ~/Models/inkling_i4/dense-int4g64/dense.safetensors

量化后的精度策略来自脚本与 docs/inkling.md：attention、shared experts、dense MLP 用 int4-gs64（相对 L2 误差约 11%，文档解释这是 4 bit 在该权重分布下的固有代价，不是转换缺陷）；embed_tokens和lm_head保持 int8 逐行量化（约 0.9%，因为它们参与每个 token）；norms、biases、router、conv1d 原样保留。11% 的误差下 975B 在 25 GB 主机上仍能给出连贯输出。

第 3 步：构建引擎

make -C c inkling # 纯 CPU（无外部依赖）

另外还有一个可选分支：

make -C c inkling CUDA=1 # + bf16 residents in VRAM (needs ~37 GB free)

CUDA 构建把 bf16 常驻权重放进显存、要求约 37 GB 空闲显存，并且把腾出的内存让给更大的专家缓存——它面向大内存机器，25 GB 主机走纯 CPU 构建即可。

第 4 步：运行并验证

文档给出的启动方式：

SNAP=~/Models/inkling_i4 ./c/inkling -p "The capital of France is" -n 64

SNAP指向快照目录，-p是提示词，-n限制生成 token 数（到 eos 或达到 N 为止）。

判断 dense 容器是否生效的依据，是启动日志中的这行（文档原文）：

[dense] container int4-gs64: …

看到这行说明引擎已自动加载 int4 dense 容器。如果日志里没出现它，按文档顺序排查两点：dense-int4g64/dense.safetensors是否已移动到正确位置；SNAP是否指向包含该目录的快照根目录。反过来，设置INK_DENSE_Q4=0可以让引擎忽略该容器、回退到 bf16 dense——文档强调，内存充足的机器不需要做第 2 步，什么都不改即可。

关于速度要有正确预期，文档对 25 GB 主机的说法很直白：dense 集占用后只剩约 8 GB 留给专家缓存，对 464 GB 的专家库而言驻留率约 1.7%，decode 是磁盘受限的——单块 NVMe 上每个 token 要几十秒，不是交互式速度。这条路径的价值是让模型在小主机上可运行、可测试，而不是快。文档明确提示：PIN和更大的缓存在你愿意给更多内存时按比例见效。

可调项与边界

• 专家缓存上限cap：第一个位置参数（或coli的--cap）指定每层在内存里保留多少个专家。每层每个槽位约 28 MB，cap × 层数 × 28 MB要和常驻 dense 集共存；int4 dense 容器加 25 GB 主机的组合下，文档建议cap取 2 左右。取小值仍然正确但慢：引擎按cap分批处理 routed experts 并累加，中途被淘汰的专家会重读，而不是被错误值静默替代。

• 缓存预热：每次生成后，引擎按(layer, expert)统计专家选择并写入SNAP/.coli_usage；启动时固定（pin）每层热度最高的前PIN_N个专家（默认cap/2，0 表示只做排序不 pin）。计数跨运行累积，所以预热提示词应当多样，单一提示词训出来的 pin 会过拟合。一次批量预热：

  SNAP=~/Models/inkling_i4 ./c/inkling -f warmup_prompts.txt -n 32

  相关环境变量：PIN=off完全关闭预热；PIN=<path>换用别的统计文件；PIN_N=<n>指定每层 pin 数；USAGE_SAVE=0不重写统计文件（跑基准时用）。

• TOPP：按累计权重截断路由，减少每 token 读取的专家数——这是磁盘受限主机上真正有效的杠杆，但它是与声明的 top-k 不同的计算，默认关闭。开启后运行会报告[topp] … N/M routed used (X% trimmed)，便于度量取舍。

• ATTN_BITS=8：转换脚本的默认行为就是把 attention 也量化为 int8（文档另有一处提到ATTN_BITS=8可把 attention 误差从 11% 降到 1.1%，代价约 +4 GB 内存）。如果你想用内存换精度，保持默认即可；想进一步压内存可以调整，但文档标注 attention 4 bit 会让输出退化，谨慎处理。

到此，25 GB 主机上 Inkling 975B 的最短可执行路径就是：下载预转换容器 →convert_inkling_dense_int4.py两遍（先--plan后正式转换）+ 移动 dense 容器 →make -C c inkling→ 用SNAP启动并确认[dense] container int4-gs64日志。能生成连贯输出即验证通过，速度上接受文档给出的磁盘受限预期；想提升体验，再按上文用预热缓存和TOPP两个文档明确支持的旋钮。

【免费下载链接】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