Controllo rapido della cache in un gateway API multimodello: prefissi stabili, isolamento dei tenant e analisi degli accessi alla cache

La memorizzazione nella cache immediata è facile da sprecare. Un team potrebbe avere un prompt di sistema da 40.000 token, uno schema di strumenti, un blocco di policy, una mappa del repository o una memoria dell'agente che dovrebbe essere riutilizzabile, quindi inserire accidentalmente un timestamp, un ID di richiesta, un nome utente, uno snippet di recupero o un ordinamento casuale degli strumenti nella parte superiore del prompt. Il provider vede un prefisso diverso, la cache viene persa, la latenza aumenta e la fattura sembra confusa.

In un'applicazione con provider singolo, puoi risolvere questo problema all'interno del modello dell'applicazione. In un gateway multi-modello, il problema è più grande: ogni provider espone diversi controlli della cache, soglie dei token, comportamento time-to-live, campi di utilizzo e semantica di fatturazione. Il gateway necessita di un modello di piano di controllo portatile per assemblare prompt sicuri per la cache, misurare il comportamento della cache, isolare i tenant e attribuire i costi.

Questo articolo descrive un'architettura di riferimento. Non è un caso di studio del cliente e non rivendica risultati di benchmark. I fatti seguenti provengono dalla documentazione del fornitore e dalla ricerca pubblica; le raccomandazioni di progettazione costituiscono una guida operativa a livello di gateway.

La modalità di errore: assemblaggio del prompt che compromette la cache

La memorizzazione nella cache dei prompt generalmente premia la ripetizione dei prefissi dei prompt. I meccanismi esatti variano a seconda del fornitore, ma l'implicazione pratica è coerente: se la parte anteriore del prompt cambia, il riutilizzo ne risente.

Gli interruttori comuni della cache includono:

• Metadati per richiesta in alto: timestamp, ID di traccia, ID di sessione, ID di distribuzione o etichette di richiesta generate.
• Dati specifici dell'utente nel prefisso: nomi, attributi dell'account, autorizzazioni o preferenze private posizionati prima dei blocchi di policy o strumenti riutilizzabili.
• Serializzazione degli strumenti instabile: schemi di strumenti emessi in ordine non deterministico, con spazi bianchi o ID generati modificati.
• Snippet di recupero troppo presto: contesto RAG inserito prima delle istruzioni di sistema stabili o del contesto del repository condiviso.
• Deriva del modello: piccole modifiche al testo rilasciate frequentemente senza controllo delle versioni o diagnostica della cache.

Un gateway non può magicamente rendere memorizzabile nella cache un prefisso instabile, ma può applicare un contratto di assemblaggio del prompt e rendere visibili i mancati risultati della cache.

Dati del provider su cui progettare

I dettagli contano perché un gateway deve normalizzare il comportamento senza fingere che i fornitori siano identici.

• OpenAI: OpenAI ha documentato la memorizzazione nella cache dei prompt per il prefisso di prompt più lungo calcolato in precedenza. Inizia con 1.024 token, aumenta con incrementi di 128 token ed espone i conteggi dei token memorizzati nella cache nei campi di utilizzo. OpenAI afferma inoltre che le cache dei prompt vengono generalmente cancellate dopo 5-10 minuti di inattività e vengono sempre rimosse entro un'ora dall'ultimo utilizzo della cache.
• Antropico: la memorizzazione nella cache dei prompt antropici può essere richiesta con cache_control. La sua documentazione descrive la corrispondenza della cache su componenti del prompt come strumenti, contenuto di sistema e messaggi fino al blocco contrassegnato con controllo della cache. Anthropic documenta una cache effimera, inclusa una durata di 5 minuti e un'opzione di 1 ora a un costo aggiuntivo.
• Gemini: la memorizzazione nella cache del contesto di Google Gemini espone i conteggi dei token di accesso alla cache tramite metadati di utilizzo come total_cached_tokens e la relativa documentazione elenca i conteggi minimi dei token di input per modello.
• Implicazioni sul controllo dei dati: la documentazione sul controllo dei dati dell'API di OpenAI rileva che la memorizzazione nella cache estesa dei prompt richiede la memorizzazione di tensori chiave/valore come stato dell'applicazione nello spazio di archiviazione locale della GPU. Anche quando i provider mantengono garanzie di isolamento, i gateway dovrebbero considerare il comportamento della cache come un'infrastruttura sensibile, non come un archivio dati di applicazioni condivise.
• Segnale di ricerca: una ricerca pubblica ha esaminato se le architetture in stile gateway possono introdurre vulnerabilità di caching rapido che aggirano i presupposti di isolamento della cache a livello di provider. Ciò non dimostra che un gateway specifico sia vulnerabile, ma supporta la progettazione conservativa dell'isolamento dei tenant.

