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

Snabb 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ässigt verktygsordning 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 gateway med flera modeller ä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äge: cachebrytande promptsammansättning

Cachning 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, implementerings-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 som sänds ut i icke-deterministisk ordning, med skiftande blanksteg eller genererade ID:n.
• Hämtning av kodavsnitt för tidigt: RAG-kontext infogas före stabila systeminstruktioner eller delad lagringskontext.
• Malldrift: små ordä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 designa runt

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

• OpenAI: OpenAI har dokumenterat promptcache för det längsta tidigare beräknade promptprefixet. Det börjar vid 1 024 tokens, ökar i steg om 128 token och exponerar cachade token-antal i användningsfält. OpenAI anger också att promptcacher vanligtvis rensas efter 5–10 minuters inaktivitet och tas alltid bort inom en timme efter att cachen senast användes.
• Antropisk: Antropisk 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 en tillfällig cache, inklusive en längd på 5 minuter och ett alternativ på 1 timme mot en extra kostnad.
• Tvillingarna: Google Gemini kontextcachning avslöjar antalet cache-hit tokens genom användningsmetadata som total_cached_tokens, och dess dokumentation listar minsta antal indatatoken per modell.
• Datakontrollimplikation: OpenAI:s 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 huruvida arkitekturer i gateway-stil kan introducera sårbarheter för snabbcachning 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 för 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 att innehållet 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 versionerade 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: halvstabil hyresgäst eller arbetsyta

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

• hyresgästspecifik policy åsidosätter;
• Tillståndslistor för verktyg på arbetsytanivå;
• kundspecifik terminologi;
• lagkodningskonventioner;
• långlivad projektkontext.

Denna region bör omfattas av en hyresgäst, 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 alls ingår i prompten;
• kortvariga konversationer vänder;
• 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-karta-8491"
  },
  "semi_stable_context": {
    "workspace_policy_version": "workspace-44-v6"
  },
  "volatile_suffix": {
    "user_message": "Förklara varför detta test misslyckas...",
    "retrieval_context_ids": ["chunk_7", "chunk_19"],
    "trace_id": "not_inserted_into_prompt"
  }
}

Gatewayen gör 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;
• bifoga cachekontroller där en leverantör stöder dem;
• bevara snabb semantik medan du flyttar flyktigt material senare;
• registrera mall 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.

Provider-adapterlager: 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": "kod-agent",
  "route": "coding-long-context",
  "provider": "leverantörsnamn",
  "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örsanvändning i normaliserade kategorier:

• Cache-skrivtokens: tokens som skapade eller uppdaterade en cache-post på leverantörssidan när leverantören rapporterar denna skillnad.
• Cachelästa tokens: tokens som 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 cachevaraktighetsklassen 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-instrumentpanel 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 att:

• hyresgäst;
• arbetsyta eller app;
• modellväg;
• leverantör och modell;
• version av promptmall;
• stabil prefixhash;
• 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 indatatoken som är kvalificerade för cachning.
• Prefix churn: antal distinkta stabila prefixhashar per mallversion och timme.
• Malldrift: cache-hit ändras efter en mallsläppning.
• Kallstartskostnad: cacheskrivning eller uncachad indatakostnad 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äver 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 gateway-antagandet är enkelt: cachebart beteende bör vara klient-omfattande. Ä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 cache för flera hyresgäster.

En konservativ politik 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, autentiseringsuppgifter, privata dokument eller användarspecifika data i ett återanvändbart delat prefix.
• Separata prefixfingeravtryck: Beräkna fingeravtryck med klientens omfattning 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.
• Isolering av leverantörer är inte en produktfunktion som ska säljas 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 cachepolicy för klienter kommer att vara 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. ocachade indatatokens;
2. cache-skrivtokens;
3. cache-lästa tokens;
4. utgångstokens;
5. leverantörsspecifika TTL- eller cachekontrollavgifter.

Detta spelar roll när en leverantör rabatterar 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 inmatningstoken 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.

Checklista för cache-linting

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äffhastighet.
• Providerns cachekontroller används endast genom adapterkod, inte spridd programlogik.
• Raw prompt-loggning är inaktiverat som standard eller skyddas av strikta lagrings- och åtkomstregler.

Utrullningsplan

1. Observera innan du ändrar uppmaningar

Börja med att samla in leverantörsanvändningsfält och normaliserade cachemått 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, omdesign av verktyg 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ågeln, 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 snabb flexibilitet: 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 cache-kontroller kan förbättra ekonomin, men trösklar, TTL:er, fält och prissättningssemantik skiljer sig åt.
• Observerbarhet kontra känslig loggning: promptdifferenser hjälper till att felsöka missar, men hash och redigerad diagnostik är säkrare standardinställningar.
• Isolering av hyresgäster jämfört med 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 antaganden som omfattas av hyresgästen.

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

Relaterad läsning

• bygga in cachemedvetna kategorier i faktureringsreskontrangå med i cache-statistik med säker LLM-observerbarhet
• behåll hämtningskontexten tenant-scoped i RAG-arbetsbelastningar