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

Features e políticas

Esta página explica uma única ideia, vincular um comportamento a um componente e verificar o resultado com uma política, e não é um espaço de trabalho executável. Uma política que interrompe um build quando dados restritos chegam sem mascaramento a um modelo gerenciado mostra as duas coisas em um espaço de trabalho que você compila; grave-o em uma pasta sua com:

Terminal window
aggrega scaffold --example policy-data-class-route

Em seguida ele imprime os próximos comandos a executar:

Terminal window
cd policy-data-class-route
aggrega build --release release-masked.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release-unmasked.yaml --config governance-rego.yaml --auto-pull # halts; exits 1
aggrega build --release release-masking-off-route.yaml --config governance-rego.yaml --auto-pull # halts; exits 1

Uma Feature é vinculada, e realizada por uma FeatureRecipe

Uma Feature é um comportamento que um componente não tem por si só — mascaramento, um backup, um ingress, uma credencial — e que um autor vincula a ele em features:. Quem a vincula decorre de quem decide suas entradas: o desenvolvedor vincula, no Aggregate, uma Feature cujo comportamento faz parte do que a aplicação é; o operador vincula, na Release, uma cujas entradas são todas operacionais. Em ambos os casos, o Manifest associa cada Feature a uma FeatureRecipe, que decide como ela é realizada para o destino.

No exemplo, o desenvolvedor vincula a core/data-masking da biblioteca padrão a um gateway de IA e lista o que mascarar, a partir de aggregate.yaml sem os comentários:

masking-gateway:
type: core/gateway/litellm
values:
model: chat
features:
masking:
type: core/data-masking
values:
patterns:
- name: claim_number
regex: '\bCLM-[0-9]{8}\b'
entities: [PERSON, EMAIL_ADDRESS]

O desenvolvedor não indica nenhum endereço, guardrail ou configuração de provedor. O Manifest associa core/data-masking a helm/data-masking-litellm, que escreve o mascaramento na configuração que a própria Recipe do gateway renderiza, por meio de etapas do pipeline de plugins que encerra a renderização, e adiciona ao lado um módulo que o gateway carrega. Todos os outros arquivos que o build escreve são idênticos byte a byte aos de um build sem o anexo.

O que a vinculação não faz é declarado com o mesmo cuidado que o que ela faz: o texto com o qual nenhum padrão corresponde e que o reconhecedor não detecta passa inalterado, o gateway e os dois serviços do reconhecedor veem o texto original, e o tráfego que não passa pelo gateway não é tocado. Os comentários da FeatureRecipe listam o que este gateway recusa e o que ele repassa como foi enviado.

Os rótulos decidem onde uma Feature pode ir

Os rótulos são a identidade semântica de um componente, e determinam o posicionamento de uma Feature, os seletores de sockets e as políticas sem nenhuma alteração no compilador. O campo appliesTo de uma Feature é um seletor de rótulos sobre o componente ao qual ela está vinculada. core/data-masking declara appliesTo: "dataplane.aggrega.ai/content-masking", uma chave isolada, que corresponde a qualquer componente que tenha esse rótulo, seja qual for o seu valor; core/gateway/litellm o tem, com o valor entity-recognition. Um seletor também pode corresponder a valores, component.aggrega.ai/type in (server, worker), ou excluir um rótulo, !model.aggrega.ai/capability; os requisitos de um mesmo seletor, separados por vírgulas, devem ser todos atendidos, e a Feature se vincula apenas a um componente ao qual eles correspondam. Vinculação baseada em rótulos apresenta a gramática completa dos seletores.

Mais duas declarações restringem as vinculações:

  • Interoperabilidade. Uma Feature pode nomear Features com as quais não pode compartilhar um componente. core/data-masking declara interoperability.conflictsWith: [core/semantic-caching], então um build em que um componente acabe carregando ambas — vinculadas ao próprio componente, ou a um subsistema ou fronteira que o contém — é interrompido antes da renderização.
  • Exigências de presença. Um Component pode exigir que uma vinculação de determinado tipo esteja presente. O example/compute/service do catálogo tem a anotação features.aggrega.ai/requiredType.monitoring: core/prometheus-exporter, então um build em que uma instância dele não tenha nenhuma core/prometheus-exporter, em nenhum escopo, é interrompido nomeando o requisito monitoring. Repita a chave com outro sufixo para exigir um segundo tipo; veja entities/component.md “Presence mandates (Exigências de presença)” para saber como uma exigência difere de um slot de vinculação.

Uma Feature fica no componente cujo comportamento ela altera. core/caller-allowlist é vinculada a um servidor de modelos, não aos gateways autorizados a chamá-lo; Um servidor de modelos que só o seu gateway pode chamar faz o build disso.

Uma política lê o grafo construído

As políticas são vinculadas pelo operador em plugins.governance na configuração do espaço de trabalho, cada vinculação em um papel. Uma política no papel label-transform adiciona rótulos ao grafo; uma no papel ir-verdict o julga e pode interromper o build. O motor Rego executa ambas; ele é compilado na CLI, e governance/rego é a sua entidade Plugin no catálogo da biblioteca padrão.

A primeira regra abaixo marca cada gateway que analisa o payload de modelo que encaminha como um ponto em que os prompts saem para um provedor de modelos. Nesse papel, os nós ficam em input.graph.nodes:

# policies/egress-tagging.rego: attached at the label-transform role
package aggrega.tagging
import rego.v1
labels contains {"node": id, "key": "compliance.aggrega.ai/egress", "value": "model-provider"} if {
some id, node in input.graph.nodes
node.labels["gateway.aggrega.ai/intelligence"] == "semantic"
}

A segunda interrompe qualquer caminho através de um gateway desse tipo que não tenha mascaramento:

# policies/model-egress.rego: attached at the ir-verdict role
package aggrega.security
import rego.v1
deny contains msg if {
some path in input.precalculated_paths
some egress in path.nodes
input.graph.spec.nodes[egress].labels["compliance.aggrega.ai/egress"] == "model-provider"
not "core/data-masking" in path.attached_features
msg := sprintf(
"BLOCKED: path %v sends model traffic through %v without core/data-masking attached.",
[concat(" -> ", path.nodes), egress]
)
}

O id de um nó é a chave sob a qual ele fica em input.graph.spec.nodes; attached_features lista os tipos de Feature vinculados a qualquer nó do caminho, então a pertinência é testada com in; a regra verifica que o mascaramento está vinculado, não o que ele lista; e uma decisão coletada em deny é reportada com a severidade halt, que interrompe o build. Uma regra sobre caminhos só vê um nó onde uma aresta chega a ele ou sai dele, então uma política que também precise cobrir um nó não conectado lê os próprios nós.

O operador vincula o motor uma vez por papel, cada vinculação com o seu próprio arquivo de política; um caminho relativo em sources é resolvido em relação ao diretório do arquivo de configuração, e a transformação é executada antes do veredito:

.aggrega-config.yaml
plugins:
governance:
- uri: governance/rego:0.9.0
role: label-transform
with:
sources:
- policies/egress-tagging.rego
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policies/model-egress.rego

A página do socket de governança é a superfície de autoria completa: o payload que cada papel expõe, as chaves de decisão e como nomear as suas. O exemplo Políticas que moldam rótulos vincula uma política que molda rótulos ao lado dos dois plugins de rotulagem integrados e faz o build dela.