---
title: "Struttura del prompt per la cache: un prefisso stabile"
description: "Come organizzare i prompt LLM perché il prefisso in cache resti identico: sistema, schemi dei tool, documenti, cronologia solo in aggiunta e un test che lo prova."
url: https://broadrouter.com/it/blog/prompt-structure-for-caching/
lang: it
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Tradotto dall’inglese con l’aiuto dell’IA. [Leggi l’originale in inglese](https://broadrouter.com/blog/prompt-structure-for-caching/) (aggiornato il 2026-11-16).

# Come strutturare i prompt perché il prefisso vada in cache

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato 2026-11-14 · Aggiornato 2026-11-16

Ordina ogni richiesta dalla parte più stabile alla meno stabile: prompt di sistema, definizioni dei tool, documenti di riferimento, cronologia della conversazione e infine il nuovo messaggio. Rendi ogni strato identico byte per byte tra le chiamate: niente timestamp o ID in testa, tool ordinati, JSON serializzato in modo deterministico e cronologia a cui si aggiunge soltanto. Poi misura cached\_tokens per confermare che il prefisso venga davvero riutilizzato.

## Punti chiave

-   Le cache confrontano un prefisso esatto. Un solo byte cambiato invalida tutto ciò che segue, quindi l’ordine degli strati conta più della loro dimensione.
-   Quattro strati, dal più stabile: prompt di sistema, tool, documenti, cronologia. Il nuovo turno dell’utente va per ultimo.
-   Serializza tool e documenti JSON con chiavi ordinate e separatori fissi; l’ordine dei dizionari rompe la cache senza farsi notare.
-   Limita i tool per singola chiamata con tool\_choice invece di togliere definizioni.
-   Testalo: invia lo stesso prefisso due volte e verifica che prompt\_tokens\_details.cached\_tokens salga alla seconda chiamata.

**In questa pagina**

1.  Perché l’ordine del prompt decide la percentuale di hit della cache?
2.  Qual è l’ordine giusto degli strati?
3.  Cosa rompe il prefisso senza che te ne accorga?
4.  Come costruire nel codice una richiesta adatta alla cache?
5.  Come dimostrare che il prefisso è in cache?
6.  Cosa cambia per agenti e contesti lunghi?
7.  Dove si colloca BroadNet Inference

I [token di input in cache](https://broadrouter.com/it/glossary/cached-input-tokens/) 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](https://broadrouter.com/it/blog/cached-input-tokens-explained/) 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](https://broadrouter.com/it/glossary/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?

1.  **L’ordine dei dizionari.** I framework costruiscono spesso l’array `tools` da un dizionario o da un registro. Se i plugin si caricano in un ordine diverso, i byte cambiano.
2.  **La formattazione JSON.** `json.dumps(x)` e `json.dumps(x, indent=2)` sono prefissi diversi. Lo sono anche due serializzatori con un ordine delle chiavi diverso.
3.  **Spazi nei template.** Uno spazio finale, o un `\r\n` da un percorso del codice e un `\n` da un altro.
4.  **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_choice` o un’impostazione dei tool consentiti.
5.  **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.
6.  **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:

```python
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:

1.  Costruisci una richiesta con il tuo vero prompt di sistema, i tuoi tool e i tuoi documenti.
2.  Inviala. Annota `usage.prompt_tokens`.
3.  Cambia solo il messaggio finale dell’utente e invia di nuovo.
4.  Leggi `usage.prompt_tokens_details.cached_tokens` alla seconda chiamata. Dovrebbe coprire quasi tutto il prefisso condiviso.
5.  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](https://broadrouter.com/it/blog/llm-api-usage-logging/), e usa il [calcolatore del prompt caching](https://broadrouter.com/tools/prompt-caching-calculator/) 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](https://broadrouter.com/it/blog/million-token-context-window-guide/), 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](https://broadrouter.com/it/blog/llm-latency-ttft-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](https://broadrouter.com/it/models/deepseek-v4.1-flash/), [GLM 5.3](https://broadrouter.com/it/models/glm-5.3/) e [Qwen3.8 27B](https://broadrouter.com/it/models/qwen3.8-27b/) si paga alla tariffa più bassa indicata nella [pagina dei prezzi](https://broadrouter.com/it/pricing/). 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.

Strumenti gratuiti sul tema (in inglese)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Strumenti gratuiti (in inglese)](https://broadrouter.com/tools/)

## Termini in questo articolo

[Token](https://broadrouter.com/it/glossary/token/)

Un token è l’unità di testo che un modello linguistico legge e scrive: una parola, una parte di parola, un segno di punteggiatura o una sequenza di byte prodotta dal tokenizer del modello. Le API LLM contano, limitano e di solito fatturano l’uso in token.

[System prompt (prompt di sistema)](https://broadrouter.com/it/glossary/system-prompt/)

Il system prompt è il testo di istruzioni che un’applicazione invia a un modello linguistico prima della conversazione, di solito come messaggio con ruolo system o developer. Stabilisce ruolo, regole, tono e formato di output del modello, che dovrebbe seguirlo anche quando i messaggi dell’utente lo contraddicono.

[Token di input in cache (cached input)](https://broadrouter.com/it/glossary/cached-input-tokens/)

I token di input in cache sono token del prompt che un provider LLM ha elaborato da poco e può riusare da una cache invece di ricalcolarli, di solito un prefisso ripetuto come un system prompt o un documento. I provider li fatturano a una tariffa più bassa dei token di input nuovi.

[Throughput](https://broadrouter.com/it/glossary/throughput/)

Il throughput, nel serving di LLM, è la quantità totale di lavoro che un sistema completa per unità di tempo su tutte le richieste concorrenti, di solito misurata in token di output al secondo o richieste al secondo. È diverso dalla velocità per stream, cioè quanto rapidamente una singola richiesta riceve i suoi token.

[Time to first token (TTFT)](https://broadrouter.com/it/glossary/time-to-first-token/)

Il time to first token (TTFT) è il tempo che passa dall’invio di una richiesta a un modello linguistico all’arrivo del primo token di output. Comprende il tempo di rete, la coda sul server e il prefill, la fase in cui il modello legge l’intero prompt, quindi cresce con la lunghezza del prompt e con il carico.

[Token di input e di output](https://broadrouter.com/it/glossary/input-and-output-tokens/)

I token di input sono quelli che un modello linguistico legge in una richiesta: system prompt, cronologia, definizioni degli strumenti e immagini. I token di output sono quelli che genera in risposta, ragionamento compreso. Le API LLM di solito li prezzano separatamente, e l’output costa di più.

[Finestra di contesto (context window)](https://broadrouter.com/it/glossary/context-window/)

La finestra di contesto è il numero massimo di token con cui un modello linguistico può lavorare in una singola richiesta. Comprende prompt, cronologia della conversazione, definizioni degli strumenti, immagini e output generato, token di ragionamento inclusi. Ciò che non ci sta va tagliato, riassunto o diviso su più richieste.

[KV cache (cache chiave-valore)](https://broadrouter.com/it/glossary/kv-cache/)

La KV cache è la memoria in cui un modello linguistico transformer conserva le chiavi e i valori di attenzione calcolati per ogni token già elaborato, così ogni nuovo token li riusa invece di ricalcolare l’intera sequenza. Cresce con la lunghezza del contesto e spesso limita quante richieste una GPU può servire.

## Domande frequenti

### Perché la percentuale di hit della cache del mio prompt è bassa?

Qualcosa vicino all’inizio del prompt cambia a ogni chiamata. Le cause tipiche sono un timestamp o un ID di richiesta nel prompt di sistema, tool serializzati in un ordine diverso, documenti recuperati messi prima delle istruzioni, o una cronologia che viene riassunta e riscritta.

### La domanda dell’utente va prima o dopo i documenti lunghi?

Dopo. Metti prima i documenti e per ultima la domanda. Così i documenti formano un prefisso riutilizzabile, e molti modelli rispondono anche meglio quando la domanda segue il materiale.

### Le definizioni dei tool rompono il prompt caching?

Solo se cambiano. I tool fanno parte del prefisso, quindi tieni lo stesso insieme, nello stesso ordine, con lo stesso JSON. Per limitare i tool in una chiamata, usa tool\_choice invece di modificare l’elenco.

### L’ordine degli esempi few-shot conta per la cache?

Sì. Esempi rimescolati producono ogni volta un prefisso diverso. Fissa l’ordine, oppure metti dopo la parte stabile gli esempi che cambiano a ogni richiesta.

## Continua a leggere

-   [Token di input in cache: come ridurre la bolletta delle API LLM](https://broadrouter.com/it/blog/cached-input-tokens-explained/)
-   [Quando conviene una finestra di contesto da 1M di token (e quando no)](https://broadrouter.com/it/blog/million-token-context-window-guide/)
-   [API LLM a tariffa flat o a consumo per token: i conti del pareggio](https://broadrouter.com/it/blog/flat-rate-vs-pay-per-token-llm-api/)
-   [Hardware GPU e serving di BroadNet, come li descrive BroadNet](https://broadrouter.com/it/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache delle risposte delle API LLM: una cache esatta in Python](https://broadrouter.com/it/blog/cache-llm-responses-cut-cost/)
-   [Guida: Streaming delle chat completions e connessioni interrotte](https://broadrouter.com/it/guides/streaming-chat-completions/)
-   [Guida: Usare l’SDK Python di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-python-sdk/)

Provalo sul tuo carico di lavoro reale. I nuovi account partono con USD 5 di credito per Gemma e trascrizione. DeepSeek, GLM e Qwen3.8 richiedono una ricarica.

[Inizia](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-prompt-structure-for-caching&utm_content=page-cta) ·

**Fonti**

-   [Riferimento API di BroadNet Inference, token in cache in usage (consultato il 2026-11-16) (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-prompt-structure-for-caching&utm_content=sources)
-   [Guida di OpenAI al prompt caching, corrispondenza del prefisso e consigli di struttura (consultata il 2026-11-14)](https://developers.openai.com/api/docs/guides/prompt-caching)
-   [Documentazione di Anthropic sul prompt caching, ordine della cache: tool, poi system, poi messaggi (consultata il 2026-11-16)](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
-   [Documentazione API di DeepSeek, context caching (consultata il 2026-11-14)](https://api-docs.deepseek.com/guides/kv_cache)
