Nadzor takojšnjega predpomnilnika v prehodu API-ja z več modeli: stabilne predpone, izolacija najemnika in analiza zadetkov predpomnilnika

Pozivno predpomnjenje je enostavno zapraviti. Ekipa ima lahko sistemski poziv s 40.000 žetoni, shemo orodja, blok pravilnika, zemljevid repozitorija ali pomnilnik agenta, ki bi ga bilo treba ponovno uporabiti, nato pa pomotoma postavi časovni žig, ID zahteve, uporabniško ime, izrezek za pridobitev ali naključno vrstni red orodja blizu vrha poziva. Ponudnik vidi drugo predpono, predpomnilnik je zgrešen, zakasnitev se poveča in račun je videti zmeden.

V aplikaciji enega ponudnika lahko to popravite znotraj predloge aplikacije. Pri prehodu z več modeli je težava večja: vsak ponudnik izpostavi različne kontrole predpomnilnika, pragove žetonov, vedenje časa do življenja, polja uporabe in semantiko zaračunavanja. Prehod potrebuje prenosni vzorec nadzorne ravnine za sestavljanje pozivov, varnih pred predpomnilnikom, merjenje obnašanja predpomnilnika, izolacijo najemnikov in pripisovanje stroškov.

Ta članek opisuje referenčno arhitekturo. To ni študija primera stranke in ne zahteva primerjalnih rezultatov. Spodnja dejstva izhajajo iz dokumentacije ponudnika in javne raziskave; priporočila za načrtovanje so navodila za delovanje na ravni prehoda.

Način napake: pozivni sklop za zlom predpomnilnika

Predpomnilnik poziva na splošno nagrajuje ponavljajoče se predpone poziva. Natančna mehanika se razlikuje glede na ponudnika, vendar je praktična implikacija dosledna: če se sprednja stran poziva spremeni, trpi ponovna uporaba.

Pogosti prekinjevalci predpomnilnika vključujejo:

• Metapodatki na zahtevo na vrhu: časovni žigi, ID-ji sledenja, ID-ji sej, ID-ji uvajanja ali ustvarjene oznake zahtev.
• Uporabniško specifični podatki v predponi: imena, atributi računa, dovoljenja ali zasebne nastavitve pred pravilnikom za večkratno uporabo ali bloki orodij.
• Nestabilna serializacija orodja: sheme orodij, oddane v nedeterminističnem vrstnem redu, s spreminjajočimi se presledki ali ustvarjenimi ID-ji.
• Izrezki za pridobivanje prezgodaj: Kontekst RAG je vstavljen pred stabilna sistemska navodila ali kontekst deljenega repozitorija.
• Premik predloge: majhne spremembe besedila, ki se pogosto izdajo brez različic ali diagnostike predpomnilnika.

Prehod ne more magično omogočiti predpomnjenja nestabilne predpone, lahko pa uveljavi takojšnjo pogodbo o sestavljanju in naredi vidne napake predpomnilnika.

Dejstva ponudnika, ki jih je treba oblikovati

Podrobnosti so pomembne, ker mora prehod normalizirati vedenje, ne da bi se pretvarjal, da so ponudniki identični.

