NeMo Guardrails comprobando las solicitudes de un agente con los modelos NemoGuard de NVIDIA
Las solicitudes de modelo de un agente pasan por NVIDIA NeMo Guardrails, que comprueba cada una con dos de los modelos NemoGuard de NVIDIA, productos de NVIDIA con licencia que necesitan para ejecutarse una licencia de NVIDIA, una clave de API de NGC y un nodo con GPU.
Qué requiere
Los dos modelos NemoGuard son productos de NVIDIA que ejecutas según los términos de NVIDIA. Desplegar lo que compila este workspace requiere:
- Una licencia de NVIDIA. La documentación de NVIDIA de cada microservicio NemoGuard indica como requisito previo «an active subscription to an NVIDIA AI Enterprise product or be an NVIDIA Developer Program member» (una suscripción activa a un producto NVIDIA AI Enterprise o ser miembro del NVIDIA Developer Program), y afirma que el acceso a los contenedores y a los modelos está restringido.
- Una clave de API de NGC, referenciada por la Release como secreto. Los contenedores NemoGuard se descargan del registro de NVIDIA,
nvcr.io, y cada uno obtiene su modelo de NVIDIA con la clave al arrancar. La Release nombra dos Secrets de Kubernetes que la contienen — uno del que los pods leen la clave y otro con el que el clúster descarga las imágenes — y ningún archivo de este workspace, ni nada que escriba la compilación, contiene la clave en sí. - Un nodo con GPU. Cada contenedor NemoGuard solicita una GPU de NVIDIA. NVIDIA indica que el modelo de seguridad del contenido necesita 48 GB de memoria de GPU, en una GPU o en dos.
La compilación no necesita nada de esto: compila a manifiestos de Kubernetes sin que haya ninguna clave presente, y no contacta ni con NVIDIA ni con el clúster.
Lo que construye
Un agente pide su modelo a través de un gateway de IA. El gateway envía primero cada solicitud de modelo a través de una guarda, y la guarda comprueba el último mensaje del usuario de tres maneras antes de reenviar al modelo lo que admite: con un clasificador de inyección de prompts, con el modelo de seguridad del contenido de NVIDIA y con el clasificador de jailbreak de NVIDIA. Este workspace compila esa disposición a manifiestos de Kubernetes.
Muestra que un producto comercial con licencia se aprovisiona del mismo modo que uno de código abierto: un Component del catálogo, una Recipe, una arista uses y una vinculación de credencial, con la licencia indicada donde un lector elige el componente. No define ninguna entidad de catálogo propia; el Aggregate, el Manifest y la Release son todo lo que cualquiera escribe.
| instancia | Component del catálogo | qué es aquí |
|---|---|---|
agent | core/ai-agent/langgraph | el agente, la imagen de aplicación propia de la Release, que llega a su modelo a través del gateway |
checkpointer | core/datastore/valkey | donde el agente guarda su estado de ejecución |
router | core/gateway/litellm | el gateway de IA: un alias, assistant, enviado al modelo a través de la guarda |
guard | core/security/nemo-guardrails | el servidor de NVIDIA NeMo Guardrails en el camino hacia el modelo |
detector | core/security/trustyai-huggingface-detector | el clasificador de inyección de prompts al que pregunta el rail propio de la guarda |
safety | core/ai-model/nemoguard-content-safety | Llama 3.1 NemoGuard 8B ContentSafety de NVIDIA, servido por su NIM |
jailbreak | core/security/nemoguard-jailbreak-detect | NemoGuard JailbreakDetect de NVIDIA, servido por su NIM |
Las aristas uses: el socket model del agente hacia el gateway y su socket checkpointer_db hacia el almacén; el socket guard del gateway hacia la guarda; y los sockets detector, content_safety y jailbreak_detection de la guarda hacia las tres comprobaciones. Las vinculaciones: shield, la Feature core/prompt-injection-shield que pone la guarda en el camino del gateway; upstream_key, la credencial que la guarda presenta a la API del modelo; y ngc_api_key en cada componente NemoGuard.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example nemo-guardrails-nemoguard-nimsDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd nemo-guardrails-nemoguard-nimsCompilación
aggrega build --release release.yaml --auto-pullUna release necesita un lockfile antes de compilarse, y los lockfiles se generan en lugar de distribuirse, así que un clon recién hecho no tiene ninguno. Resuelve uno primero, o deja que la compilación lo rellene:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste workspace resuelve las entidades del catálogo desde el registro predeterminado que nombra .aggrega-config.yaml. La realización del escudo ejecuta un plugin que no se incluye ni en el compilador ni en el catálogo, el paso de configuración del gateway pipeline-step/litellm-gateway-config, que la resolución obtiene del registro que nombra default_registry, hub.aggrega.ai.
La compilación imprime, con <workspace> en lugar de la carpeta de este ejemplo:
[… 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 nombra cada imagen que el catálogo no nombra. La del agente es tu propia aplicación. Las de la guarda y del detector son copias de las versiones que ejecutas, replicadas en un registro que controlas. Las dos imágenes NemoGuard son de NVIDIA, que tienes derecho a descargar según tu licencia; el catálogo no nombra ninguna de ellas, y release.yaml escribe cada una con el tag change-me. La compilación canaliza la cadena que haya ahí, sea cual sea; sustitúyelas antes de desplegar.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta Workspace aún no contiene una carpeta `nemo-guardrails-nemoguard-nims`, llama una vez a la herramienta `scaffold` con `example` establecido en `nemo-guardrails-nemoguard-nims` y sin `dir`: escribe el ejemplo en una nueva carpeta `nemo-guardrails-nemoguard-nims`. Luego llama a la herramienta `build` con `workspace_root` establecido en `nemo-guardrails-nemoguard-nims`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `nemo-guardrails-nemoguard-nims/dist/`.El árbol renderizado
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.yamlEntre ellos no hay ningún Secret. Cada credencial se vincula como core/referenced-secret, y el Manifest la enlaza con helm/k8s-existing-secret, que hace apuntar una carga de trabajo a un Secret que ya existe en el espacio de nombres y no renderiza nada propio.
La clave, como referencia
El Aggregate escribe solo dónde está la clave dentro de un Secret, la clave de datos NGC_API_KEY; la Release nombra el Secret, ngc-api-key, y el Secret con el que se descargan las imágenes, ngc-registry. En dist/helm/safety-statefulset.yaml, y del mismo modo en el del clasificador de jailbreak:
env: - name: NGC_API_KEY valueFrom: secretKeyRef: name: ngc-api-key key: NGC_API_KEY imagePullSecrets: - name: ngc-registryAntes de desplegar, crea ambos Secrets en el espacio de nombres de destino: ngc-api-key, que contiene la clave bajo NGC_API_KEY, y ngc-registry, un Secret de descarga de imágenes para nvcr.io que inicia sesión con la clave. La credencial upstream de la guarda se nombra del mismo modo, como el Secret upstream-provider-key que contiene la clave de la API del modelo bajo upstream-key.
Una Release no puede escribir la clave en su lugar. Un bloque values: en una vinculación de la Release se rechaza cuando se carga el documento, porque lo que una Release escribe ahí es del operador, y los valores son del desarrollador. Sustituye el bloque infra: de la ngc_api_key del componente safety por values: con un origin, y la compilación imprime, antes que nada:
[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 única cadena que la Release sí escribe, el nombre de un Secret, se publica exactamente como está escrita: la compilación no distingue un nombre de una clave, así que una clave escrita donde va un nombre aparecería en el manifiesto como ese nombre. El grafo que imprime aggrega build --ir-graph la oculta en cualquier caso, porque origin está declarado como sensible.
Qué hace la guarda
La configuración de la guarda, la clave config.yaml de dist/helm/guard/nemo-guardrails-config.configmap.yaml, hasta sus 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_safetyPara cada solicitud de chat, la guarda ejecuta los tres rails de entrada sobre el último mensaje del usuario, en ese orden, y rechaza la solicitud cuando cualquiera de ellos la rechaza:
- El clasificador de inyección de prompts rechaza cuando el detector informa
INJECTIONen0.5o por encima. - El clasificador de jailbreak rechaza cuando el clasificador de NVIDIA responde que el mensaje es un intento de jailbreak. La guarda envía el mensaje a su ruta
classify; no se configura ninguna clave, porque el servicio interno del clúster no pide ninguna. - El modelo de seguridad del contenido rechaza cuando califica el mensaje como inseguro. La guarda lo declara como un modelo al que se llega a través de la API compatible con OpenAI que sirve el NIM, en el endpoint y con el nombre de modelo que publica la arista
safety, y su prompt — el resto deconfig.yaml— es el que da la documentación de NeMo Guardrails de NVIDIA para este modelo, que enumera sus categorías de daño, leído con el analizador que NeMo Guardrails proporciona para su veredicto.
A una solicitud rechazada responde la propia guarda, con I’m sorry, I can’t respond to that. (Lo siento, no puedo responder a eso.), y nada de ella llega al modelo. La configuración de la guarda también lleva un flow, rails.co, que ejecuta los rails de entrada pida lo que pida el cuerpo de una solicitud.
values.model en safety es el nombre al que responde el NIM de seguridad del contenido, que el NIM toma de su propio manifiesto de modelo; su listado de modelos, /v1/models, lo muestra en el servidor en ejecución. La guarda lo envía con cada comprobación, así que ambos tienen que coincidir.
Lo que no hace
- Solo juzga el último mensaje del usuario. Un intento colocado en un mensaje de sistema, un turno anterior o el resultado de una herramienta llega al modelo sin comprobar, y no se juzgan ni la respuesta del modelo, ni los argumentos de las llamadas a herramientas, ni las imágenes.
- Cada veredicto es el de un modelo. Las tres comprobaciones dejan escapar algunas solicitudes dañinas o manipuladoras y rechazan algunas ordinarias.
- El rail de jailbreak falla en abierto. NVIDIA documenta que, cuando no se puede alcanzar el clasificador de jailbreak, agota el tiempo de espera o responde con un error, el rail deja pasar la solicitud y no informa de nada al llamador. Las otras dos comprobaciones se ejecutan igualmente. El rail de inyección de prompts rechaza la solicitud cuando no se puede alcanzar su detector.
- Solo cubre el tráfico que atraviesa el gateway. Una carga de trabajo que llama directamente a la dirección del modelo lo rodea. La guarda y las tres comprobaciones no autentican a ningún llamador, así que sus Services son direcciones para los componentes que los llaman, no direcciones para publicar.
- No se ha comprobado aquí en ejecución. La configuración es la que describe la documentación de NVIDIA, compilada de antemano; nada en este workspace ha ejecutado los contenedores NemoGuard.
Qué detiene la compilación
La Recipe de la guarda comprueba lo que contienen sus sockets NemoGuard. Convierte safety en un simple core/ai-model/nvidia-nim — su tipo en el Aggregate y su línea en el Manifest — y la compilación se detiene, sin escribir nada:
[… 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_safetyEl socket jailbreak_detection acepta un core/security/nemoguard-jailbreak-detect y nada más, del mismo modo, y cada socket acepta un único destino. Las detenciones propias del escudo son las de ai-gateway-prompt-injection-shield, que compila el mismo gateway y la misma guarda sin las comprobaciones NemoGuard.
Dónde el compilador no interpreta
El compilador canaliza los nombres de Service y los puertos de los NIM hacia la configuración de la guarda, y los nombres de los Secrets hacia los pods, como cadenas. No descarga ninguna imagen, no obtiene ningún modelo ni lee ninguna clave, y no contacta ni con NVIDIA, ni con la guarda, ni con el modelo. Cada detención de arriba la declaran las propias entidades del catálogo.
Adaptarlo
- Sin el modelo de seguridad del contenido. Quita el componente
safetyy la aristacontent_safetyde la guarda; la configuración de la guarda deja entonces de llevar ese modelo, rail o prompt. El clasificador de jailbreak se quita del mismo modo. - Un modelo que ejecutas tú mismo. Apunta el
upstream_endpointde la guarda al endpoint del servidor del modelo —core/ai-model/vllmpublica uno — y escribe el destino del alias comoopenai/<the name that server serves>. - GPU más grandes, o dos. Cada componente NemoGuard acepta
infra.gpu.count, einfra.gpu.runtime_classdonde el clúster selecciona su runtime de GPU por clase.