LLM-MGCL / README.md

fx2

a781cd1 verified 2 days ago

4.7 kB

license: mit
library_name: pytorch
pipeline_tag: graph-ml
datasets:
  - wzehui/Yelp-Multimodal-Recommendation
language:
  - en
tags:
  - POI
  - recommendation
  - recommender-system
  - GNN
  - graph-neural-network
  - LightGCN
  - contrastive-learning
  - yelp
  - arxiv:2608.16407

LLM-MGCL: Checkpoints

Trained checkpoints for LLM-MGCL, from the paper POI Recommendation with LLM-Augmented Multi-Graph Learning and Contrastive Alignment (Tamer, Höpken, Wang, 2026).

Code: GitHub

Model

LLM-MGCL extends LightGCN with two item-item views and aligns them with contrastive learning:

Graph	Edges	Edge weight
G_UI	user-item training interactions	star rating `(stars − 1) / 4`, clamped at 0.1
G_SEM	top-10 most similar items within 50 km	cosine similarity of LLM-generated photo summaries (`all-MiniLM-L6-v2`)
G_GEO	top-10 nearest items within 50 km	`1 / (1 + distance_km)` (Haversine)

The three graphs are propagated in parallel with LightGCN (3 / 2 / 2 layers) from shared 64-dimensional ego embeddings, and the item views are fused additively. Training uses BPR, L2 regularisation (1e-3) and a bidirectional InfoNCE loss between the collaborative view and the semantic and geographic views (λ = 0.05, τ = 0.2).

All models were trained with seeds 42, 123 and 2024, so there are 3 checkpoints per run.

Run	Description
LLM-MGCL	full model
LLM-MGCL w/o CL	ablation: λ = 0
LLM-MGCL w/o G_SEM	ablation: semantic view removed
LLM-MGCL w/o G_GEO	ablation: geographic view removed
LightGCN, SGL, NGCF, GC-MC, NeuMF, MF-BPR	baselines

ItemKNN and UserKNN have no weights. The code computes them deterministically.

Each .pt file is a dict containing model_state (a PyTorch state_dict), model_config and seed. These are raw PyTorch weights, not a transformers model. Load them with the model classes from the GitHub repository.

Usage

The checkpoints only work with the graphs and id mappings produced by the repository's preprocessing, because user and item indices must match. Build them first, then download the checkpoints and evaluate:

git clone <GITHUB-URL> && cd llm-mgcl
pip install -e .
python scripts/build_graphs.py                       # split, id mapping, G_UI / G_SEM / G_GEO

huggingface-cli download bbbur/LLM-MGCL --local-dir hf_checkpoints
python scripts/import_colab_checkpoints.py --src hf_checkpoints

python scripts/compare_models.py                     # Table 1, ablation, significance tests
python scripts/cold_start.py                         # cold-start analysis

Loading a single model in Python:

from huggingface_hub import hf_hub_download
import torch
from llm_mgcl.models import build_model
from llm_mgcl.pipeline import load_dataset
from llm_mgcl.utils import load_config, get_device

cfg, device = load_config("configs/default.yaml"), get_device()
ds = load_dataset(cfg, device)

path = hf_hub_download("bbbur/LLM-MGCL", "<path/to/llm_mgcl_geo_seed42.pt>")
model = build_model("llm_mgcl", ds.data.n_users, ds.data.n_items, cfg).to(device)
model.load_state_dict(torch.load(path, map_location=device, weights_only=False)["model_state"])
model.eval()

scores = model.scorer(ds.graphs)(torch.tensor([0], device=device))   # [1, n_items]

Training data

wzehui/Yelp-Multimodal-Recommendation. Users with fewer than 3 reviews are removed. Each user's interactions are split 80 / 10 / 10 into train / validation / test (random_state=42). The models were trained with Adam (lr 1e-3), StepLR (step 20, γ 0.5) and batch size 2048 for up to 100 epochs. Early stopping is based on validation Recall@20 (evaluated every 2 epochs, patience 8 evaluations).

Limitations

The models are transductive. They only score users and items seen during training, with the exact id mapping of the preprocessing.
They were trained and evaluated on Yelp only, and results may not transfer to other cities, platforms or domains.

Citation

@article{tamer2026llmmgcl,
  title         = {POI Recommendation with LLM-Augmented Multi-Graph Learning and Contrastive Alignment},
  author        = {Tamer, Burak and H{\"o}pken, Wolfram and Wang, Zehui},
  journal       = {arXiv preprint arXiv:2608.16407},
  year          = {2026},
  eprint        = {2608.16407},
  archivePrefix = {arXiv},
  primaryClass  = {cs.IR},
  url           = {https://arxiv.org/abs/2608.16407}
}

License

MIT. Use of the Yelp data is subject to Yelp's dataset terms.

bbbur
/

LLM-MGCL