zeavis-edu/apps/ml-service/README.md

ML Service — Rust Axum ONNX Runtime

Layanan inferensi machine learning berbasis Rust dengan Axum web framework dan ONNX Runtime untuk klasifikasi penyakit daun jagung. Service ini menyediakan endpoint HTTP untuk prediksi real-time dengan performa tinggi dan konsumsi resource minimal.

Fitur

• Framework: Axum (async Rust web framework)
• Runtime Inferensi: ONNX Runtime untuk kompatibilitas lintas platform
• Model: EfficientNetV2B0 dalam format ONNX
• Endpoint: Health check, metadata, dan prediksi gambar
• Multipart Upload: Dukungan upload gambar langsung via HTTP POST

Prasyarat

• Rust 1.70+ dan Cargo
• Model ONNX di ../../Machine_Learning/model/model.onnx (atau path custom via MODEL_PATH)

Instalasi & Setup

Instalasi Dependensi

Dependensi Rust sudah terdaftar di Cargo.toml. Cargo akan mengunduh dan mengkompilasi otomatis saat pertama kali build.

cargo build

Menjalankan Service Lokal

Opsi 1: Default (Port 8000, Model dari Machine_Learning/)

cargo run

Service akan mencari model di path default dan mendengarkan di http://localhost:8000:

../../Machine_Learning/model/model.onnx

Opsi 2: Local Development dengan .env.example (Port 8001)

Untuk development lokal dengan port 8001 (sesuai .env.example):

source .env.example
cargo run

Service akan mendengarkan di http://localhost:8001 karena ML_SERVICE_PORT=8001 di .env.example.

Opsi 3: Custom Model Path

Jika model berada di lokasi lain, gunakan environment variable MODEL_PATH:

MODEL_PATH=/path/to/model.onnx cargo run

Atau kombinasikan dengan port custom:

ML_SERVICE_PORT=9000 MODEL_PATH=/path/to/model.onnx cargo run

Environment Variables

Variable	Default	Keterangan
ML_SERVICE_HOST	0.0.0.0	Bind address
ML_SERVICE_PORT	8000	Bind port (override untuk local dev dengan .env.example)
MODEL_PATH	../../Machine_Learning/model/model.onnx	Path ke file model ONNX
MODEL_INPUT_SIZE	224	Ukuran input gambar (224x224 untuk EfficientNetV2B0)
RUST_LOG	info	Level logging (debug, info, warn, error)

Endpoint API

1. Health Check

Default (port 8000):

curl http://localhost:8000/health

Local dev dengan .env.example (port 8001):

curl http://localhost:8001/health

Response:

{
  "status": "ok",
  "model_loaded": true,
  "model_path": "../../Machine_Learning/model/model.onnx"
}

2. Metadata

Default (port 8000):

curl http://localhost:8000/metadata

Local dev dengan .env.example (port 8001):

curl http://localhost:8001/metadata

Response:

{
  "service": "ZeaVis ML Service",
  "version": "0.1.0",
  "model_path": "../../Machine_Learning/model/model.onnx",
  "input_size": 224,
  "labels": [
    "Bercak Daun",
    "Hawar Daun",
    "Karat Daun",
    "Daun Sehat"
  ]
}

3. Prediksi

Upload gambar daun jagung untuk klasifikasi:

Default (port 8000):

curl -X POST http://localhost:8000/predict \
  -F "file=@/path/to/corn-leaf.jpg"

Local dev dengan .env.example (port 8001):

curl -X POST http://localhost:8001/predict \
  -F "file=@/path/to/corn-leaf.jpg"

Response:

{
  "predictions": [
    {
      "label": "Daun Sehat",
      "confidence": 0.95
    },
    {
      "label": "Bercak Daun",
      "confidence": 0.03
    },
    {
      "label": "Hawar Daun",
      "confidence": 0.01
    },
    {
      "label": "Karat Daun",
      "confidence": 0.01
    }
  ],
  "top_prediction": {
    "label": "Daun Sehat",
    "confidence": 0.95
  }
}

Verifikasi & Testing

Build Produksi

cargo build --release

Output binary akan tersedia di target/release/zeavis-ml-service.

Menjalankan Tests

cargo test

Tests mencakup validasi loading model, preprocessing gambar, dan output prediksi.

Verifikasi Manual

Dengan default port 8000:

1. Jalankan service:

   cargo run
   

2. Di terminal lain, test health endpoint:

   curl http://localhost:8000/health
   

3. Test metadata:

   curl http://localhost:8000/metadata
   

4. Test prediksi dengan gambar sample:

   curl -X POST http://localhost:8000/predict \
     -F "file=@../../Machine_Learning/dataset/Daun\ Sehat/sample.jpg"
   

Dengan local dev port 8001 (.env.example):

1. Jalankan service dengan .env.example:

   source .env.example
   cargo run
   

2. Di terminal lain, test health endpoint:

   curl http://localhost:8001/health
   

3. Test metadata:

   curl http://localhost:8001/metadata
   

4. Test prediksi dengan gambar sample:

   curl -X POST http://localhost:8001/predict \
     -F "file=@../../Machine_Learning/dataset/Daun\ Sehat/sample.jpg"
   

Troubleshooting

Model tidak ditemukan

Error: Failed to load model: No such file or directory

Solusi: Pastikan file model tersedia di path yang benar:

ls -la ../../Machine_Learning/model/model.onnx

Atau set path custom:

MODEL_PATH=/absolute/path/to/model.onnx cargo run

Port sudah digunakan

Error: Address already in use

Solusi: Service menggunakan port 8000 secara default. Jika port sudah digunakan, ubah dengan environment variable:

ML_SERVICE_PORT=9000 cargo run

Atau jika menggunakan .env.example (port 8001), pastikan tidak ada service lain di port tersebut:

lsof -i :8001

ONNX Runtime tidak kompatibel

Error: ONNX Runtime initialization failed

Solusi: Pastikan ONNX Runtime binary kompatibel dengan sistem operasi. Cargo akan mengunduh binary yang sesuai otomatis. Jika masalah persisten, coba rebuild:

cargo clean
cargo build

Deployment

Docker

Service dapat di-deploy via Docker. Dockerfile sudah tersedia di direktori ini.

docker build -t zeavis-ml-service .
docker run -p 8000:8000 \
  -v /path/to/model.onnx:/app/model.onnx \
  -e MODEL_PATH=/app/model.onnx \
  zeavis-ml-service

Docker Compose

Lihat docker-compose.yml di root repository untuk deployment lengkap dengan web, API, dan ML service.

Dokumentasi Terkait

• Machine_Learning/README.md — Panduan training dan ekspor model ONNX
• README.md — Dokumentasi proyek utama