gnudevx/Recommendation-System

🤖 AI Recommendation System

<div align="center">

Hệ thống Recommendation thông minh sử dụng Semantic Embedding + Vector Similarity Search cho bài toán gợi ý việc làm IT

Demo · Report Bug · Contributing

</div>

📋 Mục lục

• —Tổng quan dự án
• —Tính năng nổi bật
• —Tech Stack
• —Kiến trúc hệ thống
• —Luồng recommendation
• —Cấu trúc thư mục
• —Giải thích thành phần
• —Cài đặt & Chạy dự án
• —API Documentation
• —Design Patterns
• —Challenges & Solutions

🎯 Tổng quan dự án

AI Recommendation System là hệ thống recommendation thông minh giúp phân tích CV, vector hóa dữ liệu và tính toán semantic similarity nhằm gợi ý việc làm IT phù hợp với kỹ năng, kinh nghiệm và địa điểm của người dùng.

Hệ thống sử dụng:

• —Sentence Transformers Embedding
• —Cosine Similarity
• —Vector-based Recommendation
• —CV Parsing Pipeline
• —Semantic Matching

Mục tiêu của dự án là cải thiện độ chính xác recommendation so với phương pháp keyword matching truyền thống.

🧠 Vấn đề được giải quyết

✨ Tính năng nổi bật

• —📄 CV Parsing & Processing
• —🔍 Semantic Job Recommendation
• —🧩 Vector Embedding Similarity Search
• —📍 Location-aware Recommendation
• —⚡ Fast Similarity Calculation
• —🐳 Dockerized Deployment
• —📊 Structured Recommendation Pipeline
• —🔄 Modular AI Processing Scripts

🛠 Tech Stack

Core Framework

AI / Machine Learning

Database & Infrastructure

🏗 Kiến trúc hệ thống

┌────────────────────────────────────────────────────┐
│                CLIENT / FRONTEND                  │
└──────────────────────┬────────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────────┐
│               FASTAPI APPLICATION                 │
│                                                    │
│   ┌─────────────┐      ┌────────────────────┐      │
│   │  Upload CV  │      │ Recommendation API │      │
│   └──────┬──────┘      └──────────┬─────────┘      │
└──────────│────────────────────────│────────────────┘
           │                        │
           ▼                        ▼
┌──────────────────┐      ┌─────────────────────────┐
│  CV Processing   │      │ Similarity Calculation │
│  Pipeline        │      │ Cosine Similarity      │
└────────┬─────────┘      └──────────┬──────────────┘
         │                           │
         ▼                           ▼
┌────────────────────────────────────────────────────┐
│         Sentence Transformer Embeddings            │
└──────────────────────┬─────────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────────┐
│                    MongoDB                        │
│        CV Data + Job Data + Embeddings           │
└────────────────────────────────────────────────────┘

🔄 Luồng Recommendation

CV Recommendation Pipeline

CV Upload
    │
    ▼
Text Extraction
    │
    ▼
Data Cleaning
    │
    ▼
Skill Extraction
    │
    ▼
Experience Parsing
    │
    ▼
Location Normalization
    │
    ▼
Embedding Generation
    │
    ▼
Similarity Matching
    │
    ▼
Top-K Job Recommendation

Semantic Matching Workflow

User CV
    │
    ▼
Sentence Transformer
    │
    ▼
Vector Embedding
    │
    ▼
Cosine Similarity
    │
    ▼
Ranking Algorithm
    │
    ▼
Recommended Jobs

📁 Cấu trúc thư mục

Recommendation-System/
│
├── .dockerignore
├── .gitignore
│
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── README.md
│
├── CV_based.py
├── cv_utils.py
├── cv_embedding_update.py
├── job_embedding_update.py
├── migrate_jobs.py
└── cities.py

🔍 Giải thích thành phần

CV_based.py — Main Recommendation API

File trung tâm của hệ thống recommendation.

Chức năng:

• —Upload & xử lý CV
• —Recommendation pipeline
• —Similarity matching
• —API endpoints
• —Response generation

cv_utils.py — CV Processing Utilities

Chứa các utility functions:

• —Extract text từ PDF
• —Skill extraction
• —Experience parsing
• —Text preprocessing
• —Data normalization

cv_embedding_update.py — CV Embedding Pipeline

Sinh vector embeddings cho CV.

embedding = model.encode(cv_text)

Embedding giúp hệ thống hiểu semantic meaning thay vì keyword matching đơn thuần.

job_embedding_update.py — Job Embedding Pipeline

Tạo embeddings cho job descriptions để phục vụ recommendation.

Workflow:

Job Description
      │
      ▼
Text Cleaning
      │
      ▼
Embedding Generation
      │
      ▼
Store Embedding

migrate_jobs.py — Data Migration Script

Script phục vụ:

• —Import jobs
• —Data preprocessing
• —Data normalization
• —Database migration

cities.py — Location Matching Logic

Xử lý location normalization và city matching.

Ví dụ:

TP.HCM
Ho Chi Minh
HCM

→ Ho Chi Minh City

Giúp recommendation theo location chính xác hơn.

🚀 Cài đặt & Chạy dự án

Yêu cầu

• —Python 3.11+
• —MongoDB
• —Docker & Docker Compose

1. Clone repository

git clone https://github.com/ohure1297/Recommendation-System.git

cd Recommendation-System

2. Tạo virtual environment

python -m venv venv

3. Activate environment

Windows

venv\Scripts\activate

Linux / macOS

source venv/bin/activate

4. Install dependencies

pip install -r requirements.txt

5. Chạy hệ thống

uvicorn CV_based:app --reload

6. Chạy bằng Docker

docker-compose up --build

📡 API Documentation

Sau khi chạy server:

http://localhost:8010/docs

🔌 API Endpoints

GET /

Health check endpoint.

Response:

{
  "message": "Recommendation API Running"
}

POST /recommend

Request:

{
  "cv_text": "Python backend developer with 3 years experience"
}

Response:

{
  "recommendations": [
    {
      "job_title": "Backend Developer",
      "similarity_score": 0.91
    }
  ]
}

🎨 Design Patterns

1. Modular Script-based Architecture

Hệ thống được tổ chức theo từng processing modules riêng biệt:

• —CV processing
• —Embedding generation
• —Similarity calculation
• —Recommendation ranking

Giúp dễ maintain và mở rộng pipeline.

2. Separation of Concerns

3. Vector-based Recommendation

Recommendation dựa trên:

Semantic Similarity

thay vì keyword matching truyền thống.

💡 Challenges & Solutions

📈 Future Improvements

• —[ ] Hybrid Recommendation System
• —[ ] Deep Learning Ranking Model
• —[ ] Real-time Recommendation
• —[ ] Recommendation Analytics Dashboard
• —[ ] Kubernetes Deployment
• —[ ] CI/CD Pipeline
• —[ ] Multi-language Recommendation
• —[ ] Distributed Vector Search

👤 Author

Ohure1297

GitHub: https://github.com/ohure1297