### Setup Development Environment

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/community/contributing.md

Steps to fork, clone, install dependencies, and set up the project in development mode.

```bash
# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/torch-rechub.git
cd torch-rechub

# 2. Install dependencies and set up environment
uv sync

# 3. Install package in development mode
uv pip install -e .
```

--------------------------------

### Full Example with Multiple Loggers

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/zh/tools/tracking.md

An end-to-end example showcasing the setup of multiple loggers (TensorBoardX, Wandb) and their integration with CTRTrainer.

```APIDOC
## Full Example

```python
import os
import torch
from torch_rechub.models.ranking import DeepFM
from torch_rechub.trainers import CTRTrainer
from torch_rechub.basic.tracking import WandbLogger, SwanLabLogger, TensorBoardXLogger

# Set API keys (optional, can also log in via CLI)
os.environ['WANDB_API_KEY'] = "your_key"
os.environ['SWANLAB_API_KEY'] = "your_key"

# Configuration
SEED = 2022
EPOCH = 10
LR = 1e-3
BATCH_SIZE = 2048

# Initialize loggers (can select multiple)
loggers = []

# Local TensorBoard logging
loggers.append(TensorBoardXLogger(log_dir=f"./runs/deepfm-{SEED}"))

# Cloud WandB logging
loggers.append(WandbLogger(
    project="ctr-experiment",
    name=f"deepfm-{SEED}",
    config={"seed": SEED, "lr": LR, "batch_size": BATCH_SIZE},
    tags=["deepfm", "criteo"]
))

# Instantiate model and trainer
model = DeepFM(...)
# Pass the list of loggers to the trainer
trainer = CTRTrainer(model, n_epoch=EPOCH, optimizer_params={"lr": LR}, model_logger=loggers)

# Dummy data loaders for demonstration
train_dl = [...] 
val_dl = [...] 

trainer.fit(train_dl, val_dl)
```
```

--------------------------------

### Development Setup Commands

Source: https://github.com/datawhalechina/torch-rechub/blob/main/CONTRIBUTING.md

Commands to fork, clone, install dependencies, and set up the project in development mode.

```bash
git clone https://github.com/YOUR_USERNAME/torch-rechub.git
cd torch-rechub

uv sync

uv pip install -e .
```

--------------------------------

### Quick Start with CTRTrainer

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/zh/tools/tracking.md

A basic example demonstrating how to integrate a logger with the CTRTrainer.

```APIDOC
## Quick Start

```python
from torch_rechub.trainers import CTRTrainer
from torch_rechub.basic.tracking import WandbLogger

# Initialize a logger (optional)
logger = WandbLogger(project="my-ctr", name="exp1")  # Pass None to disable logging

trainer = CTRTrainer(
    model,
    optimizer_params={"lr": 1e-3},
    n_epoch=10,
    model_logger=logger,   # Pass the logger instance here
)

trainer.fit(train_dl, val_dl)
# The logger is automatically closed after fit() completes.
```
```

--------------------------------

### Quick Start: Train Ranking Model

Source: https://github.com/datawhalechina/torch-rechub/blob/main/README.md

Navigate to the ranking examples directory and run the Criteo dataset training script.

```bash
# Run ranking example
cd ../ranking
python run_criteo.py
```

--------------------------------

### Quick Start Visualization

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/tools/visualization.md

A quick example of how to visualize a model and save the output.

```APIDOC
## Quick Start

```python
from torch_rechub.models.ranking import DeepFM
from torch_rechub.utils.visualization import visualize_model

# Create model
model = DeepFM(
    deep_features=deep_features,
    fm_features=fm_features,
    mlp_params={"dims": [256, 128], "dropout": 0.2}
)

# Visualize (auto-display in Jupyter)
graph = visualize_model(model, depth=4)

# Save as PDF
visualize_model(model, save_path="model_arch.pdf", dpi=300)
```
```

--------------------------------

### Setup Development Environment for Torch-RecHub

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/install.md

Sets up the development environment by cloning the repository, installing dependencies with uv, and installing the package in editable mode.

```bash
git clone https://github.com/YOUR_USERNAME/torch-rechub.git
cd torch-rechub
uv sync
uv pip install -e .
```

--------------------------------

### Experiment Tracking Setup

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/tools/tracking.md

This section covers the installation of tracking dependencies and the basic setup for using experiment loggers with Torch-RecHub trainers.

```APIDOC
## Installation

```bash
# Install all tracking dependencies
pip install torch-rechub[tracking]

# Or install individually
pip install wandb
pip install swanlab
pip install tensorboardX
```

## Quickstart with a Single Logger

This example demonstrates how to initialize a `WandbLogger` and pass it to the `CTRTrainer`.

```python
from torch_rechub.trainers import CTRTrainer
from torch_rechub.basic.tracking import WandbLogger

# Initialize logger
logger = WandbLogger(project="my-ctr", name="exp1")  # Optional parameters

# Initialize trainer with the logger
trainer = CTRTrainer(
    model,
    optimizer_params={"lr": 1e-3},
    n_epoch=10,
    model_logger=logger,   # Pass the logger instance here
)

trainer.fit(train_dl, val_dl)
# The logger is automatically closed after fit() completes.
```

## Using Multiple Loggers

You can pass a list of logger instances to the `model_logger` argument to use multiple tracking services simultaneously.

```python
from torch_rechub.basic.tracking import TensorBoardXLogger, WandbLogger, SwanLabLogger