Raccomandazione: implementa il controllo della cache come funzionalità gateway con policy esplicite, non come effetto collaterale accidentale di richieste ripetute.

Un contratto di assemblaggio rapido in tre regioni

La decisione progettuale più importante è separare il contenuto stabile da quello volatile prima che la richiesta raggiunga l'adattatore del provider.

Regione 1: prefisso stabile

Il prefisso stabile indica che il contenuto dovrebbe rimanere identico in molte richieste per la stessa applicazione, percorso del modello e versione del modello di prompt. Gli esempi includono:

• istruzioni del sistema principale;
• blocchi di sicurezza e policy;
• schemi degli strumenti;
• documentazione statica del prodotto;
• mappe di repository per agenti di codifica;
• istruzioni fisse sul formato di output.

Questa regione dovrebbe essere deterministica. Il gateway dovrebbe crearlo da modelli con versione, JSON canonizzato e regole di ordinamento stabili. Se è incluso un registro degli strumenti, ordina gli strumenti in base all'ID strumento stabile. Se sono inclusi schemi JSON, serializzali con un ordinamento deterministico delle chiavi e senza timestamp generati.

Regione 2: contesto di inquilino o spazio di lavoro semi-stabile

La regione semistabile cambia meno spesso rispetto alle richieste individuali ma non è condivisa a livello globale. Gli esempi includono:

• le policy specifiche del tenant prevalgono;
• liste consentite degli strumenti a livello di area di lavoro;
• terminologia specifica del cliente;
• convenzioni di codifica del team;
• contesto di progetto di lunga durata.

Questa regione deve avere come ambito un tenant, un'area di lavoro o un limite dell'applicazione. Potrebbe essere ancora memorizzabile nella cache, ma il gateway non dovrebbe mai dare per scontato che un altro tenant possa riutilizzarlo in sicurezza.

Regione 3: suffisso volatile

Il suffisso volatile è la parte per richiesta:

• messaggio utente;
• snippet recuperati per questa query;
• data e ora corrente, se veramente necessario;
• richiedi ID e metadati di traccia, se inclusi nel prompt;
• la conversazione a breve termine si trasforma;
• risultati dello strumento runtime.

La maggior parte degli errori di cache causati dalla progettazione dell'applicazione si verificano perché i dati del suffisso volatile vengono accidentalmente inseriti nel prefisso. Un builder lato gateway dovrebbe renderlo difficile.

Modello di implementazione: builder con prefisso stabile

Un'implementazione pratica del gateway può esporre un'interfaccia di assemblaggio del prompt anziché accettare una stringa di prompt opaca da ogni applicazione.

{
  "template_id": "code-agent-v3",
  "tenant_id": "tenant_123",
  "route": "codifica-contesto-lungo",
  "prefisso_stabile": {
    "system_policy_version": "2026-08-01",
    "toolset_version": "tools-v12",
    "repo_context_version": "repo-map-8491"
  },
  "contesto_semi_stabile": {
    "workspace_policy_version": "workspace-44-v6"
  },
  "suffisso_volatile": {
    "user_message": "Spiega perché questo test fallisce...",
    "retrieval_context_ids": ["chunk_7", "chunk_19"],
    "trace_id": "not_inserted_into_prompt"
  }
}

