Caching dei prompt: Riutilizzare i calcoli
In questa pagina
Cos’è il caching dei prompt?
Quando invii ripetutamente lo stesso prefisso di prompt—un lungo prompt di sistema, istruzioni dettagliate o un documento di riferimento—OpenAI può memorizzare automaticamente nella cache quel prefisso. Le chiamate successive che condividono questo prefisso beneficiano di un tempo ridotto fino al primo token (TTFT) e di costi inferiori sui token di input. In altre parole, il lavoro di ingestione del contesto stabile non viene ripetuto per ogni richiesta.
Il caching dei prompt è automatico dal 2025: non devi abilitare nulla. OpenAI rileva i prefissi identici e li memorizza nella cache. Il tuo margine di manovra, quindi, non sta nell’attivarlo o disattivarlo, ma nello scrivere i tuoi prompt in modo che il meccanismo possa applicarsi. Si tratta di struttura, non di configurazione, ed è qui che la maggior parte dei team lascia soldi sul tavolo.
Come funziona
La cache si applica ai prefissi dei prompt: i primi token devono essere strettamente identici da una chiamata all’altra e la corrispondenza si interrompe al primo carattere divergente. È richiesta una dimensione minima di 1.024 token per attivare il caching, il che esclude immediatamente i prompt di sistema brevi. La cache è condivisa all’interno di una singola organizzazione, il che significa che più servizi nella tua azienda che chiamano lo stesso prefisso si aiutano a vicenda. La sua durata varia da pochi minuti a poche ore, senza alcuna garanzia ferma, e la riduzione ottenuta è di circa il 50% sul costo dei token di input memorizzati nella cache.
La conseguenza pratica della regola del prefisso è che devi posizionare gli elementi stabili all’inizio del prompt e gli elementi variabili alla fine. Un servizio che inserisce la data odierna o un ID sessione all’inizio del suo prompt di sistema invalida la sua cache a ogni chiamata senza nemmeno rendersene conto.
import openai
client = openai.OpenAI()
# ✅ Buona struttura: elementi stabili per primi
SYSTEM_PROMPT = """Sei un assistente legale specializzato in diritto
contrattuale francese. Analizzi le clausole contrattuali secondo il
Codice Civile e la giurisprudenza recente. Rispondi sempre
strutturando la tua analisi: 1) Identificazione della clausola,
2) Analisi legale, 3) Rischi potenziali, 4) Raccomandazioni.
Ecco il contratto di riferimento da analizzare:
[Inserisci qui un documento di oltre 2.000 token che non cambia tra le chiamate]
"""
def analyze_clause(clause: str) -> str:
"""Ogni chiamata riutilizza la cache del prompt di sistema."""
response = client.responses.create(
model="gpt-5.6-terra",
instructions=SYSTEM_PROMPT, # Prefisso stabile = memorizzato nella cache
input=f"Analizza questa clausola: {clause}", # Parte variabile
)
return response.output_text
In questo esempio, il contratto di riferimento e il quadro di analisi costituiscono il blocco invariante, mentre la clausola esaminata cambia a ogni chiamata. Analizza quaranta clausole dello stesso contratto e pagherai il contesto una volta sola a prezzo pieno.
Verifica della cache
Un’ottimizzazione che non misuri è un’ottimizzazione che pensi solo di avere. L’API restituisce informazioni sull’utilizzo della cache nella risposta:
response = client.responses.create(
model="gpt-5.6-terra",
instructions=SYSTEM_PROMPT,
input="Analizza la clausola di non concorrenza.",
)
# Controlla l'utilizzo della cache
usage = response.usage
print(f"Token di input: {usage.input_tokens}")
print(f"Token di input (in cache): {usage.input_tokens_details.cached_tokens}")
print(f"Token di output: {usage.output_tokens}")
# Se cached_tokens > 0: la cache è stata utilizzata
cache_ratio = usage.input_tokens_details.cached_tokens / usage.input_tokens
print(f"Rapporto di cache: {cache_ratio:.1%}")
Registra questo rapporto in produzione invece di controllarlo una sola volta in sviluppo. Un calo improvviso del tasso di cache è il sintomo più affidabile di una modifica involontaria nella costruzione del prompt e lo vedrai prima che la fattura mensile te lo segnali.
Strutturazione per massimizzare la cache
Il primo approccio consiste nell’arricchire deliberatamente il prompt di sistema. Questo può sembrare controintuitivo quando cerchi di ridurre i token, ma si allinea alla regola della soglia: un prompt di sistema di 900 token non verrà mai memorizzato nella cache, mentre lo stesso prompt arricchito con esempi few-shot e un documento di riferimento supera la soglia e passa alla tariffa ridotta per la parte memorizzata nella cache.
# Arricchisci il prompt di sistema per massimizzare la cache
ENRICHED_PROMPT = """
[Istruzioni dettagliate - oltre 500 token]
[Esempi few-shot - oltre 500 token]
[Documento di riferimento - oltre 1.000 token]
---
Totale > 1.024 token = idoneo per la cache
"""
In una conversazione multi-turno, il meccanismo lavora a tuo favore senza sforzo aggiuntivo: la cronologia accumulata forma un prefisso naturalmente stabile che cresce a ogni scambio. Finché reinietti sempre i messaggi nello stesso ordine, il decimo turno beneficia della cache costruita dai precedenti nove.
def conversation_with_cache(history: list[dict], new_message: str):
"""La cronologia crescente massimizza automaticamente la cache."""
history.append({"role": "user", "content": new_message})
response = client.responses.create(
model="gpt-5.6-terra",
instructions=SYSTEM_PROMPT,
input=history,
)
history.append({
"role": "assistant",
"content": response.output_text,
})
return response.output_text
Infine, poiché la durata della cache si misura in minuti, raggruppare le richieste che condividono un prefisso diventa una decisione di pianificazione. Elaborare quaranta clausole di un contratto una dopo l’altra mantiene la cache “calda”; distribuirle nell’arco della giornata intercalando altri file la lascia scadere tra una chiamata e l’altra.
import asyncio
async def batch_with_cache(clauses: list[str]) -> list[str]:
"""Invia le richieste rapidamente per sfruttare la cache."""
results = []
for clause in clauses:
result = analyze_clause(clause)
results.append(result)
return results
Tre errori annullano tutto questo lavoro e si assomigliano: modificare l’inizio del prompt, anche di un solo carattere, invalida la cache per l’intera richiesta; randomizzare l’ordine delle istruzioni, ad esempio costruendo il prompt da un dizionario non ordinato, produce lo stesso effetto in modo intermittente ed è quindi difficile da diagnosticare; e aspettarsi guadagni al di sotto della soglia di 1.024 token significa cercare di ottimizzare qualcosa che non si attiva mai.
Punti chiave
- Il caching dei prompt è automatico con OpenAI: posiziona gli elementi stabili all’inizio del prompt
- Soglia minima: 1.024 token identici nel prefisso
- Guadagno: ~50% sui token di input in cache + TTFT ridotto
- Controlla
usage.input_tokens_details.cached_tokensper confermare il caching