Control prompt al memoriei cache într-un gateway API cu mai multe modele: prefixe stabile, izolarea chiriașilor și analiză cache-hit

Memorizarea promptă în cache este ușor de irosit. O echipă poate avea un prompt de sistem de 40.000 de jetoane, o schemă de instrumente, un bloc de politici, o hartă de depozit sau o memorie de agent care ar trebui să fie reutilizată, apoi să pună accidental un marcaj temporal, un ID de solicitare, un nume de utilizator, un fragment de recuperare sau o comandă aleatorie a instrumentului în partea de sus a solicitării. Furnizorul vede un prefix diferit, memoria cache este ratată, latența crește și factura pare confuză.

Într-o aplicație cu un singur furnizor, puteți remedia acest lucru în șablonul de aplicație. Într-un gateway cu mai multe modele, problema este mai mare: fiecare furnizor expune diferite controale ale cache-ului, praguri de token, comportamentul time-to-live, câmpuri de utilizare și semantică de facturare. Gateway-ul are nevoie de un model portabil de plan de control pentru asamblarea solicitărilor sigure pentru cache, măsurarea comportamentului memoriei cache, izolarea chiriașilor și atribuirea costurilor.

Acest articol descrie o arhitectură de referință. Nu este un studiu de caz pentru clienți și nu pretinde rezultate de referință. Faptele de mai jos provin din documentația furnizorului și din cercetările publice; recomandările de proiectare sunt ghiduri de operare la nivel de gateway.

Modul de eroare: asamblare promptă de rupere cache

Memorizarea promptă în cache recompensează în general prefixele repetate de prompt. Mecanismul exact variază în funcție de furnizor, dar implicația practică este consistentă: dacă partea frontală a promptului se modifică, reutilizarea are de suferit.

Defectele obișnuite ale memoriei cache includ:

• Metadate per solicitare în partea de sus: marcaje temporale, ID-uri de urmărire, ID-uri de sesiune, ID-uri de implementare sau etichete de solicitare generate.
• Date specifice utilizatorului din prefix: nume, atribute de cont, permisiuni sau preferințe private plasate înaintea politicilor reutilizabile sau a blocurilor de instrumente.
• Serializare instabilă a instrumentului: scheme de instrumente emise în ordine nedeterministă, cu spații albe modificate sau ID-uri generate.
• Fragmente de preluare prea devreme: contextul RAG a fost inserat înaintea instrucțiunilor de sistem stabile sau a contextului de depozit partajat.
• Derivarea șablonului: mici modificări de formulare sunt lansate frecvent fără diagnosticare de versiuni sau cache.

Un gateway nu poate face ca un prefix instabil să fie stocat în cache, dar poate impune un contract de asamblare promptă și poate face vizibile erorile de cache.

Oferiți informații despre care să creați

Detaliile contează deoarece un gateway trebuie să normalizeze comportamentul fără a pretinde că furnizorii sunt identici.

• OpenAI: OpenAI a documentat memorarea în cache a promptului pentru cel mai lung prefix de prompt calculat anterior. Începe de la 1.024 de jetoane, crește în incremente de 128 de jetoane și expune numărul de jetoane stocate în cache în câmpurile de utilizare. OpenAI afirmă, de asemenea, că memoriile cache sunt de obicei șterse după 5-10 minute de inactivitate și sunt întotdeauna eliminate în termen de o oră de la ultima utilizare a memoriei cache.
• Antropic: Memorarea în cache a promptului antropic poate fi solicitată cu cache_control. Documentația sa descrie potrivirea memoriei cache pe componente prompte, cum ar fi instrumente, conținut de sistem și mesaje până la blocul marcat cu controlul cache. Anthropic documentează o memorie cache efemeră, inclusiv o durată de 5 minute și o opțiune de 1 oră la un cost suplimentar.
• Gemeni: stocarea în cache a contextului Google Gemini expune numărul de jetoane accesate în cache prin metadate de utilizare, cum ar fi total_cached_tokens, iar documentația sa listează numărul minim de jetoane de intrare în funcție de model.
• Implicație pentru controlul datelor: documentația OpenAI pentru controlul datelor API notează că stocarea în cache extinsă a promptului necesită stocarea tensoarelor cheie/valoare ca stare a aplicației în stocarea locală GPU. Chiar și atunci când furnizorii mențin garanții de izolare, gateway-urile ar trebui să trateze comportamentul cache-ului ca infrastructură sensibilă, nu ca un depozit de date de aplicație partajat.
• Semnal de cercetare: cercetările publice au examinat dacă arhitecturile tip gateway pot introduce vulnerabilități de stocare în cache promptă care ocolesc ipotezele de izolare a memoriei cache la nivel de furnizor. Acest lucru nu dovedește că un anumit gateway este vulnerabil, dar acceptă un design conservator de izolare a chiriașilor.

