README.md

---
license: mit
tags:
  - video-understanding
  - event-graph
  - vjepa
  - slot-attention
  - pytorch
  - set-prediction
  - hungarian-matching
library_name: pytorch
pipeline_tag: video-classification
---

# Event Graph Generation — ViT-B

## Model Overview

動画から構造化されたイベントグラフを予測するモデルです。動画中の「**誰が**・**何を**・**どこから**・**どこへ**」を構造化 JSON として出力します。

テキスト生成ではなく、DETR 風の**セット予測**（Hungarian Matching）により、イベントグラフを直接出力する設計です。

## Base Model

[V-JEPA 2.1](https://github.com/facebookresearch/vjepa) ViT-B (`vjepa2_1_vit_base_384`) を映像特徴抽出のバックボーンとして使用しています。V-JEPA は Meta が開発した自己教師あり映像表現学習モデルで、時空間トークンを出力します。

本モデル（Event Decoder 部分）は V-JEPA の出力トークンを入力とし、Object Pooling と Event Decoder の 2 段階でイベントグラフを予測します。V-JEPA 自体の重みは本チェックポイントに**含まれません**（別途 PyTorch Hub からロードされます）。

## Model Details

| 項目 | 値 |
|---|---|
| パラメータ数 (Event Decoder) | **14.9M** |
| V-JEPA backbone | `vjepa2_1_vit_base_384` |
| V-JEPA hidden_size | 768 |
| Object Pooling | Slot Attention (K=24 slots, 3 iterations) |
| Event Decoder | DETR 風 cross-attention (M=20 event queries) |
| d_model | 256 |
| Action classes | 13 |
| Best epoch | 20 |

### Architecture

```
Video → V-JEPA 2.1 ViT-B → spatiotemporal tokens (B, S, 768)
  → ObjectPoolingModule (Slot Attention, K=24 slots)
    → ObjectRepresentation (identity, trajectory, existence, categories)
      → VJEPAEventDecoder (M=20 event queries, cross-attention)
        → 7 Prediction Heads → EventGraph JSON
```

### Prediction Heads

| Head | Shape | Description |
|---|---|---|
| interaction | (M, 1) | イベントが有効か (BCE) |
| action | (M, 13) | アクション分類 (13 クラス) |
| agent_ptr | (M, K) | 行為者スロットへのポインタ |
| target_ptr | (M, K) | 対象スロットへのポインタ |
| source_ptr | (M, K+1) | 取り出し元へのポインタ (最後 = "none") |
| dest_ptr | (M, K+1) | 格納先へのポインタ (最後 = "none") |
| frame | (M, T) | イベント発生フレーム |

## Training

### Fine-tuning

- **ファインチューニング**: あり（V-JEPA backbone は frozen、Event Decoder 部分のみ学習）
- **学習手法**: Full fine-tuning（Event Decoder 全体を学習。LoRA 等は未使用）
- **Optimizer**: adamw (lr=0.0001, weight_decay=0.0001)
- **Scheduler**: cosine_warmup (warmup 5 epochs)
- **Early stopping**: patience=15
- **AMP**: bfloat16 mixed precision
- **損失関数**: Hungarian Matching によるセット予測損失

**Loss weights:**

| Component | Weight |
|---|---|
| interaction | 2.0 |
| action | 1.0 |
| agent_ptr | 1.0 |
| target_ptr | 1.0 |
| source_ptr | 0.5 |
| dest_ptr | 0.5 |
| frame | 0.5 |

### Training Data

- **データ**: 室内環境の録画動画（デスク・キッチン・部屋）
- **アノテーション**: Qwen 3.5 VLM による合成アノテーション（人手ラベルなし）
- **フレームレート**: 1 FPS でサンプリング、16 フレーム/クリップ、50% オーバーラップ
- **オブジェクトカテゴリ**: 28 カテゴリ + unknown（person, hand, chair, desk, laptop, monitor 等）
- **アクション語彙**: 13 クラス（take_out, put_in, place_on, pick_up, hand_over, open, close, use, move, attach, detach, inspect, no_event）

## Intended Use

### Intended Use Cases

- 製造・組立作業の動画からの作業イベント自動抽出
- 室内行動の構造的記録（誰が何をどこに置いたか等）
- 動画理解研究のための構造化アノテーション自動生成
- IoT / スマートホーム環境での行動ログ生成

### Out-of-Scope Use

- 個人の監視・追跡を目的とした利用
- 屋外・交通・医療など、学習データに含まれないドメインでの高精度な利用
- リアルタイム処理が必要なシステム（V-JEPA backbone の推論コストが高い）
- セキュリティ判断や法的判断の根拠としての利用

## Evaluation

本モデルは以下のメトリクスで評価されています:

| Metric | Description |
|---|---|
| event_detection_mAP | イベント検出の平均適合率 |
| action_accuracy | アクション分類精度 |
| pointer_accuracy | agent/target ポインタの正解率 |
| frame_mae | イベントフレーム予測の平均絶対誤差 |
| graph_f1 | EventGraph 全体の F1 スコア |

> **注意**: 本モデルは VLM 合成アノテーションで学習されており、人手アノテーションによるベンチマークスコアは未計測です。

## Inference

### End-to-End Inference (推奨)

```bash
# リポジトリをクローン
git clone https://github.com/ChanYu1224/event-graph-generation.git
cd event-graph-generation
uv sync

# 推論実行
uv run python scripts/6_run_inference.py \
  --video your_video.mp4 \
  --checkpoint path/to/model.pt \
  --config configs/vjepa_training.yaml \
  --vjepa-config configs/vjepa.yaml \
  --output output/event_graph.json
```

### Python API

```python
import torch
from huggingface_hub import hf_hub_download

# Download model
model_path = hf_hub_download(repo_id="Yuchn/event-graph-vitb", filename="model.pt")
config_path = hf_hub_download(repo_id="Yuchn/event-graph-vitb", filename="config.yaml")

# Build model
from event_graph_generation.config import Config
from event_graph_generation.models.base import build_model

config = Config.from_yaml(config_path)
model = build_model(config.model, vjepa_config=config.vjepa)

state_dict = torch.load(model_path, map_location="cpu")
model.load_state_dict(state_dict)
model.eval()

# Forward pass (vjepa_tokens: pre-extracted V-JEPA features)
# vjepa_tokens shape: (batch_size, num_tokens, hidden_size)
with torch.no_grad():
    obj_repr, predictions = model(vjepa_tokens)
```

## Limitations

### Bias

- 学習データは室内環境（デスク・キッチン・部屋）に限定されており、屋外や工場環境での精度は未検証
- VLM 合成アノテーションに依存しているため、Qwen 3.5 のバイアスを継承する可能性がある
- オブジェクトカテゴリは 28 種類に限定されており、未知カテゴリのオブジェクトは "unknown" として扱われる

### Limitations

- V-JEPA backbone は frozen のため、ドメイン固有の映像表現への適応は限定的
- 13 種類のアクション語彙に限定されており、語彙外の行動は検出できない
- 1 FPS サンプリングのため、1 秒未満の高速なイベントは見逃す可能性がある
- 推論には CUDA 対応 GPU が必要（V-JEPA backbone + Event Decoder）
- 長時間動画ではスライディングウィンドウ処理のため、メモリ使用量と処理時間が線形に増加

## License

MIT License

## Citation

```bibtex
@software{event_graph_generation_2026,
  title = {Event Graph Generation: Structured Event Prediction from Video},
  author = {Yuchn},
  year = {2026},
  url = {https://github.com/ChanYu1224/event-graph-generation},
  license = {MIT}
}
```

## Links

- **Repository**: [ChanYu1224/event-graph-generation](https://github.com/ChanYu1224/event-graph-generation)
- **V-JEPA**: [facebookresearch/vjepa](https://github.com/facebookresearch/vjepa)