验证核心假设：用户评分归一化（考虑用户打分倾向）能显著提升推荐效果

大家都把评分当做黄金标准，难道评分一定是正确的吗？

• 评论文本释放的信息是否更加丰富有参考性？
• 不同用户打分倾向不同，使用原始评分训练是否会引入干扰？
• 用户侧评分归一化（只考虑相对顺序）效果是否更好？

本项目从零实现完整的推荐系统实验框架，系统性验证5种评分归一化方法在9种推荐算法上的效果。

• ✅ 完整算法实现：9个主流推荐算法从头编写
• ✅ 多种归一化策略：原始评分、用户均值、Z-score、排序归一化、二值化
• ✅ 全面评估体系：Rating指标（RMSE/MAE）+ Ranking指标（HR/NDCG/MRR）
• ✅ 可复现性保证：固定随机种子、检查点机制、实验日志
• ✅ 中断恢复：自动保存/加载检查点

recsys_2026/
├── data/
│   ├── raw/              # 原始Yelp数据集（不上传GitHub）
│   ├── sampled/          # 固化的采样数据
│   └── splits/           # 训练/验证/测试集
├── src/
│   ├── data/             # 数据预处理
│   ├── models/           # 9个算法实现
│   │   ├── rating_based/     # SVD++, BiasedMF, PMF
│   │   ├── ranking_based/    # BPR, LightGCN, SGL, NESCL
│   │   └── similarity_based/ # ItemKNN, SLIM
│   ├── evaluation/       # 评估指标
│   ├── normalization/    # 5种归一化方法
│   ├── experiments/      # 实验管理
│   └── utils/            # 工具函数
├── configs/              # 实验配置文件
├── logs/                 # 训练日志
├── checkpoints/          # 模型检查点
├── results/              # 实验结果
├── docs/                 # 文档
└── scripts/              # 批量执行脚本

# Clone repository
git clone https://github.com/PeiJieSun/recsys_2026.git
cd recsys_2026

# Install dependencies
pip install -r requirements.txt

# 下载Yelp数据集到 data/raw/
# 预处理并采样数据（10万条）
python src/data/preprocessor.py --config configs/data_prep.yaml --sample_size 100000

# 运行单个实验：SVD++ + 无归一化
python src/experiments/train.py --config configs/svdpp_none.yaml

# 批量运行45个实验（9算法 × 5归一化）
bash scripts/run_all_experiments.sh

# 生成实验报告
python src/experiments/summarize_results.py --output results/summary.md

1. SVD++: Enhanced SVD with implicit feedback
2. BiasedMF: Matrix Factorization with user/item biases
3. PMF: Probabilistic Matrix Factorization

4. BPR: Bayesian Personalized Ranking
5. LightGCN: Simplified Graph Convolutional Networks
6. SGL: Self-supervised Graph Learning
7. NESCL: Neighborhood-Enhanced Supervised Contrastive Learning

8. ItemKNN: Item-based Collaborative Filtering
9. SLIM: Sparse Linear Methods

1. None: 原始评分（baseline）
2. UserMean: $r'{ui} = r{ui} - \bar{r}_u$
3. UserZScore: $(r_{ui} - \bar{r}_u) / \sigma_u$
4. UserRanking: 保留用户内相对顺序，映射到[0,1]
5. Binarize: rating≤3→0, rating>3→1

• RMSE (Root Mean Squared Error)
• MAE (Mean Absolute Error)

• HR@K (Hit Rate at K)
• NDCG@K (Normalized Discounted Cumulative Gain)
• MRR (Mean Reciprocal Rank)
• Precision@K, Recall@K

K ∈ {5, 10, 20}

• 实验组合: 9个算法 × 5种归一化 = 45个实验
• 对比维度: 归一化效果、算法鲁棒性、数据规模影响

1. 假设1: 用户评分归一化能提升效果
2. 假设2: 用户内部相对顺序比绝对评分更重要
3. 假设3: 二值化（隐式反馈）更适合ranking任务

• 数据采样: seed=2026
• 数据划分: seed=2027
• 模型初始化: seed=2028
• 负采样: seed=2029

• Git commit hash记录
• 环境信息保存
• 数据MD5校验

• 每5个epoch保存检查点
• 自动恢复训练进度
• 保存模型、优化器、随机数状态

experiment:
  name: "svdpp_user_mean"
  seed: 2026
  
data:
  sample_size: 100000
  split_ratio: [0.6, 0.2, 0.2]
  min_user_reviews: 5
  min_item_reviews: 5
  
normalization:
  method: "user_mean"
  
model:
  name: "svdpp"
  params:
    factors: 64
    learning_rate: 0.005
    regularization: 0.02
    epochs: 20
    batch_size: 1024
    
evaluation:
  rating_metrics: ["rmse", "mae"]
  ranking_metrics: ["hr@10", "ndcg@10", "mrr"]
  negative_samples: 99

预期实验结果将展示：

1. 用户归一化方法（UserMean/UserZScore）相比原始评分能提升2-5%
2. Ranking算法对归一化更敏感
3. UserRanking方法在ranking指标上表现最佳
4. 二值化在BPR/LightGCN等ranking模型上效果显著

# src/models/rating_based/your_model.py
from src.models.base import BaseModel

class YourModel(BaseModel):
    def __init__(self, n_users, n_items, **params):
        super().__init__(n_users, n_items)
        # Initialize parameters
        
    def fit(self, train_data):
        # Training logic
        pass
        
    def predict(self, user_ids, item_ids):
        # Prediction logic
        return predictions

# src/normalization/your_method.py
from src.normalization.base import BaseNormalizer

class YourNormalizer(BaseNormalizer):
    def normalize(self, ratings, user_ids):
        # Normalization logic
        return normalized_ratings
        
    def denormalize(self, norm_ratings, user_ids):
        # Denormalization logic
        return original_ratings

• 算法实现细节
• 数据处理流程
• 实验配置指南
• 评估指标说明

本项目用于学术研究，欢迎提出问题和建议。

MIT License - 仅供学术研究使用

• Author: Peijie Sun
• GitHub: @PeiJieSun
• Email: [Your Email]

如果本项目对您的研究有帮助，请引用：

@inproceedings{sun2026rating,
  title={RatingAlign: Style-Aware Rating Calibration with Large Language Models for Recommendation},
  author={Sun, Peijie and others},
  booktitle={RecSys},
  year={2026}
}

• Week 1: Project structure and data pipeline
• Week 2: Algorithm implementation (9 models)
• Week 3: Run all experiments
• Week 4: Analysis and paper writing

Last Updated: 2025-11-22
Status: Phase 1 - Repository Setup Complete ✅