Recomandare: implementați controlul memoriei cache ca o funcție de poartă cu politici explicite, nu ca efect secundar accidental al solicitărilor repetate.

Un contract de asamblare promptă pentru trei regiuni

Cea mai importantă decizie de proiectare este separarea conținutului stabil și volatil înainte ca solicitarea să ajungă la un adaptor de furnizor.

Regiune 1: prefix stabil

Prefixul stabil este conținutul care se așteaptă să rămână identic în multe solicitări pentru aceeași aplicație, rută model și versiune de șablon prompt. Exemplele includ:

• instrucțiuni de bază ale sistemului;
• blocuri de siguranță și politici;
• scheme de instrumente;
• documentația statică a produsului;
• hărți de depozit pentru agenții de codare;
• instrucțiuni cu format de ieșire fix.

Această regiune ar trebui să fie deterministă. Gateway-ul ar trebui să îl construiască din șabloane versiuni, JSON canonizat și reguli de ordonare stabile. Dacă este inclus un registru de instrumente, sortați instrumentele după ID-ul instrumentului stabil. Dacă sunt incluse scheme JSON, serializați-le cu o ordine deterministă a cheilor și fără marcaje temporale generate.

Regiunea 2: chiriaș semi-stabil sau context de spațiu de lucru

Regiunea semi-stabilă se schimbă mai rar decât solicitările individuale, dar nu este partajată la nivel global. Exemplele includ:

• politicile specifice locatarului sunt anulate;
• liste permise de instrumente la nivel de spațiu de lucru;
• terminologia specifică clientului;
• convențiile de codificare a echipei;
• context de proiect de lungă durată.

Această regiune ar trebui să fie acoperită cu un chiriaș, un spațiu de lucru sau o limită de aplicație. Poate fi încă memorabil în cache, dar gateway-ul nu ar trebui să presupună că un alt chiriaș îl poate reutiliza în siguranță.

Regiunea 3: sufix volatil

Sufixul volatil este porțiunea pe cerere:

• mesajul utilizatorului;
• fragmente preluate pentru această interogare;
• marca temporală actuală, dacă este cu adevărat necesar;
• ID de solicitare și metadate de urmărire, dacă sunt incluse în solicitare;
• turduri de conversație pe termen scurt;
• rezultatele instrumentului de rulare.

Majoritatea erorilor de memorie cache cauzate de proiectarea aplicației se întâmplă deoarece datele sufixelor volatile sunt plasate accidental în prefix. Un constructor de la gateway ar trebui să facă acest lucru dificil.

Model de implementare: constructori de prefix stabil

O implementare practică de gateway poate expune o interfață de asamblare promptă în loc să accepte un șir de prompt opac din fiecare aplicație.

{
  "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"
  },
  „sufix_volatil”: {
    "user_message": "Explicați de ce acest test eșuează...",
    "retrieval_context_ids": ["buncă_7", "bloc_19"],
    "trace_id": "not_inserted_into_prompt"
  }
}

Gateway-ul redă apoi cererea specifică furnizorului. Acest lucru oferă gateway-ului un loc pentru a aplica regulile:

