NeMo Guardrails vérifiant les requêtes d’un agent avec les modèles NemoGuard de NVIDIA
Les requêtes de modèle d’un agent passent par NVIDIA NeMo Guardrails, qui vérifie chacune d’elles avec deux des modèles NemoGuard de NVIDIA, des produits NVIDIA sous licence qui nécessitent pour s’exécuter une licence de NVIDIA, une clé d’API NGC et un nœud GPU.
Ce qu’il requiert
Les deux modèles NemoGuard sont des produits NVIDIA que vous exécutez selon les conditions de NVIDIA. Déployer ce que ce workspace construit nécessite :
- Une licence de NVIDIA. La documentation de NVIDIA de chaque microservice NemoGuard indique comme prérequis « an active subscription to an NVIDIA AI Enterprise product or be an NVIDIA Developer Program member » (un abonnement actif à un produit NVIDIA AI Enterprise ou être membre du NVIDIA Developer Program), et précise que l’accès aux conteneurs et aux modèles est restreint.
- Une clé d’API NGC, référencée par la Release comme secret. Les conteneurs NemoGuard sont récupérés depuis le registre de NVIDIA,
nvcr.io, et chacun récupère son modèle auprès de NVIDIA avec la clé au démarrage. La Release nomme deux Secrets Kubernetes qui la contiennent — l’un depuis lequel les pods lisent la clé, l’autre avec lequel le cluster récupère les images — et aucun fichier de ce workspace, ni rien de ce qu’écrit le build, ne contient la clé elle-même. - Un nœud GPU. Chaque conteneur NemoGuard demande un GPU NVIDIA. NVIDIA indique que le modèle de sécurité du contenu nécessite 48 Go de mémoire GPU, sur un GPU ou sur deux.
Le build n’a besoin d’aucun de ces éléments : il compile en manifestes Kubernetes sans qu’aucune clé soit présente, et ne contacte ni NVIDIA ni le cluster.
Ce qu’il construit
Un agent demande son modèle via une passerelle d’IA. La passerelle fait d’abord passer chaque requête de modèle par un garde, et le garde vérifie le dernier message de l’utilisateur de trois façons avant de transmettre au modèle ce qu’il admet : avec un classifieur d’injection de prompt, avec le modèle de sécurité du contenu de NVIDIA et avec le classifieur de jailbreak de NVIDIA. Ce workspace compile cet agencement en manifestes Kubernetes.
Il montre qu’un produit commercial sous licence est provisionné comme l’est un produit open source : un Component du catalogue, une Recipe, une arête uses et un rattachement d’information d’identification, avec la licence indiquée là où un lecteur choisit le composant. Il ne rédige aucune entité de catalogue qui lui soit propre ; l’Aggregate, le Manifest et la Release sont tout ce que quiconque écrit.
| instance | Component du catalogue | ce qu’il est ici |
|---|---|---|
agent | core/ai-agent/langgraph | l’agent, l’image d’application propre à la Release, qui atteint son modèle via la passerelle |
checkpointer | core/datastore/valkey | là où l’agent conserve son état d’exécution |
router | core/gateway/litellm | la passerelle d’IA : un alias, assistant, envoyé au modèle via le garde |
guard | core/security/nemo-guardrails | le serveur de NVIDIA NeMo Guardrails sur le chemin du modèle |
detector | core/security/trustyai-huggingface-detector | le classifieur d’injection de prompt qu’interroge le rail propre au garde |
safety | core/ai-model/nemoguard-content-safety | Llama 3.1 NemoGuard 8B ContentSafety de NVIDIA, servi par son NIM |
jailbreak | core/security/nemoguard-jailbreak-detect | NemoGuard JailbreakDetect de NVIDIA, servi par son NIM |
Les arêtes uses : le socket model de l’agent vers la passerelle et son socket checkpointer_db vers le magasin ; le socket guard de la passerelle vers le garde ; et les sockets detector, content_safety et jailbreak_detection du garde vers les trois vérifications. Les rattachements : shield, la Feature core/prompt-injection-shield qui place le garde sur le chemin de la passerelle ; upstream_key, les informations d’identification que le garde présente à l’API du modèle ; et ngc_api_key sur chaque composant NemoGuard.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example nemo-guardrails-nemoguard-nimsElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd nemo-guardrails-nemoguard-nimsBuild
aggrega build --release release.yaml --auto-pullUne release a besoin d’un lockfile avant son build, et les lockfiles sont générés plutôt que livrés, de sorte qu’un clone neuf n’en contient aucun. Résolvez-en un d’abord, ou laissez le build le remplir :
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildCe workspace résout les entités du catalogue depuis le registre par défaut que nomme .aggrega-config.yaml. La réalisation du bouclier exécute un plugin qui n’est livré ni avec le compilateur ni avec le catalogue, l’étape de configuration de la passerelle pipeline-step/litellm-gateway-config, que la résolution récupère depuis le registre que nomme default_registry, hub.aggrega.ai.
Le build affiche, <workspace> désignant le dossier de cet exemple :
[… 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 nomme chaque image que le catalogue ne nomme pas. Celle de l’agent est votre propre application. Celles du garde et du détecteur sont des copies des versions que vous exécutez, mises en miroir dans un registre que vous contrôlez. Les deux images NemoGuard sont celles de NVIDIA, que vous avez le droit de récupérer en vertu de votre licence ; le catalogue n’en nomme aucune, et release.yaml écrit chacune avec le tag change-me. Le build achemine la chaîne qui s’y trouve, quelle qu’elle soit ; remplacez-les avant de déployer.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier Workspace ne contient pas encore de dossier `nemo-guardrails-nemoguard-nims`, appelez une fois l’outil `scaffold` avec `example` défini sur `nemo-guardrails-nemoguard-nims` et sans `dir` : il écrit l’exemple dans un nouveau dossier `nemo-guardrails-nemoguard-nims`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `nemo-guardrails-nemoguard-nims`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `nemo-guardrails-nemoguard-nims/dist/`.L’arborescence rendue
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.yamlIl n’y a aucun Secret parmi eux. Chaque information d’identification est rattachée comme core/referenced-secret, et le Manifest la lie à helm/k8s-existing-secret, qui fait pointer une charge de travail vers un Secret qui existe déjà dans l’espace de noms et ne rend rien de propre.
La clé, comme référence
L’Aggregate n’écrit que l’endroit où se trouve la clé à l’intérieur d’un Secret, la clé de données NGC_API_KEY ; la Release nomme le Secret, ngc-api-key, et le Secret avec lequel les images sont récupérées, ngc-registry. Dans dist/helm/safety-statefulset.yaml, et de même dans celui du classifieur de jailbreak :
env: - name: NGC_API_KEY valueFrom: secretKeyRef: name: ngc-api-key key: NGC_API_KEY imagePullSecrets: - name: ngc-registryAvant de déployer, créez les deux Secrets dans l’espace de noms cible : ngc-api-key, qui contient la clé sous NGC_API_KEY, et ngc-registry, un Secret de récupération d’images pour nvcr.io qui se connecte avec la clé. Les informations d’identification amont du garde sont nommées de la même façon, sous la forme du Secret upstream-provider-key qui contient la clé de l’API du modèle sous upstream-key.
Une Release ne peut pas écrire la clé à sa place. Un bloc values: sur un rattachement dans la Release est refusé au chargement du document, parce que ce qu’une Release écrit à cet endroit relève de l’opérateur, et que les valeurs relèvent du développeur. Remplacez le bloc infra: de la ngc_api_key du composant safety par values: contenant un origin, et le build affiche, avant toute autre chose :
[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 schemaLa seule chaîne que la Release écrit bel et bien, le nom d’un Secret, est publiée exactement telle qu’elle est écrite : le build ne sait pas distinguer un nom d’une clé, si bien qu’une clé saisie là où va un nom apparaîtrait dans le manifeste sous ce nom. Le graphe qu’affiche aggrega build --ir-graph la masque dans tous les cas, parce que origin est déclaré sensible.
Ce que fait le garde
La configuration du garde, la clé config.yaml de dist/helm/guard/nemo-guardrails-config.configmap.yaml, jusqu’à ses prompts :
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_safetyPour chaque requête de chat, le garde exécute les trois rails d’entrée sur le dernier message de l’utilisateur, dans cet ordre, et refuse la requête lorsque l’un d’eux la refuse :
- Le classifieur d’injection de prompt refuse lorsque le détecteur signale
INJECTIONà0.5ou au-dessus. - Le classifieur de jailbreak refuse lorsque le classifieur de NVIDIA répond que le message est une tentative de jailbreak. Le garde envoie le message à sa route
classify; aucune clé n’est configurée, parce que le service interne au cluster n’en demande aucune. - Le modèle de sécurité du contenu refuse lorsqu’il juge le message dangereux. Le garde le déclare comme un modèle atteint via l’API compatible OpenAI que sert le NIM, à l’endpoint et sous le nom de modèle que publie l’arête
safety, et son prompt — le reste deconfig.yaml— est celui que la documentation de NeMo Guardrails de NVIDIA donne pour ce modèle, qui liste ses catégories de préjudice, lu avec l’analyseur que NeMo Guardrails fournit pour son verdict.
À une requête refusée, le garde répond lui-même, par I’m sorry, I can’t respond to that. (Je suis désolé, je ne peux pas répondre à cela.), et rien d’elle n’atteint le modèle. La configuration du garde contient aussi un flow, rails.co, qui exécute les rails d’entrée quoi que demande un corps de requête.
values.model sur safety est le nom auquel répond le NIM de sécurité du contenu, que le NIM tire de son propre manifeste de modèle ; sa liste de modèles, /v1/models, l’affiche sur le serveur en cours d’exécution. Le garde l’envoie avec chaque vérification, si bien que les deux doivent concorder.
Ce qu’elle ne fait pas
- Seul le dernier message de l’utilisateur est jugé. Une tentative placée dans un message système, un tour précédent ou un résultat d’outil atteint le modèle sans être vérifiée, et ni la réponse du modèle, ni les arguments des appels d’outils, ni les images ne sont jugés.
- Chaque verdict est celui d’un modèle. Les trois vérifications manquent certaines requêtes nuisibles ou manipulatrices et en refusent certaines qui sont ordinaires.
- Le rail de jailbreak échoue en mode ouvert. NVIDIA documente que, lorsque le classifieur de jailbreak est injoignable, expire ou répond par une erreur, le rail laisse passer la requête et ne signale rien à l’appelant. Les deux autres vérifications s’exécutent quand même. Le rail d’injection de prompt refuse la requête lorsque son détecteur est injoignable.
- Seul le trafic qui traverse la passerelle est couvert. Une charge de travail qui appelle directement l’adresse du modèle la contourne. Le garde et les trois vérifications n’authentifient aucun appelant, si bien que leurs Services sont des adresses pour les composants qui les appellent, et non des adresses à publier.
- Son fonctionnement n’est pas prouvé ici. La configuration est celle que décrit la documentation de NVIDIA, compilée à l’avance ; rien dans ce workspace n’a exécuté les conteneurs NemoGuard.
Ce qui arrête le build
La Recipe du garde vérifie ce que contiennent ses sockets NemoGuard. Faites de safety un simple core/ai-model/nvidia-nim — son type dans l’Aggregate et sa ligne dans le Manifest — et le build s’arrête, sans rien écrire :
[… 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_safetyLe socket jailbreak_detection accepte un core/security/nemoguard-jailbreak-detect et rien d’autre, de la même façon, et chaque socket accepte une seule cible. Les arrêts propres au bouclier sont ceux de ai-gateway-prompt-injection-shield, qui construit la même passerelle et le même garde sans les vérifications NemoGuard.
Là où le compilateur n’interprète pas
Le compilateur achemine les noms de Service et les ports des NIM vers la configuration du garde, et les noms des Secrets vers les pods, sous forme de chaînes. Il ne récupère aucune image, ne récupère aucun modèle ni ne lit aucune clé, et ne contacte ni NVIDIA, ni le garde, ni le modèle. Chaque arrêt ci-dessus est déclaré par les propres entités du catalogue.
L’adapter
- Sans le modèle de sécurité du contenu. Retirez le composant
safetyet l’arêtecontent_safetydu garde ; la configuration du garde ne contient alors aucun modèle, rail ou prompt de ce type. Le classifieur de jailbreak se retire de la même façon. - Un modèle que vous exécutez vous-même. Faites pointer l’
upstream_endpointdu garde vers l’endpoint du serveur de modèle —core/ai-model/vllmen publie un — et écrivez la cible de l’aliasopenai/<the name that server serves>. - Des GPU plus grands, ou deux. Chaque composant NemoGuard accepte
infra.gpu.count, etinfra.gpu.runtime_classlà où le cluster sélectionne son runtime GPU par classe.