SCPA: Semantic Codebook-Centric Popularity-Aware Multi-modal Feature Enhancement Framework

This repository contains the official PyTorch implementation of the SCPA framework.

SCPA is a model-agnostic, plug-and-play multi-modal feature enhancement framework designed for Click-Through Rate (CTR) prediction. It addresses the granularity mismatch between fine-grained raw modalities (e.g., pixel-level images, text tokens) and abstract ID features, while effectively mitigating the noise issues often encountered in long-tail item recommendation.

🌟 Core Features

Based on the implementation in models/SCPA.py, this framework includes four key components:

1. Semantic Codebook (RVQ-based)

• Utilizes Residual Vector Quantization (RVQ) to generate discretized, coarse-grained semantic representations.
• Acts as a semantic bridge to connect low-level raw features with high-level collaborative IDs.

2. Popularity-Aware Dynamic Sparse Masking

• Dynamically estimates item popularity using the L2 norm of ID embeddings.
• Generates adaptive thresholds to mask redundant codebook features: applying stricter noise filtering for long-tail items while retaining more details for popular items.

3. Bidirectional Semantic-Collaborative Alignment

• Enforces geometric consistency between the Semantic Codebook and ID Embeddings.
• Incorporates a Popularity Gating mechanism to ensure alignment is performed only when collaborative signals are reliable.

4. Adaptive Fusion

• A Popularity-based Controller dynamically calculates fusion weights for three feature granularities:

• Raw Modality: Fine-grained details (Image/Text).

• Collaborative ID: Specific item identity.

• Semantic Codebook: General semantic categories.

• Automatically shifts focus to general semantics for tail items and precise details for head items.

📂 Data Preparation

Please ensure your dataset directory is structured as follows (using Amazon Clothing as an example):

data/
  Ama/
    clothing/
      codebook_text.pt       # Pre-trained Text Codebook (RVQ)
      codebook_image.pt      # Pre-trained Image Codebook (RVQ)
      train.txt
      test.txt
      ...
    home/
      ...

The code is designed to automatically load the corresponding codebook files based on the dataset path provided.

🧠 Code Structure

• models/SCPA.py: The core model implementation.

• class SCPA: The main framework class.

• adaptive_fusion(): Implements the popularity calculation, dynamic masking, and tri-party weighted fusion logic.

• SRCModule: A diffusion-based auxiliary module for representation consistency.

• run.py: The entry point for training and evaluation.

• basic/: Contains basic layer definitions (e.g., EmbeddingLayer, MLP).

🚀 Usage

We provide training scripts for Amazon Benchmark datasets.

Navigate to the code directory:

cd code

1. Run on Amazon Clothing

python3 run.py --dataset_path ../data/Ama/clothing/ --learning_rate 5e-4 --epoch 20

2. Run on Amazon Home

python3 run.py --dataset_path ../data/Ama/home/ --learning_rate 5e-4 --epoch 20

3. Run on Amazon Arts

python3 run.py --dataset_path ../data/Ama/arts/ --learning_rate 5e-4 --epoch 20