Spør hurtigbufferkontroll i en multi-modell API-gateway: stabile prefikser, leietakerisolasjon og cache-hit-analyse

Spørg bufring er lett å kaste bort. Et team kan ha en 40 000-token systemforespørsel, verktøyskjema, policyblokk, depotkart eller agentminne som skal kunne gjenbrukes, og deretter sette et tidsstempel, forespørsels-ID, brukernavn, hentekodebit eller randomisert verktøybestilling nær toppen av ledeteksten. Leverandøren ser et annet prefiks, hurtigbufferen er savnet, ventetiden øker og regningen ser forvirrende ut.

I en enkeltleverandørapplikasjon kan du fikse dette i applikasjonsmalen. I en multi-modell gateway er problemet større: hver leverandør avslører forskjellige hurtigbufferkontroller, token-terskler, time-to-live-atferd, bruksfelt og faktureringssemantikk. Gatewayen trenger et bærbart kontrollplanmønster for å sette sammen hurtigbuffersikre meldinger, måle bufferatferd, isolere leietakere og tilskrive kostnader.

Denne artikkelen beskriver en referansearkitektur. Det er ikke en kundecasestudie og krever ikke referanseresultater. Fakta nedenfor kommer fra leverandørdokumentasjon og offentlig forskning; designanbefalingene er driftsveiledning på gatewaynivå.

Feilmodus: cache-breaking prompt assembly

Buffring av ledetekster belønner vanligvis gjentatte ledetekstprefikser. Den nøyaktige mekanikken varierer fra leverandør til leverandør, men den praktiske implikasjonen er konsistent: Hvis forsiden av forespørselen endres, lider gjenbruken.

Vanlige bufferbrytere inkluderer:

• Metadata per forespørsel øverst: tidsstempler, sporings-ID-er, økt-ID-er, distribusjons-ID-er eller genererte forespørselsetiketter.
• Brukerspesifikke data i prefikset: navn, kontoattributter, tillatelser eller private preferanser plassert før gjenbrukbare retningslinjer eller verktøyblokker.
• Ustabil verktøyserialisering: verktøyskjemaer som sendes ut i ikke-deterministisk rekkefølge, med skiftende mellomrom eller genererte ID-er.
• Henting av kodebiter for tidlig: RAG-kontekst satt inn før stabile systeminstruksjoner eller delt depotkontekst.
• Malavvik: små ordendringer utgitt ofte uten versjons- eller bufferdiagnostikk.

En gateway kan ikke på magisk vis gjøre et ustabilt prefiks bufret, men det kan håndheve en umiddelbar monteringskontrakt og gjøre cache-misser synlige.

Leverandørfakta å designe rundt

Detaljene er viktige fordi en gateway må normalisere atferd uten å late som om leverandørene er identiske.

• OpenAI: OpenAI har dokumentert promptbufring for det lengste tidligere beregnede ledetekstprefikset. Den begynner på 1 024 tokens, øker i trinn på 128 tokener, og viser bufrede tokentellinger i bruksfelt. OpenAI angir også at hurtigbuffere vanligvis tømmes etter 5–10 minutter med inaktivitet og alltid fjernes innen én time etter siste bruk av hurtigbufferen.
• Anthropic: Anthropic promptbufring kan bes om med cache_control. Dokumentasjonen beskriver cache-matching over ledetekstkomponenter som verktøy, systeminnhold og meldinger opp til blokken merket med cache-kontroll. Anthropic dokumenterer en flyktig hurtigbuffer, inkludert en varighet på 5 minutter og et alternativ på 1 time mot ekstra kostnad.
• Gemini: Google Gemini kontekstbufring avslører cache-hit token-tellinger gjennom bruksmetadata som total_cached_tokens, og dokumentasjonen viser minimum antall input-token etter modell.
• Datakontrollimplikasjon: OpenAIs API datakontrolldokumentasjon merker at utvidet hurtigbufring krever lagring av nøkkel-/verditensorer som applikasjonstilstand i GPU-lokal lagring. Selv når leverandører opprettholder isolasjonsgarantier, bør gatewayer behandle hurtigbufferatferd som sensitiv infrastruktur, ikke som en delt applikasjonsdatalager.
• Forskningssignal: Offentlig forskning har undersøkt om arkitekturer i gateway-stil kan introdusere prompt-caching-sårbarheter som omgår antakelser om cache-isolering på leverandørnivå. Det beviser ikke at en bestemt gateway er sårbar, men den støtter konservativ design for leietakerisolering.

