# 推荐系统离线任务
  

  推荐系统的离线索引生成模块，包含多种算法和数据处理任务。

  ## 🚀 快速开始

  ### 运行所有任务（推荐）

  ```bash

  cd /home/tw/recommendation/offline_tasks

  # 运行全部离线任务（包括C++ Swing）
  python3 run_all.py

  # 开启debug模式（详细日志 + 可读文件）
  python3 run_all.py --debug

  ```
  

  ### 任务执行顺序

  ```
  前置任务:
  1. fetch_item_attributes.py  → 获取商品属性映射
  2. generate_session.py       → 生成用户行为session
  3. C++ Swing算法             → 高性能i2i相似度计算

  核心算法任务:
  4. Python Swing算法          → 支持日期维度的i2i
  5. Session W2V              → 基于序列的embedding
  6. DeepWalk                 → 图结构embedding
  7. 内容相似度               → 基于ES向量
  8. 兴趣聚合                 → 多维度商品聚合

  ```
  

  ## 📚 文档

  所有文档位于 **`doc/`** 目录：

  - **[doc/快速开始.md](./doc/快速开始.md)** - 新手入门
  - **[doc/Swing算法使用指南.md](./doc/Swing算法使用指南.md)** - 详细使用
  - **[doc/系统改进总结-20241017.md](./doc/系统改进总结-20241017.md)** - 最新改进
  - **[doc/README.md](./doc/README.md)** - 完整文档索引

  ## 🔧 核心功能

  ### 1. 前置任务优化

  - **商品属性缓存**: 一次获取，多次使用，减少90%数据库查询
  - **Session文件复用**: 统一生成，多算法共享
  - **C++ Swing集成**: 自动执行，高性能计算

  ### 2. 算法增强

  - **双维度Swing**: 同时考虑用户整体行为和单日行为
  - **时间衰减**: 可选的时间权重衰减
  - **Debug模式**: 自动生成可读版本（ID + 名称）

  ### 3. 自动化流程

  ```bash

  # 一条命令完成所有任务
  python3 run_all.py --debug

  ```
  

  输出文件：
  - `output/item_attributes_mappings.json` - ID映射
  - `output/session.txt.YYYYMMDD` - 用户session
  - `collaboration/output/swing_similar.txt` - C++ Swing结果
  - `output/i2i_swing_YYYYMMDD.txt` - Python Swing结果
  - ... 其他算法输出

  ## 📊 性能对比

  | 任务 | 改进前 | 改进后 | 提升 |
  |------|--------|--------|------|
  | 数据库查询 | 5-10次 | 1次 | 80-90% ↓ |
  | Swing性能 | Python | C++ | 10-100x ↑ |
  | 任务管理 | 手动分步 | 自动流程 | 100% ↑ |

  ## 🛠️ 单独运行任务

  ### 1. 获取商品属性

  ```bash
  python3 scripts/fetch_item_attributes.py

  ```
  

  ### 2. 生成Session

  ```bash

  python3 scripts/generate_session.py --lookback_days 730

  ```
  

  ### 3. C++ Swing

  ```bash
  cd ../collaboration
  bash run.sh
  ```

  ### 4. Python Swing（支持日期维度）

  ```bash
  python3 scripts/i2i_swing.py --lookback_days 730 --use_daily_session --debug

  ```
  

  ### 5. 其他算法

  ```bash
  # Session W2V
  python3 scripts/i2i_session_w2v.py --lookback_days 730 --debug

  # DeepWalk
  python3 scripts/i2i_deepwalk.py --lookback_days 730 --debug

  # 内容相似度
  python3 scripts/i2i_content_similar.py

  # 兴趣聚合
  python3 scripts/interest_aggregation.py --lookback_days 730 --debug
  ```

  ## 📁 项目结构

  
  ```

  offline_tasks/
  ├── scripts/              # 所有任务脚本
  │   ├── fetch_item_attributes.py
  │   ├── generate_session.py
  │   ├── i2i_swing.py
  │   ├── i2i_session_w2v.py
  │   ├── i2i_deepwalk.py
  │   ├── i2i_content_similar.py
  │   ├── interest_aggregation.py
  │   ├── add_names_to_swing.py
  │   └── debug_utils.py
  ├── config/               # 配置文件
  │   └── offline_config.py
  ├── doc/                  # 文档中心
  │   ├── README.md
  │   ├── 快速开始.md
  │   ├── Swing算法使用指南.md
  │   └── ...
  ├── output/               # 输出目录
  │   ├── item_attributes_mappings.json
  │   ├── session.txt.*
  │   └── *.txt
  ├── logs/                 # 日志目录
  ├── run_all.py           # 统一入口
  └── README.md            # 本文件
  ```
  
  ## ⚙️ 配置
  
  配置文件：`config/offline_config.py`
  
  主要参数：
  ```python
  DEFAULT_LOOKBACK_DAYS = 730    # 数据回看天数
  DEFAULT_I2I_TOP_N = 50         # i2i推荐数量
  DEFAULT_INTEREST_TOP_N = 1000  # 兴趣聚合数量
  
  # 数据库配置
  DB_CONFIG = {...}
  
  # 算法参数
  I2I_CONFIG = {...}
  ```
  
  ## 🐛 故障排查
  
  ### 常见问题
  
  **1. 映射文件不存在**
  ```bash
  # 先运行前置任务
  python3 scripts/fetch_item_attributes.py

  ```
  

  **2. Session文件找不到**
  ```bash
  # 生成session文件
  python3 scripts/generate_session.py
  ```

  **3. C++ Swing编译失败**

  ```bash

  cd ../collaboration
  make clean
  make

  ```
  

  详见：[doc/故障排查指南.md](./doc/故障排查指南.md)

  ## 📝 日志

  日志位置：
  - 主日志：`logs/run_all_YYYYMMDD.log`
  - Debug日志：`logs/debug/*.log`

  查看最新日志：
  ```bash
  tail -f logs/run_all_$(date +%Y%m%d).log

  ```
  

  ## 🔗 相关项目

  - **Collaboration**: `../collaboration/` - C++ 协同过滤
  - **GraphEmbedding**: `../graphembedding/` - 图embedding
  - **Hot**: `../hot/` - 热门推荐
  - **Frontend**: `../frontend/` - 推荐接口

  ## 📞 更多信息

  - **完整文档**: [doc/README.md](./doc/README.md)
  - **改进总结**: [doc/系统改进总结-20241017.md](./doc/系统改进总结-20241017.md)
  - **故障排查**: [doc/故障排查指南.md](./doc/故障排查指南.md)

  ---

  **最后更新**: 2024-10-17  
  **状态**: ✅ 生产就绪