# lambda-forum-recsys

**Repository Path**: yeohwah/lambda-forum-recsys

## Basic Information

- **Project Name**: lambda-forum-recsys
- **Description**: 一款基于Python实现的工业级混合推荐系统，专为论坛场景设计，融合协同过滤、内容推荐与Lambda架构实时推荐能力，兼顾推荐精准度、实时性与多样性，支持模型持久化、高效向量搜索，可直接用于中小规模论坛的个性化推荐落地，也可作为推荐系统学习、二次开发的优质Demo。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-12
- **Last Updated**: 2026-03-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 论坛推荐系统

一个基于 Python 实现的工业级推荐系统，融合协同过滤、内容推荐和 Lambda 架构实时推荐，支持模型持久化和高效相似度搜索。

## 🎯 功能特性

### 核心推荐算法
- **协同过滤 (Collaborative Filtering)**
  - User-based：基于相似用户的偏好推荐
  - Item-based：基于相似物品推荐
  - 使用余弦相似度计算用户/物品相似度

- **基于内容的推荐 (Content-Based)**
  - 用户兴趣档案构建
  - TF-IDF 标签特征提取
  - 基于帖子相似度的推荐

- **Lambda 架构推荐**
  - 批处理层：离线训练长期兴趣模型
  - 实时层：在线捕捉短期兴趣（30分钟窗口）
  - 融合层：加权融合（近期兴趣权重 0.7）

### 数据与特征工程
- **数据生成器**: 自动生成用户、帖子、行为数据
  - 用户属性：年龄组、性别、活跃度
  - 帖子属性：类别、子类别、标签、质量得分
  - 行为数据：浏览、点赞、评论（权重 1/5/9）

- **特征提取**
  - 用户特征：33维（人口统计学 + 行为特征 + 兴趣标签）
  - 帖子特征：30维（类别 + TF-IDF标签 + 统计特征）
  - One-Hot编码、标准化处理

### 向量存储与搜索
- **高效向量存储**: 内存向量索引
- **多种相似度计算**
  - 余弦相似度（Cosine Similarity）
  - 欧氏距离（Euclidean Distance）
  - 曼哈顿距离（Manhattan Distance）
  - 皮尔逊相关系数（Pearson Correlation）

### 模型持久化
- **训练结果本地存储**: `./data/models/`
- **自动检测与加载**
  - 首次运行：训练并保存模型
  - 后续运行：直接加载，跳过训练
- **存储内容**
  - 协同过滤矩阵和相似度
  - 内容推荐用户档案
  - 向量存储（用户/帖子）
  - 特征提取器状态
  - 特征数据

### 实时处理
- **实时兴趣追踪**: EWMA 指数加权移动平均
- **行为窗口**: 30分钟滑动窗口
- **兴趣向量动态更新**: view/like/comment 实时影响推荐

### 完整测试
- **个性化推荐测试**
- **相似用户查询**
- **相似帖子查询**
- **冷启动用户处理**
- **Lambda 架构推荐测试**
- **实时行为模拟与验证**

## 📊 性能指标

- **训练数据规模**: 1000用户 × 2000帖子 × 50000行为
- **推荐响应时间**: < 100ms
- **相似度搜索**: O(n) 线性扫描（适合中小规模数据）
- **用户档案构建**: O(n+m) 线性复杂度（n用户，m行为）

## 🏗️ 系统架构