• OpenAI: OpenAI je dokumentiral predpomnjenje poziva za najdaljšo predhodno izračunano predpono poziva. Začne se pri 1024 žetonih, povečuje se v korakih po 128 žetonov in razkrije predpomnjena števila žetonov v poljih uporabe. OpenAI tudi navaja, da se predpomnilniki pozivov običajno počistijo po 5–10 minutah nedejavnosti in so vedno odstranjeni v eni uri po zadnji uporabi predpomnilnika.
• Anthropic: Anthropic predpomnjenje poziva lahko zahtevate z cache_control. Njegova dokumentacija opisuje ujemanje predpomnilnika prek komponent poziva, kot so orodja, sistemska vsebina in sporočila do bloka, označenega z nadzorom predpomnilnika. Anthropic dokumentira efemerni predpomnilnik, vključno s 5-minutnim trajanjem in 1-urno možnostjo za doplačilo.
• Gemini: Google Gemini kontekstno predpomnjenje izpostavlja štetje žetonov zadetkov v predpomnilniku prek metapodatkov o uporabi, kot je total_cached_tokens, njegova dokumentacija pa navaja minimalna števila vhodnih žetonov glede na model.
• Posledica nadzora podatkov: Dokumentacija o nadzoru podatkov OpenAI API ugotavlja, da razširjeno predpomnjenje pozivov zahteva shranjevanje tenzorjev ključ/vrednost kot stanje aplikacije v lokalnem pomnilniku GPU. Tudi če ponudniki zagotavljajo izolacijo, bi morali prehodi vedenje predpomnilnika obravnavati kot občutljivo infrastrukturo, ne kot skupno shrambo podatkov aplikacij.
• Raziskovalni signal: Javna raziskava je preučila, ali lahko arhitekture v slogu prehodov povzročijo ranljivosti hitrega predpomnjenja, ki zaobidejo predpostavke o izolaciji predpomnilnika na ravni ponudnika. To ne dokazuje, da je določen prehod ranljiv, vendar podpira konzervativno zasnovo izolacije najemnika.

Priporočilo: implementirajte nadzor predpomnilnika kot funkcijo prehoda z izrecnimi pravilniki, ne kot naključni stranski učinek ponavljajočih se pozivov.

Pogodba za hitro sestavljanje v treh regijah

Najpomembnejša oblikovalska odločitev je ločiti stabilno in nestanovitno vsebino, preden zahteva doseže vmesnik ponudnika.

1. regija: stabilna predpona

Stabilna predpona je vsebina, za katero se pričakuje, da bo ostala enaka v številnih zahtevah za isto aplikacijo, model poti in različico predloge poziva. Primeri vključujejo:

• osnovna sistemska navodila;
• varnostni in politični bloki;
• sheme orodij;
• statična dokumentacija izdelka;
• preslikave skladišč za agente kodiranja;
• popravljena navodila za izhodni format.

Ta regija mora biti deterministična. Prehod bi ga moral zgraditi iz predlog z različicami, kanonikiziranih JSON in pravil stabilnega razvrščanja. Če je vključen register orodij, razvrstite orodja po stabilnem ID-ju orodja. Če so vključene JSON sheme, jih serializirajte z determinističnim vrstnim redom ključev in brez ustvarjenih časovnih žigov.

2. regija: polstabilni najemnik ali kontekst delovnega prostora

Polstabilna regija se spreminja manj pogosto kot posamezne zahteve, vendar se ne deli globalno. Primeri vključujejo:

• preglasitve pravilnika, specifičnega za najemnika;
• dovoljeni seznami orodij na ravni delovnega prostora;
• terminologija, specifična za stranke;
• konvencije skupinskega kodiranja;
• dolgoživ kontekst projekta.

To območje mora biti omejeno na najemnika, delovni prostor ali mejo aplikacije. Morda ga je še vedno mogoče predpomniti, vendar prehod ne sme nikoli domnevati, da ga lahko drug najemnik varno ponovno uporabi.

Območje 3: nestanovitna pripona

Hlapljiva pripona je del na zahtevo:

• uporabniško sporočilo;
• pridobljeni izrezki za to poizvedbo;
• trenutni časovni žig, če je res potreben;
• ID zahteve in metapodatki o sledenju, če so sploh vključeni v poziv;
• kratkotrajni pogovor se spremeni;
• rezultati orodja za izvajanje.

Večina zgrešenih predpomnilnikov, ki jih povzroči zasnova aplikacije, se zgodi, ker so nestanovitni podatki pripone pomotoma vstavljeni v predpono. Graditelj na strani prehoda bi moral to otežiti.

Implementacijski vzorec: graditelji s stabilnimi predponami

Praktična izvedba prehoda lahko izpostavi vmesnik za hitro sestavljanje, namesto da bi sprejela en neprozoren pozivni niz iz vsake aplikacije.

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

Prehod nato upodobi zahtevo, specifično za ponudnika. To daje prehodu mesto za uveljavljanje pravil:

• zavrni časovne žige v stabilnih poljih predpone;
• kanoniziraj sheme orodij;
• zgosti vsako regijo posebej;
• priložite kontrolnike predpomnilnika, kjer jih ponudnik podpira;
• ohrani semantiko poziva med poznejšim premikanjem nestanovitnega materiala;
• zapis predloge in predpone prstnih odtisov za diagnostiko.

