Spørg cachekontrol i en multi-model API-gateway: stabile præfikser, lejerisolering og cache-hit-analyse
En praktisk gateway-arkitektur til beskyttelse af prompt-cache-hitrater på tværs af OpenAI, Anthropic og Gemini-stil API'er: stabile promptregioner, udbydermetrisk normalisering, lejerisolering, faktureringstilskrivning og udrulningstjek.
Prompt caching er let at spilde. Et team kan have en systemprompt på 40.000 tokens, værktøjsskema, politikblok, lagerkort eller agenthukommelse, der skal kunne genbruges, og derefter ved et uheld placere et tidsstempel, anmodnings-id, brugernavn, hentekodestykke eller randomiseret værktøjsbestilling nær toppen af prompten. Udbyderen ser et andet præfiks, cachen savnes, forsinkelsen stiger, og regningen ser forvirrende ud.
I en applikation med én udbyder kan du rette dette i applikationsskabelonen. I en multi-model gateway er problemet større: hver udbyder afslører forskellige cache-kontroller, token-tærskler, time-to-live-adfærd, brugsfelter og faktureringssemantik. Gatewayen har brug for et bærbart kontrolplanmønster til at samle cachesikre prompter, måle cacheadfærd, isolere lejere og tilskrive omkostninger.
Denne artikel beskriver en referencearkitektur. Det er ikke et kundecasestudie og kræver ikke benchmarkresultater. Faktaene nedenfor kommer fra udbyderdokumentation og offentlig forskning; designanbefalingerne er betjeningsvejledning på gateway-niveau.
Fejltilstand: cache-breaking prompt assembly
Prompt-caching belønner generelt gentagne promptpræfikser. Den nøjagtige mekanik varierer fra udbyder til udbyder, men den praktiske implikation er konsekvent: Hvis forsiden af prompten ændres, lider genbrugen.
Almindelige cache-brydere omfatter:
- Metadata pr. anmodning øverst: tidsstempler, sporings-id'er, sessions-id'er, implementerings-id'er eller genererede anmodningsetiketter.
- Brugerspecifikke data i præfikset: navne, kontoattributter, tilladelser eller private præferencer placeret før genanvendelige politikker eller værktøjsblokke.
- Ustabil værktøjsserialisering: Værktøjsskemaer udsendt i ikke-deterministisk rækkefølge med skiftende mellemrum eller genererede id'er.
- Hentningsstykker for tidligt: RAG-kontekst indsat før stabile systeminstruktioner eller delt lagerkontekst.
- Skabelonafdrift: Små ordændringer frigives ofte uden versions- eller cachediagnostik.
En gateway kan på magisk vis ikke gøre et ustabilt præfiks cachebart, men det kan gennemtvinge en hurtig monteringskontrakt og gøre cache-misser synlige.
Udbyderfakta at designe omkring
Detaljerne betyder noget, fordi en gateway skal normalisere adfærd uden at lade som om, at udbyderne er identiske.
- OpenAI: OpenAI har dokumenteret prompt-caching for det længste tidligere beregnede promptpræfiks. Det begynder ved 1.024 tokens, stiger i intervaller på 128 tokens og afslører cachelagrede tokens i brugsfelter. OpenAI angiver også, at prompt-caches typisk ryddes efter 5-10 minutters inaktivitet og altid fjernes inden for en time efter cachens sidste brug.
- Antropisk: Antropisk prompt-caching kan anmodes om med
cache_control. Dens dokumentation beskriver cache-matching over promptkomponenter såsom værktøjer, systemindhold og meddelelser op til den blok, der er markeret med cachekontrol. Anthropic dokumenterer en flygtig cache, inklusive en 5-minutters varighed og en 1-times mulighed mod ekstra omkostninger. - Gemini: Google Gemini kontekst-caching afslører cache-hit-token-tællinger gennem brugsmetadata såsom
total_cached_tokens, og dens dokumentation viser minimum-input-token-antal efter model. - Datakontrolimplikation: OpenAIs API-datakontroldokumentation bemærker, at udvidet prompt-caching kræver lagring af nøgle-/værditensorer som applikationstilstand i GPU-lokalt lager. Selv når udbydere opretholder isolationsgarantier, bør gateways behandle cache-adfærd som følsom infrastruktur, ikke som et delt applikationsdatalager.
- Forskningssignal: Offentlig forskning har undersøgt, om arkitekturer i gateway-stil kan introducere prompt-caching-sårbarheder, der omgår udbyder-niveau cache-isolation. Det beviser ikke, at en specifik gateway er sårbar, men den understøtter konservativt lejerisoleringsdesign.
Anbefaling: implementer cachekontrol som en gatewayfunktion med eksplicitte politikker, ikke som en utilsigtet bivirkning af gentagne prompter.
En hurtig monteringskontrakt med tre regioner
Den vigtigste designbeslutning er at adskille stabilt og flygtigt indhold, før anmodningen når en udbyderadapter.
Region 1: stabilt præfiks
Det stabile præfiks er, at indhold forventes at forblive identisk på tværs af mange anmodninger om den samme applikation, modelrute og promptskabelonversion. Eksempler omfatter:
- kernesysteminstruktioner;
- sikkerheds- og politikblokeringer;
- værktøjsskemaer;
- statisk produktdokumentation;
- lagerkort til kodningsagenter;
- faste output-format instruktioner.
Denne region skal være deterministisk. Gatewayen bør bygge den ud fra versionerede skabeloner, kanoniseret JSON og stabile bestillingsregler. Hvis et værktøjsregister er inkluderet, skal du sortere værktøjer efter stabilt værktøjs-id. Hvis JSON-skemaer er inkluderet, skal du serialisere dem med deterministisk nøglerækkefølge og ingen genererede tidsstempler.
Region 2: semi-stabil lejer- eller arbejdsområdekontekst
Den semi-stabile region ændres sjældnere end individuelle anmodninger, men deles ikke globalt. Eksempler omfatter:
- lejerspecifik politik tilsidesætter;
- værktøjstilladelseslister på arbejdsområdeniveau;
- kundespecifik terminologi;
- teamkodningskonventioner;
- langvarig projektkontekst.
Denne region skal være omfattet af en lejer, et arbejdsområde eller en applikationsgrænse. Det kan stadig være cachebart, men gatewayen bør aldrig antage, at en anden lejer sikkert kan genbruge den.
Region 3: flygtigt suffiks
Det flygtige suffiks er delen pr. anmodning:
- brugermeddelelse;
- hentede uddrag for denne forespørgsel;
- aktuelt tidsstempel, hvis det virkelig er nødvendigt;
- anmod om ID og sporingsmetadata, hvis det overhovedet er inkluderet i prompten;
- kortvarig samtale vender;
- resultater fra runtime-værktøjer.
De fleste cache-misser forårsaget af applikationsdesign sker, fordi flygtige suffiksdata ved et uheld placeres i præfikset. En gateway-side builder burde gøre det svært.
Implementeringsmønster: stabile præfiksbyggere
En praktisk gateway-implementering kan afsløre en prompt-assembly-grænseflade i stedet for at acceptere en uigennemsigtig promptstreng fra hver applikation.
Gatewayen gengiver derefter den udbyderspecifikke anmodning. Dette giver gatewayen et sted at håndhæve regler:
- afvis tidsstempler i stabile præfiksfelter;
- kanonisere værktøjsskemaer;
- hash hver region separat;
- vedhæft cachekontroller, hvor en udbyder understøtter dem;
- bevar prompt semantik, mens du flytter flygtigt materiale senere;
- registreringsskabelon og præfiksfingeraftryk til diagnostik.
For ældre applikationer, der kun sender råbeskeder, kan gatewayen stadig give en lint-tilstand: undersøg meddelelsesrækkefølgen, udregn præfiks-fingeraftryk og rapporter sandsynlige cache-brydere uden at omskrive prompten i starten.
Provider-adapterlag: normaliser cachebrug uden at skjule forskelle
En multi-model gateway bør ikke afsløre tre ikke-relaterede cache-rapporter for udviklere. Det bør heller ikke udjævne udbyderspecifik økonomi så aggressivt, at fakturaer bliver umulige at forklare.
Opret en normaliseret cache-reskontro med felter som:
Adapteren kortlægger udbyderens brug i normaliserede kategorier:
- Ikke-cache-inputtokens:-tokens behandlet uden cachelæsningsrabat eller cache-læst regnskab.
- Cache-skrive-tokens:-tokens, der oprettede eller opdaterede en cache-indgang på udbydersiden, når udbyderen rapporterer denne skelnen.
- Cache-læste tokens: tokens serveret fra cachen eller tælles som cachelagret af udbyderens brugsmetadata.
- Output-tokens: genererede tokens, som skal forblive adskilt fra prompt-cache-økonomi.
- TTL-indstilling: den valgte cachevarighedsklasse, hvor en udbyder afslører et valg.
Anbefaling: Gem rå udbyderbrug i en redigeret, skemaversioneret form sammen med normaliserede felter. Normalisering er nyttig til dashboards; rå felter er nødvendige for afstemning, når udbyderens semantik ændres.
Cache observerbarhed: dashboards, der forklarer mangler
Et nyttigt cache-dashboard kan mere end at vise samlede cachede tokens. Det skulle hjælpe teams med at svare: "Hvilken arbejdsbyrde bryder præfikset, og hvad ændrede sig?"
Spor cache-metrics ved:
- lejer;
- arbejdsområde eller app;
- modelrute;
- udbyder og model;
- prompt-skabelonversion;
- stabil præfiks-hash;
- semi-stabil kontekst-hash;
- API-nøgle eller tjenestekonto, hvor det er relevant;
- tidsvindue, især fordi cache-TTL'er er korte for mange arbejdsbelastninger.
Nyttige afledte metrics omfatter:
- Cachelæsehastighed: cachelagrede inputtokens divideret med det samlede antal inputtokens, der er kvalificerede til cachelagring.
- Præfiks-churn: antal distinkte stabile præfiks-hashes pr. skabelonversion pr. time.
- Skabelonafdrift: cache-hit ændres efter en skabelonfrigivelse.
- Koldstartomkostninger: cacheskrivning eller ikke-cachede inputforbrug for den første anmodning i en burst.
- Rutesammenligning: hitrater på tværs af udbyderruter for den samme logiske arbejdsbyrde.
Du må ikke som standard gemme rå-prompter til fejlretning. Foretrække hashes, regionlængder, skabelon-id'er, kanoniseringsadvarsler og redigerede diff. Hvis et team har brug for dybere fejlretning, skal du kræve eksplicit adgangskontrol og opbevaringsbegrænsninger.
Politik for lejerisolering: design ikke til genbrug på tværs af lejere
Den sikreste gateway-antagelse er enkel: cachebar adfærd bør være lejer-omfanget. Selvom to lejere deler en identisk offentlig politikblok, bør gatewayen ikke bevidst dirigere eller forme trafik for at udnytte genbrug af cache på tværs af lejere.
En konservativ politik omfatter:
- Lejerbevidst routing: diriger cachebar trafik ved hjælp af lejer-, arbejdsområde- og applikationsgrænser.
- Ingen delte hemmelige præfikser: Anbring aldrig lejerhemmeligheder, legitimationsoplysninger, private dokumenter eller brugerspecifikke data i et genbrugeligt delt præfiks.
- Separate præfiks-fingeraftryk: Beregn fingeraftryk med lejeromfang inkluderet i gateway-reskontroen, selvom den gengivede tekst er identisk.
- Kontrolelementer på organisationsniveau: tillad administratorer at deaktivere udbyderens cachefunktioner for følsomme arbejdsbelastninger.
- Udbyderisolering er ikke en produktfunktion, der skal videresælges: Behandl udbyderens cache-isolering som en basisbeskyttelse, ikke som tilladelse til at opbygge cache-pooling på tværs af kunder.
Forudsigelse: efterhånden som langkontekstagenter bliver mere almindelige, vil cache-adfærd blive en del af sikkerhedsgennemgange, ikke kun omkostningsgennemgange. Gateways, der kan bevise en lejer-omfanget cachepolitik, vil være nemmere at styre.
Faktureringstilskrivning: separate cachelæsninger, skrivninger og normale tokens
Prompt caching kan gøre fakturaer sværere at forstå, hvis alle inputtokens vises som ét tal. Faktureringsregnskabet skal bevare mindst fem kategorier:
- ikke-cachede inputtokens;
- cache skrive-tokens;
- cache læse tokens;
- outputtokens;
- udbyderspecifikke TTL- eller cachekontrolafgifter.
Dette har betydning, når én udbyder giver rabat på cachelæsning, en anden opkræver forskelligt for cacheskrivning, og en anden viser en længere TTL-mulighed. En kundefaktura skal kunne forklare, hvorfor to anmodninger med lignende samlede inputtokens havde forskellige omkostninger.
For intern tilbageførsel skal du tilskrive cacheeffekter til lejeren og applikationen, der har foretaget anmodningen. Undgå at tildele en cache-læsefordel fra en lejer til en anden. Hvis et delt internt platformsteam ejer den stabile promptskabelon, skal du rapportere cacheydelse på skabelonniveau separat fra lejerfakturaer.
Cache-linting-tjekliste
Før du aktiverer cachehåndhævelse, skal du køre promptskabeloner gennem en fnug-tjekliste:
- Stabile systeminstruktioner vises før flygtige brugerinput.
- Værktøjsskemaer er sorteret efter stabilt ID eller navn.
- JSON serialiseres deterministisk.
- Ingen tidsstempler, tilfældige id'er, anmodnings-id'er eller sporings-id'er vises i det stabile præfiks.
- Der vises ingen brugerspecifikke hemmeligheder i delte genanvendelige blokke.
- RAG-uddrag placeres efter genbrugelige politik- og værktøjssektioner, medmindre der er en bevidst grund til ikke at gøre det.
- Promptskabeloner har eksplicitte versioner.
- Skabelonfrigivelser kan korreleres med cache-hit-rate ændringer.
- Udbyderens cachekontroller bruges kun gennem adapterkode, ikke spredt applikationslogik.
- Rå promptlogning er deaktiveret som standard eller beskyttet af strenge opbevarings- og adgangsregler.
Udviklingsplan
1. Overhold før du ændrer prompter
Start med at indsamle udbyderbrugsfelter og normaliserede cache-metrics for eksisterende trafik. Beregn præfiks-fingeraftryk for de første N tokens eller for gateway-definerede promptområder. Målet er at finde ruter med høj volumen og lang kontekst med høj præfiks-churn.
2. Klassificer arbejdsbelastninger
Gruppér trafik i kategorier: agentsessioner, kodningsassistenter, RAG, supportautomatisering, dokumentanalyse, batchjobs og kort chat. Prompt cache-arbejde lægger normalt mest vægt på arbejdsbelastninger med lang kontekst og gentagne præfikser. Korte meddelelser under udbydertærsklerne er muligvis ikke til gavn.
3. Introducer stabile præfiksbyggere
Flyt én arbejdsbyrde fra rå promptkonstruktion til regionsbaseret montage. Hold den gengivne udbyderanmodning semantisk ækvivalent. Kombiner ikke denne ændring med modelmigrering, redesign af værktøj eller større prompt-omskrivninger, ellers ved du ikke, hvad der forårsagede metriske ændringer.
4. Canary one-rute
Aktiver cachekontroller for en lille del af en lejer eller intern app. Sammenlign cache-læsehastighed, præfiks-churn, tid til første token, fejlrate og omkostningskategorier. Undgå at kræve besparelser, indtil udbyderens regninger stemmer overens med gateway-reskontro.
5. Håndhæve gradvist
Efter kanariefuglen skal du omdanne fnug-advarsler til politiktjek. Advar f.eks. først om ustabil værktøjsrækkefølge, og afvis derefter nye skabelonversioner, der inkluderer flygtige metadata i det stabile præfiks.
Afvejninger
- Højere cache-hitrate vs. promptfleksibilitet: stabile præfikser forbedrer genbrug, men teams skal muligvis flytte dynamiske instruktioner senere eller omdesigne skabeloner.
- Provider-native caching vs. portabilitet: Brug af hver udbyders cache-kontroller kan forbedre økonomien, men tærskler, TTL'er, felter og prissemantik er forskellige.
- Observabilitet vs. følsom logning: promptdiffs hjælper med at fejlsøge fejl, men hashes og redigeret diagnostik er sikrere standarder.
- Lejerisolering vs. maksimalt genbrug: bred genbrug kan se attraktiv ud, men lejer-omfattet adfærd er sikrere og lettere at forklare.
- Længere fastholdelse i forhold til omkostninger og politikkompleksitet: Længere TTL-muligheder kan hjælpe agentsessioner, men kan introducere forskellige prissætnings- og datakontrolovervejelser.
Aktiv konklusion
Behandle prompt-caching som et gateway-kontrolplan-problem, ikke et udbyder-afkrydsningsfelt. Det praktiske mønster er: definer stabile, semi-stabile og flygtige promptregioner; gengive dem deterministisk; tilpasse udbyderspecifikke cachekontroller bag én grænseflade; normalisere cachebrug til en hovedbog; eksponer cache-hit-diagnostik efter lejer, app, rute og skabelonversion; og håndhæve lejer-omfattede antagelser.
Det første nyttige trin er ikke en omskrivning. Tilføj cache-observabilitet til dine længste prompter, identificer præfiks-churn, og fnug de skabeloner, der forårsager flest fejl. Når du kan forklare cache-adfærd, kan du sikkert optimere den.
Relateret læsning
- byg cache-bevidste kategorier ind i faktureringshovedbogen
- tilslut cache-metrics med sikker LLM-observabilitet
- hold hentning i kontekst til lejer i RAG-arbejdsbelastninger