# Initialize different loggers
tb_logger = TensorBoardXLogger(log_dir="./runs/exp1")
wb_logger = WandbLogger(project="my-ctr", name="exp1")
sb_logger = SwanLabLogger(project="my-ctr")

# Pass a list of loggers to the trainer
trainer = CTRTrainer(model, model_logger=[tb_logger, wb_logger, sb_logger])
```

## Setting API Keys

API keys for services like Weights & Biases and SwanLab can be set as environment variables.

```python
import os
os.environ['WANDB_API_KEY'] = "your_wandb_api_key"
os.environ['SWANLAB_API_KEY'] = "your_swanlab_api_key"
```

## Overhead When Disabled

When `model_logger` is set to `None`, the training process runs without any tracking overhead.

```python
trainer = CTRTrainer(model, model_logger=None)
```
```

--------------------------------

### Quick Start: Train DSSM Model on MovieLens

Source: https://github.com/datawhalechina/torch-rechub/blob/main/README.md

Clone the repository, sync dependencies, and run the DSSM model training example for the MovieLens dataset.

```bash
# Clone the repository (if using latest version)
git clone https://github.com/datawhalechina/torch-rechub.git
cd torch-rechub
uv sync

# Run matching example (cd into the script directory first, as scripts use relative data paths)
cd examples/matching
python run_ml_dssm.py
```

--------------------------------

### Complete DSSM Training Example

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/models/matching.md

A full example demonstrating feature definition, data preparation with MatchDataGenerator, model initialization, trainer setup, and model training for DSSM.

```python
from torch_rechub.models.matching import DSSM
from torch_rechub.trainers import MatchTrainer
from torch_rechub.utils.data import MatchDataGenerator
from torch_rechub.basic.features import SparseFeature, DenseFeature

# 1. Define features
user_features = [
    SparseFeature(name="user_id", vocab_size=10000, embed_dim=32),
    DenseFeature(name="age", embed_dim=1),
    SparseFeature(name="gender", vocab_size=3, embed_dim=8)
]

item_features = [
    SparseFeature(name="item_id", vocab_size=100000, embed_dim=32),
    SparseFeature(name="category", vocab_size=1000, embed_dim=16)
]

# 2. Prepare data
# Assume x and y are preprocessed feature and label data
# x contains user features and item features
x = {
    "user_id": user_id_data,
    "age": age_data,
    "gender": gender_data,
    "item_id": item_id_data,
    "category": category_data
}
y = label_data  # click/no-click labels

# Test user data and all item data
x_test_user = {
    "user_id": test_user_id_data,
    "age": test_age_data,
    "gender": test_gender_data
}
x_all_item = {
    "item_id": all_item_id_data,
    "category": all_item_category_data
}

# 3. Create data generator
dg = MatchDataGenerator(x, y)
train_dl, test_dl, item_dl = dg.generate_dataloader(
    x_test_user=x_test_user,
    x_all_item=x_all_item,
    batch_size=256,
    num_workers=8
)

# 4. Create model
model = DSSM(
    user_features=user_features,
    item_features=item_features,
    temperature=0.02,
    user_params={"dims": [256, 128, 64], "activation": "prelu"},
    item_params={"dims": [256, 128, 64], "activation": "prelu"}
)

# 5. Create trainer
trainer = MatchTrainer(
    model=model,
    mode=0,  # 0: point-wise, 1: pair-wise, 2: list-wise
    optimizer_params={"lr": 0.001, "weight_decay": 0.0001},
    n_epoch=50,
    earlystop_patience=10,
    device="cuda:0",
    model_path="saved/dssm"
)

# 6. Train model
trainer.fit(train_dl, test_dl)

# 7. Export ONNX model

```

--------------------------------

### Complete Example: Manual vs. Trainer Early Stopping

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/tools/callbacks.md

Demonstrates both manual EarlyStopper integration and the CTRTrainer's built-in early stopping for comparison. Ensure necessary imports and model/dataloader setup.

```python
import torch
from torch_rechub.models.ranking import DeepFM
from torch_rechub.trainers import CTRTrainer
from torch_rechub.basic.callback import EarlyStopper

# Create model
model = DeepFM(
    deep_features=deep_features,
    fm_features=fm_features,
    mlp_params={"dims": [256, 128], "dropout": 0.2}
)

# Method 1: Use Trainer's built-in early stopping
trainer = CTRTrainer(
    model=model,
    optimizer_params={"lr": 0.001, "weight_decay": 1e-5},
    n_epoch=50,
    earlystop_patience=10,
    device="cuda:0"
)
trainer.fit(train_dl, val_dl)

# Method 2: Manual EarlyStopper usage
early_stopper = EarlyStopper(patience=10)
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)

for epoch in range(50):
    model.train()
    for batch in train_dl:
        # Training step
        optimizer.zero_grad()
        loss = model(batch)
        loss.backward()
        optimizer.step()

    # Validation
    model.eval()
    val_auc = evaluate(model, val_dl)
    print(f"Epoch {epoch}, Val AUC: {val_auc:.4f}")

    # Early stopping check
    if early_stopper.stop_training(val_auc, model.state_dict()):
        print(f"Early stopping! Best AUC: {early_stopper.best_auc:.4f}")
        model.load_state_dict(early_stopper.best_weights)
        break
```

--------------------------------

### Installation

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/zh/tools/tracking.md

Instructions for installing the necessary packages for experiment tracking.

```APIDOC
## Installation

```bash
# Install all tracking dependencies
pip install torch-rechub[tracking]

# Or install specific backends
pip install wandb
pip install swanlab
pip install tensorboardX
```
```

--------------------------------

