I token di input in cache costano poco: su BroadNet Inference, DeepSeek V4.1 Flash li fattura a $0.0055 per 1M invece di $0.175. La spiegazione dei token in cache copre il prezzo e come leggere il campo usage. Questo articolo riguarda il lavoro di progettazione: come organizzare un prompt perché la cache vada davvero a segno, e come dimostrarlo.
Perché l’ordine del prompt decide la percentuale di hit della cache?
Tutti i principali provider fanno cache per prefisso. La guida di OpenAI dice che il riutilizzo richiede che coincida l’intero prefisso renderizzato. La documentazione di DeepSeek descrive la stessa regola: una richiesta va a segno solo se corrisponde completamente a un prefisso memorizzato, e una che diverge a metà strada no. Anthropic costruisce la cache nell’ordine tool, system, messaggi.
Dietro le quinte il server riutilizza la KV cache costruita per quel prefisso. Quindi la cache è una linea retta dal primo token. Il primo byte diverso dalla chiamata precedente chiude la parte riutilizzabile. Un timestamp di una riga in testa a un prompt da 50.000 token ti costa tutti i 50.000 token a prezzo pieno.
Qual è l’ordine giusto degli strati?
| Strato | Cambia | Esempio | Regola |
|---|---|---|---|
| 1. Prompt di sistema | A ogni deploy | Ruolo, regole, formato dell’output | Niente date, ID, nomi utente |
| 2. Definizioni dei tool | A ogni deploy | Schemi delle funzioni | JSON ordinato e deterministico |
| 3. Materiale di riferimento | Per sessione o compito | File del repository, contratti, documentazione di prodotto | Ordine fisso, etichette stabili |
| 4. Cronologia della conversazione | A ogni turno, solo in aggiunta | Turni precedenti di utente e assistente | Mai modificare; solo aggiungere |
| 5. Nuovo messaggio | A ogni chiamata | La domanda, più l’ora corrente se serve | I dati volatili vanno qui |
Lo strato 5 è il posto di tutto ciò che è volatile: la data corrente, la lingua dell’utente, un ID di richiesta, frammenti recuperati che cambiano a ogni domanda.
Cosa rompe il prefisso senza che te ne accorga?
- L’ordine dei dizionari. I framework costruiscono spesso l’array
toolsda un dizionario o da un registro. Se i plugin si caricano in un ordine diverso, i byte cambiano. - La formattazione JSON.
json.dumps(x)ejson.dumps(x, indent=2)sono prefissi diversi. Lo sono anche due serializzatori con un ordine delle chiavi diverso. - Spazi nei template. Uno spazio finale, o un
\r\nda un percorso del codice e un\nda un altro. - Elenchi di tool dinamici. Togliere i tool che un utente non può usare cambia il prefisso. La guida di OpenAI consiglia di tenere stabili le definizioni e di limitarne l’uso con
tool_choiceo un’impostazione dei tool consentiti. - Riassumere la cronologia sul posto. Riscrivere i vecchi turni in un riassunto azzera tutto ciò che viene dopo il prompt di sistema. Riassumi di rado e a grandi passi.
- Recupero prima delle istruzioni. Frammenti RAG messi tra il prompt di sistema e i tool cambiano a ogni query e rompono anche lo strato dei tool.
Come costruire nel codice una richiesta adatta alla cache?
Fai di ogni strato una funzione di soli input stabili, e serializza in modo deterministico:
import json, os
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
SYSTEM = open("prompts/system.md").read() # versioned file, no templating
def stable_tools(registry: dict) -> list:
# Sort by name, sort keys inside each schema.
return [json.loads(json.dumps(registry[name], sort_keys=True)) for name in sorted(registry)]
def docs_block(paths: list[str]) -> str:
parts = [f"=== {p} ===\n{open(p).read()}" for p in sorted(paths)]
return "\n\n".join(parts)
def build_messages(history: list, user_text: str, now_iso: str, doc_paths: list[str]):
return (
[{"role": "system", "content": SYSTEM},
{"role": "user", "content": docs_block(doc_paths)}]
+ history # append-only
+ [{"role": "user", "content": f"(now: {now_iso})\n{user_text}"}]
)
resp = client.chat.completions.create(
model="broadnet/deepseek-v4.1-flash",
messages=build_messages(history, question, now_iso, files),
tools=stable_tools(TOOLS),
)
history += [{"role": "user", "content": question}, resp.choices[0].message.model_dump(exclude_none=True)]
Due dettagli. L’ora corrente va nell’ultimo messaggio, non nel prompt di sistema. E la cronologia salva il messaggio dell’assistente esattamente come è stato restituito, così la chiamata successiva reinvia byte identici.
Come dimostrare che il prefisso è in cache?
Esegui un test a due chiamate in CI o in un notebook:
- Costruisci una richiesta con il tuo vero prompt di sistema, i tuoi tool e i tuoi documenti.
- Inviala. Annota
usage.prompt_tokens. - Cambia solo il messaggio finale dell’utente e invia di nuovo.
- Leggi
usage.prompt_tokens_details.cached_tokensalla seconda chiamata. Dovrebbe coprire quasi tutto il prefisso condiviso. - Se è zero o basso, confronta byte per byte i corpi delle richieste serializzate. La prima differenza è ciò che rompe la cache.
Sulla maggior parte dei provider la cache è best-effort, e la documentazione di DeepSeek lo dice esplicitamente, quindi un singolo miss non prova un bug. Un miss costante sì. Tieni traccia del rapporto tra token in cache e token del prompt per richiesta nei tuoi log dell’uso, e usa il calcolatore del prompt caching per vedere quanto fa risparmiare una percentuale di hit più alta.
Cosa cambia per agenti e contesti lunghi?
Gli agenti ne beneficiano di più perché reinviano lo stesso grande prefisso decine di volte per compito. Contano due abitudini:
- Una conversazione per compito. Aprire una conversazione nuova per ogni sotto-passaggio butta via il prefisso.
- Leggi i file una volta, vicino all’inizio. Se l’agente rilegge un file, aggiungi la nuova copia invece di sostituire la vecchia, a meno che il file non sia cambiato.
Con una finestra di contesto da 1M di token, lo strato 3 può contenere un intero repository. Con una chiave a consumo è sostenibile solo se va in cache, ed è per questo che l’ordine degli strati conta di più man mano che i prompt crescono. I prefissi in cache tendono anche a ridurre il tempo al primo token; vedi TTFT e throughput.
Dove si colloca BroadNet Inference
Su BroadNet Inference il blocco usage riporta prompt_tokens_details.cached_tokens quando il modello lo fornisce, e l’input in cache su DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B si paga alla tariffa più bassa indicata nella pagina dei prezzi. La documentazione di BroadNet non prevede breakpoint espliciti per la cache né un parametro di chiave della cache, quindi la struttura descritta sopra è tutta la tecnica. Con un piano illimitato la cache non cambia la fattura, perché le sessioni non hanno contatore di token, ma la stessa struttura aiuta comunque la latenza.
