How hkuds/xrec works
Project type and purpose
• This is a research‐oriented machine‐learning pipeline for explainable recommendation (XRec). It integrates a graph‐based collaborative filtering encoder (GNN) with a large language model (LLM) explainer to generate human‐readable explanations for user–item recommendations.
Key architectural layers (top‐level directories)
• data: raw and preprocessed datasets (Amazon, Google, Yelp)
• process: data‐preprocessing & splitting
• generation: OpenAI API calls to generate user profiles, item profiles, and ground‐truth explanations
• encoder: GNN model (LightGCN) training to produce user/item embeddings and MoE adapter
• explainer: LLaMA‐based fine‐tuning & inference for explanation generation
• evaluation: metrics computation and system prompts for evaluation
Main components and their responsibilities
a. Data Ingestion & Storage
• Raw CSV/JSON files under data/<dataset>
• Pickles for embeddings, converters, and train/val/test splits
b. Preprocessing Pipeline (process/)
• data.py, interaction.py, metadata.py, para_dict.py, separate.py
• Cleans raw data, generates interaction matrices, profile dictionaries, and splits into trn/val/tst
c. Profile & Explanation Generation (generation/)
• Three sub‐modules for item_profile, user_profile, explanation
• Each uses OpenAI API with system & user prompts to produce profiles/explanations
• Outputs JSON and pickles under data/<dataset>
d. Collaborative Filtering Encoder (encoder/)
• models/lightgcn.py: LightGCN architecture
• train_encoder.py: trains GNN on processed interactions, outputs embeddings & MoE adapter pickles
• utils: data loading, loss, metrics, parsing
e. LLM Explainer (explainer/)
• modeling_explainer.py: wraps a modified LLaMA model with MoE adapter integration
• explainer.py: defines the XRec model architecture
• main.py: orchestrates finetuning (“--mode finetune”) and generation (“--mode generate”)
• sample.py: prints sample explanations
f. Evaluation Module (evaluation/)
• main.py: runs evaluation over generated explanations vs. ground truth
• metrics.py: computes BLEU, ROUGE, GPTScore, etc.
• system_prompt.txt: prompt for GPTScore
External dependencies & services
• OpenAI API (for generation phase)
• Hugging Face Hub (to download Llama 2 weights)
• PyTorch & Transformers
Relationships & data flow
1. Raw Data → process/ → processed interactions & metadata
2. Processed Data → generation/ → user_profile.json, item_profile.json, explanation.json
3. Processed Interactions → encoder/ → user_emb.pkl, item_emb.pkl, adapter.pkl
4. {user_profile.json, item_profile.json, user_emb.pkl, item_emb.pkl, adapter.pkl} → explainer/
→ finetune or generate explanations
5. Generated explanations + ground truth → evaluation/ → metrics report
Architectural patterns & principles
• Modular pipeline: clear separation between data prep, profile generation, embedding training, language generation, and evaluation
• Model‐agnostic adapter (Mixture-of‐Experts) connecting collaborative signals to LLM
• Micro‐batching of workloads: each directory can run independently
• Use of standardized pickles/JSON for interchange formats