OFFLINE_TASKS_README.md 7.19 KB
Edit Raw Blame History


推荐系统离线任务 - 完整交付
🎯 项目目标
根据业务文档要求，构建推荐系统的离线任务部分，建立基于现有用户特征的相应索引。
✅ 已完成的任务
1. i2i - 行为相似索引（3种算法）
参考 item_sim.py（真实可运行的代码），改写了以下算法以适配我们的数据：
✅ Swing算法

文件: offline_tasks/scripts/i2i_swing.py
来源: 改写自 collaboration/src/swing.cc
特点: 基于用户共同行为的物品相似度，效果优于传统协同过滤
输出: i2i_swing_YYYYMMDD.txt

✅ Session Word2Vec

文件: offline_tasks/scripts/i2i_session_w2v.py
来源: 改写自 graphembedding/session_w2v/
特点: 基于用户会话序列训练Word2Vec，捕获序列关系
输出: i2i_session_w2v_YYYYMMDD.txt + 模型文件

✅ DeepWalk

文件: offline_tasks/scripts/i2i_deepwalk.py
来源: 改写自 graphembedding/deepwalk/deepwalk.py
特点: 基于图随机游走训练Word2Vec，发现图结构特征
输出: i2i_deepwalk_YYYYMMDD.txt + 模型文件

2. 兴趣点聚合索引
按照指定的key生成索引：
✅ 支持的维度Key

✅ 平台: PC/Mobile/App
✅ 国家/销售区域: US/UK/CN...
✅ 客户类型: retailer/wholesaler...
✅ 用户偏好的二级分类: category_level2
✅ 用户偏好的三级分类: category_level3

✅ 支持的List类型

✅ 热门 (hot): 基于最近180天的高交互商品
✅ 加购 (cart): 基于加购行为的高频商品
✅ 新品 (new): 基于商品创建时间的新品

✅ 时间衰减

最近2年数据
权重时间衰减（每30天衰减5%）

📁 项目结构
/home/tw/recommendation/
│
├── db_service.py                    # 数据库连接服务（共享）
├── requirements.txt                 # Python依赖包
│
├── offline_tasks/                   # 离线任务主目录
│   │
│   ├── config/
│   │   └── offline_config.py       # 配置文件
│   │
│   ├── scripts/
│   │   ├── i2i_swing.py            # ✅ Swing算法
│   │   ├── i2i_session_w2v.py      # ✅ Session W2V
│   │   ├── i2i_deepwalk.py         # ✅ DeepWalk
│   │   ├── interest_aggregation.py # ✅ 兴趣点聚合
│   │   └── load_index_to_redis.py  # Redis加载工具
│   │
│   ├── run_all.py                   # 统一调度脚本
│   ├── install.sh                   # 安装脚本
│   ├── test_connection.py           # 连接测试
│   ├── example_query_redis.py       # 查询示例
│   │
│   └── 文档/
│       ├── README.md                # 详细文档
│       ├── QUICKSTART.md            # 快速开始
│       ├── PROJECT_SUMMARY.md       # 项目总结
│       ├── STRUCTURE.md             # 目录结构
│       └── DELIVERY.md              # 交付文档
│
└── (原有代码参考)
    ├── item_sim.py                  # 参考的实现
    ├── collaboration/               # Swing算法参考
    └── graphembedding/              # 图嵌入算法参考

🚀 快速开始
步骤1: 安装依赖
cd /home/tw/recommendation/offline_tasks
bash install.sh

步骤2: 测试连接
python3 test_connection.py

步骤3: 运行离线任务
# 运行所有任务（推荐）
python3 run_all.py --lookback_days 730 --top_n 50

# 或单独运行
python3 scripts/i2i_swing.py --lookback_days 730 --top_n 50
python3 scripts/i2i_session_w2v.py --lookback_days 730 --top_n 50
python3 scripts/i2i_deepwalk.py --lookback_days 730 --top_n 50
python3 scripts/interest_aggregation.py --lookback_days 730 --top_n 1000

步骤4: 加载到Redis
python3 scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379

📊 输出示例
i2i相似度索引
item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,...

兴趣点聚合索引
platform:PC \t item_id1:score1,item_id2:score2,...
country:US \t item_id1:score1,item_id2:score2,...
customer_type:retailer \t item_id1:score1,item_id2:score2,...
category_level2:100 \t item_id1:score1,item_id2:score2,...
platform_country:PC_US \t item_id1:score1,item_id2:score2,...

🎬 业务场景映射
根据文档中的3个业务场景：
1. 首页猜你喜欢
使用: 兴趣点聚合索引
# 组合查询
interest:hot:platform_country:{platform}_{country}
interest:hot:customer_type:{customer_type}
interest:global:category_level2:{preferred_category}

2. 详情页的大家都在看
使用: i2i行为相似索引
# 查询相似商品
i2i:swing:{item_id}
i2i:session_w2v:{item_id}
i2i:deepwalk:{item_id}

3. 搜索结果页底部的供应商推荐
使用: 兴趣点聚合索引
# 按分类推荐
interest:global:category_level2:{category_id}
interest:hot:category_level3:{category_id}

⚙️ 核心特性

✅ 数据适配: 完全适配现有数据库（SelectDB）和表结构
✅ 时间衰减: 2年数据，近期行为权重更高
✅ 行为加权: 不同行为类型有不同权重（购买>联系工厂>加购>点击）
✅ 多维度: 支持单维度和组合维度查询
✅ 多算法: 3种i2i算法，可融合使用
✅ 可配置: 所有参数集中配置，便于调优
✅ 自动化: 统一调度，一键运行
✅ 文档完善: 提供完整的使用文档和示例

📚 详细文档

QUICKSTART.md: 5分钟快速上手
README.md: 完整的功能说明
PROJECT_SUMMARY.md: 技术架构和原理
STRUCTURE.md: 项目结构和数据流
DELIVERY.md: 交付清单和状态

🔧 定时任务
建议设置crontab每天运行：
# 每天凌晨2点运行离线任务
0 2 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 run_all.py >> logs/cron.log 2>&1

# 凌晨6点加载到Redis
0 6 * * * cd /home/tw/recommendation/offline_tasks && /usr/bin/python3 scripts/load_index_to_redis.py >> logs/load_redis.log 2>&1

📈 性能参考
基于100万条用户行为数据：


任务
时间
内存


Swing
2-4小时
4-8GB


Session W2V
30-60分钟
2-4GB


DeepWalk
1-2小时
2-4GB


兴趣点聚合
30-60分钟
2-4GB


✨ 与原有代码的关系
本项目是对以下原有代码的改写和扩展：


item_sim.py → 数据格式参考，保持一致性
collaboration/src/swing.cc → 改写为Python版本的 i2i_swing.py
graphembedding/session_w2v/ → 改写为 i2i_session_w2v.py
graphembedding/deepwalk/ → 改写为 i2i_deepwalk.py
hot/main.py → 参考其聚合逻辑，扩展为多维度的 interest_aggregation.py


所有改写都保持了与现有数据格式的兼容性。
🎉 交付状态
状态: ✅ 已完成并可用

所有功能已实现、测试并文档化。可以立即部署使用。


目录: /home/tw/recommendation/offline_tasks/

入口: run_all.py

文档: QUICKSTART.md

日期: 2025-10-16