Rychlá kontrola mezipaměti v bráně API pro více modelů: Stabilní předpony, izolace tenantů a analýza přístupů do mezipaměti

Promptné ukládání do mezipaměti lze snadno plýtvat. Tým může mít systémovou výzvu se 40 000 tokeny, schéma nástroje, blok zásad, mapu úložiště nebo paměť agenta, která by měla být znovu použitelná, a poté náhodně umístit do horní části výzvy časové razítko, ID požadavku, uživatelské jméno, fragment načtení nebo náhodné pořadí nástroje. Poskytovatel vidí jinou předponu, chybí mezipaměť, zvyšuje se latence a účet vypadá zmateně.

V aplikaci s jedním poskytovatelem to můžete opravit v šabloně aplikace. Ve vícemodelové bráně je problém větší: každý poskytovatel odhaluje různé ovládací prvky mezipaměti, prahové hodnoty tokenů, chování doby životnosti, pole použití a sémantiku účtování. Brána potřebuje přenosný vzor řídicí roviny pro sestavování výzev bezpečných v mezipaměti, měření chování mezipaměti, izolování tenantů a přiřazování nákladů.

Tento článek popisuje referenční architekturu. Nejedná se o případovou studii zákazníka a nenárokuje si srovnávací výsledky. Níže uvedená fakta pocházejí z dokumentace poskytovatele a veřejného výzkumu; doporučení ohledně návrhu jsou provozní pokyny na úrovni brány.

Režim selhání: sestavení výzvy k prolomení mezipaměti

Ukládání výzev do mezipaměti obecně odměňuje opakované předpony výzev. Přesná mechanika se u jednotlivých poskytovatelů liší, ale praktické důsledky jsou konzistentní: pokud se přední strana výzvy změní, opakované použití trpí.

Mezi běžné lámače mezipaměti patří:

• Metadata pro jednotlivé požadavky nahoře: časová razítka, ID trasování, ID relací, ID nasazení nebo vygenerované štítky požadavků.
• Údaje specifické pro uživatele v předponě: názvy, atributy účtů, oprávnění nebo soukromé preference umístěné před opakovaně použitelnými zásadami nebo bloky nástrojů.
• Nestabilní serializace nástrojů: schémata nástrojů vysílaná v nedeterministickém pořadí, s měnícími se mezerami nebo generovanými ID.
• Příliš brzké načítání úryvků: Kontext RAG vložen před stabilní systémové pokyny nebo kontext sdíleného úložiště.
• Posun šablony: malé změny textu se často vydávají bez diagnostiky verzí nebo mezipaměti.

Brána nemůže magicky učinit nestabilní předponu mezipamětí, ale může vynutit smlouvu o rychlém sestavení a zviditelnit chybějící mezipaměť.

Poskytujte fakta, která lze navrhnout

Na detailech záleží, protože brána musí normalizovat chování, aniž by předstírala, že poskytovatelé jsou identičtí.

• OpenAI: OpenAI zdokumentovalo ukládání výzvy do mezipaměti pro nejdelší dříve vypočítanou předponu výzvy. Začíná na 1 024 tokenech, zvyšuje se o 128 tokenů a odhaluje počty tokenů uložených v mezipaměti v polích použití. OpenAI také uvádí, že rychlé mezipaměti jsou obvykle vymazány po 5–10 minutách nečinnosti a jsou vždy odstraněny do jedné hodiny od posledního použití mezipaměti.
• Anthropic: Uložení antropických výzev do mezipaměti lze vyžádat pomocí cache_control. Jeho dokumentace popisuje shodu mezipaměti přes komponenty výzvy, jako jsou nástroje, systémový obsah a zprávy, až do bloku označeného kontrolou mezipaměti. Antropické dokumenty pomíjivé vyrovnávací paměti, včetně 5minutového trvání a 1hodinové varianty za příplatek.
• Gemini: Kontextová mezipaměť Google Gemini odhaluje počty tokenů přístupů do mezipaměti prostřednictvím metadat využití, jako jsou total_cached_tokens, a jeho dokumentace uvádí minimální počty vstupních tokenů podle modelu.
• Implementace řízení dat: Dokumentace řízení dat API OpenAI uvádí, že rozšířené ukládání do mezipaměti vyžaduje ukládání tenzorů klíč/hodnota jako stav aplikace v místním úložišti GPU. I když poskytovatelé zachovávají záruky izolace, brány by měly chování mezipaměti považovat za citlivou infrastrukturu, nikoli jako sdílené úložiště dat aplikací.
• Výzkumný signál: Veřejný výzkum zkoumal, zda architektury ve stylu brány mohou zavést zranitelnosti rychlého ukládání do mezipaměti, které obcházejí předpoklady izolace mezipaměti na úrovni poskytovatele. To nedokazuje, že konkrétní brána je zranitelná, ale podporuje konzervativní návrh izolace tenantů.

