RelateAnything README

The project's README from github.com/Maelic/RelateAnything. As one markdown file: README.md.

RelateAnything

Real-time open-vocabulary relation prediction from any inputs.

arXiv models demo ci license

Paper · Project page · Models · Training data · Documentation

Give RelateAnything an image, object regions, and the relations you want to look for. It returns scored (subject, relation, object) triplets, such as person → riding → horse.

https://github.com/user-attachments/assets/76544f31-53ac-407b-9445-157e83946938

The same relation model across five scenes, with tracked regions and relations. Clip credits · Reproduce the video

Try the browser demo — no installation; inference runs on your device using WebGPU or WASM.

Quickstart · Models · Deployment · Performance · Results · How it works

Quickstart

Use Python 3.12+. Install a CUDA-enabled PyTorch build for NVIDIA GPU inference, or use device="cpu" in the example below.

git clone https://github.com/Maelic/RelateAnything.git
cd RelateAnything
pip install -e ".[hub]"

Run this from the repository root. The sample photo is included; the two example boxes identify the person and the horse.

import numpy as np
from PIL import Image
from relsgg import RelateAnything

model = RelateAnything.from_pretrained("maelic/relsgg-vits16plus", device="cuda")
image = Image.open("assets/reel/images/horse.jpg").convert("RGB")
boxes = np.array([[470, 130, 650, 630], [90, 310, 1010, 875]], dtype=np.float32)

# Boxes are [x1, y1, x2, y2] in original-image pixels.
# Labels are optional and only make the printed triplets easier to read.
for triplet in model.predict(image, boxes, box_labels=["person", "horse"], topk=5):
    print(triplet)

# Change what relations to look for, without retraining.
model.set_vocabulary(["riding", "carrying a rider", "beside", "in front of"])
graphs = model.predict(image, boxes, box_labels=["person", "horse"], decompose=True)
print(graphs["spatial"])
print(graphs["semantic"])

Released checkpoints include the backbone configuration and text encoder; no gated DINOv3 login is needed for inference. Replace the sample image and boxes with your own inputs; the API also supports masks and a larger built-in relation vocabulary.

API guide: inputs, vocabularies, masks, and scores · Installation and offline use

Models

Start with relsgg-vits16plus, the recommended balance of quality and speed. All three checkpoints use the same training recipe; their vision backbones differ.

Checkpoint Backbone Parameters
relsgg-vits16 DINOv3 ViT-S/16 46.1 M
relsgg-vits16plus DINOv3 ViT-S/16+ 53.2 M
relsgg-vitb16 DINOv3 ViT-B/16 113.8 M

Compare model quality and speed. Each model card includes evaluation results and calibration details.

Deployment

After downloading the relation graph and building the local detector as explained in the deployment guide:

# CPU image demo; omit --image to use a webcam.
python deploy/demo_webcam.py --dist deploy/dist/relsgg-vits16plus --image photo.jpg

# NVIDIA GPU, after building both TensorRT engines.
python deploy/demo_webcam.py --dist deploy/dist/relsgg-vits16plus \
  --backend tensorrt --device cuda --image photo.jpg --decompose

The relation model consumes regions; it does not detect objects itself. Demo detectors are rebuilt locally and have separate licenses. The exported ONNX/TensorRT graph scores boxes; native mask inputs are supported by the PyTorch API. Deployment contracts and limitations.

Performance

On an RTX 3080 Laptop GPU, the recommended ViT-S+ model takes 17.2 ms per image with TensorRT FP32, including preprocessing, transfers and triplet decoding. Object regions are provided as input.

With YOLO26m detection included, the full pipeline takes 36.5 ms per image. Detection uses PyTorch FP32; ViT-S+ relations use TensorRT FP32.

Warm median latency, batch 1, 35 relation types, 6 sample images; loading and setup excluded.

All models and runtimes · YOLO26, YOLO-World and YOLOE comparison · Paper pipeline benchmarks

Results

The paper evaluates relation prediction across datasets, open vocabularies and spatial reasoning tasks. Selected transfer results for ViT-S+, using ground-truth boxes and one relation per ordered pair:

Test set OvSGTR F1@50 RelateAnything F1@50
VG150 16.5 36.9
PSG 13.5 34.7
IndoorVG 20.2 37.8

Both models use the same evaluator and vocabulary. OvSGTR receives object labels; RelateAnything does not. The full results cover stronger baselines including ROBIN-3B, zero-shot controls and the complete evaluation.

Evaluation protocol · Scoring guide

How it works

Figure 2: RelateAnything's visual path, text embedding bank, predicate-conditioned scoring gate, and training objective

