Laya: come installarlo in locale e smistare email e ticket

Laya è un modello di Convai Innovations che non scrive testo. I pesi sono aperti, con licenza Apache 2.0. Gli date un testo (un’email, un ticket o un documento JSON) e alcune domande tipizzate, e per ogni domanda Laya restituisce una scelta con le probabilità di tutte le opzioni. Serve a chi vuole mandare i messaggi al reparto giusto, assegnare etichette o rispondere sì o no in automatico senza usare un modello generativo. La guida parte dall’installazione del pacchetto Python ufficiale e arriva a una prima decisione da riga di comando e alla classificazione di un testo in italiano. I comandi sono quelli della documentazione ufficiale, elencata in fondo.

Cos’è Laya e quale versione scegliere

La scheda del modello su Hugging Face descrive Laya come un modello di decisione non autoregressivo, che risponde a tutte le domande in un solo passaggio. Non genera testo, quindi non c’è niente da interpretare. Le domande sono di tre tipi:

• choice sceglie un’etichetta fra quelle che definite voi (per esempio billing, technical, other) e restituisce le probabilità di tutte le opzioni;
• score colloca il testo su una scala ordinata (non urgente, presto, bloccante) e restituisce il livello atteso;
• noul verifica un’affermazione e restituisce la probabilità che sia vera, da 0,0 a 1,0.

Le opzioni si definiscono al momento della richiesta, quindi per uno schema nuovo non serve riaddestrare il modello. Fra gli usi tipici il sito di Convai Innovations cita lo smistamento dei ticket, il riconoscimento di spam e phishing, il controllo dei prompt e la valutazione dell’urgenza.

I checkpoint sono tre e stanno tutti nello stesso repository su Hugging Face:

Il checkpoint principale legge solo l’inglese. Non serve scegliere a mano: il componente Router del pacchetto riconosce alfabeto e lingua e manda al multilingue i testi che non sono in inglese, quindi anche quelli in italiano.

Cosa serve

• Python 3.10 o più recente. Il README su GitHub spiega che questa versione minima la impongono le dipendenze (huggingface_hub 1.x, transformers 5.x e torch 2.14).
• Una connessione a internet, per scaricare il pacchetto da PyPI e, al primo uso, il checkpoint da Hugging Face. Dopo il primo download il checkpoint viene letto dalla cache locale.
• Spazio su disco per i pesi: circa 808 MB per il checkpoint inglese e circa 647 MB per quello multilingue, secondo il sito ufficiale. Viene scaricato solo il checkpoint che serve, non l’intero pacchetto da circa 2,5 GB.
• Una GPU non è obbligatoria: con i checkpoint già caricati la documentazione riporta da 193 a 464 ms per richiesta su CPU e 32,8 ms su una GPU T4.
• Su Debian e Ubuntu, con il Python di sistema, può servire il pacchetto python3-venv.

Le istruzioni del README valgono per macOS, Linux e Windows (PowerShell). Se vi serve una build di PyTorch solo CPU o per una GPU specifica, scegliete il comando nella guida di PyTorch ed eseguitelo dopo aver creato l’ambiente e prima di installare Laya, sostituendo pip o pip3 con il Python dell’ambiente seguito da -m pip.

Creare l’ambiente virtuale Python

Un ambiente virtuale è una cartella con un’installazione di Python separata dal resto del sistema: Laya e le sue dipendenze, PyTorch compreso, finiscono lì e non toccano gli altri progetti. Aprite il terminale nella cartella del progetto. Su macOS e Linux:

python3 -m venv .venv

Su Windows, in PowerShell, l’esempio del README usa il launcher py con Python 3.11. Con un’altra versione, purché sia la 3.10 o successiva, cambiate il numero dopo il trattino.

py -3.11 -m venv .venv

Se il comando riesce, nella cartella compare la sottocartella .venv. Se su Debian o Ubuntu compare un errore che dice che ensurepip non è disponibile, installate python3-venv e ripetete il comando.

Installare il pacchetto ufficiale laya

Il README consiglia di chiamare il Python dell’ambiente con il suo percorso: così installazione e verifica avvengono nell’ambiente giusto anche senza attivarlo. Il comando scarica da PyPI il pacchetto e le sue dipendenze. Su macOS e Linux:

.venv/bin/python -m pip install laya

Su Windows, in PowerShell:

.\.venv\Scripts\python.exe -m pip install laya

Per ora non usate la forma breve pip install laya della scheda di Hugging Face: con l’ambiente non attivo installerebbe il pacchetto nel Python di sistema. Va bene dopo l’attivazione, descritta più avanti.