Doporučení: implementujte řízení mezipaměti jako funkci brány s explicitními zásadami, nikoli jako náhodný vedlejší efekt opakovaných výzev.

Smlouva o rychlé montáži ve třech oblastech

Nejdůležitějším návrhovým rozhodnutím je oddělit stabilní a nestálý obsah předtím, než požadavek dorazí k adaptéru poskytovatele.

Oblast 1: stabilní předpona

Stabilní předpona je obsah, u kterého se očekává, že zůstane identický v mnoha požadavcích pro stejnou aplikaci, trasu modelu a verzi šablony výzvy. Příklady:

• pokyny pro základní systém;
• bezpečnostní a politické bloky;
• schémata nástrojů;
• statická produktová dokumentace;
• mapy úložiště pro kódovací agenty;
• pevné pokyny pro výstupní formát.

Tato oblast by měla být deterministická. Brána by ji měla sestavit z verzovaných šablon, kanonizovaných JSON a stabilních pravidel řazení. Pokud je zahrnut registr nástrojů, seřaďte nástroje podle stabilního ID nástroje. Pokud jsou zahrnuta schémata JSON, serializujte je s deterministickým řazením klíčů a bez vygenerovaných časových razítek.

Region 2: Semi-stabilní tenant nebo kontext pracovního prostoru

Semistabilní oblast se mění méně často než jednotlivé požadavky, ale není globálně sdílena. Příklady:

• přepsání zásad specifických pro nájemce;
• seznamy povolených nástrojů na úrovni pracovního prostoru;
• zákaznická terminologie;
• týmové kódovací konvence;
• kontext projektu s dlouhou životností.

Tato oblast by měla být vymezena pro tenanta, pracovní prostor nebo hranici aplikace. Může být stále možné uložit do mezipaměti, ale brána by nikdy neměla předpokládat, že ji může bezpečně znovu použít jiný tenant.

Oblast 3: těkavá přípona

Nestálá přípona je část pro každý požadavek:

• zpráva uživatele;
• získali úryvky pro tento dotaz;
• aktuální časové razítko, je-li skutečně potřeba;
• požádat o ID a metadata trasování, jsou-li ve výzvě vůbec zahrnuta;
• krátkodobá konverzace se změní;
• výsledky runtime nástroje.

Většina chyb v mezipaměti způsobených návrhem aplikace nastává proto, že do prefixu jsou náhodně vložena data nestálé přípony. Tvůrce na straně brány by to měl ztížit.

Vzor implementace: vytváření stabilních prefixů

Praktická implementace brány může odhalit rozhraní pro rychlé sestavení namísto přijímání jednoho neprůhledného řetězce výzvy z každé aplikace.

{
  "template_id": "code-agent-v3",
  "tenant_id": "tenant_123",
  "route": "coding-long-context",
  "stabilní_předpona": {
    "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": "Vysvětlete, proč tento test selže...",
    "retrieval_context_ids": ["chunk_7", "chunk_19"],
    "trace_id": "not_inserted_into_prompt"
  }
}

Brána poté vykreslí požadavek specifický pro poskytovatele. To dává bráně místo pro vynucování pravidel:

• odmítnout časová razítka v polích stabilní předpony;
• kanonizovat schémata nástrojů;
• hašujte každou oblast zvlášť;
• připojit ovládací prvky mezipaměti tam, kde je poskytovatel podporuje;
• zachovat okamžitou sémantiku při pozdějším přesunu těkavých materiálů;
• zaznamenejte šablonu a předponu otisků prstů pro diagnostiku.

U starších aplikací, které odesílají pouze nezpracované zprávy, může brána stále poskytovat režim lint: kontrolovat pořadí zpráv, vypočítat otisky prstů předpony a hlásit pravděpodobné narušení mezipaměti, aniž by bylo nutné nejprve přepisovat výzvu.

Vrstva adaptéru poskytovatele: normalizace využití mezipaměti bez skrytí rozdílů

Brána pro více modelů by neměla vývojářům odhalit tři nesouvisející zprávy o mezipaměti. Také by to nemělo zplošťovat ekonomiku specifickou pro poskytovatele tak agresivně, aby bylo nemožné vysvětlit faktury.

Vytvořte normalizovanou knihu mezipaměti s poli jako:

{
  "request_id": "req_abc",
  "tenant_id": "tenant_123",
  "app_id": "kódový agent",
  "route": "coding-long-context",
  "provider": "název_poskytovatele",
  "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": 50 000,
  "cache_read_tokens": 0,
  "output_tokens": 1300,
  "cache_ttl_class": "efemérní_5m",
  "provider_cache_fields": {
    "raw_field_names": "usage_uloženého_nebo_upraveného_poskytovatele"
  }
}

Adaptér mapuje využití poskytovatele do normalizovaných kategorií:

• Vstupní tokeny neuložené v mezipaměti: tokeny zpracované bez slevy na čtení z mezipaměti nebo bez účtování čtení z mezipaměti.
• Tokeny zápisu do mezipaměti: tokeny, které vytvořily nebo obnovily záznam mezipaměti na straně poskytovatele, když poskytovatel nahlásí tento rozdíl.
• Tokeny čtení z mezipaměti: tokeny poskytované z mezipaměti nebo započítávané do mezipaměti metadaty využití poskytovatele.
• Výstupní tokeny: generované tokeny, které by měly zůstat oddělené od okamžité ekonomiky mezipaměti.
• Možnost TTL: vybraná třída trvání mezipaměti, kde poskytovatel nabízí možnost volby.

Doporučení: ukládejte nezpracované údaje o použití poskytovatele v redigované podobě s verzí schématu vedle normalizovaných polí. Normalizace je užitečná pro řídicí panely; nezpracovaná pole jsou nezbytná pro sladění, když se změní sémantika poskytovatele.

Pozorovatelnost mezipaměti: řídicí panely, které vysvětlují chyby

Užitečný řídicí panel mezipaměti dokáže více než jen zobrazit celkový počet tokenů uložených v mezipaměti. Mělo by to týmům pomoci odpovědět: „Která pracovní zátěž porušuje předponu a co se změnilo?“

Sledování metrik mezipaměti podle:

• nájemce;
• pracovní prostor nebo aplikace;
• modelovou trasu;
• poskytovatel a model;
• rychlá verze šablony;
• stabilní hash předpony;
• polostabilní kontextový hash;
• klíč API nebo servisní účet, kde je to vhodné;
• časové okno, zejména proto, že hodnoty TTL mezipaměti jsou pro mnoho úloh krátké.

Mezi užitečné odvozené metriky patří:

• Rychlost čtení mezipaměti: vstupní tokeny uložené v mezipaměti dělené celkovým počtem vstupních tokenů vhodných pro ukládání do mezipaměti.
• Předpona churn: počet odlišných stabilních hash předpon na verzi šablony za hodinu.
• Posun šablony: změny požadavků na mezipaměť po vydání šablony.
• Cena studeného startu: útrata za zápis do mezipaměti nebo vstup do mezipaměti pro první požadavek v sérii.
• Porovnání tras: četnost zásahů napříč trasami poskytovatelů pro stejnou logickou zátěž.

Nenastavujte výchozí ukládání nezpracovaných výzev pro ladění. Upřednostňujte hashe, délky oblastí, ID šablon, varování kanonizace a redigované rozdíly. Pokud tým potřebuje hlubší ladění, požadujte explicitní řízení přístupu a omezení uchovávání.