Figure 2 from the paper. Click to enlarge.

A DINOv3 backbone reads the image once. Regions become visual tokens; a pair sampler selects candidate relations; a transformer refines them using the scene. A vocabulary head scores each pair against embeddings of your predicate strings, mixing spatial and semantic features. Swapping that embedding bank changes the vocabulary without retraining the vision model.

Architecture guide

Data and evaluation packs

Reproduce and contribute

The documentation index covers the API, architecture, training, data and deployment. Read evaluation pitfalls before comparing results or changing the scoring path.

License

Full third-party notices and credits

Citation

@article{neau2026relateanything,
  title   = {RelateAnything: Real-Time Open-Vocabulary Relation Prediction From Any Inputs},
  author  = {Neau, Ma\"elic},
  journal = {arXiv preprint arXiv:2609.12552},
  eprint  = {2609.12552},
  archivePrefix = {arXiv},
  primaryClass  = {cs.CV},
  url     = {https://arxiv.org/abs/2609.12552},
  year    = {2026}
}

RelateAnything (Maelic/RelateAnything)

Searching Database…

这是什么东西?RelateAnything 是一个实时、开放词表的关系预测模型:给它一张图片、若干物体区域和想查的关系,它就会返回带分数的(主体, 关系, 客体)三元组,比如 人 → 骑 → 马。
那我实际拿到手的是什么——Python 库、网页应用,还是一项服务?它是某篇研究论文配套开源的代码:一个带预训练权重的 PyTorch API,外加训练和评估工具、可用于 TensorRT 和 OpenVINO 部署的 ONNX 图,还有一个无需安装的浏览器演示。
怎么用它跑我自己的照片?在仓库根目录运行快速上手示例:里面自带一张示例照片和两个示例检测框(人和马),换成你自己的图片和检测框即可。也支持掩码(mask)和更大的内置关系词表。
运行之前需要装什么特别的东西吗?需要 Python 3.12+ 和 PyTorch——想在 NVIDIA GPU 上推理就装支持 CUDA 的版本,也可以用 device='cpu' 在 CPU 上运行。发布的权重已经打包了骨干网络和文本编码器,推理时不需要登录获取受限的 DINOv3。
有什么限制——它能自己在照片里找到物体吗?不能——它本身不做目标检测:物体区域需要你用检测器、分割器提供,或者手动框出来,掩码是可选的。演示用的检测器需要在本地单独构建,并且有各自独立的许可证。
如果我用浏览器演示,我的图片会被传到服务器上吗?不会——演示通过 WebGPU 或 WASM 完全在你的设备上运行推理,图片不会离开你的设备。
代码和模型可以免费使用吗?可以免费使用,但有几个限制:代码采用 Apache-2.0 协议,但权重是 Meta DINOv3 的衍生品,RA-4M 标注数据受 Gemma 使用条款约束,演示用的检测器为 AGPL-3.0,且不包含在发布产物中。
必须要有 NVIDIA GPU 吗?不必须。CPU 推理开箱即用,笔记本可以本地跑 ONNX 或 OpenVINO 演示,支持图片或摄像头输入;浏览器演示则什么都不用装——走 NVIDIA GPU 加 TensorRT 这条路只是最快而已。
这里的“开放词表”是什么意思——我能搜索自己想查的关系吗?可以——关系短语由你在推理时提供,不需要重新训练。一个小型文本编码器会把它们各嵌入一次,逐帧推理时并不运行语言模型;另外还有一个更大的内置关系词表可用。
它实际跑起来有多快?在 RTX 3080 Laptop GPU 上,推荐的 ViT-S+ 模型用 TensorRT FP32 处理一张图只需 17.2 毫秒(含预处理);再加上 YOLO26m 检测后,整条流水线每张图约 36.5 毫秒。
有三个权重文件——我该选哪一个?从 relsgg-vits16plus(5320 万参数)开始,它是质量和速度的推荐平衡之选。relsgg-vits16(4610 万)和 relsgg-vitb16(1.138 亿)采用相同的训练配方,区别只在 DINOv3 ViT 骨干网络的大小。
和之前的开放词表关系模型相比怎么样?大幅领先:在 VG150 上 F1@50 达到 36.9,而 OvSGTR 只有 16.5;在 PSG 上是 34.7 对 13.5,在 IndoorVG 上是 37.8 对 20.2,且使用的是同一个评估器——而且与 OvSGTR 不同,RelateAnything 不接收任何物体标签。
Creator
Maelic
Size
27.5 MB
Stars
1.1K
Updated
CommitOct 12
Age
1mo
Commits · 90 Days