Fråga cachekontroll i en API-gateway för flera modeller: stabila prefix, isolering av hyresgäster och analys av cacheträff

Prompt cachelagring är lätt att slösa. Ett team kan ha en systemprompt på 40 000 token, verktygsschema, policyblock, arkivkarta eller agentminne som ska kunna återanvändas, och sedan av misstag lägga en tidsstämpel, begäran-ID, användarnamn, hämtningskodavsnitt eller slumpmässig ordning av verktyg nära toppen av prompten. Leverantören ser ett annat prefix, cachen missas, latensen ökar och räkningen ser förvirrande ut.

I en applikation med en leverantör kan du fixa detta i applikationsmallen. I en multi-modell gateway är problemet större: varje leverantör exponerar olika cachekontroller, token-trösklar, time-to-live-beteende, användningsfält och faktureringssemantik. Gatewayen behöver ett bärbart kontrollplansmönster för att sammanställa cachesäkra prompter, mäta cachebeteende, isolera hyresgäster och tillskriva kostnader.

Den här artikeln beskriver en referensarkitektur. Det är inte en kundfallsstudie och gör inte anspråk på benchmarkresultat. Fakta nedan kommer från leverantörsdokumentation och offentlig forskning; designrekommendationerna är driftvägledning på gatewaynivå.

Felläget: cachebrytande promptsammansättning

Caching av prompt belönar i allmänhet upprepade promptprefix. Den exakta mekaniken varierar beroende på leverantör, men den praktiska innebörden är konsekvent: om fronten på prompten ändras blir återanvändningen lidande.

Vanliga cachebrytare inkluderar:

• Metadata per begäran högst upp: tidsstämplar, spårnings-ID:n, sessions-ID:n, distributions-ID:n eller genererade begärandeetiketter.
• Användarspecifik data i prefixet: namn, kontoattribut, behörigheter eller privata inställningar placerade före återanvändbara policyer eller verktygsblock.
• Instabil verktygsserialisering: verktygsscheman sänds ut i icke-deterministisk ordning, med skiftande blanksteg eller genererade ID:n.
• Hämtning av kodavsnitt för tidigt: RAG-kontext infogat före stabila systeminstruktioner eller delad lagringskontext.
• Mallavvikelse: små formuleringsändringar släpps ofta utan versions- eller cachediagnostik.

En gateway kan inte på ett magiskt sätt göra ett instabilt prefix cachebart, men det kan genomdriva ett snabbt monteringskontrakt och göra cachemissar synliga.

Fakta om leverantörer att utforma kring

Detaljen spelar roll eftersom en gateway måste normalisera beteendet utan att låtsas att leverantörerna är identiska.

• OpenAI: OpenAI har dokumenterad promptcache för det längsta tidigare beräknade promptprefixet. Den börjar vid 1 024 tokens, ökar i steg om 128 tokens och exponerar cachade token-antal i användningsfält. OpenAI anger också att promptcacheminne vanligtvis rensas efter 5–10 minuters inaktivitet och tas alltid bort inom en timme efter att cachen senast användes.
• Anthropic: Anthropic promptcachelagring kan begäras med cache_control. Dess dokumentation beskriver cachematchning över promptkomponenter som verktyg, systeminnehåll och meddelanden upp till blocket som är markerat med cachekontroll. Anthropic dokumenterar ett tillfälligt cache, inklusive en längd på 5 minuter och ett alternativ på 1 timme mot en extra kostnad.
• Gemini: Google Gemini kontextcachelagring avslöjar antalet cache-hit-token genom användningsmetadata som total_cached_tokens, och dess dokumentation listar minsta antal indatatoken per modell.
• Datakontrollimplikation: OpenAIs API datakontrolldokumentation noterar att utökad promptcache kräver lagring av nyckel/värde-tensorer som applikationstillstånd i GPU-lokal lagring. Även när leverantörer upprätthåller isoleringsgarantier bör gateways behandla cachebeteende som känslig infrastruktur, inte som en delad applikationsdatalagring.
• Forskningssignal: Offentlig forskning har undersökt om arkitekturer i gateway-stil kan introducera prompt-cache-sårbarheter som kringgår antaganden om cacheisolering på leverantörsnivå. Det bevisar inte att en specifik gateway är sårbar, men den stöder konservativ design för hyresgästisolering.