• respingeți marcajele de timp în câmpurile stabile de prefix;
• canonizarea schemelor de instrumente;
• Hash fiecare regiune separat;
• atașați comenzile cache acolo unde un furnizor le acceptă;
• păstrați semantica promptă în timp ce mutați materialul volatil mai târziu;
• înregistrați șablonul și amprentele de prefix pentru diagnosticare.

Pentru aplicațiile vechi care trimit numai mesaje brute, gateway-ul poate oferi în continuare un mod de scame: inspectați ordinea mesajelor, calculați amprentele prefixelor și raportați posibilele întreruperi ale memoriei cache fără a rescrie promptul inițial.

Stratul adaptor furnizor: normalizați utilizarea memoriei cache fără a ascunde diferențele

Un gateway cu mai multe modele nu ar trebui să expună dezvoltatorilor trei rapoarte de cache care nu au legătură. De asemenea, nu ar trebui să aplatizeze economia specifică furnizorului atât de agresiv încât facturile să devină imposibil de explicat.

Creați un registru cache normalizat cu câmpuri precum:

{
  "request_id": "req_abc",
  "tenant_id": "tenant_123",
  "app_id": "agent de cod",
  "route": "coding-long-context",
  "provider": "nume_furnizor",
  "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"
  }
}

Adaptorul mapează utilizarea furnizorului în categorii normalizate:

• Jetoane de intrare neînregistrate în cache: jetoane procesate fără o reducere la citirea cache sau o contabilitate pentru citirea cache.
• Jetoane de scriere în cache: indicative care au creat sau au reîmprospătat o intrare în memoria cache la nivelul furnizorului atunci când furnizorul raportează această distincție.
• Jetoane de citire în cache: indicative furnizate din cache sau contorizate ca stocate în cache de metadatele de utilizare ale furnizorului.
• Jetoane de ieșire: jetoane generate, care ar trebui să rămână separate de economia cache-ului prompt.
• Opțiune TTL: clasa de durată a memoriei cache selectată la care furnizorul expune o alegere.

Recomandare: stocați utilizarea brută a furnizorului într-o formă redactată, cu versiunea schemei, alături de câmpurile normalizate. Normalizarea este utilă pentru tablouri de bord; câmpurile brute sunt necesare pentru reconciliere atunci când semantica furnizorului se schimbă.

Observabilitatea memoriei cache: tablouri de bord care explică erorile

Un tablou de bord util pentru cache face mai mult decât să arate numărul total de jetoane stocate în cache. Ar trebui să ajute echipele să răspundă: „Ce sarcină de lucru încalcă prefixul și ce s-a schimbat?”

Urmăriți valorile cache prin:

• chiriaș;
• spațiu de lucru sau aplicație;
• model de traseu;
• furnizor și model;
• versiunea șablonului prompt;
• hash prefix stabil;
• hash de context semi-stabil;
• Cheie API sau cont de serviciu, după caz;
• fereastră de timp, în special pentru că TTL-urile cache sunt scurte pentru multe sarcini de lucru.

Valorile derivate utile includ:

• Rata de citire a memoriei cache: jetoane de intrare stocate în cache împărțite la numărul total de jetoane de intrare eligibile pentru stocare în cache.
• Renunțare la prefix: numărul de hashuri stabile distincte de prefix per versiune de șablon pe oră.
• Derivarea șablonului: se modifică accesarea în cache după lansarea unui șablon.
• Cost de pornire la rece: scrierea în cache sau cheltuielile de intrare necache pentru prima solicitare dintr-o explozie.
• Comparație rute: ratele de accesare pe rutele furnizorilor pentru aceeași sarcină de lucru logică.

Nu stocați implicit solicitări brute pentru depanare. Preferați hashurile, lungimile regiunilor, ID-urile șablonului, avertismentele de canonizare și diferențe redactate. Dacă o echipă are nevoie de o depanare mai profundă, necesită controale de acces explicite și limite de păstrare.

Politica de izolare a chiriașilor: nu proiectați pentru reutilizare între chiriași

