简介本资源是一个面向嵌入式AI开发者的实践项目聚焦于在ESP32微控制器上部署轻量级本地大模型并实现对话交互、联网通信与工具调用能力解决边缘端AI推理与云边协同的实际落地难题。适用于具备C/Python基础、熟悉ESP-IDF开发环境的物联网与人工智能交叉领域学习者及工程师。压缩包共87个文件含15个核心Python脚本含模型加载、HTTP客户端、工具调度逻辑、11个C/H源码文件ESP32底层驱动与AI推理接口、7个JSON/YML配置模型参数、API路由、工具定义以及PDF文档、LICENSE、Makefile等工程支撑文件整体12.9MB结构清晰模块划分明确。已有86人学习下载。读者可直接复现本地语音/文本对话系统获得完整端到端代码框架、小模型量化适配方案、Wi-Fi联网调用Dify等外部服务的集成示例以及xiao-zhi情感识别、闹钟控制等典型场景实现参考。1. 项目概述当ESP32遇见本地大模型最近在捣鼓一个挺有意思的玩意儿用一块几十块钱的ESP32开发板去调用跑在自己电脑上的大语言模型比如Llama 3、Qwen2.5不仅能实现本地对话还能让这个“小脑瓜”联网查资料甚至调用一些简单的工具。听起来是不是有点“小马拉大车”的感觉没错这个项目的核心魅力就在于此——将资源受限的物联网终端设备与能力强大的本地AI模型连接起来探索在边缘侧实现更智能交互的可能性。你可能会问ESP32这种主打低功耗、Wi-Fi/蓝牙的微控制器内存通常就几百KB跑大模型不是天方夜谭吗确实让模型直接在ESP32上运行目前还不现实。但这个项目的思路很巧妙让ESP32扮演一个“智能终端”或“交互代理”的角色。它负责采集信息比如语音输入、传感器数据、接收用户指令然后通过Wi-Fi将请求发送到同一局域网内、运行着Ollama服务的PC或服务器上。Ollama负责运行本地大模型处理复杂的逻辑和语言生成再将结果返回给ESP32由ESP32执行最终的动作比如在屏幕上显示、控制继电器、或者根据模型的指令再去调用某个Web API工具调用。这解决了几个实际痛点一是隐私与成本所有对话和数据都在本地流转无需支付高昂的云API费用也避免了隐私泄露风险二是低延迟与高可用性局域网内通信速度极快且不依赖外网即使断网也能进行基础对话三是扩展了物联网设备的“智力”上限让一个简单的温湿度传感器节点也能通过自然语言与你交流并基于模型的理解做出更复杂的决策。无论是想做一个个人的语音助手、智能家居的中控大脑还是一个能联网查询信息的桌面摆件这个组合都提供了一个极具性价比和可玩性的起点。2. 核心架构与组件选型解析要实现“ESP32 Ollama 联网 工具调用”这套系统我们需要清晰地理解各个组件的职责以及它们之间如何协同工作。整个架构可以看作一个微型的客户端-服务器模型并在此基础上增加了代理和工具调用的能力。2.1 硬件核心ESP32开发板ESP32是本项目的物理交互终端和动作执行单元。它的选型直接决定了项目的交互形式和能力边界。主要职责用户交互接口通过按键、触摸屏、麦克风需额外模块接收用户输入。网络通信客户端建立Wi-Fi连接向Ollama服务器发送HTTP请求并接收响应。结果呈现与执行在OLED屏幕、LED灯带上显示对话内容或通过GPIO控制继电器、电机等执行器。工具调用执行端当模型返回一个工具调用请求如“查询天气”时ESP32需要解析该请求并执行对应的网络查询或本地操作。型号选择建议ESP32-S3这是当前的首选。它主频更高240MHzPSRAM可选配最高8MBUSB接口原生支持JTAG调试开发体验更好。如果计划使用语音唤醒或更复杂的UI推荐选择带PSRAM的型号。ESP32-C3性价比极高基于RISC-V架构功耗更低。但性能稍弱且外设接口如DAC可能不如S3系列丰富。适合对成本敏感、功能简单的项目。经典ESP32ESP32-D0WD资源充足生态最成熟。如果手头已有完全可以使用。注意务必确认开发板的Wi-Fi功能正常且能稳定连接到你部署Ollama的局域网。有些兼容板的天线设计或固件可能存在连接问题。2.2 软件核心Ollama本地模型服务Ollama是本项目的“大脑”它简化了在本地Windows, macOS, Linux运行大型语言模型的复杂度。核心价值一键部署与管理通过简单的命令行就能拉取、运行和管理各种开源模型无需复杂的环境配置。提供标准化APIOllama提供了一个类似OpenAI API的RESTful接口默认端口11434这使得ESP32可以使用通用的HTTP客户端库与之通信极大降低了集成难度。模型轻量化Ollama支持运行量化后的模型如GGUF格式在保持一定性能的同时大幅降低了对硬件主要是GPU显存的要求。例如7B参数的模型在4-8GB显存的消费级显卡上就能流畅运行。模型选型建议Llama 3系列如llama3:8b综合能力强指令跟随和逻辑推理不错英文优先中文尚可。Qwen 2.5系列如qwen2.5:7b中文能力非常出色代码和数学能力强对中文场景友好。Gemma 2系列如gemma2:9b由Google推出在常识推理和安全性方面表现较好。Phi-3系列如phi3:mini超轻量级模型参数小但能力不弱适合在CPU上运行或快速测试。实操心得初次尝试时建议从参数量较小的模型开始如phi3:mini或qwen2.5:0.5b下载快运行资源要求低能快速验证整个通信链路是否通畅。之后再根据实际需求升级到更大模型。2.3 通信桥梁HTTP API与数据格式ESP32与Ollama之间通过HTTP协议进行通信。理解这个通信过程是项目成功的关键。请求流程ESP32作为客户端构造一个HTTP POST请求发送到http://[你的电脑IP]:11434/api/generate。请求体JSON格式这是核心告诉Ollama要做什么。{ model: qwen2.5:7b, // 指定使用的模型 prompt: 用户的问题或指令在这里, // 输入的文本 stream: false, // 设为false让Ollama一次性返回完整结果简化ESP32处理 options: { temperature: 0.7 // 控制创造性值越高回答越随机 } }响应体JSON格式Ollama处理完成后会返回一个JSON对象。{ model: qwen2.5:7b, created_at: 2024-..., response: 模型生成的回答内容在这里。, // 这是我们需要的核心字段 done: true }ESP32需要解析这个JSON提取出response字段的内容。关键点ESP32的代码中需要使用WiFiClient或HTTPClient在Arduino框架中库来建立连接、发送请求和解析响应。JSON的解析可以使用ArduinoJson库它非常轻量且高效。2.4 能力扩展联网搜索与工具调用这是让项目从“本地知识库问答”升级为“智能代理”的关键一步。实现方式主要有两种“伪”联网通过Ollama的上下文在发送给Ollama的prompt中手动插入实时信息。例如ESP32可以先调用一个天气API获取数据然后将“当前北京气温25度晴”这段文本作为背景信息和用户的问题“北京天气怎么样”一起组合成新的prompt发送给Ollama。模型就能基于你给的实时数据来回答。这种方式简单直接但需要ESP32事先知道该调用哪些工具、如何调用。“真”代理与工具调用这是更高级的模式需要引入“代理Agent”的概念。我们可以让Ollama模型具备“思考-行动”的能力。具体流程是用户提问“今天上海和北京的天气对比如何”ESP32发送请求将问题原样发送给Ollama。Ollama返回工具调用请求模型“思考”后发现需要天气数据它不会直接生成答案而是返回一个结构化的工具调用请求。例如它可能返回一个包含function_call字段的响应需要模型支持Function Calling功能部分Ollama模型已支持或通过特定prompt工程实现。ESP32执行工具ESP32解析这个请求识别出需要调用“天气查询API”然后分别调用上海和北京的天气接口获取原始数据。ESP32再次请求将获取到的两地天气数据连同原始问题再次发送给Ollama。Ollama生成最终答案模型基于实时数据生成对比性的总结回答。ESP32呈现结果将最终答案显示或播报出来。方案选择对于初学者强烈建议从第一种“伪”联网开始先让ESP32学会调用一个固定的API如天气、时间并将其结果成功融入对话。这能帮你夯实HTTP请求、JSON解析、字符串拼接等基础。之后再挑战更复杂的代理模式。3. 详细实现步骤与代码解析接下来我们分步拆解如何从零搭建这个系统。我们将以Arduino IDE作为ESP32的开发环境并使用一个支持Function Calling的模型例如qwen2.5:7b的某个版本来演示基础的工具调用流程。3.1 第一步搭建Ollama服务器环境这是项目的“大脑”安装环节。下载与安装访问Ollama官网根据你的操作系统Windows/macOS/Linux下载安装包。安装过程通常是一键式的。拉取模型打开终端Windows是CMD或PowerShell执行拉取命令。由于网络原因下载可能很慢。ollama pull qwen2.5:7b解决下载慢的技巧使用镜像源这是最有效的方法。在拉取前设置环境变量Linux/macOS在~/.bashrc或~/.zshrc Windows在系统环境变量中新增。# 以Linux为例添加以下行 export OLLAMA_HOST0.0.0.0 # 允许非本地访问方便ESP32连接 export OLLAMA_MODELS/path/to/your/models # 可选指定模型存放路径 # 对于下载可以尝试在拉取命令前使用代理如果你有合法合规的国际网络加速服务但更推荐使用国内镜像。 # 注意Ollama本身没有官方国内镜像但一些社区提供了镜像站使用时请自行甄别安全性和合规性。手动导入GGUF模型从Hugging Face等平台下载模型的GGUF格式文件然后使用ollama create命令从本地文件创建模型。这能绕过Ollama服务器的拉取。运行与测试安装完成后Ollama服务会自动在后台运行。你可以在终端测试ollama run qwen2.5:7b这会进入一个交互式聊天界面输入“Hello”看是否有回复以验证模型运行正常。获取本机IP地址在命令行输入ipconfig(Windows) 或ifconfig(Linux/macOS)找到你电脑在局域网中的IPv4地址如192.168.1.100。ESP32需要连接这个地址。3.2 第二步配置Arduino IDE与ESP32开发环境安装Arduino IDE从官网下载并安装。添加ESP32开发板支持打开Arduino IDE进入文件 - 首选项在“附加开发板管理器网址”中输入https://espressif.github.io/arduino-esp32/package_esp32_index.json然后进入工具 - 开发板 - 开发板管理器搜索“esp32”找到由“Espressif Systems”提供的包点击安装。安装必要库本项目需要两个核心库WiFi/WiFiClientSecureESP32内置无需额外安装。ArduinoJson用于解析Ollama返回的JSON数据。通过项目 - 加载库 - 管理库...搜索安装。HTTPClientESP32内置用于发起HTTP请求。3.3 第三步编写ESP32端核心代码下面是一个精简但功能完整的示例实现了连接Wi-Fi、向Ollama发送提问、并解析回复的基本功能。我们假设Ollama服务器IP是192.168.1.100。#include WiFi.h #include HTTPClient.h #include ArduinoJson.h // 你的Wi-Fi凭证 const char* ssid 你的Wi-Fi名称; const char* password 你的Wi-Fi密码; // Ollama服务器地址 const char* ollamaServer http://192.168.1.100:11434/api/generate; void setup() { Serial.begin(115200); delay(1000); // 连接Wi-Fi WiFi.begin(ssid, password); Serial.print(Connecting to WiFi); while (WiFi.status() ! WL_CONNECTED) { delay(500); Serial.print(.); } Serial.println(\nConnected! IP address: ); Serial.println(WiFi.localIP()); // 测试向Ollama发送一个问题 askOllama(用一句话介绍你自己。); } void loop() { // 主循环可以留空或添加按钮触发对话等逻辑 // 例如当按下某个按钮时调用 askOllama 函数 delay(10000); // 每10秒问一次仅用于测试 askOllama(现在几点了); // 注意这个问题需要模型知道时间或者我们提供时间信息。 } void askOllama(String userQuestion) { if (WiFi.status() ! WL_CONNECTED) { Serial.println(WiFi not connected!); return; } HTTPClient http; http.begin(ollamaServer); // 指定请求地址 http.addHeader(Content-Type, application/json); // 设置请求头 // 构建请求JSON DynamicJsonDocument requestDoc(1024); requestDoc[model] qwen2.5:7b; // 改为你实际运行的模型名 requestDoc[prompt] userQuestion; requestDoc[stream] false; String requestBody; serializeJson(requestDoc, requestBody); Serial.println(Sending request to Ollama...); Serial.println(Question: userQuestion); int httpResponseCode http.POST(requestBody); // 发送POST请求 if (httpResponseCode 0) { Serial.printf(HTTP Response code: %d\n, httpResponseCode); String response http.getString(); Serial.println(Raw Response: response); // 解析JSON响应 DynamicJsonDocument responseDoc(2048); // 根据返回内容大小调整 DeserializationError error deserializeJson(responseDoc, response); if (!error) { const char* modelReply responseDoc[response]; // 提取回答内容 Serial.println(\nOllama says: ); Serial.println(modelReply); // 这里可以将回答显示到屏幕或通过语音模块播报 } else { Serial.print(JSON parsing failed: ); Serial.println(error.c_str()); } } else { Serial.printf(HTTP POST failed, error: %s\n, http.errorToString(httpResponseCode).c_str()); } http.end(); // 释放资源 }代码关键点解析WiFi.begin()连接本地网络这是所有网络通信的前提。http.begin()和http.POST()发起HTTP POST请求的核心。ArduinoJson库的serializeJson和deserializeJson分别用于将内存中的数据结构序列化成JSON字符串发送以及将接收到的JSON字符串反序列化便于提取数据。务必根据响应大小分配足够的DynamicJsonDocument缓冲区否则会导致解析失败。响应处理成功时从responseDoc[response]中取出模型回复。3.4 第四步实现联网搜索工具调用功能现在我们升级代码让ESP32能够先获取实时信息比如网络时间再将信息提供给模型实现“伪”联网问答。我们将创建一个函数getNetworkTime()来从NTP服务器获取时间然后在提问时将时间信息作为上下文插入prompt中。#include WiFi.h #include HTTPClient.h #include ArduinoJson.h #include time.h // ... Wi-Fi和Ollama配置同上 ... const char* ntpServer pool.ntp.org; const long gmtOffset_sec 8 * 3600; // 东八区北京时间偏移 const int daylightOffset_sec 0; void setup() { Serial.begin(115200); connectToWiFi(); // 初始化并从NTP服务器获取时间 configTime(gmtOffset_sec, daylightOffset_sec, ntpServer); printLocalTime(); // 打印时间确认获取成功 // 组合问题将当前时间作为上下文提供给模型 String currentTimeStr getTimeString(); // 获取格式化的时间字符串 String enhancedPrompt 当前时间是 currentTimeStr 。用户问现在几点了; askOllama(enhancedPrompt); } void loop() {} String getTimeString() { struct tm timeinfo; if (!getLocalTime(timeinfo)) { return Failed to obtain time; } char timeString[64]; strftime(timeString, sizeof(timeString), %Y-%m-%d %H:%M:%S, timeinfo); return String(timeString); } void askOllama(String prompt) { // ... 与之前相同的HTTP请求和解析代码但使用传入的prompt ... // requestDoc[prompt] prompt; }在这个例子中ESP32主动获取了网络时间并将“当前时间是2024-05-27 14:30:00。”这段事实与用户问题“现在几点了”拼接在一起发送给Ollama。模型就会基于你提供的准确时间来回答案而不是基于其训练数据中的过时信息或凭空猜测。这就是工具调用的雏形。你可以将getNetworkTime()函数替换为任何其他工具函数例如getWeather(“Beijing”)调用天气API。controlGPIO(13, HIGH)控制ESP32的13号引脚输出高电平点亮LED。readSensor()读取连接的温湿度传感器数据。关键在于ESP32需要具备执行这些工具函数的能力并在与模型交互时智能地决定何时调用、如何将调用结果整合进对话。4. 高级应用构建简易Agent工作流要实现更自动化的工具调用我们需要设计一个简单的工作流让模型能“告诉”ESP32它想调用什么工具。这通常需要模型支持Function Calling。以下是一个概念性的实现思路定义工具清单在ESP32代码中预定义一个工具列表描述每个工具的功能和参数。例如[ { name: get_current_time, description: 获取当前的网络时间, parameters: {} }, { name: get_weather, description: 获取指定城市的天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名例如北京} }, required: [city] } } ]设计系统Prompt在每次对话开始时或在特定的用户请求下ESP32发送一个包含工具定义的“系统指令”给模型。这个指令会告诉模型“你拥有以下工具当用户问题需要时你可以请求调用它们。”模型返回工具调用请求如果模型判断需要调用工具它会在回复中返回一个结构化数据例如{ response: ..., // 可能是一些思考过程 tool_calls: [ { name: get_weather, arguments: {city: 上海} } ] }ESP32执行并反馈ESP32解析tool_calls调用对应的getWeather(“上海”)函数获取天气数据。然后将工具执行的结果作为新的用户消息再次发送给模型。用户: 上海和北京天气怎么样 助手: (思考后返回工具调用请求) ESP32: (执行get_weather(上海)和get_weather(北京)得到结果) ESP32发送新请求: “用户原问题是‘上海和北京天气怎么样’。工具get_weather返回的结果是上海晴25度北京多云22度。请根据这些信息回答用户。” 助手: “上海今天晴天气温25摄氏度北京多云气温22摄氏度。上海比北京暖和一些。”ESP32呈现最终答案将模型的最终回答展示给用户。实现难点模型支持并非所有Ollama模型都原生支持结构化工具调用。你需要选择明确支持此功能的模型或者通过精心设计的Prompt工程来“引导”模型输出你期望的格式。JSON解析复杂性ESP32需要解析更复杂的、嵌套的JSON响应并准确提取工具名和参数。这对ArduinoJson库的使用和内存管理提出了更高要求。状态管理ESP32需要维护简单的对话状态记住用户原始问题、工具调用结果等以进行多轮交互。5. 常见问题、优化与排查技巧在实际操作中你肯定会遇到各种问题。这里记录了一些典型的坑和解决方案。5.1 连接与通信问题问题ESP32无法连接Wi-Fi。排查检查SSID和密码是否正确确保路由器是2.4GHz频段部分ESP32型号不支持5GHz检查路由器是否设置了MAC地址过滤。技巧在代码中加入重试机制和详细的连接状态打印。void connectToWiFi() { WiFi.begin(ssid, password); int retries 0; while (WiFi.status() ! WL_CONNECTED retries 20) { delay(500); Serial.print(.); retries; } if (WiFi.status() WL_CONNECTED) { Serial.println(\nWiFi connected!); } else { Serial.println(\nWiFi connection FAILED!); // 可以考虑进入深度睡眠或重启 ESP.restart(); } }问题ESP32能连Wi-Fi但无法访问Ollama服务器HTTP请求失败。排查1IP地址和端口确认电脑的防火墙是否放行了11434端口。在电脑上尝试用curl http://localhost:11434/api/generate测试Ollama服务是否正常。如果ESP32和电脑不在同一网段也会无法访问。排查2Ollama服务绑定默认Ollama只监听本地回环地址127.0.0.1。为了让ESP32能访问需要在启动Ollama时指定监听所有网卡。可以通过设置环境变量OLLAMA_HOST0.0.0.0然后重启Ollama服务。排查3HTTPClient超时网络不稳定时增加HTTP客户端的超时时间。http.setTimeout(10000); // 设置超时为10秒5.2 内存与性能优化问题解析JSON时崩溃或得到乱码。原因DynamicJsonDocument分配的缓冲区大小不足。Ollama的回复可能很长。解决增大缓冲区。可以先在串口监视器中打印出原始的响应字符串长度然后据此调整。例如如果响应大约有2000个字符建议分配DynamicJsonDocument doc(3000)留出余量。进阶技巧如果响应是流式的stream: true或者响应体巨大可以考虑使用JsonStreamingParser之类的库来边接收边解析避免大块内存分配。问题ESP32运行一段时间后重启看门狗超时。原因HTTP请求或JSON解析耗时过长阻塞了主循环导致看门狗定时器WDT复位。解决将耗时的网络操作放在loop()中并做好状态管理避免单次操作时间过长。使用yield()函数在长循环中释放控制权。考虑使用FreeRTOS任务来分离网络通信和其他功能。5.3 模型与Prompt相关问题模型回复慢或无响应。排查首先在电脑上直接用ollama run命令测试模型响应速度。如果本地就慢可能是模型太大或电脑性能不足。尝试更小的模型如phi3:mini。优化在请求Ollama时设置stream: false可以避免处理流式数据简化ESP32代码。但如果是长文本生成等待时间会变长。问题工具调用不准确模型不按格式返回。解决这是Prompt工程问题。你需要在发送给模型的系统指令中非常清晰、严格地定义你期望的响应格式。使用少样本Few-Shot提示给出几个输入输出的例子能极大提高模型遵循格式的概率。示例Prompt你是一个助手可以调用工具。当用户问题需要实时信息时请严格按照以下JSON格式回复只返回这个JSON不要有其他文字 {tool_to_call: get_weather, parameters: {city: 用户提到的城市}} 例如 用户北京天气如何 你{tool_to_call: get_weather, parameters: {city: 北京}} 现在请回答上海今天气温多少5.4 项目扩展方向当基础功能跑通后你可以考虑以下方向进行深化语音交互接入MAX9814麦克风模块和AI语音识别模型如VITS实现语音输入。或者更简单点使用集成好的离线语音识别模块。丰富输出除了串口打印可以连接OLED显示屏来显示对话或者用WS2812灯带来通过颜色表达情绪如思考时蓝色闪烁回答时绿色常亮。多工具集成让ESP32集成更多硬件能力如控制家电通过继电器、读取环境传感器数据、拍照等并将这些全部定义为模型可调用的工具。引入向量数据库在运行Ollama的电脑上搭配使用像chroma或qdrant这样的本地向量数据库结合RAG检索增强生成技术让模型能够基于你提供的本地文档如个人笔记、产品手册进行回答实现真正的“私有知识库”。部署到专用设备将Ollama部署到树莓派、旧笔记本或小型服务器上让它24小时运行ESP32作为常开的智能终端。这个项目的乐趣在于它像一座桥梁连接了物理世界和数字智能。你不仅是在学习如何调用一个API更是在设计一个微型的人机交互系统。每一次调试每一次功能增加都是对“如何让机器更懂人”这个命题的一次亲手实践。从点亮第一盏LED到让AI根据传感器数据自动调节灯光这中间的每一步都充满了创造的成就感。本文还有配套的精品资源点击获取 ESP32+Ollama：本地大模型与物联网终端的低成本智能交互方案
简介本资源是一个面向嵌入式AI开发者的实践项目聚焦于在ESP32微控制器上部署轻量级本地大模型并实现对话交互、联网通信与工具调用能力解决边缘端AI推理与云边协同的实际落地难题。适用于具备C/Python基础、熟悉ESP-IDF开发环境的物联网与人工智能交叉领域学习者及工程师。压缩包共87个文件含15个核心Python脚本含模型加载、HTTP客户端、工具调度逻辑、11个C/H源码文件ESP32底层驱动与AI推理接口、7个JSON/YML配置模型参数、API路由、工具定义以及PDF文档、LICENSE、Makefile等工程支撑文件整体12.9MB结构清晰模块划分明确。已有86人学习下载。读者可直接复现本地语音/文本对话系统获得完整端到端代码框架、小模型量化适配方案、Wi-Fi联网调用Dify等外部服务的集成示例以及xiao-zhi情感识别、闹钟控制等典型场景实现参考。1. 项目概述当ESP32遇见本地大模型最近在捣鼓一个挺有意思的玩意儿用一块几十块钱的ESP32开发板去调用跑在自己电脑上的大语言模型比如Llama 3、Qwen2.5不仅能实现本地对话还能让这个“小脑瓜”联网查资料甚至调用一些简单的工具。听起来是不是有点“小马拉大车”的感觉没错这个项目的核心魅力就在于此——将资源受限的物联网终端设备与能力强大的本地AI模型连接起来探索在边缘侧实现更智能交互的可能性。你可能会问ESP32这种主打低功耗、Wi-Fi/蓝牙的微控制器内存通常就几百KB跑大模型不是天方夜谭吗确实让模型直接在ESP32上运行目前还不现实。但这个项目的思路很巧妙让ESP32扮演一个“智能终端”或“交互代理”的角色。它负责采集信息比如语音输入、传感器数据、接收用户指令然后通过Wi-Fi将请求发送到同一局域网内、运行着Ollama服务的PC或服务器上。Ollama负责运行本地大模型处理复杂的逻辑和语言生成再将结果返回给ESP32由ESP32执行最终的动作比如在屏幕上显示、控制继电器、或者根据模型的指令再去调用某个Web API工具调用。这解决了几个实际痛点一是隐私与成本所有对话和数据都在本地流转无需支付高昂的云API费用也避免了隐私泄露风险二是低延迟与高可用性局域网内通信速度极快且不依赖外网即使断网也能进行基础对话三是扩展了物联网设备的“智力”上限让一个简单的温湿度传感器节点也能通过自然语言与你交流并基于模型的理解做出更复杂的决策。无论是想做一个个人的语音助手、智能家居的中控大脑还是一个能联网查询信息的桌面摆件这个组合都提供了一个极具性价比和可玩性的起点。2. 核心架构与组件选型解析要实现“ESP32 Ollama 联网 工具调用”这套系统我们需要清晰地理解各个组件的职责以及它们之间如何协同工作。整个架构可以看作一个微型的客户端-服务器模型并在此基础上增加了代理和工具调用的能力。2.1 硬件核心ESP32开发板ESP32是本项目的物理交互终端和动作执行单元。它的选型直接决定了项目的交互形式和能力边界。主要职责用户交互接口通过按键、触摸屏、麦克风需额外模块接收用户输入。网络通信客户端建立Wi-Fi连接向Ollama服务器发送HTTP请求并接收响应。结果呈现与执行在OLED屏幕、LED灯带上显示对话内容或通过GPIO控制继电器、电机等执行器。工具调用执行端当模型返回一个工具调用请求如“查询天气”时ESP32需要解析该请求并执行对应的网络查询或本地操作。型号选择建议ESP32-S3这是当前的首选。它主频更高240MHzPSRAM可选配最高8MBUSB接口原生支持JTAG调试开发体验更好。如果计划使用语音唤醒或更复杂的UI推荐选择带PSRAM的型号。ESP32-C3性价比极高基于RISC-V架构功耗更低。但性能稍弱且外设接口如DAC可能不如S3系列丰富。适合对成本敏感、功能简单的项目。经典ESP32ESP32-D0WD资源充足生态最成熟。如果手头已有完全可以使用。注意务必确认开发板的Wi-Fi功能正常且能稳定连接到你部署Ollama的局域网。有些兼容板的天线设计或固件可能存在连接问题。2.2 软件核心Ollama本地模型服务Ollama是本项目的“大脑”它简化了在本地Windows, macOS, Linux运行大型语言模型的复杂度。核心价值一键部署与管理通过简单的命令行就能拉取、运行和管理各种开源模型无需复杂的环境配置。提供标准化APIOllama提供了一个类似OpenAI API的RESTful接口默认端口11434这使得ESP32可以使用通用的HTTP客户端库与之通信极大降低了集成难度。模型轻量化Ollama支持运行量化后的模型如GGUF格式在保持一定性能的同时大幅降低了对硬件主要是GPU显存的要求。例如7B参数的模型在4-8GB显存的消费级显卡上就能流畅运行。模型选型建议Llama 3系列如llama3:8b综合能力强指令跟随和逻辑推理不错英文优先中文尚可。Qwen 2.5系列如qwen2.5:7b中文能力非常出色代码和数学能力强对中文场景友好。Gemma 2系列如gemma2:9b由Google推出在常识推理和安全性方面表现较好。Phi-3系列如phi3:mini超轻量级模型参数小但能力不弱适合在CPU上运行或快速测试。实操心得初次尝试时建议从参数量较小的模型开始如phi3:mini或qwen2.5:0.5b下载快运行资源要求低能快速验证整个通信链路是否通畅。之后再根据实际需求升级到更大模型。2.3 通信桥梁HTTP API与数据格式ESP32与Ollama之间通过HTTP协议进行通信。理解这个通信过程是项目成功的关键。请求流程ESP32作为客户端构造一个HTTP POST请求发送到http://[你的电脑IP]:11434/api/generate。请求体JSON格式这是核心告诉Ollama要做什么。{ model: qwen2.5:7b, // 指定使用的模型 prompt: 用户的问题或指令在这里, // 输入的文本 stream: false, // 设为false让Ollama一次性返回完整结果简化ESP32处理 options: { temperature: 0.7 // 控制创造性值越高回答越随机 } }响应体JSON格式Ollama处理完成后会返回一个JSON对象。{ model: qwen2.5:7b, created_at: 2024-..., response: 模型生成的回答内容在这里。, // 这是我们需要的核心字段 done: true }ESP32需要解析这个JSON提取出response字段的内容。关键点ESP32的代码中需要使用WiFiClient或HTTPClient在Arduino框架中库来建立连接、发送请求和解析响应。JSON的解析可以使用ArduinoJson库它非常轻量且高效。2.4 能力扩展联网搜索与工具调用这是让项目从“本地知识库问答”升级为“智能代理”的关键一步。实现方式主要有两种“伪”联网通过Ollama的上下文在发送给Ollama的prompt中手动插入实时信息。例如ESP32可以先调用一个天气API获取数据然后将“当前北京气温25度晴”这段文本作为背景信息和用户的问题“北京天气怎么样”一起组合成新的prompt发送给Ollama。模型就能基于你给的实时数据来回答。这种方式简单直接但需要ESP32事先知道该调用哪些工具、如何调用。“真”代理与工具调用这是更高级的模式需要引入“代理Agent”的概念。我们可以让Ollama模型具备“思考-行动”的能力。具体流程是用户提问“今天上海和北京的天气对比如何”ESP32发送请求将问题原样发送给Ollama。Ollama返回工具调用请求模型“思考”后发现需要天气数据它不会直接生成答案而是返回一个结构化的工具调用请求。例如它可能返回一个包含function_call字段的响应需要模型支持Function Calling功能部分Ollama模型已支持或通过特定prompt工程实现。ESP32执行工具ESP32解析这个请求识别出需要调用“天气查询API”然后分别调用上海和北京的天气接口获取原始数据。ESP32再次请求将获取到的两地天气数据连同原始问题再次发送给Ollama。Ollama生成最终答案模型基于实时数据生成对比性的总结回答。ESP32呈现结果将最终答案显示或播报出来。方案选择对于初学者强烈建议从第一种“伪”联网开始先让ESP32学会调用一个固定的API如天气、时间并将其结果成功融入对话。这能帮你夯实HTTP请求、JSON解析、字符串拼接等基础。之后再挑战更复杂的代理模式。3. 详细实现步骤与代码解析接下来我们分步拆解如何从零搭建这个系统。我们将以Arduino IDE作为ESP32的开发环境并使用一个支持Function Calling的模型例如qwen2.5:7b的某个版本来演示基础的工具调用流程。3.1 第一步搭建Ollama服务器环境这是项目的“大脑”安装环节。下载与安装访问Ollama官网根据你的操作系统Windows/macOS/Linux下载安装包。安装过程通常是一键式的。拉取模型打开终端Windows是CMD或PowerShell执行拉取命令。由于网络原因下载可能很慢。ollama pull qwen2.5:7b解决下载慢的技巧使用镜像源这是最有效的方法。在拉取前设置环境变量Linux/macOS在~/.bashrc或~/.zshrc Windows在系统环境变量中新增。# 以Linux为例添加以下行 export OLLAMA_HOST0.0.0.0 # 允许非本地访问方便ESP32连接 export OLLAMA_MODELS/path/to/your/models # 可选指定模型存放路径 # 对于下载可以尝试在拉取命令前使用代理如果你有合法合规的国际网络加速服务但更推荐使用国内镜像。 # 注意Ollama本身没有官方国内镜像但一些社区提供了镜像站使用时请自行甄别安全性和合规性。手动导入GGUF模型从Hugging Face等平台下载模型的GGUF格式文件然后使用ollama create命令从本地文件创建模型。这能绕过Ollama服务器的拉取。运行与测试安装完成后Ollama服务会自动在后台运行。你可以在终端测试ollama run qwen2.5:7b这会进入一个交互式聊天界面输入“Hello”看是否有回复以验证模型运行正常。获取本机IP地址在命令行输入ipconfig(Windows) 或ifconfig(Linux/macOS)找到你电脑在局域网中的IPv4地址如192.168.1.100。ESP32需要连接这个地址。3.2 第二步配置Arduino IDE与ESP32开发环境安装Arduino IDE从官网下载并安装。添加ESP32开发板支持打开Arduino IDE进入文件 - 首选项在“附加开发板管理器网址”中输入https://espressif.github.io/arduino-esp32/package_esp32_index.json然后进入工具 - 开发板 - 开发板管理器搜索“esp32”找到由“Espressif Systems”提供的包点击安装。安装必要库本项目需要两个核心库WiFi/WiFiClientSecureESP32内置无需额外安装。ArduinoJson用于解析Ollama返回的JSON数据。通过项目 - 加载库 - 管理库...搜索安装。HTTPClientESP32内置用于发起HTTP请求。3.3 第三步编写ESP32端核心代码下面是一个精简但功能完整的示例实现了连接Wi-Fi、向Ollama发送提问、并解析回复的基本功能。我们假设Ollama服务器IP是192.168.1.100。#include WiFi.h #include HTTPClient.h #include ArduinoJson.h // 你的Wi-Fi凭证 const char* ssid 你的Wi-Fi名称; const char* password 你的Wi-Fi密码; // Ollama服务器地址 const char* ollamaServer http://192.168.1.100:11434/api/generate; void setup() { Serial.begin(115200); delay(1000); // 连接Wi-Fi WiFi.begin(ssid, password); Serial.print(Connecting to WiFi); while (WiFi.status() ! WL_CONNECTED) { delay(500); Serial.print(.); } Serial.println(\nConnected! IP address: ); Serial.println(WiFi.localIP()); // 测试向Ollama发送一个问题 askOllama(用一句话介绍你自己。); } void loop() { // 主循环可以留空或添加按钮触发对话等逻辑 // 例如当按下某个按钮时调用 askOllama 函数 delay(10000); // 每10秒问一次仅用于测试 askOllama(现在几点了); // 注意这个问题需要模型知道时间或者我们提供时间信息。 } void askOllama(String userQuestion) { if (WiFi.status() ! WL_CONNECTED) { Serial.println(WiFi not connected!); return; } HTTPClient http; http.begin(ollamaServer); // 指定请求地址 http.addHeader(Content-Type, application/json); // 设置请求头 // 构建请求JSON DynamicJsonDocument requestDoc(1024); requestDoc[model] qwen2.5:7b; // 改为你实际运行的模型名 requestDoc[prompt] userQuestion; requestDoc[stream] false; String requestBody; serializeJson(requestDoc, requestBody); Serial.println(Sending request to Ollama...); Serial.println(Question: userQuestion); int httpResponseCode http.POST(requestBody); // 发送POST请求 if (httpResponseCode 0) { Serial.printf(HTTP Response code: %d\n, httpResponseCode); String response http.getString(); Serial.println(Raw Response: response); // 解析JSON响应 DynamicJsonDocument responseDoc(2048); // 根据返回内容大小调整 DeserializationError error deserializeJson(responseDoc, response); if (!error) { const char* modelReply responseDoc[response]; // 提取回答内容 Serial.println(\nOllama says: ); Serial.println(modelReply); // 这里可以将回答显示到屏幕或通过语音模块播报 } else { Serial.print(JSON parsing failed: ); Serial.println(error.c_str()); } } else { Serial.printf(HTTP POST failed, error: %s\n, http.errorToString(httpResponseCode).c_str()); } http.end(); // 释放资源 }代码关键点解析WiFi.begin()连接本地网络这是所有网络通信的前提。http.begin()和http.POST()发起HTTP POST请求的核心。ArduinoJson库的serializeJson和deserializeJson分别用于将内存中的数据结构序列化成JSON字符串发送以及将接收到的JSON字符串反序列化便于提取数据。务必根据响应大小分配足够的DynamicJsonDocument缓冲区否则会导致解析失败。响应处理成功时从responseDoc[response]中取出模型回复。3.4 第四步实现联网搜索工具调用功能现在我们升级代码让ESP32能够先获取实时信息比如网络时间再将信息提供给模型实现“伪”联网问答。我们将创建一个函数getNetworkTime()来从NTP服务器获取时间然后在提问时将时间信息作为上下文插入prompt中。#include WiFi.h #include HTTPClient.h #include ArduinoJson.h #include time.h // ... Wi-Fi和Ollama配置同上 ... const char* ntpServer pool.ntp.org; const long gmtOffset_sec 8 * 3600; // 东八区北京时间偏移 const int daylightOffset_sec 0; void setup() { Serial.begin(115200); connectToWiFi(); // 初始化并从NTP服务器获取时间 configTime(gmtOffset_sec, daylightOffset_sec, ntpServer); printLocalTime(); // 打印时间确认获取成功 // 组合问题将当前时间作为上下文提供给模型 String currentTimeStr getTimeString(); // 获取格式化的时间字符串 String enhancedPrompt 当前时间是 currentTimeStr 。用户问现在几点了; askOllama(enhancedPrompt); } void loop() {} String getTimeString() { struct tm timeinfo; if (!getLocalTime(timeinfo)) { return Failed to obtain time; } char timeString[64]; strftime(timeString, sizeof(timeString), %Y-%m-%d %H:%M:%S, timeinfo); return String(timeString); } void askOllama(String prompt) { // ... 与之前相同的HTTP请求和解析代码但使用传入的prompt ... // requestDoc[prompt] prompt; }在这个例子中ESP32主动获取了网络时间并将“当前时间是2024-05-27 14:30:00。”这段事实与用户问题“现在几点了”拼接在一起发送给Ollama。模型就会基于你提供的准确时间来回答案而不是基于其训练数据中的过时信息或凭空猜测。这就是工具调用的雏形。你可以将getNetworkTime()函数替换为任何其他工具函数例如getWeather(“Beijing”)调用天气API。controlGPIO(13, HIGH)控制ESP32的13号引脚输出高电平点亮LED。readSensor()读取连接的温湿度传感器数据。关键在于ESP32需要具备执行这些工具函数的能力并在与模型交互时智能地决定何时调用、如何将调用结果整合进对话。4. 高级应用构建简易Agent工作流要实现更自动化的工具调用我们需要设计一个简单的工作流让模型能“告诉”ESP32它想调用什么工具。这通常需要模型支持Function Calling。以下是一个概念性的实现思路定义工具清单在ESP32代码中预定义一个工具列表描述每个工具的功能和参数。例如[ { name: get_current_time, description: 获取当前的网络时间, parameters: {} }, { name: get_weather, description: 获取指定城市的天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名例如北京} }, required: [city] } } ]设计系统Prompt在每次对话开始时或在特定的用户请求下ESP32发送一个包含工具定义的“系统指令”给模型。这个指令会告诉模型“你拥有以下工具当用户问题需要时你可以请求调用它们。”模型返回工具调用请求如果模型判断需要调用工具它会在回复中返回一个结构化数据例如{ response: ..., // 可能是一些思考过程 tool_calls: [ { name: get_weather, arguments: {city: 上海} } ] }ESP32执行并反馈ESP32解析tool_calls调用对应的getWeather(“上海”)函数获取天气数据。然后将工具执行的结果作为新的用户消息再次发送给模型。用户: 上海和北京天气怎么样 助手: (思考后返回工具调用请求) ESP32: (执行get_weather(上海)和get_weather(北京)得到结果) ESP32发送新请求: “用户原问题是‘上海和北京天气怎么样’。工具get_weather返回的结果是上海晴25度北京多云22度。请根据这些信息回答用户。” 助手: “上海今天晴天气温25摄氏度北京多云气温22摄氏度。上海比北京暖和一些。”ESP32呈现最终答案将模型的最终回答展示给用户。实现难点模型支持并非所有Ollama模型都原生支持结构化工具调用。你需要选择明确支持此功能的模型或者通过精心设计的Prompt工程来“引导”模型输出你期望的格式。JSON解析复杂性ESP32需要解析更复杂的、嵌套的JSON响应并准确提取工具名和参数。这对ArduinoJson库的使用和内存管理提出了更高要求。状态管理ESP32需要维护简单的对话状态记住用户原始问题、工具调用结果等以进行多轮交互。5. 常见问题、优化与排查技巧在实际操作中你肯定会遇到各种问题。这里记录了一些典型的坑和解决方案。5.1 连接与通信问题问题ESP32无法连接Wi-Fi。排查检查SSID和密码是否正确确保路由器是2.4GHz频段部分ESP32型号不支持5GHz检查路由器是否设置了MAC地址过滤。技巧在代码中加入重试机制和详细的连接状态打印。void connectToWiFi() { WiFi.begin(ssid, password); int retries 0; while (WiFi.status() ! WL_CONNECTED retries 20) { delay(500); Serial.print(.); retries; } if (WiFi.status() WL_CONNECTED) { Serial.println(\nWiFi connected!); } else { Serial.println(\nWiFi connection FAILED!); // 可以考虑进入深度睡眠或重启 ESP.restart(); } }问题ESP32能连Wi-Fi但无法访问Ollama服务器HTTP请求失败。排查1IP地址和端口确认电脑的防火墙是否放行了11434端口。在电脑上尝试用curl http://localhost:11434/api/generate测试Ollama服务是否正常。如果ESP32和电脑不在同一网段也会无法访问。排查2Ollama服务绑定默认Ollama只监听本地回环地址127.0.0.1。为了让ESP32能访问需要在启动Ollama时指定监听所有网卡。可以通过设置环境变量OLLAMA_HOST0.0.0.0然后重启Ollama服务。排查3HTTPClient超时网络不稳定时增加HTTP客户端的超时时间。http.setTimeout(10000); // 设置超时为10秒5.2 内存与性能优化问题解析JSON时崩溃或得到乱码。原因DynamicJsonDocument分配的缓冲区大小不足。Ollama的回复可能很长。解决增大缓冲区。可以先在串口监视器中打印出原始的响应字符串长度然后据此调整。例如如果响应大约有2000个字符建议分配DynamicJsonDocument doc(3000)留出余量。进阶技巧如果响应是流式的stream: true或者响应体巨大可以考虑使用JsonStreamingParser之类的库来边接收边解析避免大块内存分配。问题ESP32运行一段时间后重启看门狗超时。原因HTTP请求或JSON解析耗时过长阻塞了主循环导致看门狗定时器WDT复位。解决将耗时的网络操作放在loop()中并做好状态管理避免单次操作时间过长。使用yield()函数在长循环中释放控制权。考虑使用FreeRTOS任务来分离网络通信和其他功能。5.3 模型与Prompt相关问题模型回复慢或无响应。排查首先在电脑上直接用ollama run命令测试模型响应速度。如果本地就慢可能是模型太大或电脑性能不足。尝试更小的模型如phi3:mini。优化在请求Ollama时设置stream: false可以避免处理流式数据简化ESP32代码。但如果是长文本生成等待时间会变长。问题工具调用不准确模型不按格式返回。解决这是Prompt工程问题。你需要在发送给模型的系统指令中非常清晰、严格地定义你期望的响应格式。使用少样本Few-Shot提示给出几个输入输出的例子能极大提高模型遵循格式的概率。示例Prompt你是一个助手可以调用工具。当用户问题需要实时信息时请严格按照以下JSON格式回复只返回这个JSON不要有其他文字 {tool_to_call: get_weather, parameters: {city: 用户提到的城市}} 例如 用户北京天气如何 你{tool_to_call: get_weather, parameters: {city: 北京}} 现在请回答上海今天气温多少5.4 项目扩展方向当基础功能跑通后你可以考虑以下方向进行深化语音交互接入MAX9814麦克风模块和AI语音识别模型如VITS实现语音输入。或者更简单点使用集成好的离线语音识别模块。丰富输出除了串口打印可以连接OLED显示屏来显示对话或者用WS2812灯带来通过颜色表达情绪如思考时蓝色闪烁回答时绿色常亮。多工具集成让ESP32集成更多硬件能力如控制家电通过继电器、读取环境传感器数据、拍照等并将这些全部定义为模型可调用的工具。引入向量数据库在运行Ollama的电脑上搭配使用像chroma或qdrant这样的本地向量数据库结合RAG检索增强生成技术让模型能够基于你提供的本地文档如个人笔记、产品手册进行回答实现真正的“私有知识库”。部署到专用设备将Ollama部署到树莓派、旧笔记本或小型服务器上让它24小时运行ESP32作为常开的智能终端。这个项目的乐趣在于它像一座桥梁连接了物理世界和数字智能。你不仅是在学习如何调用一个API更是在设计一个微型的人机交互系统。每一次调试每一次功能增加都是对“如何让机器更懂人”这个命题的一次亲手实践。从点亮第一盏LED到让AI根据传感器数据自动调节灯光这中间的每一步都充满了创造的成就感。本文还有配套的精品资源点击获取