https://github.com/jubairt/titanic-model-deployment-fastapi-docker

A simple machine learning project demonstrating how to deploy a trained model as a REST API using FastAPI and Docker.
https://github.com/jubairt/titanic-model-deployment-fastapi-docker

docker fastapi ml model-serving titanic-survival-prediction

Last synced: 1 day ago
JSON representation

A simple machine learning project demonstrating how to deploy a trained model as a REST API using FastAPI and Docker.

• Host: GitHub
• URL: https://github.com/jubairt/titanic-model-deployment-fastapi-docker
• Owner: jubairt
• Created: 2025-12-20T16:01:07.000Z (6 months ago)
• Default Branch: main
• Last Pushed: 2025-12-21T03:43:01.000Z (6 months ago)
• Last Synced: 2026-05-31T09:22:26.814Z (29 days ago)
• Topics: docker, fastapi, ml, model-serving, titanic-survival-prediction
• Language: Jupyter Notebook
• Homepage:
• Size: 32.2 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# Titanic Survival Prediction API 🚢

This project demonstrates a **complete, real-world machine learning deployment workflow** — from a trained model to a **production-ready REST API** served using **FastAPI** and **Docker**.

The goal of this project is to show **how a trained ML model can be packaged, served, and deployed** in a clean, simple, and professional way.

---

```bash

docker build -t titanic-model-fastapi .

docker run -p 8000:8000 titanic-model-fastapi

```

- Run these commands in the project folder to create docker image and run the container

## 🚀 What This Project Does

This API predicts whether a passenger **survived or did not survive** the Titanic disaster based on a small set of easy-to-understand inputs.

The focus is **not on complex modeling**, but on **correct deployment practices** that reflect how ML systems are built in real-world production environments.

---

## 🧠 Machine Learning Approach

- A **Logistic Regression** model is used for prediction.

- The model is trained **offline** using the Titanic dataset.

- Only **5 meaningful and user-friendly features** are used.

- All preprocessing (encoding) is bundled together with the model using a **scikit-learn Pipeline**.

This ensures the same preprocessing logic is applied during both training and inference.

---

## 📥 Model Inputs

The API expects the following passenger details:

- **Passenger Class (`Pclass`)**  

  Travel class of the passenger (1 = First, 2 = Second, 3 = Third)

- **Sex (`Sex`)**  

  Gender of the passenger (`male` or `female`)

- **Age (`Age`)**  

  Age of the passenger in years

- **Fare (`Fare`)**  

  Ticket price paid by the passenger

- **Embarked (`Embarked`)**  

  Port where the passenger boarded the ship  

  (`S` = Southampton, `C` = Cherbourg, `Q` = Queenstown)

All inputs are provided in raw form — the API handles preprocessing internally.

---

## 📤 API Output

The API returns:

- A **numeric prediction**

  - `1` → Passenger survived

  - `0` → Passenger did not survive

- A **human-readable message** explaining the prediction

This dual output design makes the API suitable for both machines and humans.

---

## 🌐 API Endpoints

- **Health Check**

  - Confirms the service is running and responsive

- **Prediction Endpoint**

  - Accepts passenger data as JSON

  - Returns survival prediction and explanation

Interactive API documentation is automatically generated and available via **Swagger UI**.

---

## 🐳 Docker & Deployment

The application is fully **containerized using Docker**.

Key deployment principles followed:

- The model is trained **outside** the container

- The container contains **only what is needed for inference**

- Training code, notebooks, and datasets are excluded using `.dockerignore`

- Dependencies are installed efficiently using Docker layer caching

- The API runs in a reproducible, portable environment

This makes the service easy to run locally, deploy to the cloud, or scale in container orchestration systems.

---

## 🧩 Technologies Used

- **Python**

- **FastAPI** — REST API framework

- **scikit-learn** — Model training & pipelines

- **pandas / numpy** — Data handling

- **Pydantic** — Input validation

- **Docker** — Containerization

- **Uvicorn** — ASGI server

---

## 🧠 Key Learning Outcomes

This project demonstrates:

- How to serve ML models using REST APIs

- Why preprocessing must be bundled with the model

- How FastAPI and Pydantic enable clean input validation

- How Docker is used in real ML production systems

- The difference between training environments and serving environments

- Best practices for deploying ML models in a professional setting

---

## 📌 Why This Project Matters

Most ML projects stop at training.

This project goes further by showing **how models are actually deployed**, which is the most common gap between learning ML and working in real-world ML systems.

It is designed to be:

- Beginner-friendly

- Interview-ready

- Production-oriented

- Easy to extend and improve

---

## 🔮 Possible Enhancements

- Add prediction probabilities

- Add stricter input validation rules

- Introduce model versioning

- Push Docker image to a container registry

- Deploy to cloud platforms (AWS / Azure / GCP)

- Add logging and monitoring

---

## ✅ Summary

This project is a complete example of **end-to-end ML deployment** using modern, industry-standard tools.  

It focuses on **clarity, correctness, and real-world relevance**, making it suitable for learning, portfolios, and interviews.

---

**Author**  

Built as part of a hands-on journey into Machine Learning deployment and MLOps.