Contratti per applicazioni di IA: rilevare cambiamenti di modello, SDK o strumenti prima della produzione

Una demo che risponde non dimostra la compatibilità

In un’applicazione di IA, una modifica può non generare un errore di trasporto e, nonostante ciò, compromettere il prodotto. Il modello può continuare a restituire testo utile a una persona, ma omettere un campo consumato da un servizio successivo, scegliere uno strumento non consentito, cambiare il significato operativo di un’etichetta oppure fondare una conclusione su un frammento recuperato che non la supporta. Per questo, verificare che “continui a rispondere” non equivale a verificare che mantenga il comportamento operativo previsto.

Un contratto è una specifica verificabile delle proprietà che devono essere mantenute in un confine concreto del flusso. Non è la promessa che il modello formulerà sempre la stessa frase, né un tentativo di eliminare la variabilità generativa. Definisce quali input sono ammessi, quale forma deve assumere l’output, quali invarianti di business non possono essere violate, quali azioni sono autorizzate e quali evidenze sono necessarie prima di affermare qualcosa o eseguire un’operazione.

L’unità di analisi deve essere la singola modifica incompatibile. Può trattarsi di una sostituzione del modello, di un aggiornamento dell’SDK, di una modifica al prompt di sistema, di un cambiamento dello schema, di una nuova definizione di strumento o di una policy aggiornata del fornitore. L’obiettivo è rispondere prima di promuovere la modifica: il contratto è stato preservato? Il degrado rientra in un limite accettato? Il flusso deve essere adattato? Oppure la modifica deve essere bloccata?

I contratti completano le valutazioni aggregate di qualità, ma risolvono un problema diverso. Una valutazione può indicare che l’utilità media rimane elevata anche se un caso su cento emette un ordine di annullamento senza conferma. Quel caso isolato è un’incompatibilità critica se l’azione produce effetti esterni. Analogamente, un JSON valido non dimostra che un argomento sia sicuro, che una citazione corrisponda alla fonte o che una classificazione abbia conservato il proprio significato.

Inventario dei confini e delle dipendenze

Prima di scrivere i test, disegna l’intero percorso di un caso utente. Esiste un confine ogni volta che un componente consegna una rappresentazione che un altro componente interpreta: la richiesta inviata al fornitore, l’identificatore del modello, la risposta del modello, l’adattatore dell’SDK, il recuperatore di contesto, la chiamata a uno strumento, il sistema di destinazione e l’azione esterna. Ogni confine può avere un contratto distinto e un responsabile distinto.

L’inventario deve identificare le versioni e le configurazioni effettive, non soltanto nomi generici. Registra il modello o lo snapshot richiesto, la versione dell’SDK e dell’API quando applicabile, il prompt di sistema, i parametri di generazione, lo schema di output, l’elenco degli strumenti, la definizione dei permessi, la versione dell’indice di recupero e gli adattatori interni. Senza queste informazioni, sarà difficile attribuire un guasto successivo a una causa concreta.

Non tutti i confini richiedono lo stesso tipo di asserzione. La richiesta al modello richiede il controllo dei parametri ammessi e dei valori normalizzati. Un output strutturato necessita della validazione dello schema e dei campi obbligatori. Il recupero richiede controlli su provenienza, attualità e sufficienza dell’evidenza. Gli strumenti richiedono, oltre alla sintassi, autorizzazione e simulazione degli effetti. Il sistema di destinazione necessita di idempotenza, controllo transazionale o compensazione in funzione del rischio.

La documentazione dei fornitori indica che i cicli di vita dei modelli e le interfacce possono cambiare. In particolare, il ritiro dei modelli e determinati cambiamenti di parametri possono trasformare richieste prima valide in errori. Per questo la migrazione deve essere testata come un cambiamento di dipendenza, anche se il codice di business non è cambiato.

Che cosa deve diventare un contratto

Inizia dagli elementi deterministici. Sono buoni candidati i tipi, i campi obbligatori, i limiti numerici, le enumerazioni, gli identificatori, la presenza di una fonte, il formato delle date, gli strumenti consentiti e le regole di autorizzazione. Lo sono anche le invarianti di business: un rimborso non può superare l’importo pagato, un agente non può modificare i dati di un altro cliente e un’operazione che richiede approvazione umana non può essere eseguita senza quello stato.

Aggiungi quindi i vincoli operativi. Definisci un budget di latenza e di costo per caso, con una misurazione specificata: per esempio, un percentile su un campione controllato, non un’impressione isolata. Stabilisci massimi per tentativi ripetuti, strumenti per esecuzione, documenti recuperati e dimensione del contesto. Un aumento può essere tecnicamente compatibile e tuttavia inaccettabile per il prodotto; il contratto deve separare i due piani.

Le etichette meritano un trattamento semantico esplicito. Se un output contiene `rischio_alto`, il contratto deve spiegare quali fatti lo giustificano e quali conseguenze attiva. La corrispondenza letterale dell’etichetta non basta se è cambiato il criterio di assegnazione. Usa casi limite con annotazione umana e asserzioni sulle condizioni osservabili che devono condurre a ciascuna classe.

Nelle risposte con evidenze, il contratto deve distinguere tra avere una citazione ed essere effettivamente supportati. Come minimo, verifica che la fonte recuperata sia ammissibile per il dominio, che la sua data soddisfi la policy di attualità, che il passaggio contenga evidenza sufficiente per l’affermazione e che il flusso dichiari insufficienza quando manca una base. L’attribuzione non deve trasformarsi in una decorazione generata alla fine del processo.

Classificare la modifica prima di discuterne i risultati

Classifica ogni modifica proposta in quattro gruppi. Una modifica compatibile conserva tutti i contratti applicabili. Una compatibile con degrado accettabile non raggiunge un obiettivo non critico ma rimane entro una soglia approvata, come una variazione limitata della latenza. Una modifica incompatibile viola una proprietà obbligatoria, come un permesso d’azione o un campo richiesto. Una modifica sconosciuta è quella per cui mancano casi, fixture, telemetria o una definizione sufficiente per concludere.

La classificazione non deve dipendere da chi propone la modifica né dal fatto che una dimostrazione sembri convincente. Deve essere collegata a regole di promozione pubblicate in precedenza. Se il team scopre che una regola non riflette più una necessità del prodotto, può cambiare il contratto, ma la decisione deve essere esplicita, revisionata e versionata; non deve essere accettata implicitamente tramite un test fallito.

Fissare una versione concreta del modello riduce una fonte di variazione e facilita la riproduzione dei risultati. Gli alias o i modelli soggetti ad aggiornamenti possono modificare il comportamento senza che cambi il codice client. La documentazione di OpenAI raccomanda di fissare le versioni dei modelli ed eseguire valutazioni, perché gli snapshot possono variare nel comportamento di prompting. Di conseguenza, un contratto deve registrare sia l’identificatore richiesto sia la policy di aggiornamento accettata dal team.

Progettare una batteria minima ma diagnostica

Una batteria utile non deve cercare di rappresentare ogni possibile conversazione umana. Deve contenere casi fissi che coprano percorsi critici, casi limite e controesempi storici. Ogni caso deve dichiarare input, stato iniziale, configurazione del flusso, risultato atteso, gravità e asserzioni. Mantieni i dati di test privi di informazioni sensibili e assicurati che possano essere eseguiti ripetutamente.

Usa fixture per gli strumenti e le dipendenze esterne. Una fixture deve restituire stati controllati, registrare le chiamate ed evitare effetti reali. In questo modo puoi verificare che il modello abbia scelto lo strumento corretto, che gli argomenti siano stati interpretati dall’adattatore e che non sia stato tentato di eseguire un’alternativa vietata. Un ambiente di test che chiama la produzione non è una fixture: mescola compatibilità e rischio operativo.

Gli snapshot sono adatti ad artefatti deliberatamente stabili, come una richiesta normalizzata, uno schema di strumento o un elenco ordinato di identificatori recuperati. Sono fragili per intere porzioni di prosa prodotte da un modello. Per il linguaggio naturale, preferisci asserzioni semantiche circoscritte: presenza di fatti obbligatori, assenza di affermazioni vietate, corrispondenza con l’evidenza e comportamento di astensione in presenza di dati insufficienti.

Alcune misure non sono deterministiche. Il tasso di successo, la distribuzione della latenza e la frequenza di una classificazione possono richiedere più esecuzioni, un campione fissato e un intervallo o una tolleranza predefiniti. Non trasformare una piccola differenza statistica in una regressione critica, né permettere che l’incertezza statistica nasconda una violazione deterministica della sicurezza.

Output strutturati e chiamate a strumenti: lo schema non è autorizzazione

Un output strutturato deve essere validato due volte: prima rispetto alla sua rappresentazione e poi rispetto al suo significato. La prima validazione controlla JSON, tipi, campi richiesti, intervalli e valori consentiti. La seconda controlla le relazioni tra campi e stato esterno. Per esempio, che una data di inizio sia precedente a quella di fine, che l’importo appartenga all’ordine indicato e che un codice motivo sia coerente con il caso.

Le interfacce per strumenti dei fornitori possono descrivere parametri tramite JSON Schema e offrire modalità rigorose di aderenza allo schema. È un aiuto rilevante per ridurre gli argomenti malformati, ma non sostituisce la validazione dell’applicazione. Un argomento può essere ben tipizzato e indicare un account sbagliato, un’operazione fuori policy o un’azione che richiede approvazione. L’esecutore deve applicare autorizzazione, precondizioni e limiti prima di produrre effetti.

Il contratto deve fissare anche l’ordine. In un flusso che verifica l’idoneità e poi emette un rimborso, non accettare una sequenza invertita solo perché entrambe le chiamate sono individualmente valide. Registra gli strumenti consentiti per fase, il numero massimo di invocazioni, gli argomenti normalizzati, la risposta della fixture e l’assenza di chiamate non autorizzate. Questo consente di rilevare modifiche in cui il modello sembra risolvere il compito, ma sceglie una scorciatoia operativa pericolosa.

Se il fornitore modifica il modello, la definizione dello strumento o l’adattatore dell’SDK, esegui le stesse fixture. Un test di JSON valido rileverebbe un oggetto malformato; questa batteria può rilevare che è stato scelto uno strumento diverso, che è stata omessa la consultazione preventiva o che il sistema ha tentato di ripetere un’azione già confermata.

Contratti per recupero e risposte con fonti

In un flusso RAG, il contratto comincia prima della redazione. Stabilisci quali collezioni il caso può interrogare, quali metadati minimi deve restituire ciascun frammento e come viene gestita l’attualità. Se una risposta dipende da una policy corrente, un documento vecchio può essere recuperabile dal punto di vista tecnico ma inammissibile come fondamento. Il test deve ispezionare la provenienza, non soltanto il testo finale.

Definisci un’evidenza minima per ciascun tipo di affermazione. Una conclusione normativa può richiedere un passaggio esplicito da una fonte autorizzata; una sintesi può richiedere più frammenti coerenti; una cifra può richiedere una corrispondenza esatta con il documento. Se i risultati non soddisfano tale condizione, il comportamento corretto può essere chiedere altro contesto, dichiarare incertezza o non rispondere all’affermazione. Tale astensione è un output contrattuale, non un errore di esperienza predefinito.

Testa contraddizioni e contesto insufficiente. Includi fixture con documenti obsoleti, fonti di minore autorevolezza, frammenti che menzionano termini simili e insiemi che contengono informazioni conflittuali. Il contratto deve indicare se il flusso dà priorità a una fonte, espone il conflitto o passa a una revisione. Non è ragionevole affermare che una citazione sia corretta solo perché condivide parole con la risposta.

