Soglie minime della prompt cache: la documentazione le sottostima di 1.4-2.4x

Un cliente ci ha segnalato che, sul nostro gateway, la prompt cache non si attivava al numero di token indicato nella documentazione del modello. Abbiamo riprodotto il problema e ripetuto i test su un secondo serving path indipendente, uno dei maggiori gateway AI. Gli scostamenti si sono ripresentati agli stessi identici valori di token. Il dato ottimistico era quindi quello della documentazione, non quello di uno specifico gateway: il minimo pubblicato è la soglia a partire dalla quale una richiesta può entrare in cache, non la lunghezza necessaria per ottenere un cache hit. Nelle famiglie con cache automatica, i due valori differiscono di 1.4-2.4x. Per OpenAI abbiamo misurato una soglia effettiva del primo hit vicina a 1,456 token, contro i 1,024 documentati. Gemini 2.5 Flash ha restituito la prima lettura dalla cache intorno a 5,000 token, contro i 2,048 dichiarati. Claude, che usa la cache solo nei punti contrassegnati esplicitamente, ha rispettato il minimo documentato per ciascun modello con uno scarto di pochi punti percentuali.

TL;DR

• Il minimo documentato da OpenAI, pari a 1,024 token, sottostima la soglia effettiva di circa 1,456 token, misurata su due path.
• Gemini 2.5 Flash dichiara 2,048 token, ma la prima lettura è arrivata vicino a 5,000 token, circa 2.4x in più.
• Il cache_control esplicito di Claude ha rispettato 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 iniziano a leggere dalla cache intorno a 800 token; MiniMax M3 segnala circa 114 token in cache a qualsiasi lunghezza.
• Le cache automatiche richiedono inoltre un warm-up da 2 a 8 chiamate prima della prima lettura.

Abbiamo eseguito ogni misurazione attraverso due serving path: il nostro gateway e uno dei maggiori gateway AI indipendenti. Abbiamo attribuito un risultato al comportamento del modello solo quando i due path concordavano. Il secondo path serve proprio a distinguere le responsabilità: se una discrepanza si ripete sullo stack di un vendor non correlato, dipende dal modello, non dal nostro gateway. La verifica incrociata ha funzionato senza ambiguità per OpenAI, Gemini e GLM, che hanno usato la cache su entrambi i path alle stesse soglie effettive. Non è possibile fare altrettanto con tutti i modelli. Sul secondo gateway, i modelli open-weight sono serviti in gran parte da host GPU che non implementano la prompt cache del vendor, come confermano i metadati degli endpoint del gateway per ciascun provider. Inoltre, il routing senza pinning passa da un host all’altro e fa perdere la cache affinity. Quando il secondo path non poteva fornire una conferma, i numeri riportati sotto provengono dal path che raggiunge direttamente l’API di caching del rispettivo vendor. Le lunghezze sono espresse nei token propri di ciascun modello, calibrati dai dati usage restituiti, non in caratteri. Per ogni variante abbiamo usato un prefisso nuovo e registrato l’indice della prima chiamata che produceva una lettura dalla cache, anziché limitarci a un singolo hit-or-miss.

Lo scarto tra soglia documentata e soglia effettiva

Il minimo documentato indica quando un prompt può essere inserito in cache. La soglia effettiva è invece la lunghezza alla quale un prompt ripetuto viene realmente servito dalla cache. Per le famiglie con cache automatica, i due valori non coincidono.

Il valore di OpenAI è risultato identico, token per token, su entrambi i path: un prompt da 1,356 token non ha mai prodotto una lettura, mentre uno da 1,456 token sì. Gemini ha mostrato lo scarto più ampio. Un primo sweep, fermato a 3,300 token, non aveva prodotto alcuna lettura e faceva pensare che la cache fosse disabilitata. Estendendolo fino a 5,000 token, entrambi i path hanno restituito una lettura netta alla stessa lunghezza. I 2,048 token documentati sono la soglia di idoneità alla cache, non quella a partire dalla quale vengono servite le letture.

Il risultato generale dello studio è chiaro: le cache contrassegnate esplicitamente hanno specifiche accurate; quelle automatiche no.

Il minimo non è l’unica variabile non documentata

Superare la soglia effettiva è necessario, ma non sufficiente. Le famiglie con cache automatica richiedono un warm-up: la prima lettura avviene in una chiamata successiva, non nella seconda.

• OpenAI: prima lettura alla chiamata 2 o 3.
• Gemini: prima lettura tra la chiamata 4 e la 8.

Questo incide sui modelli di costo. Un prompt da 6,000 token supera tutte le soglie Gemini, sia documentate sia effettive. Tuttavia, 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 ha ancora completato il warm-up. Il traffico breve o a raffiche viene quindi fatturato alla tariffa senza cache anche se la lunghezza soddisfa i requisiti. Abbiamo concluso che un modello “non usa la cache” solo dopo almeno dodici chiamate ripetute, lasciando un intervallo di assestamento tra una e l’altra. Uno sweep più breve aveva prodotto un falso negativo su Gemini, smentito da un test più approfondito.

Anche il conteggio dei token in cache viene arrotondato a blocchi fissi, un dettaglio utile quando si riconciliano i costi: blocchi da 128 token su OpenAI e da 64 token su DeepSeek. Se un prompt da 5,014 token riporta una lettura di 4,073 token dalla cache, si tratta di un hit parziale sul prefisso arrotondato al limite di un blocco, non di un bug.

Le cache controllate esplicitamente sono precise

Claude memorizza in cache soltanto i segmenti contrassegnati con cache_control, e le relative specifiche sono accurate. Tutte le dichiarazioni di Anthropic che abbiamo verificato sono risultate corrette:

