Colibri 调优与运行时旋钮实战指南：让 MoE 模型在自有硬件上跑得更快

Colibri 调优与运行时旋钮实战指南让 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导读本文围绕 colibri 的运行时调优体系展开系统讲解采样参数、专家缓存、磁盘 I/O 流水线、资源规划coli plan/coli tune、学习型缓存、路由器前瞻预取与投机解码等核心旋钮。读完你将掌握一套默认安全、按需开启的调优方法论能够针对自己的机器产出可复现的性能档案并理解每个旋钮背后的源码实现依据。总原则一切都是可选的opt-incolibri 的全部调优旋钮默认关闭或取保守值这是刻意设计的默认配置必须保证在任何机器上执行./coli chat都是安全的。当你逐步开启这些旋钮时本质上是把通用安全兑换成针对你这台机器的性能。调优旋钮分布在三个层面本文聚焦与性能/资源最相关的引擎层旋钮CLI 标志coli run/chat/plan/tune等子命令的--flag参数多数会映射为引擎环境变量环境变量引擎c/colibri.c及各姊妹引擎通过getenv()读取的变量CLI 会把你的整个环境透传给引擎策略文件coli tune测得的机器/模型/引擎专属档案由--auto-tier自动加载。完整的变量清单见 SETTINGS.mdCLI 与标志→变量映射和 ENVIRONMENT.md引擎环境变量全量参考由扫描c/*.c、c/*.h、c/*.cu、c/*.mm中所有getenv()调用点生成。最值得关注的旋钮下表浓缩了日常调优最常用的旋钮及其作用后文逐一展开旋钮作用--temp Ttoken 采样温度默认 0.7 nucleus 0.90为 int4 量化调校0 贪心--topp 0.7自适应专家 top-p省 30–40% 磁盘流量有损——会打印警告--ngen N每次回答的最大 token 数聊天中用:more可续写被截断的回答--repin N每发射 N 个 token 就重排一次热专家RAM/VRAM 层级热更新RAM_GBn为专家缓存申领比保守自动检测更多的 RAMPINstats/PIN_GBg从实测用量档案固定最热专家到常驻热库DRAFTnMTP 投机草稿深度0 关闭投机GRAMMARg.gbnf用 GBNF 文法约束草稿产出受约束的 JSON/NDJSON详见 grammar-draft.mdTHINK1开启 GLM-5.2 的推理块reasoning blockPILOT1路由器前瞻磁盘预取见下文专门小节URING1仅 Linux批量专家 I/O隐式启用PIPE1PIPE0关闭异步专家加载池默认开启——用pread与 matmul 重叠磁盘服务时间 −18%DIRECT1专家读取使用O_DIRECT在 Strix Halo 上单独测量65%COLI_NUMA1在多路 CPU 主机上跨 NUMA 节点交错常驻权重CACHE_ROUTE1缓存感知的最大秩路由可选详见 CACHE_ROUTE.mdAUTOPIN0关闭学习缓存的自动固定CAP_RAISE0不自动扩大专家缓存上限KVSAVE0关闭 KV 缓存持久化TF1教师强制teacher-forcing验证模式一个重要的资源约束需要提前理解自动历史固定autopin与自适应 LRU 共享同一个专家 RAM 预算。colibri 会限制自动固定的规模以保留无固定no-pinLRU 的容量显式设置的PIN与PIN_GB优先级始终更高不会被自动策略削减。资源策略coli plan与分层放置三层模型hot / warm / coldcoli plan会为模型计算完整的资源放置计划报告三个层级hotVRAM常驻显存的专家层warmRAM内存中的专家 LRU 缓存层colddisk磁盘冷备份层。计划同时给出每个放置决策的原因和预期的性能瓶颈。默认的--policy quality与--policy balanced两种模式会保留检查点自带的量化与路由器决策除非你显式传入--topk或--topp——这两个显式的有损覆盖会打印警告并继续执行。计划的输出还包含一份机器可读的next_actions列表并在终端渲染展示。缺失的存储测量项被标记为required必需后续的剖析与调优工作项被标记为recommended建议。这些动作产出的是改进这台机器上计划的证据——它们不会静默开启一个未经测量的优化。这与 c/resource_plan.py 中 read-and-display only 的测量契约一脉相承例如对model/.coli_ssd缓存文件的读取只分类不重测绝不在没有证据时替引擎下结论。物理核心 OpenMP 调整自动分层计划会按物理核心数设置 OpenMP 线程数并把工作线程绑定到各核心上。原因在于内存受限的量化内核在 SMT 兄弟线程争抢有限内存通道时可能急剧退化。GLM、Kimi K3 与 OLMoE 引擎在直接启动时也应用这一物理核心上限。显式的OMP_NUM_THREADS与COLI_NO_OMP_TUNE开关优先级最高始终生效。实现层面这套逻辑位于 c/omp_tune.h它只负责按物理核心定线程数而把 spin-wait 策略OMP_WAIT_POLICYactive等留给各引擎独立控制。关键设计约束值得了解只做安全的一半omp_set_num_threads()是运行时 API、立即生效所以无需 re-exec而OMP_WAIT_POLICY由 libgomp 构造函数在main()之前读取必须在运行时重新执行才能生效。失败不猜测如果物理核心数无法确定代码返回 0 并保留 OpenMP 默认值绝不瞎猜——一个错误的计数比没有计数更糟历史 issue 中曾因静默回退到 1 个核心而把解码钉死在单核上。Kimi K3 / OLMoE 只取线程数这一半它们是最磁盘受限的引擎spin-wait 会让空转团队偷走真正干活儿的 I/O 池的核心加上它反而是可测量的退化。关于#471的坑重要过去在 Linux 上导出OMP_PROC_BIND/OMP_PLACES会与引擎的一次性 OpenMP 调优 re-exec 发生冲突——re-exec 后的镜像继承了首个镜像的 place-0 线程绑定整个团队全部落到一个核心上约20× 减速。现在引擎在 re-exec 前会先把亲和性重置到所有在线 CPU因此显式OMP_*绑定可按文档正常工作。COLI_OMP_TUNED1仍是跳过 re-exec 的逃生舱。实操命令# 查看模型在三层上的放置计划 coli plan --model /models/glm52_i4 --policy quality # 按计划自动分层运行 coli run --auto-tier --policy quality Explain MoE offloading # 显式的研究性路由器缩减有损会打印警告 coli run --policy experimental-fast --topk 4 Benchmark prompt实测机器档案coli tunecoli plan依据容量与拓扑给出一个安全的起点coli tune则在真实模型与真实机器上测量剩余的可调度选择并保存一份硬件/模型/引擎专属的性能档案# 测量并保存本机最优执行档案 coli tune --model /models/glm52_i4 # 下次运行时自动套用档案 coli run --model /models/glm52_i4 --auto-tier Explain MoE offloading各引擎的校准方式不同GLM为每个候选配置生成一条校准续写并对它做教师强制teacher-forced验证姊妹引擎Inkling/OLMoE/Qwen/Kimi K3 等使用共用的服务协议——一个引擎进程为某个候选的所有请求保持存活确定性提示按固定顺序轮换。这样既保留了专家缓存的热度又测量了真实的混合聊天场景而不是反复加载单进程或让缓存只学会一条精确提示。每个候选的贪心输出都会逐提示对比任何字节漂移都会直接淘汰该调度变更。有界扫描bounded sweep校准覆盖的执行旋钮包括OpenMP 线程数、NUMA 放置、I/O 重叠、直接 I/O、CUDA 流水线、DeepSeek V4 专家加载通道数等。当磁盘上仍有冷专家时还会测试规划器专家缓存额度的75% 与 50%。以下内容永不缩减稠密权重、KV/工作区预留、OS 保留内存且任何候选都不得超过规划器的安全基线。各引擎收到的资源上限形态不同GLM / Inkling / OLMoE / Qwen测量后的每层槽位上限slots-per-layer capDeepSeek V4整个进程的RAM_GB上限Kimi K3在其不变的全进程上限内设置K3_EXPERT_GB。扫描从不修改权重、量化、路由器决策、TOPK、TOPP或采样参数。可用可重复的--rotate-prompt选项替换内建的次级工作负载提示。存档门槛反序门控候选配置只有在中位吞吐提升 ≥ 3%、且专家命中率波动在0.5 个百分点以内、报告的 TTFT/p99 延迟与基线差距在20% 以内时才会被保存。胜出者随后会在最终基线之前重跑一次——这个反序门控把剩余的热缓存优势让给基线从而剔除启动漂移。否则就记录基线、不应用任何覆盖。已保存的档案由--auto-tier加载--ram、--cap、RAM_GB、K3_EXPERT_GB等显式设置始终优先。资源胜出者在每次启动时都会与当前计划重新核对——如果档案是在内存更充裕时测得的现在内存不足就不会被套用避免超配。--no-tune-profile可绕过已保存的档案。档案存储位置与指纹档案存放在$XDG_CONFIG_HOME/colibri/tuning通常为~/.config/colibri/tuningWindows 上为%LOCALAPPDATA%\colibri\tuning。引擎二进制、模型元数据、CPU 拓扑或 GPU 清单任一变化都会产生新的指纹从而避免复用陈旧的测量结果。磁盘是恢复源不是解码目标磁盘只是不可变的恢复来源而不是常规解码目标。如果计划让冷专家字节留在磁盘上那么速度取决于缓存命中率而输出质量不受影响——这是理解整套调优体系的前提。冷专家延迟流水线冷专家读取可走延迟流水线常驻 RAM/VRAM 专家照常执行缺失专家在一个有界后台 I/O 池中加载随后冷结果在层完成前汇合。该池仅在PIPE1下启用PIPE_WORKERSn设置其工作线程数默认 8。剖析报告同时给出磁盘服务时间与更小的前台可见等待时间让重叠收益显式可见。从源码看PIPE是字节级一致的只重排 I/O 顺序PIPE_WORKERS在URING1时还充当每个 io-wq ring 的最大工作者数上限 64。无损在线重排REPIN--policy balanced启用无损在线放置REPIN64在安全的请求边界用结合了衰减会话频率与近期访问的逐层 LFRU 分数评估每次替换至多四个足够冷的固定专家。--policy quality默认关闭在线替换REPIN0始终禁用。学习缓存越用越快colibri 会记录你的用量实际路由到了哪些专家——写到模型目录旁的.coli_usage每轮对话更新一次——并在启动时自动把最热的专家固定到空闲 RAM 中。这就是colibrì 越用越快的机制来源。PINauto直接从实时用量历史播种固定集合与PINfile的信任模型不同详见下文。缓存自动适配内存2026-07-10 起专家缓存会自动向上扩展去填满你的--ram预算而不仅仅是向下收缩。因此如果你在 2026-07-10 之前基准测试过 colibri请重跑——当时的数字被上限压制了。在线层级适应--repin N可选在安全的回合边界一个衰减的会话热力图会把冷固定专家替换为更热的流式专家。25% 的滞回hysteresis与四次交换上限防止层级抖动。持久化的.coli_usage仍是长期信号不会被衰减。用量历史的底层格式route_trace.h是.coli_usage与ROUTE_TRACE追踪流的统一实现格式为文本、每行一条记录、稀疏仅非零计数-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 有完整论证任何字段都不能是字符串——非数字字段会让旧读者的fscanf返回 3从而静默丢弃其后所有记录。因此引擎以 FNV-1a 32 位哈希标识而非名字名字表保留在头文件中以便用文字报告不匹配。哈希必须放在第三个字段——旧读者用%d解析第二个字段而 32 位哈希常超过INT_MAXglm_moe_dsa哈希为 3815245270超过 INT_MAX放在第二字段是未定义行为。所以版本号小放第二哈希放第三。负层号是通用机制而非特例所有读者都跳过首字段为负的记录因此未来可以随时新增头记录类型旧构建会跳过它而不是崩溃。硬性规则是恰好三个数字字段绝不多于一个——四个字段的记录不会被跳过而是残留一个字段、使读者失步并凭空捏造记录把残留字段拼上下一行的前两个字段。另一个关键点空历史就是一个零字节文件。PINauto通过测试文件大小判断历史是否可用为空时回退到stats.txt。因此一次什么都没路由的运行不会写入任何头记录从而保住这个回退机制。旧格式兼容旧文本无头记录的同一三元组被原样接受IKU1inkling 的稠密二进制布局仅由 inkling 自己读取其他引擎按名拒绝。信任模型方面信任跟随用户而非文件——PINfile是用户显式输入的路径受信任PINauto与AUTOPIN历史是引擎自行找到的路径无人背书走完整校验。详见 routing-telemetry.md。路由器前瞻预取PILOT1实验性GLM-5.2 的专家路由是可提前测量的把第 L1 层的路由器应用于第 L 层的 post-attention 状态能召回71.6%的真实 top-8对比与上一 token 相同的专家仅 41.3%。基于这一性质PILOT1从专用 I/O 线程发出下一层专家预读同时当前层继续计算PILOT_REAL1把预取负载移出关键路径在大型缓存主机上测量命中率11ppPILOT_TWO1把计算出的共享专家折叠进预测召回3%。相关控制变量PILOT_WORKERS阻塞式PILOT_REAL路径的加载线程数默认 1调高可提升 NVMe 队列深度钳制在 [1,16]、PILOT_K每步预取的专家数PILOT_REAL时默认 6否则 8、PILOT_EVICT_GUARD防止预取专家在被使用前被 LRU 驱逐。注意在磁盘饱和的主机上仅提示hint-only的 PILOT 可能是净负面效果——请务必在你的机器上实测。投机解码与可复现性投机解码要求草稿路径与验证路径计算同一个函数SPEC_PIN1默认保证草稿存活期间发出的每个 forward 都固定到平台的 S1 内核族——避免草稿/验证数值分歧导致接受率崩塌历史上这是 CUDA 与冷流式专家混跑时的已知陷阱见 ENVIRONMENT.md 中COLI_CUDA_MTP的讨论。跨运行的字节级精确复现配方DRAFT0若还要内核族/GPU 无关性再加IDOT0 COLI_CUDA0。接受率在--topp下跨引擎版本不可比。对话热重开关掉聊天明天接着聊coli chat在每轮对话后把压缩后的 MLA KV 缓存持久化到磁盘.coli_kv约182 KB/token增量追加、崩溃安全。关掉聊天、明天重开模型仍然记得整段对话并且零重新预填充zero re-prefill——已通过字节级验证与不间断会话完全一致。:reset清除它KVSAVE0关闭保存与加载无损往返不改变输出相关扩展KV81用 fp8 e4m3 逐行 scale 存储 MLA 潜在 KVKV RAM 约 3.9× 更省.coli_kv缩小约 4×KV_TQ4是推荐的次字节量化档旋转 int4 编解码器KV RAM 较 f32 约省 7.6×。两者目前仅 CPU attention 路径GPU 融合注意力快速路径会回退到 CPU 消费者并强制COLI_CUDA_PIPE0。一份完整的实操流程从测量到落地综合全文在一台新机器上把 colibri 调到最优的推荐流程是# 1. 先了解硬件与计划含机器可读 JSON 与 next_actions coli plan --model /models/glm52_i4 --policy quality --json # 2. 按计划自动分层跑一次验证可运行 coli run --model /models/glm52_i4 --auto-tier Explain MoE offloading # 3. 让引擎学习你的真实用量多聊几轮.coli_usage 会累积 coli chat --model /models/glm52_i4 --auto-tier # 4. 实测并保存最优执行档案含磁盘 I/O 与缓存额度扫描 coli tune --model /models/glm52_i4 # 5. 之后的运行自动套用档案需要对照时可绕过 coli run --model /models/glm52_i4 --auto-tier --no-tune-profile ...随后按需叠加进阶旋钮遵循一次只改一个变量、字节级对比、在目标机器上验证的原则磁盘快而内存充足PIPE1 PIPE_WORKERS8 DIRECT1DIRECT强依赖驱动器必须实测真 NVMe DRAM 缓存常是大赢家QLC/无 DRAM 盘可能中性甚至为负多路 CPU 主机COLI_NUMA1追求磁盘服务时间最低Linux 上URING1隐含PIPE1用批量化 SQE/CQE 取代阻塞加载线程需要确定性输出COLI_TEMP0 DRAFT0 IDOT0 COLI_CUDA0贪心USAGE_SAVE0冻结用量历史输出必须是受约束的 JSON/NDJSONGRAMMARpath.gbnf详见 grammar-draft.md。各姊妹引擎有自己的专属旋钮族Kimi K3 的K3_*、Inkling 的INK_*、Qwen3.6 的QWEN_*/Q36_*、DeepSeek V4 的V4_*/DSV4_*、OLMoE 的HOT/WIDE/SMOOTH等且引擎之间不共享旋钮集——给colibri设置INK_*变量不会生效也不会有警告。跨引擎部署时务必查阅 ENVIRONMENT.md 中对应的引擎小节以及 deepseek-v4.md 的 V4 环境参考。结语colibri 的调优哲学可以概括为三句话默认配置在任何机器上安全一切性能旋钮都可选、可测量、可回退磁盘只做恢复源、绝不做解码目标。从coli plan的安全起点出发用coli tune建立带指纹的机器专属档案再让学习缓存与路由器预取在真实用量中持续生效——这就是让极小的引擎跑动庞大的模型在日常硬件上成立的关键路径。【免费下载链接】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），仅供参考