Face Recognition API - Vietnam Medical AI

Tổng quan

API nhận diện khuôn mặt sử dụng mô hình ResNet50 của PyTorch với GPU acceleration (RTX 3060 #1). Hỗ trợ đăng ký khuôn mặt, nhận diện theo thời gian thực, xử lý video và batch operations.

GPU Acceleration

ResNet50 trên RTX 3060 12GB, tự động fallback CPU

Video Processing

Trích xuất và nhận diện từ video, hỗ trợ FPS config

Batch Operations

Đăng ký / nhận diện hàng loạt, tối đa 10 ảnh/lần

Concurrent Requests

Semaphore giới hạn 3 request đồng thời, performance tracking

Thông tin kỹ thuật

Base URL

https://pnt.badt.vn/face_recognition/

Framework

FastAPI + Uvicorn

Model

ResNet50 (512-dim embeddings)

Face Detection

OpenCV Haar Cascades (CPU)

Database

MySQL (connection pooling)

Encoding

512-dim float vector

Max File Size

50 MB

Recognition Threshold

0.6 (cosine distance)

Authentication: API public nội bộ, yêu cầu kết nối từ nội bộ hệ thống qua Nginx proxy.

Endpoints

Tổng cộng 11 endpoints — tất cả đếu chạy trên port 8001, proxy qua /face_recognition/.

POST `/recognize_faces`

Nhận diện khuôn mặt trong ảnh tải lên. So sánh với cơ sở dữ liệu đã đăng ký, trả về tên và confidence score.

Tham số	Kiểu	Bắt buộc	Mô tả
`file`	UploadFile	Có	File ảnh (JPEG/PNG), tối đa 50MB
`confidence_threshold`	float	Không (mặc định 0.4)	Ngưỡng confidence tối thiểu

Xem response mẫu

{
  "success": true,
  "message": "Found 1 face(s)",
  "data": {
    "filename": "photo.jpg",
    "faces_detected": 1,
    "faces": [
      {
        "location": {"top": 50, "right": 200, "bottom": 250, "left": 80},
        "recognized": true,
        "person_name": "Nguyen Van A",
        "confidence": 0.87,
        "distance": 0.52
      }
    ],
    "processing_time_ms": 245.3,
    "device": "cuda:0"
  }
}

POST `/recognize_video`

Nhận diện khuôn mặt trong file video. Trích xuất frame theo FPS và nhận diện từng frame.

Tham số	Kiểu	Bắt buộc	Mô tả
`file`	UploadFile	Có	File video (MP4/AVI/MOV)
`fps`	int	Không (mặc định 5)	Số frame cần xử lý mỗi giây
`confidence_threshold`	float	Không (mặc định 0.4)	Ngưỡng confidence tối thiểu

Xem response mẫu

{
  "success": true,
  "message": "Processed 150 frames from video.mp4",
  "data": {
    "filename": "video.mp4",
    "total_frames": 150,
    "faces_found": 45,
    "recognitions": [
      {
        "frame": 12,
        "timestamp_sec": 2.4,
        "person_name": "Nguyen Van A",
        "confidence": 0.91
      }
    ],
    "processing_time_ms": 12450.6,
    "device": "cuda:0"
  }
}

POST `/register_person`

Đăng ký một người mới vào cơ sở dữ liệu khuôn mặt. Upload 1 ảnh có chứa khuôn mặt rõ ràng.

Tham số	Kiểu	Bắt buộc	Mô tả
`person_name`	string	Có	Tên người cần đăng ký
`file`	UploadFile	Có	File ảnh khuôn mặt (JPEG/PNG)

Xem response mẫu

{
  "success": true,
  "message": "Person registered successfully",
  "data": {
    "person_name": "Nguyen Van A",
    "encoding_dimensions": 512,
    "faces_detected": 1,
    "face_location": {"top": 50, "right": 200, "bottom": 250, "left": 80},
    "processing_time_ms": 156.7,
    "device": "cuda:0"
  }
}

POST `/register_batch`

Đăng ký nhiều ảnh cho cùng một người. Tối đa 10 ảnh/lần. Chỉ xử lý các ảnh có đúng 1 khuôn mặt.

Tham số	Kiểu	Bắt buộc	Mô tả
`person_name`	string	Có	Tên người cần đăng ký
`files`	List[UploadFile]	Có	Danh sách file ảnh (tối đa 10)

Xem response mẫu

{
  "success": true,
  "message": "Registered 5/8 images for Nguyen Van A",
  "data": {
    "person_name": "Nguyen Van A",
    "total_images": 8,
    "processed_images": 5,
    "skipped_images": 3,
    "average_encoding_size": 512,
    "processing_time_ms": 890.2,
    "device": "cuda:0"
  }
}

POST `/recognize_batch`

Nhận diện khuôn mặt từ nhiều ảnh cùng lúc. Trả về kết quả cho từng ảnh.

Tham số	Kiểu	Bắt buộc	Mô tả
`files`	List[UploadFile]	Có	Danh sách file ảnh cần nhận diện
`confidence_threshold`	float	Không (mặc định 0.4)	Ngưỡng confidence tối thiểu

GET `/`

Thông tin API — trả về version, device, danh sách features và endpoints.

Xem response mẫu

{
  "success": true,
  "message": "Face Recognition API - Production Ready",
  "data": {
    "version": "3.0.0",
    "device": "cuda:0",
    "features": [
      "GPU-accelerated face recognition",
      "Video frame extraction",
      "Batch processing",
      "Concurrent request handling",
      "Performance metrics"
    ],
    "endpoints": {
      "/": "API information",
      "/health": "Health check",
      "/status": "Server status and metrics",
      "/gpu_status": "GPU status",
      "/register_person": "Register new person",
      "/recognize_faces": "Recognize faces in image",
      "/recognize_video": "Recognize faces in video",
      "/register_batch": "Batch register",
      "/recognize_batch": "Batch recognize",
      "/list_persons": "List all registered persons",
      "/delete_person/{name}": "Delete a person"
    }
  }
}

GET `/health`

Kiểm tra sức khỏe dịch vụ — trả về trạng thái database, GPU, model.

Xem response mẫu

{
  "success": true,
  "message": "Service health check",
  "data": {
    "status": "healthy",
    "database": "connected",
    "gpu": "available",
    "device": "cuda:0",
    "model_loaded": true,
    "uptime_seconds": 86400,
    "active_requests": 2
  }
}

GET `/status`

Trạng thái server chi tiết — số lượng người đã đăng ký, thời gian xử lý trung bình, số request active.

Xem response mẫu

{
  "success": true,
  "message": "Server status",
  "data": {
    "registered_persons": 12,
    "device": "cuda:0",
    "active_requests": 1,
    "average_processing_time_ms": 210.5,
    "uptime_seconds": 86400,
    "concurrent_limit": 3
  }
}

GET `/gpu_status`

Thông tin GPU chi tiết — tên card, memory, utilization, temperature.

Xem response mẫu

{
  "success": true,
  "message": "GPU status retrieved",
  "data": {
    "available": true,
    "device": "cuda:0",
    "gpu_name": "NVIDIA GeForce RTX 3060",
    "memory_total_mb": 12288,
    "memory_used_mb": 2048,
    "memory_free_mb": 10240,
    "utilization_percent": 15.0,
    "temperature_celsius": 52
  }
}

GET `/list_persons`

Liệt kê tất cả người đã đăng ký trong cơ sở dữ liệu.

Xem response mẫu

{
  "success": true,
  "message": "Found 12 registered person(s)",
  "data": {
    "persons": [
      {"name": "Nguyen Van A", "email": null, "pid": null, "encoding_dimensions": 512},
      {"name": "Tran Thi B", "email": null, "pid": null, "encoding_dimensions": 512}
    ],
    "total_count": 12
  }
}

DELETE `/delete_person/{name}`

Xóa một người khỏi cơ sở dữ liệu khuôn mặt theo tên.

Tham số	Kiểu	Bắt buộc	Mô tả
`name`	string	Có	Tên người cần xóa (path parameter)

Xem response mẫu

{
  "success": true,
  "message": "Person 'Nguyen Van A' deleted successfully"
}

Ví dợ sử dụng

cURL

# Nhận diện khuôn mặt
curl -s -X POST "https://pnt.badt.vn/face_recognition/recognize_faces" \
  -F "file=@photo.jpg" \
  -F "confidence_threshold=0.4" | jq .

# Đăng ký người mới
curl -s -X POST "https://pnt.badt.vn/face_recognition/register_person" \
  -F "person_name=Nguyen Van A" \
  -F "file=@face.jpg" | jq .

# Danh sách người đã đăng ký
curl -s "https://pnt.badt.vn/face_recognition/list_persons" | jq .

# Xóa người
curl -s -X DELETE "https://pnt.badt.vn/face_recognition/delete_person/Nguyen%20Van%20A" | jq .

# Xử lý video
curl -s -X POST "https://pnt.badt.vn/face_recognition/recognize_video" \
  -F "file=@meeting.mp4" \
  -F "fps=10" | jq .

# Batch Đăng ký (tối đa 10 ảnh)
curl -s -X POST "https://pnt.badt.vn/face_recognition/register_batch" \
  -F "person_name=Nguyen Van A" \
  -F "files=@face1.jpg" \
  -F "files=@face2.jpg" \
  -F "files=@face3.jpg" | jq .

Python (requests)

import requests

BASE = "https://pnt.badt.vn/face_recognition"

# Đăng ký
resp = requests.post(f"{BASE}/register_person", data={
    "person_name": "Nguyen Van A"
}, files={
    "file": open("face.jpg", "rb")
})
print(resp.json())

# Nhận diện
resp = requests.post(f"{BASE}/recognize_faces", files={
    "file": open("photo.jpg", "rb")
})
print(resp.json())

# Danh sách
resp = requests.get(f"{BASE}/list_persons")
print(resp.json())

JavaScript (fetch)

const BASE = "https://pnt.badt.vn/face_recognition";

// Nhận diện
const formData = new FormData();
formData.append("file", fileInput.files[0]);

const resp = await fetch(`${BASE}/recognize_faces`, {
  method: "POST",
  body: formData
});
const result = await resp.json();
console.log(result);

Ghi chú quan trọng

GPU sharing: Face Recognition App chạy chung GPU RTX 3060 #1 với DeepSeek OCR Service (dùng ~6-8GB tổng cộng trên 12GB VRAM).
Giới hạn đồng thời: Tối đa 3 request concurrent do semaphore, tránh quá tải GPU.
Face detection: Sử dụng OpenCV Haar Cascades trên CPU, không dùng GPU.
Video support: Yêu cầu thư viện imageio. Chỉ xử lý được nếu package đã được cài đặt.
Database: Kết nối MySQL với connection pooling, pool size mặc định là 5.
Endpoint docs: FastAPI tự động sinh docs tại https://pnt.badt.vn/face_recognition/docs (Swagger UI).

GPU-Enhanced Face Recognition API

Tổng quan

GPU Acceleration

Video Processing

Batch Operations

Concurrent Requests

Thông tin kỹ thuật

Endpoints

POST /recognize_faces

POST /recognize_video

POST /register_person

POST /register_batch

POST /recognize_batch

GET /

GET /health

GET /status

GET /gpu_status

GET /list_persons

DELETE /delete_person/{name}

Ví dợ sử dụng

cURL

Python (requests)

JavaScript (fetch)

Ghi chú quan trọng

POST `/recognize_faces`

POST `/recognize_video`

POST `/register_person`

POST `/register_batch`

POST `/recognize_batch`

GET `/`

GET `/health`

GET `/status`

GET `/gpu_status`

GET `/list_persons`

DELETE `/delete_person/{name}`