企业官网建设流程全解析

00 · 在 ESP32-P4 上跑通 LLM：从 0.61 到 4.31 tok/s 的 7 倍优化全复盘（系列总览）

本篇对应源码：仓库根目录 ——README.md·main/kmcu.c·tools/convert_minueza.py·docs/milestones.md

在ESP32-P4（RISC-V）上跑通一个 0.032B（22.8M 参数）Mistral 家族小模型，
并用私有 PIE 向量指令把 decode 加速 7× 的完整复盘。

一、这套文章解决什么问题

这是一份可复现的系列手记，覆盖从「零环境」到「0.032B 模型在 MCU 上 20/20 正确解码」的完整路径，
尤其把过程中踩过的每一个坑和每一个 bug都记录了下来。

适合读者：

• 想在 ESP32-P4 上跑 LLM 推理的嵌入式工程师；
• 想了解「MCU 上量化 + 手写 SIMD」全流程的算法/性能工程师；
• 想复现本项目、或移植到其他 RISC-V MCU 的人。

二、最终成果（先看结果）

正确性：20/20 token 与 PC 的 fp32 NumPy 参考完全一致，int16 激活量化对 argmax 零影响。

硬件：Waveshare ESP32-P4-WIFI6-DEV-KIT（SKU 32054）—— RISC-V 双核 400 MHz、32 MB PSRAM、16 MB NOR Flash。

对拍金标准速览（复现时用来核对）

single-token[1] argmax = 684 （PC 参考 logit=5.350636） 4-token prompt 末位 top1 = 23624 （PC 参考 logit=4.978983） 20-token 贪心序列： 1,450,2217,4996,23624,1199,8752,23624,1199,1199,8752,23624,1199,10436,23624,1199,3065,3161,4865,442

PIE 单算子 bench（板端）：

dotprod N=4096 match=1 speedup=20.97x（纯计算） gemv_row diff=0.000000e+00（分块 GEMV 逐位一致）

实跑复现（2026-09-28，ESP32-P4 rev v3.1）：dotprod match=1与
gemv_row diff=0.000000e+00可逐位复现；speedup随运行浮动，重跑得20.83x。
同理 M3-4 的 decode 速率在0.226–0.232 s/token（4.33–4.42 tok/s）间浮动，
表中 0.232 s/token 是其中一次读数。

完整 top-8 logits 见 02 篇「完整基准输出」。

三、模型

Felladrin/Minueza-32M-Base（Mistral 家族）：

layers=10, dim=312, heads=12, kv_heads=4, head_dim=26, ffn=1092, vocab=32002 参数量 22.81M（`--force-tie` 强制权重共享），Q4_0 量化后 12.58 MB

四、快速开始（最小命令集）

如果你只想最快跑起来，按顺序执行：

# 1) 环境（详见 01-环境搭建与构建.md）subst X:"%USERPROFILE%\.espressif"$env:IDF_TOOLS_PATH ="X:\"$env:IDF_SKIP_CHECK_SUBMODULES ="1".E:\esp-idf\export.ps1$env:PATH ="X:\python_env\idf6.0_py3.12_env\Scripts;"+$env:PATH# 2) 转换模型（详见 02-模型量化与KMCU格式.md）# 在仓库根目录执行；模型与产物统一放 models\ 子目录cd kestrel_mcu python tools\convert_minueza.py--src models\model_dir--out models\model.kmcu--force-tie python tools\ref_forward.py--km models\model.kmcu--ref_out models\ref_out.txt# 3) 构建 + 烧录（构建副本必须在纯 ASCII 路径 C:\kmcu，例如 C:\kmcu）cd C:\kmcu idf.py build idf.py-p COM5 flash# 4) 烧录模型分区（一次性）python-m esptool--chip esp32p4-p COM5-b 921600--before default-reset--after hard-resetwrite-flash0x210000 models\model.kmcu# 5) 监视输出idf.py-p COM5 monitor

五、文章导航

六、关键结论（提炼）

1. PIE 是纯定点 SIMD，没有 fp32 向量指令（乐鑫源码铁证）。要加速int8 权重 × fp32 激活的 GEMV，
   唯一路径是激活定点化（w8a16）。
2. 实测胜于推论：纯计算加速 21×，但接入后被 PSRAM 带宽墙（~84–106 MB/s）压到2.11×。
3. -Og是隐形杀手：ESP-IDF 默认 debug 优化级会系统性压低性能读数，M1/M2/M3-1 的数据都被它污染过。
4. 两个 PIE 硬约束：标量操作数不能用 t0-t2 寄存器、向量加载需 16 字节对齐——不满足会得到「随机数据对拍正确、真实数据全错」的诡异现象。

七、项目文件索引

kestrel-llm-mcu/ # https://gitee.com/pei-xiaoguang/kestrel-llm-mcu ├── main/ 固件 │ ├── main.c # 入口：SHS 自检 + PSRAM/TF 探针 + 模型加载 + decode + PIE bench + 三模式 │ ├── kmcu.c / kmcu.h # KMCU 权重读取 + 标量/PIE Transformer decode + 决策头 + agent 循环 │ ├── pie_dotprod.S # PIE（xespv）定点 GEMV 汇编 │ └── CMakeLists.txt ├── tools/ 宿主侧工具链（详见 tools/README.md） │ ├── mistral_ple.py # 架构唯一权威源（MistralPLE） │ ├── convert_minueza.py# HF safetensors → KMCU 量化权重 │ ├── ref_forward.py # PC 端 fp32 NumPy 参考（唯一对拍基准） │ ├── train_moe_ple.py # 训练 │ ├── watch_boot.py # 复位 + boot 日志监视 │ ├── upload_uart.py # UART 上传（experimental） │ └── legacy/ # 归档的历史研究脚本（含本文系列早期用到的 train_moe*.py 等） ├── docs/ 设计文档 + 开发日志（中英双版） ├── host_verify.c # PC 侧对拍程序（编译同一份 kmcu.c） ├── partitions.csv # Flash 布局（app 2 MB / model 13.87 MB） ├── sdkconfig.defaults # 关键配置（-O2、Newlib、PSRAM hex、关 WDT） └── LICENSE / NOTICE # Apache-2.0 + 第三方声明

注：GitHupSRC/（vLLM-Kestrel 引擎）与kestrel_mcu/是两个独立项目，
本系列只讲kestrel_mcu/这一条独立 determinism line，不涉及引擎源码。

对应源码（全系列总表）

每篇文末都有一节「对应源码」，给出该篇的符号级映射（文件 + 函数/宏 + 它支撑文中的哪部分结论）。
下表是系列导航级的速查：想直接读代码，从这里进。

注：09 与 15 篇引用的axiom_registry.json为内部文件，未随本仓库发布。

对应源码

仓库：https://gitee.com/pei-xiaoguang/kestrel-llm-mcu