Za podedovane aplikacije, ki pošiljajo le neobdelana sporočila, lahko prehod še vedno zagotovi način lint: preglejte vrstni red sporočil, izračunajte prstne odtise predpone in poročajte o morebitnih zlomilcih predpomnilnika, ne da bi prvotno prepisali poziv.

Sloj vmesnika ponudnika: normalizira uporabo predpomnilnika brez skrivanja razlik

Prehod z več modeli razvijalcem ne bi smel razkriti treh nepovezanih poročil o predpomnilniku. Prav tako ne bi smel tako agresivno izravnati ekonomije posameznega ponudnika, da bi računov postalo nemogoče razložiti.

Ustvarite normalizirano knjigo predpomnilnika s polji, kot so:

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

Vmesnik preslika uporabo ponudnika v normalizirane kategorije:

• Vhodni žetoni brez predpomnilnika: žetoni, obdelani brez popusta za branje predpomnilnika ali upoštevanja branja predpomnilnika.
• Žetoni pisanja v predpomnilnik: žetoni, ki so ustvarili ali osvežili vnos predpomnilnika na strani ponudnika, ko ponudnik sporoči to razliko.
• Žetoni za branje v predpomnilniku: žetoni, ki se strežejo iz predpomnilnika ali jih metapodatki o uporabi ponudnika štejejo za predpomnjene.
• Izhodni žetoni: ustvarjeni žetoni, ki morajo ostati ločeni od ekonomije hitrega predpomnilnika.
• Možnost TTL: izbrani razred trajanja predpomnilnika, kjer ponudnik izpostavi izbiro.

Priporočilo: shranite neobdelano uporabo ponudnika v redigirani obliki z različico sheme poleg normaliziranih polj. Normalizacija je uporabna za nadzorne plošče; neobdelana polja so potrebna za uskladitev, ko se semantika ponudnika spremeni.

Opazljivost predpomnilnika: nadzorne plošče, ki pojasnjujejo napake

Uporabna nadzorna plošča predpomnilnika naredi več kot samo prikaz vseh predpomnjenih žetonov. Ekipam bi morala pomagati pri odgovoru: »Katera delovna obremenitev pokvari predpono in kaj se je spremenilo?«

Sledenje meritvam predpomnilnika po:

• najemnik;
• delovni prostor ali aplikacija;
• model poti;
• ponudnik in model;
• različica predloge poziva;
• zgoščevanje stabilne predpone;
• polstabilno zgoščevanje konteksta;
• API ključ ali storitveni račun, kjer je primerno;
• časovno okno, še posebej zato, ker so TTL predpomnilnika kratki za veliko delovnih obremenitev.

Uporabne izpeljane meritve vključujejo:

• Stopnja branja predpomnilnika: predpomnjeni vhodni žetoni deljeni s skupnim številom vhodnih žetonov, primernih za predpomnjenje.
• Prefix churn: število ločenih stabilnih zgoščenih predpon na različico predloge na uro.
• Odmik predloge: spremembe zadetkov predpomnilnika po izdaji predloge.
• Stroški hladnega zagona: poraba pisanja v predpomnilnik ali nepredpomnjenega vnosa za prvo zahtevo v nizu.
• Primerjava poti: stopnje zadetkov med ponudnikovimi potmi za enako logično delovno obremenitev.

Ne privzeto shranjevaj neobdelanih pozivov za odpravljanje napak. Prednostne zgoščene vrednosti, dolžine regij, ID-je predlog, opozorila o kanonikalizaciji in redigirane razlike. Če ekipa potrebuje globlje odpravljanje napak, zahtevajte izrecne nadzore dostopa in omejitve hrambe.

Politika izolacije najemnikov: ne oblikujte za ponovno uporabo med najemniki

Predpostavka o najvarnejšem prehodu je preprosta: vedenje, ki ga je mogoče predpomniti, mora biti omejeno na najemnika. Tudi če si dva najemnika delita enak blok javnih pravil, prehod ne sme namerno usmerjati ali oblikovati prometa za izkoriščanje ponovne uporabe predpomnilnika med najemniki.

