Prompt cachebeheer in een multi-model API-gateway: stabiele voorvoegsels, tenant-isolatie en cache-hit-analyse

Snelle caching is gemakkelijk te verspillen. Een team kan een systeemprompt met 40.000 tokens, een toolschema, een beleidsblok, een repositorykaart of een agentgeheugen hebben dat herbruikbaar moet zijn, en vervolgens per ongeluk een tijdstempel, verzoek-ID, gebruikersnaam, ophaalfragment of willekeurige toolvolgorde bovenaan de prompt plaatsen. De provider ziet een ander voorvoegsel, de cache wordt gemist, de latentie neemt toe en de rekening ziet er verwarrend uit.

In een applicatie met één provider kunt u dit oplossen in de applicatiesjabloon. In een gateway met meerdere modellen is het probleem groter: elke provider heeft verschillende cachecontroles, tokendrempels, time-to-live-gedrag, gebruiksvelden en factureringssemantiek. De gateway heeft een draagbaar controlevlakpatroon nodig voor het samenstellen van cache-veilige aanwijzingen, het meten van cachegedrag, het isoleren van tenants en het toekennen van kosten.

Dit artikel beschrijft een referentiearchitectuur. Het is geen klantcasestudy en claimt geen benchmarkresultaten. De onderstaande feiten zijn afkomstig uit documentatie van leveranciers en openbaar onderzoek; de ontwerpaanbevelingen zijn operationele richtlijnen op gatewayniveau.

De foutmodus: cache-breaking prompt assembly

Prompt-caching beloont over het algemeen herhaalde prompt-voorvoegsels. Het exacte mechanisme verschilt per provider, maar de praktische implicatie is consistent: als de voorkant van de prompt verandert, heeft hergebruik daaronder te lijden.

Veel voorkomende cachebrekers zijn:

• Metadata per verzoek bovenaan: tijdstempels, trace-ID's, sessie-ID's, implementatie-ID's of gegenereerde verzoeklabels.
• Gebruikerspecifieke gegevens in het voorvoegsel: namen, accountkenmerken, rechten of privévoorkeuren geplaatst vóór herbruikbare beleids- of toolblokken.
• Onstabiele gereedschapsserialisatie: gereedschapsschema's worden in niet-deterministische volgorde verzonden, met veranderende witruimte of gegenereerde ID's.
• Fragmenten te vroeg opgehaald: RAG-context ingevoegd vóór stabiele systeeminstructies of gedeelde opslagplaatscontext.
• Sjabloonafwijking: kleine wijzigingen in de formulering worden regelmatig vrijgegeven zonder versiebeheer of cachediagnostiek.

Een gateway kan een onstabiel voorvoegsel niet op magische wijze cachebaar maken, maar kan wel een prompt-assemblagecontract afdwingen en cache-missers zichtbaar maken.

Feiten van aanbieders om rond te ontwerpen

De details zijn belangrijk omdat een gateway het gedrag moet normaliseren zonder te doen alsof providers identiek zijn.

• OpenAI: OpenAI heeft het cachen van prompts gedocumenteerd voor het langste eerder berekende promptvoorvoegsel. Het begint bij 1.024 tokens, neemt toe in stappen van 128 tokens en geeft het aantal tokens in de cache weer in gebruiksvelden. OpenAI stelt ook dat promptcaches doorgaans na 5-10 minuten inactiviteit worden gewist en altijd binnen een uur na het laatste gebruik van de cache worden verwijderd.
• Anthropic: Anthropic promptcaching kan worden aangevraagd met cache_control. De documentatie beschrijft cachematching via promptcomponenten zoals tools, systeeminhoud en berichten tot aan het blok gemarkeerd met cachecontrole. Anthropic documenteert een kortstondige cache, inclusief een duur van 5 minuten en een optie van 1 uur tegen extra kosten.
• Gemini: Google Gemini contextcaching maakt het aantal cache-hit-tokens zichtbaar via gebruiksmetagegevens zoals total_cached_tokens, en de bijbehorende documentatie vermeldt het minimale aantal invoertokens per model.
• Implicatie van gegevenscontrole: OpenAI's API documentatie over gegevenscontrole merkt op dat uitgebreide promptcaching vereist dat sleutel/waarde-tensors worden opgeslagen als applicatiestatus in lokale GPU-opslag. Zelfs als providers isolatiegaranties handhaven, moeten gateways cachegedrag behandelen als een gevoelige infrastructuur, en niet als een gedeelde applicatiedatastore.
• Onderzoekssignaal: Openbaar onderzoek heeft onderzocht of gateway-achtige architecturen kwetsbaarheden in prompt-caching kunnen introduceren die aannames op cache-isolatie op providerniveau omzeilen. Dat bewijst niet dat een specifieke gateway kwetsbaar is, maar ondersteunt wel een conservatief ontwerp voor huurderisolatie.

