BroadRouter

Cache delle risposte delle API LLM: una cache esatta in Python

A cura del team di BroadNet Inference · 8 min di lettura · Pubblicato

Calcola un hash dell’intera richiesta (modello, messaggi, temperature, max_tokens, response_format, tool, impostazioni di ragionamento e la versione del tuo prompt) come chiave, e salva la risposta sotto quella chiave con una scadenza. Restituisci una risposta salvata solo per richieste deterministiche e senza effetti collaterali. Prima misura nei tuoi log quanto spesso si ripetono richieste identiche: quella quota è il massimo che una cache esatta può farti risparmiare.

Ogni richiesta LLM identica che invii due volte la paghi due volte. Una cache delle risposte salva la risposta la prima volta e la restituisce la volta successiva, senza token fatturati e senza attesa. L’idea è semplice. Le parti difficili sono decidere cosa rende “identiche” due richieste, quali richieste non vanno mai servite da una copia salvata e se il tuo traffico si ripete abbastanza da fare la differenza.

Questo articolo costruisce in Python una piccola cache a corrispondenza esatta su SQLite, testata contro un server mock compatibile con OpenAI, e mostra come misurare la percentuale di hit dai tuoi log prima di scriverne una riga.

La cache delle risposte è uguale al prompt caching?

No. Fanno risparmiare cose diverse, e puoi usarle entrambe.

Prompt caching (provider) Cache delle risposte (tu)
Cosa si riutilizza L’inizio ripetuto del prompt L’intera risposta
Chi la gestisce Il provider dell’API Il tuo codice
Il modello gira comunque? Sì, scrive una risposta nuova No
Cosa fa risparmiare Parte del costo dell’input Token di input, di output e di ragionamento, più la latenza
Quando va a segno Prefisso condiviso, domande diverse Esattamente la stessa richiesta

I token di input in cache spiegano il lato provider, e la struttura del prompt per la cache mostra come organizzare un prompt perché il prefisso venga riutilizzato. Il calcolatore del prompt caching ne calcola il prezzo. Una cache delle risposte sta davanti a tutto questo: in caso di hit, nessuna richiesta lascia il tuo server.

Una cache ti farà davvero risparmiare?

Misura prima di costruire. Le percentuali di risparmio di molti tutorial sul caching vengono dal traffico di qualcun altro. Il tuo numero dipende da una cosa sola: quanto spesso la stessa richiesta arriva di nuovo entro la finestra di scadenza.

Se registri già ogni chiamata, come in log dell’uso delle API LLM, aggiungi un campo: request_hash, la chiave della cache descritta più sotto. Non contiene testo del prompt, quindi va bene in un log che tiene fuori i contenuti. Poi conta le ripetizioni:

import json
from collections import Counter

def potential_hit_rate(log_path: str) -> float:
    """Share of calls whose request_hash was already seen: an upper bound for an exact cache."""
    hashes = [json.loads(line)["request_hash"] for line in open(log_path)]
    seen, repeats = set(), 0
    for h in hashes:
        repeats += h in seen
        seen.add(h)
    print("top repeated requests:", Counter(hashes).most_common(3))
    return repeats / len(hashes) if hashes else 0.0

print(f"potential hit rate: {potential_hit_rate('calls.jsonl'):.1%}")

Su un log sintetico di 20 chiamate, con una richiesta ripetuta cinque volte, un’altra tre volte e dodici uniche, ha stampato una percentuale di hit potenziale del 30,0%. È un limite superiore: ignora la scadenza e presume che ogni ripetizione si possa servire in sicurezza dalla copia salvata.

Poi trasforma la percentuale in denaro:

monthly saving = hit rate × requests per month
                 × (input tokens × input price + output tokens × output price) ÷ 1,000,000

Cioè: risparmio mensile = percentuale di hit × richieste al mese × (token di input × prezzo dell’input + token di output × prezzo dell’output) ÷ 1.000.000.

I token di output includono il ragionamento. La documentazione di BroadNet dice che DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere e che il ragionamento conta in max_tokens, quindi un hit fa risparmiare token che nella risposta non vedi mai. Prendi completion_tokens dall’usage registrato, non dalla lunghezza della risposta.

Un esempio in token: 100.000 richieste al mese da 1.200 token di input e 150 di output ciascuna, con una percentuale di hit del 30%, evitano 36 milioni di token di input e 4,5 milioni di token di output. Su DeepSeek V4.1 Flash si pagano rispettivamente $0.175 e $0.52 per 1M; inserisci i tuoi dati nel calcolatore dei costi delle API LLM. Se gran parte di quell’input era già un hit della cache del provider, il risparmio sull’input è alla tariffa più bassa dell’input in cache ($0.0055 per 1M sullo stesso modello), quindi spesso conta soprattutto il lato output.