Anbefaling: implementer bufferkontroll som en gateway-funksjon med eksplisitte retningslinjer, ikke som en utilsiktet bivirkning av gjentatte forespørsler.

En monteringskontrakt med tre regioner

Den viktigste designbeslutningen er å skille stabilt og flyktig innhold før forespørselen når en leverandøradapter.

Region 1: stabilt prefiks

Det stabile prefikset er innhold som forventes å forbli identisk på tvers av mange forespørsler for samme applikasjon, modellrute og forespørselsmalversjon. Eksempler inkluderer:

• instruksjoner for kjernesystem;
• sikkerhets- og policyblokkeringer;
• verktøyskjemaer;
• statisk produktdokumentasjon;
• lagerkart for kodingsagenter;
• fixed output-format instruksjoner.

Denne regionen bør være deterministisk. Gatewayen bør bygge den fra versjonerte maler, kanonisert JSON og stabile bestillingsregler. Hvis et verktøyregister er inkludert, sorter verktøy etter stabil verktøy-ID. Hvis JSON skjemaer er inkludert, serialiser dem med deterministisk nøkkelrekkefølge og ingen genererte tidsstempler.

Region 2: semi-stabil leietaker eller arbeidsområdekontekst

Den semi-stabile regionen endres sjeldnere enn individuelle forespørsler, men deles ikke globalt. Eksempler inkluderer:

• overstyringer av leietakerspesifikke retningslinjer;
• tillatelseslister for verktøy på arbeidsområdenivå;
• kundespesifikk terminologi;
• lagkodingskonvensjoner;
• langvarig prosjektkontekst.

Denne regionen bør omfattes av en leietaker, arbeidsområde eller applikasjonsgrense. Det kan fortsatt være bufret, men gatewayen bør aldri anta at en annen leietaker trygt kan gjenbruke den.

Region 3: flyktig suffiks

Det flyktige suffikset er delen per forespørsel:

• brukermelding;
• hentet utdrag for dette søket;
• gjeldende tidsstempel, hvis det virkelig er nødvendig;
• be om ID og sporingsmetadata, hvis det i det hele tatt er inkludert i forespørselen;
• kortsiktige samtaler;
• resultater fra kjøretidsverktøy.

De fleste cache-misser forårsaket av programdesign skjer fordi flyktige suffiksdata ved et uhell plasseres i prefikset. En gateway-sidebygger bør gjøre det vanskelig.

Implementeringsmønster: stabile prefiksbyggere

En praktisk gatewayimplementering kan avsløre et ledetekstsammenstillingsgrensesnitt i stedet for å godta én ugjennomsiktig ledetekststreng fra hver applikasjon.