Aanbeveling: implementeer cachebeheer als een gatewayfunctie met expliciet beleid, niet als een toevallig neveneffect van herhaalde aanwijzingen.

Een contract voor snelle montage voor drie regio's

De belangrijkste ontwerpbeslissing is het scheiden van stabiele en vluchtige inhoud voordat het verzoek een provideradapter bereikt.

Regio 1: stabiel voorvoegsel

Het stabiele voorvoegsel is de inhoud die naar verwachting identiek blijft bij veel verzoeken voor dezelfde applicatie, modelroute en promptsjabloonversie. Voorbeelden hiervan zijn:

• kernsysteeminstructies;
• veiligheids- en beleidsblokkeringen;
• gereedschapsschema's;
• statische productdocumentatie;
• opslagplaatskaarten voor codeeragenten;
• instructies met vast uitvoerformaat.

Deze regio moet deterministisch zijn. De gateway moet deze opbouwen op basis van versiebeheersjablonen, gecanoniseerde JSON en stabiele bestelregels. Als er een gereedschapsregister is opgenomen, sorteert u de gereedschappen op stabiele gereedschaps-ID. Als JSON schema's zijn opgenomen, serialiseer ze dan met een deterministische sleutelvolgorde en zonder gegenereerde tijdstempels.

Regio 2: semi-stabiele tenant- of werkruimtecontext

De semi-stabiele regio verandert minder vaak dan individuele verzoeken, maar wordt niet wereldwijd gedeeld. Voorbeelden hiervan zijn:

• tenantspecifieke beleidsoverschrijvingen;
• Toelatingslijsten voor tools op werkruimteniveau;
• klantspecifieke terminologie;
• teamcoderingsconventies;
• langlevende projectcontext.

Deze regio moet worden beperkt tot een tenant, werkruimte of applicatiegrens. Het kan nog steeds cachebaar zijn, maar de gateway mag er nooit van uitgaan dat een andere tenant het veilig kan hergebruiken.

Regio 3: vluchtig achtervoegsel

Het vluchtige achtervoegsel is het gedeelte per verzoek:

• gebruikersbericht;
• fragmenten opgehaald voor deze zoekopdracht;
• huidige tijdstempel, indien echt nodig;
• vraag ID aan en traceer metagegevens, als deze überhaupt in de prompt zijn opgenomen;
• korte gesprekken krijgen een wending;
• resultaten van de runtimetool.

De meeste cachefouten veroorzaakt door het ontwerp van applicaties gebeuren omdat vluchtige achtervoegselgegevens per ongeluk in het voorvoegsel worden geplaatst. Een gateway-side builder zou dat moeilijk moeten maken.

Implementatiepatroon: bouwers met stabiele voorvoegsels

Een praktische gateway-implementatie kan een promptassemblage-interface blootleggen in plaats van één ondoorzichtige promptstring van elke toepassing te accepteren.

{
  "template_id": "code-agent-v3",
  "tenant_id": "tenant_123",
  "route": "coding-long-context",
  "stable_prefix": {
    "system_policy_version": "2026-08-01",
    "toolset_version": "tools-v12",
    "repo_context_version": "repo-map-8491"
  },
  "semi_stable_context": {
    "workspace_policy_version": "workspace-44-v6"
  },
  "volatile_suffix": {
    "user_message": "Explain why this test fails...",
    "retrieval_context_ids": ["chunk_7", "chunk_19"],
    "trace_id": "not_inserted_into_prompt"
  }
}

