让 ESP32 iPhone Agent 完全离线运行:vLLM、Ollama 或 DGX Spark 本地视觉模型部署完整教程
让 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
- 刷固件:编辑 hardware/hid_bridge/ 下的
secrets.h(填 2.4GHz Wi-Fi 和电脑 IP),运行 hardware/flash.sh 烧录 ESP32-S3; - 装服务端:安装 UxPlay(AirPlay 接收端),在
server/安装 Python 服务,并按 server/.env.example 写好配置; - 手机端一次性设置:打开辅助触控 → 插入板子 → 开启屏幕镜像 → 在网页里完成校准。
到这一步,"眼"和"手"已经在工作,剩下的就是把"大脑"换成你自己的本地模型。
方法一:用 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 上的本地模型可以稳稳支撑高频的"看截图 → 决策 → 动作"闭环:
彩蛋:内置极简本地服务(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"这类简单任务,观察运行画面:
- 页面右上角的 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 才算真正属于你自己。


