Hugging Face's logo

Spaces:
beppeinthesky
/
pnrr-data-processor
Running

App Files Community
pnrr-data-processor / README.md
beppeinthesky's picture
beppeinthesky
docs: Update README with application description and deployment instructions
ab8f462
preview code
|
raw
history blame contribute delete
12.3 kB
metadata 
title: PNRR Data Processor
emoji: 🏛️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

PNRR Data Processor

Un'applicazione web per l'analisi e l'elaborazione dei dati dei progetti PNRR (Piano Nazionale di Ripresa e Resilienza). L'applicazione offre strumenti avanzati di analisi basati su intelligenza artificiale per identificare pattern, raggruppamenti tematici e filtraggio semantico dei progetti.

Setup ed Esecuzione (Docker)

Prerequisiti

  • Docker e Docker Compose installati
  • File Excel con i dati dei progetti PNRR

Configurazione Ambiente

  1. Crea il file di configurazione ambiente:

    cp .env.example .env

  2. Configura la chiave API OpenAI nel file .env:

    OPENAI_API_KEY='sk-xxxxxxxxxxxxxxxxxxxxxxx'

    Per ottenere una chiave API OpenAI:

    • Registrati o accedi a OpenAI Platform
    • Vai nella sezione "API Keys" nel tuo profilo
    • Crea una nuova chiave API
    • Copia la chiave e inseriscila nel file .env

Avvio dell'Applicazione 

docker compose -f docker/compose.base.yaml up --build

L'applicazione sarà disponibile su: http://localhost:8501

Monitoraggio

Per visualizzare i log del container:

docker container logs -f semantic_filter

🎯 Funzionalità dell'Applicazione

🔍 Filtro Semantico

Scopo: Identificare automaticamente progetti PNRR rilevanti basandosi su query in linguaggio naturale.

Come funziona:

  • Utilizza modelli di AI per comprendere il significato semantico delle descrizioni dei progetti
  • Confronta la query dell'utente con il contenuto dei progetti per trovare corrispondenze concettuali
  • Assegna un punteggio di confidenza a ogni progetto basato sulla rilevanza

Come usarlo:

  1. Carica il file Excel contenente i progetti PNRR
  2. Imposta la soglia di confidenza (0.0-1.0) per filtrare i risultati
  3. Scrivi una query descrittiva in linguaggio naturale (es. "progetti di digitalizzazione nelle scuole", "infrastrutture sostenibili", "riqualificazione urbana")
  4. Scegli se aggiungere i risultati come nuova colonna o creare un nuovo file
  5. Avvia la ricerca e scarica i risultati

Output: File Excel con i progetti filtrati e punteggi di rilevanza

🎯 Analisi Cluster

Scopo: Raggruppare automaticamente progetti simili in cluster tematici per identificare pattern ricorrenti e aree di investimento comuni.

Come funziona:

  • Analizza il contenuto testuale delle colonne selezionate usando tecniche di machine learning
  • Applica preprocessing intelligente rimuovendo stopwords italiane, termini PNRR comuni e parole personalizzate dall'utente
  • Raggruppa progetti con caratteristiche simili in cluster tematici usando embeddings semantici
  • Genera automaticamente titoli, descrizioni e parole chiave per ogni cluster tramite AI
  • Calcola statistiche di distribuzione dei progetti

Come usarlo:

  1. Carica il file Excel contenente i progetti PNRR
  2. Seleziona le colonne testuali da utilizzare per il clustering (es. titolo progetto, descrizione, sintesi)
  3. Configura i parametri:
    • Automatico: L'algoritmo determina il numero ottimale di cluster
    • Manuale: Specifica un numero fisso di cluster
  4. Personalizza la blacklist (opzionale):
    • Aggiungi parole specifiche da escludere dall'analisi
    • Inserisci termini troppo generici o irrilevanti per il tuo contesto
    • Le parole possono essere inserite separate da virgole o una per riga
    • Esempi: nomi di enti frequenti, termini tecnici comuni, location ricorrenti
  5. Avvia l'analisi e attendi il completamento
  6. Esplora i risultati nei cluster generati
  7. 🆕 Visualizza il plot PCA: Analizza la distribuzione spaziale dei cluster nel grafico interattivo
  8. Scarica i risultati:
    • Sommario Cluster: File con titoli, descrizioni e statistiche
    • Dati con Cluster ID: File originale con aggiunta dell'identificativo cluster

Output:

  • Sommario dei cluster con titoli, descrizioni, parole chiave e progetti campione
  • Dataset originale arricchito con l'ID del cluster di appartenenza
  • Visualizzazioni della distribuzione dei progetti per cluster
  • 🆕 Plot PCA interattivo: Visualizzazione bidimensionale dei cluster nello spazio degli embeddings

📊 Visualizzazione PCA dei Cluster

Caratteristiche:

  • Riduzione dimensionale: I complessi embeddings multidimensionali vengono ridotti a 2 dimensioni tramite PCA (Principal Component Analysis)
  • Plot interattivo: Visualizzazione Plotly con zoom, pan e informazioni al passaggio del mouse
  • Codifica colori: Ogni cluster ha un colore distintivo per facilitare l'identificazione
  • Informazioni dettagliate: Hover con titolo cluster, descrizione e numero di progetti
  • Varianza spiegata: Mostra quanto della variabilità originale è preservata nelle due componenti principali

Interpretazione:

  • Punti vicini rappresentano progetti semanticamente simili
  • Gruppi di punti dello stesso colore mostrano la coesione del cluster
  • La distanza tra cluster indica quanto sono diversi tematicamente
  • La percentuale di varianza spiegata indica l'affidabilità della rappresentazione 2D

🎯 Blacklist Personalizzata

Scopo: Migliorare la qualità dei cluster escludendo parole irrilevanti specifiche del tuo dataset.

Benefici:

  • Cluster più precisi: Rimuovendo parole generiche, i cluster si basano su termini realmente distintivi
  • Controllo granulare: Personalizza l'analisi in base al tuo contesto specifico
  • Flessibilità: Testa diverse configurazioni per ottimizzare i risultati

Esempi di parole da escludere:

  • Termini troppo frequenti: "progetto", "attività", "servizio"
  • Nomi di enti ricorrenti: "comune", "regione", "asl"
  • Parole tecniche generiche: "sistema", "gestione", "sviluppo"
  • Location comuni nel dataset: "milano", "roma", "italia"

📋 Formato File

L'applicazione è completamente flessibile riguardo al formato del file Excel:

✅ Requisiti Minimi

  • File in formato Excel (.xlsx)
  • Almeno una colonna contenente testo descrittivo

🎯 Adattabilità

  • Nomi colonne: Possono essere qualsiasi, l'interfaccia mostrerà tutte le colonne disponibili
  • Struttura dati: Qualsiasi struttura è supportata
  • Selezione dinamica: L'utente sceglie quali colonne utilizzare per l'analisi

🏆 Colonne Consigliate (Opzionali)

Per progetti PNRR, colonne come queste migliorano la qualità dell'analisi:

  • Titolo/Nome Progetto: Identificazione del progetto
  • Descrizione/Sintesi: Contenuto descrittivo dettagliato
  • Settore/Ambito: Area tematica del progetto
  • Soggetto/Ente: Organizzazione responsabile
  • Località: Informazioni geografiche

💡 Suggerimento: Più contenuto testuale descrittivo è disponibile, migliore sarà la qualità dell'analisi semantica e del clustering, indipendentemente dai nomi delle colonne.

🚀 Deploy su Hugging Face Space

Questa guida descrive i passaggi necessari per configurare, pubblicare e aggiornare l'applicazione "PNRR Data Processor" su Hugging Face Spaces.

💻 Risorse di Sistema Necessarie

L'applicazione utilizza modelli di embedding (sentence-transformers), indici vettoriali (faiss-cpu) e librerie di manipolazione dati (pandas, scikit-learn). Per funzionare correttamente senza errori di memoria (OOM), l'ambiente di hosting richiede:

  • RAM: Minimo 4 GB (Consigliati 16 GB per elaborazioni fluide di cluster numerosi).
  • CPU: Almeno 2 vCPU.
  • Storage: Non è necessario storage persistente — i file generati vengono scritti in /tmp e scaricati direttamente dall'interfaccia.
  • Porta esposta: Il container Docker deve obbligatoriamente esporre la porta 7860 (già configurata nel Dockerfile).

Il piano gratuito "CPU Basic" di Hugging Face Spaces (16 GB RAM, 2 vCPU) è perfettamente in grado di far girare l'applicazione.

🛠️ Fase 1: Creazione e Configurazione dello Space