Cea mai sigură ipoteză a gateway-ului este simplă: comportamentul care poate fi stocat în cache ar trebui să fie vizat de chiriași. Chiar dacă doi chiriași au în comun un bloc de politică publică identic, gateway-ul nu ar trebui să direcționeze sau să modeleze în mod intenționat traficul pentru a exploata reutilizarea memoriei cache între locatari.

O politică conservatoare include:

• Dirutare în funcție de locatar: direcționează traficul care poate fi stocat în cache utilizând limitele locatarului, spațiului de lucru și aplicației.
• Fără prefixe care poartă secrete partajate: nu plasați niciodată secrete ale chiriașului, acreditări, documente private sau date specifice utilizatorului într-un prefix partajat reutilizabil.
• Amprentele digitale de prefix separate: calculează amprentele digitale cu domeniul de aplicare al locatarului inclus în registrul gateway, chiar dacă textul redat este identic.
• Comenzi la nivel de organizație: permit administratorilor să dezactiveze funcțiile de cache ale furnizorului pentru sarcinile de lucru sensibile.
• Izolarea furnizorului nu este o caracteristică de revânzare a produsului: tratați izolarea cache-ului furnizorului ca pe o protecție de bază, nu ca pe o permisiune de a crea un pool de cache pentru mai mulți clienți.

Predicție: pe măsură ce agenții cu context lung devin mai obișnuiți, comportamentul cache-ului va deveni parte din recenziile de securitate, nu doar din recenziile de cost. Gateway-urile care pot dovedi politica de cache la nivelul chiriașilor vor fi mai ușor de guvernat.

Atribuire facturare: citiri, scrieri și simboluri normale în cache separată

Memorizarea promptă în cache poate face facturile mai greu de înțeles dacă toate indicatoarele de intrare sunt afișate ca un număr. Registrul de facturare trebuie să păstreze cel puțin cinci categorii:

1. jetoane de intrare necache;
2. cache write tokens;
3. cache tokens citire;
4. jetoane de ieșire;
5. tarife TTL specifice furnizorului sau de control al memoriei cache.

Acest lucru contează atunci când un furnizor reduce lecturile stocate în cache, altul taxează diferit pentru scrierile în cache, iar altul expune o opțiune TTL mai lungă. O factură de client ar trebui să poată explica de ce două solicitări cu simboluri de intrare totale similare au avut costuri diferite.

Pentru rambursarea internă, atribuiți efectele de cache locatarului și aplicației care a făcut solicitarea. Evitați alocarea unui beneficiu pentru citirea cache-ului de la un chiriaș la altul. Dacă o echipă de platformă internă comună deține șablonul de prompt stabil, raportați performanța memoriei cache la nivel de șablon separat de facturile chiriașilor.

Lista de verificare pentru păstrarea cache-ului

Înainte de a activa aplicarea în cache, rulați șabloanele de prompt printr-o listă de verificare a scame:

• Instrucțiunile stabile ale sistemului apar înaintea intrărilor volatile ale utilizatorului.
• Schemele de instrumente sunt sortate după ID stabil sau nume.
• JSON este serializat determinist.
• Nu apar marcaje temporale, ID-uri aleatorii, ID-uri de solicitare sau ID-uri de urmărire în prefixul stabil.
• Nu apar secrete specifice utilizatorului în blocurile reutilizabile partajate.
• Fragmentele RAG sunt plasate după secțiunile de politici și instrumente reutilizabile, cu excepția cazului în care există un motiv deliberat pentru a nu face acest lucru.
• Șabloanele de promptare au versiuni explicite.
• Versiunile de șabloane pot fi corelate cu modificările ratei de accesare a memoriei cache.
• Controalele cache ale furnizorului sunt utilizate numai prin codul adaptorului, nu prin logica aplicației dispersate.
• Înregistrarea promptă brută este dezactivată în mod prestabilit sau protejată de reguli stricte de păstrare și acces.

Plan de lansare

1. Observați înainte de a schimba solicitările