Il gateway quindi esegue il rendering della richiesta specifica del provider. Ciò fornisce al gateway un luogo in cui applicare le regole:

• rifiuta i timestamp nei campi del prefisso stabile;
• canonicalizzare gli schemi degli strumenti;
• hash ciascuna regione separatamente;
• allegare controlli cache laddove un provider li supporta;
• preservare la semantica dei prompt spostando successivamente il materiale volatile;
• modello di registrazione e prefisso impronte digitali per la diagnostica.

Per le applicazioni legacy che inviano solo messaggi non elaborati, il gateway può comunque fornire una modalità lint: ispezionare l'ordine dei messaggi, calcolare le impronte digitali del prefisso e segnalare probabili interruzioni della cache senza riscrivere inizialmente il prompt.

Livello adattatore provider: normalizza l'utilizzo della cache senza nascondere le differenze

Un gateway multimodello non deve esporre agli sviluppatori tre report cache non correlati. Inoltre, non dovrebbe appiattire gli aspetti economici specifici del fornitore in modo così aggressivo da rendere le fatture impossibili da spiegare.

Crea un registro cache normalizzato con campi come:

{
  "request_id": "req_abc",
  "tenant_id": "tenant_123",
  "app_id": "codice-agente",
  "route": "codifica-contesto-lungo",
  "fornitore": "nome_fornitore",
  "modello": "id_modello",
  "template_id": "code-agent-v3",
  "stable_prefix_hash": "sha256:...",
  "semi_stable_hash": "sha256:...",
  "input_tokens_total": 58200,
  "input_tokens_uncached": 8200,
  "cache_write_tokens": 50000,
  "cache_read_tokens": 0,
  "output_tokens": 1300,
  "cache_ttl_class": "effimero_5m",
  "provider_cache_fields": {
    "raw_field_names": "stored_or_redacted_provider_usage"
  }
}

L'adattatore mappa l'utilizzo del provider in categorie normalizzate:

• Token di input non memorizzati nella cache: token elaborati senza sconto per la lettura della cache o contabilità per la lettura della cache.
• Token di scrittura nella cache: token che hanno creato o aggiornato una voce della cache lato provider quando il provider segnala questa distinzione.
• Token di lettura della cache: token serviti dalla cache o conteggiati come memorizzati nella cache dai metadati di utilizzo del provider.
• Token di output: token generati, che dovrebbero rimanere separati dall'economia della cache immediata.
• Opzione TTL: la classe di durata della cache selezionata in cui un provider espone una scelta.

Raccomandazione: archivia l'utilizzo non elaborato del provider in un formato redatto e con versione dello schema insieme ai campi normalizzati. La normalizzazione è utile per i dashboard; i campi grezzi sono necessari per la riconciliazione quando cambia la semantica del provider.

Osservabilità della cache: dashboard che spiegano gli errori

Un utile dashboard della cache fa molto di più che mostrare il totale dei token memorizzati nella cache. Dovrebbe aiutare i team a rispondere: "Quale carico di lavoro sta violando il prefisso e cosa è cambiato?"

Tieni traccia delle metriche della cache tramite:

• inquilino;
• area di lavoro o app;
• percorso modello;
• fornitore e modello;
• versione modello prompt;
• hash del prefisso stabile;
• hash di contesto semi-stabile;
• Chiave API o account di servizio, se appropriato;
• finestra temporale, soprattutto perché i TTL della cache sono brevi per molti carichi di lavoro.

Le metriche derivate utili includono:

• Frequenza di lettura della cache: token di input memorizzati nella cache divisi per il totale dei token di input idonei per la memorizzazione nella cache.
• Churn del prefisso: numero di hash del prefisso stabile distinti per versione del modello all'ora.
• Deriva del modello: modifiche all'hit della cache dopo il rilascio di un modello.
• Costo di avvio a freddo: spesa per scrittura nella cache o input non nella cache per la prima richiesta in un burst.
• Confronto dei percorsi: tassi di successo tra i percorsi del fornitore per lo stesso carico di lavoro logico.

