Matcher

🇻🇳 Tiếng Việt | 🇬🇧 English

---

Tiếng Việt

Giới thiệu

Matcher là ứng dụng AI giúp đánh giá và so sánh CV ứng viên với mô tả công việc (Job Description). Ứng dụng sử dụng các mô hình AI tiên tiến để phân tích và cho điểm mức độ phù hợp.

Tính năng

• ✅ Upload và quản lý CV (PDF, DOCX)
• ✅ Upload và quản lý JD (DOCX)
• ✅ Đánh giá tự động CV với JD bằng AI
• ✅ Quick Evaluate: Đánh giá nhanh CV mà không cần JD
• ✅ Hỗ trợ nhiều AI Provider: HuggingFace, Gemini, ChatGPT, DeepSeek
• ✅ Thêm tiêu chí đánh giá tùy chỉnh cho từng JD
• ✅ Xem lịch sử đánh giá
• ✅ Xuất báo cáo chi tiết

Cài đặt

Yêu cầu

• macOS: Không cần cài đặt trước! Matcher.app sẽ tự động cài Homebrew và Docker nếu chưa có.
• Windows: Cài đặt Docker Desktop
• Linux: Cài đặt Docker Engine & Docker Compose

🍎 Chạy nhanh (macOS) - Khuyên dùng

1. Double-click vào file matcher/Matcher.app
2. Ứng dụng sẽ tự động kiểm tra và cài đặt mọi thứ cần thiết (Homebrew, Docker).
   • Lưu ý: Nếu được hỏi mật khẩu, vui lòng nhập mật khẩu máy tính để cho phép cài đặt.
3. Chờ một chút, ứng dụng sẽ tự mở trình duyệt khi sẵn sàng!

Chạy bằng Terminal (Windows / Linux)

cd matcher
docker-compose up -d --build

Lệnh này sẽ khởi động 4 container:

• matcher-web: Web server (FastAPI)
• matcher-worker: Worker xử lý AI background
• matcher-redis: Redis queue
• matcher-postgres: Database

Bước 3: Truy cập ứng dụng

Mở trình duyệt và truy cập: http://localhost:8000

Các lệnh hữu ích khác

• Xem log (để debug):

  docker-compose logs -f

• Dừng ứng dụng:

  docker-compose down

• Restart ứng dụng (khi code thay đổi):

  docker-compose restart

---

🔑 Hướng dẫn lấy API Key HuggingFace (Miễn phí)

Bước 1: Đăng ký tài khoản

1. Truy cập https://huggingface.co/join
2. Điền thông tin và tạo tài khoản
3. Xác nhận email

Bước 2: Tạo Access Token

1. Đăng nhập vào https://huggingface.co
2. Click vào avatar góc phải → chọn Settings
3. Trong menu bên trái, chọn Access Tokens
4. Click nút New token (hoặc Create new token)
5. Đặt tên token (VD: cv-matcher)
6. Chọn Role: Read (đủ để sử dụng)
7. Click Generate token
8. Sao chép token (bắt đầu bằng hf_...) - Lưu ý: Token chỉ hiển thị 1 lần!

Bước 3: Cấu hình trong ứng dụng

1. Mở ứng dụng tại http://localhost:8000
2. Click AI Settings ở sidebar
3. Chọn Provider: HuggingFace
4. Chọn Model: deepseek-ai/DeepSeek-V3.2-Exp:novita (khuyến nghị vì thông minh và miễn phí)
5. Dán API Key vào ô
6. Click Test Connection để kiểm tra
7. Click Save để lưu

---

English

Introduction

Matcher is an AI-powered application that evaluates and compares candidate CVs with Job Descriptions. The application uses advanced AI models to analyze and score the compatibility level.

Features

• ✅ Upload and manage CVs (PDF, DOCX)
• ✅ Upload and manage JDs (DOCX)
• ✅ Automatic CV-JD evaluation using AI
• ✅ Quick Evaluate: Instantly evaluate CV without a JD
• ✅ Multiple AI Provider support: HuggingFace, Gemini, ChatGPT, DeepSeek
• ✅ Add custom evaluation criteria for each JD
• ✅ View evaluation history
• ✅ Export detailed reports

Installation

Requirements

• macOS: No pre-installation needed! Matcher.app will automatically install Homebrew and Docker if missing.
• Windows: Install Docker Desktop
• Linux: Install Docker Engine & Docker Compose

🍎 One-click Run (macOS) - Recommended

1. Double-click on matcher/Matcher.app
2. The app will automatically check and install missing dependencies (Homebrew, Docker).
   • Note: If asked, please enter your password to allow installation.
3. Wait a moment, the web interface will open automatically!

Manual Run (Windows / Linux)

We recommend using Docker to run the application anywhere.

Step 1: Clone the project

git clone <repository-url>
cd ListCV/matcher

Step 2: Run with Docker Compose

docker-compose up -d --build

This starts 4 containers:

• matcher-web: Web server (FastAPI)
• matcher-worker: Background AI worker
• matcher-redis: Redis queue
• matcher-postgres: Database

Step 3: Access the application

Open your browser and navigate to: http://localhost:8000

Useful Commands

• View logs (for debugging):

  docker-compose logs -f

• Stop application:

  docker-compose down

• Restart application (after code changes):

  docker-compose restart

---

🔑 How to Get HuggingFace API Key (Free)

Step 1: Create an account

1. Go to https://huggingface.co/join
2. Fill in your information and create an account
3. Verify your email

Step 2: Create Access Token

1. Log in to https://huggingface.co
2. Click on your avatar (top right) → select Settings
3. In the left menu, select Access Tokens
4. Click New token (or Create new token)
5. Name your token (e.g., cv-matcher)
6. Select Role: Read (sufficient for usage)
7. Click Generate token
8. Copy the token (starts with hf_...) - Note: Token is only shown once!

Step 3: Configure in the application

1. Open the app at http://localhost:8000
2. Click AI Settings in the sidebar
3. Select Provider: HuggingFace
4. Select Model: deepseek-ai/DeepSeek-V3.2-Exp:novita (recommended for best free performance)
5. Paste the API Key
6. Click Test Connection to verify
7. Click Save to save settings

---

📁 Project Structure

ListCV/
├── matcher/
│   ├── app/
│   │   ├── main.py           # FastAPI application
│   │   ├── worker.py         # Background job processor
│   │   ├── database.py       # Database models
│   │   └── ai_providers/     # AI provider implementations
│   ├── frontend/
│   │   ├── index.html        # Main comparison page
│   │   ├── jd-management.html
│   │   ├── cv-management.html
│   │   ├── history.html
│   ├── jd/                   # JD files storage
│   ├── cv/                   # CV files storage
│   └── reports/              # Generated reports
└── README.md

📄 License

MIT License

---

Made with ❤️ by DA Tools