# NextRec 快速上手

本文演示如何用 NextRec 从零到一训练并上线一个推荐模型，示例基于仓库自带的 `dataset/movielens_100k.csv`。更多完整脚本请参考 `tutorials/` 目录。

## 1. 环境与安装

- 依赖：Python 3.10+、PyTorch 1.10+（GPU/MPS 可选）。
- 安装稳定版：`pip install nextrec`
- 开发模式：在仓库根目录执行 `pip install -e .`

## 2. 数据与特征速览

推荐模型通常需要同时处理多种信号，并将其转换为向量：

- 稠密特征：连续或可序数化的数值（年龄、价格、时长等），常见做法是标准化/归一化或对数变换。
- 稀疏特征：高基数离散字段（用户 ID、物品 ID、性别、职业、设备类型等），通常需要索引化后放入 embedding lookup。
- 序列特征：可变长历史行为（浏览/点击/购买列表），需要截断、padding，再通过聚合（mean/sum/attention）转为定长向量。
- 上下文与多模态特征：时间、地理、曝光位置，或由文本/图像/视频模型生成的向量，可与主特征交互建模。

以 `movielens_100k.csv` 为例，包含 `user_id`、`item_id`、`gender`、`occupation` 等离散特征，以及 `age` 等稠密特征，监督标签为 `label`（是否点击/评分高）。

## 3. 5 分钟训练一个排序模型（DeepFM）

下面用 DeepFM 在 MovieLens 数据集上完成从特征定义到训练、评估的全流程。示例使用内置的数据加载能力，无需手动编写 DataLoader。

```python
import pandas as pd
from sklearn.model_selection import train_test_split

from nextrec.basic.features import DenseFeature, SparseFeature
from nextrec.models.ranking.deepfm import DeepFM

# 1) 读取数据
df = pd.read_csv("dataset/movielens_100k.csv")

# 2) 定义特征
dense_features = [DenseFeature("age")]
sparse_features = [
    SparseFeature("user_id", vocab_size=df["user_id"].max() + 1, embedding_dim=16),
    SparseFeature("item_id", vocab_size=df["item_id"].max() + 1, embedding_dim=16),
    SparseFeature("gender", vocab_size=df["gender"].max() + 1, embedding_dim=4),
    SparseFeature("occupation", vocab_size=df["occupation"].max() + 1, embedding_dim=8),
]

# 3) 划分训练/验证集
train_df, valid_df = train_test_split(df, test_size=0.2, random_state=2024)

# 4) 实例化并编译模型
model = DeepFM(
    dense_features=dense_features,
    sparse_features=sparse_features,
    mlp_params={"dims": [256, 128], "activation": "relu", "dropout": 0.2},
    target="label",
    device="cpu",
    session_id="movielens_deepfm",   # 管理实验日志与检查点
)

model.compile(
    optimizer="adam",
    optimizer_params={"lr": 1e-3, "weight_decay": 1e-5},
    loss="binary_crossentropy",
)

# 5) 训练
model.fit(
    train_data=train_df,
    valid_data=valid_df,
    metrics=["auc", "recall", "precision"],
    epochs=2,
    batch_size=512,
    shuffle=True,
)
```

- `metrics` 支持 `auc`/`logloss`/`accuracy`/`gauc` 等，使用 GAUC 时需传入 `user_id_column="user_id"`。
- 训练过程会自动早停，并在 `nextrec_logs/movielens_deepfm` 下保存最优权重、配置与日志。

## 4. 推理与评估

训练结束后即可进行批量预测或评估：

```python
# 批量预测
preds = model.predict(valid_df, batch_size=512)

# 评估指标
metrics = model.evaluate(
    valid_df,
    metrics=["auc", "gauc", "logloss"],
    batch_size=512,
    user_id_column="user_id",  # 仅在计算 GAUC 时需要
)
```

- 保存预测结果：`model.predict(..., save_path="outputs/preds", save_format="csv")`。
- 模型加载：调用 `model.load("path/to/checkpoint")` 继续训练或部署。

## 5. 更多示例与 Notebook

- 排序：`tutorials/example_ranking_din.py`（电商数据集 DIN）、`tutorials/movielen_ranking_deepfm.py`
- 召回：`tutorials/movielen_match_dssm.py`
- 多任务：`tutorials/example_multitask.py`
- Notebook：`tutorials/notebooks/zh/Hands on nextrec.ipynb`、`tutorials/notebooks/zh/Hands on dataprocessor.ipynb`

如果需要大规模离线特征或流式加载，可结合 `DataProcessor`、`RecDataLoader` 配置 CSV/Parquet 路径与流式参数（`streaming=True`），在不修改模型代码的情况下完成训练与推理。
