Brama AI, która odpowiada na podstawie tego, co już powiedziała
Asystent wsparcia przez cały dzień otrzymuje te same pytania, zadawane nieco innymi słowami. Brama stojąca przed jego modelem może odpowiedzieć na pytanie odpowiedzią, której udzieliła na wcześniejsze pytanie o dostatecznie bliskim znaczeniu, zamiast ponownie wywoływać model. Ten obszar roboczy kompiluje taką bramę do manifestów Kubernetes wraz z magazynem, w którym przechowuje ona te odpowiedzi.
Feature, która to realizuje, to core/semantic-caching. Które odpowiedzi wygenerowane
na żądanie jednego wywołującego mogą zostać podane innemu wywołującemu — tej kwestii
strona ta poświęca najwięcej miejsca, ponieważ pamięć podręczna współdzielona przez
niewłaściwych wywołujących przekazuje jednej osobie odpowiedź wygenerowaną dla innej.
Ten obszar roboczy nie definiuje żadnej własnej encji katalogu. Trzy pliki encji w nim — encja Aggregate, encja Manifest i encja Release — to całość tego, co ktokolwiek pisze.
Co powstaje
| instancja | encja Component z katalogu | czym jest tutaj |
|---|---|---|
router | core/gateway/litellm | brama AI: alias czatu assistant i alias embeddingów embedder, każdy obsługiwany przez model podłączony do jej gniazda models |
chat | core/ai-model/openai | model czatu stojący za assistant, własne API OpenAI, osiągane jako odwołanie: nic nie działa dla niego w klastrze |
embeddings | core/ai-model/openai-embedding | model embeddingów stojący za embedder, osiągany w ten sam sposób |
cache | core/datastore/redis | magazyn, w którym brama przechowuje swoje odpowiedzi |
Trzy krawędzie uses: dwie do gniazda models bramy, po jednej do każdego modelu,
każda niosąca jako swój credential klucz, który brama przedstawia temu modelowi,
oraz jedna do jej gniazda cache_store, niosąca jako swój credential hasło,
które cache przedstawia magazynowi. Dwa dołączenia encji Feature na bramie:
api_key, jej klucz administracyjny, i answers, cache; oraz jedno na
magazynie, password, hasło, którego on wymaga. Oba dołączenia haseł odczytują jeden
parametr, cache_password, a oba poświadczenia modeli inny, openai_key;
encja Release dostarcza oba. Dołączenie answers wskazuje alias embeddingów,
który zamienia każdy prompt na wektor, to, jak podobne muszą być dwa prompty — 0.9,
jako podobieństwo cosinusowe — oraz to, jak długo przechowywana odpowiedź jest ważna: godzinę. Pomija
scope, więc przyjmuje wartość domyślną, end_user.
Generowanie przykładu
Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example ai-gateway-semantic-cacheNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd ai-gateway-semantic-cacheKompilacja
aggrega build --release release.yaml --auto-pullWydanie wymaga pliku blokady (lockfile), zanim zostanie zbudowane, a pliki blokady są generowane, a nie dostarczane, więc świeży klon nie ma żadnego. Należy najpierw go rozwiązać albo pozwolić, by budowanie go uzupełniło:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildTen obszar roboczy rozwiązuje encje katalogu z domyślnego rejestru wskazanego w .aggrega-config.yaml. Realizacja pamięci podręcznej uruchamia jeden plugin, który nie jest dostarczany ani z kompilatorem, ani z katalogiem: krok konfiguracji bramy pipeline-step/litellm-gateway-config, pobierany podczas rozwiązywania z rejestru wskazanego przez default_registry, czyli hub.aggrega.ai.
Budowanie wypisuje (<workspace> oznacza folder tego przykładu):
[… omitted: a line reporting on the gateway configuration step's plugin, five warnings, one per credential attachment, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping, the resolution's summary and a total build time, which differ per run, and a notice that core/referenced-secret declares origin in both of its pillars]Build completed: 13 files written to <workspace>/distZ asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `ai-gateway-semantic-cache`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `ai-gateway-semantic-cache` i bez `dir`: zapisze ono przykład w nowym folderze `ai-gateway-semantic-cache`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `ai-gateway-semantic-cache`, `release` ustawionym na `release.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisało budowanie; znajdują się w `ai-gateway-semantic-cache/dist/`.Wyrenderowane drzewo
dist/helm/├── cache--password--cache-secret-cache-password.yaml├── cache-default-service.yaml├── cache-deployment.yaml├── chat-service.yaml├── embeddings-service.yaml├── router--api-zukey--router-secret-router-api-key.yaml├── router--assistant-zdcredential--router-secret-router-assistant-credential.yaml├── router--embedder-zdcredential--router-secret-router-embedder-credential.yaml├── router--replies-zdcredential--router-secret-router-replies-credential.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlDołączenie pamięci podręcznej nie wnosi własnego pliku. To, co robi, jest zapisywane w konfiguracji bramy. Każdy model renderuje jeden plik — Service mapujący nazwę wewnątrz klastra na host API OpenAI — a każde poświadczenie w połączeniu z modelem renderuje własny Secret, nazwany od bramy i aliasu połączenia.
Obsługiwane modele
Tablica routingu, czyli początek treści konfiguracji bramy, ma jeden wpis
na każde połączenie w gnieździe models, zapisany na podstawie tego, co publikuje każdy model —
jego punktu końcowego, bazowego adresu URL API OpenAI i nazwy modelu — i wskazujący
zmienną, pod którą encja Recipe bramy dostarcza klucz tego połączenia:
model_list: - model_name: "assistant" litellm_params: model: "openai/gpt-4o" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEY - model_name: "embedder" litellm_params: model: "openai/text-embedding-3-small" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_EMBEDDER_API_KEYPamięć podręczna z perspektywy bramy
Oto treść konfiguracji bramy, klucz config.yaml pliku
dist/helm/router/litellm-gateway-config/configmap.yaml, od sekcji
litellm_settings:
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter cache: true cache_params: host: os.environ/SEMANTIC_CACHE_STORE_HOST port: os.environ/SEMANTIC_CACHE_STORE_PORT redis_semantic_cache_embedding_model: embedder redis_semantic_cache_index_name: router-answers semantic_cache_scope: end_user similarity_threshold: 0.9 supported_call_types: - acompletion - completion - aresponses - responses - aanthropic_messages - anthropic_messages ttl: 3600 type: redis-semanticWarto z niej odczytać pięć rzeczy.
Nie ma w niej adresu magazynu. host i port wskazują dwie zmienne
środowiskowe przez własny mechanizm pośredniości bramy, a encja Recipe bramy ustawia
je na podstawie krawędzi cache_store. Z pliku dist/helm/router-deployment.yaml,
env kontenera bramy:
env: - name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-key - name: REDIS_PASSWORD valueFrom: secretKeyRef: name: router-replies.credential key: password - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: router-assistant.credential key: api-key - name: LITELLM_MODEL_EMBEDDER_API_KEY valueFrom: secretKeyRef: name: router-embedder.credential key: api-key - name: SEMANTIC_CACHE_STORE_HOST value: cache-default - name: SEMANTIC_CACHE_STORE_PORT value: "6379"cache-default to obiekt Service emitowany przez encję Recipe samego magazynu, odczytany z tego,
co ta encja Recipe publikuje, a 6379 to publikowany przez nią port. Pamięć podręczna odczytuje
hasło magazynu z REDIS_PASSWORD, odwołania do obiektu Secret renderowanego przez credential na
krawędzi cache_store, router-replies.credential, a nigdy samego hasła. Magazyn renderuje
własny obiekt Secret z tego samego parametru, cache-password, i uruchamia się z --requirepass
odczytanym z niego, więc hasło przedstawiane przez pamięć podręczną i hasło wymagane przez magazyn
to jedna wartość, zapisana raz. Bez krawędzi cache_store nie jest renderowana żadna z trzech
zmiennych, pod którymi docierają adres i hasło magazynu, a pamięć podręczna, nie mając gdzie
przechowywać odpowiedzi, zatrzymuje kompilację, jak opisano niżej. Trzeci i czwarty wpis to klucze
modeli, każdy przywoływany z obiektu Secret renderowanego przez poświadczenie jego własnego
połączenia, pod zmienną wskazaną przez jego wpis w tablicy routingu; dostawca helm zapisuje każdy
wpis odczytywany z obiektu Secret przed zwykłymi.
Model osadzeń jest aliasem z własnej mapy bramy. Brama wysyła każdy prompt
do embedder przez tę samą mapę, przez którą przechodzi żądanie wywołującego,
więc pamięć podręczna nie ma własnego adresu ani poświadczenia. Wskazanie aliasu,
którego mapa nie publikuje, zatrzymuje kompilację z listą aliasów, które publikuje.
Czas życia określa magazyn. Każda odpowiedź jest zapisywana z ttl jako
czasem wygaśnięcia, więc Redis usuwa ją godzinę po zapisaniu. Na kolejne żądanie
z tym promptem odpowiada model, a odpowiedź jest zapisywana od nowa.
Wskazane są tylko te rodzaje żądań, których prompt odczytuje pamięć podręczna. Buforowane są żądania czatu, strumieniowane lub nie, oraz API responses i messages. Żądanie completions nie jest buforowane, podobnie jak żądanie embeddings: przy ustawieniu domyślnym brama zapisywałaby odpowiedź na każde żądanie embeddings, osadzając w tym celu każde wejście po raz drugi, i nie zwracałaby żadnej z nich.
Nazwa indeksu pochodzi od bramy i dołączenia, router-answers, więc
dwie bramy jednej encji Release współdzielące magazyn przechowują odpowiedzi
w osobnych indeksach.
Kto jest obsługiwany z jednego wpisu pamięci podręcznej
Zapisana odpowiedź jest zwracana późniejszemu żądaniu tylko wtedy, gdy zgadza się wszystko, co składa się na jej koszyk, a prompt jest podobny co najmniej w stopniu 0.9 do tego, na który odpowiedziała:
- klucz przedstawiony przez żądanie, w postaci zweryfikowanej przez bramę, wraz z zespołem i organizacją tego klucza;
- przy
end_user— użytkownik końcowy wskazany w żądaniu; - model, o który prosi żądanie, oraz pozostałe parametry żądania — inna temperatura oznacza inny koszyk.
Brama zapisuje klucz, jego zespół i organizację oraz użytkownika końcowego w samym żądaniu. W żądaniu czatu zapisuje je w polu metadata żądania, nadpisując każdą wartość, którą przesłał tam wywołujący; w żądaniu responses lub messages przechowuje je oddzielnie od metadata wywołującego, usuwa z niego każde pole zespołu, organizacji lub użytkownika końcowego zapisane przez wywołującego, a strażnik żądań dostarczany przez jej Recipe odrzuca żądanie wskazujące tam klucz, metadata.user_api_key, z kodem HTTP 400 podającym nazwę pola. Żadne żądanie nie może więc wprowadzić się do koszyka innego klucza przez samo jego wskazanie.
Własne metadata żądania może jednak przenosić je między koszykami klucza, który przedstawia. W żądaniu responses model_group zastępuje w jego koszyku model, o który prosi żądanie. W żądaniu responses lub messages caching_groups pozwala żądaniom wskazującym tę samą grupę aliasów modeli współdzielić odpowiedzi między nimi. W żądaniu responses lub czatu redis_namespace utrzymuje żądania wskazujące przestrzeń nazw w koszykach oddzielnych od tych, które żadnej nie wskazują. Żadne z nich nie sięga koszyka innego klucza.
Kluczem tej bramy jest jej klucz administracyjny i posiada go każdy wywołujący.
Brama nie ma podłączonej bazy danych do ewidencji, więc nie wydaje własnych kluczy: każdy wywołujący przedstawia klucz podłączony do api_key, a żądanie bez klucza lub z kluczem, którego brama nie wydała, jest odrzucane, zanim cokolwiek zostanie wyszukane. Klucz nie oddziela tu zatem żadnego wywołującego od innego, a przy domyślnym zakresie dwóch wywołujących rozdziela użytkownik końcowy wskazany w każdym żądaniu.
Przy end_user, wartości domyślnej, wpis jest zwracany żądaniom wskazującym tego samego użytkownika końcowego. Brama odczytuje użytkownika końcowego z żądania: z nagłówka x-litellm-end-user-id lub x-litellm-customer-id albo z pola treści user, metadata.user_id, litellm_metadata.user lub safety_identifier. Odpowiedź zapisana dla alice jest zwracana na podobnie sformułowane pytanie alice, ale nie na pytanie bob.
Wynikają z tego dwie rzeczy i obie są zachowaniem bramy, a nie konfiguracją:
- Brama nie weryfikuje żadnej z tych nazw. Każdy, kto posiada klucz, może wskazać dowolnego użytkownika końcowego i otrzyma to, co zapisano dla tego użytkownika. Klucz należy przechowywać w aplikacji, która wie, kim są jej użytkownicy końcowi, i pozwolić jej ich wskazywać; nie należy przekazywać klucza samym użytkownikom końcowym.
- Żądania niewskazujące użytkownika końcowego współdzielą jedną pamięć podręczną. Każde takie żądanie przedstawiające ten sam klucz jest obsługiwane z tych samych wpisów, niezależnie od tego, kto je wysłał.
Przy key każdy wywołujący przedstawiający klucz jest obsługiwany z jednej pamięci podręcznej. Należy dodać
scope: key do wartości podłączenia i przebudować: semantic_cache_scope w konfiguracji przyjmuje wartość key, a nic innego w wyrenderowanym wyniku się nie zmienia. Użytkownik końcowy wskazany w nagłówku nie jest wtedy częścią koszyka, więc odpowiedź zapisana dla alice, wskazanej w nagłówku x-litellm-end-user-id, jest zwracana na podobnie sformułowane pytanie bob wskazanego w ten sam sposób, łącznie z zawartymi w niej wywołaniami narzędzi. Pole treści user jest jednak jednym z pozostałych parametrów żądania, więc dwa żądania wskazujące w nim różnych użytkowników końcowych nadal trafiają do różnych koszyków, tak jak dwie temperatury. Pasuje to do pamięci podręcznej odpowiedzi, które są takie same dla wszystkich, i do niczego innego.
Co zatrzymuje kompilację
Każda z tych sytuacji to zdanie, które wypisuje kompilacja, wskazując, co należy zmienić:
-
Brak klucza administracyjnego. Po usunięciu podłączenia
api_keykompilacja zatrzymuje się, zanim cokolwiek zostanie wyrenderowane:[… omitted: a line reporting on the gateway configuration step's plugin, what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0033]Recipe/FeatureRecipe assertionscaused by: FeatureRecipe "semantic-caching-litellm" instance "router" assertion "gateway_checks_the_caller": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "router" needs core/gateway/litellm to check every caller's key before a cached reply is served, but its api_key credential slot is not attached, so the gateway checks no caller and a cache bucket would be made only of what each caller claims. Attach a credential to the api_key slot of "router" -
Brak magazynu. Po usunięciu krawędzi
cache_storekompilacja zatrzymuje się, wskazując gniazdo do podłączenia. -
Magazyn, który nie publikuje
vector_search. Gniazdo dopuszcza magazyny klucz-wartość, a Recipe bramy zatrzymuje kompilację na takim, który nie deklaruje, że obsługuje wyszukiwanie wektorowe silnika zapytań Redis, za pomocą którego pamięć podręczna przeszukuje swoje odpowiedzi: Redis w wersji wcześniejszej niż 8.0 lub Valkey nie buforowałyby niczego, choć każde żądanie nadal kończyłoby się powodzeniem. -
Drugie podłączenie
core/semantic-cachingw bramie, która ma jedną pamięć podręczną. -
core/data-maskingw tej samej bramie. Oba deklarują konflikt, ponieważ pamięć podręczna wyznacza klucz żądania po maskowaniu, więc dwa żądania różniące się tylko tym, co zastępuje maskowanie, współdzieliłyby jedną zapisaną odpowiedź.
Gdy magazynu nie można użyć
Brama łączy się z magazynem przy obsłudze pierwszego żądania, a nie przy uruchomieniu. Jeśli nie może użyć magazynu — magazyn wymaga hasła, którego brama nie otrzymała, albo odrzuca to, które otrzymała — każde wyszukiwanie kończy się chybieniem i nic nie jest zapisywane, a każde żądanie nadal otrzymuje odpowiedź od modelu. Informuje o tym jedynie własny dziennik bramy. Dlatego oba końce hasła odczytują jeden parametr: slot password magazynu oraz credential na krawędzi cache_store.
Gdzie kompilator nie interpretuje
Kompilator przekazuje nazwę Service magazynu i jego port z encji Recipe magazynu
do środowiska bramy jako ciągi znaków, a alias i liczby do konfiguracji bramy.
Nie łączy się z magazynem, nie wie, czy cokolwiek odpowiada pod adresem
cache-default:6379, i nie wie, kim jest użytkownik końcowy. Każde z opisanych
wyżej zatrzymań deklarują własne encje katalogu: jako asercję w realizacji lub w
encji Recipe bramy albo jako konflikt deklarowany przez dwie encje Features, i
żadne z nich nie opiera się na jakimkolwiek rozumieniu ruchu.
Dostosowywanie przykładu
- Jedna pamięć podręczna na klucz. Należy dodać
scope: keydo załącznikaanswerstam, gdzie każdy wywołujący powinien otrzymywać te same odpowiedzi. - Uruchamianie magazynu bez hasła. Należy usunąć jednocześnie załącznik
passwordmagazynu orazcredentialna krawędzicache_store, wraz z parametremcache_passwordw encji Aggregate i w encji Release; zmiennaREDIS_PASSWORDbramy jest wtedy renderowana jako pusta, co oznacza połączenie bez hasła. Usunięcie tylko jednego z dwóch załączników sprawia, że pamięć podręczna nie może korzystać z magazynu. - Dopasowywanie większej lub mniejszej liczby promptów. Podniesienie
similarity_thresholdsprawia, że obsługiwane są tylko bliższe dopasowania, a obniżenie – że obsługiwanych jest więcej; odpowiednia wartość zależy od modelu embeddingów.