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

instancjaencja Component z kataloguczym jest tutaj
routercore/gateway/litellmbrama AI: jeden opublikowany alias, assistant, obsługiwany przez model podłączony do jej gniazda models
gptcore/ai-model/openaimodel stojący za tym aliasem, własne API OpenAI, osiągany jako odwołanie: nic nie działa dla niego w klastrze
analyzercore/security/presidio-analyzerznajduje wrażliwe fragmenty w tekście
anonymizercore/security/presidio-anonymizerzastę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:

Terminal window
aggrega scaffold --example ai-gateway-log-masking

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

Terminal window
cd ai-gateway-log-masking

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

Wartość 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_KEY

Wpis 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: true
guardrails:
- 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": MASK
general_settings:
disable_error_logs: true

Recipe 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:3000

Pierwsza 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 logged

Maskowanie 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ąć entities z values.log_masking oraz 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_masking dołączeniem core/data-masking na bramie, wymieniającym te same patterns i entities, oraz powiązać jego realizację w encji Manifest.
  • Obsługa drugiego modelu. Należy podłączyć inny komponent modelu do gniazda models pod jego własnym aliasem, z kluczem, który brama mu przedstawia w tym połączeniu; values.model nadal wskazuje alias publikowany przez bramę. Maskowanie obejmuje wywołania każdego aliasu obsługiwanego przez bramę.