Mô tả Mô hình AI ResNet-50 & JSON Output API

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

Mô hình ResNet50_DR phục vụ chẩn đoán tự động tổn thương võng mạc ở bệnh nhân tiểu đường dựa trên ảnh chụp đáy mắt (Fundus Camera).

Mô tả Bài toán

Phân loại 5 cấp độ tổn thương theo Tiêu chuẩn Y tế Quốc tế ICDR (International Clinical Diabetic Retinopathy Disease Severity Scale).

Backbone ResNet-50

Sử dụng mạng ResNet-50 với 50 lớp trích xuất đặc trưng sâu và kết nối tắt residual shortcuts ($2048$ kênh đặc trưng đầu ra).

Đầu vào (Input)

Kích thước chuẩn 224 × 224 × 3. Hỗ trợ đa dạng định dạng: Đường dẫn File, Mảng Bytes, PIL Image, OpenCV Array.

Đầu ra (Output)

Vector 5 xác suất Softmax $\rightarrow$ Đóng gói thành File JSON chuẩn chứa Class ID, Confidence %, Lời khuyên Y tế & Ảnh Base64.

2. Kiến trúc Chi tiết (Model Architecture)

Mạng ResNet-50 sử dụng các khối Bottleneck Blocks giúp học đặc trưng phân cấp mạnh mẽ:

Conv1 & MaxPool Head

Lớp `Conv2d(7x7, stride=2)` và `MaxPool2d(3x3)` nén ban đầu từ 224x224 về 56x56 với 64 channels.

Layer 1 -> Layer 4 (Bottleneck Blocks)

4 tầng khối Residual Bottleneck với kênh đặc trưng tăng dần: 256 $\rightarrow$ 512 $\rightarrow$ 1024 $\rightarrow$ 2048 channels.

Global Average Pooling

AdaptiveAvgPool2d(1) nén đặc trưng không gian 7x7 về vector 1D chiều dài 2048.

Classifier Head

Dropout(p=0.3) $\rightarrow$ Linear(2048 -> 5) phân loại 5 nhãn bệnh ICDR.

3. Quy trình Tiền xử lý Ảnh (Preprocessing Pipeline)

Thực thi qua 5 bước trong preprocessing.py giúp nâng cao chất lượng chẩn đoán:

Bước	Tên Hàm Python	Chức năng Kỹ thuật
1	`load_image()`	Giải mã đa dạng đầu vào (Path, Byte array, PIL, BGR Array) về mảng OpenCV BGR `uint8`.
2	`crop_fundus_circle()`	Tự động tìm Bounding Box vùng sáng đáy mắt và crop loại bỏ hoàn toàn khung viền đen dư thừa.
3	`letterbox_resize()`	Resize ảnh về `224 × 224` giữ nguyên tỷ lệ Aspect Ratio (đệm viền đen), tránh làm méo dạng tổn thương.
4	`ben_graham_transform()`	Lọc nhiễu & tăng tương phản Ben Graham: $\text{Output} = 4 \times I - 4 \times \text{GaussianBlur}(I, \sigma=10) + 128$.
5	`prepare_image_tensor()`	Chuyển đổi sang PyTorch Tensor, chuẩn hóa ImageNet Mean `[0.485, 0.456, 0.406]` & Std `[0.229, 0.224, 0.225]`.

4. Quy trình Xử lý & Tạo ra File JSON

Khi ứng dụng Frontend gửi ảnh qua REST API POST /api/predict, máy chủ tiến hành các bước xử lý tạo JSON như sau:

Tiếp nhận Request & Đọc File

Trích xuất mảng Byte từ UploadFile do HTTP Client tải lên.

Suy luận PyTorch Tensor (Inference)

Đưa Tensor qua mô hình DRPredictor (ResNet50_DR), tính toán xác suất 5 lớp qua torch.softmax.

Mã hóa Ảnh Preprocessed sang Base64

Chuyển mảng OpenCV Ben Graham sang đuôi JPEG, sau đó encode Base64 dạng data:image/jpeg;base64,... để Frontend có thể hiển thị tức thì.

Ghép nối Clinical Guidance & Trả về JSON

