Profili dei modelli, contesto ed Extra JSON

Cosa definisce un profilo

In Sapphire I.C.D.S. il modello descrive le capacità tecniche, mentre il profilo stabilisce le regole per usarle. Per uno stesso modello si possono creare, ad esempio, un profilo di assistenza rigoroso, un profilo di classificazione conciso e un profilo di analisi esteso. Ciascuno avrà una propria istruzione di sistema, lunghezza della risposta e budget di contesto, ma tutti devono rientrare nei limiti dello stesso modello registrato.

Nella sezione AI Settings → Profiles selezionate provider e modello. Devono corrispondere: un profilo non può essere associato al modello di un altro provider. Profile key è un identificatore macchina stabile, ad esempio support_ru. Non usate il nome di un dipendente o un numero temporaneo di attività. Un profilo attivo è disponibile per la selezione, mentre il profilo predefinito viene usato quando il client non specifica una registrazione. Impostatelo come default solo dopo averlo verificato.

Istruzione di sistema e formato della risposta

System prompt definisce il ruolo e le regole permanenti della modalità scelta. Scrivetelo come un contratto verificabile: ambito delle attività, lingua, formato del risultato, vincoli e criterio di completamento. Non inserite chiavi API, dati personali, l'intero contenuto della knowledge base o istruzioni che l'operatore deve cambiare per ogni richiesta.

All'avvio, il sistema parte dall'istruzione di sistema del profilo e aggiunge le istruzioni gestionali attive come politica aziendale obbligatoria. La cronologia della sessione e il suo riepilogo restano dati. Memoria e knowledge base non vengono caricate integralmente nel prompt: il modello le recupera su richiesta tramite gli strumenti consentiti. Pertanto, ampliare il system prompt non sostituisce la configurazione di istruzioni, memoria, conoscenze e diritti degli strumenti.

Definite Response format solo in una forma compresa dall'adattatore e dal modello selezionati. Per una normale conversazione, una risposta testuale è un punto di partenza sicuro. Se serve JSON strutturato, verificate prima che sia supportato dal modello e dal consumer: una stringa nel profilo, da sola, non garantisce la conformità al vostro schema aziendale.

Reasoning, Temperature e Top P

Usate Reasoning effort solo con modelli che documentano tale modalità. Non copiate un valore da un'altra famiglia. Temperature e Top P dispongono di interruttori separati. Se un parametro è disattivato, il profilo non deve imporlo al provider; è preferibile rispetto all'invio accidentale di un valore zero. Di solito è sufficiente controllare un solo metodo di variabilità e lasciare disattivato l'altro. Per l'estrazione di fatti e la classificazione si scelgono impostazioni più stabili, per generare varianti impostazioni più libere, ma l'intervallo specifico va sempre confrontato con la documentazione del modello.

Come viene calcolato il contesto

La registrazione del modello contiene tre limiti massimi: contesto totale, input massimo e output massimo. Il profilo definisce quattro valori operativi. Max output tokens limita una singola risposta. Active context tokens è il budget che l'agente può utilizzare. Compaction reserve tokens è la parte di tale budget riservata alla compattazione sicura. La soglia automatica è:

active_context_tokens - compaction_reserve_tokens

La riserva deve essere positiva e rigorosamente inferiore al budget attivo. Il budget attivo non può superare l'input massimo del modello, il limite di risposta non può superare l'output massimo e la loro somma non può superare il contesto totale. Ad esempio, con contesto 128000, input 120000 e output 8192, si possono impostare un budget attivo di 64000, una riserva di 16000 e una risposta di 4096. La soglia di compattazione sarà 48000. È solo un esempio aritmetico, non una raccomandazione universale per tutti i modelli.

Maximum agent rounds limita il numero di cicli modello-strumento, mentre Maximum agent runtime limita il tempo totale in secondi. Il valore 0 indica l'assenza di questo specifico limite del profilo, ma non annulla i limiti del provider, l'annullamento da parte dell'utente, la protezione dalla mancanza di progressi o i vincoli di sistema. Per uno scenario critico o costoso, impostate valori finiti espliciti e misurate il funzionamento reale prima di aumentarli.

Streaming e cambio di modello

L'interruttore streaming determina la modalità preferita di erogazione della risposta. Non rende in streaming un'API sincrona se il provider non lo supporta. Quando cambiate modello, create un nuovo profilo oppure ricalcolate con attenzione tutti i budget. Lo stato di compattazione associato a una coppia provider-modello non può essere considerato trasferibile a un'altra coppia.

Extra JSON senza sorprese nascoste

Extra JSON è un oggetto JSON facoltativo per parametri aggiuntivi documentati da uno specifico provider. È un'estensione, non un secondo profilo. Iniziate con un oggetto vuoto:

{}

Se l'API richiede davvero un'opzione aggiuntiva, aggiungete solo quella. Esempio neutro della forma:

{
  "metadata": {
    "integration": "sapphire-docs"
  }
}

L'esempio è valido solo quando l'API selezionata supporta il campo metadata. Il JSON deve essere un oggetto con virgolette doppie, senza commenti o virgole finali. Non inserite secret, Authorization, base URL, model key, identificatori utente o contenuti riservati.

Non duplicate in Extra JSON i campi principali della richiesta, come modello, strumenti, scelta dello strumento, messaggi di input, temperature, Top P e max output tokens. Un conflitto complica la diagnostica e può modificare il comportamento dopo un aggiornamento dell'adattatore. Il campo enable_tools non consente di aggirare la gestione degli strumenti e una configurazione arbitraria non deve sostituire la politica di contesto gestita. Gli strumenti sono autorizzati dal catalogo del server, dai diritti del gruppo e dalla selezione della sessione.

Verifica del profilo

1. Salvate il profilo attivo, ma non impostatelo come predefinito.
2. Create una nuova sessione e selezionate esplicitamente il profilo.
3. Verificate una risposta breve, l'istruzione di sistema e il formato dichiarato.
4. Eseguite un test lungo osservando la soglia del contesto e la compattazione.
5. Verificate l'arresto per numero di cicli e tempo, se i limiti non sono zero.
6. Aggiungete le chiavi di Extra JSON una alla volta e ripetete il test.
7. Solo dopo impostate il profilo come default.

Se la richiesta viene rifiutata, svuotate innanzitutto Extra JSON, disattivate i parametri di sampling facoltativi e ripetete il test minimo. Quindi verificate i limiti e il supporto di reasoning/response format. Questo ordine distingue un errore della registrazione di base da un'opzione aggiuntiva incompatibile.

Come scegliere la dimensione del budget

Non partite dal massimo del modello, ma da uno scenario operativo misurato. Valutate la lunghezza dell'istruzione di sistema, la cronologia tipica, i risultati attesi dagli strumenti e il margine per la risposta. Un active context troppo grande aumenta costi e tempi di elaborazione, mentre uno troppo piccolo causa compattazioni frequenti. La riserva deve consentire di creare un riepilogo corretto prima di raggiungere il limite rigido, quindi non può essere ridotta a un valore simbolico.

Separate i profili per attività diverse quando cambiano i requisiti di lunghezza, reasoning o tempo. Un unico profilo «universale» è più difficile da verificare e modificare in sicurezza. Registrate lo scopo del profilo nel nome e nella descrizione della procedura operativa, ma non incorporate routing o diritti nel system prompt: la selezione del profilo e l'autorizzazione degli strumenti sono controllate da altri livelli.