Minimi per il prompt cache: la documentazione sottostima di 1,4–2,4x

Un cliente ci ha segnalato che il prompt caching sul nostro gateway non si attivava al numero di token promesso dalla documentazione del modello. Abbiamo riprodotto il problema e poi rieseguito ogni modello su un secondo serving path indipendente, uno dei più grandi AI gateway, dove gli stessi scarti si sono ripresentati al token. A essere ottimista è la documentazione, non un particolare gateway: il minimo pubblicato è una soglia di idoneità, non la lunghezza che garantisce un cache hit. Per le famiglie con cache automatico i due valori differiscono di un fattore da 1,4 a 2,4x. La soglia effettiva del primo hit di OpenAI si è misurata intorno ai 1.456 token contro i 1.024 dichiarati; Gemini 2.5 Flash ha letto per la prima volta dalla cache intorno ai 5.000 token contro i 2.048 dichiarati; Claude, che mette in cache solo dove piazzi un marker esplicito, ha centrato il minimo per modello documentato con uno scarto di pochi punti percentuali.

TL;DR

• Il minimo documentato di 1.024 token per la cache di OpenAI sottostima la soglia effettiva di circa 1.456 token, misurata su due path.
• Gemini 2.5 Flash documenta 2.048 ma ha letto per la prima volta intorno ai 5.000 token, circa 2,4x in più.
• Il cache_control esplicito di Claude ha centrato il minimo documentato con uno scarto di pochi punti percentuali (Opus 1.073 contro 1.024).
• GLM 5.2 e DeepSeek V4 non pubblicano alcun minimo e leggono dalla cache già da circa 800 token; MiniMax M3 riporta circa 114 token in cache a qualsiasi lunghezza.
• Le cache automatiche richiedono anche un warm-up di 2-8 chiamate prima della prima lettura.

Abbiamo eseguito ogni misurazione su due serving path, il nostro gateway e uno dei più grandi AI gateway indipendenti, e abbiamo considerato un risultato come comportamento del modello solo dove i due path concordavano. Il senso del secondo path è l’attribuzione: uno scarto che si riproduce sullo stack di un vendor non correlato è del modello, non nostro. Questo cross-check ha funzionato bene per OpenAI, Gemini e GLM, che hanno usato la cache su entrambi i path, alle stesse soglie effettive. Non funziona per ogni modello: su quel secondo gateway i modelli open-weight sono in gran parte serviti da GPU host che non implementano il prompt cache del vendor, cosa che i metadata degli endpoint del gateway confermano per singolo provider, e il routing non pinnato si sposta tra questi host, facendo perdere l’affinità con la cache. Dove il secondo path non ha potuto confermare, i numeri qui sotto vengono dal path che raggiunge l’API di caching del vendor stesso. Le lunghezze sono i token di ciascun modello, calibrati dall’usage restituito, non i caratteri. Ogni test ha usato un prefisso nuovo e ha registrato l’indice della prima chiamata che ha prodotto una lettura dalla cache, non un singolo esito hit-or-miss.

Lo scarto tra dichiarato ed effettivo

Il minimo dichiarato indica quando un prompt può essere messo in cache. La soglia effettiva è la lunghezza a cui un prompt ripetuto torna davvero come read. Per le famiglie a cache automatica non si tratta dello stesso numero.

Il valore di OpenAI ha retto al singolo token su entrambi i percorsi: un prompt da 1.356 token non è mai tornato come read, uno da 1.456 sì. Gemini ha mostrato lo scarto più ampio. Uno sweep che si fermava a 3.300 token non ha prodotto nessun read e sembrava che il caching fosse disattivato; estendendo lo sweep a 5.000 è comparso un read pulito su entrambi i percorsi alla stessa lunghezza. Il valore dichiarato di 2.048 è la soglia a cui la cache diventa eleggibile, non quella a cui serve i read.

Il pattern emerso dallo studio: la cache che marchi in modo esplicito ha una specifica accurata, quella che avviene in automatico no.

Il minimo non è l’unica variabile non documentata

Superare la soglia effettiva è necessario ma non sufficiente. Le famiglie a cache automatica richiedono un warm-up: il primo read arriva su una chiamata successiva, non alla seconda.

• OpenAI: primo read tra la chiamata 2 e la 3.
• Gemini: primo read tra la chiamata 4 e la 8.

Questo pesa sul cost modelling. Un prompt da 6.000 token è sopra ogni soglia Gemini, dichiarata ed effettiva, ma un workload che lo invia due volte e poi passa ad altro può comunque pagare il prezzo pieno entrambe le volte, perché la cache non si era scaldata. Il traffico breve o a raffiche paga la tariffa non-cached anche quando la lunghezza è idonea. Abbiamo concluso “non fa caching” solo dopo almeno dodici chiamate ripetute con un settle tra l’una e l’altra; uno sweep più corto aveva prodotto un falso negativo su Gemini, ribaltato da uno più profondo.

Anche i conteggi cached si allineano a blocchi fissi, cosa da sapere quando riconcili una fattura: blocchi da 128 token su OpenAI, da 64 token su DeepSeek. Un read di 4.073 token cached su un prompt da 5.014 token è un hit parziale sul prefisso arrotondato al confine del blocco, non un bug.

Le cache che controlli sono esatte

Claude mette in cache solo i segmenti che marchi con cache_control, e questo controllo arriva con una specifica accurata. Ogni dichiarazione di Anthropic che abbiamo testato ha retto:

• Minimo per modello, al token. Opus 4.8 e Sonnet 5 fanno il primo read a 1.073 token contro i 1.024 dichiarati; Haiku 4.5 a 4.206 contro 4.096. La piccola eccedenza è arrotondamento al blocco, non deriva.
• Read rate di 0,1x l’input. Abbiamo ricavato il prezzo di input di ciascun modello dalle sue righe cold, poi calcolato la tariffa cached da una riga di hit. Opus 4.8 e Haiku 4.5 sono usciti entrambi a 0,10, in linea con il moltiplicatore dichiarato.
• Refresh di cinque minuti, gratis a ogni read. Seminando un prefisso e rileggendolo a due, quattro e sei minuti, ogni read ha fatto hit. Un read entro ciascuna finestra di cinque minuti tiene viva la entry senza una scrittura aggiuntiva.
• Invalidazione a cascata. Con un prefisso di sistema stabile e un tool definito, cambiando solo la descrizione del tool si è forzata una riscrittura completa della cache di sistema sottostante. Cambiare la definizione di un tool invalida la cache di sistema e quella dei message, in linea con la gerarchia dichiarata.

Da qui è emerso un conflitto doc-contro-doc. Una tabella di terze parti indicava il minimo di Claude Opus a 4.096 token; la misurazione ha fatto read a 1.073, e i 1.024 di Anthropic sono il valore corretto.

Le famiglie open-weight di solito non documentano nulla

Le famiglie viste sopra pubblicano almeno un numero su cui poter sbagliare. I modelli open-weight e quelli dei lab cinesi per lo più non pubblicano alcun minimo, quindi l’unica strada è misurare. La nostra comparazione della cache tra provider spiega come si allineano i tassi dichiarati una volta che scatta un hit; qui la domanda è solo a quale lunghezza compare la prima lettura.

GLM 5.2 non pubblica alcuna lunghezza minima e ha messo in cache a partire da circa 800 token, con granularità a blocchi da 64 token su entrambi i path: una soglia più bassa di qualsiasi famiglia documentata. Anche DeepSeek V4 non pubblica un minimo e legge da circa 800 token con la stessa granularità da 64 token, ma solo contro la propria API di caching. La documentazione di DeepSeek descrive la cache come best-effort, senza garanzie sull’hit-rate, ed è esattamente ciò che un intermediario espone: l’altro gateway serve DeepSeek attraverso un insieme di host GPU dove solo l’endpoint proprio di DeepSeek implementa la cache, quindi un routing non fissato su quell’endpoint non restituisce alcuna lettura.

MiniMax M3 è il caso in cui il numero riportato è di per sé fuorviante. Documenta un minimo di 512 token, ma riporta un valore costante intorno ai 114 token in cache fin dalla prima chiamata, a ogni lunghezza da 200 a 5.000 token. Quel numero non segue la lunghezza del prompt e compare anche sui path che non fanno alcun caching: è quindi la contabilità interna del modello, non un segnale di ciò che è stato riutilizzato. È la stessa lezione che i modelli OpenAI più recenti insegnano dall’altra direzione: i campi dei token di utilizzo e la cache reale possono divergere, quindi quando il risparmio conta, riconcilia rispetto a usage.cost, non al conteggio dei token.

I modelli più recenti stanno cambiando le regole

Ci sono due modifiche a livello di documentazione da segnalare prima di dare per scontato che il comportamento dei modelli più vecchi valga ancora. Sulla famiglia GPT-5.6, la guida di OpenAI dice che le scritture in cache costano 1,25x rispetto al costo dell’input non in cache, mentre le famiglie precedenti scrivevano gratis. La stessa guida descrive il caching implicito come il piazzamento di un breakpoint sull’ultimo messaggio, che è una forma diversa dal fare prefix caching di un blocco di system stabile attraverso i turni. Se su quei modelli vuoi riutilizzare un prefisso stabile su turni utente diversi, marcalo con un breakpoint esplicito invece di affidarti al path implicito. Verifica il moltiplicatore di scrittura e il minimo modello per modello, perché ora entrambi variano per famiglia in modi che una singola pagina di documentazione appiattisce.

Cosa farci

• Misura la tua soglia effettiva. Fai variare la lunghezza del prompt nei tuoi token e annota la prima lunghezza che restituisce una lettura dalla cache. Non dare per scontato che i cache hit inizino al minimo documentato.
• Metti in conto il warm-up. Nel tuo modello di costo, tratta come non cacheate le prime due-otto chiamate su un nuovo prefisso, se usi provider con cache automatica.
• Preferisci i marker espliciti dove il provider li offre. Il cache_control di Claude offriva una specifica precisa e verificabile: minimo noto, read rate noto, TTL noto e regola di invalidazione nota. Questa prevedibilità vale più di un minimo documentato più basso su cui non puoi fare affidamento.
• Ricalibra la baseline sulle nuove famiglie di modelli. Minimi, prezzo di scrittura e comportamento dei breakpoint sono cambiati all’interno della gamma di un singolo vendor nel corso di questo studio.

Per read rate, TTL e regole di keying che stanno dietro a queste soglie, la nostra guida al prompt caching copre i meccanismi provider per provider.

In breve: il minimo documentato è una soglia di idoneità, non una soglia di hit, e per le cache automatiche le due differiscono di un fattore da 1,4 a 2,4x. Verifica il numero che incide sulla tua bolletta, nei tuoi token, sul tuo traffico reale.

← Torna al blog