### Verify Environment with a Minimal Command

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/quick_start.md

A command-line example to quickly verify your torch-rechub environment setup by running a small training job on the Criteo dataset.

```bash
cd examples/ranking
python run_criteo.py --model_name deepfm --epoch 1 --device cuda:0
```

--------------------------------

### Multi-Task Learning Trainer (MTLTrainer) Example

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/core/evaluation.md

Demonstrates how to initialize and use the MTLTrainer for multi-task models like MMoE. It includes model definition, trainer setup with adaptive loss weighting, and training execution.

```python
from torch_rechub.trainers import MTLTrainer
from torch_rechub.models.multi_task import MMOE

model = MMOE(
    features=features,
    task_types=["classification", "classification"],
    n_expert=8,
    expert_params={"dims": [32,16]},
    tower_params_list=[{"dims": [32, 16]}, {"dims": [32, 16]}]
)

trainer = MTLTrainer(
    model=model,
    task_types=["classification", "classification"],
    optimizer_params={"lr": 0.001},
    adaptive_params={"method": "uwl"},
    n_epoch=50,
    earlystop_taskid=0,
    device="cuda:0",
    model_path="saved/mmoe"
)

trainer.fit(train_dataloader, val_dataloader)
trainer.export_onnx("mmoe.onnx")
```

--------------------------------

### Execute Example Script

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/quick_start.md

Command to run the example script directly from the command line, allowing for epoch and device configuration.

```bash
cd examples/matching
python run_ml_dssm.py --epoch 2 --device cuda:0
```

--------------------------------

### Install Milvus Client

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/serving/vector_index.md

Install the Python client library for Milvus.

```bash
pip install pymilvus
```

--------------------------------

### Complete DeepFM Training Example

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/models/ranking.md

Demonstrates the end-to-end process of defining features, preparing data, creating a data generator, initializing a DeepFM model, setting up a CTR trainer, training the model, evaluating its performance, and exporting it to ONNX format. Requires PyTorch and Torch-Rechub installed.

```python
from torch_rechub.models.ranking import DeepFM
from torch_rechub.trainers import CTRTrainer
from torch_rechub.utils.data import DataGenerator
from torch_rechub.basic.features import DenseFeature, SparseFeature

# 1. Define features
dense_features = [
    DenseFeature(name="age", embed_dim=1),
    DenseFeature(name="income", embed_dim=1)
]

sparse_features = [
    SparseFeature(name="city", vocab_size=100, embed_dim=16),
    SparseFeature(name="gender", vocab_size=3, embed_dim=8),
    SparseFeature(name="occupation", vocab_size=20, embed_dim=12)
]

# 2. Prepare data
x = {
    "age": age_data,
    "income": income_data,
    "city": city_data,
    "gender": gender_data,
    "occupation": occupation_data
}
y = label_data

# 3. Create data generator
dg = DataGenerator(x, y)
train_dl, val_dl, test_dl = dg.generate_dataloader(split_ratio=[0.7, 0.1], batch_size=256)

# 4. Create model
model = DeepFM(
    deep_features=sparse_features + dense_features,
    fm_features=sparse_features,
    mlp_params={"dims": [256, 128, 64], "dropout": 0.2, "activation": "relu"}
)

# 5. Create trainer
trainer = CTRTrainer(
    model=model,
    optimizer_params={"lr": 0.001, "weight_decay": 0.0001},
    n_epoch=50,
    earlystop_patience=10,
    device="cuda:0",
    model_path="saved/deepfm"
)

# 6. Train model
trainer.fit(train_dl, val_dl)

# 7. Evaluate model
auc = trainer.evaluate(trainer.model, test_dl)
print(f"Test AUC: {auc}")

# 8. Export ONNX model
trainer.export_onnx("deepfm.onnx")
```

--------------------------------

### NCELoss Example

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/api/api.md

Provides an example of initializing and using the NCELoss. It demonstrates creating an instance with a specified temperature and then computing the loss using logits and targets.

```python
>>> nce_loss = NCELoss(temperature=0.1)
>>> logits = torch.randn(32, 1000)
>>> targets = torch.randint(0, 1000, (32,))
>>> loss = nce_loss(logits, targets)
```

--------------------------------

### Install Optional Tracking Dependencies

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/04_Experiment_Tracking_Light.ipynb

Install the necessary libraries for your chosen experiment tracking platform (WandB, SwanLab, or TensorBoardX). Install only one based on your needs.

```bash
pip install wandb
pip install swanlab
pip install tensorboardX
```

--------------------------------

### Training a DSSM Model with MatchTrainer

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/core/evaluation.md

Initialize and train a DSSM model for matching tasks using MatchTrainer. This example demonstrates model configuration, trainer setup with different modes (point-wise, pair-wise, list-wise), and exporting ONNX models for user and item towers.

```python
from torch_rechub.trainers import MatchTrainer
from torch_rechub.models.matching import DSSM

model = DSSM(
    user_features=user_features,
    item_features=item_features,
    temperature=0.02,
    user_params={"dims": [256, 128, 64]},
    item_params={"dims": [256, 128, 64]}
)

trainer = MatchTrainer(
    model=model,
    mode=0,  # 0: point-wise, 1: pair-wise, 2: list-wise
    optimizer_params={"lr": 0.001},
    n_epoch=50,
    device="cuda:0",
    model_path="saved/dssm"
)

trainer.fit(train_dataloader)
trainer.export_onnx("user_tower.onnx", mode="user")
trainer.export_onnx("item_tower.onnx", mode="item")
```

