README.md

---
license: apache-2.0
library_name: pytorch
pipeline_tag: image-classification
tags:
  - resnet50
  - diabetic-retinopathy
  - medical-imaging
  - retinal-fundus
  - classification
datasets:
  - eyepacs
  - aptos2019-blindness-detection
  - messidor-2
metrics:
  - accuracy
  - f1
  - roc_auc
language:
  - vi
  - en
model-index:
  - name: ResNet-50 Baseline (Diabetic Retinopathy)
    results:
      - task:
          type: image-classification
          name: Diabetic Retinopathy Classification
        metrics:
          - type: accuracy
            name: Quadratic Weighted Kappa
            value: 0.8120
          - type: f1
            name: Macro F1-Score
            value: 0.4817
---

# Cấu trúc Mô hình AI — ResNet-50 Baseline (Diabetic Retinopathy Classification)

Tài liệu chi tiết về kiến trúc mô hình AI, cấu hình huấn luyện, dòng chảy dữ liệu (data flow) và hướng dẫn đóng gói suy luận (inference packaging) cho bài toán **Phân loại Mức độ Bệnh Võng mạc Tiểu đường (DR - 5 lớp ICDR)** bằng mô hình **ResNet-50**.

---

## 1. Tổng quan Mô hình

| Thông số | Giá trị |
|---|---|
| **Tên mô hình** | `ResNet50_DR` |
| **Bài toán** | Phân loại 5 mức độ bệnh Võng mạc Tiểu đường (ICDR Standard) |
| **Backbone** | `ResNet-50` (Pretrained ImageNet) |
| **Số tham số (Parameters)** | ~23.5M |
| **Kích thước đầu vào** | `3 × 224 × 224` |
| **Đầu ra** | 5 logits / xác suất (Probabilities via Softmax) |
| **Đánh giá chính** | Quadratic Weighted Kappa (`QWK`), Macro `F1-Score`, `ROC-AUC` |

---

## 2. Các Lớp Đầu Ra (Target Classes)

Mô hình dự đoán 5 mức độ tổn thương võng mạc tiểu đường theo tiêu chuẩn quốc tế ICDR:

| Class ID | Tên nhãn (Label Name) | Mô tả lâm sàng |
|:---:|---|---|
| **0** | `No DR` | Không phát hiện tổn thương DR |
| **1** | `Mild` | Xuất hiện vi phình mạch (Microaneurysms) |
| **2** | `Moderate` | Xuất hiện xuất huyết / xuất tiết nhẹ-vừa |
| **3** | `Severe` | Xuất huyết nặng 4 góc phần tư / chuỗi tĩnh mạch |
| **4** | `Proliferative DR` | Tăng sinh tân mạch / xuất huyết dịch kính |

---

## 3. Cấu trúc File Checkpoint (`.pth`)

File checkpoint `modelAI_ResNet50/resnet50_baseline_fold1.pth` lưu trữ dưới dạng PyTorch dictionary:

```python
checkpoint = {
    "epoch": 20,                                 # Epoch đạt kết quả tốt nhất
    "model_state_dict": model.state_dict(),     # Trọng số tất cả các layer ResNet-50
    "optimizer_state_dict": optimizer.state_dict(),
    "val_f1": 0.4817,                            # Macro F1 trên tập Validation
}
```

---

## 4. Hướng dẫn Đóng gói Mô hình Suy luận (Inference Packaging Guide)

### 4.1. Cấu trúc thư mục

```text
modelAI_ResNet50/
├── README.md                              # Tài liệu cấu hình & kiến trúc (File này)
├── resnet50_baseline_fold1.pth            # File trọng số PyTorch checkpoint ResNet-50
├── config.json                            # Cấu hình nhãn & tiền xử lý
├── model.py                               # Lớp PyTorch ResNet50_DR
├── preprocessing.py                       # Pipeline tiền xử lý ảnh
├── predictor.py                           # Class DRPredictor chính để gọi suy luận
├── gradcam_visualizer.py                  # Script & module sinh bản đồ nhiệt Grad-CAM
├── main_api.py                            # REST API Server với FastAPI (hỗ trợ Grad-CAM)
├── requirements.txt                       # Danh sách thư viện phụ thuộc
├── docs/                                  # Tài liệu HTML/MD chi tiết
└── hf_space/                              # Gradio UI App cho Hugging Face Space
```

---

### 4.2. Các REST API Endpoints hỗ trợ cho Web / Mobile

| Endpoint | Method | Trả về | Mục đích sử dụng |
|---|:---:|---|---|
| `/api/predict` | `POST` | `JSON` | Chẩn đoán 5 mức độ bệnh + bảng xác suất `probabilities`. |
| `/api/predict_gradcam` | `POST` | `JSON` | Chẩn đoán + bảng xác suất + chuỗi Base64 ảnh Grad-CAM sạch (`gradcam_image_base64`) + lời khuyên lâm sàng. |
| `/api/predict_gradcam_image` | `POST` | `PNG Image` | Trực tiếp file ảnh PNG chứa Grad-CAM heatmap (xem nhanh trên Swagger UI). |

---

## 5. Yêu cầu Môi trường (Dependencies)

File `requirements.txt`:

```text
torch>=2.0.0
torchvision>=0.15.0
Pillow>=9.5.0
numpy>=1.24.0
opencv-python>=4.7.0
fastapi>=0.95.0
uvicorn>=0.22.0
```