# 推荐系统离线任务 - 项目总结

## 项目概述

本项目实现了一个完整的推荐系统离线任务框架，用于生成各种推荐索引。主要包括两大模块：

1. **i2i 行为相似索引**：基于用户行为计算物品之间的相似度
2. **兴趣点聚合索引**：按多维度聚合用户行为，生成不同场景的推荐列表

## 技术架构

### 数据来源
- 数据库：SelectDB（兼容MySQL协议）
- 主要表：
  - `sensors_events`：用户行为事件表
  - `prd_goods_sku`：商品SKU表

### 算法实现

#### 1. i2i 行为相似算法

| 算法 | 原理 | 优势 | 适用场景 |
|------|------|------|---------|
| **Swing** | 基于用户共同行为的物品相似度，考虑用户重叠度 | 效果好，能发现深层关系 | 详情页推荐、相关商品 |
| **Session W2V** | 基于用户会话序列训练Word2Vec | 能捕获序列关系 | 下一个可能感兴趣的商品 |
| **DeepWalk** | 基于图随机游走训练Word2Vec | 能发现图结构特征 | 发现潜在关联商品 |

#### 2. 兴趣点聚合

**维度分类：**

- **单维度**：
  - 平台（PC/Mobile/App）
  - 国家/销售区域
  - 客户类型（零售商/批发商等）
  - 二级分类
  - 三级分类

- **组合维度**：
  - 平台 + 国家
  - 平台 + 客户类型
  - 国家 + 客户类型
  - 平台 + 国家 + 客户类型

**列表类型：**

- **hot（热门）**：基于最近180天的高交互商品
- **cart（加购）**：基于加购行为的高频商品
- **new（新品）**：基于商品创建时间的新品
- **global（全局）**：基于所有数据的综合排序

## 核心特性

### 1. 时间衰减
- 使用指数衰减模型，越近期的行为权重越高
- 衰减因子：0.95（每30天衰减一次）
- 公式：`weight = decay_factor ^ (days / 30)`

### 2. 行为权重
不同行为类型赋予不同权重：

| 行为类型 | 权重 | 说明 |
|---------|------|------|
| click | 1.0 | 点击 |
| addToPool | 2.0 | 加入询盘池 |
| addToCart | 3.0 | 加入购物车 |
| contactFactory | 5.0 | 联系工厂 |
| purchase | 10.0 | 购买 |

### 3. 可配置参数
所有参数集中在 `config/offline_config.py`，便于调整优化。

## 文件清单

### 核心代码

```
/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                              # 统一调度脚本
    ├── test_connection.py                      # 连接测试脚本
    ├── example_query_redis.py                  # Redis查询示例
    ├── README.md                               # 详细文档
    ├── QUICKSTART.md                           # 快速启动指南
    └── PROJECT_SUMMARY.md                      # 本文档
```

### 输出目录

```
offline_tasks/
├── output/                                     # 索引输出目录
│   ├── i2i_swing_YYYYMMDD.txt
│   ├── i2i_session_w2v_YYYYMMDD.txt
│   ├── i2i_deepwalk_YYYYMMDD.txt
│   ├── session_w2v_model_YYYYMMDD.model       # W2V模型
│   ├── deepwalk_model_YYYYMMDD.model          # DeepWalk模型
│   ├── item_graph_YYYYMMDD.txt                # 物品图结构
│   ├── interest_aggregation_hot_YYYYMMDD.txt
│   ├── interest_aggregation_cart_YYYYMMDD.txt
│   ├── interest_aggregation_new_YYYYMMDD.txt
│   └── interest_aggregation_global_YYYYMMDD.txt
└── logs/                                       # 日志目录
    ├── run_all_YYYYMMDD.log
    └── ...
```

## 使用流程

### 1. 环境准备
```bash
pip install -r requirements.txt
```

### 2. 测试连接
```bash
cd offline_tasks
python test_connection.py
```

### 3. 运行离线任务
```bash
python run_all.py --lookback_days 730 --top_n 50
```

### 4. 加载索引到Redis
```bash
python scripts/load_index_to_redis.py --expire-days 7
```

### 5. 查询示例
```bash
python example_query_redis.py
```

## 数据格式

### i2i索引格式
```
item_id \t item_name \t similar_item_id1:score1,similar_item_id2:score2,...
```

示例：
```
123456 \t 商品A \t 234567:0.8523,345678:0.7842,456789:0.7234
```

### 兴趣点聚合索引格式
```
dimension_key \t item_id1:score1,item_id2:score2,...
```

示例：
```
platform:PC \t 12345:98.52,23456:87.34,34567:76.89
country:US \t 45678:156.23,56789:142.87,67890:128.45
platform_country:PC_US \t 78901:234.56,89012:198.76,90123:187.23
```

## 在线推荐场景

### 场景1：详情页 - 大家都在看
```
用户浏览商品ID: 123456
查询: i2i:swing:123456
返回: 该商品的相似商品列表
```

### 场景2：首页 - 猜你喜欢
```
用户特征: PC端, 美国, 零售商
组合查询:
1. interest:hot:platform_country:PC_US
2. interest:cart:customer_type:retailer
3. 结合用户历史行为的i2i
```

### 场景3：搜索结果页 - 供应商推荐
```
用户搜索: 二级分类100
查询: interest:global:category_level2:100
返回: 该分类下的热门商品
```

## 性能指标

### 数据量参考（730天数据）
- 用户行为记录：约100万-1000万条
- 商品数量：约10万-50万个
- 生成索引：约5万-20万条

### 运行时间（参考值）
- Swing算法：2-4小时
- Session W2V：30-60分钟
- DeepWalk：1-2小时
- 兴趣点聚合：30-60分钟
- 总计：约5-8小时

### 资源占用
- CPU：8-16核
- 内存：8-16GB
- 磁盘：输出文件约500MB-2GB

## 优化建议

### 1. 算法层面
- **Swing算法**：可以使用C++版本（已有实现），性能提升10倍
- **并行化**：将不同算法分配到不同机器并行运行
- **增量更新**：对于变化不大的索引，考虑增量更新

### 2. 工程层面
- **分布式计算**：使用Spark/Flink处理大规模数据
- **缓存中间结果**：避免重复计算
- **数据采样**：调试阶段使用采样数据

### 3. 业务层面
- **A/B测试**：对比不同算法的效果
- **融合策略**：组合多个算法的结果
- **实时更新**：结合实时计算补充离线索引

## 后续扩展

### 1. 新增算法
- ItemCF（物品协同过滤）
- Node2Vec（带权重的图游走）
- Graph Neural Network（图神经网络）

### 2. 新增维度
- 价格区间
- 品牌
- 标签组合
- 用户画像更多维度

### 3. 实时化
- 实时更新热门商品
- 实时更新新品列表
- 实时i2i相似度计算

### 4. 个性化
- 结合用户画像的个性化排序
- 多目标优化（点击率、转化率、GMV）
- 强化学习排序

## 维护说明

### 定期检查
- 每周检查日志，确保任务正常运行
- 每月检查索引质量，调整参数
- 每季度评估算法效果，优化策略

### 监控指标
- 任务执行成功率
- 索引生成数量
- Redis命中率
- 推荐点击率/转化率

## 联系方式

如有问题或建议，请联系推荐系统团队。

---

**文档版本**: v1.0  
**最后更新**: 2025-10-16  
**作者**: 推荐系统团队