{
  "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 gjengir deretter den leverandørspesifikke forespørselen. Dette gir gatewayen et sted å håndheve regler:

• avvis tidsstempler i stabile prefiksfelt;
• kanonisere verktøyskjemaer;
• hash hver region separat;
• legg ved bufferkontroller der en leverandør støtter dem;
• bevar umiddelbar semantikk mens du flytter flyktig materiale senere;
• postmal og prefiksfingeravtrykk for diagnostikk.

For eldre applikasjoner som bare sender råmeldinger, kan gatewayen fortsatt tilby en lint-modus: inspiser meldingsrekkefølgen, beregne prefiksfingeravtrykk og rapporter sannsynlige hurtigbufferbrudd uten å omskrive forespørselen først.

Leverandøradapterlag: normaliser hurtigbufferbruken uten å skjule forskjeller

En gateway med flere modeller bør ikke avsløre tre urelaterte bufferrapporter for utviklere. Det bør heller ikke utjevne leverandørspesifikk økonomi så aggressivt at fakturaer blir umulige å forklare.

Opprett en normalisert hurtigbufferbok med felt 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 kartlegger leverandørbruken i normaliserte kategorier:

• Ubufrede inndatatokens: tokens behandlet uten en bufferlese-rabatt eller cache-lest regnskap.
• Cache-skrive-tokens:-tokens som opprettet eller oppdatert en bufferoppføring på leverandørsiden når leverandøren rapporterer denne forskjellen.
• Cache-lese-tokens:-tokens servert fra bufferen eller regnet som bufret av leverandørens bruksmetadata.
• Output-tokens: genererte tokens, som skal forbli atskilt fra promptbufferøkonomi.
• TTL-alternativ: den valgte buffervarighetsklassen der en leverandør avslører et valg.

Anbefaling: lagre rå leverandørbruk i en redigert, skjemaversjonsform sammen med normaliserte felt. Normalisering er nyttig for dashbord; råfelt er nødvendige for avstemming når leverandørsemantikk endres.

Cache observerbarhet: dashboards som forklarer glipp

Et nyttig hurtigbufferoversikt gjør mer enn å vise totalt bufrede tokens. Det bør hjelpe teamene med å svare: «Hvilken arbeidsmengde bryter prefikset, og hva endret seg?»

Spor bufferberegninger etter:

• leietaker;
• arbeidsområde eller app;
• modellrute;
• leverandør og modell;
• spørsmålsmalversjon;
• stabil prefiks-hash;
• semi-stabil kontekst-hash;
• API nøkkel eller tjenestekonto, der det er aktuelt;
• tidsvindu, spesielt fordi cache TTL-er er korte for mange arbeidsbelastninger.

Nyttige utledede beregninger inkluderer:

• Cache-lesefrekvens: bufrede inndatatokens delt på totalt antall inputtokener som er kvalifisert for bufring.
• Prefix churn: antall distinkte stabile prefiks-hasher per malversjon per time.
• Maldrift: cache-hit endringer etter en malutgivelse.
• Kaldstartkostnad: cache-skriving eller ubufret inndataforbruk for den første forespørselen i en serie.
• Rutesammenligning: trefffrekvens på tvers av leverandørruter for samme logiske arbeidsbelastning.

Ikke standard til å lagre rå meldinger for feilsøking. Foretrekk hasher, regionlengder, mal-ID-er, kanoniseringsadvarsler og redigerte diff. Hvis et team trenger dypere feilsøking, må du kreve eksplisitte tilgangskontroller og oppbevaringsgrenser.

Retningslinjer for isolering av leietakere: ikke design for gjenbruk på tvers av leietakere

Den sikreste gateway-antagelsen er enkel: bufret atferd bør være leietaker-omfanget. Selv om to leietakere deler en identisk offentlig policy-blokk, bør ikke gatewayen med vilje rute eller forme trafikk for å utnytte gjenbruk av buffer på tvers av leietakere.

En konservativ politikk inkluderer:

• Leietakerbevisst ruting: rute bufringbar trafikk ved hjelp av leietaker-, arbeidsområde- og applikasjonsgrenser.
• Ingen delte hemmelige prefikser: plasser aldri leietakerhemmeligheter, legitimasjon, private dokumenter eller brukerspesifikke data i et gjenbrukbart delt prefiks.
• Separate prefiksfingeravtrykk: beregne fingeravtrykk med leietakeromfang inkludert i gatewayens hovedbok, selv om den gjengitte teksten er identisk.
• Kontroller på organisasjonsnivå: lar administratorer deaktivere leverandørens hurtigbufferfunksjoner for sensitive arbeidsbelastninger.
• Leverandørisolering er ikke en produktfunksjon som skal videreselges: behandle leverandørbufferisolering som en grunnlinjebeskyttelse, ikke som tillatelse til å bygge buffersamling på tvers av kunder.

Prediksjon: etter hvert som langkontekstagenter blir mer vanlig, vil bufferatferd bli en del av sikkerhetsvurderinger, ikke bare kostnadsvurderinger. Gatewayer som kan bevise leietaker-omfanget bufferpolitikk vil være enklere å styre.

Faktureringsattribusjon: separat hurtigbufferlesing, skriving og normale tokens

Spørrebufring kan gjøre fakturaer vanskeligere å forstå hvis alle inndatatokener vises som ett tall. Faktureringsreskontroen skal ha minst fem kategorier:

1. ubufrede inndatatokener;
2. cache skrive-tokens;
3. cache read tokens;
4. output tokens;
5. leverandørspesifikke TTL- eller bufferkontrollkostnader.

Dette er viktig når én leverandør gir rabatt på bufrede lesinger, en annen tar forskjellig betalt for cacheskriving, og en annen viser et lengre TTL-alternativ. En kundefaktura skal kunne forklare hvorfor to forespørsler med lignende totale inndatatokens hadde forskjellige kostnader.

For intern tilbakeføring, tilskriv buffereffekter til leieren og applikasjonen som sendte forespørselen. Unngå å tildele en cache-lest fordel fra en leietaker til en annen. Hvis et delt internt plattformteam eier den stabile forespørselsmalen, rapporter bufferytelse på malnivå separat fra leietakerfakturaer.

Cache-linting-sjekkliste

Før du aktiverer bufferhåndhevelse, må du kjøre ledetekstmaler gjennom en sjekkliste for lo:

• Stabile systeminstruksjoner vises før flyktige brukerinndata.
• Verktøyskjemaer er sortert etter stabil ID eller navn.
• JSON er serialisert deterministisk.
• Ingen tidsstempler, tilfeldige ID-er, forespørsels-ID-er eller sporings-ID-er vises i det stabile prefikset.
• Ingen brukerspesifikke hemmeligheter vises i delte gjenbrukbare blokker.
• RAG-kodebiter plasseres etter gjenbrukbare policy- og verktøyseksjoner med mindre det er en bevisst grunn til å ikke gjøre det.
• Spørsmålsmaler har eksplisitte versjoner.
• Malutgivelser kan korreleres med endringer i cache-hit-rate.
• Leverandørbufferkontroller brukes bare gjennom adapterkode, ikke spredt programlogikk.
• Raw prompt-logging er deaktivert som standard eller beskyttet av strenge oppbevaring- og tilgangsregler.

Utrullingsplan

1. Vær oppmerksom før du endrer forespørsler

Start med å samle leverandørbruksfelt og normaliserte bufferberegninger for eksisterende trafikk. Beregn prefiksfingeravtrykk for de første N tokens eller for gateway-definerte ledetekstområder. Målet er å finne ruter med høyt volum og lang kontekst med høy prefiks-churn.

2. Klassifiser arbeidsbelastninger

Grupper trafikk i kategorier: agentøkter, kodeassistenter, RAG, støtteautomatisering, dokumentanalyse, batchjobber og kort chat. Hurtigbufferarbeid gir vanligvis mest oppmerksomhet til arbeidsbelastninger med lang kontekst og gjentatte prefikser. Korte meldinger under leverandørterskelverdiene er kanskje ikke til nytte.

3. Introduser stabile prefiksbyggere

Flytt én arbeidsbelastning fra rå promptkonstruksjon til regionbasert montering. Hold den gjengitte leverandørforespørselen semantisk likeverdig. Ikke kombiner denne endringen med modellmigrering, redesign av verktøy eller store omskrivinger av spørsmål, ellers vil du ikke vite hva som forårsaket metriske endringer.

4. Kanariøyene én rute

Aktiver bufferkontroller for en liten del av én leietaker eller intern app. Sammenlign cache-lesefrekvens, prefiks-churn, tid til første token, feilrate og kostnadskategorier. Unngå å kreve besparelser før leverandørens regninger stemmer overens med gateway-reskontro.

5. Håndheve gradvis

Etter kanarifuglen, gjør loadvarsler om til retningslinjer for kontroller. Advar for eksempel om ustabil verktøyrekkefølge først, og avvis deretter nye malversjoner som inkluderer flyktige metadata i det stabile prefikset.

Avveininger

• Høyere trefffrekvens for hurtigbuffer kontra fleksibilitet i spørsmål: stabile prefikser forbedrer gjenbruk, men teamene må kanskje flytte dynamiske instruksjoner senere eller redesigne maler.
• Provider-native caching vs. portability: bruk av hver leverandørs bufferkontroller kan forbedre økonomien, men terskler, TTL-er, felt og prissemantikk varierer.
• Observabilitet vs. sensitiv logging: ledetekstforskjeller hjelper til med å feilsøke feil, men hasher og redigert diagnostikk er sikrere standardinnstillinger.
• Isolering av leietaker kontra maksimal gjenbruk: bred gjenbruk kan se attraktivt ut, men atferd med leietaker er tryggere og enklere å forklare.
• Lengere oppbevaring i forhold til kostnad og policykompleksitet: lengre TTL-alternativer kan hjelpe agentøkter, men kan introdusere ulike pris- og datakontrollhensyn.

Aktiv konklusjon

Behandle promptbufring som et gatewaykontrollplanproblem, ikke en leverandøravmerkingsboks. Det praktiske mønsteret er: definer stabile, semi-stabile og flyktige promptregioner; gjengi dem deterministisk; tilpasse leverandørspesifikke cache-kontroller bak ett grensesnitt; normalisere cache-bruk til en hovedbok; eksponer cache-hit diagnostikk etter leietaker, app, rute og malversjon; og håndheve forutsetninger med leietakeromfang.

Det første nyttige trinnet er ikke en omskrivning. Legg til cache-observabilitet til de lengste ledetekstene dine, identifiser prefiksavbrudd, og lo malene som forårsaker flest feil. Når du kan forklare bufferoppførsel, kan du trygt optimalisere den.

Relatert lesing

• bygg bufferbevisste kategorier inn i faktureringsreskontro
• bli med i bufferberegninger med trygge LLM observerbarhet
• hold hentingskonteksten leietaker-omfanget i RAG-arbeidsbelastninger