Um gateway de IA que mantém os dados pessoais fora dos seus registos
Um assistente de apoio tem de trabalhar com os nomes e os endereços de e-mail dos clientes, pelo que o modelo que chama tem de os ver. O gateway à frente desse modelo mantém registos para auditoria e para depuração, e esses registos não os podem guardar. Este workspace compila um gateway deste tipo para manifestos Kubernetes.
O que o faz é um valor do próprio gateway, values.log_masking em core/gateway/litellm. Mascara a cópia de cada chamada que o gateway entrega aos seus registos, e nada mais: o modelo recebe o pedido exatamente como o chamador o 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 secção abaixo sobre a escolha entre elas mostra o que acontece quando ambas são definidas num mesmo gateway.
Este workspace não cria nenhuma entidade de catálogo própria. Os três ficheiros de entidade aqui presentes — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.
O que constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
router | core/gateway/litellm | o gateway de IA: um único alias publicado, assistant, servido a partir do modelo ligado ao seu socket models |
gpt | core/ai-model/openai | o modelo por trás desse alias, a própria API da OpenAI, alcançado como referência: nada é executado para ele no cluster |
analyzer | core/security/presidio-analyzer | encontra os trechos sensíveis num texto |
anonymizer | core/security/presidio-anonymizer | substitui os trechos que lhe são entregues |
Três arestas uses: o socket models do gateway para o modelo, que transporta 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 anexa essa credencial sem nomear um segredo, e a Release nomeia-a na infra do anexo: um Secret que o namespace já contém, que a realização do Manifest referencia e 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 em patterns, e os tipos de entidade PERSON e EMAIL_ADDRESS em entities. Não existe uma lista predefinida; um gateway que não liste nem uns nem outros não mascara nada nos seus registos, e é renderizado exatamente como sem o valor.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example ai-gateway-log-maskingDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd ai-gateway-log-maskingCompilação
aggrega build --release release.yaml --auto-pullUma release precisa de um lockfile antes de ser compilada, e os lockfiles são gerados em vez de distribuídos, pelo que um clone novo não tem nenhum. Resolva-se um primeiro, ou deixe-se que a compilação o preencha:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste workspace resolve as entidades do catálogo a partir do registo predefinido que .aggrega-config.yaml indica. É a própria Recipe do gateway que escreve o mascaramento de registos, pelo que a compilação não executa nenhum plugin além dos que o compilador traz.
A compilação imprime, com <workspace> a representar 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>/distCom um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta do espaço de trabalho 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`: esta escreve o exemplo numa 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 que ficheiros a compilação escreveu; encontram-se 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.yamlO valor não traz nenhum ficheiro próprio. A Recipe do gateway escreve-o na configuração do gateway, e acrescenta ao ConfigMap do gateway um módulo que essa configuração carrega. O modelo renderiza um único ficheiro, gpt-service.yaml, um Service que mapeia um nome interno do cluster para o anfitrião 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 encaminhamento, 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, o 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 ligaçã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_KEYA entrada do guardrail
Eis o corpo de configuração do gateway, a chave config.yaml de dist/helm/router/litellm-gateway-config/configmap.yaml, a partir da sua secçã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: 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: trueA Recipe do gateway escreve tudo isto 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 standard escrevem têm um hífen, pelo que nenhum anexo dessas realizações, seja qual for o seu nome, pode ocupar o lugar desta entrada. Há cinco coisas que vale a pena ler nela.
mode: logging_only é o modo próprio do gateway para um guardrail que é executado onde uma chamada concluída é entregue aos seus registos, e em mais nenhum sítio. A classe que a entrada carrega mantém-se nele, seja o que for que uma entrada nomeie, pelo que nunca é chamada sobre um pedido antes de o pedido ser reencaminhado, nem sobre uma resposta antes de a resposta ser devolvida.
default_on: true executa-o em todas as chamadas. Um chamador não o pode desligar a partir do pedido, nem sequer com um pedido que solicite a desativação dos guardrails sempre ativos do gateway.
O padrão chega ao gateway exatamente como foi escrito. É comparado dentro do gateway, sem distinguir maiúsculas de minúsculas, e cada correspondência é substituída definitivamente pelo nome do padrão em maiúsculas entre parênteses retos: [TICKET_REDACTED]. O gateway compila a expressão quando arranca, e uma que não compile impede-o de arrancar — o compilador passa a string sem a ler.
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 contentor 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:3000A 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 passa a <PERSON> e um endereço de e-mail a <EMAIL_ADDRESS>.
Uma chamada falhada é retida em vez de mascarada. O gateway não executa nenhum guardrail de registo para uma chamada que falha, pelo que o módulo que a entrada carrega também fornece log_masking.withhold_failed_calls, registado logo a seguir à guarda dos pedidos, e a Recipe do gateway escreve as duas definições ao lado dele. O callback recebe os dados de uma chamada falhada antes de qualquer callback registado depois dele, e substitui todo o 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 falhadas fora dos registos de despesa, e redact_messages_in_exceptions mantém as mensagens do pedido fora dos detalhes que o gateway anexa a um erro.
O mesmo ConfigMap tem 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 acrescenta o módulo, essa entrada de callbacks, a entrada do guardrail e as duas definições apenas enquanto values.log_masking listar algo, pelo que um gateway que não liste nada renderiza o ConfigMap sem nenhum deles, byte a byte como um gateway sem o valor.
O que vê quem lê os registos, e o que vê o modelo
Considere-se um chamador cujo pedido contém 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; não são saída da compilação.
O fornecedor do modelo recebe o pedido exatamente como o chamador o enviou, e o chamador recebe a resposta do modelo exatamente como chegou. Uma integração de registo à 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 é registado tal como foi enviado, porque o anexo não lista PHONE_NUMBER e nenhum padrão lhe corresponde. O texto a que nada do que está listado corresponde nunca é mascarado.
Todas as cópias de uma chamada bem-sucedida que o gateway entrega aos seus registos são mascaradas da mesma forma: as mensagens, as mensagens e a resposta do payload de registo standard, uma resposta em streaming à medida que o gateway a monta, o pedido e a resposta tal como o fornecedor os viu, o pedido que os registos de despesa 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 fica sem mascaramento
Mascarar os registos não esconde o texto de mais ninguém, e a descrição de values.log_masking di-lo:
- O fornecedor do modelo recebe tudo sem mascaramento, tal como o gateway e ambos os serviços de reconhecimento.
- Uma chamada falhada não guarda nenhum texto do pedido em nenhum registo que o gateway escreva, e isso custa duas coisas. A linha própria do gateway para uma chamada falhada guarda apenas o tipo de erro, como
An error was logged with its text withheld, as log masking is on: BadRequestError, pelo que a mensagem do fornecedor e o seu traceback saem desse registo; e as chamadas falhadas saem dos registos de despesa e dos totais diários de despesa, que contam apenas as chamadas bem-sucedidas. Uma integração de registo configurada fora do catálogo pode ainda ler a mensagem de erro própria de um fornecedor na exceção que uma chamada falhada transporta, e uma registada antes do callback próprio do gateway recebe o texto de uma chamada falhada tal como chegou. - Só estão abrangidos os registos através dos quais o mascaramento escreve: não a saída de depuração do gateway, nem os registos próprios de um fornecedor. Os metadados de um pedido, as suas definições de ferramentas e os seus cabeçalhos são registados tal como foram enviados.
- Uma chamada cujas cópias não podem ser mascaradas é registada com o seu texto retido. Quando um serviço de reconhecimento não está acessível, nenhuma cópia é registada parcialmente mascarada: todo o texto em todas as cópias dessa chamada é substituído por
[TEXT_WITHHELD], e os dados são entregues aos registos como habitualmente, pelo que a chamada continua a ser contada nos registos de despesa. O registo próprio do gateway assinala que o texto da chamada foi retido. A própria chamada é respondida como habitualmente.
Tal como o catálogo renderiza este gateway, este não entrega os seus registos a nenhuma integração de registo, e os seus registos de despesa não guardam nenhum texto de pedido ou de resposta nem nenhuma chamada falhada. Assim, as cópias que o mascaramento protege são as que receberiam uma integração ou um registo de despesa que guarde texto, configurados no gateway.
Mascaramento de registos ou mascaramento de dados
core/data-masking esconde do modelo o texto listado, e neste gateway a sua realização desliga o registo do conteúdo das mensagens pelo gateway enquanto estiver anexada. Ao lado dela, o mascaramento de registos não teria mais nada sobre que agir, e um leitor poderia tomar as duas por uma única proteção. Por isso, o gateway recusa as duas em conjunto: enquanto values.log_masking listar algo, um anexo core/data-masking no gateway interrompe a compilação, por meio de uma asserção do próprio Component do gateway. Acrescentar ao gateway um anexo 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 loggedRecorra-se ao mascaramento de registos quando o modelo tem de ver os dados e os registos não os podem guardar; recorra-se ao mascaramento de dados quando também o modelo não os pode ver. Ambos leem os mesmos patterns e entities, pelo que uma lista significa o mesmo em qualquer um deles.
Onde o compilador não interpreta
O compilador encaminha o padrão e os tipos de entidade para a configuração do gateway como strings. 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 por ligar, um tipo de entidade que o analisador não reconhece em inglês, mascaramento de registos ao lado de mascaramento de dados num mesmo gateway, a ligação ao modelo gerido 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 assenta em qualquer compreensão do texto.
Adaptá-lo
- Mascarar apenas padrões. Retire-se
entitiesdevalues.log_masking, bem como 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. Acrescentem-se a
entities, no vocabulário próprio do serviço de reconhecimento; um tipo que o analisador não reconhece em inglês interrompe a compilação e nomeia os que reconhece. - Esconder também o texto do modelo. Substitua-se
values.log_maskingpor um anexocore/data-maskingno gateway que liste os mesmospatternseentities, e vincule-se a sua realização no Manifest. - Servir um segundo modelo. Ligue-se outro componente de modelo ao socket
modelssob um alias próprio, com a chave que o gateway lhe apresenta nessa ligação;values.modelcontinua a nomear o alias que o gateway publica. O mascaramento aplica-se às chamadas de todos os aliases que o gateway serve.