ConvNeXt-P3

Model Card: ConvNeXt-P3 (Diabetic Retinopathy Classification)

Tài liệu hướng dẫn tích hợp mô hình ConvNeXt-Tiny chẩn đoán Bệnh Võng mạc Tiểu đường 5 phân lớp dành cho Backend, Frontend, và Software Engineers.

---

1. Tổng quan Mô hình (Model Overview)

• Kiến trúc: convnext_tiny (kiến trúc Convolutional tiên tiến thế hệ mới của Meta, đầu vào 224x224).
• Nhiệm vụ: Phân loại mức độ Bệnh võng mạc tiểu đường (Diabetic Retinopathy - DR) theo tiêu chuẩn liên bang ICDR gồm 5 lớp:
  • 0: No DR (Bình thường)
  • 1: Mild DR (Nhẹ)
  • 2: Moderate DR (Trung bình)
  • 3: Severe DR (Nặng)
  • 4: Proliferative DR (Tăng sinh nguy hiểm)
• Hiệu năng trên tập kiểm thử (Test Split - không áp Threshold tuning):
  • Weighted F1-Score: 77.77%
  • Macro ROC-AUC: 0.8379 (Mô hình có khả năng phân biệt cực kỳ mạnh mẽ giữa các lớp, phù hợp nhất khi kết hợp Ensemble với trọng số tối ưu W*).

---

2. Cấu trúc thư mục repository (Files in Repository)

• best_model.pt: Checkpoint weights của PyTorch chứa state_dict.
• convnext_inference.pt: Phiên bản mô hình đóng gói dưới dạng TorchScript (đã tích hợp Logit Adjustment và Softmax). Nhận đầu vào là Tensor ảnh đã chuẩn hóa và trả về xác suất 5 lớp trực tiếp.
• convnext_inference.onnx & convnext_inference.onnx.data: Phiên bản mô hình định dạng ONNX dùng cho deploy đa nền tảng không phụ thuộc PyTorch.
• preprocessing.py: Script Python duy nhất chứa toàn bộ luồng tiền xử lý (letterbox resize, Ben Graham transform) và lớp DRPredictor chạy suy luận.

---

3. Hướng dẫn Tích hợp dành cho Backend Engineer (Python)

Tải tệp preprocessing.py và convnext_inference.pt về chung thư mục dự án của bạn và chạy suy luận trực tiếp:

from preprocessing import DRPredictor

# Khởi tạo predictor (chỉ cần chạy 1 lần khi startup hệ thống để nạp model vào RAM/GPU)
# Chỉ định convnext_path trỏ tới file .pt vừa tải
predictor = DRPredictor(convnext_path="convnext_inference.pt")

# Dự đoán từ đường dẫn ảnh hoặc dữ liệu bytes nhận được từ client upload
result = predictor.predict("test_retina.jpg", use_ben_graham=True)

print("Kết quả chẩn đoán:", result)

Đặc tả dữ liệu đầu ra (Output JSON format):

{
  "class_id": 0,
  "class_name": "No DR",
  "confidence": 0.7325,
  "probabilities": {
    "No DR": 0.7325,
    "Mild": 0.2048,
    "Moderate": 0.0626,
    "Severe": 0.0001,
    "Proliferative DR": 0.0000
  }
}

---

4. Hướng dẫn chạy trực tiếp mô hình ONNX (Đa ngôn ngữ: Node.js, Go, C#)

ONNX Runtime hỗ trợ chạy suy luận trực tiếp trên CPU/GPU mà không cần cài đặt PyTorch.

Đặc tả Input/Output Tensor

• Đầu vào (Input): Tên tensor: input_image. Định dạng float32, Shape: [1, 3, 224, 224] (NCHW format). Ảnh được resize letterbox về (224, 224) và chuẩn hóa ImageNet (mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]).
• Đầu ra (Output): Tên tensor: probabilities. Định dạng float32, Shape: [1, 5]. Chứa phân phối xác suất Softmax của 5 lớp.

Tích hợp bằng Node.js Backend:

const ort = require('onnxruntime-node');
const sharp = require('sharp'); // Thư viện xử lý ảnh cho Node.js

async function predict(imagePath) {
    const session = await ort.InferenceSession.create('./convnext_inference.onnx');
    
    // 1. Thực hiện Resize & Normalize ảnh (tương đương preprocessing.py)
    // - Resize letterbox về 224x224
    // - Chuyển sang Float32 và chuẩn hóa ImageNet: (pixel / 255.0 - mean) / std
    // - Sắp xếp lại chiều thành NCHW [1, 3, 224, 224]
    const inputTensor = new ort.Tensor('float32', float32Data, [1, 3, 224, 224]);
    
    // 2. Chạy suy luận
    const outputs = await session.run({ input_image: inputTensor });
    const probabilities = outputs.probabilities.data;
    
    console.log("Xác suất dự đoán:", probabilities);
}

---

5. Hướng dẫn Tích hợp phía Client (Frontend / Mobile / Web-Browser)

Mô hình ONNX có thể chạy trực tiếp trên trình duyệt Client (React/Vue) hoặc ứng dụng Di động (Flutter/React Native) để bảo mật tuyệt đối dữ liệu y tế của bệnh nhân và giảm tải tối đa cho Server.

• Web Browser (React/Vue): Sử dụng thư viện onnxruntime-web chạy trên WebAssembly (WASM).
• Mobile (React Native / Flutter / Android / iOS): Sử dụng thư viện onnxruntime-react-native hoặc onnxruntime_flutter.

import * as ort from 'onnxruntime-web';

async function runOnClient(imageElement) {
    // Tải mô hình trực tiếp từ thư mục public hoặc CDN
    const session = await ort.InferenceSession.create('/models/convnext_inference.onnx');
    
    // Thực hiện trích xuất dữ liệu pixel của ảnh từ thẻ <canvas> hoặc <img> 
    // Chuẩn hóa và đóng gói thành Float32Array [1, 3, 224, 224]
    const tensor = new ort.Tensor('float32', Float32ArrayPixels, [1, 3, 224, 224]);
    
    const results = await session.run({ input_image: tensor });
    console.log("Kết quả chẩn đoán client-side:", results.probabilities.data);
}