# 推荐系统离线任务
  
  本目录包含推荐系统的离线任务脚本，用于生成各种推荐索引。
  
  ## 目录结构
  
  ```
  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. 内存是否充足