Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

AI-шлюз, который не допускает персональные данные в свои журналы

Ассистенту поддержки приходится работать с именами и адресами электронной почты клиентов, поэтому модель, которую он вызывает, должна их видеть. Шлюз перед этой моделью ведёт журналы для аудита и отладки, и в этих журналах их быть не должно. Это рабочее пространство компилирует такой шлюз в манифесты Kubernetes.

Это делает значение самого шлюза — values.log_masking в core/gateway/litellm. Оно маскирует копию каждого вызова, которую шлюз передаёт в свои журналы, и ничего больше: модель получает запрос ровно в том виде, в каком его отправил вызывающий, а вызывающий получает ответ ровно в том виде, в каком его написала модель. В этом и состоит отличие от сущности Feature core/data-masking, которая скрывает текст от самой модели. Эти два способа — альтернативы, и раздел о выборе между ними ниже показывает, что происходит, если оба заданы для одного шлюза.

Это рабочее пространство не определяет ни одной собственной сущности каталога. Три файла сущностей здесь — Aggregate, Manifest и Release — это всё, что кому-либо приходится писать.

Что собирается

экземплярсущность Component из каталогачем он является здесь
routercore/gateway/litellmAI-шлюз: один опубликованный псевдоним, assistant, обслуживаемый моделью, подключённой к его сокету models
gptcore/ai-model/openaiмодель за этим псевдонимом — собственный API OpenAI, доступный по ссылке: в кластере для неё ничего не запускается
analyzercore/security/presidio-analyzerнаходит конфиденциальные фрагменты в тексте
anonymizercore/security/presidio-anonymizerзаменяет переданные ему фрагменты

Три ребра uses: сокет models шлюза к модели, несущий в качестве своего credential ключ, который шлюз ей предъявляет, и его сокеты pii_analyzer и pii_anonymizer к двум сервисам распознавания. Сущность Aggregate подключает эти учётные данные, не называя секрет, а сущность Release называет его в infra подключения: Secret, который уже есть в пространстве имён и на который реализация в сущности Manifest ссылается, не отрисовывая его. Значение values.log_masking шлюза перечисляет, что маскировать: регулярное выражение для номеров заявок компании в patterns и типы сущностей PERSON и EMAIL_ADDRESS в entities. Списка по умолчанию нет: шлюз, в котором не указано ни то ни другое, ничего не маскирует в своих журналах и отрисовывается точно так же, как без этого значения.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd ai-gateway-log-masking

Сборка

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

Перед сборкой релизу нужен lock-файл, а lock-файлы генерируются, а не поставляются, поэтому в свежем клоне его нет. Сначала разрешите его или позвольте сборке его заполнить:

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

Это рабочее пространство разрешает сущности каталога из реестра по умолчанию, который указывает .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: 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 шлюза записывает всё это из 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

Первая переменная — ключ модели, на который ссылаются из Secret, названного в сущности Release, и который никогда не записывается явно; две другие — адреса распознавателей. Имя человека превращается в <PERSON>, а адрес — в <EMAIL_ADDRESS>.

Неудачный вызов не маскируется, а скрывается. Для неудачного вызова шлюз не запускает guardrail журналирования, поэтому модуль, который загружает запись, также предоставляет log_masking.withhold_failed_calls, регистрируемый сразу после защиты запроса, а Recipe шлюза записывает рядом с ним две настройки. Обратный вызов получает запись неудачного вызова раньше любого обратного вызова, зарегистрированного после него, и заменяет любой текст, написанный вызывающей стороной или моделью, на [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 по-прежнему называет псевдоним, который публикует шлюз. Маскировка применяется к вызовам каждого псевдонима, который обслуживает шлюз.