AgentCPM-GUI是由清华大学自然语言处理实验室（THUNLP）和ModelBest联合开发的开源设备端GUI代理工具，能够操作中文和英文安卓应用，并通过强化微调提升推理能力，高效执行任务。

## 一、主要功能
1. **高质量GUI定位**：基于大规模双语安卓数据集预训练，显著提升对常见GUI组件（如按钮、输入框、标签、图标等）的定位和理解能力。
2. **中文应用操作**：首个针对中文应用进行精细微调的开源GUI代理，涵盖30多个流行应用，如高德地图、大众点评、哔哩哔哩和小红书。
3. **增强规划与推理**：通过强化微调（RFT），模型在输出操作前能够“思考”，大幅提高复杂任务的成功率。
4. **紧凑动作空间设计**：优化的动作空间和简洁的JSON格式，将平均动作长度缩短至9.7个标记，提升设备端推理效率。

## 二、技术原理
AgentCPM-GUI基于MiniCPM-V模型，拥有80亿参数，以智能手机屏幕截图作为输入，自主执行用户指定的任务。其通过大规模双语安卓数据集进行预训练，增强对GUI组件的理解和定位能力。此外，通过强化微调（RFT）技术，模型能够在输出操作前进行推理和规划，从而提高任务执行的成功率。紧凑的动作空间设计和JSON格式的输出，进一步优化了设备端的推理效率。

## 三、应用场景
1. **自动化测试**：用于安卓应用的自动化测试，快速定位和操作界面元素，提高测试效率。
2. **智能助手**：作为智能助手的一部分，帮助用户快速完成应用内的操作任务，如点击按钮、输入文本等。
3. **应用开发**：为应用开发者提供界面交互的自动化解决方案，辅助开发和优化应用的用户体验。
4. **教育与培训**：在教育领域，用于演示和教学安卓应用的操作流程，帮助学生更好地理解和掌握应用的使用方法。

## 四、使用方法
1. **安装依赖**：
```bash
git clone https://github.com/OpenBMB/AgentCPM-GUI
cd AgentCPM-GUI
conda create -n gui_agent python=3.11
conda activate gui_agent
pip install -r requirements.txt
```
2. **下载模型**：
从Hugging Face下载AgentCPM-GUI模型，并将其放置在`model/AgentCPM-GUI`目录下。
3. **推理使用**：
- **Huggingface推理**：
```python
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
from PIL import Image
import json

# 1. 加载模型和分词器
model_path = "model/AgentCPM-GUI" # 模型路径
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(model_path, trust_remote_code=True, torch_dtype=torch.bfloat16)
model = model.to("cuda:0")

# 2. 构建输入
instruction = "请点击屏幕上的‘会员’按钮"
image_path = "assets/test.jpeg"
image = Image.open(image_path).convert("RGB")

# 3. 调整图片大小
def __resize__(origin_img):
resolution = origin_img.size
w, h = resolution
max_line_res = 1120
if max_line_res is not None:
max_line = max_line_res
if h > max_line:
w = int(w * max_line / h)
h = max_line
if w > max_line:
h = int(h * max_line / w)
w = max_line
img = origin_img.resize((w, h), resample=Image.Resampling.LANCZOS)
return img
image = __resize__(image)

# 4. 构建消息格式
messages = [{
"role": "user",
"content": [
f"<Question>{instruction}</Question>\n当前屏幕截图：",
image
]
}]

# 5. 推理
ACTION_SCHEMA = json.load(open('eval/utils/schema/schema.json', encoding="utf-8"))
items = list(ACTION_SCHEMA.items())
insert_index = 3
items.insert(insert_index, ("required", ["thought"])) # 启用/禁用思考
ACTION_SCHEMA = dict(items)
SYSTEM_PROMPT = f'''# Role
你是一名熟悉安卓系统触屏GUI操作的智能体，将根据用户的问题，分析当前界面的GUI元素和布局，生成相应的操作。

# Task
针对用户问题，根据输入的当前屏幕截图，输出下一步的操作。

# Rule
- 以紧凑JSON格式输出
- 输出操作必须遵循Schema约束

# Schema
{json.dumps(ACTION_SCHEMA, indent=None, ensure_ascii=False, separators=(',', ':'))}'''

outputs = model.chat(
image=None,
msgs=messages,
system_prompt=SYSTEM_PROMPT,
tokenizer=tokenizer,
temperature=0.1,
top_p=0.3,
n=1,
)

# 6. 输出结果
print(outputs)
```
- **vLLM推理**：
```bash
# 启动vLLM服务器
vllm serve model/AgentCPM-GUI --served-model-name AgentCPM-GUI --tensor_parallel_size 1 --trust-remote-code
```
```python
import base64
import io
import json
import requests
from PIL import Image

END_POINT = "http://localhost:8000/v1/chat/completions" # 替换为实际端点

# 系统提示
ACTION_SCHEMA = json.load(open('eval/utils/schema/schema.json', encoding="utf-8"))
items = list(ACTION_SCHEMA.items())
insert_index = 3
items.insert(insert_index, ("required", ["thought"])) # 启用/禁用思考
ACTION_SCHEMA = dict(items)
SYSTEM_PROMPT = f'''# Role
你是一名熟悉安卓系统触屏GUI操作的智能体，将根据用户的问题，分析当前界面的GUI元素和布局，生成相应的操作。

# Task
针对用户问题，根据输入的当前屏幕截图，输出下一步的操作。

# Rule
- 以紧凑JSON格式输出
- 输出操作必须遵循Schema约束

# Schema
{json.dumps(ACTION_SCHEMA, indent=None, ensure_ascii=False, separators=(',', ':'))}'''

def encode_image(image: Image.Image) -> str:
"""将PIL图像转换为base64编码的字符串"""
with io.BytesIO() as in_mem_file:
image.save(in_mem_file, format="JPEG")
in_mem_file.seek(0)
return base64.b64encode(in_mem_file.read()).decode("utf-8")

def __resize__(origin_img):
resolution = origin_img.size
w, h = resolution
max_line_res = 1120
if max_line_res is not None:
max_line = max_line_res
if h > max_line:
w = int(w * max_line / h)
h = max_line
if w > max_line:
h = int(h * max_line / w)
w = max_line
img = origin_img.resize((w, h), resample=Image.Resampling.LANCZOS)
return img

def predict(text_prompt: str, image: Image.Image):
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": [
{"type": "text", "text": f"<Question>{text_prompt}</Question>\n当前屏幕截图："},
{"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{encode_image(image)}"}}
]}
]

payload = {
"model": "AgentCPM-GUI", # 模型名称
"temperature": 0.1,
"messages": messages,
"max_tokens": 2048,
}

headers = {
"Content-Type": "application/json",
}

response = requests.post(END_POINT, headers=headers, json=payload)
assistant_msg = response.json()["choices"][0]["message"]["content"]
return assistant_msg

image = __resize__(Image.open("assets/test.jpeg"))
instruction = "请点击屏幕上的‘会员’按钮"
response = predict(instruction, image)
print(response)
```

## 五、适用人群
1. **应用开发者**：用于自动化测试和优化应用的用户体验。
2. **自动化测试工程师**：快速定位和操作界面元素，提高测试效率。
3. **教育工作者**：在教学中演示和讲解安卓应用的操作流程。
4. **智能助手开发者