Non archiviare per impostazione predefinita i prompt grezzi per il debug. Preferisci hash, lunghezze delle regioni, ID modello, avvisi di canonicalizzazione e differenze redatte. Se un team necessita di un debug più approfondito, richiedi controlli di accesso e limiti di conservazione espliciti.

Politica di isolamento del tenant: non progettare per il riutilizzo tra tenant

Il presupposto del gateway più sicuro è semplice: il comportamento memorizzabile nella cache dovrebbe avere un ambito tenant. Anche se due tenant condividono un identico blocco di policy pubbliche, il gateway non deve instradare o modellare intenzionalmente il traffico per sfruttare il riutilizzo della cache tra tenant.

Una politica conservatrice include:

• Routing tenant-aware: instrada il traffico memorizzabile nella cache utilizzando i limiti del tenant, dell'area di lavoro e dell'applicazione.
• Nessun prefisso contenente segreti condivisi: non inserire mai segreti, credenziali, documenti privati o dati specifici dell'utente del tenant in un prefisso condiviso riutilizzabile.
• Impronte digitali del prefisso separate: calcola le impronte digitali con l'ambito del tenant incluso nel registro del gateway, anche se il testo visualizzato è identico.
• Controlli a livello di organizzazione: consentono agli amministratori di disabilitare le funzionalità della cache del provider per carichi di lavoro sensibili.
• L'isolamento del provider non è una funzionalità del prodotto da rivendere: tratta l'isolamento della cache del provider come una protezione di base, non come un'autorizzazione per creare pool di cache tra clienti.

Previsione: man mano che gli agenti a contesto lungo diventano più comuni, il comportamento della cache diventerà parte delle revisioni della sicurezza, non solo delle revisioni dei costi. I gateway in grado di dimostrare la policy della cache con ambito tenant saranno più facili da governare.

Attribuzione della fatturazione: letture, scritture e token normali separati della cache

La memorizzazione tempestiva nella cache può rendere più difficile la comprensione delle fatture se tutti i token di input vengono visualizzati come un unico numero. Il registro di fatturazione dovrebbe preservare almeno cinque categorie:

1. token di input non memorizzati nella cache;
2. Memorizza nella cache i token di scrittura;
3. gettone di lettura nella cache;
4. token di output;
5. Costi TTL specifici del provider o per il controllo della cache.

Ciò è importante quando un provider sconta le letture nella cache, un altro addebita in modo diverso le scritture nella cache e un altro espone un'opzione TTL più lunga. Una fattura cliente dovrebbe essere in grado di spiegare perché due richieste con token di input totali simili avevano costi diversi.

Per il chargeback interno, attribuire gli effetti della cache al tenant e all'applicazione che ha effettuato la richiesta. Evitare di allocare un vantaggio di lettura della cache da un tenant a un altro. Se un team della piattaforma interna condivisa possiede il modello di richiesta stabile, segnala le prestazioni della cache a livello di modello separatamente dalle fatture del tenant.

Elenco di controllo per il linting della cache

Prima di abilitare l'imposizione della cache, esegui i modelli di prompt tramite un elenco di controllo dei lanugine:

• Le istruzioni di sistema stabili vengono visualizzate prima dell'input volatile dell'utente.
• Gli schemi degli strumenti sono ordinati per ID o nome stabile.
• JSON viene serializzato in modo deterministico.
• Nel prefisso stabile non vengono visualizzati timestamp, ID casuali, ID di richiesta o ID di traccia.
• Nessun segreto specifico dell'utente viene visualizzato nei blocchi riutilizzabili condivisi.
• Gli snippet RAG vengono inseriti dopo le sezioni di policy e strumenti riutilizzabili, a meno che non vi sia un motivo deliberato per non farlo.
• I modelli di prompt hanno versioni esplicite.
• I rilasci dei modelli possono essere correlati alle modifiche del tasso di successo della cache.
• I controlli della cache del provider vengono utilizzati solo tramite il codice dell'adattatore, non la logica dell'applicazione sparsa.
• La registrazione dei prompt non elaborati è disabilitata per impostazione predefinita o protetta da rigide regole di conservazione e accesso.