--------------------------------

### Install Torch-RecHub

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/community/faq.md

Install or upgrade the Torch-RecHub library after ensuring Annoy is installed.

```bash
pip install --upgrade torch-rechub
```

--------------------------------

### Install PyTorch for CPU

Source: https://github.com/datawhalechina/torch-rechub/blob/main/README.md

Install the CPU-only version of PyTorch.

```bash
pip install torch
```

--------------------------------

### Install Torch-RecHub

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/quick_start.md

Install the core PyTorch-RecHub library. For optional features like ONNX export or experiment tracking, install with extras.

```bash
pip install torch         # Install the PyTorch build for your device first; see the installation guide for CUDA/ROCm/NPU
pip install torch-rechub
```

```bash
pip install "torch-rechub[all]"
```

--------------------------------

### Install ONNX for Export

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/05_Model_Export_and_Serving.ipynb

Install the ONNX library to enable model export functionality.

```bash
pip install onnx
```

--------------------------------

### Install uv and Torch-Rechub (Latest Version)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/README.md

Install the latest version of Torch-Rechub using uv for faster dependency management. Includes cloning the repository and installing PyTorch variants.

```bash
# Install uv first (if not already installed)
pip install uv

# Clone and install
git clone https://github.com/datawhalechina/torch-rechub.git
cd torch-rechub

# Install one PyTorch build matching your device
uv pip install torch                                                     # CPU
uv pip install torch --index-url https://download.pytorch.org/whl/cu121  # NVIDIA GPU (CUDA 12.1)
uv pip install torch torch-npu                                           # Huawei Ascend NPU (requires torch-npu >= 2.5.1)
uv pip install --index-url https://repo.amd.com/rocm/whl/gfx1151/ "rocm[libraries,devel]" torch torchvision torchaudio  # AMD GPU (ROCm, gfx1151 = Ryzen AI Max+ 395/390/385)

uv sync
```

--------------------------------

### Install Torch-RecHub with Tracking Dependencies

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/tools/tracking.md

Install the full tracking suite or individual libraries for experiment logging.

```bash
pip install torch-rechub[tracking]

# or individually
pip install wandb
pip install swanlab
pip install tensorboardX
```

--------------------------------

### Start Milvus Standalone with Docker

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/serving/vector_index.md

Quickly start a Milvus standalone service using Docker for local development and testing.

```bash
docker run -d --name milvus-standalone -p 19530:19530 milvusdb/milvus:latest
```

--------------------------------

### Install PyArrow for Parquet Support

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/core/data.md

Install the pyarrow library, which is required for Parquet data loading.

```bash
pip install pyarrow
```

--------------------------------

### Install ONNXRuntime for Inference and Quantization

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/05_Model_Export_and_Serving.ipynb

Install ONNXRuntime to perform inference with exported ONNX models and to enable INT8 dynamic quantization.

```bash
pip install onnxruntime
```

--------------------------------

### Install Annoy (Online - Windows)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/community/faq.md

Use this command for online installation of the Annoy library on Windows. Ensure a C++ compilation environment is available.

```bash
pip install annoy
```

--------------------------------

### Install Torch-Rechub and Import Libraries

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/group_learning/DIN.ipynb

Installs the torch-rechub library and imports necessary modules for the tutorial. It also sets a manual seed for PyTorch for reproducibility and prints version information.

```python
# If you haven't installed it yet, uncomment and run the following command
# !pip install torch-rechub

import torch
import pandas as pd
from torch_rechub.models.ranking import DIN
from torch_rechub.trainers import CTRTrainer
from torch_rechub.basic.features import SparseFeature, SequenceFeature
from torch_rechub.utils.data import create_seq_features, df_to_dict, DataGenerator

# Fix the random seed for reproducibility
torch.manual_seed(2024)

# Check PyTorch version and CUDA availability
print(f"PyTorch Version: {torch.__version__}, CUDA Available: {torch.cuda.is_available()}")
```

--------------------------------

### MTLTrainer Visualization Examples

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/api/api.md

Examples demonstrating how to use the visualization method of MTLTrainer. This includes auto-display in Jupyter notebooks and saving high-DPI images for publications.

```python
>>> trainer = MTLTrainer(model, task_types=["classification", "classification"])
>>> trainer.fit(train_dl, val_dl)
>>>
>>> # Auto-display in Jupyter (no save_path needed)
>>> trainer.visualization(depth=4)
>>>
>>> # Save to high-DPI PNG for papers
>>> trainer.visualization(save_path="model.png", dpi=300)
```

--------------------------------

### Check PyTorch Installation and GPU Availability

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/DIN.ipynb

Verify the installed PyTorch version and check if a GPU is available for accelerated computation. Imports necessary libraries for the tutorial.

```python
# 检查torch的安装以及gpu的使用
import torch
print(torch.__version__, torch.cuda.is_available())

import torch_rechub
import pandas as pd
import numpy as np
import tqdm
import sklearn

torch.manual_seed(2022) #固定随机种子
```

--------------------------------

### Import Libraries and Setup

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/01_Ranking_DIN.ipynb

Imports necessary libraries and sets up project paths, random seed, and device for training.