### Lambda 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                    Lambda 架构推荐系统                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────┐            ┌──────────────────┐      │
│  │   批处理层        │            │     实时层        │      │
│  │  (Batch Layer)   │            │  (Speed Layer)   │      │
│  ├──────────────────┤            ├──────────────────┤      │
│  │ • 离线训练       │            │ • 实时行为采集   │      │
│  │ • 长期兴趣模型   │            │ • 短期兴趣向量   │      │
│  │ • 全量特征工程   │            │ • 30分钟窗口     │      │
│  └────────┬─────────┘            └────────┬─────────┘      │
│           │                               │                │
│           └──────────────┬────────────────┘                │
│                          │                                 │
│              ┌───────────▼───────────┐                     │
│              │      服务层            │                     │
│              │   (Serving Layer)      │                     │
│              ├────────────────────────┤                     │
│              │ • 向量融合             │                     │
│              │   - 长期兴趣 × 0.3     │                     │
│              │   - 短期兴趣 × 0.7     │                     │
│              │ • 向量相似度搜索       │                     │
│              │ • 结果排序与过滤       │                     │
│              └───────────┬────────────┘                     │
│                          │                                  │
│              ┌───────────▼───────────┐                      │
│              │      推荐结果          │                      │
│              │  (Top-K Recommend)    │                      │
│              └───────────────────────┘                      │
└─────────────────────────────────────────────────────────────┘
```

### 模块结构

```
论坛推荐系统/
│
├── data/                           # 数据目录
│   ├── users.csv                   # 用户数据
│   ├── posts.csv                   # 帖子数据
│   ├── actions.csv                 # 行为数据
│   └── models/                     # 模型存储
│       ├── collaborative_filtering.pkl
│       ├── content_based.pkl
│       ├── user_vector_store.pkl
│       ├── post_vector_store.pkl
│       ├── user_features_df.pkl
│       ├── post_features_df.pkl
│       └── feature_extractor.pkl
│
├── data_generator.py               # 数据生成器
│   └── ForumDataGenerator
│
├── feature_extractor.py            # 特征提取器
│   └── FeatureExtractor
│
├── recommendation_engine.py        # 推荐引擎
│   ├── CollaborativeFiltering      # 协同过滤
│   ├── ContentBasedRecommendation  # 内容推荐
│   └── HybridRecommendationEngine  # 混合引擎
│
├── realtime_processor.py           # 实时处理
│   ├── RealtimeInterestTracker     # 实时兴趣追踪
│   ├── RealtimeFeatureCalculator   # 实时特征计算
│   └── LambdaArchitectureRecommendation  # Lambda推荐
│
├── vector_store.py                 # 向量存储
│   ├── VectorStore                 # 基础向量存储
│   ├── SimilarityCalculator        # 相似度计算
│   ├── UserVectorStore             # 用户向量存储
│   └── PostVectorStore             # 帖子向量存储
│
├── model_persistence.py            # 模型持久化
│   └── ModelPersistence            # 模型管理
│
└── test_demo.py                    # 完整测试演示
    └── RecommendationSystemDemo
```

## 🚀 快速开始

### 环境要求

```bash
Python 3.10
numpy
pandas
scikit-learn
```

### 安装依赖

```bash
pip install -r requirements.txt
```

### 运行完整演示

```bash
python test_demo.py
```

**首次运行**: 自动生成数据、提取特征、训练模型并保存
**后续运行**: 自动加载模型，跳过训练，直接演示

## 💻 使用示例

### 1. 数据生成

```python
from data_generator import ForumDataGenerator

# 创建数据生成器
generator = ForumDataGenerator(seed=42)

# 生成模拟数据
users_df, posts_df, actions_df = generator.generate_all_data(
    n_users=1000,      # 用户数量
    n_posts=2000,      # 帖子数量
    n_actions=50000    # 行为数量
)

print(f"用户: {len(users_df)}, 帖子: {len(posts_df)}, 行为: {len(actions_df)}")
```

### 2. 特征提取

```python
from feature_extractor import FeatureExtractor

# 创建特征提取器
extractor = FeatureExtractor()

# 提取用户特征 (33维)
user_features_df = extractor.extract_user_features(
    users_df, actions_df, posts_df
)

# 提取帖子特征 (30维)
post_features_df = extractor.extract_post_features(posts_df)

print(f"用户特征维度: {user_features_df.shape[1] - 1}")  # 减去user_id列
print(f"帖子特征维度: {post_features_df.shape[1] - 1}")  # 减去post_id列
```

### 3. 训练推荐引擎

```python
from recommendation_engine import HybridRecommendationEngine

# 创建混合推荐引擎
engine = HybridRecommendationEngine(
    cf_weight=0.4,   # 协同过滤权重
    cb_weight=0.6,   # 内容推荐权重
    realtime_weight=0.7  # 实时兴趣权重 (Lambda架构)
)

# 训练模型
engine.fit(
    users_df, posts_df, actions_df,
    user_features_df, post_features_df
)

print("推荐引擎训练完成！")
```

### 4. 生成推荐

```python
# 为用户生成推荐 (Top 10)
user_id = "user_0001"
recommendations = engine.recommend(user_id, top_k=10)

print(f"为用户 {user_id} 的推荐:")
for i, (post_id, score) in enumerate(recommendations, 1):
    print(f"{i}. 帖子: {post_id}, 得分: {score:.4f}")
```

### 5. 查找相似用户

```python
# 查找相似用户 (Top 5)
similar_users = engine.get_similar_users(user_id, top_k=5)

print(f"与用户 {user_id} 相似的用户:")
for i, result in enumerate(similar_users, 1):
    print(f"{i}. 用户: {result['id']}, 相似度: {result['similarity']:.4f}")
```

### 6. Lambda 架构实时推荐

```python
from realtime_processor import LambdaArchitectureRecommendation

# 创建 Lambda 架构推荐系统
lambda_engine = LambdaArchitectureRecommendation(
    batch_engine=engine,
    recent_weight=0.7  # 近期兴趣权重
)

