AI-шлюз, який не зберігає персональні дані у своїх журналах
Асистент підтримки має працювати з іменами та адресами електронної пошти клієнтів, тож модель, яку він викликає, мусить їх бачити. Шлюз перед цією моделлю веде журнали для аудиту та налагодження, і ці журнали не повинні їх зберігати. Цей робочий простір компілює такий шлюз у маніфести Kubernetes.
Це робить значення самого шлюзу, values.log_masking у
core/gateway/litellm. Воно маскує копію кожного виклику, яку шлюз передає до своїх
журналів, і нічого більше: модель отримує запит саме таким, яким його надіслав
виклик, а той, хто викликає, отримує відповідь саме такою, якою її написала модель. У цьому
відмінність від Feature core/data-masking, що приховує текст від
самої моделі. Ці два варіанти є альтернативами, а розділ про вибір між
ними нижче показує, що відбувається, коли обидва задано в одному шлюзі.
Цей робочий простір не створює жодної власної сутності каталогу. Три файли сутностей тут — Aggregate, Manifest і Release — це все, що будь-хто пише.
Що він збирає
| екземпляр | Component із каталогу | що це тут |
|---|---|---|
router | core/gateway/litellm | AI-шлюз: один опублікований псевдонім, assistant, який обслуговує модель, під’єднана до його сокета models |
gpt | core/ai-model/openai | модель за цим псевдонімом — власний API OpenAI, доступний як посилання: для неї в кластері нічого не запускається |
analyzer | core/security/presidio-analyzer | знаходить у тексті чутливі фрагменти |
anonymizer | core/security/presidio-anonymizer | замінює передані йому фрагменти |
Три ребра uses: сокет шлюзу models до моделі, що несе як свій
credential ключ, який шлюз їй пред’являє, а також його сокети pii_analyzer і
pii_anonymizer до двох сервісів розпізнавання. Сутність Aggregate приєднує
ці облікові дані, не називаючи секрету, а сутність Release називає його в полі
infra приєднання: це Secret, який уже є в просторі імен і на який реалізація в сутності Manifest
посилається, але не рендерить його. Значення шлюзу values.log_masking
перелічує, що маскувати: регулярний вираз для номерів заявок компанії в
patterns, а також типи сутностей PERSON і EMAIL_ADDRESS в entities.
Списку за замовчуванням немає; шлюз, що не перелічує жодного з них, нічого не маскує у своїх журналах
і рендериться так само, як і без цього значення.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example ai-gateway-log-maskingПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd ai-gateway-log-maskingЗбирання
aggrega build --release release.yaml --auto-pullПерш ніж збирати release, йому потрібен lockfile, а lockfile-и генеруються, а не постачаються, тож у свіжому клоні їх немає. Спершу отримайте його або дозвольте збиранню його заповнити:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildЦей робочий простір знаходить сутності каталогу в реєстрі за замовчуванням, який називає .aggrega-config.yaml. Маскування журналів записує власний Recipe шлюзу, тож збирання не запускає жодного плагіна, крім тих, що є в самому компіляторі.
Збирання виводить таке (<workspace> позначає теку цього прикладу):
[… 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З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `ai-gateway-log-masking`, викличте один раз інструмент `scaffold`, задавши для `example` значення `ai-gateway-log-masking` і не задаючи `dir`: він запише приклад у нову теку `ai-gateway-log-masking`. Потім викличте інструмент `build`, задавши для `workspace_root` значення `ai-gateway-log-masking`, для `release` — `release.yaml`, для `auto_pull` — true і для `write` — true. Скажіть мені, які файли записала збірка; вони лежать у `ai-gateway-log-masking/dist/`.Згенероване дерево
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Значення не додає власного файлу. Recipe шлюзу записує його в конфігурацію шлюзу й додає до ConfigMap шлюзу модуль, який ця конфігурація завантажує. Модель генерує один файл, gpt-service.yaml, — Service, що відображає внутрішньокластерне ім’я на хост API OpenAI, api.openai.com; її ключ не генерує жодного, бо Secret, у якому він зберігається, уже існує.
Таблиця маршрутизації, початок тіла конфігурації шлюзу, має один запис, записаний з того, що публікує модель, — її кінцевої точки, базової URL-адреси API OpenAI та назви моделі, — і він називає змінну, під якою Recipe шлюзу передає ключ з’єднання:
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Запис guardrail
Ось тіло конфігурації шлюзу, ключ config.yaml файлу
dist/helm/router/litellm-gateway-config/configmap.yaml, починаючи з його
розділу 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: trueСутність Recipe шлюзу записує все це з values.log_masking і називає
запис на честь шлюзу, тут router, з крапкою там, де записи guardrail,
які пишуть реалізації стандартної бібліотеки, мають дефіс, тож жодне їхнє
приєднання, хоч як воно називається, не може зайняти місце цього запису. З нього
варто вичитати п’ять речей.
mode: logging_only — це власний режим шлюзу для guardrail, що виконується
там, де завершений виклик передається до журналів, і більше ніде. Клас, який
завантажує запис, дотримується його, хоч би що вказував запис, тож він ніколи не
викликається для запиту до того, як запит переслано, чи для відповіді до того, як
відповідь повернуто.
default_on: true запускає його для кожного виклику. Той, хто викликає, не може вимкнути його
із запиту, навіть запитом на вимкнення завжди ввімкнених guardrail
шлюзу.
Шаблон потрапляє до шлюзу точно таким, як його написано. Його зіставляють
усередині шлюзу без урахування регістру, і кожен збіг остаточно замінюється
назвою шаблону великими літерами у квадратних дужках: [TICKET_REDACTED]. Шлюз
компілює вираз під час запуску, і вираз, що не компілюється, не дає йому
запуститися — компілятор передає рядок далі, не читаючи його.
Типи сутностей знаходять дві служби розпізнавання. Запис не вказує
жодної адреси: шлюз читає обидві зі свого середовища, яке Recipe шлюзу
заповнює з двох ребер. З dist/helm/router-deployment.yaml — розділ
env контейнера шлюзу:
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Перша — це ключ моделі, на який посилаються із секрету, названого в сутності Release,
і який ніколи не виписується; дві інші — адреси служб розпізнавання. Ім’я людини
стає <PERSON>, а адреса — <EMAIL_ADDRESS>.
Невдалий виклик приховується, а не маскується. Шлюз не запускає guardrail
журналювання для виклику, що завершився невдачею, тому модуль, який завантажує запис, також надає
log_masking.withhold_failed_calls, зареєстрований одразу після захисту запитів,
а Recipe шлюзу записує поруч із ним два параметри. Цей callback
отримує запис невдалого виклику раніше за будь-який callback, зареєстрований після нього, і
замінює кожен текст, написаний тим, хто викликає, або моделлю, на [TEXT_WITHHELD], незалежно від збігу,
а текст помилки — на [ERROR_TEXT_WITHHELD], залишаючи без змін те, що надсилає повторна
спроба. disable_error_logs не допускає невдалі виклики до журналів
витрат, а redact_messages_in_exceptions не допускає повідомлення запиту до
подробиць, які шлюз додає до помилки.
Той самий ConfigMap містить другий ключ, log_masking.py: модуль, який називають
guardrail запису та другий запис callbacks. Recipe шлюзу додає
модуль, той запис callbacks, запис guardrail і два параметри лише
тоді, коли values.log_masking щось містить, тож шлюз, у якому нічого не вказано, генерує
ConfigMap без жодного з них, байт у байт як шлюз без цього значення.
Що бачить читач журналів і що бачить модель
Візьмімо абонента, чий запит містить такий текст:
My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.Блок вище і три блоки нижче ілюструють, що робить із ним запущений шлюз; вони не є результатом збірки.
Постачальник моделі отримує запит саме таким, яким його надіслав абонент, а абонент отримує відповідь моделі саме такою, якою вона надійшла. Інтеграція журналювання, якій шлюз передає виклик, отримує ті самі повідомлення в замаскованому вигляді:
My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.Номер телефону записується в журнал таким, яким його надіслано, бо приєднання не містить у переліку PHONE_NUMBER і жоден шаблон йому не відповідає. Текст, якому не відповідає нічого з переліку, ніколи не маскується.
Кожна копія успішного виклику, яку шлюз передає своїм журналам, маскується так само: повідомлення, повідомлення й відповідь стандартного корисного навантаження журналювання, потокова відповідь у тому вигляді, в якому її збирає шлюз, запит і відповідь у тому вигляді, в якому їх бачив постачальник, запит, який зберігають журнали витрат, і відповідь, яку отримує кожна інтеграція. Відповідь моделі в цих копіях також маскується:
Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].Що залишається незамаскованим
Маскування журналів не приховує текст ні від кого іншого, і опис values.log_masking про це каже:
- Постачальник моделі отримує все незамаскованим, як і шлюз та обидва сервіси розпізнавання.
- Невдалий виклик не залишає тексту запиту в жодному журналі, який пише шлюз, і це
має дві ціни. Власний рядок шлюзу для невдалого виклику зберігає лише
тип помилки, наприклад
An error was logged with its text withheld, as log masking is on: BadRequestError(Помилку записано в журнал із приховуванням тексту, оскільки маскування журналів увімкнено), тож повідомлення постачальника та його трасування стеку зникають із цього журналу; а невдалі виклики зникають із журналів витрат і щоденних підсумків витрат, які враховують лише успішні виклики. Інтеграція журналювання, налаштована поза каталогом, усе ще може прочитати власне повідомлення про помилку постачальника у винятку, який несе невдалий виклик, а інтеграція, зареєстрована перед власним зворотним викликом шлюзу, отримує текст невдалого виклику таким, яким він надійшов. - Охоплено лише журнали, через які пише маскування: не охоплено ні налагоджувальний вивід шлюзу, ні власні журнали постачальника. Метадані запиту, визначення його інструментів і його заголовки записуються в журнал так, як їх надіслано.
- Виклик, копії якого неможливо замаскувати, записується в журнал із прихованим текстом.
Коли сервіс розпізнавання недоступний, жодна копія не записується частково замаскованою: кожен
текст у кожній копії цього виклику замінюється на
[TEXT_WITHHELD], а запис передається до журналів як зазвичай, тож виклик усе одно враховується в журналах витрат. Власний журнал шлюзу фіксує, що текст виклику було приховано. На сам виклик надається відповідь як зазвичай.
У тому вигляді, у якому каталог рендерить цей шлюз, він не передає свої журнали жодній інтеграції журналювання, а його журнали витрат не зберігають ні тексту запитів чи відповідей, ні невдалих викликів. Отже, копії, які захищає маскування, — це ті, що їх отримала б інтеграція або журнал витрат зі збереженням тексту, налаштовані на шлюзі.
Маскування журналів чи маскування даних
core/data-masking приховує зазначений текст від моделі, а на цьому шлюзі її реалізація вимикає журналювання вмісту повідомлень шлюзом, доки її приєднано. Поруч із нею маскуванню журналів не залишилося б на що діяти, а читач міг би сприйняти їх як один і той самий захист. Тому шлюз відмовляється від їх поєднання: доки values.log_masking щось перелічує, приєднання core/data-masking до шлюзу зупиняє збирання завдяки твердженню власної сутності Component шлюзу.
Додавання до шлюзу приєднання з назвою masked, реалізацію якого прив’язано в сутності
Manifest, виводить:
[… 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Вдавайтеся до маскування журналів там, де модель має бачити дані, а журнали не мають їх зберігати; вдавайтеся до маскування даних там, де модель також не має їх бачити. Обидва читають ті самі patterns і entities, тож список означає те саме в
будь-якому з них.
Де компілятор не інтерпретує
Компілятор передає шаблон і типи сутностей у конфігурацію шлюзу як рядки. Він не компілює вираз, не знає, що таке номер заявки чи особа, і не бачить трафіку, який передаватиме шлюз. Кожну зупинку, з якою може зіткнутися цей робочий простір, — типи сутностей із непід’єднаним сокетом розпізнавача, тип сутності, який аналізатор не розпізнає англійською, маскування журналів поруч із маскуванням даних на одному шлюзі, з’єднання з керованою моделлю без облікових даних — оголошують власні сутності каталогу як твердження сутності Component шлюзу або його сутності Recipe, і жодна з них не спирається на будь-яке розуміння тексту.
Адаптація прикладу
- Маскувати лише шаблони. Вилучіть
entitiesзvalues.log_masking, а також два компоненти розпізнавання разом з їхніми ребрами та записами в Release; шаблони зіставляються всередині шлюзу й не потребують жодного з цих сервісів. - Маскувати більше типів сутностей. Додайте їх до
entities, у власному словнику розпізнавача; тип, який аналізатор не розпізнає англійською, зупиняє збирання й називає ті, які він розпізнає. - Приховати текст і від моделі. Замініть
values.log_maskingна прикріпленняcore/data-maskingдо шлюзу з тими самимиpatternsіentitiesта прив’яжіть його реалізацію в Manifest. - Обслуговувати другу модель. Під’єднайте ще один компонент моделі до сокета
modelsпід власним псевдонімом, із ключем, який шлюз пред’являє йому в цьому з’єднанні;values.modelі далі називає псевдонім, який публікує шлюз. Маскування застосовується до викликів кожного псевдоніма, який обслуговує шлюз.