Szybka kontrola pamięci podręcznej w wielomodelowej bramie API: stabilne prefiksy, izolacja dzierżawców i analiza trafień w pamięci podręcznej

Szybkie buforowanie jest łatwe do zmarnowania. Zespół może mieć monit systemowy na 40 000 tokenów, schemat narzędzia, blok zasad, mapę repozytorium lub pamięć agenta, która powinna nadawać się do ponownego wykorzystania, a następnie przypadkowo umieścić sygnaturę czasową, identyfikator żądania, nazwę użytkownika, fragment kodu pobierania lub losową kolejność narzędzi w górnej części podpowiedzi. Dostawca widzi inny prefiks, brakuje pamięci podręcznej, wzrasta opóźnienie, a rachunek wygląda na zagmatwany.

W aplikacji jednego dostawcy możesz to naprawić w szablonie aplikacji. W bramie wielomodelowej problem jest większy: każdy dostawca udostępnia inną kontrolę pamięci podręcznej, progi tokenów, zachowanie czasu wygaśnięcia, pola użytkowania i semantykę rozliczeń. Brama potrzebuje przenośnego wzorca płaszczyzny kontrolnej do tworzenia podpowiedzi bezpiecznych dla pamięci podręcznej, mierzenia zachowania pamięci podręcznej, izolowania dzierżawców i przypisywania kosztów.

W tym artykule opisano architekturę referencyjną. Nie jest to studium przypadku klienta i nie zawiera wyników testów porównawczych. Poniższe fakty pochodzą z dokumentacji dostawcy i badań publicznych; zalecenia projektowe stanowią wskazówki operacyjne na poziomie bramy.

Tryb awarii: monit o łamanie pamięci podręcznej

Buforowanie podpowiedzi zazwyczaj nagradza powtarzające się przedrostki podpowiedzi. Dokładna mechanika różni się w zależności od dostawcy, ale praktyczne implikacje są spójne: jeśli zmieni się przód monitu, ucierpi na tym ponowne wykorzystanie.

Do typowych programów do łamania pamięci podręcznej należą:

• U góry metadane dotyczące żądania: znaczniki czasu, identyfikatory śledzenia, identyfikatory sesji, identyfikatory wdrożeń lub wygenerowane etykiety żądań.
• Dane specyficzne dla użytkownika w przedrostku: nazwy, atrybuty konta, uprawnienia lub prywatne preferencje umieszczone przed zasadami lub blokami narzędzi wielokrotnego użytku.
• Niestabilna serializacja narzędzi: schematy narzędzi emitowane w kolejności niedeterministycznej, ze zmieniającymi się białymi znakami lub wygenerowanymi identyfikatorami.
• Zbyt wczesne pobranie fragmentów: Kontekst RAG wstawiony przed stabilnymi instrukcjami systemu lub kontekstem współdzielonego repozytorium.
• Przesunięcie szablonu: często wprowadzane są drobne zmiany w sformułowaniach, bez kontroli wersji i diagnostyki pamięci podręcznej.

Brama nie może w magiczny sposób umieścić w pamięci podręcznej niestabilnego prefiksu, ale może wymusić umowę dotyczącą szybkiego montażu i uwidocznić braki w pamięci podręcznej.

Fakty dotyczące dostawcy, na których warto się oprzeć

Szczegóły mają znaczenie, ponieważ brama musi normalizować zachowanie, nie udając, że dostawcy są identyczni.

• OpenAI: OpenAI udokumentowało buforowanie podpowiedzi dla najdłuższego wcześniej obliczonego przedrostka podpowiedzi. Zaczyna się od 1024 tokenów, zwiększa się o 128 tokenów i wyświetla liczbę tokenów w pamięci podręcznej w polach użycia. OpenAI stwierdza również, że pamięć podręczna podpowiedzi jest zwykle czyszczona po 5–10 minutach bezczynności i zawsze usuwana w ciągu godziny od ostatniego użycia pamięci podręcznej.
• Anthropic: Anthropic buforowania podpowiedzi można zażądać za pomocą cache_control. Jego dokumentacja opisuje dopasowanie pamięci podręcznej do komponentów podpowiedzi, takich jak narzędzia, zawartość systemu i komunikaty, aż do bloku oznaczonego jako kontrola pamięci podręcznej. Anthropic dokumentuje efemeryczną pamięć podręczną, obejmującą 5-minutowy czas trwania i 1-godzinną opcję za dodatkową opłatą.
• Gemini: Google Gemini buforowanie kontekstowe udostępnia liczbę tokenów trafień w pamięci podręcznej za pośrednictwem metadanych użycia, takich jak total_cached_tokens, a jego dokumentacja zawiera minimalną liczbę tokenów wejściowych według modelu.
• Implikacje dotyczące kontroli danych: Dokumentacja OpenAI API dotycząca kontroli danych zauważa, że ​​rozszerzone buforowanie podpowiedzi wymaga przechowywania tensorów klucz/wartość jako stanu aplikacji w lokalnej pamięci GPU. Nawet jeśli dostawcy zapewniają gwarancje izolacji, bramy powinny traktować zachowanie pamięci podręcznej jako wrażliwą infrastrukturę, a nie jak magazyn danych współdzielonej aplikacji.
• Sygnał badawczy: W ramach badań publicznych zbadano, czy architektury typu bramy mogą wprowadzać luki w zabezpieczeniach buforowania podpowiedzi, które omijają założenia izolacji pamięci podręcznej na poziomie dostawcy. Nie oznacza to, że konkretna brama jest podatna na ataki, ale obsługuje konserwatywny projekt izolacji dzierżawców.