De gateway geeft vervolgens het providerspecifieke verzoek weer. Dit geeft de gateway een plek om regels af te dwingen:

• tijdstempels in stabiele voorvoegselvelden weigeren;
• toolschema's canoniseren;
• hash elke regio afzonderlijk;
• voeg cachecontroles toe waar een provider deze ondersteunt;
• behoud de semantiek van de prompt terwijl vluchtig materiaal later wordt verplaatst;
• registratiesjabloon en vingerafdrukken voor prefix voor diagnostiek.

Voor oudere applicaties die alleen onbewerkte berichten verzenden, kan de gateway nog steeds een lintmodus bieden: de berichtvolgorde inspecteren, prefix-vingerafdrukken berekenen en waarschijnlijke cache-onderbrekers rapporteren zonder de prompt in eerste instantie te herschrijven.

Provider-adapterlaag: normaliseer het cachegebruik zonder de verschillen te verbergen

Een gateway met meerdere modellen mag geen drie niet-gerelateerde cacherapporten aan ontwikkelaars tonen. Het mag ook de aanbiederspecifieke economie niet zo agressief afvlakken dat facturen onmogelijk uit te leggen zijn.

Maak een genormaliseerd cachegrootboek met velden zoals:

{
  "request_id": "req_abc",
  "tenant_id": "tenant_123",
  "app_id": "code-agent",
  "route": "coding-long-context",
  "provider": "provider_name",
  "model": "model_id",
  "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": "ephemeral_5m",
  "provider_cache_fields": {
    "raw_field_names": "stored_or_redacted_provider_usage"
  }
}

De adapter brengt het providergebruik in genormaliseerde categorieën in kaart:

• Niet in de cache opgeslagen invoertokens: tokens verwerkt zonder cache-leeskorting of cache-read-accounting.
• Cache-schrijftokens: tokens die een cache-item aan de providerzijde hebben gemaakt of vernieuwd wanneer de provider dit onderscheid rapporteert.
• Leestokens in cachegeheugen: tokens geleverd vanuit het cachegeheugen of geteld als in het cachegeheugen opgeslagen door metagegevens over het gebruik van de provider.
• Uitvoertokens: gegenereerde tokens, die gescheiden moeten blijven van de promptcache-economie.
• TTL-optie: de geselecteerde cacheduurklasse waarbij een provider een keuze biedt.

Aanbeveling: sla het onbewerkte providergebruik op in een geredigeerde vorm met een schemaversie naast genormaliseerde velden. Normalisatie is handig voor dashboards; onbewerkte velden zijn nodig voor afstemming wanneer de semantiek van de provider verandert.

Waarneembaarheid van cache: dashboards die missers verklaren

Een handig cachedashboard doet meer dan alleen het totaal aantal in de cache opgeslagen tokens weergeven. Het zou teams moeten helpen de volgende vraag te beantwoorden: 'Welke werklast overtreedt het voorvoegsel, en wat is er veranderd?'

Cachestatistieken bijhouden op:

• huurder;
• werkruimte of app;
• modelroute;
• aanbieder en model;
• promptsjabloonversie;
• stabiele voorvoegsel-hash;
• semi-stabiele contexthash;
• API sleutel of serviceaccount, indien van toepassing;
• tijdsperiode, vooral omdat cache-TTL's voor veel productietaken kort zijn.

Nuttige afgeleide statistieken zijn onder meer:

• Cache-leessnelheid: in de cache opgeslagen invoertokens gedeeld door het totale aantal invoertokens dat in aanmerking komt voor caching.
• Voorvoegselverloop: aantal verschillende stabiele voorvoegsel-hashes per sjabloonversie per uur.
• Sjabloonafwijking: wijzigingen in cachehit na release van een sjabloon.
• Kosten bij koude start: uitgaven voor cacheschrijven of niet-gecachte invoer voor het eerste verzoek in een burst.
• Routevergelijking: hitpercentages op verschillende providerroutes voor dezelfde logische werklast.

