Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Um gateway de IA que mantém dados pessoais fora dos seus logs

Um assistente de suporte precisa trabalhar com os nomes e os endereços de e-mail dos clientes, então o modelo que ele chama precisa vê-los. O gateway na frente desse modelo mantém logs para auditoria e para depuração, e esses logs não podem guardá-los. Este workspace compila um gateway assim para manifestos Kubernetes.

O que faz isso é um valor do próprio gateway, values.log_masking em core/gateway/litellm. Ele mascara a cópia de cada chamada que o gateway entrega aos seus logs, e nada mais: o modelo recebe a requisição exatamente como o chamador a enviou, e o chamador recebe a resposta exatamente como o modelo a escreveu. Essa é a diferença em relação à Feature core/data-masking, que esconde o texto do próprio modelo. As duas são alternativas, e a seção abaixo sobre como escolher entre elas mostra o que acontece quando ambas são definidas em um mesmo gateway.

Este workspace não cria nenhuma entidade de catálogo própria. Os três arquivos de entidade daqui — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.

O que ele constrói

instânciaComponent do catálogoo que é aqui
routercore/gateway/litellmo gateway de IA: um único alias publicado, assistant, servido a partir do modelo ligado ao seu socket models
gptcore/ai-model/openaio modelo por trás desse alias, a própria API da OpenAI, alcançado como referência: nada é executado para ele no cluster
analyzercore/security/presidio-analyzerencontra os trechos sensíveis em um texto
anonymizercore/security/presidio-anonymizersubstitui os trechos que lhe são entregues

Três arestas uses: o socket models do gateway para o modelo, carregando como sua credential a chave que o gateway lhe apresenta, e os seus sockets pii_analyzer e pii_anonymizer para os dois serviços de reconhecimento. O Aggregate vincula essa credencial sem nomear um segredo, e a Release a nomeia na infra da vinculação: um Secret que o namespace já contém, ao qual a realização do Manifest faz referência e que ela não renderiza. O values.log_masking do gateway lista o que mascarar: uma expressão regular para os números de ticket da empresa sob patterns, e os tipos de entidade PERSON e EMAIL_ADDRESS sob entities. Não há lista padrão; um gateway que não lista nem um nem outro não mascara nada nos seus logs, e é renderizado exatamente como sem o valor.

Gerar o exemplo

Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.

Escreva o exemplo em uma nova pasta com o nome dele:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd ai-gateway-log-masking

Build

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

Uma release precisa de um lockfile antes de fazer o build, e os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum. Resolva um primeiro, ou deixe o build preenchê-lo:

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

Este workspace resolve as entidades do catálogo a partir do registro padrão que .aggrega-config.yaml nomeia. A própria Recipe do gateway escreve o mascaramento de logs, então o build não executa nenhum plugin além dos que o compilador carrega.

O build imprime, com <workspace> representando a pasta deste exemplo:

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

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `ai-gateway-log-masking`, chame a ferramenta `scaffold` uma única vez com `example` definido como `ai-gateway-log-masking` e sem `dir`: ela escreve o exemplo em uma nova pasta `ai-gateway-log-masking`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `ai-gateway-log-masking`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build escreveu; eles ficam em `ai-gateway-log-masking/dist/`.

A árvore renderizada

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

O valor não traz nenhum arquivo próprio. A Recipe do gateway o escreve na configuração do gateway, e adiciona ao ConfigMap do gateway um módulo que essa configuração carrega. O modelo renderiza um arquivo, gpt-service.yaml, um Service que mapeia um nome interno do cluster para o host da API da OpenAI, api.openai.com; a sua chave não renderiza nenhum, porque o Secret que a contém já existe.

A tabela de roteamento, o início do corpo de configuração do gateway, tem uma única entrada, escrita a partir do que o modelo publica — o seu endpoint, a URL base da API da OpenAI, e o seu nome de modelo — e que nomeia a variável sob a qual a Recipe do gateway entrega a chave da conexão:

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

A entrada do guardrail

Aqui está o corpo de configuração do gateway, a chave config.yaml de dist/helm/router/litellm-gateway-config/configmap.yaml, a partir da sua seção 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

A Recipe do gateway escreve tudo isso a partir de values.log_masking, e dá à entrada o nome do gateway, aqui router, com um ponto onde as entradas de guardrail que as realizações da biblioteca padrão escrevem levam um hífen, de modo que nenhuma vinculação delas, qualquer que seja o seu nome, pode tomar o lugar desta entrada. Cinco coisas valem a pena ser lidas nela.