Zásady izolace tenantů: nenavrhujte pro opakované použití mezi tenanty

Nejbezpečnější předpoklad brány je jednoduchý: chování uložené v mezipaměti by mělo být v rozsahu tenanta. I když dva nájemci sdílejí identický blok veřejné politiky, brána by neměla záměrně směrovat nebo utvářet provoz, aby využila opětovné použití mezipaměti mezi nájemci.

Konzervativní zásady zahrnují:

• Směrování s ohledem na tenanty: směrujte provoz uložený do mezipaměti pomocí hranic tenanta, pracovního prostoru a aplikací.
• Žádné sdílené předpony nesoucí tajemství: nikdy neumisťujte tajné klíče, přihlašovací údaje, soukromé dokumenty ani data specifická pro uživatele do opakovaně použitelné sdílené předpony.
• Oddělené otisky předpony: vypočítávají otisky prstů s rozsahem tenanta zahrnutým do knihy brány, i když je vykreslený text identický.
• Ovládací prvky na úrovni organizace: umožňují správcům deaktivovat funkce mezipaměti poskytovatele pro citlivé úlohy.
• Izolace poskytovatelů není funkcí produktu k prodeji: izolaci mezipaměti poskytovatele považujte za základní ochranu, nikoli za povolení vytvářet sdružování mezipaměti mezi zákazníky.

Předpověď: Jak se agenti dlouhého kontextu stanou běžnějšími, stane se chování mezipaměti součástí bezpečnostních kontrol, nejen cenových kontrol. Brány, které dokážou prokázat zásady mezipaměti v rozsahu tenanta, se budou snáze řídit.

Atribuce fakturace: oddělená mezipaměť čtení, zápis a normální tokeny

Pokud jsou všechny vstupní tokeny zobrazeny jako jedno číslo, může rychlé ukládání do mezipaměti ztížit pochopení faktur. Účetní kniha by měla zachovat alespoň pět kategorií:

1. neuložené vstupní tokeny;
2. ukládat tokeny zápisu do mezipaměti;
3. ukládat tokeny čtení do mezipaměti;
4. výstupní tokeny;
5. Poplatky za TTL nebo kontrolu mezipaměti specifické pro poskytovatele.

To je důležité, když jeden poskytovatel zlevňuje čtení z mezipaměti, jiný účtuje různé poplatky za zápisy do mezipaměti a další nabízí delší možnost TTL. Faktura zákazníka by měla být schopna vysvětlit, proč měly dva požadavky s podobným celkovým vstupním tokenem různé náklady.

U interního zpětného zúčtování přiřaďte efekty mezipaměti tenantovi a aplikaci, která požadavek podala. Vyhněte se přidělování výhody čtení z mezipaměti od jednoho tenanta druhému. Pokud tým sdílené interní platformy vlastní šablonu stabilní výzvy, vykazujte výkon mezipaměti na úrovni šablony odděleně od faktur tenantů.

Kontrolní seznam pro vyrovnávání mezipaměti

Před povolením vynucení mezipaměti spusťte šablony výzev pomocí kontrolního seznamu lint:

• Před nestabilním uživatelským vstupem se objevují pokyny pro stabilní systém.
• Schémata nástrojů jsou řazena podle stabilního ID nebo názvu.
• JSON je serializován deterministicky.
• Ve stabilní předponě se neobjevují žádná časová razítka, náhodná ID, ID požadavků ani ID trasování.
• Ve sdílených opakovaně použitelných blocích se neobjevují žádná uživatelská tajemství.
• Úryvky RAG se umísťují za opakovaně použitelné sekce zásad a nástrojů, pokud k tomu není úmyslný důvod.
• Šablony výzev mají explicitní verze.
• Vydání šablony lze korelovat se změnami rychlosti přístupu do mezipaměti.
• Ovládací prvky mezipaměti poskytovatele se používají pouze prostřednictvím kódu adaptéru, nikoli logiky rozptýlené aplikace.
• Protokolování nezpracovaných výzev je ve výchozím nastavení zakázáno nebo chráněno přísnými pravidly uchovávání a přístupu.

