Caching avanzato dei prompt
In questa pagina
Oltre il caching automatico
Hai visto le basi del caching dei prompt nella Lezione 3. Lì, il caching appariva come un meccanismo automatico che ti avvantaggia senza alcuno sforzo speciale, e questo è vero finché la tua applicazione invia richieste ben ordinate. La realtà della produzione è più caotica: più utenti colpiscono la stessa API simultaneamente, ognuno con la propria cartella, documenti e domande. Il prefisso comune si riduce allora a quasi nulla e il tasso di successo della cache crolla senza che nessuno se ne accorga, poiché nulla si rompe: aumenta solo la fattura.
Pipeline di elaborazione multi-utente e multi-documento: affronteremo questi scenari complessi uno per uno per massimizzare il tasso di successo della cache. Il principio guida sta in una frase: il caching non è qualcosa che ti capita; è qualcosa che progetti.
Architettura del prompt per massimizzare il caching
Il caching si applica al prefisso comune più lungo tra le tue richieste. Più questo prefisso è lungo e stabile, più risparmi. La conseguenza pratica è che un prompt deve essere organizzato dal più stabile al più variabile, come un libro le cui prime pagine non cambiano mai e solo il capitolo finale viene riscritto a ogni edizione.
L’esempio seguente applica questo principio a un assistente di analisi documentale per uno studio legale. Tre strati si susseguono: istruzioni globali, che sono congelate; la base di conoscenza, rivista una volta al mese; e il fascicolo del caso e la domanda, che cambiano a ogni chiamata.
import openai
client = openai.OpenAI()
# Architettura a strati: dal più stabile al più variabile
# Strato 1: Istruzioni globali (non cambiano mai)
GLOBAL_INSTRUCTIONS = """
You are a document analysis assistant for a law firm.
Rules:
- Always respond in French
- Cite relevant legal articles
- Structure as: Analysis / Risks / Recommendations
- Be factual and precise
"""
# Strato 2: Base di conoscenza (cambia raramente)
KNOWLEDGE_BASE = """
[Insert 5,000+ tokens of case law, legal articles,
analysis templates here—this content changes at most once a month]
"""
# Strato 3: Contesto del caso (cambia per cliente)
def build_prompt(case_context: str, question: str) -> str:
return f"""{GLOBAL_INSTRUCTIONS}
{KNOWLEDGE_BASE}
--- Current Case ---
{case_context}
--- Question ---
{question}"""
L’errore classico è posizionare il nome del cliente o la data odierna all’inizio del prompt di sistema per “personalizzarlo”. Un singolo carattere variabile nella posizione iniziale è sufficiente a rendere unico il prefisso, riducendo a zero il tasso di successo della cache per tutti gli strati successivi. Tutto ciò che varia deve andare alla fine.
Ovviamente, devi verificare che la teoria si traduca in numeri. Il monitor seguente legge input_tokens_details.cached_tokens su ogni risposta e accumula le misurazioni, fornendoti un tasso medio utilizzabile piuttosto che una sensazione istintiva.
class CacheMonitor:
"""Monitora l'efficienza del caching dei prompt."""
def __init__(self):
self.calls: list[dict] = []
def record(self, usage) -> dict:
total_input = usage.input_tokens
cached_tokens = getattr(
usage.input_tokens_details, "cached_tokens", 0
)
rate = cached_tokens / total_input if total_input > 0 else 0
entry = {
"total_input": total_input,
"cached_tokens": cached_tokens,
"cache_rate": rate,
}
self.calls.append(entry)
return entry
@property
def average_rate(self) -> float:
if not self.calls:
return 0.0
return sum(a["cache_rate"] for a in self.calls) / len(self.calls)
def report(self) -> str:
if not self.calls:
return "Nessuna chiamata."
return (
f"Chiamate: {len(self.calls)} | "
f"Tasso medio di cache: {self.average_rate:.1%} | "
f"Token risparmiati: "
f"{sum(a['cached_tokens'] for a in self.calls):,}"
)
monitor = CacheMonitor()
Tre pattern che fanno la differenza
Il primo pattern riguarda l’ordine di elaborazione. Quando elabori un batch di richieste eterogenee, eseguirle nell’ordine di arrivo alterna i prefissi e impedisce alla cache di rimanere calda. Raggruppare per contesto condiviso risolve il problema: raccogli prima, esegui dopo, così ogni gruppo beneficia del prefisso preparato dalla sua prima richiesta.
from collections import defaultdict
def group_by_context(
requests: list[dict],
) -> dict[str, list[dict]]:
"""Raggruppa le richieste per prefisso comune."""
groups = defaultdict(list)
for request in requests:
# Chiave = hash del contesto condiviso
key = hash(request.get("shared_context", ""))
groups[key].append(request)
return dict(groups)
def process_by_cohort(requests: list[dict]):
"""Elabora le richieste raggruppate per massimizzare il caching."""
groups = group_by_context(requests)
for key, group in groups.items():
# Tutte le richieste nel gruppo condividono lo stesso prefisso
for request in group:
response = client.responses.create(
model="gpt-5.6-terra",
instructions=request["shared_context"],
input=request["question"],
)
monitor.record(response.usage)
Il secondo pattern gestisce le partenze a freddo (cold start). La prima richiesta di una serie paga il prezzo pieno poiché nulla è ancora in cache; se quella prima richiesta proviene da un utente reale un lunedì mattina alle 9:00, è lui a subire la latenza. Una richiesta di riscaldamento inviata prima dell’apertura del servizio sposta quel costo dove non dà fastidio a nessuno. Nota il controllo all’inizio della funzione: sotto i 1.024 token, il caching non si applica e il pre-riscaldamento sarebbe una pura spesa.
def warm_up_cache(system_prompt: str):
"""Invia una richiesta minima per preparare la cache."""
if len(system_prompt) // 4 < 1024:
print("Prompt troppo corto per il caching (< 1.024 token)")
return
response = client.responses.create(
model="gpt-5.6-terra",
instructions=system_prompt,
input="Confirm that you are ready.",
max_output_tokens=10,
)
usage = response.usage
print(
f"Cache preparata: {usage.input_tokens} token in input, "
f"{getattr(usage.input_tokens_details, 'cached_tokens', 0)} in cache"
)
Il terzo pattern rende visibile l’invalidazione della cache. Correggere una virgola in un prompt di sistema di 5.000 token sembra banale, eppure quella virgola svuota la cache per tutti. Allegando un’impronta digitale al contenuto, rilevi la modifica al momento del deployment piuttosto che il giorno dopo sulla fattura, e puoi procedere immediatamente con il pre-riscaldamento.
import hashlib
class VersionedPrompt:
"""Gestisce le versioni dei prompt per controllare il caching."""
def __init__(self, content: str):
self.content = content
self.version = hashlib.md5(content.encode()).hexdigest()[:8]
def is_same_version(self, other: "VersionedPrompt") -> bool:
return self.version == other.version
# Se la versione cambia, la cache verrà invalidata
prompt_v1 = VersionedPrompt("Instructions v1...")
prompt_v2 = VersionedPrompt("Instructions v2 modified...")
if not prompt_v1.is_same_version(prompt_v2):
print("Attenzione: prompt modificato, la cache verrà invalidata")
warm_up_cache(prompt_v2.content)
Cosa significa questo in volume
Prendi un caso reale di 10.000 chiamate al giorno con un prompt di sistema di 3.000 token. Senza caching, fatturi 10.000 × 3.000, ovvero 30 milioni di token in input ogni giorno. Con un tasso di successo dell’80%, 6 milioni di token rimangono a prezzo pieno e 24 milioni scendono a metà prezzo, portando il risparmio a circa il 40% sui token in input. La cifra sembra modesta rispetto a una singola chiamata; nel corso di un anno di produzione, cambia la struttura dei costi dell’applicazione.
Punti chiave
- Struttura i tuoi prompt a strati, dal più stabile al più variabile
- Raggruppa le richieste per contesto condiviso per mantenere la cache calda
- Riscalda la cache prima dei picchi di traffico
- Monitora il tasso di cache con
input_tokens_details.cached_tokens - Versiona i tuoi prompt per anticipare le invalidazioni della cache