Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

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

instancjaencja Component z kataloguczym jest tutaj
routercore/gateway/litellmbrama AI: alias czatu assistant i alias embeddingów embedder, każdy obsługiwany przez model podłączony do jej gniazda models
chatcore/ai-model/openaimodel czatu stojący za assistant, własne API OpenAI, osiągane jako odwołanie: nic nie działa dla niego w klastrze
embeddingscore/ai-model/openai-embeddingmodel embeddingów stojący za embedder, osiągany w ten sam sposób
cachecore/datastore/redismagazyn, 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:

Terminal window
aggrega scaffold --example ai-gateway-semantic-cache

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd ai-gateway-semantic-cache

Kompilacja

Terminal window
aggrega build --release release.yaml --auto-pull

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

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Ten 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>/dist

Z 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.yaml

Dołą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_KEY

Pamięć 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-semantic

Warto 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_key kompilacja 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 assertions
    caused 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_store kompilacja 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-caching w bramie, która ma jedną pamięć podręczną.

  • core/data-masking w 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: key do załącznika answers tam, gdzie każdy wywołujący powinien otrzymywać te same odpowiedzi.
  • Uruchamianie magazynu bez hasła. Należy usunąć jednocześnie załącznik password magazynu oraz credential na krawędzi cache_store, wraz z parametrem cache_password w encji Aggregate i w encji Release; zmienna REDIS_PASSWORD bramy 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_threshold sprawia, ż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.