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-brekende prompt-assemblage

Prompt-caching beloont over het algemeen herhaalde prompt-voorvoegsels. Het exacte mechanisme verschilt per aanbieder, 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, machtigingen of privévoorkeuren geplaatst vóór herbruikbare beleids- of toolblokkeringen.
• Onstabiele serialisatie van tools: toolschema's die in niet-deterministische volgorde worden 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 promptcaching 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 tot 10 minuten inactiviteit worden gewist en altijd binnen een uur na het laatste gebruik van de cache worden verwijderd.
• Antropisch: Antropische 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 tokentellingen in de cache zichtbaar via metagegevens over gebruik, zoals total_cached_tokens, en de bijbehorende documentatie vermeldt het minimale aantal invoertokens per model.
• Implicatie van gegevenscontrole: OpenAI's documentatie over API-gegevenscontrole merkt op dat uitgebreide promptcaching vereist dat sleutel/waarde-tensors worden opgeslagen als applicatiestatus in GPU-lokale 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 gateway-functie met expliciet beleid, niet als een toevallig neveneffect van herhaalde prompts.

Een contract voor snelle montage in 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;
• toolschema's;
• statische productdocumentatie;
• repositorykaarten voor codeeragenten;
• vaste instructies voor het 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 zich richten op de grens van een tenant, werkruimte of applicatie. 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;
• kortetermijngesprekken veranderen;
• runtime-toolresultaten.

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 applicatie te accepteren.

{
  "template_id": "code-agent-v3",
  "tenant_id": "tenant_123",
  "route": "codering-lange-context",
  "stable_prefix": {
    "system_policy_version": "2026-08-01",
    "toolset_version": "tools-v12",
    "repo_context_version": "repo-map-8491"
  },
  "semi_stabiele_context": {
    "workspace_policy_version": "werkruimte-44-v6"
  },
  "vluchtig_achtervoegsel": {
    "user_message": "Leg uit waarom deze test mislukt...",
    "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;
• cachecontroles toevoegen waar een provider deze ondersteunt;
• de prompt-semantiek behouden terwijl vluchtig materiaal later wordt verplaatst;
• sjabloon en prefix-vingerafdrukken vastleggen voor diagnostiek.

Voor oudere toepassingen 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 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": "codeagent",
  "route": "codering-lange-context",
  "provider": "provider_naam",
  "model": "model_id",
  "template_id": "code-agent-v3",
  "stable_prefix_hash": "sha256:...",
  "semi_stable_hash": "sha256:...",
  "input_tokens_totaal": 58200,
  "input_tokens_uncached": 8200,
  "cache_write_tokens": 50000,
  "cache_read_tokens": 0,
  "output_tokens": 1300,
  "cache_ttl_class": "efemere_5m",
  "provider_cache_fields": {
    "raw_field_names": "opgeslagen_of_geredacteerde_provider_usage"
  }

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

• Niet-gecachte 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 cache: tokens die vanuit de cache worden aangeboden of als in de cache worden geteld door metagegevens over het gebruik van de provider.
• Uitvoertokens: gegenereerde tokens, die gescheiden moeten blijven van de prompt-cache-economie.
• TTL-optie: de geselecteerde cacheduurklasse waarbij een provider een keuze biedt.

Aanbeveling: sla onbewerkt 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.

Cachewaarneming: dashboards die missers verklaren

Een handig cachedashboard doet meer dan het totaal aantal in de cache opgeslagen tokens weergeven. Het zou teams moeten helpen antwoorden: “Welke werklast overtreedt het voorvoegsel, en wat is er veranderd?”

Houd cachestatistieken bij door:

• huurder;
• werkruimte of app;
• modelroute;
• aanbieder en model;
• prompt sjabloonversie;
• stabiele voorvoegsel-hash;
• semi-stabiele context-hash;
• API-sleutel of serviceaccount, indien van toepassing;
• tijdvenster, vooral omdat cache-TTL's kort zijn voor veel werkbelastingen.

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 de cachehit na een sjabloonrelease.
• Kosten bij koude start: uitgaven voor schrijven in cache 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 eenvoudig: cachebaar gedrag moet tenantgericht 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 gedeelde voorvoegsels die geheimen bevatten: 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 gateway-grootboek, zelfs als de weergegeven tekst identiek is.
• Besturingselementen op organisatieniveau: stellen beheerders in staat cachefuncties van providers uit te schakelen voor gevoelige productietaken.
• Provider-isolatie is geen productfunctie die u kunt doorverkopen: 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.

Factureringsattributie: 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 cachecontrolekosten.

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

Voor interne terugboekingen wijst u cache-effecten toe aan de tenant en de toepassing die het verzoek hebben 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 cache-hit-rate.
• Cachebesturingselementen van de provider worden alleen gebruikt via adaptercode, niet via verspreide applicatielogica.
• Het loggen 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 werklasten

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 belangrijke 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 rekeningen van de provider overeenkomen met de grootboeken van de gateway.

5. Geleidelijk handhaven

Verander lintwaarschuwingen 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 versus draagbaarheid: het gebruik van de cache-instellingen 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.
• Isolatie van huurders versus maximaal hergebruik: breed hergebruik lijkt misschien aantrekkelijk, maar gedrag op huurderniveau is veiliger en gemakkelijker uit te leggen.
• Langere retentie versus kosten en complexiteit van beleid: langere TTL-opties kunnen agentsessies helpen, maar kunnen andere overwegingen met zich meebrengen op het gebied van prijzen en gegevensbeheer.

Bruikbare conclusie

Behandel promptcaching als een probleem met het gateway-besturingsvlak, en niet als een selectievakje voor de 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 aannames op tenantniveau 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.

Gerelateerd informatie

• cachebewuste categorieën inbouwen in het factureringsgrootboek
• voeg cachestatistieken toe met veilige LLM-observeerbaarheid
• behoud de ophaalcontext tenantgericht in RAG-workloads