🚀 UGround-V1-7B （基於Qwen2-VL）

UGround是一個強大的GUI視覺定位模型，採用簡單的方法進行訓練。更多詳細信息請查看我們的主頁和論文。本項目是俄亥俄州立大學自然語言處理小組和Orby AI的合作成果。

• 主頁：https://osu-nlp-group.github.io/UGround/
• 代碼倉庫：https://github.com/OSU-NLP-Group/UGround
• 論文（ICLR'25口頭報告）：https://arxiv.org/abs/2410.05243
• 演示：https://huggingface.co/spaces/orby-osu/UGround
• 聯繫人：苟博宇

✨ 主要特性

• 強大的GUI視覺定位能力：在多個GUI視覺定位任務中表現出色，如ScreenSpot等。
• 多模型版本：提供不同參數規模的模型版本，包括2B、7B和72B。
• 豐富的實驗支持：涵蓋離線和在線實驗，提供推理代碼和實驗結果。
• 數據合成管道：即將推出數據合成管道，方便用戶進行數據生成。

📦 安裝指南

可參考Qwen2-VL的官方倉庫獲取更多訓練和推理的說明。

💻 使用示例

vLLM服務器

vllm serve osunlp/UGround-V1-7B  --api-key token-abc123 --dtype float16

或者

python -m vllm.entrypoints.openai.api_server --served-model-name osunlp/UGround-V1-7B --model osunlp/UGround-V1-7B --dtype float16 

視覺定位提示

def format_openai_template(description: str, base64_image):
    return [
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"},
                },
                {
                    "type": "text",
                    "text": f"""
  Your task is to help the user identify the precise coordinates (x, y) of a specific area/element/object on the screen based on a description.

  - Your response should aim to point to the center or a representative point within the described area/element/object as accurately as possible.
  - If the description is unclear or ambiguous, infer the most relevant area or element based on its likely context or purpose.
  - Your answer should be a single string (x, y) corresponding to the point of the interest.

  Description: {description}

  Answer:"""
                },
            ],
        },
    ]


messages = format_openai_template(description, base64_image)

completion = await client.chat.completions.create(
    model=args.model_path,
    messages=messages,
    temperature=0  # REMEMBER to set temperature to ZERO!
# REMEMBER to set temperature to ZERO!
# REMEMBER to set temperature to ZERO!
)

# The output will be in the range of [0,1000), which is compatible with the original Qwen2-VL
# So the actual coordinates should be (x/1000*width, y/1000*height)

📚 詳細文檔

模型

• 模型V1：
  • 初始UGround
  • UGround-V1-2B（Qwen2-VL）
  • UGround-V1-7B（Qwen2-VL）
  • UGround-V1-72B（Qwen2-VL）
  • 訓練數據

發佈計劃

• [x] 模型權重
  • [x] 初始版本（論文中使用的版本）
  • [x] 基於Qwen2-VL的V1版本
    • [x] 2B
    • [x] 7B
    • [x] 72B
• [x] 代碼
  • [x] UGround的推理代碼（初始版本和基於Qwen2-VL的版本）
  • [x] 離線實驗（代碼、結果和有用資源）
    • [x] ScreenSpot（以及由GPT-4/4o生成的指代表達）
    • [x] 多模態Mind2Web
    • [x] OmniAct
    • [x] 安卓控制
  • [x] 在線實驗
    • [x] Mind2Web-Live-SeeAct-V
    • [x] AndroidWorld-SeeAct-V
  • [ ] 數據合成管道（即將推出）
• [x] 訓練數據（V1）
• [x] 在線演示（HF Spaces）

主要結果

GUI視覺定位：ScreenSpot（標準設置）

GUI視覺定位：ScreenSpot（代理設置）

🔧 技術細節

暫未提供相關技術細節。

📄 許可證

本項目採用Apache-2.0許可證。

引用信息

如果您覺得本項目有用，請考慮引用我們的論文：