Rekommendation: implementera cachekontroll som en gatewayfunktion med explicita policyer, inte som en oavsiktlig bieffekt av upprepade uppmaningar.

Ett monteringskontrakt med tre regioner

Det viktigaste designbeslutet är att separera stabilt och flyktigt innehåll innan begäran når en leverantörsadapter.

Region 1: stabilt prefix

Det stabila prefixet är innehåll som förväntas förbli identiskt över många förfrågningar för samma applikation, modellväg och version för promptmall. Exempel inkluderar:

• instruktioner för kärnsystemet;
• säkerhets- och policyblockeringar;
• verktygsscheman;
• statisk produktdokumentation;
• lagerkartor för kodningsagenter;
• fixade instruktioner för utdataformat.

Denna region bör vara deterministisk. Gatewayen bör bygga den från versionsbaserade mallar, kanoniserad JSON och stabila ordningsregler. Om ett verktygsregister ingår, sortera verktyg efter stabilt verktygs-ID. Om JSON scheman ingår, serialisera dem med deterministisk nyckelordning och inga genererade tidsstämplar.

Region 2: semi-stabil hyresgäst eller arbetsyta kontext

Den halvstabila regionen ändras mindre ofta än enskilda förfrågningar men delas inte globalt. Exempel inkluderar:

• hyresgästspecifika policyöverskridanden;
• tillståndslistor för verktyg på arbetsytanivå;
• kundspecifik terminologi;
• lagkodningskonventioner;
• långlivat projektsammanhang.

Den här regionen bör omfattas av en klient, arbetsyta eller applikationsgräns. Det kan fortfarande vara cachebart, men gatewayen bör aldrig anta att en annan hyresgäst säkert kan återanvända den.

Region 3: flyktigt suffix

Det flyktiga suffixet är delen per begäran:

• användarmeddelande;
• hämtade utdrag för den här frågan;
• aktuell tidsstämpel, om det verkligen behövs;
• begär ID och spårningsmetadata, om det överhuvudtaget ingår i prompten;
• konversationsvändningar på kort sikt;
• resultat från körtidsverktyg.

De flesta cachemissar orsakade av programdesign inträffar eftersom flyktiga suffixdata av misstag placeras i prefixet. En gateway-side-byggare borde göra det svårt.

Implementeringsmönster: stabila prefixbyggare

En praktisk gateway-implementering kan avslöja ett snabbsammansättningsgränssnitt snarare än att acceptera en ogenomskinlig promptsträng från varje applikation.

{
  "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"
  }
}

Gatewayen återger sedan den leverantörsspecifika begäran. Detta ger gatewayen en plats att upprätthålla regler:

• avvisa tidsstämplar i stabila prefixfält;
• kanonisera verktygsscheman;
• hasha varje region separat;
• attach cache-kontroller där en leverantör stöder dem;
• bevara snabb semantik medan du flyttar flyktigt material senare;
• postmall och prefixfingeravtryck för diagnostik.

För äldre applikationer som bara skickar råmeddelanden kan gatewayen fortfarande tillhandahålla ett lint-läge: inspektera meddelandeordning, beräkna prefixfingeravtryck och rapportera troliga cache-brytare utan att skriva om prompten initialt.

Leverantörsadapterlager: normalisera cacheanvändningen utan att dölja skillnader

En gateway med flera modeller bör inte exponera tre orelaterade cacherapporter för utvecklare. Det bör inte heller försämra leverantörsspecifik ekonomi så aggressivt att fakturor blir omöjliga att förklara.

Skapa en normaliserad cache-reskontra med fält som:

{
  "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"
  }
}

Adaptern mappar leverantörens användning i normaliserade kategorier:

• Ocachade indatatokens: tokens bearbetade utan cacheläsrabatt eller cacheläst redovisning.
• Cache-skrivtokens:-tokens som skapade eller uppdaterade en cachepost på leverantörssidan när leverantören rapporterar denna distinktion.
• Cachelästa tokens: tokens serveras från cacheminnet eller räknas som cachade av leverantörens användningsmetadata.
• Utdatatokens: genererade tokens, som bör förbli åtskilda från promptcacheekonomi.
• TTL-alternativ: den valda cachevaraktigheten där en leverantör avslöjar ett val.

