Brama AI, która nie dopuszcza danych osobowych do swoich logów
Asystent wsparcia musi pracować z imionami i nazwiskami oraz adresami e-mail klientów, więc model, który wywołuje, musi je widzieć. Brama przed tym modelem prowadzi logi na potrzeby audytu i debugowania, a te logi nie mogą ich przechowywać. Ten obszar roboczy kompiluje taką bramę do manifestów Kubernetes.
Odpowiada za to wartość samej bramy, values.log_masking w
core/gateway/litellm. Maskuje ona kopię każdego wywołania, którą brama przekazuje do swoich
logów, i nic poza tym: model otrzymuje żądanie dokładnie w takiej postaci, w jakiej
wysłał je wywołujący, a wywołujący otrzymuje odpowiedź dokładnie w takiej postaci, w jakiej napisał ją model. Na tym
polega różnica względem encji Feature core/data-masking, która ukrywa tekst przed
samym modelem. Oba rozwiązania są alternatywami, a sekcja o wyborze między
nimi poniżej pokazuje, co się dzieje, gdy oba są ustawione w jednej bramie.
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: jeden opublikowany alias, assistant, obsługiwany przez model podłączony do jej gniazda models |
gpt | core/ai-model/openai | model stojący za tym aliasem, własne API OpenAI, osiągany jako odwołanie: nic nie działa dla niego w klastrze |
analyzer | core/security/presidio-analyzer | znajduje wrażliwe fragmenty w tekście |
anonymizer | core/security/presidio-anonymizer | zastępuje przekazane mu fragmenty |
Trzy krawędzie uses: gniazdo models bramy do modelu, niosące jako swój
credential klucz, którym brama się przed nim uwierzytelnia, oraz jej gniazda pii_analyzer i
pii_anonymizer do dwóch usług rozpoznających. Encja Aggregate dołącza
to poświadczenie bez nazywania sekretu, a encja Release nazywa je w polu
infra dołączenia: jest to Secret, który przestrzeń nazw już zawiera, a do którego
realizacja w encji Manifest się odwołuje, nie renderując go. Wartość values.log_masking bramy
wymienia, co maskować: wyrażenie regularne dla numerów zgłoszeń firmy w
patterns oraz typy encji PERSON i EMAIL_ADDRESS w entities.
Nie ma listy domyślnej; brama, która nie wymienia żadnego z nich, niczego w swoich logach nie maskuje
i renderuje się dokładnie tak, jak bez tej wartości.
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-log-maskingNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd ai-gateway-log-maskingKompilacja
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. Maskowanie logów zapisuje encja Recipe samej bramy, więc budowanie nie uruchamia żadnego pluginu poza tymi, które zawiera kompilator.
Budowanie wypisuje (<workspace> oznacza folder tego przykładu):
[… omitted: the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]Build completed: 9 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-log-masking`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `ai-gateway-log-masking` i bez `dir`: zapisze ono przykład w nowym folderze `ai-gateway-log-masking`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `ai-gateway-log-masking`, `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-log-masking/dist/`.Wyrenderowane drzewo
dist/helm/├── analyzer-default-service.yaml├── analyzer-deployment.yaml├── anonymizer-default-service.yaml├── anonymizer-deployment.yaml├── gpt-service.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlWartość nie wnosi własnego pliku. Recipe bramy zapisuje ją w konfiguracji
bramy i dodaje do ConfigMap bramy moduł, który ta konfiguracja ładuje. Model renderuje jeden plik, gpt-service.yaml: Service
odwzorowujący nazwę wewnątrzklastrową na host API OpenAI, api.openai.com; jego klucz
nie renderuje żadnego, ponieważ Secret, który go przechowuje, już istnieje.
Tablica routingu, początek treści konfiguracji bramy, ma jeden wpis, zapisany na podstawie tego, co publikuje model — jego punktu końcowego, bazowego adresu URL API OpenAI i nazwy modelu — i wskazujący zmienną, pod którą Recipe bramy dostarcza klucz 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_KEYWpis guardrail
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 - log_masking.withhold_failed_calls redact_messages_in_exceptions: trueguardrails: - guardrail_name: "router.log-masking" litellm_params: guardrail: log_masking.LogMasking default_on: true mode: logging_only patterns: - pattern_type: regex name: "ticket" pattern: "\\bTCK-[0-9]{6}\\b" action: MASK pii_entities_config: "PERSON": MASK "EMAIL_ADDRESS": MASKgeneral_settings: disable_error_logs: trueRecipe bramy zapisuje całość na podstawie values.log_masking i nazywa
wpis od nazwy bramy, tutaj router, z kropką w miejscu, w którym wpisy guardrail
zapisywane przez realizacje biblioteki standardowej mają łącznik, dzięki czemu żadne z ich
powiązań, niezależnie od nazwy, nie może zająć miejsca tego wpisu. Warto odczytać
z niego pięć rzeczy.
mode: logging_only to własny tryb bramy dla guardrail, który działa
tam, gdzie zakończone wywołanie jest przekazywane do logów, i nigdzie indziej. Klasa ładowana przez
wpis trzyma się go niezależnie od tego, co wpis wskazuje, więc nigdy nie jest wywoływana dla
żądania przed jego przekazaniem ani dla odpowiedzi przed jej
zwróceniem.
default_on: true uruchamia go przy każdym wywołaniu. Wywołujący nie może go wyłączyć
z poziomu żądania, również żądaniem wyłączenia zawsze aktywnych guardrail
bramy.
Wzorzec trafia do bramy dokładnie w takiej postaci, w jakiej go napisano. Jest dopasowywany wewnątrz
bramy bez rozróżniania wielkości liter, a każde dopasowanie jest trwale zastępowane
nazwą wzorca wielkimi literami w nawiasach kwadratowych: [TICKET_REDACTED]. Brama
kompiluje wyrażenie przy starcie, a wyrażenie, które się nie kompiluje, uniemożliwia jej
uruchomienie — kompilator przekazuje ciąg znaków dalej, nie odczytując go.
Typy encji wykrywają dwie usługi rozpoznające. Wpis nie podaje
żadnego adresu: brama odczytuje oba ze swojego środowiska, które Recipe bramy
wypełnia na podstawie dwóch krawędzi. Z dist/helm/router-deployment.yaml — sekcja
env kontenera bramy:
env: - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: openai-api-key key: api-key - name: PRESIDIO_ANALYZER_API_BASE value: http://analyzer-default:3000 - name: PRESIDIO_ANONYMIZER_API_BASE value: http://anonymizer-default:3000Pierwsza to klucz modelu, przywoływany z obiektu Secret wskazanego w encji Release i
nigdy nie wypisywany; dwie pozostałe to adresy usług rozpoznających. Imię i nazwisko osoby
staje się <PERSON>, a adres <EMAIL_ADDRESS>.
Nieudane wywołanie jest wstrzymywane, a nie maskowane. Brama nie uruchamia żadnego
guardrail logowania dla wywołania zakończonego błędem, dlatego moduł ładowany przez wpis udostępnia też
log_masking.withhold_failed_calls, rejestrowany zaraz po ochronie żądań,
a Recipe bramy zapisuje obok niego dwa ustawienia. Callback
otrzymuje rekord nieudanego wywołania przed każdym callbackiem zarejestrowanym po nim
i zastępuje każdy tekst napisany przez wywołującego lub model przez [TEXT_WITHHELD], dopasowany
czy nie, a tekst błędu przez [ERROR_TEXT_WITHHELD], pozostawiając bez zmian to, co wysyła
ponowiona próba. disable_error_logs wyłącza nieudane wywołania z logów
wydatków, a redact_messages_in_exceptions wyłącza wiadomości żądania ze
szczegółów, które brama dołącza do błędu.
Ten sam ConfigMap zawiera drugi klucz, log_masking.py: moduł wskazywany przez
guardrail wpisu i drugi wpis callbacks. Recipe bramy dodaje
moduł, ten wpis callbacks, wpis guardrail i dwa ustawienia tylko
wtedy, gdy values.log_masking coś wymienia, więc brama niczego niewymieniająca renderuje
ConfigMap bez żadnego z nich, bajt w bajt tak samo jak brama bez tej wartości.
Co widzi czytelnik logów, a co widzi model
Weźmy wywołującego, którego żądanie zawiera taki tekst:
My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.Powyższy blok i trzy poniższe ilustrują, co działająca brama z nim robi; nie są wynikiem kompilacji.
Dostawca modelu otrzymuje żądanie dokładnie w takiej postaci, w jakiej wysłał je wywołujący, a wywołujący otrzymuje odpowiedź modelu dokładnie w takiej postaci, w jakiej nadeszła. Integracja logowania, której brama przekazuje wywołanie, otrzymuje te same wiadomości zamaskowane:
My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.Numer telefonu jest logowany w postaci, w jakiej go wysłano, ponieważ dołączenie nie wymienia
PHONE_NUMBER i żaden wzorzec go nie dopasowuje. Tekst, którego nie dopasowuje nic z wymienionych,
nigdy nie jest maskowany.
Każda kopia udanego wywołania, którą brama przekazuje do swoich logów, jest maskowana w ten sam sposób: wiadomości, wiadomości i odpowiedź ze standardowego ładunku logowania, odpowiedź strumieniowana w postaci złożonej przez bramę, żądanie i odpowiedź w postaci, w jakiej widział je dostawca, żądanie przechowywane w logach wydatków oraz odpowiedź otrzymywana przez każdą integrację. Odpowiedź modelu również jest maskowana w tych kopiach:
Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].Co pozostaje niezamaskowane
Maskowanie logów nie ukrywa tekstu przed nikim innym, co stwierdza też opis
values.log_masking:
- Dostawca modelu otrzymuje wszystko bez maskowania, podobnie jak bramka i obie usługi rozpoznające.
- Nieudane wywołanie nie zostawia tekstu żądania w żadnym logu zapisywanym przez bramkę, co
ma dwa koszty. Własny wpis bramki dla nieudanego wywołania zawiera tylko
rodzaj błędu, na przykład
An error was logged with its text withheld, as log masking is on: BadRequestError, więc komunikat dostawcy i jego ślad stosu znikają z tego logu; a nieudane wywołania znikają z logów wydatków i z dziennych sum wydatków, które liczą wyłącznie udane wywołania. Integracja logowania skonfigurowana poza katalogiem nadal może odczytać własny komunikat błędu dostawcy z wyjątku, który niesie nieudane wywołanie, a integracja zarejestrowana przed własnym wywołaniem zwrotnym bramki otrzymuje tekst nieudanego wywołania w oryginalnej postaci. - Objęte są tylko logi, przez które zapisuje maskowanie: nie obejmuje ono wyjścia debugowania bramki ani własnych logów dostawcy. Metadane żądania, definicje jego narzędzi i jego nagłówki są logowane w postaci, w jakiej je wysłano.
- Wywołanie, którego kopii nie da się zamaskować, jest logowane z wstrzymanym tekstem.
Gdy usługa rozpoznająca jest nieosiągalna, żadna kopia nie jest logowana częściowo zamaskowana: każdy
tekst w każdej kopii tego wywołania zostaje zastąpiony przez
[TEXT_WITHHELD], a rekord trafia do logów jak zwykle, więc wywołanie nadal jest liczone w logach wydatków. Własny log bramki odnotowuje, że tekst wywołania został wstrzymany. Samo wywołanie otrzymuje odpowiedź jak zwykle.
W postaci, w jakiej katalog renderuje tę bramkę, nie przekazuje ona logów żadnej integracji logowania, a jej logi wydatków nie przechowują tekstu żądań ani odpowiedzi, ani nieudanych wywołań. Kopie chronione przez maskowanie to zatem te, które otrzymałaby integracja albo log wydatków przechowujący tekst, skonfigurowane w bramce.
Maskowanie logów czy maskowanie danych
core/data-masking ukrywa wymieniony tekst przed modelem, a w tej bramie jego realizacja wyłącza logowanie treści wiadomości przez bramę, dopóki jest dołączona. Obok niej maskowanie logów nie miałoby już na czym działać, a czytelnik mógłby wziąć te dwa mechanizmy za jedną ochronę. Dlatego brama odrzuca je razem: dopóki values.log_masking cokolwiek wymienia, dołączenie core/data-masking do bramy zatrzymuje budowanie na mocy asercji własnej encji Component bramy. Dodanie do bramy dołączenia o nazwie masked, z realizacją powiązaną w encji Manifest, wypisuje:
[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][DEVELOPER_ERROR E0033] Component/Feature assertions caused by: Component "core/gateway/litellm" instance "router" assertion "log_masking_not_beside_data_masking": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: "router" lists what to mask in its logs under values.log_masking, and the core/data-masking attachment "masked" is on it too: that attachment's realization turns the gateway's logging of message contents off, so log masking would have nothing left to act on, and a reader could take the two for one protection. Remove values.log_masking to mask what travels, or the "masked" attachment to mask only what is loggedMaskowanie logów należy stosować tam, gdzie model musi widzieć dane, a logi nie mogą ich przechowywać; maskowanie danych — tam, gdzie model również nie może ich widzieć. Oba mechanizmy odczytują te same patterns i entities, więc lista oznacza to samo w każdym z nich.
Gdzie kompilator nie interpretuje
Kompilator przekazuje wzorzec i typy encji do konfiguracji bramy jako ciągi znaków. Nie kompiluje wyrażenia, nie wie, czym jest numer zgłoszenia ani osoba, i nie widzi ruchu, który brama będzie obsługiwać. Każde zatrzymanie, na które może natrafić ten obszar roboczy — typy encji przy niepodłączonym gnieździe rozpoznawania, typ encji, którego analizator nie rozpoznaje w języku angielskim, maskowanie logów obok maskowania danych w jednej bramie, połączenie z zarządzanym modelem bez poświadczenia — jest zadeklarowane przez własne encje katalogu, jako asercja encji Component bramy lub jej encji Recipe, i żadne z nich nie opiera się na jakimkolwiek rozumieniu tekstu.
Dostosowywanie przykładu
- Maskowanie tylko wzorców. Należy usunąć
entitieszvalues.log_maskingoraz oba komponenty rozpoznające wraz z ich krawędziami i wpisami w encji Release; wzorce są dopasowywane wewnątrz bramy i nie potrzebują żadnej z tych usług. - Maskowanie większej liczby typów encji. Należy dodać je do
entities, w słownictwie samego komponentu rozpoznającego; typ, którego analizator nie rozpoznaje w języku angielskim, zatrzymuje kompilację i wymienia te, które rozpoznaje. - Ukrycie tekstu również przed modelem. Należy zastąpić
values.log_maskingdołączeniemcore/data-maskingna bramie, wymieniającym te samepatternsientities, oraz powiązać jego realizację w encji Manifest. - Obsługa drugiego modelu. Należy podłączyć inny komponent modelu do gniazda
modelspod jego własnym aliasem, z kluczem, który brama mu przedstawia w tym połączeniu;values.modelnadal wskazuje alias publikowany przez bramę. Maskowanie obejmuje wywołania każdego aliasu obsługiwanego przez bramę.