```python
import os
from pathlib import Path
import numpy as np
import pandas as pd
import torch

from torch_rechub.basic.features import SparseFeature, SequenceFeature
from torch_rechub.models.ranking import DIN
from torch_rechub.trainers import CTRTrainer
from torch_rechub.utils.data import DataGenerator, create_seq_features, df_to_dict

# 可选：实验跟踪（默认关闭）
# from torch_rechub.basic.tracking import WandbLogger, SwanLabLogger, TensorBoardXLogger

SEED = 2022
DEVICE = "cpu"  # 可改为 "cuda:0"

PROJECT_ROOT = Path.cwd() if (Path.cwd() / "examples").exists() else Path.cwd().parent
DATASET_PATH = PROJECT_ROOT / "examples/ranking/data/amazon-electronics/amazon_electronics_sample.csv"

SEQ_MAX_LEN = 50
DROP_SHORT = 0  # sample 数据较小，通常不丢弃

EPOCH = 2
BATCH_SIZE = 4096
LR = 1e-3
WEIGHT_DECAY = 1e-3
EARLYSTOP_PATIENCE = 4

USE_TRACKING = False
LOGGER_TYPE = None  # "wandb" | "swanlab" | "tensorboard" | None
PROJECT_NAME = "amazon-electronics-din"

EXPORT_ONNX = False
ONNX_PATH = "din.onnx"

torch.manual_seed(SEED)
print("DATASET_PATH:", DATASET_PATH.resolve())

```

--------------------------------

### Install PyTorch for AMD GPU (ROCm)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/README.md

Install PyTorch with ROCm support for AMD GPUs. This example is for gfx1151 (Ryzen AI Max+ 395/390/385).

```bash
pip install --index-url https://repo.amd.com/rocm/whl/gfx1151/ "rocm[libraries,devel]" torch torchvision torchaudio
```

--------------------------------

### Run a Simple Torch-RecHub Example

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/install.md

Executes a sample machine learning script (ml_dssm.py) from the examples directory to verify Torch-RecHub's functionality. Ensure you navigate to the script's directory first.

```bash
cd examples/matching
python run_ml_dssm.py
```

--------------------------------

### Quick Start: Build and Query Vector Index

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/serving/vector_index.md

Demonstrates building a vector index from embeddings and performing a top-K query. Includes saving and loading the index.

```python
import torch
from torch_rechub.serving import builder_factory

# Prepare embeddings
item_embeddings = torch.randn(1000, 64, dtype=torch.float32)  # 1000 items, 64 dimensions
user_embeddings = torch.randn(10, 64, dtype=torch.float32)    # 10 users, 64 dimensions

# Create Builder and build index
builder = builder_factory("faiss", index_type="Flat", metric="L2")

with builder.from_embeddings(item_embeddings) as indexer:
    # Query Top-K
    ids, distances = indexer.query(user_embeddings, top_k=10)
    # Save index
    indexer.save("item.index")

# Load existing index
with builder.from_index_file("item.index") as indexer:
    ids, distances = indexer.query(user_embeddings, top_k=10)
```

--------------------------------

### Initialize and Use VectorQuantizer

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/api/api.md

Demonstrates how to initialize a VectorQuantizer and apply it to input data. Shows the expected output shape.

```python
>>> vq = VectorQuantizer(n_e=512, e_dim=64)
>>> x = torch.randn(32, 10, 64)
>>> x_q, loss, indices = vq(x)
>>> x_q.shape
```

```python
torch.Size([32, 10, 64])
```

--------------------------------

### Install Faiss GPU Version

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/serving/vector_index.md

Install the GPU-accelerated version of Faiss. Requires CUDA to be installed.

```bash
pip install faiss-gpu
```

--------------------------------

### Complete Training Example for MMOE Model

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/models/mtl.md

This example demonstrates the full workflow of defining features, preparing data, creating a data generator, initializing the MMOE model, setting up the MTLTrainer with adaptive loss weighting, training the model, evaluating its performance, exporting it to ONNX format, and making predictions. Ensure all necessary data variables (e.g., user_id_data, task1_labels) are defined before running.

```python
from torch_rechub.models.multi_task import MMOE
from torch_rechub.trainers import MTLTrainer
from torch_rechub.utils.data import DataGenerator
from torch_rechub.basic.features import SparseFeature, DenseFeature

# 1. Define features
common_features = [
    SparseFeature(name="user_id", vocab_size=10000, embed_dim=32),
    SparseFeature(name="city", vocab_size=100, embed_dim=16),
    DenseFeature(name="age", embed_dim=1),
    DenseFeature(name="income", embed_dim=1)
]

# 2. Prepare data
# Assume x contains all features, y contains labels for two tasks
x = {
    "user_id": user_id_data,
    "city": city_data,
    "age": age_data,
    "income": income_data
}
y = {
    "task1": task1_labels,  # CTR labels
    "task2": task2_labels   # CVR labels
}

# 3. Create data generator
dg = DataGenerator(x, y)
train_dl, val_dl, test_dl = dg.generate_dataloader(split_ratio=[0.7, 0.1], batch_size=256)

# 4. Create model
model = MMOE(
    features=common_features,
    task_types=["classification", "classification"],
    n_expert=8,
    expert_params={"dims": [256, 128], "dropout": 0.2, "activation": "relu"},
    tower_params_list=[
        {"dims": [64, 32], "dropout": 0.2, "activation": "relu"},
        {"dims": [64, 32], "dropout": 0.2, "activation": "relu"}
    ]
)

# 5. Create trainer
trainer = MTLTrainer(
    model=model,
    task_types=["classification", "classification"],
    optimizer_params={"lr": 0.001, "weight_decay": 0.0001},
    adaptive_params={"method": "uwl"},  # Use adaptive loss weighting
    n_epoch=50,
    earlystop_patience=10,
    device="cuda:0",
    model_path="saved/mmoe"
)

# 6. Train model
trainer.fit(train_dl, val_dl)

# 7. Evaluate model
scores = trainer.evaluate(trainer.model, test_dl)
print(f"Task 1 AUC: {scores[0]}")
print(f"Task 2 AUC: {scores[1]}")

# 8. Export ONNX model
trainer.export_onnx("mmoe.onnx")

# 9. Model prediction
preds = trainer.predict(trainer.model, test_dl)
print(f"Predictions shape: {np.array(preds).shape}")
```

