| --- |
| 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*](https://arxiv.org/abs/2608.16407) |
| (Tamer, Höpken, Wang, 2026). |
|
|
| Code: **[GitHub](https://github.com/wwebpy/LLM-MGCL)** |
|
|
| ## 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). |
| |
| ## Contents |
| |
| 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: |
| |
| ```bash |
| 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: |
| |
| ```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](https://huggingface.co/datasets/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 |
| |
| ```bibtex |
| @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. |
