BroadRouter

Come strutturare i prompt perché il prefisso vada in cache

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato · Aggiornato

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.

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?

  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:

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, 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.

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.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity