# RecSys_erdos

**Repository Path**: cheng-yuling/RecSys_erdos

## Basic Information

- **Project Name**: RecSys_erdos
- **Description**: recsys4erdos
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-26
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 女装推荐系统

基于深度学习的智能女装推荐系统，采用双塔模型架构，结合BGE-m3文本嵌入技术，提供个性化商品推荐服务。

## 项目概览

本系统是一个完整的推荐系统解决方案，支持多种推荐算法和召回策略，特别针对女装电商场景进行了优化。系统采用模块化设计，易于扩展和维护。

### 核心特性

- **多算法支持**：协同过滤、基于内容的推荐、图卷积网络（GCN）、双塔模型
- **深度学习架构**：基于PyTorch的双塔神经网络模型
- **文本嵌入**：集成BGE-m3模型，支持中文语义理解
- **向量检索**：使用FAISS进行高效的相似度搜索
- **实时推荐**：基于FastAPI的高性能推荐服务
- **多路召回**：支持用户相似度、产品相似度、双塔模型等多种召回策略
- **冷启动处理**：针对新用户提供热门商品推荐
- **多样性优化**：支持推荐结果的多样性增强

### 技术栈

- **深度学习框架**: PyTorch 1.9+
- **NLP模型**: Transformers, Sentence-Transformers, BGE-m3
- **Web框架**: FastAPI 0.68+
- **数据库**: PostgreSQL（通过SSH隧道连接）
- **向量检索**: FAISS
- **数据处理**: Pandas, NumPy, Scikit-learn
- **API服务器**: Uvicorn

## 项目结构

```
RecSys_erdos/
├── src/                          # 源代码目录
│   ├── api/                      # API接口模块
│   │   ├── __init__.py
│   │   └── main.py              # FastAPI主应用，提供推荐API
│   ├── core/                     # 核心算法模块
│   │   ├── algorithms/          # 推荐算法实现
│   │   │   ├── base.py         # 算法基类
│   │   │   ├── collaborative_filtering.py  # 协同过滤
│   │   │   ├── content_based.py # 基于内容的推荐
│   │   │   ├── dual_tower_model.py  # 双塔模型
│   │   │   ├── gcn_recommender.py  # 图卷积网络
│   │   │   ├── hybrid_recommender.py  # 混合推荐
│   │   │   └── cold_start_handler.py  # 冷启动处理
│   │   ├── tuning/              # 参数调优模块
│   │   │   └── parameter_tuner.py
│   │   ├── base.py              # 基础类
│   │   ├── two_tower_trainer.py # 双塔模型训练器
│   │   ├── recommendation_system.py  # 推荐系统核心
│   │   ├── train_two_tower_model.py  # 双塔模型训练脚本
│   │   ├── embeddings.py        # 嵌入向量生成
│   │   ├── cache_service.py     # 缓存服务
│   │   ├── model_version_manager.py  # 模型版本管理
│   │   └── query_rewriter.py    # 查询重写
│   ├── data/                     # 数据处理模块
│   │   ├── __init__.py
│   │   ├── database.py          # 数据库连接和查询
│   │   ├── data_processor.py    # 数据预处理
│   │   └── data_loader.py       # 数据加载器
│   ├── models/                   # 模型定义模块
│   │   ├── __init__.py
│   │   ├── two_tower_model.py   # 双塔神经网络模型
│   │   └── neural_models.py     # 神经网络模型
│   ├── utils/                    # 工具函数模块
│   │   ├── __init__.py
│   │   ├── logger.py            # 日志工具
│   │   └── helpers.py           # 辅助函数
│   ├── integration/              # 集成模块
│   │   └── multipath_recall.py # 多路召回
│   ├── config.py                # 配置文件
│   └── train_model.py           # 模型训练脚本
├── models/                       # 训练好的模型目录
│   └── two_tower_20251225_123122/  # 双塔模型实例
│       ├── final_model.pt       # 最终模型
│       └── train_config.json    # 训练配置
├── data/                         # 数据文件目录
│   ├── 24FW女装产品梳理-4.8_url版.xlsx  # 产品数据
│   ├── member_basic_info.csv    # 会员基础信息
│   ├── member_tags.csv          # 会员标签
│   └── 会员订单记录.xlsx        # 订单记录
├── logs/                         # 日志文件目录
├── evaluation_results/           # 评估结果目录
├── tuning_results/               # 调优结果目录
├── requirements.txt              # Python依赖清单
├── .gitignore                   # Git忽略文件
└── README.md                    # 项目说明文档
```

## 快速开始

### 1. 环境要求

- Python 3.7+
- CUDA 10.2+（可选，用于GPU加速）
- PostgreSQL数据库访问权限

### 2. 安装依赖