Cosa va nella chiave della cache?

Tutto ciò che può cambiare la risposta, e nient’altro.

  • Includi: model, l’intero elenco messages (prompt di sistema compreso), temperature, top_p, max_tokens, seed, response_format, tools, tool_choice e reasoning_effort.
  • Aggiungi una versione del prompt che controlli tu, per esempio faq-v3. Incrementala quando cambi template dei prompt, dati di retrieval o post-elaborazioni che il corpo della richiesta non mostra.
  • Lascia fuori tutto ciò che varia a ogni chiamata senza cambiare la risposta: ID di richiesta, timestamp, header di tracing, un campo user che invii solo per il monitoraggio degli abusi.

Serializza il materiale della chiave sempre allo stesso modo. json.dumps di Python con sort_keys=True e separators=(",", ":") produce un’unica stringa canonica a prescindere dall’ordine del dizionario; ensure_ascii=False mantiene l’arabo e gli altri testi non latini in UTF-8 invece che come sequenze di escape. Calcolane l’hash con SHA-256.

L’errore pericoloso è un campo mancante. Se max_tokens non è nella chiave, una risposta troncata con un limite basso verrà servita a una richiesta che ne consentiva una lunga.

La cache: SQLite, TTL e una policy di esclusione

import hashlib, json, sqlite3, time

# Every field that changes the answer belongs in the key.
KEY_FIELDS = ("model", "messages", "temperature", "top_p", "max_tokens", "seed",
              "response_format", "tools", "tool_choice", "reasoning_effort")