Tra cứu bảng chỉ dẫn y tế theo class_id (Title, Advice, Urgency, Badge Color) và đóng gói kết quả JSON hoàn chỉnh.

5. Cấu trúc File JSON Output (JSON Specification)

Dưới đây là ví dụ cấu trúc dữ liệu JSON phản hồi chuẩn HTTP 200 OK khi chẩn đoán thành công một ảnh đáy mắt:

JSON REST API Response (`POST /api/predict`)

{
  "class_id": 0,
  "class_name": "No DR",
  "confidence": 0.9945334196090698,
  "probabilities": {
    "No DR": 0.9945334196090698,
    "Mild": 0.0008030196186155081,
    "Moderate": 0.0019999665673822165,
    "Severe": 0.0011487160809338093,
    "Proliferative DR": 0.0015149053651839495
  }
}

Mô tả Giải thích Trường Dữ liệu (Field Dictionary)

Tên Trường (Field)	Kiểu Dữ Liệu	Mô tả Chi tiết
`class_id`	`Integer`	Mã lớp mức độ bệnh từ `0` (Bình thường) đến `4` (Tăng sinh nguy hiểm).
`class_name`	`String`	Tên nhãn tiếng Anh theo chuẩn ICDR (`No DR`, `Mild`, `Moderate`, `Severe`, `Proliferative DR`).
`confidence`	`Float`	Giá trị độ tin cậy của mô hình cho nhãn dự đoán (xác suất thô từ 0.0 đến 1.0).
`probabilities`	`Object`	Map chứa xác suất phân bố cụ thể cho toàn bộ 5 lớp ICDR.

6. Danh mục Lời khuyên Y tế Lâm sàng (ICDR Standard)

Mô hình AI tự động quy đổi kết quả sang khuyến nghị y tế lâm sàng theo tiêu chuẩn 5 mức độ ICDR:

Class ID	Nhãn ICDR	Chẩn đoán Tiếng Việt	Mức độ Khẩn cấp	Badge Color UI
0	No DR	Mắt Bình Thường	Bình thường	#10b981 - Green
1	Mild	Bệnh Nhẹ	Theo dõi định kỳ	#3b82f6 - Blue
2	Moderate	Bệnh Trung Bình	Khám chuyên khoa	#f59e0b - Orange
3	Severe	Bệnh Nặng	Cần can thiệp sớm	#ef4444 - Red
4	Proliferative DR	Tăng Sinh Nguy Hiểm	KHẨN CẤP	#8b5cf6 - Purple

7. Hướng dẫn Tích hợp REST API

REST API được khởi chạy với FastAPI tại cổng 8000. Dưới đây là các ví dụ mã nguồn kết nối tích hợp:

Mã nguồn Python Gọi API

Python (requests)

import requests

url = "http://localhost:8000/api/predict"
file_path = "fundus_sample.jpg"

with open(file_path, "rb") as f:
    files = {"file": (file_path, f, "image/jpeg")}
    response = requests.post(url, files=files)

data = response.json()
print("Nhãn chẩn đoán:", data["prediction"]["class_name"])
print("Độ tin cậy:", data["prediction"]["confidence"], "%")
print("Lời khuyên y tế:", data["clinical_guidance"]["advice"])

Mã nguồn JavaScript Frontend (Fetch API)

JavaScript (React / Vue / HTML)

async function sendImageToAI(fileInput) {
  const formData = new FormData();
  formData.append("file", fileInput.files[0]);

  const res = await fetch("http://localhost:8000/api/predict", {
    method: "POST",
    body: formData
  });

  const json = await res.json();
  
  // Update UI Elements
  document.getElementById("result-title").innerText = json.clinical_guidance.title;
  document.getElementById("result-title").style.color = json.clinical_guidance.badge_color;
  document.getElementById("preview-img").src = json.preprocessed_image_base64;
}

8. Đóng gói & Triển khai (Deployment)

Khởi chạy hệ thống trong môi trường Docker Container production:

Bash Terminal

# Build Docker Image
docker build -t dr-resnet50-api .

# Run Container
docker run -d -p 8000:8000 --name dr_resnet50_service dr-resnet50-api