Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Features e policy

Questa pagina spiega un’unica idea, associare un comportamento a un componente e verificare il risultato con una policy, e non è un workspace eseguibile. Una policy che arresta una build quando dati riservati raggiungono un modello gestito senza essere mascherati mostra entrambe le cose in un workspace di cui esegui la build; scrivilo in una tua cartella con:

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

Poi stampa i prossimi comandi da eseguire:

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

Una Feature viene associata, e una FeatureRecipe la realizza

Una Feature è un comportamento che un componente non ha di per sé — il mascheramento, un backup, un ingress, una credenziale — e che un autore gli associa sotto features:. Chi la associa discende da chi ne decide gli input: lo sviluppatore associa, nell’Aggregate, una Feature il cui comportamento fa parte di ciò che l’applicazione è; l’operatore associa, nella Release, una Feature i cui input sono tutti operativi. In entrambi i casi il Manifest lega ogni Feature a una FeatureRecipe, che decide come viene realizzata per il target.

Nell’esempio, lo sviluppatore associa la core/data-masking della libreria standard a un gateway di IA ed elenca che cosa mascherare, da aggregate.yaml con i commenti omessi:

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]

Lo sviluppatore non indica alcun indirizzo, guardrail o impostazione del provider. Il Manifest lega core/data-masking a helm/data-masking-litellm, che scrive il mascheramento nella configurazione che renderizza la Recipe del gateway stesso, attraverso passi della pipeline di plugin che chiude il rendering, e aggiunge accanto un modulo che il gateway carica. Ogni altro file che la build scrive è identico byte per byte a quello di una build senza il collegamento.

Ciò che l’associazione non fa è indicato con la stessa cura di ciò che fa: il testo che nessun pattern intercetta e che il riconoscitore non rileva passa invariato, il gateway e i due servizi del riconoscitore vedono il testo originale, e il traffico che non passa attraverso il gateway non viene toccato. I commenti della FeatureRecipe elencano ciò che questo gateway rifiuta e ciò che lascia passare così come è stato inviato.

Le etichette decidono dove può andare una Feature

Le etichette sono l’identità semantica di un componente, e guidano il posizionamento di una Feature, i selettori dei socket e le policy senza alcuna modifica al compilatore. Il campo appliesTo di una Feature è un selettore di etichette applicato al componente a cui è associata. core/data-masking dichiara appliesTo: "dataplane.aggrega.ai/content-masking", una chiave nuda, che corrisponde a qualsiasi componente che porti quell’etichetta, qualunque ne sia il valore; core/gateway/litellm la porta, con il valore entity-recognition. Un selettore può anche confrontare valori, component.aggrega.ai/type in (server, worker), o escludere un’etichetta, !model.aggrega.ai/capability; i requisiti di un selettore, separati da virgole, devono valere tutti, e la Feature si associa solo a un componente a cui corrispondono. Associazione basata sulle etichette fornisce l’intera grammatica dei selettori.

Altre due dichiarazioni vincolano le associazioni:

  • Interoperabilità. Una Feature può indicare le Features con cui non può condividere un componente. core/data-masking dichiara interoperability.conflictsWith: [core/semantic-caching], quindi una build in cui un componente finisce per portarle entrambe — associate al componente stesso oppure a un sottosistema o a un confine che lo contiene — si arresta prima del rendering.
  • Obblighi di presenza. Un Component può richiedere che sia presente un’associazione di un dato tipo. Nel catalogo, example/compute/service porta l’annotazione features.aggrega.ai/requiredType.monitoring: core/prometheus-exporter, quindi una build in cui una sua istanza non porta alcuna core/prometheus-exporter, a qualsiasi livello, si arresta indicando il requisito monitoring. Ripeti la chiave con un altro suffisso per richiedere un secondo tipo; vedi entities/component.md «Presence mandates (Obblighi di presenza)» per come un obbligo differisce da uno slot di associazione.

Una Feature va sul componente di cui modifica il comportamento. core/caller-allowlist è associata a un server di modelli, non ai gateway autorizzati a chiamarlo; Un server di modelli che solo il suo gateway può chiamare ne esegue la build.

Una policy legge il grafo costruito

Le policy vengono associate dall’operatore sotto plugins.governance nella configurazione del workspace, ciascuna associazione in un ruolo. Una policy nel ruolo label-transform aggiunge etichette al grafo; una nel ruolo ir-verdict lo giudica e può arrestare la build. Il motore Rego le esegue entrambe; è compilato nella CLI, e governance/rego è la sua entità Plugin nel catalogo della libreria standard.

La prima regola qui sotto etichetta ogni gateway che analizza il payload del modello che inoltra come un punto in cui i prompt partono verso un provider di modelli. In questo ruolo i nodi si trovano in 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"
}

La seconda arresta qualsiasi percorso attraverso un gateway di questo tipo che non porta alcun mascheramento:

# 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]
)
}

L’id di un nodo è la chiave sotto cui si trova in input.graph.spec.nodes; attached_features elenca i tipi di Feature associati a qualsiasi nodo del percorso, quindi l’appartenenza si verifica con in; la regola controlla che il mascheramento sia associato, non che cosa elenchi; e una decisione raccolta sotto deny viene segnalata con la severità halt, che arresta la build. Una regola sui percorsi vede un nodo solo dove un arco lo raggiunge o ne parte, quindi una policy che deve coprire anche un nodo non collegato legge i nodi stessi.

L’operatore associa il motore una volta per ruolo, ciascuna associazione con il proprio file di policy; un percorso relativo sotto sources si risolve rispetto alla directory del file di configurazione, e la trasformazione viene eseguita prima del verdetto:

.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

La pagina del socket di governance è la superficie di scrittura completa: il payload che ogni ruolo espone, le chiavi di decisione e come dare un nome alle tue. L’esempio Policy che danno forma alle etichette associa una policy che dà forma alle etichette accanto ai due plugin di etichettatura integrati e ne esegue la build.