Rekommendation: lagra råleverantörsanvändning i en redigerad form med schemaversion tillsammans med normaliserade fält. Normalisering är användbar för instrumentpaneler; råfält är nödvändiga för avstämning när leverantörens semantik ändras.

Cache observerbarhet: instrumentpaneler som förklarar missar

En användbar cacheöversikt gör mer än att visa totalt cachade tokens. Det borde hjälpa team att svara: "Vilken arbetsbelastning bryter prefixet och vad har förändrats?"

Spåra cachestatistik genom:

• hyresgäst;
• arbetsyta eller app;
• modellrutt;
• leverantör och modell;
• version av promptmall;
• stabil prefix hash;
• halvstabil kontexthash;
• API nyckel eller tjänstkonto, där så är lämpligt;
• tidsfönster, särskilt eftersom cache-TTL:er är korta för många arbetsbelastningar.

Användbara härledda mätvärden inkluderar:

• Cacheläshastighet: cachade indatatoken dividerat med det totala antalet indatatokens som är kvalificerade för cachning.
• Prefix churn: antal distinkta stabila prefixhaschar per mallversion och timme.
• Malldrift: cache-hit ändringar efter en mallsläppning.
• Kallstartskostnad: cache-skrivning eller uncachad inmatningskostnad för den första begäran i en serie.
• Ruttjämförelse: träffar över leverantörsrutter för samma logiska arbetsbelastning.

Lagra inte som standard råuppmaningar för felsökning. Föredrar hash, regionlängder, mall-ID:n, kanoniseringsvarningar och redigerade diffar. Om ett team behöver djupare felsökning krävs explicita åtkomstkontroller och lagringsbegränsningar.

Policy för isolering av hyresgäster: designa inte för återanvändning över flera hyresgäster

Det säkraste antagandet om gateway är enkelt: cachebart beteende bör vara klientomfattande. Även om två hyresgäster delar ett identiskt block av allmän policy, bör gatewayen inte avsiktligt dirigera eller forma trafik för att utnyttja återanvändning av cacheminne för flera klienter.

En konservativ policy inkluderar:

• Tenant-aware routing: dirigera cachebar trafik med hjälp av klient-, arbetsyta- och applikationsgränser.
• Inga delade hemlighetsbärande prefix: placera aldrig hyresgästhemligheter, användaruppgifter, privata dokument eller användarspecifika data i ett återanvändbart delat prefix.
• Separata prefixfingeravtryck: beräkna fingeravtryck med klientomfattning som ingår i gatewayreskontran, även om den renderade texten är identisk.
• Kontroller på organisationsnivå: tillåter administratörer att inaktivera leverantörens cachefunktioner för känsliga arbetsbelastningar.
• Leverantörsisolering är inte en produktfunktion för att sälja vidare: behandla leverantörens cacheisolering som ett baslinjeskydd, inte som tillstånd att bygga cachepoolning över flera kunder.

Prognos: när agenter med långa sammanhang blir vanligare kommer cachebeteende att bli en del av säkerhetsgranskningar, inte bara kostnadsgranskningar. Gateways som kan bevisa en cachepolicy med omfattning av klienter blir lättare att styra.

Faktureringsattribution: separat cacheläsning, skrivning och normala tokens

Prompt cachelagring kan göra fakturor svårare att förstå om alla inmatningstoken visas som ett nummer. Faktureringsreskontran bör bevara minst fem kategorier:

1. uncachade indatatokens;
2. cache-skrivtokens;
3. cache-lästa tokens;
4. output tokens;
5. leverantörsspecifika TTL- eller cachekontrollavgifter.

Detta spelar roll när en leverantör ger rabatt på cachade läsningar, en annan tar olika betalt för cacheskrivning och en annan visar ett längre TTL-alternativ. En kundfaktura ska kunna förklara varför två förfrågningar med liknande totala indatatoken hade olika kostnader.

För intern återkrav, tillskriv cacheeffekter till klienten och applikationen som gjorde begäran. Undvik att tilldela en cache-läsförmån från en hyresgäst till en annan. Om ett delat internt plattformsteam äger den stabila promptmallen, rapportera cacheprestanda på mallnivå separat från hyresgästens fakturor.

Cache-linting checklista

Innan du aktiverar cachetillämpning, kör promptmallar genom en luddchecklista:

• Stabila systeminstruktioner visas före flyktig användarinmatning.
• Verktygsscheman sorteras efter stabilt ID eller namn.
• JSON serialiseras deterministiskt.
• Inga tidsstämplar, slumpmässiga ID:n, begärande ID:n eller spårnings-ID:n visas i det stabila prefixet.
• Inga användarspecifika hemligheter visas i delade återanvändbara block.
• RAG-kodavsnitt placeras efter återanvändbara policy- och verktygsavsnitt om det inte finns en avsiktlig anledning att inte göra det.
• Promptmallar har explicita versioner.
• Mallutgåvor kan korreleras med ändringar i cache-träfffrekvens.
• Providers cachekontroller används endast genom adapterkod, inte spridd applikationslogik.
• Raw prompt-loggning är inaktiverat som standard eller skyddas av strikta lagrings- och åtkomstregler.

Utbyggnadsplan

1. Observera innan du ändrar uppmaningar

Börja med att samla in leverantörsanvändningsfält och normaliserade cachestatistik för befintlig trafik. Beräkna prefixfingeravtryck för de första N tokens eller för gatewaydefinierade promptregioner. Målet är att hitta rutter med långa volymer med hög prefix churn.

2. Klassificera arbetsbelastningar

Gruppera trafik i kategorier: agentsessioner, kodningsassistenter, RAG, supportautomation, dokumentanalys, batchjobb och kort chatt. Snabbcachearbete ägnar vanligtvis mest uppmärksamhet åt arbetsbelastningar med långa sammanhang och upprepade prefix. Korta uppmaningar under leverantörströskelvärdena kanske inte är till nytta.

3. Introducera stabila prefixbyggare

Flytta en arbetsbelastning från obearbetad promptkonstruktion till regionbaserad montering. Behåll den renderade leverantörsbegäran semantiskt likvärdig. Kombinera inte den här förändringen med modellmigrering, verktygsomformning eller större omskrivningar av uppmaningar, annars vet du inte vad som orsakade metriska förändringar.

4. Canary one route

Aktivera cachekontroller för en liten del av en klient eller intern app. Jämför cache-läshastighet, prefix-churn, tid till första token, felfrekvens och kostnadskategorier. Undvik att göra anspråk på besparingar tills leverantörsfakturor stämmer överens med gatewayreskontra.

5. Genomför gradvis

Efter kanariefågel, förvandla luddvarningar till policykontroller. Varna till exempel för instabil verktygsordning först och avvisa sedan nya mallversioner som innehåller flyktiga metadata i det stabila prefixet.

Avvägningar

• Högre träfffrekvens för cache jämfört med flexibilitet i snabbmeddelanden: stabila prefix förbättrar återanvändningen, men team kan behöva flytta dynamiska instruktioner senare eller designa om mallar.
• Provider-native caching kontra portabilitet: att använda varje leverantörs cachekontroller kan förbättra ekonomin, men trösklar, TTL, fält och prissättningssemantik skiljer sig åt.
• Observerbarhet kontra känslig loggning: promptdiffs hjälper till att felsöka missar, men hash och redigerad diagnostik är säkrare standardinställningar.
• Isolering av hyresgäster kontra maximal återanvändning: bred återanvändning kan se attraktiv ut, men beteende med hyresgäster är säkrare och lättare att förklara.
• Längre lagring jämfört med kostnad och policykomplexitet: längre TTL-alternativ kan hjälpa agentsessioner, men kan införa olika prissättnings- och datakontrollöverväganden.

Aktiv slutsats

Behandla promptcache som ett gateway-kontrollplansproblem, inte en kryssruta för leverantör. Det praktiska mönstret är: definiera stabila, halvstabila och flyktiga promptregioner; återge dem deterministiskt; anpassa leverantörsspecifika cachekontroller bakom ett gränssnitt; normalisera cacheanvändning till en reskontra; exponera cache-hit diagnostik efter klient, app, rutt och mallversion; och upprätthålla hyresgästens antaganden.

Det första användbara steget är inte en omskrivning. Lägg till observerbarhet i cache till dina längsta uppmaningar, identifiera prefix-churn och ludda mallarna som orsakar flest missar. När du kan förklara cachebeteende kan du säkert optimera det.

Relaterad läsning

• bygg cache-medvetna kategorier i faktureringsreskontra
• join cache-statistik med säker LLM observerbarhet
• håll hämtningskontexten hyresgäst-omfattande i RAG-arbetsbelastningar