Piano di implementazione

1. Osservare prima di modificare le istruzioni

Inizia raccogliendo i campi di utilizzo del provider e i parametri della cache normalizzati per il traffico esistente. Calcola le impronte digitali del prefisso per i primi N token o per le aree prompt definite dal gateway. L'obiettivo è trovare percorsi ad alto volume e con contesto lungo con un elevato tasso di abbandono del prefisso.

2. Classificare i carichi di lavoro

Raggruppa il traffico in categorie: sessioni agente, assistenti di codifica, RAG, automazione del supporto, analisi dei documenti, lavori batch e brevi chat. Il lavoro della cache tempestiva in genere presta maggiore attenzione ai carichi di lavoro con contesto lungo e prefissi ripetuti. Brevi richieste al di sotto delle soglie del fornitore potrebbero non apportare benefici.

3. Introdurre i builder con prefisso stabile

Sposta un carico di lavoro dalla costruzione di prompt grezzi all'assemblaggio basato su regione. Mantieni la richiesta del provider renderizzata semanticamente equivalente. Non combinare questa modifica con la migrazione del modello, la riprogettazione degli strumenti o importanti riscritture dei prompt, altrimenti non saprai cosa ha causato le modifiche alle metriche.

4. Canarie una rotta

Abilita i controlli della cache per una piccola parte di un tenant o di un'app interna. Confronta la velocità di lettura della cache, la varianza del prefisso, il tempo necessario al primo token, la percentuale di errore e le categorie di costo. Evita di richiedere risparmi finché le fatture del fornitore non si riconciliano con i registri del gateway.

5. Applicare gradualmente

Dopo il canary, trasforma gli avvisi di lanugine in controlli delle policy. Ad esempio, avvisa inizialmente in caso di ordine degli strumenti instabile, quindi rifiuta le nuove versioni del modello che includono metadati volatili nel prefisso stabile.

Compromessi

• Percentuale di riscontri nella cache più elevata rispetto alla flessibilità dei prompt: i prefissi stabili migliorano il riutilizzo, ma i team potrebbero dover spostare le istruzioni dinamiche in un secondo momento o riprogettare i modelli.
• Memoria nella cache nativa del provider e portabilità: l'utilizzo dei controlli della cache di ciascun provider può migliorare i costi, ma le soglie, i TTL, i campi e la semantica dei prezzi differiscono.
• Osservabilità e registrazione sensibile: le differenze dei prompt aiutano a eseguire il debug degli errori, ma gli hash e la diagnostica redatta sono valori predefiniti più sicuri.
• Isolamento del tenant rispetto al massimo riutilizzo: un ampio riutilizzo può sembrare attraente, ma il comportamento nell'ambito del tenant è più sicuro e più facile da spiegare.
• Conservazione più lunga rispetto a costi e complessità delle policy: opzioni TTL più lunghe possono aiutare le sessioni degli agenti, ma possono introdurre considerazioni diverse sui prezzi e sul controllo dei dati.

Conclusione attuabile

Tratta la memorizzazione nella cache dei prompt come un problema del piano di controllo del gateway, non come una casella di controllo del provider. Lo schema pratico è: definire regioni prompt stabili, semi-stabili e volatili; renderli deterministicamente; adattare i controlli della cache specifici del provider dietro un'unica interfaccia; normalizzare l'utilizzo della cache in un registro; esporre la diagnostica degli accessi alla cache per tenant, app, route e versione del modello; e applicare ipotesi relative all'ambito del tenant.

Il primo passo utile non è una riscrittura. Aggiungi l'osservabilità della cache ai tuoi prompt più lunghi, identifica l'abbandono del prefisso e filtra i modelli che causano il maggior numero di errori. Dopo aver spiegato il comportamento della cache, puoi ottimizzarla in sicurezza.

Leggi correlati

• crea categorie compatibili con la cache nel registro di fatturazione
• unisci le metriche della cache con l'osservabilità LLM sicura
• mantieni contesto di recupero con ambito tenant nei carichi di lavoro RAG