# api-search-recomond

**Repository Path**: theoliu/api-search-recomond

## Basic Information

- **Project Name**: api-search-recomond
- **Description**: 推荐系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Movie RecSys - 电影推荐系统

完整的工业级电影推荐系统实现，采用现代 Python 技术栈。

## 技术架构

### 核心技术栈
- **FastAPI** - 高性能异步 Web 框架
- **UV** - 超快的 Python 包管理器
- **DuckDB** - 嵌入式分析型数据库（特征存储）
- **Bytewax** - Python 原生流处理框架
- **Kafka** - 分布式消息队列（Mock 模式）

### 架构设计

```
原始数据 (MovieLens)
    ↓
离线处理 (Pandas + Scikit-learn)
    ├─ 特征工程
    ├─ Embedding 训练
    └─ 协同过滤
    ↓
特征存储 (DuckDB)
    ↓
近线处理 (Bytewax + Kafka Mock)
    ├─ 实时评分流
    └─ 特征更新
    ↓
在线服务 (FastAPI)
    ├─ 推荐 API
    ├─ 查询 API
    └─ 管理 API
    ↓
HTTP/JSON 接口
```

## 项目结构

```
api-search/
├── src/
│   ├── online/              # 在线服务层
│   │   ├── api/            # FastAPI 路由
│   │   ├── models/         # Pydantic 数据模型
│   │   ├── services/       # 业务逻辑
│   │   └── main.py         # 应用入口
│   ├── offline/            # 离线处理层
│   │   ├── feature_eng.py  # 特征工程
│   │   ├── embedding.py    # Embedding 训练
│   │   └── collaborative.py # 协同过滤
│   ├── nearline/           # 近线流处理层
│   │   ├── streaming.py    # Bytewax 流处理
│   │   └── kafka_mock.py   # Kafka Mock
│   ├── storage/            # 存储层
│   │   ├── duckdb_client.py # DuckDB 客户端
│   │   └── schemas.py      # 数据库 Schema
│   ├── recommender/        # 推荐算法
│   │   ├── similar.py      # 相似推荐
│   │   ├── collaborative.py # 协同过滤推荐
│   │   └── hybrid.py       # 混合推荐
│   └── config.py           # 配置管理
├── data/                   # 数据目录
│   ├── raw/               # 原始数据
│   ├── processed/         # 处理后数据
│   └── models/            # 模型文件
├── scripts/               # 脚本
│   ├── init_db.py        # 初始化数据库
│   ├── load_data.py      # 加载数据
│   └── train_models.py   # 训练模型
├── tests/                # 测试
└── pyproject.toml        # 项目配置
```

## 快速开始

### 1. 安装依赖

使用 UV（推荐）:
```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate  # Linux/Mac
uv pip install -e .
```

或使用 pip:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

### 2. 准备数据

下载 MovieLens 数据集并放置到 `data/raw/` 目录:
```bash
# 下载数据（示例）
wget https://files.grouplens.org/datasets/movielens/ml-latest-small.zip
unzip ml-latest-small.zip -d data/raw/
```

### 3. 初始化数据库

```bash
python scripts/init_db.py
python scripts/load_data.py
```

### 4. 训练模型（可选）

```bash
python scripts/train_models.py
```

### 5. 启动服务

```bash
# 启动在线服务
uvicorn src.online.main:app --reload --port 8000

# 启动流处理（另一个终端）
python -m src.nearline.streaming
```

### 6. 访问 API

- API 文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health
- 获取电影: http://localhost:8000/api/v1/movies/{movie_id}
- 相似推荐: http://localhost:8000/api/v1/recommend/similar/{movie_id}
- 个性化推荐: http://localhost:8000/api/v1/recommend/for-you/{user_id}

## API 接口

### 电影相关
- `GET /api/v1/movies/{movie_id}` - 获取电影详情
- `GET /api/v1/movies` - 搜索电影
- `GET /api/v1/movies/genre/{genre}` - 按类型获取电影

### 用户相关
- `GET /api/v1/users/{user_id}` - 获取用户信息
- `GET /api/v1/users/{user_id}/ratings` - 获取用户评分

### 推荐相关
- `GET /api/v1/recommend/similar/{movie_id}` - 相似电影推荐
- `GET /api/v1/recommend/for-you/{user_id}` - 个性化推荐
- `GET /api/v1/recommend/popular` - 热门推荐
- `POST /api/v1/recommend/rate` - 提交评分

## 实现的推荐算法

1. **基于内容的推荐** - 使用电影特征（类型、标签等）
2. **协同过滤** - 基于用户-物品评分矩阵
3. **Item2Vec** - 物品向量化
4. **混合推荐** - 结合多种算法

## 特性

- ✅ 完整的三层架构（离线、近线、在线）
- ✅ 高性能异步 API（FastAPI）
- ✅ 嵌入式分析数据库（DuckDB）
- ✅ 流处理支持（Bytewax + Kafka Mock）
- ✅ 类型安全（Pydantic）
- ✅ 自动 API 文档（OpenAPI/Swagger）
- ✅ 结构化日志
- ✅ 配置管理
- ✅ 单元测试

## 开发

```bash
# 运行测试
pytest

# 代码格式化
black src/
ruff check src/ --fix

# 类型检查
mypy src/
```

## License

MIT License