api/README.md

🎭 Facial Emotion Detection API

ตรวจจับอารมณ์จากใบหน้า 7 ประเภท โดยใช้ Quantized ONNX model
Model: dima806/facial_emotions_image_detection

---

โครงสร้างโปรเจค

project/
├── model_optimization/
│   ├── baseline_test.py       ← Step 1-2: baseline
│   ├── convert_onnx.py        ← Step 3: ONNX export
│   ├── quantize.py            ← Step 4: INT8 quantization
│   └── benchmark.py           ← Step 5: summary table
├── api/
│   ├── main.py                ← FastAPI app
│   ├── model_runner.py        ← ONNX inference (subprocess)
│   ├── schemas.py             ← Pydantic models
│   └── requirements.txt
├── tests/
│   ├── conftest.py
│   └── test_api.py            ← pytest unit tests
├── models/
│   └── onnx/
│       └── model_quantized.onnx
├── Dockerfile
└── .github/
    └── workflows/
        └── ci_cd.yml

---

Emotions ที่ตรวจจับได้

Label	ความหมาย
angry	โกรธ
disgust	รังเกียจ
fear	กลัว
happy	มีความสุข
neutral	เป็นกลาง
sad	เศร้า
surprise	แปลกใจ

---

รันแบบ Local

1. ติดตั้ง + เตรียมโมเดล

pip install "numpy==1.26.4" torch torchvision transformers onnx onnxruntime Pillow

cd model_optimization
python baseline_test.py
python convert_onnx.py
python quantize.py
python benchmark.py

2. รัน API

pip install -r api/requirements.txt
cd api
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

3. ทดสอบ

pip install pytest pytest-asyncio httpx
pytest tests/ -v

---

รันด้วย Docker

# Build
docker build -t emotion-api .

# Run
docker run -p 7860:7860 emotion-api

# Build พร้อมปรับ config
docker build --build-arg NUM_WORKERS=4 --build-arg MAX_FILE_SIZE_MB=10 -t emotion-api .

---

API Endpoints

Method	Path	Description
GET	/	API info
GET	/health	Health check + model status
POST	/predict	Predict emotion from image
GET	/docs	Swagger UI (interactive)

---

cURL Examples

Health Check

curl http://localhost:7860/health

Predict (Local)

curl -X POST http://localhost:7860/predict \
  -F "file=@/path/to/face.jpg" \
  -H "accept: application/json"

Predict (Cloud — Hugging Face Spaces)

curl -X POST https://<YOUR_HF_USERNAME>-<SPACE_NAME>.hf.space/predict \
  -F "file=@/path/to/face.jpg" \
  -H "accept: application/json"

ตัวอย่าง Response

{
  "predicted_emotion": "happy",
  "confidence": 0.9234,
  "all_scores": {
    "angry": 0.0121,
    "disgust": 0.0031,
    "fear": 0.0082,
    "happy": 0.9234,
    "neutral": 0.0412,
    "sad": 0.0071,
    "surprise": 0.0049
  },
  "inference_time_ms": 48.3
}

---

HTTP Status Codes

Code	เหตุ
200	สำเร็จ
400	ไฟล์ไม่ใช่รูปภาพ / ไฟล์เสีย / ไฟล์เปล่า
413	ไฟล์ใหญ่เกิน 5 MB
415	Content-Type ไม่ใช่รูปภาพ
422	ไม่ส่ง file field มา
500	Internal server error

---

Environment Variables

Variable	Default	Description
MODEL_PATH	models/onnx/model_quantized.onnx	Path to ONNX model
NUM_WORKERS	2	ProcessPool workers
MAX_FILE_SIZE_MB	5	Max upload size (MB)

---

CI/CD

GitHub Actions รัน 2 jobs:

1. test — รัน pytest ทุกครั้งที่ push (ทุก branch)
2. deploy — deploy ไป Hugging Face Spaces อัตโนมัติ เฉพาะ push ไป main และ test ผ่าน 100%

GitHub Secrets ที่ต้องตั้งค่า

Secret	ค่า
HF_TOKEN	Hugging Face Access Token
HF_USERNAME	HF username ของคุณ
HF_SPACE_NAME	ชื่อ Space บน Hugging Face