跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

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它在此处的角色
agentcore/ai-agent/langgraph智能体,即 Release 自己的应用镜像,通过网关访问其模型
checkpointercore/datastore/valkey智能体保存其运行状态的位置
routercore/gateway/litellmAI 网关:一个别名 assistant,经由防护组件发送到模型
guardcore/security/nemo-guardrails位于模型路径上的 NVIDIA NeMo Guardrails 服务器
detectorcore/security/trustyai-huggingface-detector防护组件自身的 rail 所询问的提示注入分类器
safetycore/ai-model/nemoguard-content-safetyNVIDIA 的 Llama 3.1 NemoGuard 8B ContentSafety,由其 NIM 提供服务
jailbreakcore/security/nemoguard-jailbreak-detectNVIDIA 的 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 助手替你构建。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example nemo-guardrails-nemoguard-nims

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd nemo-guardrails-nemoguard-nims

构建

Terminal window
aggrega build --release release.yaml --auto-pull

release 在构建之前需要一个 lockfile,而 lockfile 是生成的而非随附发布的,因此全新克隆的仓库中没有 lockfile。请先解析出一个,或者让构建来填充它:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega 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>/dist

Release 指明了目录未指明的每个镜像。 智能体的镜像是你自己的应用。防护组件和检测器的镜像是你所运行构建的副本,镜像到你控制的注册表中。两个 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 schema

Release 真正会写入的唯一字符串,即 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: EMPTY
passthrough: true
rails:
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_safety

jailbreak_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。