README.md

---
base_model: facebook/seamless-m4t-v2-large
library_name: peft
license: mit
language:
- it
- en
- fr
- es
pipeline_tag: translation
tags:
- base_model:adapter:facebook/seamless-m4t-v2-large
- lora
- transformers
- qlora
- nmt
- multilingual
- italian
- technical-translation
---

# LEO — Language Extraction and Optimization
## SeamlessM4T v2 Large · QLoRA Fine-tune · Testi tecnici IT → EN/FR/ES

**Progetto:** [LEO su GitHub](https://github.com/MaxDvTn/LEO)
**Autori:** Massimo Bosetti — Liceo Da Vinci,  
      Manuel Masera ;
      Federico Mauri, Mattia Ndria, Muad Berkane, Stefano Brol 
      Vittorio Pendenza ;
      Alex Valzolgher;
      Syed Islam ;
      Giacomo Gubert.
**Dataset:** Documenti tecnici Roverplastik (IT → EN, FR, ES)

---

## Model Details

### Model Description

LEO (*Language Extraction and Optimization*) è un sistema di traduzione automatica multilingua specializzato su testi tecnici in italiano, sviluppato come progetto scolastico presso il Liceo Da Vinci di Rovereto.

Il modello fine-tuna **Seamless-M4T v2 Large** (Meta AI, 1.3B parametri) tramite **QLoRA** (Quantized Low-Rank Adaptation), consentendo l'addestramento su una singola GPU consumer (NVIDIA RTX 4090).

- **Developed by:** Massimo Bosetti — Liceo Da Vinci, Rovereto (TN)
- **Funded by:** Liceo Leonardo Da Vinci, Trento (progetto scolastico)
- **Shared by:** Massimo Bosetti
- **Model type:** Text-to-Text Neural Machine Translation — QLoRA adapter su Seamless-M4T v2 Large
- **Language(s):** Italiano (input) → Inglese, Francese, Spagnolo (output)
- **License:** MIT
- **Finetuned from:** `facebook/seamless-m4t-v2-large`

### Model Sources

- **Repository:** https://github.com/MaxDvTn/LEO
- **Demo:** Disponibile via Hugging Face Spaces (accesso istituzionale `@liceodavincitn.it`)

---

## Uses

### Direct Use

LEO è progettato per la traduzione automatica di **testi tecnici in italiano** verso inglese, francese e spagnolo. Adatto a:

- Documentazione tecnica di prodotto (edilizia, manifattura, materiali)
- Schede tecniche e manuali
- Comunicazione aziendale in contesti plurilingue

```python
from transformers import AutoProcessor, SeamlessM4Tv2Model
from peft import PeftModel

base_model = SeamlessM4Tv2Model.from_pretrained("facebook/seamless-m4t-v2-large")
model = PeftModel.from_pretrained(base_model, "maxbsdv/LEO-SeamlessM4T-v2-Large-Roverplastik")
processor = AutoProcessor.from_pretrained("facebook/seamless-m4t-v2-large")

text = "La membrana è incombustibile e resistente alle alte temperature."
inputs = processor(text=text, src_lang="ita_Latn", return_tensors="pt")
output = model.generate(**inputs, tgt_lang="eng_Latn")
translation = processor.decode(output[0], skip_special_tokens=True)
print(translation)
```

### Out-of-Scope Use

- Testi non tecnici o letterari (modello specializzato su dominio tecnico/industriale)
- Lingue diverse da IT/EN/FR/ES
- Uso in contesti medici, legali o di sicurezza critica senza validazione umana

---

## Bias, Risks, and Limitations

- Addestrato su dataset di nicchia (documentazione Roverplastik): performance variabili su altri domini tecnici.
- Termini molto specifici o rari possono essere tradotti in modo impreciso.
- L'italiano → inglese è la direzione più difficile (BLEU 0.35 vs 0.49 per ita→spa).
- Come tutti i modelli NMT, può produrre traduzioni plausibili ma semanticamente errate su frasi ambigue.

### Recommendations

- Verificare sempre le traduzioni con un revisore umano in contesti critici.
- Performa meglio su frasi tecniche brevi e ben strutturate (< 100 token).
- Per testi lunghi, segmentare in frasi prima della traduzione.

---

## How to Get Started with the Model

```python
from transformers import AutoProcessor, SeamlessM4Tv2Model
from peft import PeftModel
import torch

base = SeamlessM4Tv2Model.from_pretrained(
    "facebook/seamless-m4t-v2-large",
    load_in_4bit=True,
    device_map="auto"
)
model = PeftModel.from_pretrained(base, "maxbsdv/LEO-SeamlessM4T-v2-Large-Roverplastik")
processor = AutoProcessor.from_pretrained("facebook/seamless-m4t-v2-large")

def translate(text, src="ita_Latn", tgt="eng_Latn"):
    inputs = processor(text=text, src_lang=src, return_tensors="pt")
    with torch.no_grad():
        out = model.generate(**inputs, tgt_lang=tgt, max_new_tokens=256)
    return processor.decode(out[0].tolist(), skip_special_tokens=True)

# Esempi
print(translate("La finestra prefabbricata deve essere installata con guarnizione perimetrale."))
# → "The prefabricated window must be installed with a perimeter gasket."

print(translate("La coibentazione dei finestroni garantisce l'isolamento termico.", tgt="fra_Latn"))
# → "L'isolation des grandes fenêtres garantit l'isolation thermique."
```

---

## Training Details

### Training Data

Fine-tuning su dataset proprietario di documenti tecnici **Roverplastik** (Rovereto, TN), estratti tramite:
- PDF mining di schede tecniche e manuali di prodotto
- Web scraping del sito aziendale multilingue
- Generazione di glossari tecnici domain-specific

Formato CSV bilingue con codici **FLORES-200** (`ita_Latn`, `eng_Latn`, `fra_Latn`, `spa_Latn`).

### Training Procedure

#### Preprocessing

- Tokenizzazione con **SentencePiece** (tokenizer nativo di Seamless-M4T)
- Filtro per lunghezza massima 512 token
- Deduplicazione e pulizia del testo (normalizzazione Unicode)

#### Training Hyperparameters

- **Training regime:** bf16 mixed precision (GPU Ampere+)
- **Learning rate:** 2e-4 con Cosine Annealing scheduler
- **Batch size:** 4 (gradient accumulation ×4 → effective batch 16)
- **Epochs:** 20 (best checkpoint su val_BLEU)
- **Optimizer:** AdamW (β₁=0.9, β₂=0.999)
- **Warm-up steps:** 100 (linear)
- **LoRA rank (r):** 8 · **alpha:** 16 · **dropout:** 0.1
- **Target modules:** q_proj, k_proj, v_proj, o_proj
- **Quantization:** 4-bit NF4 via bitsandbytes

#### Speeds, Sizes, Times

- **Parametri trainable (LoRA):** ~3.4M su 1.3B totali (0.26%)
- **VRAM inference (4-bit):** ~3 GB
- **Hardware:** NVIDIA RTX 4090 24GB — Single GPU — locale
- **Tempo training:** ~6 ore (20 epoche)
- **Esperimenti tracciati (W&B):** 37 run

---

## Evaluation

### Testing Data, Factors & Metrics

#### Testing Data

Set di test indipendente estratto dagli stessi documenti tecnici Roverplastik, con traduzioni di riferimento verificate manualmente (39 run di valutazione).

#### Metrics

- **BLEU** — n-gram precision tra output e reference
- **ChrF** — character n-gram F-score (robusto per lingue romanze)
- **METEOR** — considera sinonimi e varianti morfologiche

### Results

| Direzione | BLEU | ChrF | METEOR |
|-----------|:----:|:----:|:------:|
| ita → spa | **0.49** | **0.40** | **0.52** |
| ita → fra | 0.46 | 0.35 | 0.45 |
| ita → eng | 0.35 | 0.28 | 0.31 |

Miglioramento rispetto al modello base (improvement_METEOR): fino a **+0.37** sul run ottimale.
Regressioni identificate: 43 casi (word-level error analysis disponibile nel repository).

### Summary

QLoRA fine-tuning di Seamless-M4T v2 Large porta miglioramenti concreti e misurabili rispetto al modello base non specializzato, mantenendo i requisiti hardware accessibili (singola GPU consumer, no cloud).

---

## Environmental Impact

- **Hardware Type:** NVIDIA RTX 4090 (24 GB VRAM)
- **Hours used:** ~16 ore totali (training + sperimentazione, 37 run)
- **Cloud Provider:** N/A — training locale
- **Compute Region:** Rovereto, Italia
- **Carbon Emitted:** stimato < 0.5 kg CO₂eq