最近在 Hacker News 上看到一个很有代表性的项目有人把 180.9M 参数的 LLM 和一个简易 Agent 推理流程完整跑在了 ESP32-P4 上并且完全离线运行。这个案例最打动我的地方不在于参数大小而是它把“云端大模型”拉回到了“设备端小模型”的轨道上。对做嵌入式、做硬件产品、做边缘 AI 的同学来说这类方案很有参考价值。这篇文章我会围绕“在 ESP32-P4 上离线运行 180.9M 参数 LLM 和 Agent 推理”这个方向拆解背后的资源估算、量化原理、推理流程、Agent 设计思路以及落地的具体步骤。文章内容以思路和工程方法为主不会死绑定某一个具体 SDK代码示例也会标注清楚哪些需要根据你的实际环境调整。1. 背景与核心概念1.1 为什么要在设备端跑 LLM传统使用大模型的方式基本都是把请求发送到云端由云端推理完成后返回结果。这种方式有几个绕不开的问题必须联网离线环境无法工作。数据会离开设备隐私敏感场景存在风险。网络延迟会影响交互体验。长期使用会产生 API 调用成本。如果把 LLM 推理放到设备端就可以做到不联网、低延迟、数据不出设备。对智能家居、便携设备、工业控制器这类场景来说离线 LLM 推理的价值非常高。当然设备端的算力和内存有限不能直接跑 70B 的大模型。但是 100M 到 500M 参数级别的小模型经过量化后完全有机会在 MCU 级别的硬件上运行。本文讨论的 180.9M 参数模型就属于这个范围。1.2 LLM、Agent、Inference 分别是什么这里先把几个关键词对齐避免后面理解出现偏差。LLMLarge Language Model是“大语言模型”它的核心能力是根据输入文本预测下一个 token。模型越大通常理解能力越强但需要的资源也越多。Inference是“推理”指的是用训练好的模型处理新的输入生成输出。我们要优化的重点就是推理过程中的内存占用、速度和功耗。Agent是“智能体”它在 LLM 的基础上增加了“调用工具、执行多步任务”的能力。比如用户说“请把灯打开”Agent 识别出意图调用led_on()这个工具完成动作后回复用户。Offline表示整个过程都在本地完成不需要访问云服务器。这也是这个项目最大的亮点。1.3 为什么是 ESP32-P4ESP32-P4 是乐鑫面向边缘计算推出的新一代芯片。相比我们熟悉的经典 ESP32它在 CPU 性能、内存支持、AI 相关指令等方面都有明显提升。虽然它依然不能和手机或 PC 相比但已经具备运行量化小模型的硬件条件。一个 180.9M 参数的模型通过 int4 量化后权重约 90MBint8 量化后约 181MB。ESP32-P4 可以通过外部 PSRAM 扩展内存再结合较大的外部 Flash 存储模型文件就有机会把模型真正跑起来。2. 180.9M 参数模型的资源估算与量化2.1 参数规模带来的压力在嵌入式设备上运行 LLM首先要算清楚一件事模型权重到底占多大空间。以 180.9M 参数为例不同精度下的理论占用如下精度每参数占用模型权重大小约FP324 字节723.6 MBFP16 / BF162 字节361.8 MBINT81 字节180.9 MBINT40.5 字节90.45 MB可以看到如果不做量化FP32 的 700 多 MB 对 MCU 来说是完全不可行的。即使降到 FP16也需要 360MB 左右依然不现实。所以量化是端侧 LLM 落地的关键步骤。最近很多资料都在讨论 FP16、FP32、BF16 对模型精度的影响。如果你在 PC 上做模型微调FP16/BF16 是常用方案但到了 MCU 场景真正要关心的是 INT8、INT4 这类整数量化方案。2.2 量化精度怎么选INT8 还是 INT4INT8 量化的损失相对较小质量通常更接近原始模型但占用空间是 INT4 的两倍。INT4 能进一步压缩体积但精度损失更大需要在实际任务上做验证。选择标准可以这样看如果目标是“先跑通”优先选 INT8。如果内存实在紧张再尝试 INT4。无论选哪种都要用真实输入测试生成质量不能只看文件体积。下面是一个用代码转换模型格式的示例思路假设你使用类似 llama.cpp 的工具链# 示例将 Hugging Face 格式模型转换为 GGUF 格式 # 需要根据你本地的 llama.cpp 路径调整 python convert_hf_to_gguf.py \ --outfile model_int8.gguf \ --outtype q8_0 \ ./local_model_dir如果你要转 INT4可以把--outtype换成q4_0。转换完成后再把生成的.gguf文件放进设备 Flash。这里要注意不同推理库支持的量化格式可能不一样。有的支持 GPTQ有的支持 AWQ有的只支持自己的格式。使用前建议先确认你的目标推理框架支持哪种量化格式。2.3 运行时的内存估算除了模型权重本身推理过程中还要占用额外的内存主要包括激活值每个 token 前向传播时的中间结果。KV Cache用于缓存注意力机制的 Key 和 Value减少重复计算。临时缓冲区tokenizer 处理、采样、日志输出等。KV Cache 的大小和输入长度、层数、注意力头数有关。在 MCU 上通常通过限制上下文长度来控制内存占用。比如把max_context设置在 256 或 512就能显著降低 KV Cache 的开销。实际项目里建议先画出内存分布图模型权重占多少、KV Cache 占多少、激活值占多少、系统任务占多少。等内存有余量了再去调整上下文长度和生成长度。3. 环境准备与硬件选型3.1 硬件环境要在 ESP32-P4 上跑 180.9M 参数的 LLM硬件选型很重要。通常需要满足以下条件开发板是 ESP32-P4 系列。外部 PSRAM 容量尽量大方案上建议选择容量满足模型权重加运行时内存需求的版本。外部 Flash 容量尽量大至少能放下模型文件。准备 USB 数据线、串口调试工具、稳定的 5V 供电。不同厂商的 ESP32-P4 开发板在外设、Flash、PSRAM 配置上差异较大购买前需要确认具体型号和存储配置。如果板子 Flash 太小可以先用大容量板子验证再根据实际产品精简。3.2 软件环境开发环境建议使用乐鑫官方的 ESP-IDF。安装方式官方文档写得比较清楚这里给出 Linux/macOS 下常见的安装思路mkdir -p ~/esp cd ~/esp git clone --recursive https://github.com/espressif/esp-idf.git cd esp-idf ./install.sh source export.sh如果你的网络环境无法直接 clone 官方仓库可以使用镜像地址具体以乐鑫官方文档为准。版本方面ESP-IDF 更新比较快不同版本的命令和 API 可能有差异。本文不固定具体版本建议使用官方最新的稳定版本。重点是演示思路实际编译时以你本地的 SDK 版本为准。3.3 工程目录结构一个典型的 ESP32-P4 LLM 工程结构可以这样组织esp32_p4_llm/ ├── CMakeLists.txt ├── main/ │ ├── CMakeLists.txt │ ├── main.c │ ├── agent.c │ └── agent.h ├── partitions.csv └── model/ └── model_int8.ggufmodel目录用于存放量化后的模型文件最终会通过自定义分区或文件系统写入设备。agent.c存放工具函数和 Agent 循环逻辑main.c负责初始化和主流程。4. 端侧 LLM 推理的核心原理4.1 从文本到 TokenLLM 不能直接处理任意长度的字符串它首先会把文本切成 Token。Token 可以理解成模型自己认识的最小文本片段。比如一句话可能被切成几个 Token也可能一个词就是一个 Token。Tokenizer 的作用就是把用户输入变成 Token ID 序列。在端侧推理中Tokenizer 一般在本地运行不需要联网。4.2 Prefill 与 Decode 两个阶段大模型推理通常分为两个阶段Prefill 阶段把用户输入的整段 Token 并行处理计算第一个输出 Token。这个阶段计算量大但一次处理完。Decode 阶段逐个生成后续 Token。每次生成一个 Token然后把新 Token 加入输入继续下一次前向计算。在 MCU 上Decode 阶段是主要瓶颈。因为每生成一个 Token都要重新跑一遍 Transformer 的前向计算而 MCU 的算力远不如 PC。所以实际项目中生成速度通常比较慢需要针对性地做优化。一个常见优化方式是利用 KV Cache。简单理解就是缓存已经计算过的 Key 和 Value这样后续生成新 Token 时不需要重新计算前面所有 Token 的注意力信息。4.3 Flash 与内存的协同模型权重可以放在外部 Flash 中也可以加载到 PSRAM 中运行。这两种方式的差别很大如果直接从 Flash 读取权重省内存但读取速度慢。如果先把权重加载到 PSRAM推理速度更快但占用大量内存。具体用哪种方式取决于你的硬件容量和推理库支持。有些推理库支持按层加载需要哪层就加载哪层这样可以在内存和速度之间做平衡。这类方案比较适合模型较大的场景。5. 端侧 Agent 推理是怎么实现的5.1 Agent 的基本组成在 MCU 上实现的 Agent和云端 Agent 有一些区别。云端 Agent 可以调用大量 API、跑 Python 代码、访问数据库MCU 上的 Agent 则更轻量通常只包含系统提示词设定 Agent 的角色和行为。用户输入。工具列表。一个解析工具调用的逻辑。虽然 MCU 上无法运行 Spring AI、LangChain 这类重量级框架但 Agent 的核心思想是通用的模型根据意图输出一个“调用哪个工具、传什么参数”的结构化文本然后由代码解析并执行。5.2 让模型输出工具调用端侧 Agent 最常用的做法是在 system prompt 中定义好工具的描述让模型输出一段固定格式的文本。例如[TOOL_CALL] led_on()然后代码检测文本中是否包含[TOOL_CALL]如果包含就解析出工具名和参数并执行。这种方式的优点是简单、不需要微调模型只要 prompt 组织合理小模型也能做到基本意图识别。你也可以让模型输出 JSON{tool: read_temperature, params: {}}但要提醒一点小模型输出 JSON 时容易出现格式错误解析器要做得宽容一些最好支持“部分匹配”和“重试”逻辑。5.3 一个简化版 Agent 对话循环下面是一个端侧 Agent 主循环的示意代码语言采用 C 语言风格。它不是一个可直接编译的完整工程而是方便你理解整个链路// 示意代码端侧 Agent 主循环 // 需要根据你的硬件抽象层和推理库 API 调整 const char *system_prompt 你是设备端助理。当你需要控制设备或读取传感器时 请输出 [TOOL_CALL] 工具名(参数)例如 [TOOL_CALL] led_on()。; char user_input[128]; for (;;) { get_user_input(user_input); // 第一轮推理生成回答 char *reply llm_generate(system_prompt, user_input, NULL); // 判断是否包含工具调用标记 if (is_tool_call(reply)) { char tool_name[32]; parse_tool_name(reply, tool_name); if (!is_allowed_tool(tool_name)) { output(工具不在白名单中); continue; } char result[256]; run_tool(tool_name, result); // 第二轮推理带上工具结果生成最终回答 reply llm_generate(system_prompt, user_input, result); } output(reply); }这段逻辑非常朴素但已经具备了 Agent 的基本框架识别意图、调用工具、结合结果生成回答。在实际产品中你还需要处理超时、多轮上下文、工具调用失败等异常情况。6. 完整实战在 ESP32-P4 上跑通离线 LLM Agent6.1 准备模型文件选择一个适合嵌入式部署的小模型然后在 PC 上完成格式转换和量化。这里再次以 llama.cpp 工具链为例python convert_hf_to_gguf.py \ --outfile model_int8.gguf \ --outtype q8_0 \ ./local_model_dir转换完成后把模型文件放到工程目录下的model/文件夹中。如果你的目标推理库不识别 GGUF请按它的文档选择对应格式。6.2 配置 Flash 分区在 ESP-IDF 中如果模型文件比较大建议在分区表中单独划分一个model分区。下面是一个分区表示例# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x6000, phy_init, data, phy, 0xf000, 0x1000, factory, app, factory, 0x10000, 2M, storage, data, spiffs, 0x210000, 8M, model, data, spiffs, , 24M,这里把model分区大小为 24MB具体大小要根据你的 Flash 容量和模型文件调整。如果模型真的超过 90MB就需要更大容量的 Flash或者改用外部存储方案。6.3 编译与烧录在工程根目录执行idf.py set-target esp32p4 idf.py build idf.py flash monitor如果set-target的参数和你安装的 SDK 不一致以官方文档为准。烧录成功后可以在 monitor 中看到日志输出。6.4 核心推理流程示例下面是一个更完整的推理流程示例。这段代码不是某一个库的直接调用示例而是一个通用的“初始化模型 → 处理用户输入 → 生成回复”的骨架// 示意代码模型初始化与推理流程 // API 名称需要根据你使用的嵌入式推理库调整 ModelHandle model; void app_main() { // 1. 初始化系统 esp_logger_init(); flash_init(); // 2. 加载模型 model model_load(/model/model_int8.gguf); if (model NULL) { ESP_LOGE(MAIN, 模型加载失败请检查分区和文件路径); return; } ESP_LOGI(MAIN, 模型加载成功); // 3. 配置 tokenizer Tokenizer *tok tokenizer_init(model); // 4. 创建推理参数 InferenceParams params; params.max_tokens 128; params.temperature 0.7f; // 5. 示例输入 const char *input 请打开LED灯; int *input_ids tokenizer_encode(tok, input); // 6. 执行推理 const char *output model_generate(model, input_ids, params); // 7. 输出结果 ESP_LOGI(MAIN, 模型输出: %s, output); // 8. 释放资源 model_free(model); }这个骨架演示了加载模型、编码输入、生成输出三个核心步骤。具体实现时ModelHandle、model_load、model_generate这些 API 都要替换成你实际使用的推理库接口。6.5 验证输出烧录后串口日志中应该能看到模型文件加载成功的提示。模型占用的内存大小。每次推理的耗时。最终生成的文本输出。如果输出内容明显与预期不符需要检查 tokenizer 是否匹配、量化格式是否正确、上下文长度是否设置合理。7. 常见问题与排查思路在 ESP32-P4 上跑 LLM 和 Agent常见问题主要集中在内存、模型格式、工具调用三个方面。下面整理成表格方便快速排查。问题现象常见原因解决思路上电后一直复位Flash 分区配置错误或模型分区越界检查分区表 offset 和 size确认模型文件烧录位置正确内存分配失败PSRAM 容量不足或没有启用外部 PSRAM确认板卡支持 PSRAM并在 menuconfig 中启用模型加载失败模型格式与推理库不兼容重新转换模型格式确认量化类型符合框架要求推理速度太慢模型过大或没有使用 KV Cache减小上下文长度尝试 INT4 量化优化内存访问输出乱码Tokenizer 与模型不匹配使用与模型配套的 tokenizer 文件工具调用失败输出格式不稳定增加解析容错允许重试或固定工具调用格式Flash 空间不足模型文件太大选用更小模型或使用更激进的量化方案排查过程中建议先开日志逐段确认每一层是否执行成功。比如先确认模型可以正常加载再确认推理可以产生输出最后才去调 Agent 的工具调用逻辑。不要一上来就调试 Agent容易把模型问题和逻辑问题混在一起。8. 最佳实践与工程建议8.1 量化不是万能的量化能大幅减少内存但也会损失模型能力。建议在量化后做一轮真实任务测试而不是只看困惑度。如果生成质量下降严重可以考虑使用混合精度方案比如权重用 INT8、关键层保持 FP16。8.2 内存规划要前置在写代码之前先计算好模型权重、KV Cache、激活值和系统任务各占多少内存。可以在工程中加一个内存自检函数启动时打印剩余堆内存和 PSRAM 使用量方便快速定位内存问题。8.3 Agent 工具要有白名单MCU 上的 Agent 可以控制硬件外设这本身是好事但也意味着一旦模型输出异常可能导致设备误操作。建议所有工具调用都走白名单校验只有明确的工具名和参数范围才允许执行。比如led_on()只能控制指定 GPIO不能接受任意端口号。8.4 日志与可观测性端侧模型推理是一个相对复杂的过程日志设计直接决定排查效率。建议至少打印以下信息每次推理耗时。内存剩余量。输入文本和输出文本。Agent 是否触发了工具调用调用结果是什么。8.5 模型更新与 OTA模型文件过大时OTA 更新会很慢。建议把模型文件放在独立分区并支持通过串口或 SD 卡更新。OTA 更新期间注意断电保护避免模型分区写坏导致设备变砖。8.6 功耗需要单独优化跑 LLM 推理时CPU 和内存访问都很频繁功耗会比普通嵌入式应用高很多。产品化时需要考虑模型加载完成后是否进入低功耗模式。推理完成后是否关闭外设。DC-DC 供电能力是否足够。9. 总结与下一步如果你想尝试在 ESP32-P4 上跑离线 LLM 和 Agent我的建议是先不要把目标定得太高。先选一个 100M 参数左右的量化模型把“模型加载 → 推理 → 输出”这条链路完整跑通再逐步加入 Agent 工具调用、多轮对话、意图识别这些能力。这个项目给我们的启发是小模型 低精度量化 合理的内存规划确实可以让 LLM 脱离云端跑进 MCU。接下来值得继续学习的方向包括更高效的端侧推理框架原理比如算子融合、内存复用。KV Cache 的量化与压缩。针对具体任务的模型微调让 180.9M 参数的小模型在业务场景中表现更好。端侧 Agent 的安全设计包括工具白名单、输入过滤和异常恢复。如果这篇文章对你有帮助可以收藏备用。后面我也会继续更新端侧 LLM 推理的实战细节包括具体框架的移植和性能优化方法。 ESP32-P4上离线运行180.9M参数LLM与Agent推理实践
最近在 Hacker News 上看到一个很有代表性的项目有人把 180.9M 参数的 LLM 和一个简易 Agent 推理流程完整跑在了 ESP32-P4 上并且完全离线运行。这个案例最打动我的地方不在于参数大小而是它把“云端大模型”拉回到了“设备端小模型”的轨道上。对做嵌入式、做硬件产品、做边缘 AI 的同学来说这类方案很有参考价值。这篇文章我会围绕“在 ESP32-P4 上离线运行 180.9M 参数 LLM 和 Agent 推理”这个方向拆解背后的资源估算、量化原理、推理流程、Agent 设计思路以及落地的具体步骤。文章内容以思路和工程方法为主不会死绑定某一个具体 SDK代码示例也会标注清楚哪些需要根据你的实际环境调整。1. 背景与核心概念1.1 为什么要在设备端跑 LLM传统使用大模型的方式基本都是把请求发送到云端由云端推理完成后返回结果。这种方式有几个绕不开的问题必须联网离线环境无法工作。数据会离开设备隐私敏感场景存在风险。网络延迟会影响交互体验。长期使用会产生 API 调用成本。如果把 LLM 推理放到设备端就可以做到不联网、低延迟、数据不出设备。对智能家居、便携设备、工业控制器这类场景来说离线 LLM 推理的价值非常高。当然设备端的算力和内存有限不能直接跑 70B 的大模型。但是 100M 到 500M 参数级别的小模型经过量化后完全有机会在 MCU 级别的硬件上运行。本文讨论的 180.9M 参数模型就属于这个范围。1.2 LLM、Agent、Inference 分别是什么这里先把几个关键词对齐避免后面理解出现偏差。LLMLarge Language Model是“大语言模型”它的核心能力是根据输入文本预测下一个 token。模型越大通常理解能力越强但需要的资源也越多。Inference是“推理”指的是用训练好的模型处理新的输入生成输出。我们要优化的重点就是推理过程中的内存占用、速度和功耗。Agent是“智能体”它在 LLM 的基础上增加了“调用工具、执行多步任务”的能力。比如用户说“请把灯打开”Agent 识别出意图调用led_on()这个工具完成动作后回复用户。Offline表示整个过程都在本地完成不需要访问云服务器。这也是这个项目最大的亮点。1.3 为什么是 ESP32-P4ESP32-P4 是乐鑫面向边缘计算推出的新一代芯片。相比我们熟悉的经典 ESP32它在 CPU 性能、内存支持、AI 相关指令等方面都有明显提升。虽然它依然不能和手机或 PC 相比但已经具备运行量化小模型的硬件条件。一个 180.9M 参数的模型通过 int4 量化后权重约 90MBint8 量化后约 181MB。ESP32-P4 可以通过外部 PSRAM 扩展内存再结合较大的外部 Flash 存储模型文件就有机会把模型真正跑起来。2. 180.9M 参数模型的资源估算与量化2.1 参数规模带来的压力在嵌入式设备上运行 LLM首先要算清楚一件事模型权重到底占多大空间。以 180.9M 参数为例不同精度下的理论占用如下精度每参数占用模型权重大小约FP324 字节723.6 MBFP16 / BF162 字节361.8 MBINT81 字节180.9 MBINT40.5 字节90.45 MB可以看到如果不做量化FP32 的 700 多 MB 对 MCU 来说是完全不可行的。即使降到 FP16也需要 360MB 左右依然不现实。所以量化是端侧 LLM 落地的关键步骤。最近很多资料都在讨论 FP16、FP32、BF16 对模型精度的影响。如果你在 PC 上做模型微调FP16/BF16 是常用方案但到了 MCU 场景真正要关心的是 INT8、INT4 这类整数量化方案。2.2 量化精度怎么选INT8 还是 INT4INT8 量化的损失相对较小质量通常更接近原始模型但占用空间是 INT4 的两倍。INT4 能进一步压缩体积但精度损失更大需要在实际任务上做验证。选择标准可以这样看如果目标是“先跑通”优先选 INT8。如果内存实在紧张再尝试 INT4。无论选哪种都要用真实输入测试生成质量不能只看文件体积。下面是一个用代码转换模型格式的示例思路假设你使用类似 llama.cpp 的工具链# 示例将 Hugging Face 格式模型转换为 GGUF 格式 # 需要根据你本地的 llama.cpp 路径调整 python convert_hf_to_gguf.py \ --outfile model_int8.gguf \ --outtype q8_0 \ ./local_model_dir如果你要转 INT4可以把--outtype换成q4_0。转换完成后再把生成的.gguf文件放进设备 Flash。这里要注意不同推理库支持的量化格式可能不一样。有的支持 GPTQ有的支持 AWQ有的只支持自己的格式。使用前建议先确认你的目标推理框架支持哪种量化格式。2.3 运行时的内存估算除了模型权重本身推理过程中还要占用额外的内存主要包括激活值每个 token 前向传播时的中间结果。KV Cache用于缓存注意力机制的 Key 和 Value减少重复计算。临时缓冲区tokenizer 处理、采样、日志输出等。KV Cache 的大小和输入长度、层数、注意力头数有关。在 MCU 上通常通过限制上下文长度来控制内存占用。比如把max_context设置在 256 或 512就能显著降低 KV Cache 的开销。实际项目里建议先画出内存分布图模型权重占多少、KV Cache 占多少、激活值占多少、系统任务占多少。等内存有余量了再去调整上下文长度和生成长度。3. 环境准备与硬件选型3.1 硬件环境要在 ESP32-P4 上跑 180.9M 参数的 LLM硬件选型很重要。通常需要满足以下条件开发板是 ESP32-P4 系列。外部 PSRAM 容量尽量大方案上建议选择容量满足模型权重加运行时内存需求的版本。外部 Flash 容量尽量大至少能放下模型文件。准备 USB 数据线、串口调试工具、稳定的 5V 供电。不同厂商的 ESP32-P4 开发板在外设、Flash、PSRAM 配置上差异较大购买前需要确认具体型号和存储配置。如果板子 Flash 太小可以先用大容量板子验证再根据实际产品精简。3.2 软件环境开发环境建议使用乐鑫官方的 ESP-IDF。安装方式官方文档写得比较清楚这里给出 Linux/macOS 下常见的安装思路mkdir -p ~/esp cd ~/esp git clone --recursive https://github.com/espressif/esp-idf.git cd esp-idf ./install.sh source export.sh如果你的网络环境无法直接 clone 官方仓库可以使用镜像地址具体以乐鑫官方文档为准。版本方面ESP-IDF 更新比较快不同版本的命令和 API 可能有差异。本文不固定具体版本建议使用官方最新的稳定版本。重点是演示思路实际编译时以你本地的 SDK 版本为准。3.3 工程目录结构一个典型的 ESP32-P4 LLM 工程结构可以这样组织esp32_p4_llm/ ├── CMakeLists.txt ├── main/ │ ├── CMakeLists.txt │ ├── main.c │ ├── agent.c │ └── agent.h ├── partitions.csv └── model/ └── model_int8.ggufmodel目录用于存放量化后的模型文件最终会通过自定义分区或文件系统写入设备。agent.c存放工具函数和 Agent 循环逻辑main.c负责初始化和主流程。4. 端侧 LLM 推理的核心原理4.1 从文本到 TokenLLM 不能直接处理任意长度的字符串它首先会把文本切成 Token。Token 可以理解成模型自己认识的最小文本片段。比如一句话可能被切成几个 Token也可能一个词就是一个 Token。Tokenizer 的作用就是把用户输入变成 Token ID 序列。在端侧推理中Tokenizer 一般在本地运行不需要联网。4.2 Prefill 与 Decode 两个阶段大模型推理通常分为两个阶段Prefill 阶段把用户输入的整段 Token 并行处理计算第一个输出 Token。这个阶段计算量大但一次处理完。Decode 阶段逐个生成后续 Token。每次生成一个 Token然后把新 Token 加入输入继续下一次前向计算。在 MCU 上Decode 阶段是主要瓶颈。因为每生成一个 Token都要重新跑一遍 Transformer 的前向计算而 MCU 的算力远不如 PC。所以实际项目中生成速度通常比较慢需要针对性地做优化。一个常见优化方式是利用 KV Cache。简单理解就是缓存已经计算过的 Key 和 Value这样后续生成新 Token 时不需要重新计算前面所有 Token 的注意力信息。4.3 Flash 与内存的协同模型权重可以放在外部 Flash 中也可以加载到 PSRAM 中运行。这两种方式的差别很大如果直接从 Flash 读取权重省内存但读取速度慢。如果先把权重加载到 PSRAM推理速度更快但占用大量内存。具体用哪种方式取决于你的硬件容量和推理库支持。有些推理库支持按层加载需要哪层就加载哪层这样可以在内存和速度之间做平衡。这类方案比较适合模型较大的场景。5. 端侧 Agent 推理是怎么实现的5.1 Agent 的基本组成在 MCU 上实现的 Agent和云端 Agent 有一些区别。云端 Agent 可以调用大量 API、跑 Python 代码、访问数据库MCU 上的 Agent 则更轻量通常只包含系统提示词设定 Agent 的角色和行为。用户输入。工具列表。一个解析工具调用的逻辑。虽然 MCU 上无法运行 Spring AI、LangChain 这类重量级框架但 Agent 的核心思想是通用的模型根据意图输出一个“调用哪个工具、传什么参数”的结构化文本然后由代码解析并执行。5.2 让模型输出工具调用端侧 Agent 最常用的做法是在 system prompt 中定义好工具的描述让模型输出一段固定格式的文本。例如[TOOL_CALL] led_on()然后代码检测文本中是否包含[TOOL_CALL]如果包含就解析出工具名和参数并执行。这种方式的优点是简单、不需要微调模型只要 prompt 组织合理小模型也能做到基本意图识别。你也可以让模型输出 JSON{tool: read_temperature, params: {}}但要提醒一点小模型输出 JSON 时容易出现格式错误解析器要做得宽容一些最好支持“部分匹配”和“重试”逻辑。5.3 一个简化版 Agent 对话循环下面是一个端侧 Agent 主循环的示意代码语言采用 C 语言风格。它不是一个可直接编译的完整工程而是方便你理解整个链路// 示意代码端侧 Agent 主循环 // 需要根据你的硬件抽象层和推理库 API 调整 const char *system_prompt 你是设备端助理。当你需要控制设备或读取传感器时 请输出 [TOOL_CALL] 工具名(参数)例如 [TOOL_CALL] led_on()。; char user_input[128]; for (;;) { get_user_input(user_input); // 第一轮推理生成回答 char *reply llm_generate(system_prompt, user_input, NULL); // 判断是否包含工具调用标记 if (is_tool_call(reply)) { char tool_name[32]; parse_tool_name(reply, tool_name); if (!is_allowed_tool(tool_name)) { output(工具不在白名单中); continue; } char result[256]; run_tool(tool_name, result); // 第二轮推理带上工具结果生成最终回答 reply llm_generate(system_prompt, user_input, result); } output(reply); }这段逻辑非常朴素但已经具备了 Agent 的基本框架识别意图、调用工具、结合结果生成回答。在实际产品中你还需要处理超时、多轮上下文、工具调用失败等异常情况。6. 完整实战在 ESP32-P4 上跑通离线 LLM Agent6.1 准备模型文件选择一个适合嵌入式部署的小模型然后在 PC 上完成格式转换和量化。这里再次以 llama.cpp 工具链为例python convert_hf_to_gguf.py \ --outfile model_int8.gguf \ --outtype q8_0 \ ./local_model_dir转换完成后把模型文件放到工程目录下的model/文件夹中。如果你的目标推理库不识别 GGUF请按它的文档选择对应格式。6.2 配置 Flash 分区在 ESP-IDF 中如果模型文件比较大建议在分区表中单独划分一个model分区。下面是一个分区表示例# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x6000, phy_init, data, phy, 0xf000, 0x1000, factory, app, factory, 0x10000, 2M, storage, data, spiffs, 0x210000, 8M, model, data, spiffs, , 24M,这里把model分区大小为 24MB具体大小要根据你的 Flash 容量和模型文件调整。如果模型真的超过 90MB就需要更大容量的 Flash或者改用外部存储方案。6.3 编译与烧录在工程根目录执行idf.py set-target esp32p4 idf.py build idf.py flash monitor如果set-target的参数和你安装的 SDK 不一致以官方文档为准。烧录成功后可以在 monitor 中看到日志输出。6.4 核心推理流程示例下面是一个更完整的推理流程示例。这段代码不是某一个库的直接调用示例而是一个通用的“初始化模型 → 处理用户输入 → 生成回复”的骨架// 示意代码模型初始化与推理流程 // API 名称需要根据你使用的嵌入式推理库调整 ModelHandle model; void app_main() { // 1. 初始化系统 esp_logger_init(); flash_init(); // 2. 加载模型 model model_load(/model/model_int8.gguf); if (model NULL) { ESP_LOGE(MAIN, 模型加载失败请检查分区和文件路径); return; } ESP_LOGI(MAIN, 模型加载成功); // 3. 配置 tokenizer Tokenizer *tok tokenizer_init(model); // 4. 创建推理参数 InferenceParams params; params.max_tokens 128; params.temperature 0.7f; // 5. 示例输入 const char *input 请打开LED灯; int *input_ids tokenizer_encode(tok, input); // 6. 执行推理 const char *output model_generate(model, input_ids, params); // 7. 输出结果 ESP_LOGI(MAIN, 模型输出: %s, output); // 8. 释放资源 model_free(model); }这个骨架演示了加载模型、编码输入、生成输出三个核心步骤。具体实现时ModelHandle、model_load、model_generate这些 API 都要替换成你实际使用的推理库接口。6.5 验证输出烧录后串口日志中应该能看到模型文件加载成功的提示。模型占用的内存大小。每次推理的耗时。最终生成的文本输出。如果输出内容明显与预期不符需要检查 tokenizer 是否匹配、量化格式是否正确、上下文长度是否设置合理。7. 常见问题与排查思路在 ESP32-P4 上跑 LLM 和 Agent常见问题主要集中在内存、模型格式、工具调用三个方面。下面整理成表格方便快速排查。问题现象常见原因解决思路上电后一直复位Flash 分区配置错误或模型分区越界检查分区表 offset 和 size确认模型文件烧录位置正确内存分配失败PSRAM 容量不足或没有启用外部 PSRAM确认板卡支持 PSRAM并在 menuconfig 中启用模型加载失败模型格式与推理库不兼容重新转换模型格式确认量化类型符合框架要求推理速度太慢模型过大或没有使用 KV Cache减小上下文长度尝试 INT4 量化优化内存访问输出乱码Tokenizer 与模型不匹配使用与模型配套的 tokenizer 文件工具调用失败输出格式不稳定增加解析容错允许重试或固定工具调用格式Flash 空间不足模型文件太大选用更小模型或使用更激进的量化方案排查过程中建议先开日志逐段确认每一层是否执行成功。比如先确认模型可以正常加载再确认推理可以产生输出最后才去调 Agent 的工具调用逻辑。不要一上来就调试 Agent容易把模型问题和逻辑问题混在一起。8. 最佳实践与工程建议8.1 量化不是万能的量化能大幅减少内存但也会损失模型能力。建议在量化后做一轮真实任务测试而不是只看困惑度。如果生成质量下降严重可以考虑使用混合精度方案比如权重用 INT8、关键层保持 FP16。8.2 内存规划要前置在写代码之前先计算好模型权重、KV Cache、激活值和系统任务各占多少内存。可以在工程中加一个内存自检函数启动时打印剩余堆内存和 PSRAM 使用量方便快速定位内存问题。8.3 Agent 工具要有白名单MCU 上的 Agent 可以控制硬件外设这本身是好事但也意味着一旦模型输出异常可能导致设备误操作。建议所有工具调用都走白名单校验只有明确的工具名和参数范围才允许执行。比如led_on()只能控制指定 GPIO不能接受任意端口号。8.4 日志与可观测性端侧模型推理是一个相对复杂的过程日志设计直接决定排查效率。建议至少打印以下信息每次推理耗时。内存剩余量。输入文本和输出文本。Agent 是否触发了工具调用调用结果是什么。8.5 模型更新与 OTA模型文件过大时OTA 更新会很慢。建议把模型文件放在独立分区并支持通过串口或 SD 卡更新。OTA 更新期间注意断电保护避免模型分区写坏导致设备变砖。8.6 功耗需要单独优化跑 LLM 推理时CPU 和内存访问都很频繁功耗会比普通嵌入式应用高很多。产品化时需要考虑模型加载完成后是否进入低功耗模式。推理完成后是否关闭外设。DC-DC 供电能力是否足够。9. 总结与下一步如果你想尝试在 ESP32-P4 上跑离线 LLM 和 Agent我的建议是先不要把目标定得太高。先选一个 100M 参数左右的量化模型把“模型加载 → 推理 → 输出”这条链路完整跑通再逐步加入 Agent 工具调用、多轮对话、意图识别这些能力。这个项目给我们的启发是小模型 低精度量化 合理的内存规划确实可以让 LLM 脱离云端跑进 MCU。接下来值得继续学习的方向包括更高效的端侧推理框架原理比如算子融合、内存复用。KV Cache 的量化与压缩。针对具体任务的模型微调让 180.9M 参数的小模型在业务场景中表现更好。端侧 Agent 的安全设计包括工具白名单、输入过滤和异常恢复。如果这篇文章对你有帮助可以收藏备用。后面我也会继续更新端侧 LLM 推理的实战细节包括具体框架的移植和性能优化方法。