--------------------------------

### Docstring Example for Training Function

Source: https://github.com/datawhalechina/torch-rechub/blob/main/CONTRIBUTING.md

Example of a Python docstring following NumPy/SciPy conventions, including parameters, return values, and examples.

```python
def train_model(model, data_loader, optimizer):
    """Train a recommendation model.

    Parameters
    ----------
    model : torch.nn.Module
        Model to train.
    data_loader : DataLoader
        Training data loader.
    optimizer : torch.optim.Optimizer
        Optimizer for training.

    Returns
    -------
    float
        Training loss.

    Examples
    --------
    >>> model = DeepFM(features, mlp_params)
    >>> loss = train_model(model, train_loader, optimizer)
    """
    # Implementation here
```

--------------------------------

### Install Torch-RecHub Visualization Dependencies

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/zh/tutorials/models/matching/dssm.md

Installs the necessary packages for model visualization, including `torch-rechub[visualization]`. Also requires system-level installation of Graphviz.

```bash
pip install torch-rechub[visualization]
# 还需要安装系统级 graphviz:
# Ubuntu: sudo apt-get install graphviz
# macOS: brew install graphviz
# Windows: choco install graphviz
```

--------------------------------

### Initialize Device and Imports for DSSM

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/group_learning/DSSM.ipynb

Sets up the device (CPU/GPU) and imports necessary libraries for the DSSM model and data handling. Ensure PyTorch is installed and CUDA is available for GPU acceleration.

```python
import torch
import pandas as pd
import numpy as np
import os
from sklearn.preprocessing import LabelEncoder

from torch_rechub.models.matching import DSSM
from torch_rechub.trainers import MatchTrainer
from torch_rechub.basic.features import SparseFeature, SequenceFeature
from torch_rechub.utils.match import generate_seq_feature_match, gen_model_input, Annoy
from torch_rechub.utils.data import df_to_dict, MatchDataGenerator

torch.manual_seed(2022)
# 如果有显卡可以设置为 'cuda:0'
device = 'cuda:0' if torch.cuda.is_available() else 'cpu'
print(f"Using device: {device}")
```

--------------------------------

### Install Torch-RecHub (Stable Version)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/README.md

Installs the latest stable version of Torch-RecHub. Ensure you have the correct PyTorch version installed based on your hardware and drivers.

```bash
pip install torch-rechub
```

--------------------------------

### Install Nose (Offline - macOS)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/community/faq.md

Use this command for offline installation of the 'nose' library on macOS, often a prerequisite for Annoy if online installation fails.

```bash
pip install nose‑1.3.7‑py3‑none‑any.whl
```

--------------------------------

### Run Matching Benchmark

Source: https://github.com/datawhalechina/torch-rechub/blob/main/benchmarks/README.md

Execute a matching benchmark using a specified configuration file. This command initiates the first stage of the matching benchmark process.

```bash
python benchmarks/runner.py --config benchmarks/configs/matching/ml_1m_mind.yaml
```

--------------------------------

### Setup and Configuration for Model Export

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/05_Model_Export_and_Serving.ipynb

Initializes project paths, export directory, and sets the device for PyTorch operations and ONNX export. Ensures the export directory exists.

```python
import os
from pathlib import Path
import numpy as np
import pandas as pd
import torch
from sklearn.preprocessing import LabelEncoder, MinMaxScaler
from tqdm import tqdm

from torch_rechub.basic.features import DenseFeature, SparseFeature, SequenceFeature
from torch_rechub.models.ranking import DeepFM
from torch_rechub.models.matching import DSSM
from torch_rechub.trainers import CTRTrainer
from torch_rechub.utils.data import DataGenerator
from torch_rechub.utils.onnx_export import ONNXExporter
from torch_rechub.utils.model_utils import generate_dummy_input_dict

SEED = 2022
DEVICE = "cuda:0" if torch.cuda.is_available() else "cpu"
EXPORT_DEVICE = "cpu"  # ONNX export defaults to CPU for better compatibility
torch.manual_seed(SEED)

PROJECT_ROOT = Path.cwd() if (Path.cwd() / "examples").exists() else Path.cwd().parent
EXPORT_DIR = PROJECT_ROOT / "onnx_exports"
EXPORT_DIR.mkdir(parents=True, exist_ok=True)
print("DEVICE:", DEVICE, "EXPORT_DEVICE:", EXPORT_DEVICE)
print("EXPORT_DIR:", EXPORT_DIR.resolve())
```

--------------------------------

### Quickstart: Initialize and Use WandbLogger with CTRTrainer

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/tools/tracking.md

Initialize a WandbLogger and pass it to the CTRTrainer for experiment tracking. The logger is automatically closed after `fit()`.

```python
from torch_rechub.trainers import CTRTrainer
from torch_rechub.basic.tracking import WandbLogger

logger = WandbLogger(project="my-ctr", name="exp1")  # optional

trainer = CTRTrainer(
    model,
    optimizer_params={"lr": 1e-3},
    n_epoch=10,
    model_logger=logger,   # pass None for zero tracking
)

trainer.fit(train_dl, val_dl)
# Logger is automatically closed after fit(), no need to call finish() manually
```

