NVIDIA의 NemoGuard 모델로 에이전트의 요청을 검사하는 NeMo Guardrails
에이전트의 모델 요청은 NVIDIA NeMo Guardrails를 거치며, NeMo Guardrails는 각 요청을 NVIDIA의 NemoGuard 모델 두 개로 검사합니다. 이 모델들은 NVIDIA의 라이선스 제품으로, 실행하려면 NVIDIA의 라이선스, NGC API 키, GPU 노드가 필요합니다.
필요한 것
두 NemoGuard 모델은 NVIDIA의 약관에 따라 실행하는 NVIDIA 제품입니다. 이 워크스페이스가 빌드하는 것을 배포하려면 다음이 필요합니다:
- NVIDIA의 라이선스. 각 NemoGuard 마이크로서비스에 대한 NVIDIA의 문서는 전제 조건을 “NVIDIA AI Enterprise 제품의 활성 구독이 있거나 NVIDIA Developer Program 회원일 것”으로 명시하며, 컨테이너와 모델에 대한 액세스가 제한된다고 밝힙니다.
- Release가 시크릿으로 참조하는 NGC API 키. NemoGuard 컨테이너는 NVIDIA의 레지스트리
nvcr.io에서 풀되며, 각 컨테이너는 시작할 때 이 키로 NVIDIA에서 모델을 가져옵니다. Release는 키를 담은 두 Kubernetes Secret을 지정합니다. 하나는 파드가 키를 읽는 Secret이고, 다른 하나는 클러스터가 이미지를 풀할 때 쓰는 Secret입니다. 이 워크스페이스의 어떤 파일도, 빌드가 쓰는 어떤 것도 키 자체를 담고 있지 않습니다. - GPU 노드. 각 NemoGuard 컨테이너는 NVIDIA GPU를 요청합니다. NVIDIA에 따르면 콘텐츠 안전 모델에는 GPU 한 개 또는 두 개에 걸쳐 48GB의 GPU 메모리가 필요합니다.
빌드에는 이 중 어느 것도 필요하지 않습니다. 키 없이 Kubernetes 매니페스트로 컴파일하며, NVIDIA에도 클러스터에도 연결하지 않습니다.
구성되는 내용
에이전트는 AI 게이트웨이를 통해 모델을 요청합니다. 게이트웨이는 모든 모델 요청을 먼저 가드로 보내고, 가드는 최신 사용자 메시지를 세 가지 방법으로 검사한 뒤 허용한 것을 모델로 전달합니다. 프롬프트 인젝션 분류기, NVIDIA의 콘텐츠 안전 모델, NVIDIA의 탈옥(jailbreak) 분류기로 검사합니다. 이 워크스페이스는 이 구성을 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 | 가드 자체의 레일이 질의하는 프롬프트 인젝션 분류기 |
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 소켓은 세 검사로 연결됩니다. 연결(attachment): shield는 가드를 게이트웨이 경로에 두는 core/prompt-injection-shield Feature이고, upstream_key는 가드가 모델 API에 제시하는 자격 증명이며, ngc_api_key는 각 NemoGuard 컴포넌트에 있습니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example nemo-guardrails-nemoguard-nims그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd nemo-guardrails-nemoguard-nims빌드
aggrega build --release release.yaml --auto-pullrelease는 빌드하기 전에 lockfile이 필요하며, lockfile은 배포되지 않고 생성되므로 새로 clone한 저장소에는 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` 폴더가 없으면 `example`을 `nemo-guardrails-nemoguard-nims`로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 새 `nemo-guardrails-nemoguard-nims` 폴더에 예제가 작성됩니다. 그런 다음 `workspace_root`를 `nemo-guardrails-nemoguard-nims`로, `release`를 `release.yaml`로, `auto_pull`을 true로, `write`를 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 작성한 파일을 알려 주십시오. 파일은 `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와, 그 키로 로그인하는 nvcr.io용 이미지 풀 Secret인 ngc-registry입니다. 가드의 업스트림 자격 증명도 같은 방식으로 이름이 지정되며, upstream-key 아래에 모델 API의 키를 보관하는 Secret upstream-provider-key입니다.
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도 받습니다.