Sla niet standaard onbewerkte aanwijzingen op voor foutopsporing. Geef de voorkeur aan hashes, regiolengtes, sjabloon-ID's, canonicalisatiewaarschuwingen en geredigeerde diffs. Als een team diepere foutopsporing nodig heeft, eis dan expliciete toegangscontroles en bewaarlimieten.

Tenantisolatiebeleid: ontwerp niet voor hergebruik tussen tenants

De veiligste gateway-aanname is simpel: cachebaar gedrag moet op de tenant gericht zijn. Zelfs als twee tenants een identiek openbaar beleidsblok delen, mag de gateway niet opzettelijk verkeer routeren of vormgeven om hergebruik van de cache tussen tenants te misbruiken.

Een conservatief beleid omvat:

• Tenantbewuste routering: routeer cachebaar verkeer met behulp van tenant-, werkruimte- en applicatiegrenzen.
• Geen voorvoegsels met gedeelde geheimen: plaats nooit huurdergeheimen, inloggegevens, privédocumenten of gebruikersspecifieke gegevens in een herbruikbaar gedeeld voorvoegsel.
• Afzonderlijke prefix-vingerafdrukken: bereken vingerafdrukken met het tenantbereik opgenomen in het gatewaygrootboek, zelfs als de weergegeven tekst identiek is.
• Beheerders op organisatieniveau: stellen beheerders in staat cachefuncties van de provider uit te schakelen voor gevoelige productietaken.
• Isolatie van providers is geen productfunctie om door te verkopen: behandel cache-isolatie van providers als een basisbescherming, niet als toestemming om cachepooling voor meerdere klanten te bouwen.

Voorspelling: Naarmate agenten met een lange context steeds gebruikelijker worden, zal cachegedrag onderdeel worden van beveiligingsbeoordelingen, en niet alleen van kostenbeoordelingen. Gateways die een cachebeleid op tenantniveau kunnen bewijzen, zullen gemakkelijker te beheren zijn.

Factureringstoeschrijving: aparte cache-lees-, schrijf- en normale tokens

Snelle caching kan ervoor zorgen dat facturen moeilijker te begrijpen zijn als alle invoertokens als één getal worden weergegeven. Het factureringsgrootboek moet ten minste vijf categorieën behouden:

1. niet-gecachte invoertokens;
2. Schrijftokens in de cache opslaan;
3. leestokens in de cache opslaan;
4. uitvoertokens;
5. providerspecifieke TTL- of cachebeheerkosten.

Dit is van belang wanneer de ene provider korting geeft op in de cache opgeslagen leesbewerkingen, een andere provider andere kosten in rekening brengt voor cacheschrijfbewerkingen en een andere een langere TTL-optie aanbiedt. Een klantfactuur zou moeten kunnen uitleggen waarom twee verzoeken met vergelijkbare totale invoertokens verschillende kosten hadden.

Voor interne terugvordering schrijft u cache-effecten toe aan de tenant en applicatie die het verzoek heeft ingediend. Vermijd het toewijzen van een cache-lees voordeel van de ene tenant aan de andere. Als een gedeeld intern platformteam eigenaar is van de stabiele promptsjabloon, rapporteer dan de cacheprestaties op sjabloonniveau afzonderlijk van de huurderfacturen.

Checklist voor cache-linting

Voordat u cache-afdwinging inschakelt, voert u promptsjablonen uit via een lintchecklist:

• Stabiele systeeminstructies verschijnen vóór vluchtige gebruikersinvoer.
• Toolschema's worden gesorteerd op stabiele ID of naam.
• JSON is deterministisch geserialiseerd.
• Er verschijnen geen tijdstempels, willekeurige ID's, verzoek-ID's of trace-ID's in het stabiele voorvoegsel.
• Er verschijnen geen gebruikersspecifieke geheimen in gedeelde herbruikbare blokken.
• RAG-fragmenten worden na herbruikbare beleids- en toolsecties geplaatst, tenzij er een opzettelijke reden is om dit niet te doen.
• Promptsjablonen hebben expliciete versies.
• Sjabloonreleases kunnen worden gecorreleerd met wijzigingen in de cachehitrate.
• Cachebesturingselementen van de provider worden alleen gebruikt via adaptercode, niet via verspreide applicatielogica.
• Het vastleggen van onbewerkte prompts is standaard uitgeschakeld of wordt beschermd door strikte bewaar- en toegangsregels.