```bash
# 克隆项目
cd /bigdata/JMT/RecSys_erdos

# 安装Python依赖
pip install -r requirements.txt
```

主要依赖包括：
- torch >= 1.9.0
- transformers >= 4.20.0
- sentence-transformers >= 2.2.0
- fastapi >= 0.68.0
- uvicorn >= 0.15.0
- pandas >= 1.3.0
- numpy >= 1.21.0
- scikit-learn >= 1.0.0
- psycopg2-binary >= 2.9.0
- sshtunnel >= 0.4.0

### 3. 配置环境

编辑 `src/config.py` 文件，配置数据库连接和模型路径：

```python
# 数据库配置
DATABASE_CONFIG = {
    'db_host': 'your_db_host',
    'db_port': 5432,
    'db_name': 'your_db_name',
    'db_user': 'your_db_user',
    'db_password': 'your_db_password',
    'ssh_host': 'your_ssh_host',
    'ssh_port': 2221,
    'ssh_username': 'your_ssh_username',
    'ssh_password': 'your_ssh_password'
}

# 推荐系统配置
RECOMMENDATION_CONFIG = {
    'embedding_dim': 1024,  # BGE-m3模型输出维度
    'use_bge_model': True,
    'bge_model_name': 'BAAI/bge-m3',
    'two_tower_enabled': True,
    'two_tower_model_path': 'models/two_tower_20251225_123122/final_model.pt'
}
```

### 4. 启动服务

```bash
# 进入src目录
cd src

# 启动API服务
python -m uvicorn api.main:app --host 0.0.0.0 --port 6123
```

服务启动后，可以通过以下地址访问：
- API文档: `http://localhost:6123/docs`
- 健康检查: `http://localhost:6123/health`
- 推荐接口: `http://localhost:6123/api/recommendations`

## 使用说明

### API接口

#### 1. 获取推荐

**请求示例**：

```bash
curl -X POST "http://localhost:6123/api/recommendations" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "9354930",
    "query": "黑色连衣裙",
    "top_k": 10,
    "use_diversity_enhancement": true,
    "diversity_weight": 0.3,
    "recommendation_type": "comprehensive"
  }'
```

**请求参数**：

| 参数 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| user_id | string | 是 | 用户ID | "9354930" |
| query | string | 否 | 用户查询（可选） | "黑色连衣裙" |
| top_k | integer | 否 | 推荐数量，默认10 | 10 |
| use_diversity_enhancement | boolean | 否 | 是否使用多样性增强，默认true | true |
| diversity_weight | float | 否 | 多样性权重，范围0.0-1.0，默认0.3 | 0.3 |
| recommendation_type | string | 否 | 推荐类型：comprehensive/similar_users/similar_products，默认comprehensive | "comprehensive" |
| model_type | string | 否 | 模型类型：collaborative/content/hybrid/two_tower，默认hybrid | "hybrid" |

**响应示例**：

```json
{
  "success": true,
  "message": "推荐成功",
  "data": {
    "目标用户": "9354930",
    "推荐时间": "2025-12-25 14:30:00",
    "综合推荐": [
      {
        "商品编码": "ABC123",
        "商品名称": "羊绒连衣裙",
        "零售价": 2580.0,
        "PIC": "https://example.com/image1.jpg",
        "FAB": "100%羊绒",
        "颜色": "黑色",
        "推荐分数": 0.95,
        "产品类别": "裙装",
        "品牌": "某品牌",
        "价格区间": "2000-3000元",
        "图片信息": {
          "PIC": "https://example.com/image1.jpg"
        }
      }
    ]
  },
  "timestamp": "2025-12-25T14:30:00",
  "request_id": "req_20251225143000000"
}
```

#### 2. 健康检查

```bash
curl http://localhost:6123/health
```

**响应示例**：

```json
{
  "status": "healthy",
  "timestamp": "2025-12-25T14:30:00",
  "model_loaded": true,
  "total_users": 50000,
  "total_products": 10000
}
```

### 推荐类型说明

1. **comprehensive（综合推荐）**：结合用户相似度和产品相似度的混合推荐
2. **similar_users（基于相似用户）**：基于相似用户的购买历史推荐
3. **similar_products（基于相似产品）**：基于产品相似度推荐

### 多样性增强

系统支持推荐结果的多样性增强，通过调整 `diversity_weight` 参数控制多样性程度：
- `0.0`：不考虑多样性，完全基于相关性
- `0.3`：平衡相关性和多样性（推荐值）
- `1.0`：完全基于多样性

## 模型训练

### 训练双塔模型

系统提供了完整的双塔模型训练流程，支持自定义超参数。

#### 基础训练

```bash
cd src
python train_model.py
```

#### 自定义参数训练

