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

Hitro 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 vedenja 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: sestava poziva za zlom predpomnilnika

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

Pogosti zlomilci predpomnilnika vključujejo:

• Metapodatki posamezne zahteve 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 pravilniki za večkratno uporabo ali bloki orodij.
• Nestabilna serializacija orodij: 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 stabilnimi sistemskimi navodili ali kontekstom skupnega repozitorija.
• Odmik 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 pogodbo o takojšnjem 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: Antropično predpomnjenje poziva lahko zahtevate s 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: predpomnjenje konteksta Google Gemini razkriva štetje žetonov zadetkov v predpomnilniku prek metapodatkov o uporabi, kot je total_cached_tokens, njegova dokumentacija pa navaja najmanjše število vhodnih žetonov glede na model.
• Posledica nadzora podatkov: Dokumentacija API-ja OpenAI za nadzor podatkov ugotavlja, da razširjeno predpomnjenje pozivov zahteva shranjevanje tenzorjev ključ/vrednost kot stanje aplikacije v lokalnem pomnilniku GPE. Tudi če ponudniki zagotavljajo izolacijo, bi morali prehodi obnašanje 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 najemnikov.

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

Pogodba o takojšnji montaži za tri regije

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

Območje 1: 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 za kodiranje;
• popravljena navodila za izhodni format.

Ta regija mora biti deterministična. Prehod bi ga moral zgraditi iz predlog z različicami, kanoničnega JSON in stabilnih pravil za naročanje. Če je vključen register orodij, razvrstite orodja po stabilnem ID-ju orodja. Če so vključene sheme JSON, 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 stranko;
• 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:

• sporočilo uporabnika;
• pridobljene izrezke za to poizvedbo;
• trenutni časovni žig, če je resnično potreben;
• ID zahteve in metapodatki o sledenju, če so sploh vključeni v poziv;
• kratkotrajni pogovor se obrne;
• rezultati izvajalnega orodja.

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

Vzorec implementacije: graditelji s stabilnimi predponami

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

{
  "template_id": "code-agent-v3",
  "tenant_id": "najemnik_123",
  "route": "coding-long-context",
  "stabilna_predpona": {
    "system_policy_version": "2026-08-01",
    "toolset_version": "tools-v12",
    "repo_context_version": "repo-map-8491"
  },
  "polstabilen_kontekst": {
    "workspace_policy_version": "workspace-44-v6"
  },
  "nestanovitna_pripona": {
    "user_message": "Pojasnite, zakaj ta test ne uspe ...",
    "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:

• zavrniti časovne žige v stabilnih poljih predpone;
• kanonizirati sheme orodij;
• razprši vsako regijo posebej;
• priložite kontrolnike predpomnilnika, kjer jih ponudnik podpira;
• ohraniti semantiko poziva med poznejšim premikanjem nestanovitnega materiala;
• snemajte predlogo in predpono prstnih odtisov za diagnostiko.

Za podedovane aplikacije, ki pošiljajo samo 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 verjetnih zlomilcih predpomnilnika, ne da bi prvotno prepisali poziv.

Sloj vmesnika ponudnika: normalizirajte 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": "najemnik_123",
  "app_id": "kodni agent",
  "route": "coding-long-context",
  "ponudnik": "ime_ponudnika",
  "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": "efemerno_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 za pisanje v predpomnilnik: žetoni, ki so ustvarili ali osvežili vnos v predpomnilnik na strani ponudnika, ko ponudnik sporoči to razliko.
• Žetoni za branje predpomnilnika: žetoni, dostavljeni iz predpomnilnika ali metapodatki o uporabi ponudnika štejejo kot predpomnjeni.
• 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 le prikaz skupnega števila 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;
• stabilno zgoščevanje predpone;
• razpršitev polstabilnega konteksta;
• Ključ API ali storitveni račun, kjer je primerno;
• časovno okno, zlasti zato, ker so TTL predpomnilnika kratki za veliko delovnih obremenitev.

Uporabne izpeljane meritve vključujejo:

• Stopnja branja predpomnilnika: predpomnjeni vhodni žetoni, deljeno s skupnim številom vhodnih žetonov, primernih za predpomnilnik.
• Odliv predpone: število različnih 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 vnos brez predpomnilnika za prvo zahtevo v nizu.
• Primerjava poti: stopnje zadetkov med ponudnikovimi potmi za isto 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 kontrole dostopa in omejitve hrambe.

Politika izolacije najemnikov: ne načrtujte 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: usmerite promet, 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čunajte prstne odtise z obsegom najemnika, vključenim v glavno knjigo prehodov, tudi če je upodobljeno besedilo enako.
• Kontrole na ravni organizacije: omogočajo skrbnikom, da onemogočijo funkcije predpomnilnika ponudnika za občutljive delovne obremenitve.
• Izolacija ponudnika ni funkcija izdelka za preprodajo: obravnavajte izolacijo predpomnilnika ponudnika kot osnovno zaščito, ne kot dovoljenje za ustvarjanje združevanja predpomnilnika med strankami.

Predvidevanje: 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

Hitro predpomnjenje lahko oteži razumevanje računov, č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;
4. izhodni žetoni;
5. stroški TTL ali nadzora predpomnilnika, specifični za ponudnika.

To je pomembno, ko en ponudnik popusti na predpomnjena branja, drugi drugače zaračunava pisanje v predpomnilnik, tretji pa izpostavi daljšo možnost 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 podala 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 uspešnosti predpomnilnika na ravni predloge ločeno od računov najemnikov.

Kontrolni seznam 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 vmesnika, ne pa logike razpršene aplikacije.
• Beleženje neobdelanega poziva je privzeto onemogočeno ali zaščiteno s strogimi pravili hrambe in dostopa.

Načrt uvajanja

1. Upoštevajte, preden spremenite pozive

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 predpon.

2. Razvrstite 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 pragom ponudnika morda ne bodo koristili.

3. Predstavite graditelje stabilne predpone

Premaknite eno delovno obremenitev iz neobdelane gradnje pozivov v 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 prihrankov, dokler se računi ponudnika ne uskladijo z glavnimi knjigami prehoda.

5. Uveljavite postopoma

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

Kompromisi

• Višja stopnja zadetkov v predpomnilniku v primerjavi s prilagodljivostjo takojšnjega poziva: stabilne predpone izboljšajo ponovno uporabo, vendar bodo ekipe morda morale pozneje premakniti dinamična navodila ali preoblikovati predloge.
• Izvorno predpomnilnik ponudnika v primerjavi s prenosljivostjo: uporaba kontrolnikov 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: pozivne razlike pomagajo odpravljati napake, 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: daljše možnosti TTL lahko pomagajo sejam agentov, vendar lahko uvedejo drugačne premisleke glede cen in nadzora podatkov.

Dejanski sklep

Obravnavajte predpomnjenje pozivov kot težavo z nadzorno ravnino 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

• v glavno knjigo obračunov vgradite kategorije, ki poznajo predpomnilnik
• združi meritve predpomnilnika z varno opazovalnostjo LLM
• ohranjanje konteksta pridobivanja v obsegu najemnika v delovnih obremenitvah RAG