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.
| istanza | Component del catalogo | che cosa è qui |
|---|---|---|
agent | core/ai-agent/langgraph | l’agente, l’immagine applicativa propria della Release, che raggiunge il suo modello attraverso il gateway |
checkpointer | core/datastore/valkey | dove l’agente conserva il suo stato di esecuzione |
router | core/gateway/litellm | l’AI gateway: un alias, assistant, inviato al modello attraverso la guardia |
guard | core/security/nemo-guardrails | il server di NVIDIA NeMo Guardrails nel percorso verso il modello |
detector | core/security/trustyai-huggingface-detector | il classificatore di prompt injection che il rail proprio della guardia interroga |
safety | core/ai-model/nemoguard-content-safety | Llama 3.1 NemoGuard 8B ContentSafety di NVIDIA, servito dal suo NIM |
jailbreak | core/security/nemoguard-jailbreak-detect | NemoGuard 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:
aggrega scaffold --example nemo-guardrails-nemoguard-nimsPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd nemo-guardrails-nemoguard-nimsBuild
aggrega build --release release.yaml --auto-pullUna 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:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildQuesto 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>/distLa 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.yamlTra 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-registryPrima 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 schemaL’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: EMPTYpassthrough: truerails: 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_safetyPer 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
INJECTIONa0.5o 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
safetypubblica, e il suo prompt — il resto diconfig.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_safetyIl 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
safetye l’arcocontent_safetydella 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_endpointdella guardia verso l’endpoint del server del modello —core/ai-model/vllmne pubblica uno — e scrivi il target dell’alias comeopenai/<the name that server serves>. - GPU più grandi, o due. Ogni componente NemoGuard accetta
infra.gpu.count, einfra.gpu.runtime_classdove il cluster seleziona il proprio runtime GPU per classe.