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>
This commit is contained in:
Asep Haryana Saputra
co-authored by
Claude Opus 4.7
Claude Opus 4.7
parent
b1e99643f6
commit
abff278f49
@@ -14,8 +14,9 @@ Pipeline lengkap untuk klasifikasi penyakit daun jagung menggunakan **EfficientN
|
||||
6. [Tahap 2 — Upload ke Google Drive & Training di Colab](#6-tahap-2--upload-ke-google-drive--training-di-colab)
|
||||
7. [Tahap 3 — Download Model dari Colab](#7-tahap-3--download-model-dari-colab)
|
||||
8. [Tahap 4 — Ekspor Model untuk Produksi](#8-tahap-4--ekspor-model-untuk-produksi)
|
||||
9. [Output Akhir](#9-output-akhir)
|
||||
10. [Troubleshooting](#10-troubleshooting)
|
||||
9. [Tahap 5 — Konversi ke ONNX](#9-tahap-5--konversi-ke-onnx)
|
||||
10. [Output Akhir](#10-output-akhir)
|
||||
11. [Troubleshooting](#11-troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
@@ -314,9 +315,34 @@ tensorflowjs_converter \
|
||||
model/tfjs_model
|
||||
```
|
||||
|
||||
### Langkah 3: Konversi ke ONNX (untuk Rust ONNX Runtime)
|
||||
|
||||
Konversi SavedModel ke format ONNX untuk digunakan oleh layanan inferensi Rust:
|
||||
|
||||
```bash
|
||||
python convert_onnx.py
|
||||
```
|
||||
|
||||
Skrip ini akan:
|
||||
1. Memuat model dari `model/saved_model/`.
|
||||
2. Mengonversi ke format ONNX.
|
||||
3. Menyimpan ke `model/model.onnx`.
|
||||
|
||||
Model ONNX ini digunakan oleh layanan inferensi Rust di `apps/ml-service/` untuk performa dan kompatibilitas lintas platform yang lebih baik.
|
||||
|
||||
#### Validasi Parity ONNX
|
||||
|
||||
Untuk memverifikasi bahwa model ONNX menghasilkan prediksi yang sama dengan SavedModel asli, jalankan:
|
||||
|
||||
```bash
|
||||
python validate_onnx_parity.py /path/to/corn-leaf.jpg
|
||||
```
|
||||
|
||||
Skrip ini akan membandingkan output prediksi antara SavedModel dan ONNX untuk memastikan keakuratan konversi.
|
||||
|
||||
---
|
||||
|
||||
## 9. Output Akhir
|
||||
## 10. Output Akhir
|
||||
|
||||
Setelah seluruh pipeline selesai dijalankan, berikut file output yang tersedia:
|
||||
|
||||
@@ -325,13 +351,14 @@ Setelah seluruh pipeline selesai dijalankan, berikut file output yang tersedia:
|
||||
| `dataset/` | Folder gambar terstruktur | Dataset akhir hasil preprocessing |
|
||||
| `dataset.zip` | ZIP | Dataset untuk diupload ke Google Drive / Colab |
|
||||
| `best_model/best_model.keras` | Keras | Model terlatih lengkap (dengan optimizer) |
|
||||
| `model/saved_model/` | SavedModel (PB) | Inferensi server-side & jembatan konversi TFJS |
|
||||
| `model/saved_model/` | SavedModel (PB) | Inferensi server-side & jembatan konversi TFJS/ONNX |
|
||||
| `model/model.tflite` | TFLite | Inferensi di perangkat **Android / iOS** |
|
||||
| `model/model.onnx` | ONNX | Inferensi server-side via **Rust ONNX Runtime** |
|
||||
| `model/tfjs_model/` | TensorFlow.js | Inferensi di **browser / Node.js** |
|
||||
|
||||
---
|
||||
|
||||
## 10. Troubleshooting
|
||||
## 11. Troubleshooting
|
||||
|
||||
### `FileNotFoundError: dataset_1.zip tidak ditemukan`
|
||||
**Solusi:** Pastikan ketiga file ZIP sudah diunduh dan diletakkan di direktori yang sama dengan `preprocessing.py`.
|
||||
|
||||
@@ -6,7 +6,7 @@ ZeaVis Edu adalah aplikasi edukasi untuk membantu mengenali penyakit daun jagung
|
||||
|
||||
- Aplikasi web untuk pengalaman pengguna dan interaksi edukatif.
|
||||
- API backend untuk status layanan, integrasi data, dan komunikasi dengan layanan ML.
|
||||
- ML service berbasis FastAPI untuk inferensi penyakit daun jagung dari gambar.
|
||||
- ML service berbasis Rust/Axum dengan ONNX Runtime untuk inferensi penyakit daun jagung dari gambar.
|
||||
- Pipeline machine learning untuk preprocessing dataset, training di Google Colab, dan ekspor model produksi.
|
||||
- Dukungan Docker untuk deployment web, API, dan ML service.
|
||||
- Workspace monorepo berbasis Bun dan Moon untuk menjalankan task development, typecheck, dan build secara terpusat.
|
||||
@@ -28,7 +28,7 @@ Model klasifikasi menargetkan empat label berbahasa Indonesia:
|
||||
.
|
||||
├── apps/
|
||||
│ ├── api/ # Backend Elysia/Bun
|
||||
│ ├── ml-service/ # Layanan inferensi FastAPI + TensorFlow
|
||||
│ ├── ml-service/ # Layanan inferensi Rust/Axum + ONNX Runtime
|
||||
│ └── web/ # Frontend React + Vite
|
||||
├── Machine_Learning/ # Pipeline dataset, training, dan ekspor model
|
||||
├── packages/
|
||||
@@ -59,11 +59,12 @@ Model klasifikasi menargetkan empat label berbahasa Indonesia:
|
||||
|
||||
### Machine Learning
|
||||
|
||||
- Python
|
||||
- Python (preprocessing, training, export)
|
||||
- TensorFlow/Keras
|
||||
- EfficientNetV2B0
|
||||
- FastAPI
|
||||
- Uvicorn
|
||||
- Rust
|
||||
- Axum
|
||||
- ONNX Runtime
|
||||
- TFLite
|
||||
- TensorFlow.js
|
||||
|
||||
@@ -82,10 +83,10 @@ Untuk menjalankan seluruh project secara lokal, siapkan:
|
||||
|
||||
- Bun
|
||||
- Python 3.9–3.11 untuk pipeline ML
|
||||
- Python 3.10+ untuk `apps/ml-service`
|
||||
- Rust dan Cargo untuk `apps/ml-service`
|
||||
- Docker dan Docker Compose jika ingin menjalankan/deploy via container
|
||||
- PostgreSQL jika fitur backend yang membutuhkan database digunakan
|
||||
- File model `Machine_Learning/best_model/best_model.keras` untuk inferensi ML lokal
|
||||
- File model `Machine_Learning/model/model.onnx` untuk inferensi ML lokal
|
||||
|
||||
## Instalasi Root Workspace
|
||||
|
||||
@@ -150,19 +151,20 @@ bun run typecheck
|
||||
|
||||
```bash
|
||||
cd apps/ml-service
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
uvicorn main:app --host 0.0.0.0 --port 8001
|
||||
cargo run
|
||||
```
|
||||
|
||||
Default path model adalah:
|
||||
|
||||
```text
|
||||
../../Machine_Learning/best_model/best_model.keras
|
||||
../../Machine_Learning/model/model.onnx
|
||||
```
|
||||
|
||||
Jika model berada di lokasi lain, gunakan environment variable `MODEL_PATH`.
|
||||
Jika model berada di lokasi lain, gunakan environment variable `MODEL_PATH`:
|
||||
|
||||
```bash
|
||||
MODEL_PATH=/path/to/model.onnx cargo run
|
||||
```
|
||||
|
||||
## Endpoint Penting
|
||||
|
||||
@@ -248,6 +250,7 @@ Output utama pipeline ML:
|
||||
| `Machine_Learning/best_model/best_model.keras` | Model Keras hasil training |
|
||||
| `Machine_Learning/model/saved_model/` | TensorFlow SavedModel |
|
||||
| `Machine_Learning/model/model.tflite` | Model untuk mobile/TFLite |
|
||||
| `Machine_Learning/model/model.onnx` | Model untuk Rust ONNX Runtime |
|
||||
| `Machine_Learning/model/tfjs_model/` | Model untuk TensorFlow.js |
|
||||
|
||||
## Artifact Lokal dan Generated Files
|
||||
@@ -262,6 +265,7 @@ Beberapa file tidak tersedia di fresh clone karena berukuran besar, dihasilkan l
|
||||
- `Machine_Learning/best_model/best_model.keras`
|
||||
- `Machine_Learning/model/saved_model/`
|
||||
- `Machine_Learning/model/model.tflite`
|
||||
- `Machine_Learning/model/model.onnx`
|
||||
- `Machine_Learning/model/tfjs_model/`
|
||||
|
||||
## Environment Variable Penting
|
||||
@@ -272,7 +276,7 @@ Beberapa file tidak tersedia di fresh clone karena berukuran besar, dihasilkan l
|
||||
| `API_PORT` | API | Port backend produksi |
|
||||
| `WEB_APP_URL` | API | URL frontend untuk konfigurasi CORS/integrasi |
|
||||
| `ML_SERVICE_URL` | API | URL layanan ML |
|
||||
| `MODEL_PATH` | ML Service | Lokasi file model Keras |
|
||||
| `MODEL_PATH` | ML Service | Lokasi file model ONNX, default `../../Machine_Learning/model/model.onnx` |
|
||||
| `MODEL_INPUT_SIZE` | ML Service | Ukuran input model, default produksi `224` |
|
||||
|
||||
## Troubleshooting
|
||||
@@ -294,13 +298,13 @@ Pastikan `DATABASE_URL` tersedia di `.env` root dan PostgreSQL dapat diakses ole
|
||||
Pastikan file model tersedia di path default:
|
||||
|
||||
```text
|
||||
Machine_Learning/best_model/best_model.keras
|
||||
Machine_Learning/model/model.onnx
|
||||
```
|
||||
|
||||
Atau set path khusus:
|
||||
|
||||
```bash
|
||||
MODEL_PATH=/path/to/best_model.keras uvicorn main:app --host 0.0.0.0 --port 8001
|
||||
MODEL_PATH=/path/to/model.onnx cargo run
|
||||
```
|
||||
|
||||
### Docker Compose gagal karena network tidak ditemukan
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user