Conserva per ogni esecuzione l’insieme dei documenti candidati, quelli selezionati, i loro identificatori e metadati rilevanti, la versione dell’indice, la query trasformata e il risultato finale. Questa telemetria consente di distinguere se la violazione è nata nel recupero, nell’interpretazione del modello o nella rappresentazione dell’evidenza.

Integrazione in CI/CD, decisione e ripristino

Esegui la batteria quando cambia uno qualsiasi degli artefatti registrati: versione del modello, SDK, prompt di sistema, parametri, schema, definizione degli strumenti, recuperatore, indice o policy. La modifica deve produrre un manifesto confrontabile che includa versioni, hash o identificatori interni, risultati per caso, durata, consumo misurato quando disponibile e tracce di strumenti e recupero. Evita che un aggiornamento implicito rimanga fuori dal controllo delle modifiche.

Organizza i gate di CI in base alla gravità. Le asserzioni critiche, come autorizzazioni, effetti non consentiti, isolamento dei clienti o evidenza obbligatoria, devono bloccare. Quelle di gravità elevata normalmente bloccano fino a quando non esiste un adattamento approvato. Le metriche di qualità o prestazione con tolleranza possono richiedere revisione. Un risultato sconosciuto non deve diventare automaticamente compatibile per mancanza di segnale.

Quando un contratto fallisce, individua anzitutto il confine. Confronta la richiesta normalizzata, l’artefatto del modello, la risposta grezza, l’adattamento dell’SDK, i documenti recuperati e il registro degli strumenti. Poi scegli se correggere l’integrazione, adattare il contratto perché è cambiata un’esigenza legittima, versionare il flusso per mantenere entrambi i comportamenti oppure rifiutare la modifica. Documenta perché la decisione è valida e chi l’ha approvata.

Il ripristino deve essere progettato prima della promozione. Conserva la configurazione precedente che consenta di ripristinare modello, prompt, schema, strumenti e adattatori compatibili. Se il fornitore ritira una versione, potrebbe non esistere un ripristino esatto; in tal caso l’alternativa è un flusso versionato con adattamento testato. Le policy di ritiro pubblicate dai fornitori sono un’ulteriore ragione per pianificare le migrazioni prima della data limite, non dopo aver rilevato un incidente.

Modello di manifesto del contratto per flusso

Un manifesto breve trasforma l’intenzione in un artefatto revisionabile. Deve vivere accanto al flusso e cambiare tramite lo stesso processo di revisione del codice. Non deve contenere segreti né tutte le conversazioni di test; deve puntare a identificatori interni delle fixture e definire con precisione quali proprietà governa.

Includi: nome e scopo del flusso; responsabile tecnico e di prodotto; versione del contratto; identificatori di modello, SDK e configurazioni; prompt o riferimento alla sua versione; schema di output; strumenti consentiti e permessi; dipendenze di recupero; elenco dei casi; soglie di prestazione e costo; gravità di ogni regola; policy di promozione; telemetria obbligatoria; strategia di ripristino; e data di revisione. Se una regola non ha un responsabile o un criterio di fallimento, non è ancora un contratto operativo.

Il modello non elimina il giudizio tecnico. Le fonti disponibili documentano meccanismi di versionamento, ritiro, schemi e uso rigoroso degli strumenti, ma non possono decidere quale evidenza sia sufficiente per il tuo dominio né quale azione richieda approvazione umana. Queste decisioni spettano al team responsabile e devono essere formulate come policy verificabili. Il vantaggio del manifesto è costringere a renderle visibili prima che un aggiornamento le contraddica.

Continua a esplorare

Correzioni e trasparenza

Se trovi un dato errato o non aggiornato, inviaci la pagina e la fonte da verificare.