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

NeMo Guardrails che controlla le richieste di un agente con i modelli NemoGuard di NVIDIA

Le richieste al modello di un agente passano attraverso NVIDIA NeMo Guardrails, che controlla ciascuna di esse con due dei modelli NemoGuard di NVIDIA, prodotti NVIDIA con licenza che per funzionare richiedono una licenza di NVIDIA, una chiave API NGC e un nodo GPU.

Che cosa richiede

I due modelli NemoGuard sono prodotti NVIDIA che esegui alle condizioni di NVIDIA. Distribuire ciò che questo workspace compila richiede:

  • Una licenza di NVIDIA. La documentazione di NVIDIA per ciascun microservizio NemoGuard indica come prerequisito «an active subscription to an NVIDIA AI Enterprise product or be an NVIDIA Developer Program member» (un abbonamento attivo a un prodotto NVIDIA AI Enterprise o essere membro del NVIDIA Developer Program), e afferma che l’accesso ai container e ai modelli è riservato.
  • Una chiave API NGC, referenziata dalla Release come segreto. I container NemoGuard vengono scaricati dal registry di NVIDIA, nvcr.io, e ciascuno scarica il proprio modello da NVIDIA con la chiave all’avvio. La Release nomina due Secret Kubernetes che la contengono — uno da cui i pod leggono la chiave, uno con cui il cluster scarica le immagini — e nessun file in questo workspace, né nulla di ciò che il build scrive, contiene la chiave stessa.
  • Un nodo GPU. Ogni container NemoGuard richiede una GPU NVIDIA. NVIDIA afferma che il modello di sicurezza dei contenuti richiede 48 GB di memoria GPU, su una GPU o su due.

Il build non ha bisogno di nessuna di queste cose: compila in manifest Kubernetes senza che sia presente alcuna chiave, e non contatta né NVIDIA né il cluster.

Che cosa costruisce

Un agente richiede il proprio modello tramite un AI gateway. Il gateway fa passare prima ogni richiesta di modello attraverso una guardia, e la guardia controlla l’ultimo messaggio dell’utente in tre modi prima di inoltrare al modello ciò che ammette: con un classificatore di prompt injection, con il modello di sicurezza dei contenuti di NVIDIA e con il classificatore di jailbreak di NVIDIA. Questo workspace compila quella disposizione in manifest Kubernetes.

Mostra che un prodotto commerciale con licenza viene predisposto nello stesso modo di uno open source: un Component del catalogo, una Recipe, un arco uses e un’associazione di credenziale, con la licenza indicata dove un lettore sceglie il componente. Non scrive alcuna entità di catalogo propria; l’Aggregate, il Manifest e la Release sono tutto ciò che chiunque scrive.

istanzaComponent del catalogoche cosa è qui
agentcore/ai-agent/langgraphl’agente, l’immagine applicativa propria della Release, che raggiunge il suo modello attraverso il gateway
checkpointercore/datastore/valkeydove l’agente conserva il suo stato di esecuzione
routercore/gateway/litellml’AI gateway: un alias, assistant, inviato al modello attraverso la guardia
guardcore/security/nemo-guardrailsil server di NVIDIA NeMo Guardrails nel percorso verso il modello
detectorcore/security/trustyai-huggingface-detectoril classificatore di prompt injection che il rail proprio della guardia interroga
safetycore/ai-model/nemoguard-content-safetyLlama 3.1 NemoGuard 8B ContentSafety di NVIDIA, servito dal suo NIM
jailbreakcore/security/nemoguard-jailbreak-detectNemoGuard JailbreakDetect di NVIDIA, servito dal suo NIM

Gli archi uses: il socket model dell’agente verso il gateway e il suo socket checkpointer_db verso lo store; il socket guard del gateway verso la guardia; e i socket detector, content_safety e jailbreak_detection della guardia verso i tre controlli. Le associazioni: shield, la Feature core/prompt-injection-shield che mette la guardia sul percorso del gateway; upstream_key, la credenziale che la guardia presenta all’API del modello; e ngc_api_key su ciascun componente NemoGuard.