--------------------------------

### Install Stable Torch-RecHub (CPU)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/install.md

Installs the stable version of Torch-RecHub using pip for CPU-only environments. Ensure PyTorch is installed separately to match your system.

```bash
pip install torch
pip install torch-rechub
```

--------------------------------

### Complete Training Example for HSTUModel

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/models/generative.md

This snippet shows how to load data, initialize the SequenceDataGenerator, set up the HSTUModel, and train it using SeqTrainer. It includes data loading from pickle files and model training/evaluation steps.

```python
import pickle
import torch

from torch_rechub.models.generative import HSTUModel
from torch_rechub.trainers import SeqTrainer
from torch_rechub.utils.data import SequenceDataGenerator

with open("examples/generative/data/ml-1m/processed/train_data.pkl", "rb") as f:
    train_data = pickle.load(f)
with open("examples/generative/data/ml-1m/processed/val_data.pkl", "rb") as f:
    val_data = pickle.load(f)
with open("examples/generative/data/ml-1m/processed/test_data.pkl", "rb") as f:
    test_data = pickle.load(f)
with open("examples/generative/data/ml-1m/processed/vocab.pkl", "rb") as f:
    vocab = pickle.load(f)

train_gen = SequenceDataGenerator(
    train_data["seq_tokens"],
    train_data["seq_positions"],
    train_data["targets"],
    train_data["seq_time_diffs"],
)
val_gen = SequenceDataGenerator(
    val_data["seq_tokens"],
    val_data["seq_positions"],
    val_data["targets"],
    val_data["seq_time_diffs"],
)
test_gen = SequenceDataGenerator(
    test_data["seq_tokens"],
    test_data["seq_positions"],
    test_data["targets"],
    test_data["seq_time_diffs"],
)

train_dl = train_gen.generate_dataloader(batch_size=512, num_workers=0)[0]
val_dl = val_gen.generate_dataloader(batch_size=512, num_workers=0)[0]
test_dl = test_gen.generate_dataloader(batch_size=512, num_workers=0)[0]

vocab_size = len(vocab["item_to_idx"]) if "item_to_idx" in vocab else len(vocab)
model = HSTUModel(
    vocab_size=vocab_size,
    d_model=128,
    n_heads=4,
    n_layers=2,
    dqk=32,
    dv=32,
    max_seq_len=200,
    dropout=0.1,
)

trainer = SeqTrainer(
    model,
    optimizer_fn=torch.optim.Adam,
    optimizer_params={"lr": 0.001, "weight_decay": 0.0001},
    n_epoch=10,
    earlystop_patience=10,
    device="cuda" if torch.cuda.is_available() else "cpu",
    model_path="saved/hstu",
)

trainer.fit(train_dl, val_dl)
test_loss, top1_acc = trainer.evaluate(test_dl)
print(f"test_loss={test_loss:.4f}, top1_acc={top1_acc:.4f}")
```

--------------------------------

### Install Torch-RecHub Visualization Dependencies

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/tools/visualization.md

Installs the torch-rechub library with visualization extras and system-level graphviz. Ensure graphviz is installed on your system for visualization to function correctly.

```bash
pip install torch-rechub[visualization]
```

```bash
# Ubuntu/Debian
sudo apt-get install graphviz

# macOS
brew install graphviz

# Windows
choco install graphviz
```

--------------------------------

### RQVAEModel Initialization and Forward Pass Example

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/api/api.md

Initializes and demonstrates a forward pass of the RQVAEModel. Input features are processed to produce reconstructed output, quantization loss, and codebook indices.

```python
model = RQVAEModel(in_dim=768, num_emb_list=[512,512], e_dim=64, layers=[256,128])
x = torch.randn(32, 768)
out, rq_loss, indices = model(x)
out.shape
```

```python
torch.Size([32, 768])
```

--------------------------------

### Install Development Version of Torch-RecHub (CPU)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/install.md

Installs the latest development version of Torch-RecHub using uv for CPU environments. Includes installing uv and cloning the repository.

```bash
pip install uv
git clone https://github.com/datawhalechina/torch-rechub.git
cd torch-rechub
uv pip install torch
uv sync
```

--------------------------------

### Matching Benchmark Configuration Example

Source: https://github.com/datawhalechina/torch-rechub/blob/main/benchmarks/BENCHMARK_DESIGN.md

YAML configuration for a matching benchmark, specifying dataset, model, trainer, and metrics parameters. Use this for setting up list-wise recall model benchmarks.

```yaml
task: matching

dataset:
  name: ml-1m-sample
  path: examples/matching/data/ml-1m/ml-1m_sample.csv
  seq_max_len: 50
  neg_ratio: 3
  sample_method: 1
  padding: post
  truncating: post

model:
  name: MIND
  params:
    embed_dim: 16
    interest_num: 4
    temperature: 0.02

trainer:
  mode: 2
  epochs: 1
  batch_size: 32
  learning_rate: 0.001
  weight_decay: 0.000001
  device: cpu
  seed: 2022

metrics:
  topk: 10

output_dir: benchmark_results/matching/ml_1m_mind

```

--------------------------------

### Quick Start: MovieLens-1M Preprocessing and Training

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/blog/hllm_reproduction.md

Commands to preprocess MovieLens-1M data and train an HLLM model. Includes options for different LLM model sizes.

