Il campo model: oggi non è validato

Per chi: tutti i prodotti che hanno una chiave AgileV, e in particolare chi il nome del modello lo prende da una variabile d'ambiente o da un file di configurazione. Da dove nasce: la prova dal posto di trpg del 28/9. Prima ci avevano scritto «il riordino vuole agilev-rerank, non agilev-m3» — dedotto da /v1/models, non misurato, e falso. Poi l'hanno misurato e hanno trovato di più: passa anche un nome inventato. E ci hanno chiesto una cosa sola: l'avviso prima del 400 MODEL_UNKNOWN. Questa pagina è quell'avviso, con la misura sotto.

1. Oggi nessun nome viene rifiutato

Misurato il 28/9 su 4 rotte x 9 nomi, sul codice 1.1 in produzione e sulla 1.2 già pronta, con esito identico sulle due: zero 400. Il deploy della 1.2 non cambia una riga di questa tabella.

Una richiesta con un nome sconosciuto viene servita e contata in fattura come tutte le altre: la validazione è di forma, non di sostanza.

2. I due punti ciechi, che riguardano voi più di noi

Il nome vuoto non lascia traccia. "", null e il campo assente valgono come «default» e non vengono contati da nessuna parte. Se la vostra variabile d'ambiente è vuota, oggi non se ne accorge nessuno: né voi (ricevete 200) né noi (il contatore resta fermo).

/embed non guarda il campo affatto. Il formato storico ha solo texts: un model nel corpo viene scartato senza nemmeno essere contato. Chi è rimasto su /embed è invisibile a questa validazione, oggi e domani.

Il controllo che regge, ed è gratis: ogni risposta dichiara il modello usato, non quello chiesto — /v1/rerank risponde sempre "model":"agilev-rerank", /v1/embeddings "model":"agilev-m3", /embed "model":"bge-m3". Confrontate quello, non quello che avete spedito: è l'unico controllo che continua a funzionare anche dopo che la validazione esisterà. È la correzione che trpg ha già messo nel proprio banco.

Un nome si confronta solo con quello della STESSA rotta. I tre valori qui sopra non sono intercambiabili: /v1/embeddings e /embed danno gli stessi vettori (misurato: identici bit per bit) con due nomi diversi, perché il primo usa il nome di listino e il secondo quello del modello sottostante. Lo stesso vale per GET /health, che dichiara "model":"bge-m3": non è confrontabile con agilev-m3 di /v1/models, e chi li confronta ha un falso allarme a ogni avvio (segnalato da trpg il 28/9 sera). Se cercate un controllo di salute all'avvio, quello è sulla dimensione: Regola 4, contromisura (a).

3. Quando diventerà 400 MODEL_UNKNOWN, e come lo saprete prima

Non presto. Letto dai contatori di produzione il 29/9 alle 03:2x: 4 delle 7 richieste di rerank riuscite dal riavvio del 27/9 06:37:49Z portavano un nome non riconosciuto (il 28/9 erano 3 su 6). Prima di cambiare succederanno, in quest'ordine, tutte e quattro queste cose:

1. il contatore dei nomi sconosciuti resta a zero in modo stabile (è la condizione scritta nel nostro codice dal primo giorno). Fino al 29/9 questa frase non era nemmeno misurabile: il contatore vive in memoria e ripartiva da zero a ogni riavvio del servizio, quindi «stabilmente a zero» si otteneva riavviando. Ora il conto per chiave sta sul disco e i riavvii non lo cancellano;
2. il contatore diventa attribuibile: sapere che qualcuno sbaglia senza sapere chi avvisare non basta, e finché non sappiamo a chi scrivere non si cambia nulla. Fatto il 29/9/2026: il servizio registra, per chiave e per rotta, quante richieste hanno portato un nome che non riconosce — solo numeri, mai il nome ricevuto, che è testo vostro. Lo vedete voi in GET /v1/usage, campo model_unknown, che non costa né quota né richieste al minuto: vuota è la risposta normale;
3. voce in NOVITA e messaggio diretto a ogni titolare di chiave, con almeno 30 giorni fra l'avviso e il cambio;
4. il cambio va in un deploy da solo, mai insieme ad altro: se rompe qualcosa si sa cosa tornare indietro.

Nel frattempo i modi di controllarvi da soli sono due, entrambi gratis. Il primo è model_unknown in GET /v1/usage: se non è vuoto, la vostra configurazione manda un nome che non conosciamo, e sapete su quale rotta. Il secondo è il model della risposta, che è l'unico dei due a cogliere anche la variabile d'ambiente vuota (una stringa vuota vale come default e non viene contata da nessuna parte). Se non è quello che vi aspettate, la vostra configurazione è già sbagliata oggi.

4. Cosa NON cambia col deploy della 1.2

Tutto quanto sopra. Le misure sono state fatte su entrambe le versioni proprio per poterlo dire: se dopo il passaggio alla 1.2 vedete un 400 su un nome di modello, è un guasto nostro e vogliamo saperlo subito. La tabella completa e il resto del contratto sono in api.html (la copia pubblica è allineata dalla regia: fino ad allora questa pagina è la più aggiornata).

this page in English