Zalecenie: zaimplementuj kontrolę pamięci podręcznej jako funkcję bramy z wyraźnymi zasadami, a nie jako przypadkowy efekt uboczny powtarzających się monitów.

Umowa na szybki montaż obejmująca trzy regiony

Najważniejszą decyzją projektową jest oddzielenie treści stabilnej i niestabilnej, zanim żądanie dotrze do adaptera dostawcy.

Region 1: stabilny prefiks

Prefiks stabilny oznacza, że treść ma pozostać identyczna w wielu żądaniach dla tej samej aplikacji, trasy modelu i wersji szablonu podpowiedzi. Przykłady obejmują:

• podstawowe instrukcje systemowe;
• blokady dotyczące bezpieczeństwa i zasad;
• schematy narzędzi;
• statyczna dokumentacja produktu;
• mapy repozytoriów dla agentów kodujących;
• naprawiono instrukcje w formacie wyjściowym.

Ten region powinien być deterministyczny. Brama powinna zbudować ją na podstawie wersjonowanych szablonów, kanonizowanego JSON i stabilnych reguł porządkowania. Jeśli dołączony jest rejestr narzędzi, posortuj narzędzia według stabilnego identyfikatora narzędzia. Jeśli uwzględnione są JSON schematy, serializuj je z deterministyczną kolejnością kluczy i bez generowanych znaczników czasu.

Region 2: półstabilny kontekst najemcy lub obszaru roboczego

Region półstabilny zmienia się rzadziej niż pojedyncze żądania, ale nie jest udostępniany globalnie. Przykłady obejmują:

• zastąpienia zasad specyficznych dla dzierżawcy;
• listy dozwolonych narzędzi na poziomie obszaru roboczego;
• terminologia dostosowana do potrzeb klienta;
• konwencje kodowania zespołowego;
• długoterminowy kontekst projektu.

Zakres tego regionu powinien obejmować dzierżawcę, obszar roboczy lub granicę aplikacji. Może nadal można go przechowywać w pamięci podręcznej, ale brama nigdy nie powinna zakładać, że inny dzierżawca może bezpiecznie go ponownie użyć.

Region 3: przyrostek zmienny

Ulotny przyrostek to część żądania:

• wiadomość użytkownika;
• pobrano fragmenty tego zapytania;
• bieżący znacznik czasu, jeśli jest to naprawdę potrzebne;
• poproś o identyfikator i metadane śledzenia, jeśli w ogóle zostały uwzględnione w monicie;
• krótkoterminowe zmiany w rozmowie;
• wyniki działania narzędzia.

Większość błędów w pamięci podręcznej spowodowanych projektem aplikacji ma miejsce w wyniku przypadkowego umieszczenia w prefiksie danych zmiennego sufiksu. Kreator po stronie bramy powinien to utrudnić.

Wzorzec implementacji: narzędzia do tworzenia stabilnych prefiksów

Praktyczna implementacja bramy może udostępnić interfejs szybkiego montażu zamiast akceptować jeden nieprzejrzysty ciąg znaków podpowiedzi z każdej aplikacji.

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

Następnie brama renderuje żądanie specyficzne dla dostawcy. Dzięki temu brama może egzekwować reguły:

• odrzucaj znaczniki czasu w polach stabilnych prefiksów;
• kanonizacja schematów narzędzi;
• hashuj każdy region osobno;
• dołącz elementy sterujące pamięcią podręczną, jeśli dostawca je obsługuje;
• zachowaj semantykę podpowiedzi podczas późniejszego przenoszenia niestabilnego materiału;
• zapisuj szablony i odciski palców z prefiksami na potrzeby diagnostyki.

