docs: document Rust ONNX ML service

Update documentation to reflect migration from FastAPI/Uvicorn to Rust/Axum with ONNX Runtime: - Root README: Update ML service description, tech stack, prerequisites, and run instructions to use Rust/Cargo instead of Python/Uvicorn - Root README: Update model path references from best_model.keras to model.onnx - Root README: Add model.onnx to artifact lists and generated files - Root README: Update troubleshooting section with Rust-specific guidance - Machine_Learning/README: Add table of contents entry for ONNX conversion - Machine_Learning/README: Add Tahap 5 section documenting ONNX conversion with convert_onnx.py and validate_onnx_parity.py - Machine_Learning/README: Update output table to include model.onnx with Rust ONNX Runtime usage - apps/ml-service/README: Create comprehensive documentation for Rust Axum ONNX service including setup, endpoints, environment variables, testing, and troubleshooting Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-23 10:51:59 +00:00
parent b1e99643f6
commit abff278f49
3 changed files with 281 additions and 21 deletions
@@ -0,0 +1,229 @@
+# 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.
+
+```bash
+cargo build
+```
+
+## Menjalankan Service Lokal
+
+### Opsi 1: Default (Model dari Machine_Learning/)
+
+```bash
+cargo run
+```
+
+Service akan mencari model di path default:
+```
+../../Machine_Learning/model/model.onnx
+```
+
+### Opsi 2: Custom Model Path
+
+Jika model berada di lokasi lain, gunakan environment variable `MODEL_PATH`:
+
+```bash
+MODEL_PATH=/path/to/model.onnx cargo run
+```
+
+Service akan mendengarkan di `http://localhost:8000` secara default.
+
+## Environment Variables
+
+| Variable | Default | Keterangan |
+|---|---|---|
+| `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
+
+```bash
+curl http://localhost:8000/health
+```
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "model_loaded": true,
+  "model_path": "../../Machine_Learning/model/model.onnx"
+}
+```
+
+### 2. Metadata
+
+```bash
+curl http://localhost:8000/metadata
+```
+
+**Response:**
+```json
+{
+  "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:
+
+```bash
+curl -X POST http://localhost:8000/predict \
+  -F "file=@/path/to/corn-leaf.jpg"
+```
+
+**Response:**
+```json
+{
+  "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
+
+```bash
+cargo build --release
+```
+
+Output binary akan tersedia di `target/release/zeavis-ml-service`.
+
+### Menjalankan Tests
+
+```bash
+cargo test
+```
+
+Tests mencakup validasi loading model, preprocessing gambar, dan output prediksi.
+
+### Verifikasi Manual
+
+1. Jalankan service:
+   ```bash
+   cargo run
+   ```
+
+2. Di terminal lain, test health endpoint:
+   ```bash
+   curl http://localhost:8000/health
+   ```
+
+3. Test metadata:
+   ```bash
+   curl http://localhost:8000/metadata
+   ```
+
+4. Test prediksi dengan gambar sample:
+   ```bash
+   curl -X POST http://localhost:8000/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:
+```bash
+ls -la ../../Machine_Learning/model/model.onnx
+```
+
+Atau set path custom:
+```bash
+MODEL_PATH=/absolute/path/to/model.onnx cargo run
+```
+
+### Port sudah digunakan
+
+**Error:** `Address already in use`
+
+**Solusi:** Service menggunakan port 8000. Jika port sudah digunakan, ubah di source code atau gunakan port forwarding.
+
+### 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:
+```bash
+cargo clean
+cargo build
+```
+
+## Deployment
+
+### Docker
+
+Service dapat di-deploy via Docker. Dockerfile sudah tersedia di direktori ini.
+
+```bash
+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`](../../Machine_Learning/README.md) — Panduan training dan ekspor model ONNX
+- [`README.md`](../../README.md) — Dokumentasi proyek utama