# 推荐系统离线任务

本目录包含推荐系统的离线任务脚本，用于生成各种推荐索引。

## 目录结构

```
offline_tasks/
├── config/
│   └── offline_config.py          # 离线任务配置文件
├── scripts/
│   ├── i2i_swing.py               # Swing算法实现
│   ├── i2i_session_w2v.py         # Session Word2Vec实现
│   ├── i2i_deepwalk.py            # DeepWalk算法实现
│   └── interest_aggregation.py    # 兴趣点聚合索引生成
├── output/                         # 输出目录
├── logs/                           # 日志目录
├── run_all.py                      # 统一调度脚本
└── README.md                       # 本文档
```

## 功能说明

### 1. i2i - 行为相似索引

基于用户行为数据，计算商品之间的相似度，生成i2i（item-to-item）推荐索引。

#### 1.1 Swing算法

Swing算法是一种基于用户共同行为的物品相似度计算方法，相比协同过滤有更好的效果。

**运行命令：**
```bash
python scripts/i2i_swing.py --lookback_days 730 --top_n 50 --time_decay
```

**参数说明：**
- `--lookback_days`: 回溯天数（默认730天，即2年）
- `--top_n`: 每个商品输出的相似商品数量（默认50）
- `--alpha`: Swing算法的alpha参数（默认0.5）
- `--time_decay`: 是否使用时间衰减
- `--decay_factor`: 时间衰减因子（默认0.95，每30天衰减一次）

**输出格式：**
```
item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,...
```

#### 1.2 Session Word2Vec

基于用户会话序列训练Word2Vec模型，学习商品的向量表示，通过向量相似度计算商品相似度。

**运行命令：**
```bash
python scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50 --save_model
```

**参数说明：**
- `--lookback_days`: 回溯天数
- `--top_n`: 输出相似商品数量
- `--window_size`: Word2Vec窗口大小（默认5）
- `--vector_size`: 向量维度（默认128）
- `--min_count`: 最小词频（默认2）
- `--workers`: 训练线程数（默认10）
- `--epochs`: 训练轮数（默认10）
- `--session_gap`: 会话间隔（分钟，默认30）
- `--save_model`: 是否保存模型

**输出格式：**
```
item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,...
```

#### 1.3 DeepWalk

基于用户-商品交互图，使用随机游走生成序列，然后训练Word2Vec模型。

**运行命令：**
```bash
python scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50 --save_model --save_graph
```

**参数说明：**
- `--lookback_days`: 回溯天数
- `--top_n`: 输出相似商品数量
- `--num_walks`: 每个节点的游走次数（默认10）
- `--walk_length`: 游走长度（默认40）
- `--window_size`: Word2Vec窗口大小（默认5）
- `--vector_size`: 向量维度（默认128）
- `--save_model`: 是否保存模型
- `--save_graph`: 是否保存图结构

**输出格式：**
```
item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,...
```

### 2. 兴趣点聚合索引

按照多个维度聚合用户行为，生成不同场景下的商品推荐索引。

**运行命令：**
```bash
python scripts/interest_aggregation.py --lookback_days 730 --top_n 1000
```

**参数说明：**
- `--lookback_days`: 回溯天数（默认730天，即2年）
- `--recent_days`: 热门商品的统计天数（默认180天）
- `--new_days`: 新品的定义天数（默认90天）
- `--top_n`: 每个维度输出的商品数量（默认1000）
- `--decay_factor`: 时间衰减因子（默认0.95）

**支持的维度：**

1. **单维度：**
   - `platform`: 平台
   - `country`: 国家/销售区域
   - `customer_type`: 客户类型
   - `category_level2`: 二级分类
   - `category_level3`: 三级分类

2. **组合维度：**
   - `platform_country`: 平台 + 国家
   - `platform_customer`: 平台 + 客户类型
   - `country_customer`: 国家 + 客户类型
   - `platform_country_customer`: 平台 + 国家 + 客户类型

3. **列表类型：**
   - `hot`: 热门商品（基于最近N天的高交互）
   - `cart`: 加购商品（基于加购行为）
   - `new`: 新品（基于商品创建时间）
   - `global`: 全局索引（所有数据）

**输出格式：**
```
dimension_key \t item_id1:score1,item_id2:score2,...
```

**示例：**
```
platform:PC \t 12345:98.5,23456:87.3,...
country:US \t 34567:156.2,45678:142.8,...
platform_country:PC_US \t 56789:234.5,67890:198.7,...
```

## 统一调度脚本

使用 `run_all.py` 可以一次性运行所有离线任务：

**运行所有任务：**
```bash
python run_all.py --lookback_days 730 --top_n 50
```

**运行特定任务：**
```bash
# 只运行Swing算法
python run_all.py --only-swing

# 只运行Session W2V
python run_all.py --only-w2v

# 只运行DeepWalk
python run_all.py --only-deepwalk

# 只运行兴趣点聚合
python run_all.py --only-interest

# 跳过i2i任务
python run_all.py --skip-i2i

# 跳过兴趣点聚合
python run_all.py --skip-interest
```

## 配置文件

所有配置参数都在 `config/offline_config.py` 中定义，包括：

- **数据库配置**：数据库连接信息
- **路径配置**：输出目录、日志目录
- **时间配置**：回溯天数、时间衰减参数
- **算法配置**：各算法的超参数
- **行为权重**：不同行为类型的权重

可以根据实际需求修改配置文件中的参数。

## 输出文件

所有输出文件都保存在 `output/` 目录下，文件名格式为：

```
{任务名}_{日期}.txt
```

例如：
- `i2i_swing_20251016.txt`
- `i2i_session_w2v_20251016.txt`
- `i2i_deepwalk_20251016.txt`
- `interest_aggregation_hot_20251016.txt`
- `interest_aggregation_cart_20251016.txt`
- `interest_aggregation_new_20251016.txt`
- `interest_aggregation_global_20251016.txt`

## 日志

所有任务的执行日志都保存在 `logs/` 目录下。

## 依赖项

```bash
pip install pandas sqlalchemy pymysql gensim numpy
```

## 定时任务设置

建议使用crontab设置定时任务，每天凌晨运行一次：

```bash
# 编辑crontab
crontab -e

# 添加定时任务（每天凌晨2点运行）
0 2 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 run_all.py --lookback_days 730 --top_n 50
```

## 注意事项

1. **数据量**：由于需要处理2年的数据，任务可能需要较长时间（几小时到十几小时不等）
2. **内存占用**：Swing算法和DeepWalk可能占用较多内存，建议在内存充足的机器上运行
3. **数据库连接**：确保数据库连接信息正确，且有足够的权限读取相关表
4. **磁盘空间**：确保output目录有足够的磁盘空间存储输出文件

## 性能优化建议

1. **并行化**：可以将不同算法的任务分配到不同机器上并行运行
2. **增量更新**：对于已有的索引，可以考虑增量更新而不是全量计算
3. **采样**：对于数据量特别大的场景，可以考虑先采样一部分数据进行调试
4. **缓存**：可以将中间结果缓存，避免重复计算

## 问题排查

如果任务执行失败，请检查：

1. 日志文件中的错误信息
2. 数据库连接是否正常
3. 数据表结构是否正确
4. Python依赖包是否安装完整
5. 磁盘空间是否充足
6. 内存是否充足