W przypadku starszych aplikacji, które wysyłają tylko nieprzetworzone wiadomości, brama może nadal zapewniać tryb lint: sprawdzanie kolejności wiadomości, obliczanie odcisków palców prefiksów i zgłaszanie prawdopodobnych przypadków naruszenia pamięci podręcznej bez początkowego przepisywania monitu.

Warstwa adaptera dostawcy: normalizuj wykorzystanie pamięci podręcznej bez ukrywania różnic

Brama obsługująca wiele modeli nie powinna udostępniać programistom trzech niepowiązanych raportów dotyczących pamięci podręcznej. Nie powinno to również spłaszczać ekonomii specyficznej dla dostawcy tak agresywnie, tak aby niemożliwe stało się wyjaśnienie faktur.

Utwórz znormalizowaną księgę pamięci podręcznej z polami takimi jak:

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

Adapter mapuje użycie dostawcy na znormalizowane kategorie:

• Tokeny wejściowe niezapisane w pamięci podręcznej: tokeny przetworzone bez rabatu za odczyt z pamięci podręcznej lub rozliczania odczytu z pamięci podręcznej.
• Tokeny zapisu w pamięci podręcznej: tokeny, które utworzyły lub odświeżyły wpis w pamięci podręcznej po stronie dostawcy, gdy dostawca zgłosi to rozróżnienie.
• Tokeny odczytu pamięci podręcznej: tokeny podawane z pamięci podręcznej lub liczone jako buforowane przez metadane użycia dostawcy.
• Tokeny wyjściowe: wygenerowane tokeny, które powinny pozostać oddzielone od ekonomii pamięci podręcznej.
• Opcja TTL: wybrana klasa czasu trwania pamięci podręcznej, w której dostawca udostępnia wybór.

Zalecenie: przechowuj surowe dane dotyczące użycia dostawcy w zredagowanej formie opartej na wersji schematu obok znormalizowanych pól. Normalizacja jest przydatna w przypadku dashboardów; surowe pola są niezbędne do uzgodnienia w przypadku zmiany semantyki dostawcy.

Obserwacja pamięci podręcznej: panele wyjaśniające błędy

Przydatny panel pamięci podręcznej nie tylko wyświetla całkowitą liczbę tokenów w pamięci podręcznej. Powinno to pomóc zespołom odpowiedzieć: „Które obciążenie zakłóca przedrostek i co się zmieniło?”

Śledź wskaźniki pamięci podręcznej za pomocą:

• najemca;
• przestrzeń robocza lub aplikacja;
• modelowa trasa;
• dostawca i model;
• wersja szablonu podpowiedzi;
• stabilny skrót przedrostka;
• półstabilny skrót kontekstu;
• API konto klucza lub usługi, w stosownych przypadkach;
• okno czasowe, zwłaszcza że czasy TTL pamięci podręcznej są krótkie w przypadku wielu obciążeń.

Przydatne metryki pochodne obejmują:

• Szybkość odczytu pamięci podręcznej: buforowanych tokenów wejściowych podzielona przez całkowitą liczbę tokenów wejściowych kwalifikujących się do buforowania.
• Rezygnacja z prefiksu: liczba różnych stabilnych skrótów prefiksów na wersję szablonu na godzinę.
• Przesunięcie szablonu: zmiany w trafieniach w pamięci podręcznej po wydaniu szablonu.
• Koszt zimnego startu: wydatki na zapis w pamięci podręcznej lub dane wejściowe w pamięci podręcznej dla pierwszego żądania w serii.
• Porównanie tras: współczynnik trafień na trasach dostawców przy tym samym obciążeniu logicznym.

Nie przechowuj domyślnie nieprzetworzonych monitów o debugowanie. Preferuj skróty, długości regionów, identyfikatory szablonów, ostrzeżenia o kanonizacji i zredagowane różnice. Jeśli zespół potrzebuje głębszego debugowania, wymagaj jawnej kontroli dostępu i limitów przechowywania.

Zasady izolacji dzierżawców: nie projektuj z myślą o ponownym wykorzystaniu przez wielu dzierżawców

Założenie najbezpieczniejszej bramy jest proste: zachowanie pamięci podręcznej powinno mieć zasięg dzierżawcy. Nawet jeśli dwóch dzierżawców korzysta z identycznego bloku zasad publicznych, brama nie powinna celowo kierować ani kształtować ruchu w celu wykorzystania ponownego wykorzystania pamięci podręcznej między dzierżawcami.

