let5see/Open-AutoGLM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme for ai guide

Browse Source
This commit is contained in:
yongbin-buaa
2025-12-11 17:43:05 +08:00
parent cc51051342
commit cf6a3b78eb
2 changed files with 84 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
README.md
View File

@@ -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" "你的任务描述"
# 查看支持的应用列表

28
README_en.md
View File

@@ -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):**