diff --git a/README.md b/README.md index 3a147d6..b510264 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ ## 项目介绍 Phone Agent 是一个基于 AutoGLM 构建的手机端智能助理框架,它能够以多模态方式理解手机屏幕内容,并通过自动化操作帮助用户完成任务。系统通过 -ADB(Android Debug Bridge)来控制设备,以视觉语言模型进行屏幕感知,再结合智能规划能力生成并执行操作流程。用户只需用自然语言描述需求,如“打开小红书搜索美食”,Phone +ADB(Android Debug Bridge)来控制设备,以视觉语言模型进行屏幕感知,再结合智能规划能力生成并执行操作流程。用户只需用自然语言描述需求,如“打开小红书搜索美食”,Phone Agent 即可自动解析意图、理解当前界面、规划下一步动作并完成整个流程。系统还内置敏感操作确认机制,并支持在登录或验证码场景下进行人工接管。同时,它提供远程 ADB 调试能力,可通过 WiFi 或网络连接设备,实现灵活的远程控制与开发。 @@ -60,7 +60,7 @@ ADB 调试能力,可通过 WiFi 或网络连接设备,实现灵活的远程 ![权限](resources/screenshot-20251209-181423.png) -### 4. 安装 ADB Keyboard(用于文本输入) +### 4. 安装 ADB Keyboard(用于文本输入) 下载 [安装包](https://github.com/senzhk/ADBKeyBoard/blob/master/ADBKeyboard.apk) 并在对应的安卓设备中进行安装。 注意,安装完成后还需要到 `设置-输入法` 或者 `设置-键盘列表` 中启用 `ADB Keyboard` 才能生效 @@ -97,7 +97,7 @@ adb devices 如果你不想自行部署模型,可以使用以下已部署我们模型的第三方服务: -**1. ModelScope(魔搭社区)** +**1. ModelScope(魔搭社区)** - 文档: https://modelscope.cn/models/ZhipuAI/AutoGLM-Phone-9B - `--base-url`: `https://api-inference.modelscope.cn/v1` @@ -143,7 +143,7 @@ python main.py --base-url https://api-inference.modelscope.cn/v1 --model "ZhipuA **注意**: 上述步骤出现的关于 transformers 的依赖冲突可以忽略。 -1. 在对应容器或者实体机中(非容器安装)下载模型,通过 SGlang / vLLM 启动,得到 OpenAI 格式服务。这里提供一个 vLLM部署方案,请严格遵循我们提供的启动参数: +1. 在对应容器或者实体机中(非容器安装)下载模型,通过 SGlang / vLLM 启动,得到 OpenAI 格式服务。这里提供一个 vLLM部署方案,请严格遵循我们提供的启动参数: - vLLM: @@ -204,9 +204,9 @@ python scripts/check_deployment_cn.py --base-url http://你的IP:你的端口/v1 ``` **参数说明:** -- `--base-url`: 模型服务地址(根据实际部署地址修改) +- `--base-url`: 模型服务地址(根据实际部署地址修改) - `--model`: 模型名称 -- `--messages-file`: 可选,指定自定义测试消息文件(默认使用 `scripts/sample_messages.json`) +- `--messages-file`: 可选,指定自定义测试消息文件(默认使用 `scripts/sample_messages.json`) ## 使用 AutoGLM @@ -341,7 +341,7 @@ conn.disconnect("192.168.1.100:5555") 系统提供中英文两套 prompt,通过 `--lang` 参数切换: -- `--lang cn` - 中文 prompt(默认),配置文件:`phone_agent/config/prompts_zh.py` +- `--lang cn` - 中文 prompt(默认),配置文件:`phone_agent/config/prompts_zh.py` - `--lang en` - 英文 prompt,配置文件:`phone_agent/config/prompts_en.py` 可以直接修改对应的配置文件来增强模型在特定领域的能力,或通过注入 app 名称禁用某些 app。 @@ -364,7 +364,7 @@ from phone_agent.model import ModelConfig config = ModelConfig( base_url="http://localhost:8000/v1", - api_key="EMPTY", # API 密钥(如需要) + api_key="EMPTY", # API 密钥(如需要) model_name="autoglm-phone-9b", # 模型名称 max_tokens=3000, # 最大输出 token 数 temperature=0.1, # 采样温度 @@ -379,9 +379,9 @@ from phone_agent.agent import AgentConfig config = AgentConfig( max_steps=100, # 每个任务最大步数 - device_id=None, # ADB 设备 ID(None 为自动检测) - lang="cn", # 语言选择:cn(中文)或 en(英文) - verbose=True, # 打印调试信息(包括思考过程和执行动作) + device_id=None, # ADB 设备 ID(None 为自动检测) + lang="cn", # 语言选择:cn(中文)或 en(英文) + verbose=True, # 打印调试信息(包括思考过程和执行动作) ) ``` @@ -457,7 +457,7 @@ Agent 可以执行以下操作: | `Long Press` | 长按 | | `Double Tap` | 双击 | | `Wait` | 等待页面加载 | -| `Take_over` | 请求人工接管(登录/验证码等) | +| `Take_over` | 请求人工接管(登录/验证码等) | ## 自定义回调 @@ -544,7 +544,7 @@ adb devices 如果仍然无法识别,请检查: 1. USB 调试是否已开启 -2. 数据线是否支持数据传输(部分数据线仅支持充电) +2. 数据线是否支持数据传输(部分数据线仅支持充电) 3. 手机上弹出的授权框是否已点击「允许」 4. 尝试更换 USB 接口或数据线 @@ -553,7 +553,7 @@ adb devices 部分机型需要同时开启两个调试选项才能正常使用: - **USB 调试** -- **USB 调试(安全设置)** +- **USB 调试(安全设置)** 请在 `设置 → 开发者选项` 中检查这两个选项是否都已启用。 @@ -563,9 +563,9 @@ adb devices 2. 在设置 > 系统 > 语言和输入法 > 虚拟键盘 中启用 3. Agent 会在需要输入时自动切换到 ADB Keyboard -### 截图失败(黑屏) +### 截图失败(黑屏) -这通常意味着应用正在显示敏感页面(支付、密码、银行类应用)。Agent 会自动检测并请求人工接管。 +这通常意味着应用正在显示敏感页面(支付、密码、银行类应用)。Agent 会自动检测并请求人工接管。 ### windows 编码异常问题 @@ -600,9 +600,9 @@ adb devices --- -## 自动化部署指南(面向 AI) +## 自动化部署指南(面向 AI) -> **本章节专为 AI 助手(如 Claude Code)设计,用于自动化部署 Open-AutoGLM。** +> **本章节专为 AI 助手(如 Claude Code)设计,用于自动化部署 Open-AutoGLM。** > > 如果你是人类读者,可以跳过本章节,按照上面的文档操作即可。 @@ -611,12 +611,12 @@ adb devices ### 项目概述 Open-AutoGLM 是一个手机 Agent 框架: -- **输入**:用户的自然语言指令(如"打开微信发消息给张三") +- **输入**:用户的自然语言指令(如"打开微信发消息给张三") - **输出**:自动操作用户的安卓手机完成任务 - **原理**:截图 → 视觉模型理解界面 → 输出点击坐标 → ADB 执行操作 → 循环 架构分为两部分: -1. **Agent 代码**(本仓库):运行在用户电脑上,负责调用模型、解析动作、控制手机 +1. **Agent 代码**(本仓库):运行在用户电脑上,负责调用模型、解析动作、控制手机 2. **视觉模型服务**:可以是远程 API,也可以本地部署 --- @@ -626,28 +626,28 @@ Open-AutoGLM 是一个手机 Agent 框架: 在开始部署前,请逐项向用户确认以下内容: #### 硬件环境 -- [ ] 用户有一台安卓手机(Android 7.0+) -- [ ] 用户有一根支持数据传输的 USB 数据线(不是仅充电线) +- [ ] 用户有一台安卓手机(Android 7.0+) +- [ ] 用户有一根支持数据传输的 USB 数据线(不是仅充电线) - [ ] 手机和电脑可以通过数据线连接 #### 手机端配置 -- [ ] 手机已开启「开发者模式」(设置 → 关于手机 → 连续点击版本号 7 次) -- [ ] 手机已开启「USB 调试」(设置 → 开发者选项 → USB 调试) -- [ ] 部分机型需要同时开启「USB 调试(安全设置)」 -- [ ] 手机已安装 ADB Keyboard 应用(下载地址:https://github.com/senzhk/ADBKeyBoard/blob/master/ADBKeyboard.apk) -- [ ] ADB Keyboard 已在系统设置中启用(设置 → 语言和输入法 → 启用 ADB Keyboard) +- [ ] 手机已开启「开发者模式」(设置 → 关于手机 → 连续点击版本号 7 次) +- [ ] 手机已开启「USB 调试」(设置 → 开发者选项 → USB 调试) +- [ ] 部分机型需要同时开启「USB 调试(安全设置)」 +- [ ] 手机已安装 ADB Keyboard 应用(下载地址:https://github.com/senzhk/ADBKeyBoard/blob/master/ADBKeyboard.apk) +- [ ] ADB Keyboard 已在系统设置中启用(设置 → 语言和输入法 → 启用 ADB Keyboard) -#### 模型服务确认(二选一) +#### 模型服务确认(二选一) **请明确询问用户:你是否已有可用的 AutoGLM 模型服务?** -- **选项 A:使用已部署的模型服务(推荐)** - - 用户提供模型服务的 URL(如 `http://xxx.xxx.xxx.xxx:8000/v1`) +- **选项 A:使用已部署的模型服务(推荐)** + - 用户提供模型服务的 URL(如 `http://xxx.xxx.xxx.xxx:8000/v1`) - 无需本地 GPU,无需下载模型 - 直接使用该 URL 作为 `--base-url` 参数 -- **选项 B:本地部署模型(高配置要求)** - - 需要 NVIDIA GPU(建议 24GB+ 显存) +- **选项 B:本地部署模型(高配置要求)** + - 需要 NVIDIA GPU(建议 24GB+ 显存) - 需要安装 vLLM 或 SGLang - 需要下载约 20GB 的模型文件 - **如果用户是新手或不确定,强烈建议选择选项 A** @@ -687,11 +687,11 @@ adb devices #### 阶段二:安装 Agent ```bash -# 1. 克隆仓库(如果还没有克隆) +# 1. 克隆仓库(如果还没有克隆) git clone https://github.com/zai-org/Open-AutoGLM.git cd Open-AutoGLM -# 2. 创建虚拟环境(推荐) +# 2. 创建虚拟环境(推荐) python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate @@ -704,17 +704,32 @@ pip install -e . #### 阶段三:配置模型服务 -**如果用户选择选项 A(使用已部署的模型):** -- 直接使用用户提供的 URL -- 跳过本地模型部署步骤 +**如果用户选择选项 A(使用已部署的模型):** -**如果用户选择选项 B(本地部署模型):** +你可以使用以下第三方模型服务: + +1. **ModelScope(魔搭社区)** + - 文档:https://modelscope.cn/models/ZhipuAI/AutoGLM-Phone-9B + - `--base-url`:`https://api-inference.modelscope.cn/v1` + - `--model`:`ZhipuAI/AutoGLM-Phone-9B` + - `--apikey`:在 ModelScope 平台申请你的 API Key + +使用示例: + +```bash +# 使用 ModelScope +python main.py --base-url https://api-inference.modelscope.cn/v1 --model "ZhipuAI/AutoGLM-Phone-9B" --apikey "your-modelscope-api-key" "打开美团搜索附近的火锅店" +``` + +或者直接使用用户提供的其他模型服务 URL,跳过本地模型部署步骤。 + +**如果用户选择选项 B(本地部署模型):** ```bash # 1. 安装 vLLM pip install vllm -# 2. 启动模型服务(会自动下载模型,约 20GB) +# 2. 启动模型服务(会自动下载模型,约 20GB) python3 -m vllm.entrypoints.openai.api_server \ --served-model-name autoglm-phone-9b \ --allowed-local-media-path / \ @@ -752,9 +767,9 @@ python main.py --base-url {MODEL_URL} --model "autoglm-phone-9b" "打开微信 |---------|---------|---------| | `adb devices` 无输出 | USB 调试未开启或数据线问题 | 检查开发者选项,更换数据线 | | `adb devices` 显示 unauthorized | 手机未授权 | 手机上点击「允许 USB 调试」| -| 能打开应用但无法点击 | 缺少安全调试权限 | 开启「USB 调试(安全设置)」| +| 能打开应用但无法点击 | 缺少安全调试权限 | 开启「USB 调试(安全设置)」| | 中文输入变成乱码或无输入 | ADB Keyboard 未启用 | 在系统设置中启用 ADB Keyboard | -| 截图返回黑屏 | 敏感页面(支付/银行) | 正常现象,系统会自动处理 | +| 截图返回黑屏 | 敏感页面(支付/银行) | 正常现象,系统会自动处理 | | 连接模型服务失败 | URL 错误或服务未启动 | 检查 URL,确认服务正在运行 | | `ModuleNotFoundError` | 依赖未安装 | 执行 `pip install -r requirements.txt` | @@ -782,10 +797,10 @@ adb kill-server && adb start-server # 安装依赖 pip install -r requirements.txt && pip install -e . -# 运行 Agent(交互模式) +# 运行 Agent(交互模式) python main.py --base-url {MODEL_URL} --model "autoglm-phone-9b" -# 运行 Agent(单次任务) +# 运行 Agent(单次任务) python main.py --base-url {MODEL_URL} --model "autoglm-phone-9b" "你的任务描述" # 查看支持的应用列表 diff --git a/README_en.md b/README_en.md index f9bae80..e9d188a 100644 --- a/README_en.md +++ b/README_en.md @@ -630,8 +630,32 @@ pip install -e . #### Phase 3: Configure Model Service **If user chooses Option A (using already-deployed model):** -- Use the URL provided by the user directly -- Skip local model deployment steps + +You can use the following third-party model services: + +1. **Novita AI** + - Documentation: https://novita.ai/models/model-detail/zai-org-autoglm-phone-9b-multilingual + - `--base-url`: `https://api.novita.ai/openai` + - `--model`: `zai-org/autoglm-phone-9b-multilingual` + - `--apikey`: Apply for your own API key on the Novita AI platform + +2. **Parasail** + - Documentation: https://www.saas.parasail.io/serverless?name=auto-glm-9b-multilingual + - `--base-url`: `https://api.parasail.io/v1` + - `--model`: `parasail-auto-glm-9b-multilingual` + - `--apikey`: Apply for your own API key on the Parasail platform + +Example usage: + +```bash +# Using Novita AI +python main.py --base-url https://api.novita.ai/openai --model "zai-org/autoglm-phone-9b-multilingual" --apikey "your-novita-api-key" "Open Chrome browser" + +# Using Parasail +python main.py --base-url https://api.parasail.io/v1 --model "parasail-auto-glm-9b-multilingual" --apikey "your-parasail-api-key" "Open Chrome browser" +``` + +Or use the URL provided by the user directly and skip local model deployment steps. **If user chooses Option B (deploy model locally):**