让 ESP32 iPhone Agent 完全离线运行:vLLM、Ollama 或 DGX Spark 本地视觉模型部署完整教程

原创2026-10-15 18:54:491,362 阅读
文章标签:人工智能大模型AI AgentGUI 自动化AI 应用嵌入式

让 ESP32 iPhone Agent 完全离线运行:vLLM、Ollama 或 DGX Spark 本地视觉模型部署完整教程

ESP32 iPhone Agent 是一个让 AI 操作真实 iPhone 的开源项目:一块约 7 美元的 ESP32-S3 小板子充当"手",AirPlay 屏幕镜像充当"眼",而"大脑"可以是任何 OpenAI 兼容的本地视觉模型。本完整教程带你用 Ollama、vLLM、DGX Spark 三种最主流的方式,在自己的机器上把这个 iPhone Agent 跑成完全离线——不依赖云端 API、不需要联网推理、不产生任何 Token 费用。

部署方式 难度 推荐硬件 适合人群
Ollama ⭐ 最简单 任意 GPU(CPU 也能跑小模型) 第一次部署视觉模型的新手
vLLM ⭐⭐ 8GB+ 显存 追求性能与成本平衡
DGX Spark 双机 ⭐⭐⭐ 2 台 DGX Spark 追求极致速度(约 1.3 秒/动作)
内置极简服务 ⭐⭐⭐ NVIDIA GPU 想 100% 本地化的实验玩家

为什么要把视觉模型部署到本地

用云端 API 当然可以,但本地视觉模型有四个明显优势:

  • 🔒 隐私:手机截图只在局域网内流转,不会离开你的机器;
  • 💰 费用:按量计费变成零成本,可以 7×24 小时跑任务;
  • ⚡ 稳定:没有速率限制,不会因为断网而中断长任务;
  • 🏃 延迟:本项目是闭环 Agent,每个动作都要推理一次,本地推理可以做到每步 1~2 秒的节奏。

动手前先理解一个关键点:这个项目的"大脑"由 Planner(规划)+ Actor(执行) 两个角色组成,它们通过标准的 OpenAI 兼容接口调用模型(客户端实现见 server/hidagent/llm.py)。也就是说——无论用哪种方式部署本地模型,只要它对外暴露 /v1/chat/completions 接口,你只需要改 .env 里的三行配置。

前置准备:三步让项目先跑起来

如果你还没搭好整套系统,先按 README.zh-CN.md 的 Quick start 完成(可先填云端 API 验证流程):

git clone https://gitcode.com/gh_mirrors/es/esp32-iphone-agent
  1. 刷固件:编辑 hardware/hid_bridge/ 下的 secrets.h(填 2.4GHz Wi-Fi 和电脑 IP),运行 hardware/flash.sh 烧录 ESP32-S3;
  2. 装服务端:安装 UxPlay(AirPlay 接收端),在 server/ 安装 Python 服务,并按 server/.env.example 写好配置;
  3. 手机端一次性设置:打开辅助触控 → 插入板子 → 开启屏幕镜像 → 在网页里完成校准。

ESP32 iPhone Agent 硬件连接:XIAO ESP32S3 插入 iPhone,旁边电脑上的网页界面接入本地视觉模型

到这一步,"眼"和"手"已经在工作,剩下的就是把"大脑"换成你自己的本地模型。

方法一:用 Ollama 部署视觉模型(新手最快)

Ollama 是上手最快的本地大模型工具,自带 OpenAI 兼容接口,端口默认 11434。

第一步,安装 Ollama 并拉取一个视觉模型(任选其一):

模型 建议显存 说明
tinyllava / moondream2 约 4GB 轻量,CPU 也能跑,适合先跑通流程
qwen2.5vl:7b 8GB+ 中文与界面理解强,最推荐
llava:13b 16GB+ 图像理解更好,速度较慢
ollama pull qwen2.5vl:7b
ollama serve    # 多数情况下已随系统自动启动

第二步,修改 server/.env(API Key 填任意值即可):

LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=qwen2.5vl:7b
LLM_API_KEY=ollama

第三步,重启服务端,部署完成。如果 Ollama 和 Agent 服务端不在同一台机器,把 localhost 换成 Ollama 机器的 IP 即可。

💡 LLM_MODEL 的值必须与 Ollama 实际上报的模型名完全一致,可用 ollama list 核对。

方法二:用 vLLM 起高性能本地视觉模型

vLLM 的吞吐和延迟表现优于 Ollama,是单卡部署 7B~32B 视觉模型时最常见的选择。

pip install vllm
vllm serve Qwen/Qwen2.5-VL-7B-Instruct \
  --served-model-name qwen2.5-vl \
  --port 8000

启动后接口就在 http://localhost:8000/v1——正好是本项目 LLM_BASE_URL 的默认地址。.env 里只需:

LLM_BASE_URL=http://localhost:8000/v1
LLM_MODEL=qwen2.5-vl

两个进阶调优技巧:

  • 关闭思考模式:新一代视觉模型默认"思考"会拖慢每一步。用 LLM_EXTRA_BODY 给每次请求注入参数即可:
LLM_EXTRA_BODY='{"chat_template_kwargs": {"enable_thinking": false}}'
  • 输出长度参数:若服务提示不识别 max_tokens,设置 LLM_TOKEN_PARAM=max_completion_tokens(默认 auto 会自动探测切换)。

方法三:DGX Spark 双机并行的本地部署

追求极致速度的话,直接参考本项目的"官方答案"——这也是开发时实测速度用的配置:

  • 模型:nvidia/Qwen3.8-Flash-Next-NVFP4(NVFP4 量化);
  • 部署:两台 NVIDIA DGX Spark 通过 TensorFold 张量并行(TP=2),对外提供 OpenAI 兼容接口;
  • 实测速度:关闭思考模式后,每个动作约 1.3 秒、每次规划约 2 秒,Agent 的操作节奏已经接近真人。

对应的 .env 配置:

LLM_BASE_URL=http://<dgx-spark-ip>:8888/v1
LLM_MODEL=Qwen3.8-Flash-Next
LLM_EXTRA_BODY='{"chat_template_kwargs": {"enable_thinking": false}}'

让手机执行"设置每天早上 7 点重复的闹钟"这类日常任务时,DGX Spark 上的本地模型可以稳稳支撑高频的"看截图 → 决策 → 动作"闭环:

ESP32 iPhone Agent 本地视觉模型离线运行演示:在真实 iPhone 上自动设置每天重复的闹钟

彩蛋:内置极简本地服务(DiffusionGemma 实验方案)

仓库的 server/serve/ 目录自带一个极简服务:server/serve/transformers_server.py 直接用 transformers 加载 Hugging Face 视觉语言模型,只实现了 Agent 需要的两个接口(POST /v1/chat/completions 与 GET /v1/models)。

环境变量 默认值 说明
MODEL_ID google/diffusiongemma-26B-A4B-it 模型仓库 ID 或本地路径
MODEL_NAME 取自 MODEL_ID 上报给客户端的模型名
PORT 8000 服务端口
IMAGE_TOKENS 280 图像 Token 预算(DiffusionGemma 支持 70/140/280/560/1120)

NVIDIA GPU 机器上可以直接用 Docker 启动(脚本见 server/serve/run-docker.sh):

MODEL_REPO=google/diffusiongemma-26B-A4B-it \
IMAGE=<带 PyTorch 与 transformers 的 CUDA 镜像> \
serve/run-docker.sh start

脚本直接从 Hugging Face 缓存目录加载模型,并设置 HF_HUB_OFFLINE=1,断网也能跑。注意:项目 README 把它标为实验路线,完整的 Agent 跑通尚未测试,适合愿意折腾的玩家。

验证:确认本地模型已正确接入

先确认模型服务存活:

curl http://localhost:8000/v1/models

然后打开 Web UI,下达"打开设置,进入 Wi-Fi"这类简单任务,观察运行画面:

ESP32 iPhone Agent 完全离线运行网页界面:本地视觉模型完成"在白板画笑脸"任务,右上角显示规划与执行模型名

  • 页面右上角的 Decision Planner / Action Actor 处,应显示你配置的两个本地模型名;
  • 设置 HIDAGENT_DEBUG=1 后,每次运行会在 ~/.hidagent/traces/ 保存提示词、模型原始回复与每次调用的耗时,可以直观确认延迟来自本地推理。

常见问题排查清单

症状 可能原因 解决办法
400 报错 / 模型答非所问 选了纯文本模型,不支持图片 换视觉模型:qwen2.5vl、llava、minicpm-v 等
每步耗时 10 秒以上 思考模式未关 / 纯 CPU 推理 加 LLM_EXTRA_BODY 关思考,或换更小模型、上 GPU
连接超时、控制器无反应 端口未放行或填错地址 核对 LLM_BASE_URL 的 IP 与端口,检查防火墙
请求被拒 / 模型名不匹配 .env 与上报的模型名不一致 ollama list 或查看 vLLM 的 --served-model-name

常见问题 FAQ

云端和本地能混用吗? 能。ACTOR_* 和 PLANNER_* 可以分别覆盖两个角色的配置——比如执行用快速本地模型,规划用更强的云端模型,随时切换。

显存要多少? 7B 视觉模型(4bit 量化)约 8GB,13B 以上建议 16GB+,70B+ 需要多卡;CPU 可以跑 tinyllava、moondream2 试水,但延迟会明显偏高。

本地部署后彻底不联网可以吗? 可以。模型下载到本地后,Ollama / vLLM 的推理过程不再请求外网;serve/ 的极简服务更是明确按离线缓存设计的,整条链路(ESP32 ↔ 服务端 ↔ 模型)都在局域网内。

写在最后

ESP32 iPhone Agent 的"眼"(AirPlay 镜像)和"手"(USB HID 桥)本来就与互联网无关。Ollama 起步最快、vLLM 性价比最高、DGX Spark 速度最强——任选一条路把本地视觉模型部署好,"截图 → 理解 → 动作 → 校验"的完整闭环就跑在你的局域网里,这个 iPhone 自动化 Agent 才算真正属于你自己。

登录后查看全文
esp32-iphone-agent