NeMo Guardrails verificando as requisições de um agente com os modelos NemoGuard da NVIDIA
As requisições de modelo de um agente passam pelo NVIDIA NeMo Guardrails, que verifica cada uma delas com dois dos modelos NemoGuard da NVIDIA, produtos licenciados da NVIDIA que precisam de uma licença da NVIDIA, de uma chave de API do NGC e de um nó com GPU para rodar.
O que ele requer
Os dois modelos NemoGuard são produtos da NVIDIA que você executa sob os termos da NVIDIA. Implantar o que este workspace compila requer:
- Uma licença da NVIDIA. A documentação da NVIDIA para cada microsserviço NemoGuard indica como pré-requisito “an active subscription to an NVIDIA AI Enterprise product or be an NVIDIA Developer Program member” (uma assinatura ativa de um produto NVIDIA AI Enterprise ou ser membro do NVIDIA Developer Program), e afirma que o acesso aos contêineres e aos modelos é restrito.
- Uma chave de API do NGC, referenciada pela Release como segredo. Os contêineres NemoGuard são baixados do registro da NVIDIA,
nvcr.io, e cada um baixa o seu modelo da NVIDIA com a chave ao iniciar. A Release nomeia dois Secrets do Kubernetes que a contêm — um do qual os pods leem a chave, outro com o qual o cluster baixa as imagens — e nenhum arquivo neste workspace, nem nada que o build escreve, contém a própria chave. - Um nó com GPU. Cada contêiner NemoGuard solicita uma GPU da NVIDIA. A NVIDIA afirma que o modelo de segurança de conteúdo precisa de 48 GB de memória de GPU, em uma GPU ou em duas.
O build não precisa de nada disso: ele compila para manifestos do Kubernetes sem nenhuma chave presente, e não contata nem a NVIDIA nem o cluster.
O que ele constrói
Um agente pede o seu modelo por meio de um gateway de IA. O gateway envia cada requisição de modelo primeiro por uma guarda, e a guarda verifica a última mensagem do usuário de três maneiras antes de encaminhar ao modelo o que admite: com um classificador de injeção de prompt, com o modelo de segurança de conteúdo da NVIDIA e com o classificador de jailbreak da NVIDIA. Este workspace compila esse arranjo para manifestos do Kubernetes.
Ele mostra que um produto comercial licenciado é provisionado da mesma forma que um de código aberto: um Component do catálogo, uma Recipe, uma aresta uses e uma vinculação de credencial, com a licença indicada onde um leitor escolhe o componente. Ele não define nenhuma entidade de catálogo própria; o Aggregate, o Manifest e a Release são tudo o que qualquer pessoa escreve.
| instância | Component do catálogo | o que é aqui |
|---|---|---|
agent | core/ai-agent/langgraph | o agente, a imagem de aplicação própria da Release, que alcança o seu modelo pelo gateway |
checkpointer | core/datastore/valkey | onde o agente guarda o seu estado de execução |
router | core/gateway/litellm | o gateway de IA: um alias, assistant, enviado ao modelo pela guarda |
guard | core/security/nemo-guardrails | o servidor do NVIDIA NeMo Guardrails no caminho do modelo |
detector | core/security/trustyai-huggingface-detector | o classificador de injeção de prompt que o rail próprio da guarda consulta |
safety | core/ai-model/nemoguard-content-safety | Llama 3.1 NemoGuard 8B ContentSafety da NVIDIA, servido pelo seu NIM |
jailbreak | core/security/nemoguard-jailbreak-detect | NemoGuard JailbreakDetect da NVIDIA, servido pelo seu NIM |
As arestas uses: o socket model do agente para o gateway e o seu socket checkpointer_db para o repositório; o socket guard do gateway para a guarda; e os sockets detector, content_safety e jailbreak_detection da guarda para as três verificações. As vinculações: shield, a Feature core/prompt-injection-shield que coloca a guarda no caminho do gateway; upstream_key, a credencial que a guarda apresenta à API do modelo; e ngc_api_key em cada componente NemoGuard.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example nemo-guardrails-nemoguard-nimsEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd nemo-guardrails-nemoguard-nimsBuild
aggrega build --release release.yaml --auto-pullUma release precisa de um lockfile antes de fazer o build, e os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum. Resolva um primeiro, ou deixe o build preenchê-lo:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste workspace resolve as entidades do catálogo a partir do registro padrão que .aggrega-config.yaml nomeia. A realização do escudo executa um plugin que não vem nem no compilador nem no catálogo, a etapa de configuração do gateway pipeline-step/litellm-gateway-config, que a resolução obtém do registro que default_registry nomeia, hub.aggrega.ai.
O build imprime, com <workspace> representando a pasta deste exemplo:
[… 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>/distA Release nomeia cada imagem que o catálogo não nomeia. A do agente é a sua própria aplicação. As da guarda e do detector são cópias das versões que você executa, espelhadas em um registro que você controla. As duas imagens NemoGuard são da NVIDIA, e você tem direito a baixá-las sob a sua licença; o catálogo não nomeia nenhuma delas, e release.yaml escreve cada uma com a tag change-me. O build canaliza qualquer string que esteja ali; substitua-as antes de implantar.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta Workspace ainda não contiver uma pasta `nemo-guardrails-nemoguard-nims`, chame uma vez a ferramenta `scaffold` com `example` definido como `nemo-guardrails-nemoguard-nims` e sem `dir`: ela grava o exemplo em uma nova pasta `nemo-guardrails-nemoguard-nims`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `nemo-guardrails-nemoguard-nims`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `nemo-guardrails-nemoguard-nims/dist/`.A árvore renderizada
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.yamlNão há nenhum Secret entre eles. Cada credencial é vinculada como core/referenced-secret, e o Manifest a associa a helm/k8s-existing-secret, que aponta uma carga de trabalho para um Secret que já existe no namespace e não renderiza nada próprio.
A chave, como referência
O Aggregate escreve apenas onde a chave fica dentro de um Secret, a chave de dados NGC_API_KEY; a Release nomeia o Secret, ngc-api-key, e o Secret com que as imagens são baixadas, ngc-registry. Em dist/helm/safety-statefulset.yaml, e da mesma forma no do classificador de jailbreak:
env: - name: NGC_API_KEY valueFrom: secretKeyRef: name: ngc-api-key key: NGC_API_KEY imagePullSecrets: - name: ngc-registryAntes de implantar, crie os dois Secrets no namespace de destino: ngc-api-key, que contém a chave sob NGC_API_KEY, e ngc-registry, um Secret de pull de imagens para nvcr.io que faz login com a chave. A credencial upstream da guarda é nomeada da mesma forma, como o Secret upstream-provider-key que contém a chave da API do modelo sob upstream-key.
Uma Release não pode escrever a chave no seu lugar. Um bloco values: em uma vinculação na Release é recusado quando o documento é carregado, porque o que uma Release escreve ali é do operador, e os valores são do desenvolvedor. Substitua o bloco infra: da ngc_api_key do componente safety por values: contendo um origin, e o build imprime, antes de qualquer outra coisa:
[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 schemaA única string que a Release de fato escreve, o nome de um Secret, é publicada exatamente como escrita: o build não consegue distinguir um nome de uma chave, então uma chave digitada onde vai um nome apareceria no manifesto como esse nome. O grafo que aggrega build --ir-graph imprime a omite em qualquer caso, porque origin é declarado sensível.
O que a guarda faz
A configuração da guarda, a chave config.yaml de dist/helm/guard/nemo-guardrails-config.configmap.yaml, até os seus 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 requisição de chat, a guarda executa os três rails de entrada sobre a última mensagem do usuário, nessa ordem, e recusa a requisição quando qualquer um deles a recusa:
- O classificador de injeção de prompt recusa quando o detector relata
INJECTIONem0.5ou acima. - O classificador de jailbreak recusa quando o classificador da NVIDIA responde que a mensagem é uma tentativa de jailbreak. A guarda envia a mensagem à sua rota
classify; nenhuma chave é configurada, porque o serviço interno ao cluster não pede nenhuma. - O modelo de segurança de conteúdo recusa quando classifica a mensagem como insegura. A guarda o declara como um modelo alcançado pela API compatível com OpenAI que o NIM serve, no endpoint e sob o nome de modelo que a aresta
safetypublica, e o seu prompt — o restante deconfig.yaml— é o que a documentação do NeMo Guardrails da NVIDIA fornece para este modelo, listando as suas categorias de dano, lido com o parser que o NeMo Guardrails fornece para o seu veredito.
Uma requisição recusada é respondida pela própria guarda, com I’m sorry, I can’t respond to that. (Sinto muito, não posso responder a isso.), e nada dela chega ao modelo. A configuração da guarda também traz um flow, rails.co, que executa os rails de entrada seja o que for que um corpo de requisição peça.
values.model em safety é o nome ao qual o NIM de segurança de conteúdo responde, que o NIM tira do seu próprio manifesto de modelo; a sua listagem de modelos, /v1/models, o mostra no servidor em execução. A guarda o envia com cada verificação, então os dois precisam concordar.
O que ela não faz
- Julga apenas a última mensagem do usuário. Uma tentativa colocada em uma mensagem de sistema, em um turno anterior ou no resultado de uma ferramenta chega ao modelo sem verificação, e nem a resposta do modelo, nem os argumentos de chamadas de ferramentas, nem imagens são julgados.
- Todo veredito é o de um modelo. As três verificações deixam passar algumas requisições nocivas ou manipuladoras e recusam algumas comuns.
- O rail de jailbreak falha aberto. A NVIDIA documenta que, quando o classificador de jailbreak não pode ser alcançado, excede o tempo limite ou responde com um erro, o rail deixa a requisição passar e não relata nada ao chamador. As outras duas verificações continuam sendo executadas. O rail de injeção de prompt recusa a requisição quando o seu detector não pode ser alcançado.
- Cobre apenas o tráfego que atravessa o gateway. Uma carga de trabalho que chama diretamente o endereço do modelo passa ao largo dele. A guarda e as três verificações não autenticam nenhum chamador, então os seus Services são endereços para os componentes que os chamam, não endereços para publicar.
- Não está comprovado em execução aqui. A configuração é a que a documentação da NVIDIA descreve, compilada antecipadamente; nada neste workspace executou os contêineres NemoGuard.
O que interrompe o build
A Recipe da guarda verifica o que os seus sockets NemoGuard contêm. Torne safety um simples core/ai-model/nvidia-nim — o seu tipo no Aggregate e a sua linha no Manifest — e o build é interrompido, sem escrever 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_safetyO socket jailbreak_detection aceita um core/security/nemoguard-jailbreak-detect e nada mais, da mesma forma, e cada socket aceita um único destino. As interrupções próprias do escudo são as de ai-gateway-prompt-injection-shield, que compila o mesmo gateway e a mesma guarda sem as verificações NemoGuard.
Onde o compilador não interpreta
O compilador canaliza os nomes de Service e as portas dos NIMs para a configuração da guarda, e os nomes dos Secrets para os pods, como strings. Ele não baixa nenhuma imagem, não obtém nenhum modelo nem lê nenhuma chave, e não contata nem a NVIDIA, nem a guarda, nem o modelo. Cada interrupção acima é declarada pelas próprias entidades do catálogo.
Adaptando-o
- Sem o modelo de segurança de conteúdo. Remova o componente
safetye a arestacontent_safetyda guarda; a configuração da guarda então não traz nenhum modelo, rail ou prompt desse tipo. O classificador de jailbreak é removido da mesma forma. - Um modelo que você mesmo executa. Aponte o
upstream_endpointda guarda para o endpoint do servidor do modelo —core/ai-model/vllmpublica um — e escreva o destino do alias comoopenai/<the name that server serves>. - GPUs maiores, ou duas. Cada componente NemoGuard aceita
infra.gpu.count, einfra.gpu.runtime_classonde o cluster seleciona o seu runtime de GPU por classe.