--- title: AI Virtual Wardrobe emoji: 👕 colorFrom: pink colorTo: indigo sdk: docker app_port: 7860 pinned: false --- # AI Virtual Wardrobe Backend - Trợ lý Thời trang AI Phần phát triển Backend cho dự án **AI Virtual Wardrobe (Trợ lý thời trang cá nhân bằng AI)** sử dụng framework **FastAPI**, **Celery** để xử lý tác vụ bất đồng bộ, **PostgreSQL** lưu trữ dữ liệu quan hệ và **Qdrant** làm cơ sở dữ liệu vector cho công cụ tìm kiếm sản phẩm thời trang tương đồng. --- ## 1. Công nghệ Sử dụng (Tech Stack) * **Framework chính**: [FastAPI](https://fastapi.tiangolo.com/) (Python 3.11+) * **Hàng đợi & Xử lý bất đồng bộ**: [Celery](https://docs.celeryq.dev/) + [Redis](https://redis.io/) * **Cơ sở dữ liệu quan hệ**: [PostgreSQL](https://www.postgresql.org/) + [SQLAlchemy ORM](https://www.sqlalchemy.org/) * **Cơ sở dữ liệu Vector**: [Qdrant Vector DB](https://qdrant.tech/) * **Quản lý môi trường**: [uv](https://github.com/astral-sh/uv) (Trình quản lý package Python siêu tốc từ Astral) * **Bảo mật**: JWT (thông qua cookie HttpOnly), băm mật khẩu trực tiếp bằng thư viện `bcrypt`. * **AI SDK**: Google Gemini API (`google-generativeai`) cho công cụ gợi ý phối đồ. --- ## 2. Cấu trúc Dự án (Project Structure) ``` backend/ ├── app/ │ ├── api/ # Các Router API │ │ ├── v1/ # Phiên bản API v1 (auth, wardrobe, body, tryon, recommendations) │ │ ├── deps.py # Dependencies cho FastAPI (Xác thực JWT...) │ │ └── router.py # Điểm gom các router con │ ├── core/ # Cấu hình hệ thống, Database pool & Security │ │ ├── config.py # Pydantic Settings đọc cấu hình từ môi trường │ │ ├── database.py # Cấu hình SQLAlchemy engine & session │ │ └── security.py # Hashing password bằng bcrypt & xử lý mã hóa JWT │ ├── models/ # SQLAlchemy Database Models (Postgres tables) │ ├── schemas/ # Pydantic models để validate input/output dữ liệu │ ├── services/ # Lớp tích hợp dịch vụ bên ngoài (R2, Qdrant, Gemini) │ │ ├── llm_service.py # Dịch vụ gọi Gemini sinh gợi ý phối đồ │ │ ├── qdrant_client.py# Dịch vụ thêm/sửa/tìm kiếm vector trên Qdrant │ │ └── storage.py # Dịch vụ upload/delete tệp tin trên Cloudflare R2 │ ├── workers/ # Cấu hình Celery Workers xử lý AI nặng │ │ ├── celery_app.py # Thiết lập Celery │ │ └── tasks.py # Các tác vụ xử lý YOLOv11 + CLIP, SMPL, CatVTON │ └── main.py # Cổng chạy chính của API FastAPI ├── tests/ # Thư mục chứa các script kiểm thử tự động │ ├── conftest.py # Cấu hình pytest (SQLite Mock DB và Custom ARRAY compiler) │ └── test_auth.py # Các unit test cho Module Auth & Bảo mật ├── docker-compose.yml # Cấu hình PostgreSQL, Redis, Qdrant local ├── pyproject.toml # Quản lý project bằng uv ├── uv.lock # Lockfile chứa thông tin phiên bản dependencies chính xác └── requirements.txt # File mô tả các package bổ trợ ``` --- ## 3. Hướng dẫn Cài đặt & Chạy dưới Local ### Bước 1: Clone dự án và truy cập thư mục backend ```bash cd backend ``` ### Bước 2: Khởi động các dịch vụ cơ sở dữ liệu qua Docker Compose Đảm bảo bạn đã cài đặt Docker và Docker Compose. Khởi động PostgreSQL, Redis và Qdrant bằng lệnh: ```bash docker compose up -d ``` *Lưu ý*: Lệnh này sẽ chạy các cơ sở dữ liệu ở chế độ chạy ngầm (detached mode) trên các cổng: * PostgreSQL: `5432` * Redis: `6380` (Cổng mới để tránh xung đột với Redis sẵn có trên máy) * Qdrant: `6333` ### Bước 3: Tạo môi trường ảo và cài đặt dependencies bằng `uv` Nếu chưa có `uv`, bạn có thể cài đặt thông qua script chính thức hoặc pip. Sau đó chạy: ```bash # Tạo môi trường ảo (.venv) uv venv # Cài đặt tất cả các package đã mô tả trong pyproject.toml uv sync ``` ### Bước 4: Tạo cấu hình môi trường (.env) Tạo file `.env` tại thư mục `backend/` với cấu hình lưu trữ local như sau (không cần tài khoản Cloudflare R2): ```env # Xác thực (JWT) JWT_SECRET_KEY=94c8e79b294e09f5bb648cf496d66e816a0410ff10a5fcf47f22a57dc2095eb3 # Chế độ Lưu trữ: "local" (ưu tiên local không cần key) hoặc "r2" (đám mây Cloudflare) STORAGE_MODE=local UPLOAD_DIR=uploads SERVER_HOST_URL=http://localhost:8002 PORT=8002 # Các biến R2 chỉ cần thiết khi STORAGE_MODE=r2 (Tùy chọn) # R2_BUCKET_NAME=wardrobe-bucket # R2_ACCESS_KEY_ID=your_cloudflare_r2_access_key_id # R2_SECRET_ACCESS_KEY=your_cloudflare_r2_secret_access_key # R2_ENDPOINT_URL=https://your-account-id.r2.cloudflarestorage.com # PostgreSQL & Redis Local POSTGRES_SERVER=localhost POSTGRES_USER=postgres POSTGRES_PASSWORD=development_password_change_me POSTGRES_DB=wardrobe_db REDIS_HOST=localhost REDIS_PORT=6380 # Google Gemini API GEMINI_API_KEY=your_gemini_api_key_here ``` ### Bước 5: Chạy ứng dụng FastAPI *Lưu ý*: Bạn phải **truy cập vào thư mục `backend/`** trước khi chạy lệnh để tránh lỗi `ModuleNotFoundError: No module named 'app'`. Ngoài ra, cổng chạy mặc định được lấy từ biến môi trường `PORT` (mặc định là `8002`). ```bash cd backend # 1. Chạy nhanh nhất qua file wrapper (tự động đọc PORT, HOST, RELOAD từ .env) uv run python main.py # 2. Hoặc chạy thủ công qua uvicorn lấy PORT từ file .env: export $(grep -v '^#' .env | xargs) && uv run uvicorn app.main:app --host 0.0.0.0 --port $PORT --workers 4 ``` Sau khi chạy thành công: * Trang tài liệu API tự động (Swagger UI) sẽ có mặt tại: `http://127.0.0.1:8002/docs` * Tài liệu API dạng ReDoc: `http://127.0.0.1:8002/redoc` ### Bước 6: Khởi động Celery Worker (Để xử lý tác vụ AI bất đồng bộ) Mở một terminal mới và chạy lệnh sau từ thư mục `backend/` để lắng nghe các task xử lý ảnh/3D: ```bash cd backend uv run celery -A app.workers.celery_app worker --loglevel=info ``` ### Bước 7: Khởi chạy CatVTON Gradio Demo (Chạy thử đồ ảo cục bộ trên GPU) Tác vụ thử đồ ảo (Virtual Try-On) đã được tích hợp cục bộ qua mô hình **CatVTON** (`zhengchong/CatVTON`). Bạn có thể khởi chạy Gradio demo của CatVTON bằng GPU chỉ định trong `.env` (ví dụ: `CUDA_VISIBLE_DEVICES=2`): ```bash cd CatVTON CUDA_VISIBLE_DEVICES=2 ../backend/.venv/bin/python app.py \ --output_dir="resource/demo/output" \ --mixed_precision="bf16" \ --allow_tf32 ``` Giao diện Gradio sẽ hiển thị tại: `http://127.0.0.1:7860`. --- ## 4. Kiểm thử Tự động (Testing) Bộ kiểm thử của hệ thống sử dụng SQLite in-memory để chạy test nhanh chóng mà không cần kết nối tới database Postgres thật. Để khởi chạy toàn bộ unit tests, thực hiện lệnh (từ thư mục `backend/`): ```bash cd backend uv run python -m pytest tests/ ``` --- ## 5. Các biện pháp Bảo mật đã tích hợp (Security Measures) 1. **Phòng chống Directory Traversal (Tải file độc hại)**: * Tên file ảnh tải lên được định dạng lại hoàn toàn dưới dạng UUID ngẫu nhiên. * Sử dụng hàm `os.path.basename()` để bóc tách lọc bỏ mọi ký tự điều hướng thư mục (`../`, `..\`). * Xác thực chất lượng ảnh thông qua **Magic Bytes** để tránh việc người dùng đổi tên đuôi file độc hại (ví dụ: `script.sh` -> `script.png`) và tải lên máy chủ. 2. **Bảo mật JWT qua HttpOnly Cookie**: * JWT Token không được trả về body phản hồi hoặc lưu ở LocalStorage (để tránh bị đánh cắp qua tấn công XSS). * Token được ghi thẳng vào Cookie của trình duyệt với cấu hình `HttpOnly`, `Secure` và thuộc tính chống CSRF `SameSite=Lax`. 3. **Bảo mật Cơ sở dữ liệu**: * SQLAlchemy ORM tự động parameterized các tham số truyền vào câu lệnh SQL để loại bỏ hoàn toàn nguy cơ tấn công **SQL Injection**. * Exception handler toàn cục trong [main.py](file:///home/llm/MinhPV/AI_Virtual_Wardrobe/backend/app/main.py) sẽ bắt các lỗi phát sinh ngoài ý muốn và trả về thông báo lỗi chung thân thiện với người dùng, tuyệt đối không trả về Stack Trace chứa cấu trúc bảng hoặc câu lệnh SQL lỗi.