Verificare che l’installazione sia andata a buon fine

Questo controllo stampa la versione di Laya senza caricare nessun checkpoint, quindi non scarica niente. L’opzione -I esclude la cartella corrente dai percorsi in cui Python cerca i moduli, così una copia locale del codice sorgente non può nascondere un’installazione mancante. Su macOS e Linux:

.venv/bin/python -I -c "import laya; print(laya.__version__)"

Su Windows:

.\.venv\Scripts\python.exe -I -c "import laya; print(laya.__version__)"

Se compare un numero di versione, il pacchetto è installato (il README consultato arriva alla 0.3.24). Se compare ModuleNotFoundError: No module named 'laya', state usando un Python diverso da quello dell’ambiente.

Attivare l’ambiente per usare il comando laya

Il pacchetto installa anche il comando laya, comodo per le prove dal terminale. Per usarlo senza scrivere il percorso completo bisogna attivare l’ambiente: come spiega la guida di Python Packaging, l’attivazione aggiunge al PATH della shell gli eseguibili dell’ambiente. Su macOS e Linux:

source .venv/bin/activate

Per controllare che l’ambiente sia attivo chiedete alla shell quale Python sta usando: il percorso stampato deve finire con .venv/bin/python.

which python

Su Windows la guida di Python Packaging indica questo comando:

.venv\Scripts\activate

Nel Prompt dei comandi avvia lo script activate.bat; in PowerShell lo script è Activate.ps1, nella stessa cartella, e la documentazione Python del modulo venv lo indica come .\.venv\Scripts\Activate.ps1. PowerShell può rifiutarsi di eseguirlo con un errore che dice che l’esecuzione di script è disabilitata.

La documentazione di venv prevede due soluzioni. La prima non tocca il sistema: non attivate l’ambiente e lanciate gli eseguibili con il percorso completo, che funzionano anche così. Il comando diventa .\.venv\Scripts\laya.exe su Windows (.venv/bin/laya su macOS e Linux), seguito dagli stessi argomenti degli esempi più avanti.

La seconda è cambiare il criterio di esecuzione di PowerShell. Attenzione: è un’impostazione di sicurezza di Windows, vale per tutti gli script PowerShell che lancerete con il vostro account e resta in vigore finché non la cambiate di nuovo. Il parametro -Scope CurrentUser limita la modifica al vostro utente. Se accettate, il comando indicato dalla documentazione Python è Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser; poi ripetete l’attivazione.

In PowerShell non usate where python come controllo: lì where è un alias del cmdlet Where-Object, che filtra oggetti e non cerca eseguibili. Su Windows il controllo affidabile è la verifica della versione con il percorso esplicito.

Con l’ambiente attivo potete usare anche la forma breve della scheda di Hugging Face, che ora installa nell’ambiente:

pip install laya

Quando chiudete il terminale l’ambiente si disattiva: in una nuova finestra va riattivato.

Prima decisione da riga di comando

Se a laya passate solo un testo, il comando calcola soltanto l’instradamento, cioè quale checkpoint userebbe, e non scarica nulla. Con --predict carica il checkpoint scelto e restituisce le risposte complete. La prima volta serve una connessione a Hugging Face; se il download non riesce, il comando lo segnala invece di andare in errore.

laya "Refactor this service" --predict

Senza domande indicate, il comando usa un insieme predefinito pensato per la scelta del modello, non per lo smistamento per reparto: prendete questa prova come un controllo che tutto funzioni. Per decisioni utili il README documenta due alternative. --preset triage usa un insieme di domande già pronto (gli altri preset sono email, guard, moderation e router). --questions, seguito dal nome di un file JSON, usa domande scritte da voi, nello stesso formato del codice Python, e implica già --predict.

Quando una decisione sbagliata costa cara potete fissare una soglia di confidenza. La soglia segnala le risposte incerte ma non dimostra che la decisione sia corretta: la documentazione riporta casi in cui il modello resta molto sicuro pur sbagliando.

laya "Refund my card" --predict --min-confidence 0.9

Aggiungendo --json (laya "Refund my card" --predict --min-confidence 0.9 --json) ottenete anche i campi di astensione: ogni risposta riporta passed, abstained o unevaluated, e quelle sotto la soglia vengono segnate con low_confidence: True, così i casi dubbi possono passare a una persona. Il README avverte che la stessa soglia non vale allo stesso modo se cambia il numero di opzioni.

Prima decisione su un testo in italiano con Router

