Workshop ProfessionAI: Dal Modello al Servizio

Questo repository contiene il codice e i materiali per il workshop "Dal Modello al Servizio". L'obiettivo è mostrare come trasformare un modello di machine learning, salvato in un file .pkl, in un servizio API robusto e interrogabile utilizzando Flask.

Vedremo come servire il modello localmente, simuleremo un ambiente di produzione con Waitress (un server WSGI cross-platform, ideale per Windows) e, come bonus, impacchetteremo l'intera applicazione in un container Docker per renderla portabile e riproducibile.

---

Struttura del Progetto

/api_workshop
|-- model_generator.py      # Script ausiliario per creare il modello di esempio (modello.pkl)
|-- modello.pkl             # File del modello di classificazione pre-allenato
|-- requirements.txt        # Elenco delle dipendenze Python del progetto
|-- requirements-docker.txt # Elenco delle dipendenze per il container docker del progetto
|-- app.py                  # Il cuore del servizio: l'applicazione Flask con gli endpoint
|-- Dockerfile              # La "ricetta" per costruire l'immagine Docker del servizio
|-- request.py              # Script client per testare l'API (validazione e carico)
|-- README.md               # Questo file

---

1. Prerequisiti

Prima di iniziare, assicurati di avere installato sul tuo sistema:

• Python (versione 3.8 o successiva) e pip.
• Git per clonare il repository.
• Docker Desktop (opzionale, per la parte su Docker). Scaricabile da docker.com.

---

2. Setup e Installazione

Segui questi passaggi per configurare l'ambiente di sviluppo.

1. Clona il Repository

git clone <URL_DEL_TUO_REPOSITORY>
cd api_workshop

2. Crea e Attiva un Ambiente Virtuale È una best practice fondamentale per isolare le dipendenze del progetto.

# Crea l'ambiente virtuale
python -m venv venv

# Attiva l'ambiente virtuale
# Su Windows (Git Bash o CMD/PowerShell):
venv\Scripts\activate

# Su macOS/Linux:
source venv/bin/activate

Vedrai (venv) all'inizio del prompt del tuo terminale.

3. Installa le Dipendenze Questo comando legge il file requirements.txt e installa tutte le librerie necessarie.

pip install -r requirements.txt

---

3. Esecuzione del Servizio

Puoi avviare il servizio API in tre modalità diverse.

Modo 1: Server di Sviluppo Flask (Per Debug)

Ideale per testare rapidamente durante lo sviluppo. Non usare in produzione!

flask --app app run

Il servizio sarà in ascolto su http://127.0.0.1:5000.

Modo 2: Server di Produzione Waitress (Consigliato per Windows)

Questo simula un ambiente di produzione reale ed è la scelta cross-platform.

waitress-serve --host=0.0.0.0 --port=5000 app:app

Il servizio sarà in ascolto sulla porta 5000 da qualsiasi interfaccia di rete.

Modo 3: Server di produzione Gunicorn (consigliato per Unix)

gunicorn --workers 3 --bind 0.0.0.0:5000 app:app

Il servizio sarà in ascolto sulla porta 5000 e ci saranno 3 Processi attivi (gestione del carico migliorata)

Modo 4: Con Docker (Best Practice per la Portabilità)

Questo approccio impacchetta l'intera applicazione in un container, garantendo che funzioni allo stesso modo ovunque.

a. Costruisci l'immagine Docker: (Assicurati che Docker Desktop sia in esecuzione)

docker build -t churn-api .

b. Avvia il container in background (modalità detached):

docker run -d -p 5000:5000 --name churn-container churn-api

• -d: Esegue il container in background.
• -p 5000:5000: Mappa la porta 5000 del tuo PC alla porta 5000 del container.
• --name churn-container: Assegna un nome facile da ricordare al container.

Comandi Docker utili:

• docker ps: Mostra i container in esecuzione.
• docker logs -f churn-container: Mostra i log del servizio in tempo reale.
• docker stop churn-container: Ferma il container.
• docker rm churn-container: Rimuove il container fermato.

---

4. Testare l'API

Con il server in esecuzione (in una delle tre modalità), apri un nuovo terminale e usa uno dei seguenti metodi.

a) Con lo script Python fornito

Lo script request.py esegue un health check, test di validazione e un semplice test di carico.

python request.py

b) Con curl (da terminale)

Un modo universale per testare gli endpoint.

Test dell'endpoint /health:

curl http://127.0.0.1:5000/health

Test dell'endpoint /predict (richiesta valida):

curl -X POST -H "Content-Type: application/json" \
-d '{"eta": 45, "sessioni_mensili": 30, "spesa_totale": 850.75}' \
http://127.0.0.1:5000/predict

Test dell'endpoint /predict (richiesta non valida):

curl -X POST -H "Content-Type: application/json" \
-d '{"eta": -5}' \
http://127.0.0.1:5000/predict

---

5. Spunti per Best Practice e Miglioramenti

Il codice in questo repository è volutamente semplice per scopi didattici. In un progetto reale, considera i seguenti miglioramenti:

1. Gestione della Configurazione: Separa le configurazioni (come host e porta) dal codice usando variabili d'ambiente e un file .env.
2. Testing Automatico: Aggiungi una suite di test con pytest per verificare automaticamente il comportamento degli endpoint e della logica di validazione.
3. Logging Strutturato: Usa il logging in formato JSON per rendere i log facilmente indicizzabili e analizzabili da sistemi di monitoraggio come Elastic Stack o Datadog.
4. Validazione degli Schemi: Invece di if/else manuali, usa una libreria come Pydantic per definire schemi di dati robusti per l'input e l'output, ottenendo validazione e documentazione automatica.
5. CORS (Cross-Origin Resource Sharing): Se l'API deve essere chiamata da un'applicazione web su un altro dominio, abilita il CORS usando l'estensione Flask-CORS.

---

Licenza

Distribuito sotto licenza MIT.