编辑 `src/train_model.py` 文件中的 `main()` 函数，或直接调用 `train_two_tower_model()` 函数：

```python
from train_model import train_two_tower_model

model_path = train_two_tower_model(
    embedding_dim=1024,      # 嵌入维度，与BGE-m3输出一致
    learning_rate=0.0005,    # 学习率
    batch_size=256,          # 批次大小
    num_epochs=30,          # 训练轮数
    num_workers=8,          # 数据加载线程数
    loss_type='contrastive'  # 损失函数类型
)
```

#### 训练参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| embedding_dim | int | 1024 | 嵌入向量维度 |
| learning_rate | float | 0.0005 | 学习率 |
| batch_size | int | 256 | 批次大小 |
| num_epochs | int | 30 | 训练轮数 |
| num_workers | int | 8 | 数据加载线程数 |
| loss_type | str | 'contrastive' | 损失函数类型：contrastive/bpr |
| sample_size | int | 20000 | 训练样本数量 |

#### 训练流程

1. **数据加载**：从数据库加载产品、用户标签、用户信息和订单数据
2. **特征提取**：使用BGE-m3模型生成用户和产品的嵌入向量
3. **负样本生成**：采用流行度加权的负采样策略
4. **模型训练**：使用对比学习损失函数训练双塔模型
5. **模型评估**：在验证集上评估模型性能
6. **模型保存**：保存训练好的模型和配置

#### 训练输出

训练完成后，模型会保存到 `models/two_tower_YYYYMMDD_HHMMSS/` 目录：
- `final_model.pt`：训练好的模型权重
- `train_config.json`：训练配置记录

#### 训练监控

训练过程中会输出详细的日志信息：

```
============================================================
开始训练双塔模型
============================================================
1. 加载数据...
   产品数据: 10000 条记录
   用户标签: 50000 条记录
   用户信息: 50000 条记录
   用户订单: 200000 条记录
2. 初始化推荐系统...
3. 处理交互数据...
4. 创建用户和产品嵌入...
5. 准备训练数据...
   共提取 20000 条用户-产品交互记录
   训练集: 16000 条记录
   验证集: 4000 条记录
6. 初始化训练器...
   训练设备: cuda
   模型架构: TwoTowerModel(
     (user_tower): UserTower(...)
     (product_tower): ProductTower(...)
   )
7. 生成负样本...
   训练集(含负样本): 160000 条记录
   验证集(含负样本): 40000 条记录
8. 提取特征...
   训练集特征: 160000 条
   验证集特征: 40000 条
9. 开始训练...
============================================================
Epoch 1/30
============================================================
Train Loss: 0.6523
Val Loss: 0.6234
Val Precision: 0.6845
Val Recall: 0.6234
Val NDCG: 0.7123
Val Hit Rate@10: 0.4567
Val Precision@10: 0.4234
Val NDCG@10: 0.5123
...
============================================================
训练完成，共完成 30 个epoch
============================================================
10. 保存模型...
   模型已保存到: models/two_tower_20251225_123122/final_model.pt
============================================================
双塔模型训练完成
============================================================
```

## 模型优化

### 优化策略

#### 1. 损失函数优化

系统实现了优化的对比学习损失函数（InfoNCE风格）：

```python
def contrastive_loss(user_embeddings, product_embeddings, labels, temperature=0.1):
    """
    优化的对比学习损失函数
    
    - 正样本：使用InfoNCE损失，最大化正样本对的相似度
    - 负样本：使用margin-based loss，确保负样本对相似度低于阈值
    - 温度参数：控制分布平滑程度（推荐值0.1）
    """
```

**优化要点**：
- 分离正负样本处理，提高训练稳定性
- 使用margin-based loss约束负样本
- 温度参数从0.05调整到0.1，更稳定的训练动态

#### 2. 超参数调优

**学习率**：
- 初始值：0.001 → 优化后：0.0005
- 使用AdamW优化器，添加权重衰减（0.001）

**批次大小**：
- 初始值：512 → 优化后：256
- 提高梯度质量，避免内存溢出

**训练轮数**：
- 推荐值：30 epochs
- 使用余弦退火学习率调度

**隐藏层维度**：
- 用户塔：[768, 512, 256]
- 产品塔：[768, 512, 256]
- 适配BGE-m3的1024维嵌入向量

#### 3. 负采样策略

系统采用流行度加权的负采样策略：

```python
def generate_negative_samples(self, positive_pairs, all_products, num_negatives=5):
    """
    流行度加权负采样
    
    - 根据产品流行度计算采样概率
    - 流行度高的产品更可能被选为负样本
    - 提高模型对难负样本的学习能力
    """
```

**优势**：
- 提高负样本质量
- 加速模型收敛
- 提升推荐准确性

#### 4. 训练技巧