@article{gou2024uground,
        title={Navigating the Digital World as Humans Do: Universal Visual Grounding for GUI Agents},
        author={Boyu Gou and Ruohan Wang and Boyuan Zheng and Yanan Xie and Cheng Chang and Yiheng Shu and Huan Sun and Yu Su},
        journal={arXiv preprint arXiv:2410.05243},
        year={2024},
        url={https://arxiv.org/abs/2410.05243},
      }

@article{zheng2023seeact,
        title={GPT-4V(ision) is a Generalist Web Agent, if Grounded},
        author={Boyuan Zheng and Boyu Gou and Jihyung Kil and Huan Sun and Yu Su},
        journal={arXiv preprint arXiv:2401.01614},
        year={2024},
      }

Qwen2-VL-7B-Instruct

介紹

我們很高興推出Qwen2-VL，這是我們Qwen-VL模型的最新版本，凝聚了近一年的創新成果。

Qwen2-VL有哪些新特性？

關鍵改進：

• 對各種分辨率和比例圖像的最先進理解：Qwen2-VL在視覺理解基準測試中取得了最先進的性能，包括MathVista、DocVQA、RealWorldQA、MTVQA等。
• 理解20分鐘以上的視頻：Qwen2-VL可以理解超過20分鐘的視頻，用於高質量的基於視頻的問答、對話、內容創作等。
• 可操作手機、機器人等的智能體：憑藉複雜的推理和決策能力，Qwen2-VL可以與手機、機器人等設備集成，根據視覺環境和文本指令進行自動操作。
• 多語言支持：為了服務全球用戶，除了英語和中文，Qwen2-VL現在支持理解圖像中不同語言的文本，包括大多數歐洲語言、日語、韓語、阿拉伯語、越南語等。

模型架構更新：

• 樸素動態分辨率：與之前不同，Qwen2-VL可以處理任意圖像分辨率，將其映射到動態數量的視覺標記，提供更接近人類的視覺處理體驗。

我們有三個參數分別為20億、70億和720億的模型。本倉庫包含經過指令微調的70億參數Qwen2-VL模型。更多信息請訪問我們的博客和GitHub。

評估

圖像基準測試

視頻基準測試

要求

Qwen2-VL的代碼已包含在最新的Hugging face transformers中，我們建議您使用以下命令從源代碼構建：

pip install git+https://github.com/huggingface/transformers

否則，您可能會遇到以下錯誤：

KeyError: 'qwen2_vl'

快速開始

我們提供了一個工具包，幫助您更方便地處理各種類型的視覺輸入，包括base64編碼、URL和交錯的圖像和視頻。您可以使用以下命令安裝：

pip install qwen-vl-utils

以下是一個代碼示例，展示如何使用transformers和qwen_vl_utils來使用聊天模型：

from transformers import Qwen2VLForConditionalGeneration, AutoTokenizer, AutoProcessor
from qwen_vl_utils import process_vision_info

# 默認：將模型加載到可用設備上
model = Qwen2VLForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2-VL-7B-Instruct", torch_dtype="auto", device_map="auto"
)

# 我們建議啟用flash_attention_2以獲得更好的加速和內存節省，特別是在多圖像和視頻場景中。
# model = Qwen2VLForConditionalGeneration.from_pretrained(
#     "Qwen/Qwen2-VL-7B-Instruct",
#     torch_dtype=torch.bfloat16,
#     attn_implementation="flash_attention_2",
#     device_map="auto",
# )

# 默認處理器
processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-7B-Instruct")

# 模型中每個圖像的視覺標記數量的默認範圍是4-16384。您可以根據需要設置min_pixels和max_pixels，例如標記數量範圍為256-1280，以平衡速度和內存使用。
# min_pixels = 256*28*28
# max_pixels = 1280*28*28
# processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-7B-Instruct", min_pixels=min_pixels, max_pixels=max_pixels)

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "image": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen-VL/assets/demo.jpeg",
            },
            {"type": "text", "text": "Describe this image."},
        ],
    }
]

# 推理準備
text = processor.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True
)
image_inputs, video_inputs = process_vision_info(messages)
inputs = processor(
    text=[text],
    images=image_inputs,
    videos=video_inputs,
    padding=True,
    return_tensors="pt",
)
inputs = inputs.to("cuda")

# 推理：生成輸出
generated_ids = model.generate(**inputs, max_new_tokens=128)
generated_ids_trimmed = [
    out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
]
output_text = processor.batch_decode(
    generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
)
print(output_text)