```bash
# 1. Enter data directory
cd examples/generative/data/ml-1m

# 2. Preprocess MovieLens-1M sequence data (downloads missing raw files)
python preprocess_ml_hstu.py

# 3. HLLM data preprocessing (text extraction + embedding generation)
# Option A: TinyLlama-1.1B (recommended, 2GB GPU, ~10 minutes)
python preprocess_hllm_data.py --model_type tinyllama --device cuda

# Option B: Baichuan2-7B (larger, 14GB GPU, ~30 minutes)
# python preprocess_hllm_data.py --model_type baichuan2 --device cuda

# 4. Return to project root and train model
cd ../../../..
python examples/generative/run_hllm_movielens.py \
    --model_type tinyllama \
    --epoch 5 \
    --batch_size 512 \
    --device cuda
```

--------------------------------

### Install Stable Torch-RecHub (AMD GPU)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/install.md

Installs the stable version of Torch-RecHub for AMD GPUs with ROCm support (gfx1151). This command installs ROCm libraries and PyTorch.

```bash
pip install --index-url https://repo.amd.com/rocm/whl/gfx1151/ "rocm[libraries,devel]" torch torchvision torchaudio
pip install torch-rechub
```

--------------------------------

### Install ONNX Dependencies

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/serving/onnx.md

Install optional ONNX dependencies for Torch-RecHub.

```bash
pip install "torch-rechub[onnx]"
```

--------------------------------

### Visualization Installation

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/tools/visualization.md

Install Torch-RecHub with visualization dependencies and system-level graphviz.

```APIDOC
## Installation

Visualization requires additional dependencies:

```bash
pip install torch-rechub[visualization]
```

Also install system-level graphviz:

```bash
# Ubuntu/Debian
sudo apt-get install graphviz

# macOS
brew install graphviz

# Windows
choco install graphviz
```
```

--------------------------------

### Install Stable Torch-RecHub (NVIDIA GPU)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/install.md

Installs the stable version of Torch-RecHub using pip for NVIDIA GPUs with CUDA 12.1. Ensure your PyTorch installation matches the CUDA version.

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install torch-rechub
```

--------------------------------

### Import Libraries and Configure Training Parameters

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/04_Experiment_Tracking_Light.ipynb

Import necessary libraries for data handling, model definition, training, and tracking. Configure training parameters such as dataset path, epochs, batch size, learning rate, and weight decay. Set flags to enable or disable specific loggers.

```python
import os
from pathlib import Path
import numpy as np
import pandas as pd
import torch
from sklearn.preprocessing import LabelEncoder, MinMaxScaler
from tqdm import tqdm

from torch_rechub.basic.features import DenseFeature, SparseFeature
from torch_rechub.models.ranking import DeepFM
from torch_rechub.trainers import CTRTrainer
from torch_rechub.utils.data import DataGenerator

# 跟踪组件（按需导入，未安装时会 ImportError）
# from torch_rechub.basic.tracking import WandbLogger, SwanLabLogger, TensorBoardXLogger

SEED = 2022
DEVICE = "cpu"
PROJECT_ROOT = Path.cwd() if (Path.cwd() / "examples").exists() else Path.cwd().parent
DATASET_PATH = PROJECT_ROOT / "examples/ranking/data/criteo/criteo_sample.csv"

EPOCH = 1
BATCH_SIZE = 2048
LR = 1e-3
WEIGHT_DECAY = 1e-3
EARLYSTOP_PATIENCE = 2

# 默认不启用任何 logger（保持轻量）
USE_WANDB = False
USE_SWANLAB = False
USE_TENSORBOARD = False
PROJECT_NAME = "tracking-demo"

torch.manual_seed(SEED)
print("DATASET_PATH:", DATASET_PATH.resolve())
```

--------------------------------

### Install Development Version of Torch-RecHub (NVIDIA GPU)

Source: https://github.com/datawhalechina/torch-rechub/blob/main/docs/en/guide/install.md

Installs the latest development version of Torch-RecHub using uv for NVIDIA GPUs with CUDA 12.1. Includes installing uv and cloning the repository.

```bash
pip install uv
git clone https://github.com/datawhalechina/torch-rechub.git
cd torch-rechub
uv pip install torch --index-url https://download.pytorch.org/whl/cu121
uv sync
```

--------------------------------

### Import Libraries and Set Up Constants

Source: https://github.com/datawhalechina/torch-rechub/blob/main/tutorials/03_MultiTask_MMOE.ipynb

Imports necessary libraries and defines constants for model training, including data paths, training parameters, and device selection. Ensures reproducibility by setting a manual seed.

```python
import os
from pathlib import Path
import pandas as pd
import torch

from torch_rechub.basic.features import DenseFeature, SparseFeature
from torch_rechub.models.multi_task import MMOE
from torch_rechub.trainers import MTLTrainer
from torch_rechub.utils.data import DataGenerator

SEED = 2022
DEVICE = "cpu"  # 可改为 "cuda:0"

PROJECT_ROOT = Path.cwd() if (Path.cwd() / "examples").exists() else Path.cwd().parent
DATA_DIR = PROJECT_ROOT / "examples/ranking/data/ali-ccp"

EPOCH = 1
BATCH_SIZE = 1024
LR = 1e-3
WEIGHT_DECAY = 1e-4
EARLYSTOP_PATIENCE = 30

# 可选：自适应权重（默认关闭）
USE_ADAPTIVE_WEIGHT = False
ADAPTIVE_METHOD = "uwl"  # "uwl" | "gradnorm" | ...（以实现为准）

torch.manual_seed(SEED)
print("DATA_DIR:", DATA_DIR.resolve())

```