• Minimo per modello, verificato token per token. Opus 4.8 e Sonnet 5 hanno prodotto la prima lettura a 1,073 token, contro i 1,024 documentati; Haiku 4.5 a 4,206, contro 4,096. Il piccolo scarto dipende dall’arrotondamento dei blocchi, non da una deriva della soglia.
• Tariffa di lettura pari a 0.1x dell’input. Abbiamo ricavato il prezzo di input di ogni modello dalle relative righe cold, quindi calcolato la tariffa della cache da una riga con hit. Opus 4.8 e Haiku 4.5 hanno entrambi restituito 0.10, in linea con il moltiplicatore documentato.
• Refresh di cinque minuti, gratuito a ogni lettura. Dopo aver inizializzato un prefisso, lo abbiamo riletto dopo due, quattro e sei minuti, ottenendo sempre un hit. Una lettura entro ciascuna finestra di cinque minuti mantiene attiva l’entry senza costi di scrittura aggiuntivi.
• Invalidazione a cascata. Con un prefisso di sistema stabile e un solo tool definito, la modifica della sola descrizione del tool ha imposto la riscrittura completa della cache di sistema sottostante. La modifica della definizione di un tool invalida le cache di sistema e dei messaggi, come previsto dalla gerarchia documentata.

Il test ha anche evidenziato un conflitto tra fonti. Una tabella di terze parti indicava per Claude Opus un minimo di 4,096 token; la lettura è avvenuta a 1,073, confermando che il valore corretto è quello di Anthropic, pari a 1,024.

Le famiglie open-weight di solito non documentano nulla

Le famiglie citate sopra pubblicano almeno un valore, anche se errato. I modelli open-weight e quelli dei laboratori cinesi, invece, in gran parte non indicano alcun minimo. L’unico modo per scoprirlo è misurarlo. Il nostro confronto tra le cache dei provider analizza la corrispondenza tra le tariffe pubblicate e quelle effettive una volta ottenuto un hit; qui ci interessa soltanto la lunghezza alla quale compare la prima lettura.

GLM 5.2 non pubblica una lunghezza minima e ha iniziato a usare la cache intorno a 800 token, con blocchi da 64 token su entrambi i path. La sua soglia è più bassa di quella di tutte le famiglie che dichiarano un minimo. Anche DeepSeek V4 non pubblica alcun minimo e ha prodotto letture da circa 800 token, con la stessa granularità di 64 token, ma solo attraverso la propria API di caching. La documentazione di DeepSeek definisce la cache best-effort e non garantisce alcun hit rate. È esattamente ciò che espone un intermediario: l’altro gateway serve DeepSeek tramite un insieme di host GPU, tra i quali solo l’endpoint di DeepSeek implementa la cache. Se il routing non è vincolato a quell’endpoint, non viene restituita alcuna lettura.

MiniMax M3 è un caso in cui il valore riportato risulta fuorviante. La documentazione indica un minimo di 512 token, ma il modello segnala un conteggio costante vicino a 114 token in cache fin dalla prima chiamata, per tutte le lunghezze comprese tra 200 e 5,000 token. Il valore non segue la lunghezza del prompt e compare anche sui path che non eseguono alcun caching. È quindi un conteggio interno del modello, non un’indicazione di quanto sia stato effettivamente riutilizzato. I modelli OpenAI più recenti mostrano lo stesso problema nella direzione opposta: i campi relativi ai token in usage e il caching reale possono non coincidere. Quando il risparmio è rilevante, la riconciliazione va fatta rispetto a usage.cost, non al conteggio dei token.

I modelli più recenti stanno cambiando le regole

Prima di dare per scontato che il comportamento precedente resti valido, vanno considerate due modifiche nella documentazione. Per la famiglia GPT-5.6, la guida di OpenAI indica che le scritture in cache costano 1.25x rispetto alla tariffa di input senza cache, mentre nelle famiglie precedenti erano gratuite. La stessa guida descrive il caching implicito come l’inserimento di un breakpoint sull’ultimo messaggio. È un comportamento diverso dal caching del prefisso, che riutilizza tra i turni un blocco di sistema stabile. Per riutilizzare un prefisso stabile con turni utente diversi su questi modelli, conviene contrassegnarlo con un breakpoint esplicito anziché affidarsi al path implicito. Il moltiplicatore di scrittura e il minimo vanno verificati per ogni modello: entrambi cambiano tra famiglie, anche se una singola pagina di documentazione tende ad appiattire queste differenze.

Indicazioni operative

• Misurate la vostra soglia effettiva. Eseguite uno sweep della lunghezza del prompt nei token del modello e registrate la prima lunghezza che restituisce una lettura dalla cache. Non date per scontato che gli hit inizino al minimo documentato.
• Includete il warm-up nel budget. Nel modello di costo dei provider con cache automatica, considerate senza cache le prime due-otto chiamate su un prefisso nuovo.
• Preferite i marker espliciti quando il provider li supporta. Il cache_control di Claude offre specifiche accurate e verificabili: minimo, tariffa di lettura, TTL e regole di invalidazione noti. Questa prevedibilità vale più di una soglia documentata più bassa sulla quale non si può fare affidamento.
• Ricalibrate ogni nuova famiglia di modelli. Nel corso di questo studio, soglie minime, prezzi di scrittura e comportamento dei breakpoint sono cambiati persino all’interno dell’offerta dello stesso vendor.

La nostra guida alla prompt cache descrive, per ciascun provider, le tariffe di lettura, i TTL e le regole di keying associate a queste soglie.

In sintesi: il minimo documentato è una soglia di idoneità, non una soglia di hit. Per le cache automatiche, i due valori differiscono di 1.4-2.4x. Verificate sui vostri flussi di traffico, usando i token del modello, il valore che determina realmente la fattura.

← Torna al blog