1. Creazione Account e Space

  1. Crea un account gratuito su Hugging Face.
  2. Vai in alto a destra (sulla tua immagine profilo) e seleziona "New Space".
  3. Compila il modulo:
    • Space name: pnrr-data-processor (o un nome a tua scelta).
    • License: Seleziona MIT o lascia vuoto.
    • Select the Space SDK: Scegli Docker e poi il template Blank.
    • Space Hardware: Lascia il piano gratuito di default.
    • Visibility: Imposta su Public (necessario per condividere l'app con i clienti tramite link senza richiedere il login ad HF).
  4. Clicca su Create Space.

2. Configurazione Credenziali (Secrets)

L'applicazione è protetta da una schermata di login. Le password non sono nel codice sorgente e devono essere configurate nel cloud.

  1. Nella pagina del tuo Space, vai sulla tab Settings.
  2. Scorri fino a Variables and secrets e clicca su New secret.
  3. Aggiungi i seguenti segreti:
    • LOGIN_USER1 ➔ Valore: nomeutente:password_scelta (es. admin:12345)
    • OPENAI_API_KEY ➔ Valore: sk-... (Inserisci la tua chiave API di OpenAI, se usata dai moduli dell'app).

3. Storage

Non è necessario (né consigliato) attaccare uno storage persistente di HF Spaces. I file generati vengono scritti in /tmp/results all'interno del container e sono scaricabili direttamente tramite i pulsanti di download nell'interfaccia. Montare un bucket su /app/results causerebbe errori di permesso (Permission denied) perché il volume sovrascrive i permessi impostati nel Dockerfile.

🚀 Fase 2: Configurazione del Deploy Locale

Per inviare il codice dal tuo computer a Hugging Face senza sovrascrivere la tua repository principale (es. Bitbucket), configureremo HF come destinazione remota secondaria.

1. Generare un Access Token

  1. Vai su Hugging Face ➔ Settings ➔ Access Tokens.
  2. Clicca su New token.
  3. Nominalo Deploy-App e imposta il Type su Write.
  4. Copia il token generato (hf_...). Attenzione: non inserire MAI questo token nel codice sorgente.

2. Collegare il repository locale

Apri il terminale nella cartella del progetto locale e aggiungi Hugging Face come remote (chiamato hf). Sostituisci TUO_NOME_UTENTE, TUO_TOKEN e NOME_SPACE con i tuoi dati reali:

git remote add hf [https://TUO_NOME_UTENTE:TUO_TOKEN@huggingface.co/spaces/TUO_NOME_UTENTE/NOME_SPACE](https://TUO_NOME_UTENTE:TUO_TOKEN@huggingface.co/spaces/TUO_NOME_UTENTE/NOME_SPACE)

🔄 Fase 3: Deploy di nuovi sviluppi

Ogni volta che fai una modifica al codice sul tuo computer e vuoi pubblicare l'aggiornamento sull'app in produzione, segui questi 3 passaggi nel terminale:

1. Registra le modifiche (Commit):

git add .
git commit -m "Descrizione dell'aggiornamento"

2. Invia alla tua repository principale (es. Bitbucket):

git push origin main

3. Invia a Hugging Face per avviare il deploy:

git push hf main

(Nota: se il tuo branch locale principale si chiama master, usa il comando git push hf master:main).

Non appena eseguito il comando push hf, Hugging Face rileverà il nuovo codice e inizierà automaticamente la ricostruzione del container Docker. L'app sarà online in circa 2-3 minuti.

⚠️ Note Importanti e Limitazioni

  • Sleep Mode: Poiché l'app è ospitata sul piano gratuito, se non riceve traffico web per 48 ore consecutive, il server andrà in pausa ("Sleep"). Al primo accesso successivo, l'utente vedrà una schermata di caricamento per circa 1-2 minuti mentre il container si riavvia. Dopodiché, l'app tornerà fluida e responsiva.
  • Link Diretto per Demo: Per inviare l'app a un cliente offrendo un'esperienza a tutto schermo (nascondendo l'interfaccia di Hugging Face), usa l'URL diretto. Clicca sui tre puntini ... in alto a destra sull'app in esecuzione ➔ Embed this Space ➔ Copia il Direct URL.
  • Gestione Segreti: Non committare mai token di Hugging Face, password in chiaro o chiavi API nei file di codice o nei Notebook Jupyter (.ipynb). Il sistema di sicurezza di HF bloccherà automaticamente il caricamento del codice in caso di leak.