Generare l’esempio

Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example nemo-guardrails-nemoguard-nims

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd nemo-guardrails-nemoguard-nims

Build

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

Una release ha bisogno di un lockfile prima di eseguire il build, e i lockfile sono generati anziché distribuiti, quindi un clone appena creato non ne ha nessuno. Risolvine prima uno, oppure lascia che sia il build a crearlo:

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

Questo workspace risolve le entità del catalogo dal registry predefinito nominato da .aggrega-config.yaml. La realizzazione dello scudo esegue un plugin che non è incluso né nel compilatore né nel catalogo, il passo di configurazione del gateway pipeline-step/litellm-gateway-config, che la risoluzione scarica dal registry nominato da default_registry, hub.aggrega.ai.

Il build stampa, con <workspace> al posto della cartella di questo esempio:

[… omitted: a line reporting on the gateway configuration step's plugin, 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: 18 files written to <workspace>/dist

La Release nomina ogni immagine che il catalogo non nomina. Quella dell’agente è la tua applicazione. Quelle della guardia e del rilevatore sono copie delle versioni che esegui, replicate in un registry che controlli. Le due immagini NemoGuard sono di NVIDIA, e hai diritto a scaricarle in base alla tua licenza; il catalogo non ne nomina nessuna, e release.yaml scrive ciascuna con il tag change-me. Il build convoglia qualunque stringa vi si trovi; sostituiscile prima della distribuzione.

Con un assistente AI

Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella Workspace non contiene ancora una cartella `nemo-guardrails-nemoguard-nims`, chiama una volta lo strumento `scaffold` con `example` impostato a `nemo-guardrails-nemoguard-nims` e senza `dir`: scrive l’esempio in una nuova cartella `nemo-guardrails-nemoguard-nims`. Poi chiama lo strumento `build` con `workspace_root` impostato a `nemo-guardrails-nemoguard-nims`, `release` impostato a `release.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `nemo-guardrails-nemoguard-nims/dist/`.

L’albero renderizzato

dist/helm/
├── agent-deployment.yaml
├── checkpointer-default-service.yaml
├── checkpointer-deployment.yaml
├── detector-default-service.yaml
├── detector-deployment.yaml
├── guard-default-service.yaml
├── guard-deployment.yaml
├── guard/
│ └── nemo-guardrails-config.configmap.yaml
├── jailbreak-default-service.yaml
├── jailbreak-headless-service.yaml
├── jailbreak-statefulset.yaml
├── router-default-service.yaml
├── router-deployment.yaml
├── router/
│ ├── litellm-gateway-config/
│ │ └── configmap.yaml
│ └── request-guard/
│ └── request-guard.yaml
├── safety-default-service.yaml
├── safety-headless-service.yaml
└── safety-statefulset.yaml

Tra questi non c’è alcun Secret. Ogni credenziale è associata come core/referenced-secret, e il Manifest la lega a helm/k8s-existing-secret, che punta un carico di lavoro a un Secret già esistente nel namespace e non renderizza nulla di proprio.

La chiave, come riferimento

L’Aggregate scrive soltanto dove si trova la chiave all’interno di un Secret, la chiave di dati NGC_API_KEY; la Release nomina il Secret, ngc-api-key, e il Secret con cui vengono scaricate le immagini, ngc-registry. In dist/helm/safety-statefulset.yaml, e allo stesso modo in quello del classificatore di jailbreak:

env:
- name: NGC_API_KEY
valueFrom:
secretKeyRef:
name: ngc-api-key
key: NGC_API_KEY
imagePullSecrets:
- name: ngc-registry

Prima della distribuzione, crea entrambi i Secret nel namespace di destinazione: ngc-api-key, che contiene la chiave sotto NGC_API_KEY, e ngc-registry, un Secret di image pull per nvcr.io che effettua l’accesso con la chiave. La credenziale upstream della guardia è nominata allo stesso modo, come il Secret upstream-provider-key che contiene la chiave dell’API del modello sotto upstream-key.

Una Release non può scrivere la chiave al suo posto. Un blocco values: su un’associazione nella Release viene rifiutato quando il documento viene caricato, perché ciò che una Release scrive lì appartiene all’operatore, e i valori appartengono allo sviluppatore. Sostituisci il blocco infra: della ngc_api_key del componente safety con values: che contiene un origin, e il build stampa, prima di ogni altra cosa:

[OPS_ERROR E0215] release.yaml
document envelope validation failed (Release, at release.yaml); 66:11: spec.components.safety.features.ngc_api_key.values: against /$defs/boundary_component: unexpected property: "values". correct the document to match its kind's schema

L’unica stringa che la Release scrive davvero, il nome di un Secret, viene pubblicata esattamente come è scritta: il build non sa distinguere un nome da una chiave, quindi una chiave digitata dove va un nome comparirebbe nel manifest come quel nome. Il grafo che aggrega build --ir-graph stampa la omette in ogni caso, perché origin è dichiarato sensibile.

Che cosa fa la guardia

La configurazione della guardia, la chiave config.yaml di dist/helm/guard/nemo-guardrails-config.configmap.yaml, fino ai suoi prompt:

models:
- type: main
engine: openai
model: named-by-each-request
api_key_env_var: UPSTREAM_API_KEY
- type: content_safety
engine: openai
model: "llama-3.1-nemoguard-8b-content-safety"
parameters:
base_url: "http://safety-default:8000/v1"
api_key: EMPTY
passthrough: true
rails:
config:
hf_classifier:
prompt_injection:
engine: fms
model: "protectai/deberta-v3-base-prompt-injection-v2"
base_url: "http://detector-default:8000"
threshold: 0.5
blocked_labels: ["INJECTION"]
jailbreak_detection:
nim_base_url: "http://jailbreak-default:8000/v1/"
nim_server_endpoint: classify
input:
flows:
- hf classifier check input $classifier=prompt_injection
- jailbreak detection model
- content safety check input $model=content_safety

Per ogni richiesta di chat la guardia esegue i tre rail di input sull’ultimo messaggio dell’utente, in quest’ordine, e rifiuta la richiesta quando uno qualsiasi di essi la rifiuta:

  • Il classificatore di prompt injection rifiuta quando il rilevatore riporta INJECTION a 0.5 o oltre.
  • Il classificatore di jailbreak rifiuta quando il classificatore di NVIDIA risponde che il messaggio è un tentativo di jailbreak. La guardia invia il messaggio alla sua route classify; non è configurata alcuna chiave, perché il servizio interno al cluster non ne richiede.
  • Il modello di sicurezza dei contenuti rifiuta quando valuta il messaggio come non sicuro. La guardia lo dichiara come un modello raggiunto tramite l’API compatibile con OpenAI che il NIM serve, all’endpoint e con il nome di modello che l’arco safety pubblica, e il suo prompt — il resto di config.yaml — è quello che la documentazione di NeMo Guardrails di NVIDIA fornisce per questo modello, con l’elenco delle sue categorie di danno, letto con il parser che NeMo Guardrails fornisce per il suo verdetto.

A una richiesta rifiutata risponde la guardia stessa, con I’m sorry, I can’t respond to that. (Mi dispiace, non posso rispondere a questo.), e nulla di essa raggiunge il modello. La configurazione della guardia contiene anche un flow, rails.co, che esegue i rail di input qualunque cosa chieda il corpo di una richiesta.

values.model su safety è il nome a cui risponde il NIM di sicurezza dei contenuti, che il NIM prende dal proprio manifest del modello; il suo elenco dei modelli, /v1/models, lo mostra sul server in esecuzione. La guardia lo invia con ogni controllo, quindi i due devono concordare.

Che cosa non fa

  • Giudica solo l’ultimo messaggio dell’utente. Un tentativo collocato in un messaggio di sistema, in un turno precedente o nel risultato di uno strumento raggiunge il modello senza essere controllato, e non vengono giudicati né la risposta del modello, né gli argomenti delle chiamate agli strumenti, né le immagini.
  • Ogni verdetto è quello di un modello. I tre controlli non rilevano alcune richieste dannose o manipolatorie e rifiutano alcune richieste ordinarie.
  • Il rail di jailbreak fallisce in modo aperto. NVIDIA documenta che, quando il classificatore di jailbreak non è raggiungibile, va in timeout o risponde con un errore, il rail lascia passare la richiesta e non segnala nulla al chiamante. Gli altri due controlli vengono comunque eseguiti. Il rail di prompt injection rifiuta la richiesta quando il suo rilevatore non è raggiungibile.
  • Copre solo il traffico che attraversa il gateway. Un carico di lavoro che chiama direttamente l’indirizzo del modello lo aggira. La guardia e i tre controlli non autenticano alcun chiamante, quindi i loro Service sono indirizzi per i componenti che li chiamano, non indirizzi da pubblicare.
  • Qui non è dimostrato in esecuzione. La configurazione è quella descritta dalla documentazione di NVIDIA, compilata in anticipo; nulla in questo workspace ha eseguito i container NemoGuard.

Che cosa arresta il build

La Recipe della guardia controlla ciò che contengono i suoi socket NemoGuard. Rendi safety un semplice core/ai-model/nvidia-nim — il suo tipo nell’Aggregate e la sua riga nel Manifest — e il build si arresta, senza scrivere nulla:

[… omitted: a line reporting on the gateway configuration step's plugin, what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars]
[CATALOG_ERROR E0364] instance guard
rendering node "guard"
caused by: [CATALOG_ERROR] nemo-guardrails-config.configmap.yaml
artifact "nemo-guardrails-config.configmap.yaml" template eval
caused by: [CATALOG_ERROR] artifacts[nemo-guardrails/nemo-guardrails-config.configmap.yaml]
template "artifacts[nemo-guardrails/nemo-guardrails-config.configmap.yaml]" execute
caused by (2):
a value template failed while it ran
---
[… omitted: the template position and the template's own source]: error calling fail: the guard's content_safety socket is wired to "safety", a core/ai-model/nvidia-nim, but the content-safety rail's prompt and verdict parser are NVIDIA's for core/ai-model/nemoguard-content-safety, which another model answers in a shape the parser does not read; wire a core/ai-model/nemoguard-content-safety to content_safety

Il socket jailbreak_detection accetta un core/security/nemoguard-jailbreak-detect e nient’altro, allo stesso modo, e ogni socket accetta un solo target. Gli arresti propri dello scudo sono quelli di ai-gateway-prompt-injection-shield, che compila lo stesso gateway e la stessa guardia senza i controlli NemoGuard.

Dove il compilatore non interpreta

Il compilatore convoglia i nomi dei Service e le porte dei NIM nella configurazione della guardia, e i nomi dei Secret nei pod, come stringhe. Non effettua il pull di alcuna immagine, non scarica alcun modello né legge alcuna chiave, e non contatta né NVIDIA, né la guardia, né il modello. Ogni arresto descritto sopra è dichiarato dalle entità stesse del catalogo.

Adattarlo

  • Senza il modello di sicurezza dei contenuti. Rimuovi il componente safety e l’arco content_safety della guardia; la configurazione della guardia allora non contiene alcun modello, rail o prompt del genere. Il classificatore di jailbreak si rimuove allo stesso modo.
  • Un modello che esegui tu stesso. Punta l’upstream_endpoint della guardia verso l’endpoint del server del modello — core/ai-model/vllm ne pubblica uno — e scrivi il target dell’alias come openai/<the name that server serves>.
  • GPU più grandi, o due. Ogni componente NemoGuard accetta infra.gpu.count, e infra.gpu.runtime_class dove il cluster seleziona il proprio runtime GPU per classe.