Zasady konserwatywne obejmują:

• Routing uwzględniający dzierżawców: kieruj ruch możliwy do buforowania przy użyciu granic dzierżawcy, obszaru roboczego i aplikacji.
• Brak współdzielonych prefiksów zawierających klucz tajny: nigdy nie umieszczaj tajnych kluczy dzierżawcy, danych uwierzytelniających, dokumentów prywatnych ani danych specyficznych dla użytkownika we współdzielonym przedrostku wielokrotnego użytku.
• Oddzielne odciski palców prefiksu: obliczaj odciski palców z zakresem dzierżawy zawartym w księdze bramy, nawet jeśli renderowany tekst jest identyczny.
• Kontrola na poziomie organizacji: umożliwia administratorom wyłączanie funkcji pamięci podręcznej dostawcy w przypadku wrażliwych obciążeń.
• Izolacja dostawcy nie jest funkcją produktu, którą można odsprzedawać: traktuj izolację pamięci podręcznej dostawcy jako podstawową ochronę, a nie pozwolenie na tworzenie pul pamięci podręcznej między klientami.

Przewidywanie: w miarę jak agenci o długim kontekście staną się coraz bardziej powszechni, zachowanie pamięci podręcznej stanie się częścią przeglądów bezpieczeństwa, a nie tylko przeglądów kosztów. Łatwiej będzie zarządzać bramami, które będą w stanie sprawdzić zasady pamięci podręcznej ograniczone do dzierżawcy.

Atrybucja rozliczeń: oddzielne odczyty i zapisy w pamięci podręcznej oraz normalne tokeny

Szybkie buforowanie może sprawić, że faktury będą trudniejsze do zrozumienia, jeśli wszystkie tokeny wejściowe będą wyświetlane jako jedna liczba. Księga rozliczeniowa powinna zawierać co najmniej pięć kategorii:

1. niebuforowane tokeny wejściowe;
2. tokeny zapisu w pamięci podręcznej;
3. tokeny odczytu pamięci podręcznej;
4. tokeny wyjściowe;
5. opłaty TTL lub kontrola pamięci podręcznej specyficzne dla dostawcy.

Ma to znaczenie, gdy jeden dostawca rabatuje odczyty z pamięci podręcznej, inny pobiera inne opłaty za zapisy w pamięci podręcznej, a jeszcze inny udostępnia opcję dłuższego TTL. Faktura klienta powinna wyjaśniać, dlaczego dwa żądania z podobnymi łącznymi tokenami wejściowymi miały różne koszty.

W przypadku wewnętrznego obciążenia zwrotnego przypisz efekty pamięci podręcznej dzierżawcy i aplikacji, która wysłała żądanie. Unikaj przydzielania korzyści z odczytu pamięci podręcznej między jedną dzierżawą a drugą. Jeśli stabilny szablon monitu jest własnością zespołu współdzielonej platformy wewnętrznej, należy raportować wydajność pamięci podręcznej na poziomie szablonu oddzielnie od faktur najemcy.

Lista kontrolna czyszczenia pamięci podręcznej

Przed włączeniem wymuszania pamięci podręcznej uruchom szablony podpowiedzi za pomocą listy kontrolnej lint:

• Instrukcje dotyczące stabilnego systemu pojawiają się przed niestabilnymi danymi wprowadzonymi przez użytkownika.
• Schematy narzędzi są sortowane według stabilnego identyfikatora lub nazwy.
• JSON jest serializowany deterministycznie.
• W stabilnym przedrostku nie pojawiają się żadne znaczniki czasu, losowe identyfikatory, identyfikatory żądań ani identyfikatory śledzenia.
• We współdzielonych blokach wielokrotnego użytku nie pojawiają się żadne sekrety specyficzne dla użytkownika.
• Fragmenty RAG są umieszczane po sekcjach zasad i narzędzi wielokrotnego użytku, chyba że istnieje celowy powód, aby tego nie robić.
• Szablony podpowiedzi mają jawne wersje.
• Wersje szablonów można powiązać ze zmianami współczynnika trafień w pamięci podręcznej.
• Kontrola pamięci podręcznej dostawcy jest używana wyłącznie poprzez kod adaptera, a nie rozproszoną logikę aplikacji.
• Rejestrowanie nieprzetworzonych monitów jest domyślnie wyłączone lub chronione rygorystycznymi regułami przechowywania i dostępu.

Plan wdrożenia

1. Zanim zmienisz monity, zaobserwuj