Per usare domande vostre potete passare un file JSON al comando laya con --questions oppure scrivere uno script Python, come nell’esempio seguente. Il punto di partenza è il primo blocco Python della sezione Quickstart del README, che comincia con from laya import Router, crea un Router() e definisce tre domande:

• department, di tipo choice, che sceglie fra billing, technical e other;
• urgency, di tipo score, su tre livelli;
• churn_risk, di tipo noul, che chiede se l’utente minaccia di disdire.

Salvate il blocco nella cartella del progetto, per esempio come prova.py, e sostituite il testo fra virgolette di state con un’email in italiano, per esempio una richiesta di rimborso per un addebito doppio. Istruzioni ed etichette possono restare in inglese: nel README la stessa domanda viene applicata a testi in hindi e in spagnolo. Avviate lo script con .venv/bin/python prova.py (su Windows con .\.venv\Scripts\python.exe prova.py), oppure con python prova.py se l’ambiente è attivo.

Lo script stampa tre righe: l’etichetta scelta per department, la probabilità che la risposta a churn_risk sia sì e il checkpoint che ha risposto. Per un testo in italiano il checkpoint atteso è multilingual; il campo result["routing"] riporta anche il motivo della scelta.

Attenzione ai testi brevi: un testo corto in alfabeto latino spesso non basta a riconoscere la lingua e finisce sul checkpoint predefinito, quello inglese. Le soluzioni documentate sono tre:

• creare il router con Router(default="multilingual"), se la maggior parte dei testi non è in inglese;
• passare a predict l’indicazione lang_guess="it";
• scegliere il checkpoint con model="multilingual", che insieme a max_len=8192 serve anche per i documenti lunghi.

Senza Router, laya.load("convaiinnovations/laya", subfolder="multilingual") carica direttamente il checkpoint multilingue e scarica solo quella sottocartella.

Smistare più ticket in una volta

Con molti messaggi conviene lavorare in blocco, perché le richieste condividono il caricamento del checkpoint e i passaggi del modello: su 20 ticket il README riporta un’elaborazione 2,6 volte più veloce rispetto all’invio uno alla volta. Nella cartella del progetto create un file tickets.txt con una richiesta per riga. La forma base del comando è questa:

laya --batch tickets.txt --predict

Così però il comando risponde alle domande predefinite dedicate alla scelta del modello, non classifica i ticket per reparto. Le opzioni --preset e --questions funzionano anche con --batch:

• per classificare i ticket con le domande di triage già pronte: laya --batch tickets.txt --preset triage --json;
• per scegliere fra i vostri reparti, salvate la domanda department in un file JSON (per esempio domande.json) e usate laya --batch tickets.txt --questions domande.json --json.

Con --json ottenete una riga JSON di risposte per ogni richiesta; --batch-size limita quante richieste vengono elaborate in un singolo passaggio. Ogni riga viene instradata per conto suo, quindi lo stesso file può contenere ticket in inglese e in italiano.

Limiti e specializzazione del modello

Su questo punto la documentazione va letta per intero. Il README dice che i checkpoint distribuiti funzionano zero-shot, cioè senza addestramento aggiuntivo, ma la sezione sui limiti della scheda di Hugging Face è più netta. Sul benchmark typed-decisions i checkpoint base sono vicini al caso: 0,362 l’inglese e 0,352 il multilingue, contro 0,318 di una risposta casuale e 0,461 di una scelta fissa sulla classe più frequente. Lo 0,766 pubblicizzato appartiene al checkpoint addestrato su quel benchmark. Gli autori definiscono Laya una base veloce da specializzare, non un motore di decisione zero-shot.

Gli altri limiti dichiarati includono:

• errori sulle negazioni: negli esempi di cancellazione riportati nel README, anche domande choice con etichette semantiche hanno selezionato la cancellazione per richieste che la negavano, in un caso con probabilità 0,9998. Prima di automatizzare queste decisioni, validate il checkpoint e le formulazioni effettivamente usate; cambiare le etichette o fissare una soglia di confidenza non elimina questo problema;
• checkpoint troppo sicuri di sé: nelle misurazioni riportate dagli autori, stimare una temperatura per ogni combinazione di tipo di domanda e numero di opzioni ha ridotto l’errore di calibrazione (ECE) da 0,466 a 0,081 per l’inglese e da 0,314 a 0,106 per il multilingue. Sui vostri dati occorre stimare le temperature e verificare il risultato, che può essere diverso;
• scelte che peggiorano con molte opzioni (0,425 su Banking77, che ha 77 etichette): il sito consiglia di restare sotto le 20 opzioni o di dividere la scelta in due livelli;
• le domande score sono il tipo più debole;
• le domande noul possono seguire le etichette false/true invece del testo, soprattutto con il checkpoint inglese; la scheda suggerisce di riformularle come choice a due opzioni con chiavi neutre;
• action.act_probability per ora non dà indicazioni utili: per filtrare le risposte si usa confidence.

