chrisnguyenx/ResNet50-P3

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:

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

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
├── main_api.py                            # REST API Server với FastAPI
├── requirements.txt                       # Danh sách thư viện phụ thuộc
└── hf_space/                              # Gradio UI App cho Hugging Face Space

---

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

File requirements.txt:

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