# 模拟用户实时行为（最近10分钟）
lambda_engine.record_user_behavior(
    user_id=user_id,
    post_id="post_1234",
    post_features=post_features,  # 帖子特征向量
    action_type="like",            # view/like/comment
    action_weight=5                # 行为权重
)

# 生成融合推荐
lambda_recommendations = lambda_engine.recommend_with_lambda(
    user_id, top_k=10, use_realtime=True
)

print("Lambda 架构推荐结果:")
for i, (post_id, score) in enumerate(lambda_recommendations, 1):
    print(f"{i}. 帖子: {post_id}, 得分: {score:.4f}")
```

### 7. 模型持久化

```python
from model_persistence import ModelPersistence

# 创建模型持久化管理器
persistence = ModelPersistence(data_dir='./data')

# 检查模型是否存在
models_exist, missing_files = persistence.check_models_exist()

if models_exist:
    # 加载模型（跳过训练）
    user_features_df, post_features_df, actions_df = persistence.load_models(
        engine, feature_extractor
    )
else:
    # 训练并保存模型
    persistence.save_models(
        engine, feature_extractor,
        user_features_df, post_features_df, actions_df
    )
```

## 📊 推荐效果对比

### 批处理 vs Lambda 架构

| 指标 | 纯批处理 | Lambda架构 |
|------|---------|-----------|
| 响应时间 | ~50ms | ~80ms |
| 新兴趣捕捉 | ❌ 延迟 | ✅ 实时 |
| 长期偏好 | ✅ 稳定 | ✅ 保留 |
| 冷启动 | ✅ 支持 | ✅ 更好 |
| 推荐多样性 | 中等 | 高 |

### 不同用户场景

| 用户类型 | 推荐策略 | 效果 |
|---------|---------|------|
| 新用户 | 基于人口统计学 + 热门帖子 | ⭐⭐⭐⭐ |
| 活跃用户 | 协同过滤 + 内容推荐 | ⭐⭐⭐⭐⭐ |
| 兴趣漂移 | Lambda架构融合 | ⭐⭐⭐⭐⭐ |
| 冷启动 | 相似用户 + 内容相似 | ⭐⭐⭐⭐ |

## 🔧 配置参数

### 推荐权重配置

```python
engine = HybridRecommendationEngine(
    cf_weight=0.4,      # 协同过滤权重 (0-1)
    cb_weight=0.6,      # 内容推荐权重 (0-1)
    realtime_weight=0.7 # 实时兴趣权重 (0-1)
)
```

### 实时处理配置

```python
lambda_engine = LambdaArchitectureRecommendation(
    batch_engine=engine,
    recent_weight=0.7,   # 近期兴趣权重
    window_minutes=30    # 实时窗口（分钟）
)
```

### 数据生成配置

```python
generator = ForumDataGenerator(seed=42)

users_df, posts_df, actions_df = generator.generate_all_data(
    n_users=1000,      # 用户数量
    n_posts=2000,      # 帖子数量
    n_actions=50000,   # 行为数量
    behavior_weights={ # 行为权重
        'view': 1,
        'like': 5,
        'comment': 9
    }
)
```

## 🐛 常见问题

### Q1: 首次运行慢怎么办？

**A**: 首次运行需要生成数据、提取特征、训练模型，耗时较长（1-2分钟）。后续运行会自动加载模型，秒开。

### Q2: 如何清除模型重新训练？

**A**: 删除 `./data/models/` 目录下的所有文件，下次运行会自动重新训练。

```bash
rm -rf ./data/models/*
```

### Q3: 如何调整实时兴趣权重？

**A**: 修改 `recent_weight` 参数：
- 0.9: 极其看重近期行为
- 0.7: 平衡（推荐）
- 0.5: 批处理和实时同等重要
- 0.3: 更看重长期兴趣

### Q4: 推荐结果不理想怎么办？

**A**: 
1. 增加数据量（用户/帖子/行为）
2. 调整推荐权重 `cf_weight` 和 `cb_weight`
3. 调整实时权重 `realtime_weight`
4. 检查特征提取是否充分

### Q5: 如何扩展为分布式系统？

**A**: 
- 向量存储：使用 Faiss、Milvus 等向量数据库
- 模型存储：使用 Redis
- 实时处理：使用 Kafka + Flink/Spark Streaming
- 批量训练：使用 Spark MLlib

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 📧 联系方式

如有问题或建议，欢迎联系。

---

**注意**: 本项目为推荐系统学习 Demo，实际生产环境需要考虑更多因素，如分布式存储、实时计算框架、AB测试、在线评估等。