RefCOCO

<p align="center" width="100%">
<img src="https://i.postimg.cc/g0QRgMVv/WX20240228-113337-2x.png" width="100%" height="80%">
</p>

# Large-scale Multi-modality Models Evaluation Suite

> Accelerating the development of large-scale multi-modality models (LMMs) with `lmms-eval`

🏠 [Homepage](https://lmms-lab.github.io/) | 📚 [Documentation](docs/README.md) | 🤗 [Huggingface Datasets](https://huggingface.co/lmms-lab)

# This Dataset

This is a formatted version of [RefCOCO](https://github.com/lichengunc/refer). It is used in our `lmms-eval` pipeline to allow for one-click evaluations of large multi-modality models.

```
@inproceedings{kazemzadeh-etal-2014-referitgame,
title = "{R}efer{I}t{G}ame: Referring to Objects in Photographs of Natural Scenes",
author = "Kazemzadeh, Sahar and
Ordonez, Vicente and
Matten, Mark and
Berg, Tamara",
editor = "Moschitti, Alessandro and
Pang, Bo and
Daelemans, Walter",
booktitle = "Proceedings of the 2014 Conference on Empirical Methods in Natural Language Processing ({EMNLP})",
month = oct,
year = "2014",
address = "Doha, Qatar",
publisher = "Association for Computational Linguistics",
url = "https://aclanthology.org/D14-1086",
doi = "10.3115/v1/D14-1086",
pages = "787--798",
}
```

<div align='center'><h1>可解码视觉块（Patch-as-Decodable-Token, PaDT）：面向多模态大语言模型的统一视觉任务范式</h1></div>

<font size=4><div align='center'>[[🔗 开源代码](https://github.com/Gorilla-Lab-SCUT/PaDT)]
[[🤗 数据集](https://huggingface.co/collections/PaDT-MLLM/padt-dataset-68e400440ffb8c8f95e5ee20)] [[🤗 模型权重](https://huggingface.co/collections/PaDT-MLLM/padt-68e3f5c22e8ecbd6d0d13d43)]</div></font>
<font size=4><div align='center'>[[📄 技术报告](https://arxiv.org/abs/2510.01954)] [[🤗 论文](https://huggingface.co/papers/2510.01954)]</div></font>

<div align="center">
<img src="./assets/Pipeline.webp" width="900"/>
<p>图A. PaDT 工作流程</p>
</div>

## 🌟 简介

我们荣幸地推出**可解码视觉块（Patch-as-Decodable-Token, PaDT）**，这是一种统一范式，可使多模态大语言模型（Multimodal Large Language Model, MLLM）直接生成文本与视觉输出。

PaDT的核心是**视觉参考令牌（Visual Reference Tokens, VRTs）**。与传统MLLM通过基于文本的边界框坐标表示视觉目标不同（这类方式通常语义性不足，且与实际物体对齐效果较差，如图B所示），PaDT允许MLLM直接通过视觉块表示视觉目标。这些VRTs使模型能够在输出序列中以更自然、直接的方式对视觉信息进行推理。

通过引入VRTs，我们在MLLM的自回归生成过程中实现了**语义推理与针对特定目标的视觉令牌预测**。随后，通过即插即用的轻量PaDT解码器，可将预测得到的视觉令牌解码为定位图或分割图这类**低级输出**。

如图C所示，我们在四大主流视觉感知与理解任务上验证了PaDT的有效性。在所有场景中，相较于传统逐字符坐标生成的MLLM，PaDT均取得了**当前最优（State-of-the-Art, SOTA）**的性能。

### PaDT成功的核心原因？

PaDT的成功源于其对MLLM视觉能力瓶颈的深刻洞察：
1. **原生视觉-语言对齐**：无需将视觉信息“适配”至文本空间，PaDT直接将视觉块视为可解码令牌，实现了无缝的模态对齐。
2. **动态视觉绑定**：采用动态嵌入机制，将视觉参考令牌（VRTs）与每张图像紧密绑定，避免跨图像混淆。
3. **统一令牌空间**：使大语言模型能够统一处理语言与视觉信息，简化训练流程并提升一致性。
4. **轻量解码器**：将稠密预测与大语言模型解耦，在保留其语义推理能力的同时，新增了精准的空间输出能力。
5. **强大的多任务泛化能力**：在REC/RES/OVD/RIC联合训练的PaDT Pro模型可通过提示词切换任务，且性能优于单任务模型。

我们希望本工作能够**启发社区的进一步探索**：
- 真正的多模态推理应当具备何种形态？
- 纯文本输出是否足以支撑视觉推理？

<div align="center">
<img src="./assets/Motivation.webp" width="900"/>
<p>图B. 传统逐字符坐标生成MLLM与我们提出的PaDT的相关观察</p>
</div>

<div align="center">
<img src="./assets/TaskIntroduction.webp" width="900"/>
<p>图C. PaDT在四大视觉感知与理解任务上的应用</p>
</div>

## 快速上手
克隆本仓库并通过少量命令配置运行环境：

bash
git clone https://github.com/Gorilla-Lab-SCUT/PaDT.git

conda create -n PaDT python=3.11
conda activate PaDT

bash setup.sh

以下代码片段展示了PaDT的使用方法：

python
import torch
from transformers import AutoProcessor
from qwen_vl_utils import process_vision_info
from PaDT import PaDTForConditionalGeneration, VisonTextProcessingClass, parseVRTintoCompletion

TEST_IMG_PATH="./eval/imgs/000000368335.jpg"
MODEL_PATH="PaDT-MLLM/PaDT_Pro_3B"

# 加载模型
model = PaDTForConditionalGeneration.from_pretrained(MODEL_PATH, torch_dtype=torch.bfloat16, device_map={"": 0})
# 加载处理器
processor = AutoProcessor.from_pretrained(
MODEL_PATH
)
processor = VisonTextProcessingClass(processor, model.config.vision_config.spatial_merge_size)
processor.prepare(model.model.embed_tokens.weight.shape[0])

# 问题提示词
PROMPT = """请仔细检查图像，并检测以下语句描述的物体："汽车在马的左侧"。"""

# 构建对话
message = [
{
"role": "user",
"content": [
{
"type": "image",
"image": TEST_IMG_PATH
}, {
"type": "text",
"text": PROMPT
}
]
}
]
text = processor.apply_chat_template(message, tokenize=False, add_generation_prompt=True)
image_inputs, video_inputs = process_vision_info(message)
prompt_inputs = processor(
text=[text],
images=image_inputs,
padding=True,
padding_side="left",
return_tensors="pt",
add_special_tokens=False
).to("cuda:0")

# 生成结果
with torch.inference_mode():
generate_returned_result = model.generate(**prompt_inputs, use_cache=True, max_new_tokens=1024, do_sample=False,
output_hidden_states=True, return_dict_in_generate=True)
prompt_length = prompt_inputs["input_ids"].size(1)
completion_ids = generate_returned_result['sequences'][:, prompt_length:]

# 提取序列中的视觉参考令牌
completions, feats, labels, vrts, vrts_feats = parseVRTintoCompletion(processor, completion_ids, generate_returned_result['hidden_states'], torch.Tensor([False]))

print("
生成结果:", completions[0])

# 解码低级视觉任务结果
low_res_image_embeds = generate_returned_result.past_image_embeds
high_res_image_embeds = generate_returned_result.past_high_res_image_embeds
visual_pe = generate_returned_result.past_visual_pe
decoded_list = model.vl_decode(feats, low_res_image_embeds, high_res_image_embeds, prompt_inputs['image_grid_thw'], visual_pe)

print(f"
预测边界框: {decoded_list['pred_boxes']},
预测置信度: {decoded_list['pred_score'].sigmoid()}
")

## 模型列表
- PaDT_OVD：在COCO2017训练集上训练得到。
- PaDT_REC：在RefCOCO/+/g训练集上训练得到。
- PaDT_RIC：在指代表像字幕任务训练集上训练得到。
- PaDT_Pro：在COCO2017、RefCOCO/+/g以及指代表像字幕任务训练集的联合数据集上训练得到。

| 模型 | 基础视觉语言模型 | 模型权重链接 | 任务类型 |
| - | - | - | -
| PaDT_OVD_3B | Qwen2.5VL-3B | [PaDT-MLLM/PaDT_OVD_3B](https://huggingface.co/PaDT-MLLM/PaDT_OVD_3B) | 开放词汇检测 |
| PaDT_REC_3B | Qwen2.5VL-3B | [PaDT-MLLM/PaDT_REC_3B](https://huggingface.co/PaDT-MLLM/PaDT_REC_3B) | 指代表达理解/分割 |
| PaDT_RIC_3B | Qwen2.5VL-3B | [PaDT-MLLM/PaDT_RIC_3B](https://huggingface.co/PaDT-MLLM/PaDT_RIC_3B) | 指代表像字幕 |
| PaDT_Pro_3B | Qwen2.5VL-3B | [PaDT-MLLM/PaDT_Pro_3B](https://huggingface.co/PaDT-MLLM/PaDT_Pro_3B) | 全任务 |
| PaDT_OVD_7B | Qwen2.5VL-7B | [PaDT-MLLM/PaDT_OVD_7B](https://huggingface.co/PaDT-MLLM/PaDT_OVD_7B) | 开放词汇检测 |
| PaDT_REC_7B | Qwen2.5VL-7B | [PaDT-MLLM/PaDT_REC_7B](https://huggingface.co/PaDT-MLLM/PaDT_REC_7B) | 指代表达理解/分割 |
| PaDT_RIC_7B | Qwen2.5VL-7B | [PaDT-MLLM/PaDT_RIC_7B](https://huggingface.co/PaDT-MLLM/PaDT_RIC_7B) | 指代表像字幕 |
| PaDT_Pro_7B | Qwen2.5VL-7B | [PaDT-MLLM/PaDT_Pro_7B](https://huggingface.co/PaDT-MLLM/PaDT_Pro_7B) | 全任务 |

## 效果展示
以下是随机选取的测试样例，展示了PaDT优异的性能表现。
- 指代表达理解/分割与开放词汇检测任务
<div align="center">
<img src="./assets/REC_OVD.webp" width="900"/>
</div>

- 指代表像字幕任务
<div align="center">
<img src="./assets/RIC.webp" width="900"/>
</div>

- 令牌激活图对比
<div align="center">
<img src="./assets/TAM.webp" width="900"/>
</div>

## 训练指南
### 数据集下载
- [COCO](https://cocodataset.org/#home)
- RefCOCO/+/g
bash
wget https://web.archive.org/web/20220413011718/https://bvisionweb1.cs.unc.edu/licheng/referit/data/refcoco.zip
wget https://web.archive.org/web/20220413011656/https://bvisionweb1.cs.unc.edu/licheng/referit/data/refcoco+.zip
wget https://web.archive.org/web/20220413012904/https://bvisionweb1.cs.unc.edu/licheng/referit/data/refcocog.zip

将下载的数据集解压并放置到以下目录结构中：

PaDT/
├── dataset/
│ ├── coco/
│ │ ├── annotations/
│ │ ├── train2014/
│ │ ├── train2017/
│ │ ├── val2014/
│ │ └── val2017/
│ └── RefCOCO/
│ ├── refcoco/
│ ├── refcoco+/
│ └── refcocog/

### 数据集预处理
1. 通过我们提供的脚本进行预处理（请先更新预处理脚本中的数据集路径配置）：
bash
cd src/preprocess
python process_coco.py
python process_refcoco.py

2. 我们还在Hugging Face上发布了已预处理完成的数据集，可直接用于训练：

| 数据集 | 数据集路径 | 任务类型 |
| - | - | -|
| COCO | [PaDT-MLLM/COCO](https://huggingface.co/datasets/PaDT-MLLM/COCO) | 开放词汇检测 |
| RefCOCO | [PaDT-MLLM/RefCOCO](https://huggingface.co/datasets/PaDT-MLLM/RefCOCO) | 指代表达理解/分割 |
| RIC | [PaDT-MLLM/ReferringImageCaptioning](https://huggingface.co/datasets/PaDT-MLLM/ReferringImageCaptioning) | 指代表像字幕 |

`run_scripts`目录下的训练脚本可直接执行。例如：在单节点8×96 GB GPU上训练PaDT-Pro 3B模型：
bash
bash ./run_scripts/padt_pro_3b_sft.sh

## 评估
我们在`eval/test_demo.py`中提供了一个简单的推理示例，更多评估脚本将陆续更新。

## 许可协议
PaDT采用Apache 2.0协议开源。

## 参考文献
- [Patch-as-Decodable-Token: Towards Unified Multi-Modal Vision Tasks in MLLMs](https://huggingface.co/papers/2510.01954)

## 许可协议
PaDT采用Apache 2.0协议开源。

## 引用
如果您认为本工作对您有帮助，请引用我们的论文：

@misc{su2025patchasdecodabletokenunifiedmultimodalvision,
title={Patch-as-Decodable-Token: Towards Unified Multi-Modal Vision Tasks in MLLMs},
author={Yongyi Su and Haojie Zhang and Shijie Li and Nanqing Liu and Jingyi Liao and Junyi Pan and Yuan Liu and Xiaofen Xing and Chong Sun and Chen Li and Nancy F. Chen and Shuicheng Yan and Xulei Yang and Xun Xu},
year={2025},
eprint={2510.01954},
archivePrefix={arXiv},
primaryClass={cs.CV},
url={https://arxiv.org/abs/2510.01954},
}