README.md

metadata

title: Backend Project
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

🚀 Face Similarity API (FastAPI)

ยินดีต้อนรับสู่ระบบ Backend สำหรับวิเคราะห์และเปรียบเทียบใบหน้าครับ โปรเจกต์นี้ถูกออกแบบมาให้รันบน Hugging Face Spaces โดยใช้ Docker.

🛠️ Tech Stack

• Framework: FastAPI (Python 3.11).
• Database: SQLAlchemy (Raw SQL).
• Security: Argon2id & JWT Authentication.
• ML Models: ConvNeXt & InceptionV3.

💻 การพัฒนาและคำสั่งที่สำคัญ (Development Commands)

ในการพัฒนาโปรเจกต์นี้ เราใช้ uv สำหรับจัดการ Python environment และ dependencies:

1. การจัดการ Environment & Dependencies

• uv sync: ติดตั้ง dependencies ทั้งหมดที่ระบุในไฟล์ pyproject.toml.
• uv add <package>: เพิ่ม package ใหม่เข้าไปในโปรเจกต์.

2. การรันเซิร์ฟเวอร์ (Running Server)

• uv run uvicorn app.main:app --reload: รันเซิร์ฟเวอร์สำหรับพัฒนา (Development Server) โดยจะรีสตาร์ทอัตโนมัติเมื่อมีการแก้ไขโค้ด.
• --host 0.0.0.0 --port 8000: (ตัวเลือกเสริม) กำหนด host และ port.

3. การจัดการฐานข้อมูล (Database Migrations)

เราใช้ Alembic ในการควบคุมเวอร์ชันของฐานข้อมูล:

• alembic upgrade head: อัปเดตโครงสร้างฐานข้อมูล (Schema) ให้เป็นเวอร์ชันล่าสุด.
• alembic revision --autogenerate -m "comment": สร้างไฟล์ migration ใหม่โดยอัตโนมัติจากการตรวจสอบความเปลี่ยนแปลงใน models.
• alembic downgrade -1: ย้อนกลับโครงสร้างฐานข้อมูลไป 1 เวอร์ชัน.

4. การทดสอบ (Testing)

• pytest: รันการทดสอบทั้งหมดในโฟลเดอร์ tests/.

📁 โครงสร้างโปรเจกต์ (Project Structure)

• app/api/: จัดการ Endpoints และ API Logic ทั้งหมด แบ่งเป็นเวอร์ชัน (v1).
• app/crud/: ตรรกะการจัดการฐานข้อมูล (Create, Read, Update, Delete) โดยใช้ Raw SQL ร่วมกับ SQLAlchemy.
• app/models/: การนิยาม Schema ของตารางฐานข้อมูลด้วย SQLAlchemy Models.
• app/schemas/: การนิยาม Data Model สำหรับการรับ-ส่งข้อมูล (Validation) ด้วย Pydantic.
• app/services/: ส่วนการประมวลผลหลักของระบบ:
  • prediction_service.py: การทำ ML Inference ด้วย TensorFlow.
  • storage_service.py: การจัดการไฟล์บน Cloudflare R2 (S3 Compatible).
  • encoding_service.py: การแปลงข้อความเป็น Vector และในทางกลับกัน.
  • cosine_similarity_service.py: การคำนวณความคล้ายคลึงของใบหน้า.
• alembic/: เก็บไฟล์เวอร์ชันของฐานข้อมูล (Database Migration Scripts).
• tests/: ไฟล์สำหรับทดสอบระบบ (Unit & Integration Tests).

🌐 System URLs

• Live API (Production): https://jetsada117-backend-project.hf.space/
• Interactive Documentation (Scalar): https://jetsada117-backend-project.hf.space/scalar
• Alternative Documentation (Swagger UI): https://jetsada117-backend-project.hf.space//docs

📊 Data Structure (25-Dimensional Vector)

ระบบจะแปลงผลลัพธ์จากการทำนายหรือคำบรรยายให้กลายเป็น Vector ขนาด 25 มิติ เพื่อใช้คำนวณความคล้ายคลึง (Similarity Score):

• Age (6 มิติ): [2-6, 7-12, 13-25, 26-40, 41-65, 66+]
• Gender (2 มิติ): [ชาย, หญิง]
• Hair Color (3 มิติ): [ดำ, น้ำตาล, อื่นๆ]
• Hair Style (2 มิติ): [สั้น, ยาว]
• Eyebrows (4 มิติ): แยกตามรูปทรงคิ้ว
• Skin Tone (4 มิติ): แยกตามเฉดสีผิว
• Beard (4 มิติ): แยกตามลักษณะหนวดเครา

🔒 Security & Performance

• Authentication: ใช้ Argon2id ในการแฮชรหัสผ่านและ JWT (JSON Web Token) สำหรับการเข้าถึงทรัพยากร.
• OTP Verification: ระบบส่งรหัสยืนยันตัวตนผ่าน Gmail SMTP เพื่อความปลอดภัยในการสมัครสมาชิก.
• Cold Start Optimization: มีระบบ Dummy Inference เพื่อวอร์มโมเดล (Warm-up) ทำให้ลดเวลาการประมวลผลครั้งแรกจาก 35 วินาที เหลือเพียง 3-4 วินาที.

🛡️ Role-Based Access

• Admin: สามารถจัดการข้อมูลและดูสถิติทั้งหมดได้.
• User: สามารถใช้งานการทำนายและค้นหาใบหน้าที่คล้ายกันได้.