Konzervativna politika vključuje:

• Usmerjanje glede na najemnika: usmerjanje prometa, ki ga je mogoče predpomniti, z uporabo meja najemnika, delovnega prostora in aplikacije.
• Brez predpon, ki nosijo skrivnost v skupni rabi: nikoli ne postavljajte skrivnosti najemnika, poverilnic, zasebnih dokumentov ali uporabniško specifičnih podatkov v predpono v skupni rabi za večkratno uporabo.
• Ločeni prstni odtisi predpone: izračuna prstne odtise z obsegom najemnika, vključenim v glavno knjigo prehodov, tudi če je upodobljeno besedilo enako.
• Kontrolniki na ravni organizacije: skrbnikom omogočajo, da onemogočijo funkcije predpomnilnika ponudnika za občutljive delovne obremenitve.
• Izolacija ponudnika ni funkcija izdelka za nadaljnjo prodajo: obravnavajte izolacijo predpomnilnika ponudnika kot osnovno zaščito, ne kot dovoljenje za ustvarjanje združevanja predpomnilnika med strankami.

Napoved: ko bodo agenti z dolgim kontekstom vse pogostejši, bo vedenje predpomnilnika postalo del varnostnih pregledov, ne le pregledov stroškov. Prehode, ki lahko dokažejo politiko predpomnilnika v obsegu najemnika, bo lažje upravljati.

Dodeljevanje zaračunavanja: ločeno branje predpomnilnika, pisanje in običajni žetoni

S takojšnjim predpomnjenjem so lahko računi težje razumljivi, če so vsi vhodni žetoni prikazani kot ena številka. Obračunska knjiga mora ohraniti vsaj pet kategorij:

1. nepredpomnjeni vhodni žetoni;
2. predpomnilnik pisalnih žetonov;
3. predpomnilnik za branje žetonov;
4. izhodni žetoni;
5. stroški TTL ali nadzora predpomnilnika, specifični za ponudnika.

To je pomembno, ko en ponudnik popusti pri branju v predpomnilniku, drugi drugače zaračuna pisanje v predpomnilnik, tretji pa izpostavi možnost daljšega TTL. Na računu stranke bi moralo biti razloženo, zakaj sta imeli dve zahtevi s podobnimi skupnimi vhodnimi žetoni različne stroške.

Za interno povratno bremenitev pripišite učinke predpomnilnika najemniku in aplikaciji, ki je poslala zahtevo. Izogibajte se dodeljevanju prednosti branja predpomnilnika od enega najemnika drugemu. Če je stabilna predloga poziva v lasti skupine za skupno interno platformo, poročajte o zmogljivosti predpomnilnika na ravni predloge ločeno od računov najemnikov.

Kontrolni seznam za linting predpomnilnika

Preden omogočite uveljavljanje predpomnilnika, zaženite predloge pozivov prek kontrolnega seznama lint:

• Navodila za stabilen sistem se prikažejo pred nestanovitnim vnosom uporabnika.
• Sheme orodij so razvrščene po stabilnem ID-ju ali imenu.
• JSON je serializiran deterministično.
• V stabilni predponi niso prikazani nobeni časovni žigi, naključni ID-ji, ID-ji zahtev ali ID-ji sledenja.
• V blokih za večkratno uporabo v skupni rabi niso prikazane nobene uporabniško specifične skrivnosti.
• Izrezki RAG so postavljeni za razdelke s pravilniki in orodji za večkratno uporabo, razen če obstaja namenski razlog, da tega niso.
• Predloge pozivov imajo eksplicitne različice.
• Izdaje predlog je mogoče povezati s spremembami stopnje zadetkov predpomnilnika.
• Kontrolniki predpomnilnika ponudnika se uporabljajo samo prek kode adapterja, ne pa logike razpršene aplikacije.
• Neobdelano beleženje pozivov je privzeto onemogočeno ali zaščiteno s strogimi pravili hrambe in dostopa.

Načrt uvajanja

1. Upoštevajte, preden spremenite poziv