mode: logging_only é o modo próprio do gateway para um guardrail que é executado onde uma chamada concluída é entregue aos seus logs, e em nenhum outro lugar. A classe que a entrada carrega se atém a ele, seja o que for que uma entrada nomeie, então ela nunca é chamada sobre uma requisição antes que a requisição seja encaminhada, nem sobre uma resposta antes que a resposta seja devolvida.

default_on: true o executa em toda chamada. Um chamador não pode desligá-lo a partir da requisição, nem mesmo com uma requisição que peça para desativar os guardrails sempre ativos do gateway.

O padrão chega ao gateway exatamente como foi escrito. Ele é comparado dentro do gateway, sem diferenciar maiúsculas de minúsculas, e cada correspondência é substituída definitivamente pelo nome do padrão em maiúsculas entre colchetes: [TICKET_REDACTED]. O gateway compila a expressão quando inicia, e uma que não compila o impede de iniciar — o compilador repassa a string sem lê-la.

Os tipos de entidade são encontrados pelos dois serviços de reconhecimento. A entrada não nomeia nenhum endereço: o gateway lê ambos do seu ambiente, que a Recipe do gateway preenche a partir das duas arestas. De dist/helm/router-deployment.yaml, o env do contêiner do gateway:

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

A primeira é a chave do modelo, referenciada a partir do Secret que a Release nomeia e nunca escrita por extenso; as outras duas são os endereços dos serviços de reconhecimento. O nome de uma pessoa se torna <PERSON> e um endereço de e-mail <EMAIL_ADDRESS>.

Uma chamada que falhou é retida em vez de mascarada. O gateway não executa nenhum guardrail de logging para uma chamada que falha, então o módulo que a entrada carrega também fornece log_masking.withhold_failed_calls, registrado logo após a guarda de requisições, e a Recipe do gateway escreve as duas configurações ao lado dele. O callback recebe os dados de uma chamada que falhou antes de qualquer callback registrado depois dele, e substitui todo texto que um chamador ou o modelo escreveu por [TEXT_WITHHELD], correspondido ou não, e o texto do erro por [ERROR_TEXT_WITHHELD], deixando como estava o que uma tentativa repetida envia. disable_error_logs mantém as chamadas que falharam fora dos logs de gastos, e redact_messages_in_exceptions mantém as mensagens da requisição fora dos detalhes que o gateway anexa a um erro.

O mesmo ConfigMap carrega uma segunda chave, log_masking.py: o módulo que o guardrail da entrada e a segunda entrada de callbacks nomeiam. A Recipe do gateway adiciona o módulo, essa entrada de callbacks, a entrada do guardrail e as duas configurações apenas enquanto values.log_masking lista algo, então um gateway que não lista nada renderiza o ConfigMap sem nenhum deles, byte a byte como um gateway sem o valor.

O que um leitor de logs vê, e o que o modelo vê

Considere um chamador cuja requisição carrega este texto:

My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.

O bloco acima e os três abaixo ilustram o que o gateway em execução faz com ele; eles não são saída do build.

O provedor do modelo recebe a requisição exatamente como o chamador a enviou, e o chamador recebe a resposta do modelo exatamente como ela veio. Uma integração de logging à qual o gateway entrega a chamada recebe as mesmas mensagens mascaradas:

My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.

O número de telefone é registrado no log como foi enviado, porque a vinculação não lista PHONE_NUMBER e nenhum padrão corresponde a ele. Texto ao qual nada listado corresponde nunca é mascarado.

Toda cópia de uma chamada bem-sucedida que o gateway entrega aos seus logs é mascarada da mesma forma: as mensagens, as mensagens e a resposta do payload de logging padrão, uma resposta em streaming à medida que o gateway a monta, a requisição e a resposta como o provedor as viu, a requisição que os logs de gastos guardam, e a resposta que cada integração recebe. A resposta do modelo também é mascarada nessas cópias:

Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].

O que permanece sem mascaramento