Zacznij od zebrania pól użycia dostawcy i znormalizowanych wskaźników pamięci podręcznej dla istniejącego ruchu. Oblicz odciski palców prefiksu dla pierwszych N tokenów lub dla obszarów podpowiedzi zdefiniowanych przez bramę. Celem jest znalezienie tras o dużym natężeniu ruchu i długim kontekście, charakteryzujących się dużą zmianą prefiksów.

2. Klasyfikuj obciążenia

Grupuj ruch w kategorie: sesje agentów, asystenci kodowania, RAG, automatyzacja wsparcia, analiza dokumentów, zadania wsadowe i krótki czat. Szybka praca z pamięcią podręczną zwykle skupia największą uwagę na obciążeniach z długim kontekstem i powtarzającymi się prefiksami. Krótkie podpowiedzi poniżej progów dostawcy mogą nie przynieść korzyści.

3. Przedstaw narzędzia do tworzenia stabilnych prefiksów

Przenieś jedno zadanie z surowej konstrukcji podpowiedzi do montażu opartego na regionie. Zachowaj semantyczny równoważność renderowanego żądania dostawcy. Nie łącz tej zmiany z migracją modelu, przeprojektowaniem narzędzi lub poważnym przepisaniem podpowiedzi, w przeciwnym razie nie będziesz wiedzieć, co spowodowało zmiany metryki.

4. Kanaryjska jedna trasa

Włącz kontrolę pamięci podręcznej dla małego fragmentu jednego dzierżawcy lub aplikacji wewnętrznej. Porównaj współczynnik odczytu pamięci podręcznej, zmianę prefiksu, czas do pierwszego tokena, poziom błędów i kategorie kosztów. Unikaj ubiegania się o oszczędności, dopóki rachunki dostawcy nie pokryją się z księgami bramy.

5. Egzekwuj stopniowo

Po kanarku zamień ostrzeżenia o kłaczkach w kontrole zasad. Na przykład najpierw ostrzegaj o niestabilnej kolejności narzędzi, a następnie odrzucaj nowe wersje szablonów zawierające niestabilne metadane w przedrostku stabilnym.

Kompromis

• Większy współczynnik trafień w pamięci podręcznej w porównaniu z elastycznością natychmiastowości: stabilne prefiksy ułatwiają ponowne użycie, ale zespoły mogą być zmuszone później przenieść instrukcje dynamiczne lub przeprojektować szablony.
• Buforowanie natywne przez dostawcę a przenośność: korzystanie z kontroli pamięci podręcznej każdego dostawcy może poprawić ekonomię, ale progi, TTL, pola i semantyka cen są różne.
• Obserwowalność a wrażliwe rejestrowanie: różnice w podpowiedziach pomagają w usuwaniu błędów, ale skróty i zredagowana diagnostyka są bezpieczniejszymi ustawieniami domyślnymi.
• Izolacja dzierżawcy a maksymalne ponowne wykorzystanie: szerokie ponowne wykorzystanie może wyglądać atrakcyjnie, ale zachowanie ukierunkowane na dzierżawcę jest bezpieczniejsze i łatwiejsze do wyjaśnienia.
• Dłuższe przechowywanie a złożoność kosztów i zasad: dłuższe opcje TTL mogą pomóc w sesjach agentów, ale mogą powodować inne kwestie związane z cenami i kontrolą danych.

Wniosek, który można zastosować

Traktuj buforowanie podpowiedzi jako problem z płaszczyzną kontrolną bramy, a nie pole wyboru dostawcy. Praktyczny wzór jest następujący: zdefiniuj stabilne, półstabilne i lotne obszary podpowiedzi; renderuj je deterministycznie; dostosować kontrolę pamięci podręcznej specyficzną dla dostawcy za jednym interfejsem; normalizować wykorzystanie pamięci podręcznej w księdze; udostępniać diagnostykę trafień w pamięci podręcznej według dzierżawy, aplikacji, trasy i wersji szablonu; i wymuszaj założenia dotyczące zasięgu najemcy.

Pierwszym użytecznym krokiem nie jest przepisanie. Dodaj możliwość obserwacji pamięci podręcznej do najdłuższych podpowiedzi, zidentyfikuj zmianę prefiksów i zaznacz szablony powodujące najwięcej pomyłek. Gdy już wyjaśnisz zachowanie pamięci podręcznej, możesz je bezpiecznie zoptymalizować.

Powiązane lektury

• wprowadź kategorie uwzględniające pamięć podręczną w księdze rozliczeniowej
• połącz metryki pamięci podręcznej z bezpieczną obserwowalnością LLM
• kontynuuj pobieranie kontekst w zakresie dzierżawy w obciążeniach RAG