Questo progetto mira a fornire un sistema di suggerimenti automatico per supplementi volte a colmare le lacune nei Papiri di Ercolano e a supportare il processo di creazione di nuove edizioni critiche.
Per installare ed eseguire il progetto localmente, avrai bisogno dei seguenti strumenti installati sul tuo sistema:
Questo è il modo più semplice per eseguire l'intero stack (API, Frontend e MongoDB) in modo fluido e integrato.
- Docker e Docker Compose: Installa Docker
Se preferisci eseguire i servizi manualmente o sviluppare localmente senza Docker:
- Python
- uv: Gestore di pacchetti e progetti Python. Installa uv
- Node.js e npm: Richiesti per il frontend Angular. Installa Node.js
- Angular CLI: Da installare globalmente tramite
npm install -g @angular/cli.
Segui questi passaggi per configurare ed eseguire il progetto sulla tua macchina.
git clone https://github.com/CoPhi/gs-suggestions-dataset.git
cd gs-suggestions-datasetIl progetto utilizza le variabili d'ambiente per configurare i servizi. Nel repository è fornito un file modello chiamato .env.example.
Per configurare il tuo ambiente, copia il file .env.example in un nuovo file chiamato .env e modificalo:
cp .env.example .env(Nota: Quando si esegue localmente al di fuori di Docker, assicurarsi che MONGO_HOST=localhost).
Se desideri addestrare nuovi modelli, dovrai impostare le variabili WANDB_API_KEY e HF_TOKEN nel file .env.
Per mantenere il repository leggero, i grandi dataset testuali analizzati memorizzati nella cartella data/ sono esclusi dal tracciamento Git (tramite .gitignore). Tutti i collaboratori devono ricostruire autonomamente l'ambiente dei dati a livello locale dopo aver clonato il repository.
Prima di utilizzare i modelli o le API in modo significativo, è necessario popolare i dati. Assicurati innanzitutto che le dipendenze del backend siano installate tramite uv:
uv sync[!IMPORTANTE] Configurazione CLTK per corpora personalizzati Prima di eseguire lo script di download dei dati (
make data), è necessario configurare o creare il filedistributed_corpora.yamlall'interno della cartellacltk_datadel proprio utente (solitamente situata in~/cltk_data/distributed_corpora.yaml).Questo file è richiesto da CLTK per mappare e scaricare i repository remoti contenenti i corpora. Assicurati che il file contenga la seguente sintassi:
DDbDP-DCLP: origin: https://github.com/papyri/idp.data language: grc type: corpora EDH: origin: https://github.com/epigraphic-database-heidelberg/data language: grc type: corpora First1KGreek: origin: https://github.com/OpenGreekAndLatin/First1KGreek language: grc type: corpora PerseusDL: origin: https://github.com/PerseusDL/canonical-greekLit language: grc type: corpora
Passo 1: Scaricare e integrare i corpora
Esegui la pipeline automatizzata per scaricare, elaborare e inserire i corpora nella cartella data/:
make dataPasso 2: Analisi dei file XML TEI standard (Opzionale) Se disponi di archivi di testo aggiuntivi che utilizzano il formato TEI standard (senza lacune complesse in formato EpiDoc), puoi compilarli utilizzando il convertitore autonomo:
uv run python -m scripts.tei.pipeline <percorso_della_tua_cartella_tei>Nota: Entrambi i comandi popoleranno la directory data/ in blocchi di file isolati (fino a 50 MB) in un formato JSON fruibile da codice, pronto per le attività successive.
È possibile eseguire e testare i servizi in due modi: tramite Docker (consigliato per uno stack completo e pronto all'uso) o avviando il backend e il frontend in locale per lo sviluppo attivo.
Questo è il modo più semplice per testare l'intera applicazione integrata (API Backend, Frontend Angular e MongoDB) senza installare manualmente le dipendenze di sviluppo.
-
Avviare l'ambiente:
make run
(Questo avvia tutti i servizi in background tramite
docker compose up). -
Arrestare l'ambiente:
make stop
-
Riavviare l'ambiente:
make restart
Una volta avviato, puoi accedere ai servizi ai seguenti indirizzi:
- Applicazione Frontend: http://localhost:4200
- API Backend: http://localhost:8000 (Documentazione interattiva Swagger su http://localhost:8000/docs)
- MongoDB:
localhost:27017
Se stai sviluppando attivamente o testando modifiche al codice del backend o del frontend, è più veloce eseguire i servizi localmente.
-
Eseguire l'API Backend:
make run-api
Questo avvierà il server Uvicorn su http://localhost:8000 con ricaricamento automatico (auto-reload) attivo.
-
Eseguire l'Applicazione Frontend:
make run-frontend
Questo verificherà e installerà automaticamente eventuali dipendenze npm mancanti e avvierà il server di sviluppo di Angular su http://localhost:4200 con Hot Module Replacement (HMR) attivo.
(Nota: Consulta frontend/README.md per comandi avanzati e test specifici di Angular).
Il framework supporta il pre-addestramento (MLM) e il fine-tuning di modelli linguistici BERT specializzati per il greco antico su frammenti e lacune papirologiche.
I modelli gestiti centralmente tramite ModelRegistry sono:
CNR-ILC/gs-GreBerta(base:bowphs/GreBerta)CNR-ILC/gs-aristoBERTo(base:Jacobo/aristoBERTo)CNR-ILC/gs-Logion(base:cabrooks/LOGION-50k_wordpiece)
Per un riepilogo rapido di tutti i comandi disponibili è possibile digitare in qualsiasi momento:
make helpÈ possibile addestrare i modelli sia con le configurazioni ottimali predefinite (definite in ModelRegistry) sia sovrascrivendo i parametri da riga di comando.
# Esempio 1: Addestramento di GreBERTa con configurazione di default
make train MODEL=gs-GreBerta
# Esempio 2: Personalizzazione di epoche, learning rate e batch size
make train MODEL=gs-aristoBERTo EPOCHS=3 LR=1.5e-5 BATCH_SIZE=64
# Esempio 3: Addestramento senza caricamento su Hugging Face Hub
make train MODEL=gs-Logion NO_PUSH=truePer verificare che l'ambiente, la GPU e i dataset funzionino correttamente senza attendere tutte le epoche e senza pubblicare su Hugging Face (esegue 1 epoca, batch 32, --no_push_to_hub):
make train-test MODEL=gs-GreBertaNel restauro di testi antichi, l'accuratezza lessicale rigida (Top-1 Exact Match) e la plausibilità semantica/coesione contestuale (Cluster Inclusion Rate) sono obiettivi concorrenti. Il progetto integra l'algoritmo genetico NSGA-II (Non-dominated Sorting Genetic Algorithm II, Deb et al., 2002) tramite Optuna, permettendo di trovare la Frontiera di Pareto senza imporre pesi arbitrari a priori.
# Avvio standard (25 trial, popolazione di 8 individui, obiettivi 2D: Top-1 EM vs Cluster Inc.)
make hpo-nsga2 MODEL=gs-GreBerta
# Con parametri personalizzati
make hpo-nsga2 MODEL=gs-GreBerta TRIALS=30 POPULATION=10 OBJECTIVES=2dNote
Tutti i trial vengono salvati in un database SQLite locale (optuna_nsga_studies.db). L'esecuzione può essere interrotta e ripresa in qualsiasi momento. Al termine, viene generato automaticamente un grafico interattivo della frontiera in formato HTML (pareto_front_*.html).
Ispeziona la frontiera di Pareto estratta da NSGA-II e identifica automaticamente il punto di massimo compromesso matematico (Knee Point, minima distanza euclidea dall'Utopia Point
make pareto MODEL=gs-GreBerta SELECTION=kneeStrategie di selezione supportate (SELECTION):
knee: Miglior compromesso tra accuratezza lessicale e plausibilità semantica (consigliato).max_em: Massima precisione lessicale (modello conservativo su congetture storiche).max_cluster: Massima coesione semantica ed inclusione delle gold label nel cluster predittivo.
Una volta individuata la configurazione desiderata, puoi addestrare il modello finale a regime e caricarlo su Hugging Face Hub con un unico comando:
make pareto-train MODEL=gs-GreBerta SELECTION=kneePer confrontare le prestazioni del modello base (Pre-FT, es. bowphs/GreBerta) rispetto alla versione fine-tunata (Post-FT, es. CNR-ILC/gs-GreBerta) su un test set specifico (senza dover riavviare un addestramento) e generare o pubblicare la Model Card arricchita su Hugging Face Hub:
# Esempio 1: Confronto sul dataset di testing TLG per tutte le policy di lacuna (default, word, suffix)
make compare MODEL=gs-GreBerta EVAL_DATASET=CNR-ILC/gs-dataset-tlg-uncased POLICY=all
# Esempio 2: Confronto con generazione della Model Card in locale (README.md)
make compare MODEL=gs-GreBerta EVAL_DATASET=CNR-ILC/gs-dataset-tlg-uncased POLICY=all UPDATE_CARD=true OUTPUT_CARD=README_gs-GreBerta.md
# Esempio 3: Confronto e pubblicazione diretta della Model Card su Hugging Face Hub
make compare MODEL=gs-GreBerta EVAL_DATASET=CNR-ILC/gs-dataset-tlg-uncased POLICY=all PUSH_CARD=true
# Esempio 4: Pubblicazione / aggiornamento della Model Card da un file JSON precedentemente salvato
make model-card MODEL=gs-GreBerta FROM_JSON=comparison_greberta.json PUSH_CARD=trueIl confronto produce sia a terminale sia nella Model Card una tabella dettagliata che evidenzia:
- Exact Match: Top-1, Top-5, Top-10, Top-20
- BERTScore F1: @1, @5, @10, @20
- Cosine Similarity (Max e Mean): @1, @5, @10, @20
- Cluster Inclusion (Plausibilità Semantica): In-Cluster Rate, Margin, Gold Centroid CosSim
-
Delta (
$\Delta$ ): variazione netta tra modello pre-addestrato e modello post-finetuning con indicatori di progresso (+X.XX% 🟢).
Tip
Durante il fine-tuning standard (make train o pipeline_finetuning), se push_to_hub=True, la pipeline genera e carica automaticamente su Hugging Face Hub la Model Card arricchita comprensiva dei metadati completi, iperparametri e della tabella comparativa Pre vs Post-FT con i delta su TLG!
In alternativa a NSGA-II, è possibile utilizzare l'ottimizzatore bayesiano su metrica composita tramite W&B Sweeps:
# 1. Inizializzare lo sweep (restituisce SWEEP_ID)
make sweep SWEEP_YAML=models/bert/finetuning/sweep_greBERTa.yaml
# 2. Avviare l'agente per eseguire le run
make sweep-agent SWEEP_ID=<tuo_sweep_id>
# 3. Visualizzare a terminale la miglior configurazione trovata
make sweep-best SWEEP_ID=<tuo_sweep_id>Quando si eseguono addestramenti o sweep su server remoti via SSH:
- Variabili d'ambiente: assicurarsi che il file
.envsulla macchina remota contenga:HF_TOKEN=tuo_token_huggingface WANDB_API_KEY=tuo_token_wandb
- Sessione persistente con
tmux(per evitare interruzioni in caso di disconnessione SSH):# Avviare una sessione persistente tmux new -s training # Selezionare la GPU ed eseguire CUDA_VISIBLE_DEVICES=0 make train MODEL=gs-GreBerta # Per staccarsi dalla sessione: premere Ctrl+B, poi D # Per riconnettersi: tmux attach -t training
- Selezione specifica della GPU: anteporre
CUDA_VISIBLE_DEVICES=<id_gpu>(es.CUDA_VISIBLE_DEVICES=0 make hpo-nsga2 ...).
Il framework supporta l'adattamento (fine-tuning) del modello Ithaca (Google DeepMind, Assael et al., Nature 2022) per il restauro del testo greco sui papiri ercolanesi e sulla letteratura greca antica tramite il corpus TLG (Thesaurus Linguae Graecae).
A differenza dell'addestramento originale su iscrizioni epigrafiche (corpus PHI), il modello viene adattato al registro linguistico letterario e filosofico congelando le teste di attribuzione geografica e temporale per concentrare la capacità del modello sul restauro testuale a livello di carattere (character-level masked language modeling).
Per visualizzare tutti i comandi disponibili digitare:
make help
# oppure per la guida rapida a Ithaca:
make ithaca-
Configurazione dell'ambiente e checkpoint base: Scarica il checkpoint pre-addestrato di DeepMind (
checkpoint_v1.pkl), clona il motore Ithaca e configura l'ambiente JAX/Flax:make ithaca-setup
-
Preparazione del dataset TLG: Normalizza il corpus TLG in maiuscolo epigrafico senza diacritici e genera lacune sintetiche stratificate (
default,word,suffix):make ithaca-data # Oppure specificando un dataset personalizzato: make ithaca-data DATASET=CNR-ILC/gs-dataset-tlg-uncased -
Esecuzione del Fine-Tuning: Allena il Transformer BigBird e la testa di restauro MLM congelando le teste di datazione e localizzazione:
make ithaca-train # Con parametri personalizzati: make ithaca-train ITHACA_EPOCHS=3 ITHACA_BATCH_SIZE=8 ITHACA_LR=2e-5 -
Valutazione comparativa (Pre-FT vs Post-FT): Confronta le prestazioni di infilling del checkpoint base rispetto a quello fine-tunato calcolando Top-1/5/20 Accuracy, MRR e Character Error Rate (CER), salvando il report JSON, la tabella Markdown e il CSV:
make ithaca-compare # Con personalizzazione dei file di destinazione (JSON, CSV, Markdown): make ithaca-compare ITHACA_OUTPUT_JSON=eval/results/eval_results_ithaca_comparison.json ITHACA_OUTPUT_CSV=eval/results/eval_results_ithaca_comparison.csv ITHACA_OUTPUT_MD=eval/results/eval_results_ithaca_comparison.md -
Pubblicazione su Hugging Face Hub: Carica il checkpoint fine-tunato, la configurazione e la Model Card arricchita con la tabella dei benchmark sul repository di Hugging Face Hub:
make ithaca-publish # Oppure specificando il repository target: make ithaca-publish ITHACA_REPO_ID=CNR-ILC/gs-ithaca-tlg
Il progetto integra un quarto approccio di restauro testuale basato su Retrieval-Augmented Generation (RAG) orchestrato tramite il framework DSPy (dspy>=3.4.0) in models/rag/.
Il sistema combina:
-
Retrieval Ibrido (
GreekHybridRetriever): unisce la ricerca lessicale/morfologica BM25 + character n-grams (per intercettare radici, prefissi e suffissi parziali attorno alla lacuna) e la ricerca semantica densa tramitedspy.Embedder/dspy.Embeddings(alimentata dai modelli BERT greci del progetto comeCNR-ILC/gs-GreBerta) sui blocchi del TLG (data/tlg_*.json) e del corpus MAAT (data/maat_*.json), fondendo i ranking con Reciprocal Rank Fusion (RRF). -
Signature e Moduli Componibili (
GreekRAGInfiller): guida modelli LLM da Hugging Face (es.Qwen/Qwen2.5-7B-Instruct,meta-llama/Llama-3.1-8B-Instruct) tramite Chain-of-Thought filologico (GreekInfillingSignature) e auto-correzione sui vincoli di lunghezza in caratteri (ConstraintRefinementSignature). -
Compilazione Automatica DSPy (
BootstrapFewShot/MIPROv2): seleziona e congela automaticamente nel prompt le migliori dimostrazioni few-shot dal dev set ottimizzando la metrica composita (Exact Match + Character Accuracy$1 - \text{CER}$ + rispetto della lunghezza della lacuna).
Per visualizzare la guida rapida ai comandi:
make rag-
Costruzione dell'Indice Ibrido su
data/:make rag-index # Personalizzando il numero massimo di passaggi o l'embedder: make rag-index RAG_MAX_PASSAGES=10000 RAG_EMBEDDER=CNR-ILC/gs-GreBerta -
Compilazione / Ottimizzazione Few-Shot del Modulo DSPy:
make rag-compile RAG_LM=Qwen/Qwen2.5-7B-Instruct RAG_OPTIMIZER=bootstrap
-
Valutazione Stratificata (
default,word,suffix):make rag-eval RAG_LM=Qwen/Qwen2.5-7B-Instruct EVAL_DATASET=CNR-ILC/gs-dataset-eval POLICY=all
-
Inferenza Interattiva da Terminale:
make rag-predict RAG_TEXT="Ἆρες Ἆρες βροτολοιγὲ μιαιφόνε τειχεσιβ[....]" RAG_LM=Qwen/Qwen2.5-7B-Instruct
Per monitorare lo stato di avanzamento del progetto, incluse nuove funzionalità, correzioni di bug, refactoring e aggiornamenti dei pacchetti, puoi fare riferimento al file CHANGELOG.md.