|
Download README.md from funterpie/mnist-api: direct link, hf CLI and curl.
- Browser
- Download file 4.58 kB
-
https://huggingface.co/spaces/funterpie/mnist-api/resolve/main/README.md
- Command line
-
hf download hf://spaces/funterpie/mnist-api/README.md
-
curl -L -o README.md https://huggingface.co/spaces/funterpie/mnist-api/resolve/main/README.md
4.58 kB
| # π’ MNIST Digit Classifier | |
| > Handwritten digit recognition powered by a Keras Dense Neural Network β deployed via FastAPI on HuggingFace Spaces + Streamlit Cloud frontend. | |
| [](https://huggingface.co/spaces/YOUR_HF_USERNAME/mnist-api) | |
| [](https://YOUR_APP.streamlit.app) | |
| [](https://tensorflow.org) | |
| [](https://python.org) | |
| --- | |
| ## π Live Demo | |
| | Service | URL | | |
| |---------|-----| | |
| | π Streamlit Frontend | `https://YOUR_APP.streamlit.app` | | |
| | β‘ FastAPI Backend | `https://YOUR_HF_USERNAME-mnist-api.hf.space` | | |
| | π API Swagger Docs | `https://YOUR_HF_USERNAME-mnist-api.hf.space/docs` | | |
| --- | |
| ## π Project Structure | |
| ``` | |
| mnist-digit-classifier/ | |
| β | |
| βββ main.py # FastAPI backend | |
| βββ app.py # Streamlit frontend | |
| βββ Notebook.ipynb # Model training notebook | |
| βββ mnist_model.keras # Trained Keras model | |
| βββ Dockerfile # HuggingFace Docker config | |
| βββ requirements.txt # Backend dependencies | |
| βββ sample_digits/ # Sample test images (0β9) | |
| β βββ digit_0.png | |
| β βββ digit_1.png | |
| β βββ ... | |
| βββ README.md | |
| ``` | |
| --- | |
| ## π§ Model Architecture | |
| ``` | |
| Input Layer β 784 neurons (28Γ28 flattened) | |
| Dense Layer 1 β 256 neurons, ReLU activation | |
| Dense Layer 2 β 128 neurons, ReLU activation | |
| Output Layer β 10 neurons, Softmax activation | |
| ``` | |
| | Parameter | Value | | |
| |-----------|-------| | |
| | Dataset | MNIST (70,000 images) | | |
| | Optimizer | Adam | | |
| | Loss | Sparse Categorical Crossentropy | | |
| | Epochs | 10 | | |
| | Batch Size | 128 | | |
| | **Test Accuracy** | **97.65%** | | |
| --- | |
| ## β‘ API Reference | |
| ### Health Check | |
| ```http | |
| GET / | |
| ``` | |
| ```json | |
| { | |
| "message": "MNIST Digit Classifier API is running.", | |
| "docs": "/docs" | |
| } | |
| ``` | |
| ### Predict Digit | |
| ```http | |
| POST /predict/ | |
| Content-Type: multipart/form-data | |
| ``` | |
| **Request:** Upload any PNG/JPG image of a handwritten digit. | |
| **Response:** | |
| ```json | |
| { | |
| "filename": "digit_3.png", | |
| "predicted_digit": 3, | |
| "confidence": 0.9921, | |
| "all_probabilities": { | |
| "0": 0.0001, "1": 0.0000, "2": 0.0012, | |
| "3": 0.9921, "4": 0.0003, "5": 0.0020, | |
| "6": 0.0001, "7": 0.0002, "8": 0.0035, "9": 0.0005 | |
| } | |
| } | |
| ``` | |
| ### cURL Example | |
| ```bash | |
| curl -X POST "https://YOUR_HF_USERNAME-mnist-api.hf.space/predict/" \ | |
| -F "file=@digit_0.png" | |
| ``` | |
| --- | |
| ## π οΈ Local Setup | |
| ```bash | |
| # 1. Clone the repo | |
| git clone https://github.com/funterpie/mnist-digit-classifier.git | |
| cd mnist-digit-classifier | |
| # 2. Create virtual environment | |
| python -m venv venv | |
| source venv/bin/activate # Windows: venv\Scripts\activate | |
| # 3. Install dependencies | |
| pip install -r requirements.txt | |
| # 4. Run FastAPI backend | |
| uvicorn main:app --reload | |
| # β http://127.0.0.1:8000/docs | |
| # 5. Run Streamlit frontend (new terminal) | |
| pip install streamlit | |
| streamlit run app.py | |
| # β http://localhost:8501 | |
| ``` | |
| --- | |
| ## βοΈ Deployment Guide | |
| ### FastAPI β HuggingFace Spaces (Docker) | |
| 1. Go to [huggingface.co/new-space](https://huggingface.co/new-space) | |
| 2. Select **Docker** as SDK | |
| 3. Push these files: | |
| - `main.py` | |
| - `mnist_model.keras` | |
| - `requirements.txt` | |
| - `Dockerfile` | |
| - `README.md` | |
| ```bash | |
| git clone https://huggingface.co/spaces/YOUR_HF_USERNAME/mnist-api | |
| cd mnist-api | |
| # copy your files here | |
| git add . && git commit -m "deploy: FastAPI MNIST backend" | |
| git push | |
| ``` | |
| ### Streamlit Frontend β Streamlit Cloud | |
| 1. Push `app.py` + `requirements.txt` + `sample_digits/` to GitHub | |
| 2. Go to [share.streamlit.io](https://share.streamlit.io) | |
| 3. Connect your GitHub repo | |
| 4. Set main file: `app.py` | |
| 5. Update `API_URL` in `app.py` to your HF Space URL | |
| --- | |
| ## π¨βπ» Author | |
| **Muhammad Taha Sattar Arain** | |
| Founder & CEO β [Alpha Orbit](https://alphaorbit.site) | |
| SMIT Batch 10 β AI & Data Science | |
| [](mailto:taha@alphaorbit.site) | |
| [](https://linkedin.com/in/taha-arain) | |
| [](https://github.com/funterpie) | |
| --- | |
| *Assignment 8 β Deep Learning | SMIT AI & Data Science Batch 10* | |