Začnite z zbiranjem polj uporabe ponudnika in normaliziranih meritev predpomnilnika za obstoječi promet. Izračunajte prstne odtise predpone za prvih N žetonov ali za območja pozivov, ki jih definira prehod. Cilj je najti poti z velikim obsegom in dolgim kontekstom z velikim odlivom predpone.

2. Razvrsti delovne obremenitve

Združite promet v kategorije: seje agentov, pomočniki kodiranja, RAG, avtomatizacija podpore, analiza dokumentov, paketna opravila in kratek klepet. Delo s hitrim predpomnilnikom običajno posveča največ pozornosti delovnim obremenitvam z dolgim ​​kontekstom in ponavljajočo se predpono. Kratki pozivi pod pragovi ponudnika morda ne bodo koristili.

3. Predstavite graditelje stabilne predpone

Premik ene delovne obremenitve iz neobdelane gradnje poziva na sestavljanje na podlagi regije. Upodobljena zahteva ponudnika naj bo pomensko enakovredna. Ne kombinirajte te spremembe s selitvijo modela, preoblikovanjem orodij ali večjimi hitrimi prepisi, sicer ne boste vedeli, kaj je povzročilo spremembe meritev.

4. Canary one route

Omogoči nadzor predpomnilnika za majhen del enega najemnika ali notranje aplikacije. Primerjajte stopnjo branja predpomnilnika, odliv predpone, čas do prvega žetona, stopnjo napak in kategorije stroškov. Izogibajte se zahtevam za prihranke, dokler se računi ponudnika ne uskladijo z glavnimi knjigami prehoda.

5. Uveljavi postopoma

Po kanarčku spremenite opozorila o vlaknih v preverjanje pravilnika. Na primer, najprej opozori na nestabilno zaporedje orodij, nato pa zavrni nove različice predlog, ki vključujejo spremenljive metapodatke v stabilni predponi.

Kompromisi

• Višja stopnja zadetkov predpomnilnika v primerjavi s prilagodljivostjo poziva: stabilne predpone izboljšajo ponovno uporabo, vendar bodo ekipe morda morale pozneje premakniti dinamična navodila ali preoblikovati predloge.
• Izvorno predpomnjenje ponudnika v primerjavi s prenosljivostjo: uporaba kontrol predpomnilnika vsakega ponudnika lahko izboljša ekonomičnost, vendar se pragovi, TTL-ji, polja in semantika cen razlikujejo.
• Opazljivost v primerjavi z občutljivim beleženjem: razlike v pozivih pomagajo pri odpravljanju napak, vendar so zgoščene vrednosti in redigirana diagnostika varnejše privzete vrednosti.
• Izolacija najemnika v primerjavi z največjo ponovno uporabo: široka ponovna uporaba je morda videti privlačna, vendar je vedenje v obsegu najemnika varnejše in ga je lažje razložiti.
• Daljša hramba v primerjavi s stroški in kompleksnostjo pravilnika: možnosti daljšega TTL lahko pomagajo sejam agentov, vendar lahko uvedejo drugačne premisleke glede cen in nadzora podatkov.

Dejanski sklep

Obravnavajte predpomnjenje pozivov kot težavo nadzorne ravnine prehoda in ne kot potrditveno polje ponudnika. Praktični vzorec je: definirajte stabilna, polstabilna in nestanovitna hitra območja; jih upodablja deterministično; prilagodite kontrole predpomnilnika, specifične za ponudnika, za enim vmesnikom; normalizira uporabo predpomnilnika v glavno knjigo; izpostavite diagnostiko zadetkov v predpomnilniku glede na najemnika, aplikacijo, pot in različico predloge; in uveljaviti predpostavke v obsegu najemnika.

Prvi uporaben korak ni ponovno pisanje. Svojim najdaljšim pozivom dodajte možnost opazovanja predpomnilnika, prepoznajte odliv predpone in poiščite predloge, ki povzročajo največ napak. Ko razložite vedenje predpomnilnika, ga lahko varno optimizirate.

Sorodno branje

• zgradite kategorije, ki poznajo predpomnilnik, v knjigo obračunavanja
• združite meritve predpomnilnika z varnim LLM opazljivost
• ohranjanje konteksta pridobivanja v obsegu najemnika v delovnih obremenitvah RAG