from PIL import Image
import requests
import torch
from torchvision import io
from typing import Dict
from transformers import Qwen2VLForConditionalGeneration, AutoTokenizer, AutoProcessor

# 將模型以半精度加載到可用設備上
model = Qwen2VLForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2-VL-7B-Instruct", torch_dtype="auto", device_map="auto"
)
processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-7B-Instruct")

# 圖像
url = "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen-VL/assets/demo.jpeg"
image = Image.open(requests.get(url, stream=True).raw)

conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
            },
            {"type": "text", "text": "Describe this image."},
        ],
    }
]

# 預處理輸入
text_prompt = processor.apply_chat_template(conversation, add_generation_prompt=True)
# 預期輸出: '<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n<|im_start|>user\n<|vision_start|><|image_pad|><|vision_end|>Describe this image.<|im_end|>\n<|im_start|>assistant\n'

inputs = processor(
    text=[text_prompt], images=[image], padding=True, return_tensors="pt"
)
inputs = inputs.to("cuda")

# 推理：生成輸出
output_ids = model.generate(**inputs, max_new_tokens=128)
generated_ids = [
    output_ids[len(input_ids) :]
    for input_ids, output_ids in zip(inputs.input_ids, output_ids)
]
output_text = processor.batch_decode(
    generated_ids, skip_special_tokens=True, clean_up_tokenization_spaces=True
)
print(output_text)

# 包含多個圖像和文本查詢的消息
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "file:///path/to/image1.jpg"},
            {"type": "image", "image": "file:///path/to/image2.jpg"},
            {"type": "text", "text": "Identify the similarities between these images."},
        ],
    }
]

# 推理準備
text = processor.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True
)
image_inputs, video_inputs = process_vision_info(messages)
inputs = processor(
    text=[text],
    images=image_inputs,
    videos=video_inputs,
    padding=True,
    return_tensors="pt",
)
inputs = inputs.to("cuda")

# 推理
generated_ids = model.generate(**inputs, max_new_tokens=128)
generated_ids_trimmed = [
    out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
]
output_text = processor.batch_decode(
    generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
)
print(output_text)

# 包含圖像列表作為視頻和文本查詢的消息
messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "video",
                "video": [
                    "file:///path/to/frame1.jpg",
                    "file:///path/to/frame2.jpg",
                    "file:///path/to/frame3.jpg",
                    "file:///path/to/frame4.jpg",
                ],
                "fps": 1.0,
            },
            {"type": "text", "text": "Describe this video."},
        ],
    }
]
# 包含視頻和文本查詢的消息
messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "video",
                "video": "file:///path/to/video1.mp4",
                "max_pixels": 360 * 420,
                "fps": 1.0,
            },
            {"type": "text", "text": "Describe this video."},
        ],
    }
]

# 推理準備
text = processor.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True
)
image_inputs, video_inputs = process_vision_info(messages)
inputs = processor(
    text=[text],
    images=image_inputs,
    videos=video_inputs,
    padding=True,
    return_tensors="pt",
)
inputs = inputs.to("cuda")

# 推理
generated_ids = model.generate(**inputs, max_new_tokens=128)
generated_ids_trimmed = [
    out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
]
output_text = processor.batch_decode(
    generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
)
print(output_text)

# 批量推理的示例消息
messages1 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "file:///path/to/image1.jpg"},
            {"type": "image", "image": "file:///path/to/image2.jpg"},
            {"type": "text", "text": "What are the common elements in these pictures?"},
        ],
    }
]
messages2 = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Who are you?"},
]
# 合併消息進行批量處理
messages = [messages1, messages1]

# 批量推理準備
texts = [
    processor.apply_chat_template(msg, tokenize=False, add_generation_prompt=True)
    for msg in messages
]
image_inputs, video_inputs = process_vision_info(messages)
inputs = processor(
    text=texts,
    images=image_inputs,
    videos=video_inputs,
    padding=True,
    return_tensors="pt",
)
inputs = inputs.to("cuda")

# 批量推理
generated_ids = model.generate(**inputs, max_new_tokens=128)
generated_ids_trimmed = [
    out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
]
output_texts = processor.batch_decode(
    generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
)
print(output_texts)