Mascarar os logs não esconde o texto de mais ninguém, e a descrição de values.log_masking diz isso:

  • O provedor do modelo recebe tudo sem mascaramento, assim como o gateway e os dois serviços de reconhecimento.
  • Uma chamada que falhou não guarda nenhum texto da requisição em nenhum log que o gateway escreve, e isso custa duas coisas. A linha própria do gateway para uma chamada que falhou guarda apenas o tipo de erro, como An error was logged with its text withheld, as log masking is on: BadRequestError, então a mensagem do provedor e o seu traceback saem desse log; e as chamadas que falharam saem dos logs de gastos e dos totais diários de gastos, que contam apenas chamadas bem-sucedidas. Uma integração de logging configurada fora do catálogo ainda pode ler a mensagem de erro própria de um provedor na exceção que uma chamada que falhou carrega, e uma registrada antes do callback próprio do gateway recebe o texto de uma chamada que falhou como ele veio.
  • Apenas os logs pelos quais o mascaramento escreve são cobertos: não a saída de depuração do gateway, e não os logs próprios de um provedor. Os metadados de uma requisição, as suas definições de ferramentas e os seus cabeçalhos são registrados no log como foram enviados.
  • Uma chamada cujas cópias não podem ser mascaradas é registrada no log com o seu texto retido. Quando um serviço de reconhecimento não pode ser alcançado, nenhuma cópia é registrada parcialmente mascarada: todo texto em toda cópia dessa chamada é substituído por [TEXT_WITHHELD], e os dados são entregues aos logs como de costume, então a chamada ainda é contada nos logs de gastos. O log próprio do gateway registra que o texto da chamada foi retido. A própria chamada é respondida como de costume.

Da forma como o catálogo renderiza este gateway, ele não entrega os seus logs a nenhuma integração de logging, e os seus logs de gastos não guardam nenhum texto de requisição ou de resposta nem nenhuma chamada que falhou. Então as cópias que o mascaramento protege são as que receberiam uma integração ou um log de gastos que guarda texto, configurados no gateway.

Mascaramento de logs ou mascaramento de dados

core/data-masking esconde do modelo o texto listado, e neste gateway a sua realização desliga o registro em log do conteúdo das mensagens pelo gateway enquanto está vinculada. Ao lado dela, o mascaramento de logs não teria mais nada sobre o que agir, e um leitor poderia tomar as duas por uma única proteção. Então o gateway recusa as duas juntas: enquanto values.log_masking lista algo, uma vinculação core/data-masking no gateway interrompe o build, por meio de uma asserção do próprio Component do gateway. Adicionar ao gateway uma vinculação com o nome masked, com a sua realização vinculada no Manifest, imprime:

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

Recorra ao mascaramento de logs quando o modelo precisa ver os dados e os logs não podem guardá-los; recorra ao mascaramento de dados quando o modelo também não pode vê-los. Ambos leem os mesmos patterns e entities, então uma lista significa a mesma coisa em qualquer um dos dois.

Onde o compilador não interpreta

O compilador roteia o padrão e os tipos de entidade para a configuração do gateway como strings. Ele não compila a expressão, não sabe o que é um número de ticket ou uma pessoa, e não vê o tráfego que o gateway vai transportar. Cada interrupção que este workspace pode encontrar — tipos de entidade com um socket de reconhecimento não ligado, um tipo de entidade que o analisador não reconhece em inglês, mascaramento de logs ao lado de mascaramento de dados em um mesmo gateway, a conexão com o modelo gerenciado sem nenhuma credencial — é declarada pelas próprias entidades do catálogo, como uma asserção do Component do gateway ou da sua Recipe, e nenhuma delas se apoia em qualquer compreensão do texto.

Adaptando-o

  • Mascarar apenas padrões. Remova entities de values.log_masking, e os dois componentes de reconhecimento com as suas arestas e as suas entradas na Release; os padrões são comparados dentro do gateway e não precisam de nenhum dos dois serviços.
  • Mascarar mais tipos de entidade. Adicione-os a entities, no vocabulário próprio do serviço de reconhecimento; um tipo que o analisador não reconhece em inglês interrompe o build e nomeia os que ele reconhece.
  • Esconder o texto também do modelo. Substitua values.log_masking por uma vinculação core/data-masking no gateway que liste os mesmos patterns e entities, e vincule a sua realização no Manifest.
  • Servir um segundo modelo. Ligue outro componente de modelo ao socket models sob um alias próprio, com a chave que o gateway lhe apresenta nessa conexão; values.model continua nomeando o alias que o gateway publica. O mascaramento se aplica às chamadas de cada alias que o gateway serve.