**梯度裁剪**：
```python
self.grad_clip = 5.0  # 防止梯度爆炸
```

**学习率调度**：
```python
self.scheduler = optim.lr_scheduler.CosineAnnealingLR(
    self.optimizer,
    T_max=num_epochs,
    eta_min=learning_rate * 0.01
)
```

**Dropout正则化**：
```python
layers.append(nn.Dropout(0.2))  # 防止过拟合
```

### 性能指标

系统支持多种评估指标：

- **AUC**：曲线下面积
- **Precision**：精确率
- **Recall**：召回率
- **NDCG**：归一化折损累计增益
- **Hit Rate@K**：Top-K命中率
- **Precision@K**：Top-K精确率
- **NDCG@K**：Top-K NDCG

### 优化建议

1. **数据质量**：
   - 清洗异常数据
   - 处理缺失值
   - 特征标准化

2. **模型架构**：
   - 根据数据规模调整隐藏层维度
   - 尝试不同的激活函数
   - 增加注意力机制

3. **训练策略**：
   - 使用早停法（Early Stopping）
   - 实施模型集成
   - 采用交叉验证

4. **部署优化**：
   - 模型量化
   - 推理加速
   - 缓存策略

## 系统架构

### 推荐流程

```
用户请求
    ↓
用户画像提取
    ↓
多路召回
    ├── 用户相似度召回
    ├── 产品相似度召回
    └── 双塔模型召回
    ↓
精排
    ↓
多样性优化
    ↓
结果返回
```

### 核心模块

#### 1. 推荐系统核心（recommendation_system.py）

主要类：`ProductBasedRecommendationSystem`

核心功能：
- 用户画像构建
- 产品嵌入生成
- 多路召回策略
- 推荐结果排序
- 多样性优化

#### 2. 双塔模型（two_tower_model.py）

主要类：
- `UserTower`：用户塔网络
- `ProductTower`：产品塔网络
- `TwoTowerModel`：双塔模型

特点：
- 注意力机制
- 残差连接
- L2归一化

#### 3. 训练器（two_tower_trainer.py）

主要类：`TwoTowerTrainer`

功能：
- 模型训练
- 模型评估
- 模型保存
- 学习率调度

#### 4. API服务（api/main.py）

主要端点：
- `POST /api/recommendations`：获取推荐
- `GET /health`：健康检查
- `GET /`：服务状态

## 常见问题

### 1. 如何更换模型？

编辑 `src/config.py`，更新 `two_tower_model_path`：

```python
RECOMMENDATION_CONFIG = {
    'two_tower_model_path': 'models/your_new_model/final_model.pt'
}
```

### 2. 如何调整推荐策略？

修改 `RECOMMENDATION_CONFIG` 中的权重参数：

```python
RECOMMENDATION_CONFIG = {
    'collaborative_weight': 0.6,  # 协同过滤权重
    'content_weight': 0.4,       # 基于内容权重
    'diversity_weight': 0.3      # 多样性权重
}
```

### 3. 如何处理新用户？

系统会自动检测新用户，返回热门商品推荐。无需额外配置。

### 4. 如何监控训练过程？

训练过程会输出详细的日志信息，包括：
- 每个epoch的训练损失和验证损失
- 各项评估指标
- 模型保存路径

### 5. 如何使用GPU加速？

确保安装了CUDA版本的PyTorch，训练器会自动检测并使用GPU：

```python
device = 'cuda' if torch.cuda.is_available() else 'cpu'
```

## 性能优化建议

### 1. 数据库优化

- 使用索引加速查询
- 定期清理历史数据
- 考虑使用数据库连接池

### 2. 缓存策略

系统内置了缓存服务，可以缓存：
- 用户画像
- 产品嵌入
- 推荐结果

### 3. 批量处理

对于批量推荐请求，可以使用批量API接口提高效率。

### 4. 模型量化

考虑对训练好的模型进行量化，减少模型大小和推理时间。

## 开发指南

### 添加新的推荐算法

1. 在 `src/core/algorithms/` 下创建新的算法文件
2. 继承 `BaseRecommender` 基类
3. 实现 `recommend()` 方法
4. 在 `recommendation_system.py` 中注册新算法

### 自定义特征工程

编辑 `src/core/advanced_feature_engineering.py`，添加自定义特征提取逻辑。

### 扩展API接口

在 `src/api/main.py` 中添加新的API端点。

## 许可证

MIT License

## 联系方式

如有问题或建议，请提交Issue或联系项目维护者。

## 更新日志

### v1.0.0 (2025-12-25)
- 初始版本发布
- 实现双塔模型推荐
- 集成BGE-m3文本嵌入
- 支持多路召回策略
- 提供完整的API服务
- 实现模型训练和评估流程