更多使用提示

對於輸入圖像，我們支持本地文件、base64編碼和URL。對於視頻，目前我們僅支持本地文件。

# 您可以直接在文本中想要的位置插入本地文件路徑、URL或base64編碼的圖像。
## 本地文件路徑
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "file:///path/to/your/image.jpg"},
            {"type": "text", "text": "Describe this image."},
        ],
    }
]
## 圖像URL
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "http://path/to/your/image.jpg"},
            {"type": "text", "text": "Describe this image."},
        ],
    }
]
## Base64編碼的圖像
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "data:image;base64,/9j/..."},
            {"type": "text", "text": "Describe this image."},
        ],
    }
]

為提高性能調整圖像分辨率

模型支持廣泛的分辨率輸入。默認情況下，它使用原生分辨率進行輸入，但更高的分辨率可以提高性能，但會增加計算量。用戶可以設置最小和最大像素數，以實現適合自己需求的最佳配置，例如標記數量範圍為256-1280，以平衡速度和內存使用。

min_pixels = 256 * 28 * 28
max_pixels = 1280 * 28 * 28
processor = AutoProcessor.from_pretrained(
    "Qwen/Qwen2-VL-7B-Instruct", min_pixels=min_pixels, max_pixels=max_pixels
)

此外，我們提供了兩種方法來精細控制輸入到模型的圖像大小：

1. 定義min_pixels和max_pixels：圖像將被調整大小以保持其寬高比在min_pixels和max_pixels的範圍內。
2. 指定確切的尺寸：直接設置resized_height和resized_width。這些值將被四捨五入到最接近的28的倍數。

# min_pixels和max_pixels
messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "image": "file:///path/to/your/image.jpg",
                "resized_height": 280,
                "resized_width": 420,
            },
            {"type": "text", "text": "Describe this image."},
        ],
    }
]
# resized_height和resized_width
messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "image": "file:///path/to/your/image.jpg",
                "min_pixels": 50176,
                "max_pixels": 50176,
            },
            {"type": "text", "text": "Describe this image."},
        ],
    }
]

侷限性

雖然Qwen2-VL適用於廣泛的視覺任務，但瞭解其侷限性同樣重要。以下是一些已知的限制：

1. 缺乏音頻支持：當前模型無法理解視頻中的音頻信息。
2. 數據時效性：我們的圖像數據集更新至2023年6月，此日期之後的信息可能未涵蓋。
3. 個體和知識產權識別限制：模型識別特定個體或知識產權的能力有限，可能無法全面涵蓋所有知名人物或品牌。
4. 複雜指令處理能力有限：當面對複雜的多步驟指令時，模型的理解和執行能力有待提高。
5. 計數準確性不足：特別是在複雜場景中，對象計數的準確性不高，需要進一步改進。
6. 空間推理能力較弱：特別是在3D空間中，模型對對象位置關係的推斷不足，難以精確判斷對象的相對位置。

這些侷限性是模型優化和改進的持續方向，我們致力於不斷提升模型的性能和應用範圍。

引用

如果您覺得我們的工作有幫助，請隨意引用我們的論文。

@article{Qwen2VL,
  title={Qwen2-VL: Enhancing Vision-Language Model's Perception of the World at Any Resolution},
  author={Wang, Peng and Bai, Shuai and Tan, Sinan and Wang, Shijie and Fan, Zhihao and Bai, Jinze and Chen, Keqin and Liu, Xuejing and Wang, Jialin and Ge, Wenbin and Fan, Yang and Dang, Kai and Du, Mengfei and Ren, Xuancheng and Men, Rui and Liu, Dayiheng and Zhou, Chang and Zhou, Jingren and Lin, Junyang},
  journal={arXiv preprint arXiv:2409.12191},
  year={2024}
}

@article{Qwen-VL,
  title={Qwen-VL: A Versatile Vision-Language Model for Understanding, Localization, Text Reading, and Beyond},
  author={Bai, Jinze and Bai, Shuai and Yang, Shusheng and Wang, Shijie and Tan, Sinan and Wang, Peng and Lin, Junyang and Zhou, Chang and Zhou, Jingren},
  journal={arXiv preprint arXiv:2308.12966},
  year={2023}
}