Per specializzare il modello il README rimanda a un notebook di fine-tuning per Kaggle (con due GPU T4) e a uno script per Apple Silicon (MPS o CPU), che coprono tutto il ciclo: dataset, addestramento con RLCD, calibrazione, valutazione ed esportazione.

Le differenze rispetto a Jev

Laya si presenta come alternativa aperta a Jev di TypeSafe AI, un’API chiusa che costa 0,042 dollari per milione di token. Secondo la scheda, Laya risponde a una domanda in 32,8 ms, contro i 236-276 ms misurati per Jev da benchmark indipendenti, e va meglio su typed-decisions (0,766 contro 0,727), AG News e DAIR Emotion. I dati di Jev però vengono da pubblicazioni di terzi, con campioni e prompt diversi, perché Convai non ha accesso all’API. La scheda riconosce che Jev resta avanti con più di 20 opzioni (0,870 su Banking77, e ne supporta fino a 255), nell’accuratezza misurata sulle distribuzioni di riferimento e nella calibrazione prima della stima delle temperature.

Il pacchetto comprende anche laya-serve, un server HTTP compatibile con il protocollo di Jev che si installa con l’extra laya[serve]. Se non impostate LAYA_API_KEY, il server accetta connessioni su tutte le interfacce senza autenticazione.

Uscire dall’ambiente e disinstallare

Quando avete finito, uscite dall’ambiente virtuale:

deactivate

Per riprendere il lavoro basta riattivarlo, senza crearlo di nuovo. Per eliminare Laya del tutto vanno cancellate due cose: la cartella .venv del progetto, che contiene il pacchetto e le dipendenze, e i checkpoint scaricati nella cache di Hugging Face. Le fonti consultate non dicono dove si trovi questa cache per impostazione predefinita, solo che la variabile HF_HUB_CACHE serve a spostarla: se l’avete impostata, i pesi sono in quella cartella, altrimenti il percorso predefinito va cercato nella documentazione di Hugging Face Hub. Prima di cancellare, controllate che la cache non contenga modelli usati da altri progetti.

Se qualcosa va storto

• ModuleNotFoundError: No module named 'laya': installazione e script devono usare lo stesso Python, quello dell’ambiente. In un editor, selezionate lo stesso interprete.
• Errore su ensurepip con Debian o Ubuntu: manca il pacchetto python3-venv.
• PowerShell blocca l’attivazione: usate i percorsi completi degli eseguibili oppure cambiate il criterio di esecuzione, come spiegato nella sezione sull’attivazione.
• Manca rl_agent_config.json: il file fa parte del checkpoint, sta accanto a model.safetensors e non va creato. Per un modello locale indicate la cartella che contiene i file del checkpoint.
• laya.load() si blocca: all’avvio transformers cerca TensorFlow e, se lo trova installato, la costruzione del modello può bloccarsi. Avviate il programma con la variabile USE_TF=0.
• Poca memoria: il Router tiene in memoria fino a due checkpoint. Con Router(max_loaded=1) ne tiene uno solo, ma lo ricarica a ogni cambio di lingua (da 7 a 10 secondi). Router(preload=True) usa più memoria, quindi non è una soluzione quando la memoria manca.
• Crash su Windows con Python 3.14: il problema è stato corretto in Laya 0.3.7. Aggiornate con il Python dell’ambiente seguito da -m pip install -U laya.

Documentazione di riferimento

Pagine consultate il 3 ottobre 2026. La guida di Python Packaging e la documentazione del modulo venv sono generiche: valgono per qualsiasi pacchetto Python, non solo per Laya.

• README ufficiale di Laya su GitHub (NandhaKishorM/laya)
• Scheda del modello su Hugging Face (convaiinnovations/laya)
• Sito ufficiale di Laya, Convai Innovations
• Python Packaging User Guide: Install packages in a virtual environment using pip and venv
• Documentazione di Python, «venv — Creation of virtual environments» (docs.python.org)
• Documentazione di PowerShell su Microsoft Learn, cmdlet «Where-Object»

Leggi anche

• Gemma 4 in locale: come usarla sul PC con Ollama, LM Studio o Bionic
• LM Studio Bionic: come installarlo e usare un modello aperto in locale
• AI in locale: che computer serve tra GPU, VRAM, RAM e mini PC