File size: 3,796 Bytes
d64524a |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 |
# Customer Conversion Prediction API
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://www.docker.com/)
[](LICENSE)
This project demonstrates **deploying a machine learning model with FastAPI and Docker**.
The model predicts the probability of a lead converting to a customer based on simple features.
---
## Table of Contents
- [Project Overview](#project-overview)
- [Requirements](#requirements)
- [Setup & Installation](#setup--installation)
- [Running Locally](#running-locally)
- [Docker Deployment](#docker-deployment)
- [Using the API](#using-the-api)
- [Project Structure](#project-structure)
- [License](#license)
---
## Project Overview
We use a pre-trained **Logistic Regression model** with a `DictVectorizer` to process input features:
- `lead_source` (categorical: `organic_search`, `social_media`, `paid_ads`, `referral`, `events`)
- `annual_income` (numeric)
- `number_of_courses_viewed` (numeric)
The model is served via **FastAPI**, and can be deployed using **Docker**.
---
## Requirements
- Python 3.12 or 3.13
- [FastAPI](https://fastapi.tiangolo.com/)
- [Uvicorn](https://www.uvicorn.org/)
- [uv](https://uv-lang.org/) (for dependency management)
- [Docker](https://www.docker.com/)
---
## Setup & Installation
### 1. Clone the repository
```bash
git clone <your-repo-url>
cd <repo-folder>
````
### 2. Install dependencies with `uv`
```bash
# Install uv globally if not already
pip install uv
# Initialize uv project
uv init
# Install dependencies from pyproject.toml
uv sync --frozen
```
### 3. Verify Python and library versions
```bash
python --version
uv --version
```
---
## Running Locally
1. Make sure the `model.bin` file is in the project directory.
2. Run the FastAPI server:
```bash
uvicorn predict:app --host 0.0.0.0 --port 9696
```
3. Open API docs in your browser:
[http://localhost:9696/docs](http://localhost:9696/docs)
---
## Docker Deployment
### 1. Build Docker image
```bash
docker build -t customer-conversion-prediction .
```
### 2. Run container
```bash
docker run -d -p 9696:9696 customer-conversion-prediction
```
* Access the API at `http://localhost:9696/predict`.
### 3. Test API inside Python
```python
import requests
url = "http://localhost:9696/predict"
client = {
"lead_source": "organic_search",
"number_of_courses_viewed": 4,
"annual_income": 80304.0
}
response = requests.post(url, json=client)
print(response.json())
```
---
## Using the API
### Request format
```json
{
"lead_source": "paid_ads",
"number_of_courses_viewed": 2,
"annual_income": 79276.0
}
```
### Response format
```json
{
"convert_probability": 0.533,
"converted": true
}
```
* `convert_probability`: probability of conversion
* `converted`: True if probability >= 0.5, else False
---
## Project Structure
```
.
├── Dockerfile
├── model.bin
├── pyproject.toml
├── uv.lock
├── predict.py
└── README.md
```
* `Dockerfile`: defines container image
* `predict.py`: FastAPI app and prediction code
* `model.bin`: pre-trained ML model
* `pyproject.toml` & `uv.lock`: dependency management
* `README.md`: project documentation
---
## License
This project is for educational purposes for **ML Zoomcamp 2025**.
---
## References
* [FastAPI Documentation](https://fastapi.tiangolo.com/)
* [Uvicorn Documentation](https://www.uvicorn.org/)
* [Docker Documentation](https://docs.docker.com/)
* [Scikit-Learn Pipeline](https://scikit-learn.org/stable/modules/compose.html)
|