Începeți prin a colecta câmpuri de utilizare a furnizorilor și valori cache normalizate pentru traficul existent. Calculați amprentele prefixelor pentru primele N jetoane sau pentru regiunile prompt definite de gateway. Scopul este de a găsi rute cu volum mare, cu context lung, cu prefixe ridicate.

2. Clasificați sarcinile de lucru

Grupați traficul în categorii: sesiuni de agenți, asistenți de codare, RAG, automatizare de asistență, analiză de documente, joburi în lot și chat scurt. Lucrarea promptă în cache acordă, de obicei, cea mai mare atenție sarcinilor de lucru în context lung și cu prefixuri repetate. Este posibil ca solicitările scurte sub pragurile furnizorului să nu beneficieze.

3. Introduceți generatori de prefix stabil

Mutați o sarcină de lucru de la construcția promptă brută la asamblarea bazată pe regiune. Păstrați cererea de furnizor redată echivalentă din punct de vedere semantic. Nu combinați această modificare cu migrarea modelului, reproiectarea instrumentului sau rescrierile majore ale promptului, altfel nu veți ști ce a cauzat modificările valorii.

4. Canary one route

Activați comenzile cache pentru o mică parte dintr-un locatar sau aplicație internă. Comparați rata de citire a memoriei cache, rata prefixului, timpul până la primul simbol, rata de eroare și categoriile de cost. Evitați să solicitați economii până când facturile furnizorilor se reconciliază cu registrele gateway.

5. Aplicați treptat

După canar, transformați avertismentele de scame în verificări ale politicii. De exemplu, avertizați mai întâi despre ordinea instabilă a instrumentelor, apoi respingeți noile versiuni de șablon care includ metadate volatile în prefixul stabil.

Compartimente

• Rată mai mare de accesare a memoriei cache față de flexibilitatea promptă: prefixele stabile îmbunătățesc reutilizarea, dar este posibil ca echipele să fie nevoite să mute instrucțiunile dinamice mai târziu sau să reproiecteze șabloanele.
• Memorizarea în cache nativă a furnizorului vs. portabilitate: utilizarea controalelor cache ale fiecărui furnizor poate îmbunătăți economia, dar pragurile, valorile TTL, câmpurile și semantica prețurilor diferă.
• Observabilitate față de înregistrarea sensibilă: diferențele de prompte ajută la depanarea erorilor, dar hashurile și diagnosticele redactate sunt valori prestabilite mai sigure.
• Izolarea chiriașilor vs. reutilizarea maximă: reutilizarea amplă poate părea atractivă, dar comportamentul în funcție de chiriaș este mai sigur și mai ușor de explicat.
• Retenție mai lungă comparativ cu costul și complexitatea politicii: opțiunile TTL mai lungi pot ajuta sesiunile de agenți, dar pot introduce diferite considerații privind prețurile și controlul datelor.

Concluzie acționabilă

Tratați memorarea promptă în cache ca o problemă a planului de control al gateway-ului, nu o casetă de selectare a furnizorului. Modelul practic este: definiți regiuni prompte stabile, semistabile și volatile; redați-le în mod determinist; adaptați controalele cache specifice furnizorului în spatele unei singure interfețe; normalizați utilizarea cache-ului într-un registru; expune diagnosticarea accesării în cache după locatar, aplicație, rută și versiunea șablonului; și să impună ipotezele legate de chiriași.

Primul pas util nu este o rescriere. Adăugați observabilitate în cache la cele mai lungi solicitări, identificați prefixele și scame șabloanele care cauzează cele mai multe rateuri. Odată ce puteți explica comportamentul memoriei cache, îl puteți optimiza în siguranță.

Lectură similară

• construiți categorii conștiente de cache în registrul de facturare
• href="https://model-gate.com/en/blog/llm-observability-multi-model-api-gateway-traces-token-ledgers-safe-prompt-logging-9/">alăturați valorile cache cu observabilitate LLM sigură
• păstrați contextul de recuperare în limitele chiriașilor în sarcinile de lucru RAG