Plán zavádění

1. Před změnou výzvy věnujte pozornost

Začněte shromažďováním polí využití poskytovatele a normalizovaných metrik mezipaměti pro stávající provoz. Vypočítejte otisky prstů předpony pro prvních N tokenů nebo pro oblasti výzvy definované bránou. Cílem je najít velkoobjemové trasy s dlouhým kontextem s vysokou předponou churn.

2. Klasifikujte pracovní zátěž

Seskupte provoz do kategorií: relace agentů, asistenti kódování, RAG, automatizace podpory, analýza dokumentů, dávkové úlohy a krátký chat. Rychlá práce s mezipamětí obvykle věnuje největší pozornost zátěži s dlouhým kontextem a opakovanými předponami. Krátké výzvy pod limity poskytovatele nemusí být přínosem.

3. Představte nástroje pro tvorbu předpon stabilní

Přesuňte jednu pracovní zátěž z prvotní rychlé konstrukce do sestavy založené na regionu. Udržujte vykreslený požadavek poskytovatele sémanticky ekvivalentní. Nekombinujte tuto změnu s migrací modelu, přepracováním nástroje nebo zásadními přepisy, jinak nebudete vědět, co způsobilo změny metrik.

4. Canary one route

Povolte ovládací prvky mezipaměti pro malou část jednoho tenanta nebo interní aplikaci. Porovnejte rychlost čtení mezipaměti, odchod předpony, dobu do prvního tokenu, chybovost a cenové kategorie. Vyhněte se nárokování úspor, dokud se účty poskytovatele neodsouhlasí s účetními knihami brány.

5. Vynucovat postupně

Po kanárku přeměňte varování před žmolky na kontroly zásad. Nejprve například varujte před nestabilním pořadím nástrojů a poté odmítněte nové verze šablon, které obsahují nestálá metadata ve stabilní předponě.

Výměny

• Vyšší míra přístupu do mezipaměti oproti rychlé flexibilitě: Stabilní předpony zlepšují opakované použití, ale týmy možná budou muset přesunout dynamické pokyny později nebo přepracovat šablony.
• Ukládání do mezipaměti nativního poskytovatele vs. přenositelnost: používání ovládacích prvků mezipaměti jednotlivých poskytovatelů může zlepšit ekonomiku, ale prahové hodnoty, TTL, pole a cenová sémantika se liší.
• Pozorovatelnost vs. citlivé protokolování: rychlé rozdíly pomáhají ladit chyby, ale hodnoty hash a redigovaná diagnostika jsou bezpečnější výchozí hodnoty.
• Izolace nájemců vs. maximální opětovné použití: široké opakované použití může vypadat atraktivně, ale chování v rámci nájemce je bezpečnější a snáze vysvětlitelné.
• Delší uchování vs. náklady a složitost zásad: Delší možnosti TTL mohou pomoci relacím agentů, ale mohou představovat jiné úvahy o cenách a kontrole dat.

Akční závěr

Ukládání výzev do mezipaměti považujte za problém řídicí roviny brány, nikoli za zaškrtávací políčko poskytovatele. Praktický vzor je: definovat stabilní, polostabilní a volatilní oblasti výzvy; vykreslit je deterministicky; přizpůsobit ovládací prvky mezipaměti specifické pro poskytovatele za jedno rozhraní; normalizovat využití mezipaměti do účetní knihy; odhalit diagnostiku přístupů do mezipaměti podle tenanta, aplikace, trasy a verze šablony; a prosazovat předpoklady v rozsahu nájemců.

Prvním užitečným krokem není přepis. Přidejte ke svým nejdelším výzvám pozorovatelnost mezipaměti, identifikujte předponu churn a linťte šablony, které způsobují nejvíce chyb. Jakmile vysvětlíte chování mezipaměti, můžete jej bezpečně optimalizovat.

Související informace

• vytvořte do fakturační knihy kategorie podporující mezipaměť
připojit metriky mezipaměti s bezpečnou pozorovatelností LLM
• ponechat kontext získávání v rozsahu působnosti tenanta v úlohách RAG