NeMo Guardrails kiểm tra các yêu cầu của agent bằng các mô hình NemoGuard của NVIDIA
Các yêu cầu mô hình của một agent đi qua NVIDIA NeMo Guardrails, thành phần kiểm tra từng yêu cầu bằng hai mô hình NemoGuard của NVIDIA, là các sản phẩm NVIDIA có bản quyền cần giấy phép từ NVIDIA, khóa API NGC và một node GPU để chạy.
Những gì cần có
Hai mô hình NemoGuard là các sản phẩm NVIDIA mà bạn chạy theo các điều khoản của NVIDIA. Việc triển khai những gì workspace này build cần có:
- Giấy phép từ NVIDIA. Tài liệu của NVIDIA cho từng microservice NemoGuard nêu điều kiện tiên quyết là “có gói đăng ký đang hoạt động cho một sản phẩm NVIDIA AI Enterprise hoặc là thành viên NVIDIA Developer Program”, và cho biết quyền truy cập vào các container và mô hình bị hạn chế.
- Một khóa API NGC, được Release tham chiếu dưới dạng secret. Các container NemoGuard được kéo từ registry của NVIDIA,
nvcr.io, và mỗi container tải mô hình của nó từ NVIDIA bằng khóa đó khi khởi động. Release nêu tên hai Kubernetes Secret chứa khóa — một Secret mà các pod đọc khóa từ đó, một Secret mà cụm dùng để kéo image — và không tệp nào trong workspace này, cũng như không thứ gì mà bản build ghi ra, chứa chính khóa đó. - Một node GPU. Mỗi container NemoGuard yêu cầu một GPU NVIDIA. NVIDIA cho biết mô hình an toàn nội dung cần 48 GB bộ nhớ GPU, trên một hoặc hai GPU.
Bản build không cần thứ nào trong số này: nó biên dịch thành các manifest Kubernetes mà không cần có khóa, và không liên hệ với NVIDIA lẫn cụm.
Những gì ví dụ này xây dựng
Một agent yêu cầu mô hình của nó thông qua một AI gateway. Gateway gửi mọi yêu cầu mô hình qua một guard trước, và guard kiểm tra tin nhắn mới nhất của người dùng theo ba cách trước khi chuyển những gì nó chấp nhận tới mô hình: bằng một bộ phân loại prompt injection, bằng mô hình an toàn nội dung của NVIDIA, và bằng bộ phân loại jailbreak của NVIDIA. Workspace này biên dịch cách sắp xếp đó thành các manifest Kubernetes.
Nó cho thấy một sản phẩm thương mại có bản quyền được cung cấp theo cùng cách như một sản phẩm mã nguồn mở: một Component trong catalog, một Recipe, một cạnh uses và một attachment thông tin xác thực, với giấy phép được nêu ở nơi người đọc chọn thành phần. Nó không tạo entity catalog nào của riêng mình; Aggregate, Manifest và Release là toàn bộ những gì bất kỳ ai viết.
| instance | Component trong catalog | vai trò ở đây |
|---|---|---|
agent | core/ai-agent/langgraph | agent, image ứng dụng riêng của Release, tiếp cận mô hình của nó qua gateway |
checkpointer | core/datastore/valkey | nơi agent lưu trạng thái chạy của nó |
router | core/gateway/litellm | AI gateway: một alias, assistant, được gửi tới mô hình qua guard |
guard | core/security/nemo-guardrails | máy chủ NVIDIA NeMo Guardrails trên đường đi của mô hình |
detector | core/security/trustyai-huggingface-detector | bộ phân loại prompt injection mà rail riêng của guard truy vấn |
safety | core/ai-model/nemoguard-content-safety | Llama 3.1 NemoGuard 8B ContentSafety của NVIDIA, được NIM của nó phục vụ |
jailbreak | core/security/nemoguard-jailbreak-detect | NemoGuard JailbreakDetect của NVIDIA, được NIM của nó phục vụ |
Các cạnh uses: socket model của agent tới gateway và socket checkpointer_db của nó tới kho lưu trữ; socket guard của gateway tới guard; và các socket detector, content_safety và jailbreak_detection của guard tới ba bước kiểm tra. Các attachment: shield, Feature core/prompt-injection-shield đặt guard trên đường đi của gateway; upstream_key, thông tin xác thực mà guard xuất trình cho API của mô hình; và ngc_api_key trên mỗi thành phần NemoGuard.
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example nemo-guardrails-nemoguard-nimsSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd nemo-guardrails-nemoguard-nimsBuild
aggrega build --release release.yaml --auto-pullMột release cần có lockfile trước khi build, và lockfile được tạo ra chứ không được phân phối kèm, nên một bản clone mới sẽ không có. Hãy resolve một lockfile trước, hoặc để quá trình build tự điền vào:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildWorkspace này phân giải các thực thể của catalog từ registry mặc định mà .aggrega-config.yaml chỉ định. Phần hiện thực hóa của shield chạy một plugin không đi kèm trong compiler lẫn catalog, đó là bước cấu hình gateway pipeline-step/litellm-gateway-config, mà quá trình phân giải tải về từ registry do default_registry chỉ định, hub.aggrega.ai.
Bản build in ra như sau, với <workspace> đại diện cho thư mục của ví dụ này:
[… 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 nêu tên mọi image mà catalog không nêu. Image của agent là ứng dụng của chính bạn. Image của guard và của detector là bản sao của các bản build bạn chạy, được mirror vào một registry do bạn kiểm soát. Hai image NemoGuard là của NVIDIA, mà bạn có quyền kéo theo giấy phép của mình; catalog không nêu tên image nào trong số đó, và release.yaml ghi mỗi image với tag change-me. Bản build truyền nguyên bất kỳ chuỗi nào có ở đó; hãy thay thế chúng trước khi triển khai.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục Workspace chưa có thư mục `nemo-guardrails-nemoguard-nims`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `nemo-guardrails-nemoguard-nims` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `nemo-guardrails-nemoguard-nims` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `nemo-guardrails-nemoguard-nims`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Cho tôi biết bản dựng đã ghi những tệp nào; chúng nằm trong `nemo-guardrails-nemoguard-nims/dist/`.Cây thư mục được kết xuất
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.yamlKhông có Secret nào trong số đó. Mọi thông tin xác thực được gắn dưới dạng core/referenced-secret, và Manifest ràng buộc nó với helm/k8s-existing-secret, thứ trỏ một workload tới một Secret đã tồn tại trong namespace và tự nó không render gì.
Khóa, dưới dạng tham chiếu
Aggregate chỉ ghi vị trí của khóa bên trong một Secret, tức khóa dữ liệu NGC_API_KEY; Release đặt tên cho Secret, ngc-api-key, và cho Secret dùng để kéo image, ngc-registry. Trong dist/helm/safety-statefulset.yaml, và tương tự trong tệp của bộ phân loại jailbreak:
env: - name: NGC_API_KEY valueFrom: secretKeyRef: name: ngc-api-key key: NGC_API_KEY imagePullSecrets: - name: ngc-registryTrước khi triển khai, hãy tạo cả hai Secret trong namespace đích: ngc-api-key chứa khóa dưới NGC_API_KEY, và ngc-registry, một Secret kéo image cho nvcr.io đăng nhập bằng khóa đó. Thông tin xác thực upstream của dịch vụ bảo vệ được đặt tên theo cùng cách, là Secret upstream-provider-key chứa khóa của API mô hình dưới upstream-key.
Release không thể ghi chính khóa vào vị trí đó. Một khối values: trên một phần đính kèm trong Release bị từ chối khi tài liệu được tải, vì những gì Release ghi ở đó thuộc về người vận hành, còn values thuộc về nhà phát triển. Thay khối infra: của ngc_api_key thuộc thành phần safety bằng values: chứa một origin, và bản build sẽ in ra, trước mọi thứ khác:
[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 schemaChuỗi duy nhất mà Release thực sự ghi, tức tên của một Secret, được công bố đúng như khi được viết: quá trình build không thể phân biệt một tên với một khóa, nên một khóa được gõ vào chỗ dành cho tên sẽ xuất hiện trong tệp manifest dưới dạng chính tên đó. Đồ thị mà aggrega build --ir-graph in ra đều ẩn nó trong cả hai trường hợp, vì origin được khai báo là nhạy cảm.
Lớp bảo vệ làm gì
Cấu hình của dịch vụ bảo vệ, tức khóa config.yaml của dist/helm/guard/nemo-guardrails-config.configmap.yaml, cho đến trước phần prompt:
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_safetyVới mỗi yêu cầu chat, dịch vụ bảo vệ chạy ba rail đầu vào trên tin nhắn mới nhất của người dùng, theo đúng thứ tự đó, và từ chối yêu cầu khi bất kỳ rail nào trong số đó từ chối:
- Bộ phân loại chèn prompt từ chối khi bộ phát hiện báo cáo
INJECTIONở mức bằng hoặc cao hơn0.5. - Bộ phân loại jailbreak từ chối khi bộ phân loại của NVIDIA trả lời rằng tin nhắn là một nỗ lực jailbreak. Dịch vụ bảo vệ gửi tin nhắn đến route
classifycủa nó; không có khóa nào được cấu hình, vì dịch vụ trong cụm không yêu cầu khóa nào. - Mô hình an toàn nội dung từ chối khi nó đánh giá tin nhắn là không an toàn. Dịch vụ bảo vệ khai báo nó là một mô hình được truy cập qua API tương thích OpenAI mà NIM cung cấp, tại endpoint và dưới tên mô hình mà cạnh
safetycông bố, và prompt của nó — phần còn lại củaconfig.yaml— là prompt mà tài liệu NeMo Guardrails của NVIDIA đưa ra cho mô hình này, liệt kê các danh mục gây hại của nó, được đọc bằng trình phân tích cú pháp mà NeMo Guardrails cung cấp cho phán quyết của nó.
Yêu cầu bị từ chối được chính dịch vụ bảo vệ trả lời bằng I’m sorry, I can’t respond to that., và không phần nào của nó đến được mô hình. Cấu hình của dịch vụ bảo vệ cũng mang một luồng, rails.co, chạy các rail đầu vào bất kể phần thân yêu cầu đòi hỏi gì.
values.model trên safety là tên mà NIM an toàn nội dung phản hồi theo, được NIM lấy từ manifest mô hình của chính nó; danh sách mô hình của nó, /v1/models, hiển thị tên này trên máy chủ đang chạy. Dịch vụ bảo vệ gửi tên này kèm mỗi lần kiểm tra, nên hai bên phải khớp nhau.
Những gì nó không làm
- Nó chỉ đánh giá tin nhắn mới nhất của người dùng. Một nỗ lực được đặt trong tin nhắn hệ thống, một lượt trước đó hoặc kết quả công cụ sẽ đến mô hình mà không bị kiểm tra, và cả câu trả lời của mô hình, các đối số gọi công cụ lẫn hình ảnh đều không được đánh giá.
- Mọi phán quyết đều do mô hình đưa ra. Ba bước kiểm tra bỏ sót một số yêu cầu gây hại hoặc thao túng và từ chối một số yêu cầu bình thường.
- Rail jailbreak cho yêu cầu đi qua khi gặp lỗi. NVIDIA ghi trong tài liệu rằng khi không thể kết nối tới bộ phân loại jailbreak, khi nó hết thời gian chờ hoặc trả lời bằng một lỗi, rail sẽ cho yêu cầu đi qua và không báo gì cho bên gọi. Hai bước kiểm tra còn lại vẫn chạy. Rail chèn prompt từ chối yêu cầu khi không thể kết nối tới bộ phát hiện của nó.
- Nó chỉ bao quát lưu lượng đi qua gateway. Một khối lượng công việc gọi trực tiếp đến địa chỉ của mô hình sẽ đi vòng qua nó. Dịch vụ bảo vệ và ba bước kiểm tra không xác thực bên gọi nào, nên các Services của chúng là địa chỉ dành cho các thành phần gọi chúng, không phải địa chỉ để công bố.
- Chưa được chứng minh là chạy được ở đây. Cấu hình là cấu hình mà tài liệu của NVIDIA mô tả, được biên dịch trước; không có gì trong workspace này từng chạy các container NemoGuard.
Điều gì làm dừng quá trình build
Recipe của dịch vụ bảo vệ kiểm tra những gì các socket NemoGuard của nó chứa. Hãy biến safety thành một core/ai-model/nvidia-nim thông thường — kiểu của nó trong Aggregate và dòng của nó trong Manifest — và bản build sẽ dừng lại, không ghi gì:
[… 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_safetySocket jailbreak_detection theo cùng cách chỉ nhận một core/security/nemoguard-jailbreak-detect và không gì khác, và mỗi socket nhận một đích. Các điểm dừng riêng của lớp chắn là những điểm dừng của ai-gateway-prompt-injection-shield, ví dụ xây dựng cùng gateway và dịch vụ bảo vệ đó nhưng không có các bước kiểm tra NemoGuard.
Nơi trình biên dịch không diễn giải
Trình biên dịch truyền tên Service và cổng của các NIM vào cấu hình của dịch vụ bảo vệ, và tên của các Secret vào các pod, dưới dạng chuỗi. Nó không kéo image, không tải mô hình hay đọc khóa, và không liên hệ với NVIDIA, dịch vụ bảo vệ hay mô hình. Mỗi điểm dừng ở trên đều do chính các thực thể của catalog khai báo.
Điều chỉnh ví dụ
- Không có mô hình an toàn nội dung. Xóa thành phần
safetyvà cạnhcontent_safetycủa dịch vụ bảo vệ; khi đó cấu hình của dịch vụ bảo vệ không còn mô hình, rail hay prompt nào như vậy. Bộ phân loại jailbreak được xóa theo cùng cách. - Một mô hình do bạn tự chạy. Trỏ
upstream_endpointcủa guard tới endpoint của máy chủ mô hình —core/ai-model/vllmcông bố một endpoint như vậy — và viết đích của alias làopenai/<the name that server serves>. - GPU lớn hơn hoặc hai GPU. Mỗi thành phần NemoGuard nhận
infra.gpu.count, vàinfra.gpu.runtime_classkhi cụm chọn runtime GPU của nó theo lớp.