def cache_key(params: dict, prompt_version: str) -> str:
    material = {k: params[k] for k in KEY_FIELDS if k in params}
    material["prompt_version"] = prompt_version
    canon = json.dumps(material, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
    return hashlib.sha256(canon.encode("utf-8")).hexdigest()

class ResponseCache:
    def __init__(self, path="llm_cache.sqlite", ttl_s=7 * 86400):
        self.db, self.ttl = sqlite3.connect(path), ttl_s
        self.db.execute("CREATE TABLE IF NOT EXISTS cache (k TEXT PRIMARY KEY, created REAL,"
                        " body TEXT, prompt_tokens INT, completion_tokens INT)")
        self.hits = self.misses = self.skips = self.saved_in = self.saved_out = 0

    def create(self, client, prompt_version: str, **params):
        if params.get("stream") or params.get("temperature", 1) > 0:
            self.skips += 1                       # not cacheable: call the model directly
            return client.chat.completions.create(**params)
        k = cache_key(params, prompt_version)
        row = self.db.execute("SELECT body, created, prompt_tokens, completion_tokens"
                              " FROM cache WHERE k = ?", (k,)).fetchone()
        if row and time.time() - row[1] < self.ttl:
            self.hits += 1; self.saved_in += row[2]; self.saved_out += row[3]
            return json.loads(row[0])             # a plain dict, not an SDK object
        self.misses += 1
        r = client.chat.completions.create(**params)
        choice = r.choices[0]
        if choice.finish_reason == "stop" and not choice.message.tool_calls:
            self.db.execute("INSERT OR REPLACE INTO cache VALUES (?, ?, ?, ?, ?)",
                            (k, time.time(), r.model_dump_json(),
                             r.usage.prompt_tokens, r.usage.completion_tokens))
            self.db.commit()
        return r.model_dump()

E un’esecuzione di prova:

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
cache = ResponseCache("demo.sqlite", ttl_s=86400)
SYSTEM = {"role": "system", "content": "Answer questions about our refund policy in one sentence."}
questions = ["How long do refunds take?", "Can I refund a gift card?",
             "How long do refunds take?", "How long do refunds take?", "Can I refund a gift card?"]
for q in questions:
    r = cache.create(client, "faq-v3", model="broadnet/deepseek-v4.1-flash", temperature=0,
                     max_tokens=1200, messages=[SYSTEM, {"role": "user", "content": q}])
    print(r["choices"][0]["message"]["content"])
# a personalised, sampled request is never cached
cache.create(client, "faq-v3", model="broadnet/deepseek-v4.1-flash", temperature=0.7,
             messages=[SYSTEM, {"role": "user", "content": "Write me a friendly reminder"}])
# a new prompt version is a new key
cache.create(client, "faq-v4", model="broadnet/deepseek-v4.1-flash", temperature=0,
             max_tokens=1200, messages=[SYSTEM, {"role": "user", "content": "How long do refunds take?"}])
print(f"hits={cache.hits} misses={cache.misses} skipped={cache.skips} "
      f"saved_input={cache.saved_in} saved_output={cache.saved_out}")

L’abbiamo eseguito con l’SDK Python di OpenAI 3.51.0 contro un server mock locale che contava le chiamate a monte e riportava 1.200 token di prompt e 150 di completamento per risposta (nessuna chiamata all’API reale). Sette richieste hanno prodotto quattro chiamate a monte. Lo script ha stampato hits=3 misses=3 skipped=1 saved_input=3600 saved_output=450. Rieseguito sullo stesso file di database, tutte e sei le richieste memorizzabili sono state hit (hits=6 misses=0): SQLite mantiene la cache tra un riavvio e l’altro. Chiavi costruite dagli stessi campi in ordine diverso hanno coinciso.

Note sul codice:

  • max_tokens=1200 lascia spazio al ragionamento prima della risposta. Con un limite basso un modello che ragiona può restituire una risposta vuota (perché). Quelle risposte non vengono salvate, perché finish_reason è length, non stop.
  • Gli hit restituiscono un dict. Anche i miss restituiscono model_dump(), così chi chiama vede una sola forma. Se il tuo codice si aspetta oggetti dell’SDK, avvolgi entrambi.
  • Una temperature mancante conta come campionata. In quel caso il server applica il proprio default, che può essere sopra 0, quindi il wrapper salta la cache a meno che tu non imposti 0 esplicitamente.
  • SQLite va bene per uno o pochi processi. Per più server, metti la stessa logica di chiave e TTL in Redis o nel tuo database.

Cosa non va mai servito da una cache?

  • Risposte campionate (temperature sopra 0). Hai scelto la varietà. La cache la elimina, e un utente che preme “rigenera” riceve lo stesso testo.
  • Risposte personalizzate, a meno che l’ID utente non sia nella chiave. Due utenti che inviano “riassumi il mio account” hanno account diversi. Meglio ancora: metti in cache solo richieste i cui messaggi non contengono dati del singolo utente.
  • Tool call. Una tool call è un’istruzione ad agire. Riprodurre “rimborsa l’ordine 1182” da una copia salvata può ripetere un effetto collaterale, e il passo successivo giusto dipende dallo stato attuale. Il wrapper rifiuta di salvare qualsiasi risposta con tool_calls.
  • Risposte in streaming. Il wrapper salta la cache per stream=True. Mettere in cache uno stream significa bufferizzarlo, verificare che sia terminato e riprodurlo, cosa che per le interfacce di chat raramente vale la pena.
  • Risposte troncate o fallite. Salva solo con finish_reason == "stop". Una risposta tagliata o un errore in cache per una settimana è un bug che sembra un problema del modello.
  • Risposte che dipendono dal tempo. “Qual è il tasso di cambio di oggi?” richiede un TTL breve o nessuna cache.

Cosa si presta bene alla cache: classificazione di un insieme fisso di input, estrazione da documenti che rielabori, risposte alle FAQ da un prompt fisso, suite di test ed eval che riesegui, e cicli di sviluppo in cui invii la stessa richiesta più e più volte.

Quando devono scadere le risposte in cache?

Usa tre tipi di invalidazione:

  1. TTL. Un limite di tempo per voce: giorni per risposte alle FAQ stabili, minuti per tutto ciò che legge dati in tempo reale.
  2. Versione nella chiave. Cambia la versione del prompt quando cambiano il prompt di sistema, l’indice di retrieval o lo schema dell’output. Le vecchie voci smettono di corrispondere e scadono.
  3. Modello nella chiave. C’è già, quindi passare da un modello all’altro fa partire una cache nuova, ed è ciò che vuoi mentre valuti un cambio.

Elimina le righe scadute a intervalli regolari (DELETE FROM cache WHERE created < ?). Altrimenti il file non fa che crescere.

C’è un vantaggio collaterale. I motori di serving non promettono output identici a parità di input: la documentazione di vLLM dice che «does not guarantee the reproducibility of the results by default» (traduzione: non garantisce di default la riproducibilità dei risultati). Una cache dà a ogni utente la stessa risposta alla stessa domanda per tutta la vita della voce.

E la cache semantica?

Una cache semantica calcola l’embedding di ogni domanda e restituisce una risposta salvata quando una nuova domanda è abbastanza vicina, così “quanto dura un rimborso?” può corrispondere a “quanto tempo richiedono i rimborsi?”. GPTCache è l’esempio open source più noto. Il suo README dice che usa un vector store per la ricerca per similarità e un valutatore di similarità per decidere un hit, avverte che «you may encounter false positives during cache hits and false negatives during cache misses» (traduzione: potresti incontrare falsi positivi negli hit della cache e falsi negativi nei miss) e nota che disattivando gli embedding diventa una cache a parole chiave.

Due punti pratici. Primo, servono un modello di embedding e un vector store. BroadNet Inference non offre embedding, quindi per quello strato useresti un altro provider o un modello locale; il calcolatore dei costi degli embedding mette a confronto le opzioni. Secondo, un falso hit restituisce una risposta sicura di sé a una domanda diversa. Usa una soglia di similarità rigorosa, testala su coppie reali di quasi-corrispondenze e riserva la cache semantica alle risposte a basso rischio. In ogni caso metti davanti la cache esatta: controllarla non costa nulla e non sbaglia mai su cosa è stato chiesto.

Cosa comporta una cache per la privacy?

Una cache è un archivio di prompt e risposte. Questo cambia il posto in cui vivono i tuoi dati.

L’informativa privacy per l’inferenza di BroadNet, verificata il 2026-11-15, dice che il suo gateway non conserva prompt, messaggi, risposte o trascrizioni, mentre vengono conservati registri di traffico e di uso senza contenuti (conteggi di token, costi, tempi). I contenuti dell’inferenza non vengono conservati. I metadati necessari di account, fatturazione e sicurezza vengono conservati come descritto in quell’informativa. Quando aggiungi una cache delle risposte, il tuo sistema conserva i contenuti che il provider non conserva. Trattala come qualsiasi altro archivio di dati degli utenti:

  • Dove puoi, metti in cache solo richieste senza dati personali, il che alza anche la percentuale di hit.
  • Imposta un TTL abbastanza breve per la tua policy di conservazione ed elimina a intervalli regolari.
  • Cifra il file o la tabella a riposo e limita chi può leggerli.
  • Includi la cache nelle richieste di cancellazione dei dati se può contenere testo degli utenti.

Inviare dati sensibili a un’API LLM copre il resto della checklist.

Come si combina la cache con gli altri controlli dei costi?

La cache elimina le chiamate ripetute. Non fa nulla per quelle uniche, quindi affianca gli altri controlli invece di sostituirli: prompt più corti, il prompt caching del provider, un limite max_tokens per richiesta, e budget e limiti ai cicli dal controllo della spesa API LLM. Per grandi job una tantum, elimina i duplicati dagli input prima di inviarli; è la stessa idea di una cache, applicata una volta sola. Elaborare un job grande senza una Batch API mostra il lato dei job.

Con un piano a tariffa flat i conti cambiano. Le sessioni DeepSeek di BroadNet non hanno contatore di token, quindi lì un hit della cache non fa risparmiare denaro. Fa comunque risparmiare tempo: una sessione esegue una richiesta alla volta, quindi ogni ripetizione che salti libera la sessione per lavoro nuovo.

Dove si colloca BroadNet Inference

BroadRouter è il sito di BroadNet. BroadNet Inference offre DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B e Gemma 4 VL 26B dietro un endpoint /v1/chat/completions compatibile con OpenAI, quindi il wrapper qui sopra funziona con l’SDK Python di OpenAI cambiando la base URL. Non ha una propria funzione di cache delle risposte; la cache di questo articolo è tua. Gli hit della cache lato provider sono riportati in usage.prompt_tokens_details.cached_tokens e fatturati al prezzo dell’input in cache, secondo il suo riferimento API. I prezzi per modello sono nella pagina dei prezzi.

Domande frequenti

Che differenza c’è tra prompt caching e cache delle risposte?

Il prompt caching lo fa il provider: un prefisso ripetuto del prompt si paga al prezzo più basso dell’input in cache, e il modello scrive comunque una risposta nuova. La cache delle risposte la fai tu: salvi l’intera risposta e la restituisci per una richiesta identica senza chiamare affatto il modello.

Conviene mettere in cache le risposte LLM con temperature a 0?

Sì, se la richiesta non ha effetti collaterali e la stessa risposta va bene per chiunque la invii. Temperature a 0 non garantisce comunque output identici da un motore di serving, quindi la cache rende anche la risposta coerente. Non usare la cache quando temperature è sopra 0 o non è indicata.

Quanto si risparmia con la cache delle risposte LLM?

La quota di richieste che sono ripetizioni esatte entro la finestra di scadenza, moltiplicata per il costo di quelle richieste. Conta gli hash di richiesta ripetuti nei tuoi log per ottenere quella quota. Può essere quasi zero per una chat aperta e alta per FAQ fisse o input di classificazione.

La cache semantica è meglio della cache a corrispondenza esatta?

Va a segno più spesso, perché domande simili corrispondono, ma può restituire la risposta a una domanda diversa. Richiede anche un modello di embedding e un vector store. Parti da una cache esatta e aggiungi uno strato semantico solo dove un hit sbagliato costa poco.

Posso mettere in cache le risposte in streaming?

Non con il semplice wrapper di questo articolo. Dovresti raccogliere l’intero stream, verificare che sia terminato normalmente, salvarlo e poi riprodurlo come stream. La maggior parte dei team mette in cache solo chiamate senza streaming, come classificazione, estrazione e risposte alle FAQ.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity