Dự án FACE_ID là giải pháp chấm công và quản lý nhân sự thời gian thực thông minh dựa trên trí tuệ nhân tạo (AI). Hệ thống kết hợp các mô hình Mạng Nơ-ron Sâu (Deep Neural Networks) trích xuất đặc trưng khuôn mặt cùng với động cơ tìm kiếm không gian vector tốc độ cao FAISS (Facebook AI Similarity Search).
Repository GitHub: https://github.com/Ximoncute/FACE_ID.git
- Tính Năng Nổi Bật
- Kiến Trúc & Thuật Toán AI
- Công Nghệ Sử Dụng
- Hướng Dẫn Khởi Chạy Nhanh (1-Click Start)
- Hướng Dẫn Cài Đặt Chi Tiết (Thủ Công)
- Tài Liệu Chi Tiết Về API (API Documentation)
- Hướng Dẫn Xem Cơ Sở Dữ Liệu (Database View Guide)
- Cấu Trúc Thư Mục Dự Án
- Xử Lý Sự Cố Thường Gặp (Troubleshooting)
- 🧬 Trích xuất Đa Mô hình (Multi-Model Feature Extraction): Khi đăng ký nhân viên mới, hệ thống tự động chạy qua 3 mô hình học sâu hàng đầu là Facenet512, ArcFace, và VGG-Face để tạo cơ sở dữ liệu véc-tơ đa dạng.
- ⚡ Tìm kiếm Vector Siêu tốc với FAISS: Sử dụng thuật toán
faiss.IndexFlatL2kết hợp chuẩn hóa khoảng cách$L_2$ (Unit-length Normalization) giúp việc so khớp khuôn mặt diễn ra trong dưới 1ms cho hàng triệu bản ghi. - 📷 Chấm công thời gian thực qua Webcam: Quét ảnh từ Webcam với tần số cao, tự động lọc và cắt vùng mặt bằng OpenCV Haar Cascade chuẩn.
- 📊 Biểu đồ Phân tích & Benchmark (Analytics): Tích hợp Chart.js để trực quan hóa thời gian xử lý và độ sai lệch (Confidence Score / Distance) giữa các mô hình AI khác nhau.
- 💎 Giao diện Glassmorphism Sang trọng: Thiết kế giao diện hiện đại trên nền React 19 + Vite, tối ưu trải nghiệm người dùng trên máy tính và thiết bị di động.
- 🚀 Script Khởi chạy 1-Click: Tích hợp sẵn
run.bat(Windows) vàrun.sh(macOS / Linux) tự động cài đặt và chạy cả Backend lẫn Frontend.
graph TD
A[Webcam / Frame Base64] -->|POST /register hoặc /checkin| B(FastAPI Backend)
B --> C[OpenCV Face Detection]
C --> D[DeepFace Embeddings Extraction]
D --> E[L2 Vector Normalization]
E --> F{Hành động?}
F -->|Đăng ký /register| G[Lưu SQLite DB & Thêm vào FAISS Index]
F -->|Chấm công /checkin| H[FAISS Index Search L2 Distance]
H --> I[So sánh Threshold & Ghi nhận Attendance Log]
I --> J[Trả kết quả JSON về React Frontend]
Tất cả các vector đặc trưng sau khi trích xuất đều được đưa về độ dài đơn vị (Unit Vector:
| Mô hình AI | Kích thước Vector (Dimensions) | Ngưỡng khoảng cách ( |
Đặc điểm |
|---|---|---|---|
| Facenet512 | 512 |
1.15 |
Độ chính xác cao nhất, đề xuất sử dụng chính |
| ArcFace | 512 |
1.20 |
Tối ưu hóa góc nghiêng và ánh sáng |
| VGG-Face | 4096 |
1.25 |
Tốc độ xử lý nhanh |
- Core Framework:
FastAPI(Python 3.10+) - Server Engine:
Uvicornvới ASGI protocol - AI / Deep Learning:
DeepFace,TensorFlow,tf-keras - Computer Vision:
OpenCV(opencv-python 4.8.1.78) - Vector Search Database:
faiss-cpu(Facebook AI Similarity Search) - Database & ORM:
SQLite,SQLAlchemy,Pydantic v2
- UI Framework:
React 19 - Build Tool:
Vite 8 - Webcam Stream:
react-webcam - Charts & Graphics:
chart.js,react-chartjs-2 - HTTP Client:
axios
Chỉ cần mở thư mục dự án và click đúp chuột vào file run.bat (hoặc chạy trong PowerShell):
.\run.batScript sẽ tự động bật 2 cửa sổ Command Prompt cho Backend (
http://127.0.0.1:8000) và Frontend (http://localhost:5173).
Mở Terminal tại thư mục dự án và chạy câu lệnh:
chmod +x run.sh
./run.shScript
run.shsẽ tự kiểm tra môi trường ảovenv, cài đặt thư viện thiếu nếu cần, sau đó chạy ngầm cả Backend và Frontend song song. NhấnCtrl+Cđể dừng tất cả dịch vụ.
Nếu bạn muốn tùy chỉnh môi trường hoặc chạy riêng lẻ từng phần:
# 1. Chuyển vào thư mục backend
cd backend
# 2. Tạo môi trường ảo Python venv
python3 -m venv venv
# 3. Kích hoạt môi trường ảo
# Trên Windows:
.\venv\Scripts\activate
# Trên macOS / Linux:
source venv/bin/activate
# 4. Cài đặt tất cả các thư viện cần thiết (đã tự động khóa numpy<2 & opencv<5)
pip install -r requirements.txt
# 6. Chạy Backend Server với Host 127.0.0.1
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload📍 Backend Swagger UI: http://127.0.0.1:8000/docs
# 1. Mở terminal riêng và chuyển vào thư mục frontend
cd frontend
# 2. Cài đặt các gói phụ thuộc NPM
npm install
# 3. Chạy môi trường phát triển Vite
npm run dev📍 Frontend Web App: http://localhost:5173
- Content-Type:
multipart/form-data - Body Params:
name(string): Tên nhân viên.image(string): Chuỗi base64 của ảnh đại diện chụp từ camera (data:image/jpeg;base64,...).
- Phản hồi mẫu (200 OK):
{ "id": 1, "name": "Nguyễn Văn A", "created_at": "2026-07-29T04:50:00" }
- Content-Type:
multipart/form-data - Body Params:
image(string): Ảnh base64 cần điểm danh.model_name(string): Thuật toán sử dụng (Facenet512,ArcFace, hoặcVGG-Face).
- Phản hồi mẫu (200 OK):
{ "user_id": 1, "name": "Nguyễn Văn A", "confidence": 0.4215, "model_used": "Facenet512", "time_taken_ms": 185.4 }
- Phản hồi mẫu: Danh sách 50 lượt chấm công mới nhất.
- Phản hồi mẫu: Thời gian trích xuất trung bình (ms) của từng mô hình AI.
Cơ sở dữ liệu của hệ thống được lưu trữ dưới dạng SQLite tại đường dẫn: backend/attendance.db (chứa 3 bảng chính: users, face_embeddings, attendance_logs).
Dưới đây là 3 cách đơn giản để xem và truy vấn dữ liệu:
- DB Browser for SQLite (Miễn phí & Nhẹ): Tải tại https://sqlitebrowser.org/, nhấn Open Database và chọn file
backend/attendance.db. - VS Code / Antigravity IDE Extension: Cài đặt extension SQLite Viewer, sau đó click đúp trực tiếp vào file
backend/attendance.dbđể xem bảng dữ liệu.
Mở Terminal và thực hiện câu lệnh:
python backend/view_db.py
# Hoặc trên Windows venv:
.\backend\venv\Scripts\python.exe backend\view_db.pyScript sẽ tự động in danh sách Nhân viên (
users), Vector đặc trưng (face_embeddings) và Lịch sử chấm công (attendance_logs) dạng bảng sạch sẽ.
Khi Backend đang chạy (http://127.0.0.1:8000), truy cập đường dẫn API Docs:
- URL: http://127.0.0.1:8000/docs
- Tìm endpoint
GET /logs➔ nhấn Try it out ➔ Execute để xem dữ liệu JSON phản hồi trực tiếp.
FACE_ID/
├── backend/
│ ├── app/
│ │ ├── core/
│ │ │ ├── ai_models.py # Trích xuất vector đặc trưng DeepFace & L2 Normalize
│ │ │ ├── vector_search.py # Quản lý FAISS Index & Tự động khớp kích thước Vector
│ │ │ └── evaluator.py # Benchmark các mô hình AI
│ │ ├── database.py # Khởi tạo SQLite connection & Session
│ │ ├── models.py # SQLAlchemy DB Models (User, FaceEmbedding, AttendanceLog)
│ │ ├── schemas.py # Pydantic Schemas (Request/Response)
│ │ └── main.py # FastAPI App & Endpoints
│ ├── attendance.db # Cơ sở dữ liệu SQLite (Tự động khởi tạo)
│ └── requirements.txt # Danh sách thư viện Python
├── frontend/
│ ├── src/
│ │ ├── pages/
│ │ │ ├── Register.jsx # Giao diện Đăng ký nhân viên mới
│ │ │ ├── CheckIn.jsx # Giao diện Chấm công trực tiếp qua Webcam
│ │ │ └── Analytics.jsx # Giao diện Biểu đồ phân tích hiệu năng
│ │ ├── App.jsx # Navigation & Layout
│ │ └── main.jsx # Entry point React
│ ├── package.json # NPM Dependencies
│ └── vite.config.js
├── run.bat # Script 1-Click trên Windows
├── run.sh # Script 1-Click trên macOS / Linux
├── .gitignore # Bỏ qua node_modules, venv, pycache, .db
└── README.md # Tài liệu hướng dẫn dự án
- Nguyên nhân: Frontend gọi tới
localhost:8000nhưng trên Windows,localhostphân giải IPv6 (::1) trong khi Uvicorn lắng nghe IPv4 (127.0.0.1). - Giải pháp: Tất cả file Frontend đã được cập nhật đường dẫn chuẩn:
http://127.0.0.1:8000. Đảm bảo cửa sổ Backend đã bật và hiển thị:Uvicorn running on http://127.0.0.1:8000.
- Nguyên nhân: Mô hình
VGG-Facetrong các bản DeepFace gần đây xuất ra vector kích thước 4096 thay vì 2622. - Giải pháp: File
vector_search.pyđã tích hợp cơ chế tự động phát hiện số chiều (Auto-adapt dimensions) cho FAISS Index nên lỗi này đã được xử lý triệt để.
- Nguyên nhân: Do cài đặt đồng thời cả
opencv-pythonvàopencv-python-headlesshoặc nâng cấp nhầm OpenCV 5.x (numpy>=2). - Giải pháp: Đã được xử lý tự động trong
run.bat/run.sh/requirements.txt. Nếu chạy thủ công, gỡ sạch OpenCV bằngpip uninstall -y opencv-python opencv-python-headlesssau đó chạypip install -r requirements.txt.
- Tác giả: Ximoncute
- Repository: https://github.com/Ximoncute/FACE_ID.git
- Giấy phép: Phát hành theo giấy phép MIT License.