Uitrolplan

1. Observeer voordat u de aanwijzingen wijzigt

Begin met het verzamelen van providergebruiksvelden en genormaliseerde cachestatistieken voor bestaand verkeer. Bereken prefix-vingerafdrukken voor de eerste N-tokens of voor door de gateway gedefinieerde promptregio's. Het doel is om routes met een hoog volume en een lange context te vinden met een hoog voorvoegselverloop.

2. Classificeer productietaken

Groepeer verkeer in categorieën: agentsessies, codeerassistenten, RAG, ondersteuningsautomatisering, documentanalyse, batchtaken en korte chat. Bij snel cachewerk wordt meestal de meeste aandacht besteed aan werkbelastingen met een lange context en herhaalde voorvoegsels. Korte prompts onder de providerdrempels hebben mogelijk geen voordeel.

3. Introduceer stabiele voorvoegselbouwers

Verplaats één werklast van onbewerkte promptconstructie naar regiogebaseerde assemblage. Houd het weergegeven providerverzoek semantisch gelijkwaardig. Combineer deze wijziging niet met modelmigratie, het opnieuw ontwerpen van tools of het herschrijven van grote prompts, anders weet u niet wat de statistische wijzigingen heeft veroorzaakt.

4. Canarische route

Schakel cachebeheer in voor een klein deel van één tenant of interne app. Vergelijk het leespercentage in de cache, het verloop van het voorvoegsel, de tijd tot het eerste token, het foutenpercentage en de kostencategorieën. Vermijd het claimen van besparingen totdat de facturen van de provider overeenkomen met de gateway-grootboeken.

5. Geleidelijk afdwingen

Verander pluiswaarschuwingen na de kanarie in beleidscontroles. Waarschuw bijvoorbeeld eerst voor een onstabiele toolvolgorde en wijs vervolgens nieuwe sjabloonversies af die vluchtige metadata in het stabiele voorvoegsel bevatten.

Afwegingen

• Hoger cachetrefferpercentage versus promptflexibiliteit: stabiele voorvoegsels verbeteren hergebruik, maar teams moeten mogelijk later dynamische instructies verplaatsen of sjablonen opnieuw ontwerpen.
• Provider-native caching vs. draagbaarheid: het gebruik van de cachecontroles van elke provider kan de economie verbeteren, maar drempels, TTL's, velden en prijssemantiek verschillen.
• Waarneembaarheid vs. gevoelige logboekregistratie: prompt-diffs helpen fouten op te sporen, maar hashes en geredigeerde diagnostische gegevens zijn veiligere standaardwaarden.
• Tenantisolatie versus maximaal hergebruik: breed hergebruik ziet er misschien aantrekkelijk uit, maar gedrag op tenantniveau is veiliger en gemakkelijker uit te leggen.
• Langere retentie vs. kosten en complexiteit van beleid: langere TTL-opties kunnen agentsessies helpen, maar kunnen verschillende prijs- en gegevenscontroleoverwegingen met zich meebrengen.

Conclusie waar actie op ondernomen kan worden

Behandel promptcaching als een gateway-controlevlakprobleem, en niet als een selectievakje van een provider. Het praktische patroon is: definieer stabiele, semi-stabiele en vluchtige promptgebieden; geef ze deterministisch weer; providerspecifieke cachecontroles achter één interface aanpassen; normaliseer het cachegebruik in een grootboek; diagnostiek van cachehits blootleggen per tenant, app, route en sjabloonversie; en op tenants gerichte aannames afdwingen.

De eerste nuttige stap is niet herschrijven. Voeg cache-waarneembaarheid toe aan uw langste aanwijzingen, identificeer voorvoegselverloop en lint de sjablonen die de meeste fouten veroorzaken. Zodra u het cachegedrag kunt uitleggen, kunt u het veilig optimaliseren.

Gerelateerde informatie

• Cachebewuste categorieën inbouwen in het factureringsgrootboek
• Cachestatistieken samenvoegen met veilige LLM-observatie
• behouden ophaalcontext tenantgericht in RAG-productietaken