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);
}