1. 模型选型本文以Felladrin/Minueza-32M-BaseMistral 家族为例演示如何把一个 HuggingFace 小模型转成 MCU 能直接读取的量化权重文件并逐字节理解自定义二进制格式 KMCU v1。模型关键配置layers10dim312heads12kv_heads4head_dim26ffn1092vocab32002原始config.json关键字段转换脚本据此生成 KMCU 头{ architectures: [MistralForCausalLM], model_type: mistral, hidden_size: 312, num_hidden_layers: 10, num_attention_heads: 12, num_key_value_heads: 4, intermediate_size: 1092, vocab_size: 32002, max_position_embeddings: 2048, hidden_act: silu, rms_norm_eps: 1e-6, rope_theta: 10000.0, bos_token_id: 1, eos_token_id: 32000, tie_word_embeddings: false, torch_dtype: float32 }架构特性决定了推理内核要支持什么RMSNorm非 LayerNormrms_norm_eps1e-6RoPE旋转位置编码rope_theta10000GQA12 个 q head 共享 4 个 kv headkv_rep 3SwiGLU激活hidden_actsilu权重共享原模型tie_word_embeddingsfalse带独立lm_head共32.79M参数。转换脚本默认尊重配置保留lm_head→ 镜像18.07 MB装不进 16 MB Flash 的model分区。本系列全程使用的是--force-tie强制lm_head复用tok_embed省下 32002×312 的输出头得到22.81M / 12.58 MB装得下 Flash。--force-tie的代价远不止「省 9.98M 参数」它丢弃了已训练的输出头。实测同一 prompt[1,450,2217,4996]下两种镜像的贪心输出不是「略有差异」而是完全不同--force-tie12.58 MB→ epidCl cant epidClCl cant epidCl dialog epidCl near whether reading or ... 词沙拉 默认18.07 MB → ita, 2012\nThe 2012 season was the 2012 season. 通顺英文本系列 M1/M2/M3 的全部性能读数与对拍金标准都出自--force-tie镜像——它是为「装进 Flash」刻意降级的产物。复现本文时请务必带上--force-tie否则拿不到下面的金标准这不是你操作错了。注eos_token_id32000但vocab_size32002Mistral 家族的 padding/占位 tokendecode 用的是贪心 argmax本项目的测试循环用固定长度未依赖 eos 停止。2. Q4_0 量化扁平块量化每个权重矩阵按行展开每32 个权重组成一个块每块存[0,2) fp16 scale d max_abs / 8 [2,18) 16 字节每个权重用 4-bit 半字节存 q round(w/d)截断到 [-8,7]反量化w (nibble - 8) * d所以存储密度 18 字节 / 32 权重 4.5 bit/权重。关键实现tools/convert_minueza.pydef q4_quantize(w): flat np.asarray(w, dtypenp.float32).reshape(-1) nb (flat.size 31) // 32 flat pad_to(flat, nb * 32) # 补齐到 32 倍数 blocks flat.reshape(nb, 32) amax np.abs(blocks).max(axis1) d np.where(amax 0, amax / 8.0, 1.0) # 块 scale q np.clip(np.rint(blocks / d[:, None]), -8, 7) nib (q 8).astype(np.uint8) # [0,15] out[:, 0:2] d.astype(np.float16) # scale out[:, 2:18] pack(nib) # 低半字节偶数下标 return out.tobytes()3. 行对齐到 32M3-2 的关键改动n_cols312 / 1092 / 32002都不是 32 的倍数导致每行的块「相位漂移」、块可能跨行、内层循环出现变长cnt和分支。做法量化前把每行补齐到 32 的整数倍行尾零填充使每个 32 元素块只属于一行块号 r * nblk bnblk ceil(n_cols/32)可规整寻址GEMV 内层变成定长 32 的可完全展开循环。w2 w.reshape(rows, cols) if cols % 32 ! 0: w2 np.pad(w2, ((0, 0), (0, 32 - (cols % 32))))这是有损变更块边界变了 ⇒ 每块 scale 变了 ⇒ 反量化权重与未对齐版本不再逐位相同。通常量化保真度略优每块只覆盖同一行但「等价性」不再成立PC 参考序列本身也会变。4. KMCU v1 二进制格式KMCU v1 文件布局Header 128B 48B/项目录 64B 对齐数据区。[0,128) Header128B [dir_offset, dir_offset n_tensors*48) 目录每项 48B [data_offset, ...) 数据区每张量 64B 对齐Header小端偏移字段类型0magic KMCUchar[4]4version 1u328n_layersu3212dimu3216n_headsu3220n_kv_headsu3224head_dimu3228ffn_dimu3232vocab_sizeu3236max_sequ3240bos_idu3244eos_idu3248tied_embed1lm_head 复用 embedu3252n_tensorsu3256dir_offsetu3260data_offsetu3264rope_thetaf3268norm_epsf3272total_paramsu32目录项48B/项偏移字段类型0name[24]char[24]24dtype1f32, 2q4u828n_rowsu3232n_cols记录原始列数MCU 按 align32 推导 nblku3236offset绝对文件偏移u3240nbytesu32张量命名约定tok_embed L{i}.in_ln L{i}.q L{i}.k L{i}.v L{i}.o L{i}.post_ln L{i}.gate L{i}.up L{i}.down final_norm5. 转换与参考脚本convert_minueza.pyHF → KMCU该脚本读取 HuggingFace 权重按上述 Q4_0 扁平块量化与行对齐规则生成 KMCU v1 二进制文件。核心流程解析config.json生成 Header按张量命名约定遍历权重逐张量做 Q4_0 量化每行补齐到 32 的整数倍后分块打包写入目录项与 64B 对齐的数据区。配套的main/kmcu.h定义了 KMCU 文件解析与张量寻址接口tools/ref_forward.py提供 PC 端参考前向实现用于与 MCU 端推理结果对拍。