Spørg cachekontrol i en multi-model API-gateway: stabile præfikser, lejerisolering og cache-hit-analyse

Prompt caching er let at spilde. Et team kan have en systemprompt på 40.000 tokener, 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 benchmark-resultater. Faktaene nedenfor kommer fra udbyderdokumentation og offentlig forskning; designanbefalingerne er betjeningsvejledning på gateway-niveau.

Fejltilstanden: 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 frigivet 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 udbydere er identiske.

• OpenAI: OpenAI har dokumenteret prompt-caching for det længste tidligere beregnede promptpræfiks. Det begynder ved 1.024 tokens, stiger i trin på 128 tokens og afslører cachelagrede tokens i brugsfelter. OpenAI angiver også, at promptcaches typisk ryddes efter 5-10 minutters inaktivitet og altid fjernes inden for en time efter cachens sidste brug.
• Anthropic: Anthropic prompt-cachelagring 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 varighed på 5 minutter og en mulighed på 1 time 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 promptcaching 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 antagelser om cache-isolering på udbyderniveau. Det beviser ikke, at en bestemt gateway er sårbar, men den understøtter konservativt design af lejerisolering.

Anbefaling: implementer cachekontrol som en gatewayfunktion med eksplicitte politikker, ikke som en utilsigtet bivirkning af gentagne prompter.

A tre-region prompt montagekontrakt

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 indhold, der 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;
• fixed output-format instruktioner.

Denne region skal være deterministisk. Gatewayen skal 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åde kontekst

Den semi-stabile region ændres sjældnere end individuelle anmodninger, men deles ikke globalt. Eksempler omfatter:

• lejerspecifikke politiktilsidesættelser;
• værktøjstilladelseslister på arbejdsområdeniveau;
• kundespecifik terminologi;
• teamkodningskonventioner;
• projektkontekst med lang levetid.

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;
• drejninger i kortvarig samtale;
• resultater af runtime-værktøjer.

De fleste cache-misser forårsaget af applikationsdesign sker, fordi flygtige suffiksdata ved et uheld placeres i præfikset. En gatewayside-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 én uigennemsigtig promptstreng fra hver 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 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 hurtig semantik, mens du flytter flygtigt materiale senere;
• registreringsskabelon og præfiksfingeraftryk til diagnostik.

For ældre applikationer, der kun sender råbeskeder, kan gatewayen stadig levere 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:

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

Adapteren kortlægger udbyderens brug i normaliserede kategorier:

• Ikke-cachede inputtokens: tokens behandlet uden cachelæsningsrabat eller cachelæst regnskab.
• Cache-skrivetokens:-tokens, der oprettede eller opdaterede en cache-indgang på udbydersiden, når udbyderen rapporterer denne skelnen.
• Cache-læsetokens:-tokens serveret fra cache eller tælles som cachelagret af udbyderbrugsmetadata.
• 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æfikshash;
• 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 kvalificeret til cachelagring.
• Prefix churn: antal distinkte stabile præfiks-hashes pr. skabelonversion pr. time.
• Skabelonafdrift: cache-hit ændringer 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ækker 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 skal være lejer-omfanget. Selvom to lejere deler en identisk offentlig politikblok, bør gatewayen ikke bevidst dirigere eller forme trafik til 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: placer aldrig lejerhemmeligheder, legitimationsoplysninger, private dokumenter eller brugerspecifikke data i et genanvendeligt delt præfiks.
• Separate præfiks-fingeraftryk: beregne fingeraftryk med lejeromfang inkluderet i gateway-reskontroen, selvom den gengivede tekst er identisk.
• Kontroller på organisationsniveau: giver administratorer mulighed for at deaktivere udbyderens cachefunktioner for følsomme arbejdsbelastninger.
• Udbyderisolering er ikke en produktfunktion, der skal videresælges: behandle udbyderens cache-isolering som en basisbeskyttelse, ikke som tilladelse til at opbygge cache-pooling på tværs af kunder.

Forudsigelse: efterhånden som agenter med lang kontekst bliver mere almindelige, vil cache-adfærd blive en del af sikkerhedsgennemgange, ikke kun omkostningsgennemgange. Gateways, der kan bevise en lejer-omfattet cachepolitik, bliver 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:

1. ikke-cachede inputtokens;
2. cache-skrivetokens;
3. cache-læsetokens;
4. outputtokens;
5. 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 er serialiseret 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.
• Skabelonudgivelser kan korreleres med cache-hit-rate ændringer.
• Providers cachekontroller bruges kun via adapterkode, ikke spredt applikationslogik.
• Rå promptlogning er deaktiveret som standard eller beskyttet af strenge opbevarings- og adgangsregler.

Udviklingsplan

1. Overhold før du ændrer prompt

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ærskelværdierne gavner muligvis ikke.

3. Introducer stabile præfiksbyggere

Flyt én arbejdsbelastning fra rå promptkonstruktion til regionsbaseret montage. Hold den gengivne udbyderanmodning semantisk ækvivalent. Kombiner ikke denne ændring med modelmigrering, værktøjsomlægning eller større promptomskrivninger, ellers ved du ikke, hvad der forårsagede metriske ændringer.

4. Canary one route

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 cachehitrate 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. maksimal genbrug: bred genbrug kan se attraktiv ud, men lejer-omfattet adfærd er sikrere og lettere at forklare.
• Længere opbevaring 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

• build cache-bevidste kategorier i faktureringshovedbogen
• deltag cache-metrics med sikker LLM observerbarhed
• hold genfindingskonteksten lejer-omfang i RAG-arbejdsbelastninger