免解析加载的秘诀：mmap 直读张量与 Needle 的秒级冷启动

免解析加载的秘诀mmap 直读张量与 Needle 的秒级冷启动【免费下载链接】needleAutomation foundation model for tiny devices: 2-bit, 8-29 MB, tool calls, ASR, structured extraction and embeddings on phones, wearables, smart homes, robots, cars and microcontrollers.项目地址: https://gitcode.com/GitHub_Trending/needle20/needle在大模型的世界里pip install之后的第一次agent.run()往往要等上好几秒——那段时间里加载器正在干一件和推理无关的粗活扫描 JSON 头部、按字符串名字逐个匹配张量、把整个权重文件从磁盘拷贝进内存、再完成一次反序列化。对一台手机或手表来说这几秒既是功耗黑洞也是用户能感知到的最长等待。Needle 给出的答案是把加载路径本身删掉权重、分词器、量化码本全部封装进一个.cact二进制用固定头部 无名单张量目录 mmap 按偏移直读代替解析式加载。45M 参数只占 14MB 文件Needle 3 为 8–29MB端侧运行内存稳定在 28MB 量级。本文直接从仓库源码出发拆开这个容器的字节布局看免解析到底省掉了什么、mmap 又是如何让张量原地可读的。固定头部与无名单张量目录把解析从加载路径上删掉一切的关键在 needle/model/export.py 的模块文档里写得很直白.cact是the deployment weights the C / single-mega-kernel inference readsmmap or linked read-only section; no parsing——引擎读取的权重经过 mmap 映射或链接进只读段全程不做解析。为什么可以做到因为容器的字节布局把需要解析才能获得的信息全部提前变成了固定偏移HEADER (49 个 u32 尺寸字段rope_theta 为 f32) tag, num_tensors, codebook_len, kv_window, kv_bits, vocab, out_vocab, d_model, num_heads, num_kv_heads, num_layers, qk_head_dim, v_head_dim, max_seq_len, hada_n, mhc_lanes, ... DIRECTORY (num_tensors 条记录每条 44 字节无名字) u8 dtype, u8 ndim, u16 pad, u32 shape[4], u64 offset, u64 nbytes, u32 group_size, u32 bits TENSOR ORDER (运行时按位置索引) embedding; 每层 [norm_in, q_proj, k_proj, v_proj, ...]; 9 个 mHC 块; 每个 engram 站点 [tables, key_proj, value_proj, taps]; final_norm; 可选 probe heads; RAW tokenizer对照源码目录记录的 struct 是_REC_FMT BBHIIIIQQIIdtype、ndim、shape、u64 offset、u64 nbytes、group_size、bits每条固定 44 字节REC_SIZE struct.calcsize(...)直接算好一个张量名都没有。张量按固定 canon 顺序存放、按位置索引运行时读完 49 个 u32 的头部就掌握了全部几何信息——so one binary loads and runs any configuration of the (single) architecture。这带来两个直接后果没有字符串索引。传统格式里加载器要遍历权重表、对名字做哈希或字典查找才能把磁盘字节和内存里的参数对象对上。Needle 的寻址是纯算术header_size num_tensors * 44 该张量在 canon 顺序中的位置再跳到offset读nbytes。数值语义被锁进文件。kv_window滑动窗口宽度和kv_bitsKV 缓存量化位宽直接写入头部注释说得更狠a model quantized for one must be RUN at it - leaving either to a runtime flag silently serves the wrong numerics。量化过一次的模型用运行时 flag 去改它只会静默地得到错误的数值——所以这类元信息干脆不进加载流程直接进字节布局。分词器同样不例外SentencePiece BPE 表作为唯一的 RAW 附件跟在模型张量后面tokenizer 导出逻辑 中的_tokenizer_blob自包含、无外部文件依赖。read_tokenizer_blob()甚至可以在不解包任何权重的情况下从头部 目录的固定偏移里把分词器整段抠出来。mmap 之下张量按偏移直读免解析只是省时间真正省内存的是 mmap 的按需分页语义。引擎拿到needle_load(data, size)之后权重页在首次被访问时才触发缺页加载未触达的页不占用物理内存而文件系统的 page cache 一旦温热第二次冷启动就是纯内存访问。Python 侧的桥接把这个流程压到了三行needle/_worker.py 的子进程加载逻辑with open(config[weights], rb) as handle: weights handle.read() if lib.needle_load(weights, len(weights)) 0: raise RuntimeError(fneedle_load failed for {config[weights]})而引擎侧的 C API 同样极简needle_init(system, tools, index)做前缀初始化needle_complete(text, pcm, samples, max_new_tokens, out, out_size)直接产出结构化响应。一个模型就是一个字节数组从打开文件到引擎就绪之间没有任何中间对象。为了让按偏移直读在计算侧也成立导出器还做了两件布局级优化见 export.py 的格式注释预转置matmul 权重写成[out, in]输出行的 reduction 轴连续正是 GEMV/GEMM 流想要的内存排布量化组也沿这条轴切分层优先LAYER-MAJORembedding → layer 0 全部张量 → layer 1 → ... → final_norm保证单层推理的工作集在地址空间里连续——内核处理完一层缓存里的下一块数据恰好就是下一层天然贴合顺序推理的访存模式。量化的落地是 CQ 格式Cactus Quants每个[out, in]矩阵先按 128 的 group 切块块内做归一化 Walsh-Hadamard 旋转后量化到共享的 Lloyd-Max 单位球码本cb2 | cb3 | cb4 拼进头部blob 里只存打包后的索引 每组的 FP16 L2 范数。重建公式就一行w_group (codebook_bits[idx] * norm) H。三元bits5和二元bits1权重甚至不带码本——{-c, 0, c}和{-sqrt(2/pi), sqrt(2/pi)}是解析式直接硬编码进引擎。这意味着权重从磁盘到寄存器全程以紧凑格式流动反量化发生在内核里而不是加载时。这正是 Whistle 能搭便车的原因语音模型和文本模型共用.cact容器、共用量化、共用 C 引擎needle_load读的是这个.cact里装的是什么模型一个运行时同时服务工具调用与语音识别。对端侧功耗与首 token 延迟的实际影响免解析加载对端侧的真实价值要放到功耗和首 token 延迟两条线上看加载期零解析 冷启动接近纯 I/O 成本。传统加载器在首 token 之前还要烧掉 CPU 做 JSON 扫描、字符串匹配、逐张量 memcpy这些在 14MB 的单文件容器里全部消失。引擎第一次触页后后续启动直接命中页缓存毫秒级完成模型就绪。常驻内存被按需分页压住。45M 参数、W4A8 量化WEIGHT_BITS4、ACT_BITS8见 needle/model/quantize.py下14MB 权重跑在 28MB 内存预算内mmap 保证没被算过的权重不占物理页——这对智能手表、耳机这类只有几十 MB 可用内存的靶场是硬性要求。首 token 延迟受益于层优先 紧凑权重。单层工作集连续、权重按 GEMV 流预转置、反量化内联进内核Whistle 就是现成证据16.9MB 的模型比 Whisper base 快 6.6 倍到达首 token且在自己报告ttft_ms的 API 里把这一指标作为一等公民输出见 needle/agent/whistle.py 的 transcribe 返回结构。配合 needle/agent/fetch.py 里 17 个平台目录macOS、Linux 各架构、Android、iOS、watchOS、wasm……每个平台一份预编译引擎、同一套.cact权重免解析加载从 Python 包一路延伸到裸机把加载从解析变成映射本质上是把文件格式当作内存布局来设计头部即几何、目录即偏移、张量即地址。当模型小到 14MB、设备小到手表这种少做一件事的工程取舍往往比任何内核优化都更能决定用户等到的第一个 token 有多快。【免费下载链接】needleAutomation foundation model for tiny devices: 2-bit, 8-29 MB, tool calls, ASR, structured extraction and embeddings on phones, wearables, smart homes, robots, cars and microcontrollers.项目地址: https://gitcode.com/GitHub_Trending/needle20/needle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考