Modelli AI
Catalogo dei modelli, parametri di generazione, prompt di sistema, fallback, budget e assegnazione ai progetti.
Un modello AI in Blu Pantheon è una configurazione riutilizzabile che unisce il provider, il modello di linguaggio, i parametri di generazione e il prompt di sistema. Puoi definire più modelli e assegnarne uno diverso a ogni progetto.
Prima di iniziare
- Ruolo con permesso identity:models:write
- Almeno un provider abilitato sul tenant
- Piano Business o superiore per i provider self-hosted
Catalogo dei modelli
L'elenco mostra i modelli disponibili sul tuo tenant con provider, contesto massimo, costo indicativo per milione di token e stato.
| Provider | Modello | Contesto | Punti di forza | Uso consigliato |
|---|---|---|---|---|
| Azure OpenAI | gpt-4.1 | 128k | Ragionamento, function calling | Assistenza complessa, strumenti |
| Azure OpenAI | gpt-4.1-mini | 128k | Latenza bassa, costo ridotto | Chat ad alto volume |
| Anthropic | claude-sonnet-4 | 200k | Documenti lunghi, tono naturale | Knowledge base estese |
gemini-2.5-pro | 1M | Contesto molto ampio, multimodale | Analisi documentale | |
| Mistral | mistral-large | 128k | Residenza dati UE | Requisiti di sovranità |
| Self-hosted | llama-3.3-70b | 128k | Nessun dato verso terzi | Ambienti isolati |
Residenza dei dati
Se il tuo settore richiede il trattamento dei dati esclusivamente nell'Unione Europea, filtra il catalogo con Regione = EU. Vedi Conformità.
Creare un modello
Assegna nome e descrizione
Usa un nome parlante, ad esempio Assistente clinica — produzione.
La descrizione è visibile agli altri amministratori del tenant.
Seleziona provider e modello
Il campo Modello si popola in base al provider. Se il modello desiderato non compare, il provider non è abilitato: contatta il supporto.
Imposta i parametri di generazione
Parti dai valori consigliati nella tabella sottostante e modificali solo dopo aver misurato i risultati nel playground.
Scrivi il prompt di sistema
È il documento che definisce ruolo, limiti e stile dell'assistente. Usa il modello copiabile più avanti in questa pagina.
Configura fallback e budget
Indica il modello di riserva e il tetto di spesa mensile.
Salva e collauda
Seleziona Salva, poi apri il playground e verifica almeno cinque domande reali.
Parametri di generazione
Campi della configurazione modello
| Parametro | Tipo | Obblig. | Default | Descrizione |
|---|---|---|---|---|
provider | string | Sì | — | Fornitore del modello. Determina regione, costi e funzionalità disponibili. |
model | string | Sì | — | Identificativo del modello, ad esempio gpt-4.1-mini. |
temperature | number | No | — | Casualità della generazione, da 0 a 2. Consigliato 0.3 per assistenza operativa. |
top_p | number | No | — | Campionamento nucleare, da 0 a 1. Consigliato 0.9. Non modificare insieme a temperature. |
max_output_tokens | number | No | — | Lunghezza massima della risposta. Consigliato 800 per chat, 2000 per riepiloghi. |
frequency_penalty | number | No | — | Penalità sulle ripetizioni, da 0 a 2. Consigliato 0.2. |
presence_penalty | number | No | — | Incentivo a introdurre nuovi argomenti, da 0 a 2. Consigliato 0. |
timeout_ms | number | No | — | Tempo massimo di attesa della risposta. Consigliato 30000 millisecondi. |
stream | boolean | No | — | Abilita la risposta progressiva token per token. Consigliato attivo per il widget. |
system_prompt | string | Sì | — | Istruzioni permanenti fornite al modello a ogni richiesta. |
fallback_model_id | string | No | — | Modello usato se il primario non risponde o supera il budget. |
monthly_budget_eur | number | No | — | Tetto di spesa mensile in euro. Al superamento si applica la politica scelta. |
budget_policy | string | No | — | Comportamento oltre il budget: fallback, blocca oppure notifica. |
Temperatura consigliata per caso d'uso
| Caso d'uso | Temperature | Note |
|---|---|---|
| Assistenza medica e sanitaria | 0.1 – 0.2 | Priorità assoluta all'accuratezza |
| Supporto tecnico e FAQ | 0.2 – 0.3 | Risposte riproducibili |
| Prenotazioni e front office | 0.3 | Tono cordiale ma prevedibile |
| Consulenza commerciale | 0.4 – 0.5 | Serve un po' di variazione |
| Generazione di testi marketing | 0.7 – 0.9 | Creatività desiderata |
| Brainstorming interno | 1.0 | Solo per uso interno |
Non regolare due manopole insieme
Modifica temperature oppure top_p, mai entrambi nella stessa iterazione:
gli effetti si sommano e diventa impossibile attribuire il risultato.
Prompt di sistema
Il prompt di sistema è la parte più determinante della configurazione. Struttura sempre in cinque blocchi: identità, ambito, regole, formato, escalation.
# IDENTITÀ
Sei l'assistente virtuale di Poliambulatorio Acme, con sede a Milano.
Ti chiami Aura. Parli italiano, sei cortese, sintetico e professionale.
Dai sempre del "tu" al paziente, senza mai usare formule burocratiche.
# AMBITO
Rispondi esclusivamente su questi argomenti:
- informazioni sulle prestazioni offerte dal poliambulatorio;
- disponibilità e prenotazione di visite ed esami;
- preparazione agli esami, documenti da portare, tempi di attesa;
- orari, sedi, parcheggi, modalità di pagamento e convenzioni;
- ritiro dei referti.
# REGOLE
1. Non formulare diagnosi, non interpretare referti, non suggerire terapie
né dosaggi di farmaci. In questi casi rispondi che serve la valutazione
di un medico e proponi la prenotazione di una visita.
2. Usa esclusivamente le informazioni presenti nella knowledge base e nei
risultati degli strumenti. Se l'informazione non è disponibile, dichiaralo
apertamente e proponi il contatto con la segreteria.
3. Non inventare mai prezzi, orari, nomi di medici o disponibilità.
Per queste informazioni invoca sempre lo strumento previsto.
4. Non chiedere né registrare dati sanitari non necessari alla prenotazione.
I dati richiesti sono: nome, cognome, recapito telefonico, email.
5. Se il paziente descrive sintomi che indicano un'emergenza (dolore toracico,
difficoltà respiratorie, perdita di coscienza, emorragia, trauma grave),
interrompi ogni altra attività e invita a chiamare immediatamente il 112.
# FORMATO
- Massimo 4 frasi per risposta, salvo elenchi di prestazioni o istruzioni di preparazione.
- Usa elenchi puntati quando fornisci più di due informazioni.
- Concludi con una domanda che faccia avanzare la conversazione.
- Non usare emoji. Non usare grassetto se non per date e orari.
# ESCALATION
Passa la conversazione a un operatore umano quando:
- il paziente lo richiede esplicitamente;
- si tratta di un reclamo, di un rimborso o di una contestazione;
- hai fornito due risposte consecutive senza risolvere la richiesta;
- la richiesta riguarda dati di un altro paziente.
Prima dell'escalation riepiloga in una frase quanto raccolto.Suggerimento
Mantieni il prompt sotto le 800 parole. Le istruzioni che dipendono dai dati (listino, orari, medici) vanno nella knowledge base o negli strumenti, non nel prompt.
Versionamento del prompt
Ogni salvataggio del prompt crea una nuova versione immutabile.
| Azione | Effetto |
|---|---|
| Confronta | Mostra le differenze riga per riga tra due versioni |
| Ripristina | Crea una nuova versione con il contenuto di quella selezionata |
| Etichetta | Assegna un'etichetta, ad esempio v3-triage-sicuro |
| Promuovi | Rende la versione attiva in produzione |
Le versioni restano disponibili per 24 mesi e sono tracciate nell'audit log.
Modello di fallback
Il fallback interviene quando il modello primario restituisce un errore, supera il timeout oppure il budget mensile è esaurito.
| Condizione | Comportamento predefinito |
|---|---|
| Timeout superato | Un tentativo sul primario, poi fallback |
Errore 429 (limite di frequenza) | Attesa di 2 secondi, poi fallback |
Errore 5xx del provider | Fallback immediato |
| Budget mensile esaurito | Politica definita in budget_policy |
| Fallback non disponibile | Messaggio di cortesia e proposta di handover |
Coerenza del fallback
Assegna al modello di fallback lo stesso prompt di sistema del primario, altrimenti il tono delle risposte cambia in modo percepibile per l'utente.
Limiti di costo e budget
- Budget mensile: tetto di spesa in euro per il modello.
- Soglia di avviso: percentuale che genera una notifica, tipicamente 80%.
- Limite per sessione: token massimi consumabili da una singola conversazione.
- Limite per progetto: quota assegnata a ciascun progetto sul budget complessivo.
Il consumo aggiornato è consultabile nella sezione seguente.
Test nel playground
Il playground esegue il modello con la configurazione corrente senza pubblicarla. Mostra la risposta, i token consumati, la latenza e le eventuali chiamate agli strumenti.
Prepara un set di domande di riferimento
Raccogli almeno 20 domande reali dei tuoi utenti, comprese quelle fuori ambito e quelle a cui l'assistente non deve rispondere.
Esegui e annota
Per ogni domanda valuta: correttezza, tono, lunghezza, presenza di citazioni.
Confronta due configurazioni
Attiva Confronto A/B per eseguire la stessa domanda su due modelli affiancati.
Esporta il risultato
Seleziona Esporta CSV per allegare le evidenze alla richiesta di approvazione interna.
Assegnare il modello a un progetto
Seleziona il modello dall'elenco e conferma con Applica. La modifica è immediata in ambiente di sviluppo; in produzione richiede la pubblicazione del progetto. Vedi Progetti.
Identificativo del modello da usare nelle API
mdl_4b81c6de92f14aa7Passa questo valore nel campo model_id delle chiamate REST.
Impostazione via API
/identity/v1/projects/{projectId}/modelBearer JWTAggiorna il modello assegnato a un progetto senza passare dalla Console.
{
"model_id": "mdl_4b81c6de92f14aa7",
"temperature": 0.3,
"max_output_tokens": 800,
"fallback_model_id": "mdl_9ac0117e33d8420b"
}Il riferimento completo è in API.
Risoluzione dei problemi
Riduci max_output_tokens a 500 e aggiungi al prompt il vincolo
"Massimo 4 frasi per risposta". Il vincolo testuale da solo non è sufficiente.
Abbassa temperature a 0.2, rafforza la regola 2 del prompt e verifica che la
knowledge base sia indicizzata. Attiva le citazioni obbligatorie nel progetto.
Il problema è quasi sempre la descrizione dello strumento, non il modello. Vedi Strumenti.
Attiva stream, riduci max_output_tokens e passa a un modello mini per i progetti
ad alto volume. Verifica anche il numero di documenti recuperati dalla knowledge base.