NeMo Guardrails 使用 NVIDIA 的 NemoGuard 模型检查智能体的请求
智能体的模型请求会经过 NVIDIA NeMo Guardrails,它用 NVIDIA 的两个 NemoGuard 模型检查每个请求;这两个模型是 NVIDIA 的授权产品,运行它们需要 NVIDIA 的许可证、NGC API 密钥和 GPU 节点。
所需条件
这两个 NemoGuard 模型是你依照 NVIDIA 的条款运行的 NVIDIA 产品。部署此工作区构建的内容需要:
- NVIDIA 的许可证。 NVIDIA 为每个 NemoGuard 微服务提供的文档将其前提条件表述为“拥有 NVIDIA AI Enterprise 产品的有效订阅,或是 NVIDIA Developer Program 成员”,并说明对容器和模型的访问受到限制。
- NGC API 密钥,由 Release 作为 secret 引用。 NemoGuard 容器从 NVIDIA 的注册表
nvcr.io拉取,每个容器在启动时使用该密钥从 NVIDIA 获取其模型。Release 指明了保存该密钥的两个 Kubernetes Secret——一个供 pod 从中读取密钥,另一个供集群拉取镜像——此工作区中没有任何文件、构建写出的内容中也没有任何东西保存密钥本身。 - GPU 节点。 每个 NemoGuard 容器都会请求一块 NVIDIA GPU。NVIDIA 表示,内容安全模型需要 48 GB 的 GPU 显存,分布在一块或两块 GPU 上。
构建不需要其中任何一项:它在没有密钥的情况下编译为 Kubernetes 清单,既不联系 NVIDIA,也不联系集群。
它构建了什么
智能体通过 AI 网关请求其模型。网关先将每个模型请求发送给防护组件,防护组件以三种方式检查最新的用户消息,然后才将其放行的内容转发给模型:使用提示注入分类器、使用 NVIDIA 的内容安全模型,以及使用 NVIDIA 的越狱分类器。此工作区将这一编排编译为 Kubernetes 清单。
它展示了获得许可的商业产品与开源产品的配置方式相同:一个目录 Component、一个 Recipe、一条 uses 边和一个凭据挂接,并在读者选择该组件的地方说明许可证。它不编写任何自己的目录实体;Aggregate、Manifest 和 Release 就是任何人需要编写的全部内容。
| 实例 | 目录中的 Component | 它在此处的角色 |
|---|---|---|
agent | core/ai-agent/langgraph | 智能体,即 Release 自己的应用镜像,通过网关访问其模型 |
checkpointer | core/datastore/valkey | 智能体保存其运行状态的位置 |
router | core/gateway/litellm | AI 网关:一个别名 assistant,经由防护组件发送到模型 |
guard | core/security/nemo-guardrails | 位于模型路径上的 NVIDIA NeMo Guardrails 服务器 |
detector | core/security/trustyai-huggingface-detector | 防护组件自身的 rail 所询问的提示注入分类器 |
safety | core/ai-model/nemoguard-content-safety | NVIDIA 的 Llama 3.1 NemoGuard 8B ContentSafety,由其 NIM 提供服务 |
jailbreak | core/security/nemoguard-jailbreak-detect | NVIDIA 的 NemoGuard JailbreakDetect,由其 NIM 提供服务 |
uses 边:智能体的 model 套接字连接到网关,其 checkpointer_db 套接字连接到存储;网关的 guard 套接字连接到防护组件;防护组件的 detector、content_safety 和 jailbreak_detection 套接字连接到三项检查。挂接:shield,即把防护组件放到网关路径上的 core/prompt-injection-shield Feature;upstream_key,即防护组件向模型 API 出示的凭据;以及每个 NemoGuard 组件上的 ngc_api_key。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example nemo-guardrails-nemoguard-nims然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd nemo-guardrails-nemoguard-nims构建
aggrega build --release release.yaml --auto-pullrelease 在构建之前需要一个 lockfile,而 lockfile 是生成的而非随附发布的,因此全新克隆的仓库中没有 lockfile。请先解析出一个,或者让构建来填充它:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the build此工作区从 .aggrega-config.yaml 指定的默认注册表解析目录实体。shield 的实现会运行一个既不随编译器也不随目录提供的插件,即网关配置步骤 pipeline-step/litellm-gateway-config,解析过程会从 default_registry 指定的注册表 hub.aggrega.ai 获取它。
构建会输出如下内容,其中 <workspace> 代表本示例的文件夹:
[… 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>/distRelease 指明了目录未指明的每个镜像。 智能体的镜像是你自己的应用。防护组件和检测器的镜像是你所运行构建的副本,镜像到你控制的注册表中。两个 NemoGuard 镜像属于 NVIDIA,你可以依据你的许可证拉取它们;目录一个都没有指明,release.yaml 将每个镜像都写为标签 change-me。构建会原样传递那里的任何字符串;请在部署前替换它们。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `nemo-guardrails-nemoguard-nims` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `nemo-guardrails-nemoguard-nims`,不设 `dir`:它会把示例写入新的 `nemo-guardrails-nemoguard-nims` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `nemo-guardrails-nemoguard-nims`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我这次构建写入了哪些文件;它们位于 `nemo-guardrails-nemoguard-nims/dist/` 下。渲染出的目录树
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其中没有 Secret。每个凭据都以 core/referenced-secret 的形式挂接,Manifest 将其绑定到 helm/k8s-existing-secret,后者让工作负载指向命名空间中已存在的 Secret,自身不渲染任何内容。
密钥,作为引用
Aggregate 只写出密钥在 Secret 中所处的位置,即数据键 NGC_API_KEY;Release 则命名该 Secret,即 ngc-api-key,以及拉取镜像所用的 Secret,即 ngc-registry。在 dist/helm/safety-statefulset.yaml 中如下,越狱分类器的对应文件中也一样:
env: - name: NGC_API_KEY valueFrom: secretKeyRef: name: ngc-api-key key: NGC_API_KEY imagePullSecrets: - name: ngc-registry部署之前,请在目标命名空间中创建这两个 Secret:ngc-api-key,在 NGC_API_KEY 下保存该密钥;以及 ngc-registry,一个用于 nvcr.io 的镜像拉取 Secret,它使用该密钥登录。防护服务的上游凭据也以同样的方式命名,即 Secret upstream-provider-key,在 upstream-key 下保存模型 API 的密钥。
Release 不能在该位置写入密钥本身。Release 中某个附加项上的 values: 块会在文档加载时被拒绝,因为 Release 在那里写入的内容属于运维人员,而 values 属于开发者。将 safety 组件的 ngc_api_key 的 infra: 块替换为包含 origin 的 values:,构建会在输出任何其他内容之前打印:
[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 schemaRelease 真正会写入的唯一字符串,即 Secret 的名称,会按书写的原样发布:构建过程无法区分名称与密钥,因此在应填写名称的位置键入的密钥,会作为该名称出现在清单中。aggrega build --ir-graph 打印的图在两种情况下都会隐去它,因为 origin 被声明为敏感项。
防护层做什么
防护服务的配置,即 dist/helm/guard/nemo-guardrails-config.configmap.yaml 中的 config.yaml 键,截至其提示词之前:
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_safety对于每个聊天请求,防护服务都会按此顺序对最新的用户消息运行三个输入护栏,并在其中任一护栏拒绝时拒绝该请求:
- 提示注入分类器在检测器报告
INJECTION达到或超过0.5时拒绝。 - 越狱分类器在 NVIDIA 的分类器回答该消息是越狱尝试时拒绝。防护服务将消息发送到其
classify路由;未配置任何密钥,因为集群内服务不要求密钥。 - 内容安全模型在将消息评为不安全时拒绝。防护服务将其声明为一个通过 NIM 提供的 OpenAI 兼容 API 访问的模型,使用
safety边所发布的端点和模型名称;其提示词——即config.yaml的其余部分——是 NVIDIA 的 NeMo Guardrails 文档为该模型给出的提示词,其中列出了它的危害类别,并使用 NeMo Guardrails 为其判定结果提供的解析器来读取。
被拒绝的请求由防护服务自行回答,回复为 I’m sorry, I can’t respond to that.,其中任何内容都不会到达模型。防护服务的配置还带有一个流程 rails.co,无论请求体要求什么,它都会运行输入护栏。
safety 上的 values.model 是内容安全 NIM 所响应的名称,NIM 从其自身的模型清单中获取该名称;它的模型列表 /v1/models 会在运行中的服务器上显示该名称。防护服务在每次检查时都会发送它,因此两者必须一致。
它不做什么
- 它只判断最新的用户消息。 放在系统消息、较早的轮次或工具结果中的尝试会未经检查地到达模型,而模型的回复、工具调用参数和图像都不会被判断。
- 每个判定都出自模型。 这三项检查会漏掉一些有害或操纵性的请求,也会拒绝一些普通请求。
- 越狱护栏在故障时放行。 NVIDIA 的文档说明,当越狱分类器无法访问、超时或返回错误时,该护栏会放行请求,并且不向调用方报告任何内容。另外两项检查仍会运行。当提示注入护栏的检测器无法访问时,该护栏会拒绝请求。
- 它只覆盖经过网关的流量。 直接调用模型地址的工作负载会绕过它。防护服务和三项检查都不对任何调用方进行身份验证,因此它们的 Services 是供调用它们的组件使用的地址,而不是要对外发布的地址。
- 此处未证明它能运行。 该配置是 NVIDIA 文档所描述的配置,经过预先编译;此工作区中没有任何东西运行过 NemoGuard 容器。
什么会中止构建
防护服务的 Recipe 会检查其 NemoGuard 插口中装的是什么。将 safety 改为普通的 core/ai-model/nvidia-nim——包括它在 Aggregate 中的类型和在 Manifest 中的那一行——构建就会停止,且不写入任何内容:
[… 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_safetyjailbreak_detection 插口同样只接受 core/security/nemoguard-jailbreak-detect,不接受其他任何东西,并且每个插口只接受一个目标。防护盾自身的停止条件与 ai-gateway-prompt-injection-shield 的相同,该示例构建相同的网关和防护服务,但不带 NemoGuard 检查。
编译器不做解释的地方
编译器将各 NIM 的 Service 名称和端口传入防护服务的配置,并将各 Secret 的名称传入 Pod,均以字符串形式传递。它不拉取镜像,不获取模型,也不读取密钥,并且不联系 NVIDIA、防护服务或模型。上述每个停止都由目录自身的实体声明。
改编示例
- 不使用内容安全模型。 移除
safety组件以及防护服务的content_safety边;此后防护服务的配置中就不再有这样的模型、护栏或提示词。越狱分类器也以同样的方式移除。 - 自行运行的模型。 将 guard 的
upstream_endpoint指向模型服务器的端点(core/ai-model/vllm会发布一个), 并将别名的目标写为openai/<the name that server serves>。 - 更大的 GPU 或两块 GPU。 每个 NemoGuard 组件都接受
infra.gpu.count,在集群按类选择其 GPU 运行时的情况下,还接受infra.gpu.runtime_class。