NeMo Guardrails 越狱检测实战指南：基于 jailbreak_detection 示例配置构建输入防护-开发者社区

人工智能
大模型
AI 安全治理
模型安全
内容安全
提示词注入防护
RAG

【免费下载链接】Guardrails

NeMo Guardrails is an open-source toolkit for easily adding programmable guardrails to LLM-based conversational systems.

项目地址：https://gitcode.com/gh_mirrors/ne/Guardrails

点击查看免费下载

NeMo Guardrails 是 NVIDIA 开源的 LLM 对话系统可编程护栏工具包。本文围绕仓库中 examples/configs/jailbreak_detection 示例，系统讲解如何为基于 LLM 的对话系统接入"越狱检测"（Jailbreak Detection）能力：从配置文件结构、两条内置 Rail 流（启发式 + 模型分类器）、阈值参数语义，到独立检测服务的部署与在进程内运行两种模式。读完本文，你将掌握config.yml的完整配置方法、flows.co的对话流写法，以及jailbreak detection heuristics与jailbreak detection model两条输入 Rail 的实际拦截行为与底层实现原理。

一、示例整体概览：三份文件各司其职

jailbreak_detection示例目录的结构非常精简，只有三个文件：

文件	作用
README.md	示例说明，交代目录结构与配置要点
config.yml	核心配置，声明主模型、越狱检测参数与启用的 Rail 流
flows.co	Colang 对话流文件，定义用户消息、机器人回复及示例对话流

其中config.yml和flows.co是真正驱动 NeMo Guardrails 运行时行为的两份文件：前者决定"检测能力如何配置与启用"，后者决定"机器人在什么场景下如何应答、越狱拦截后如何收场"。而真正的检测逻辑，则由仓库nemoguardrails/library/jailbreak_detection目录下的实现提供（详见下文）。

二、config.yml 逐字段解读：模型、阈值与 Rail 启用

示例中的 config.yml 内容如下：

models: - type: main engine: openai model: gpt-3.5-turbo-instruct rails: config: jailbreak_detection: server_endpoint: "http://localhost:1337/heuristics" lp_threshold: 89.79 ps_ppl_threshold: 1845.65 embedding: "Snowflake/snowflake-arctic-embed-m-long" input: flows: - jailbreak detection heuristics - jailbreak detection model

下面逐一拆解每个字段的含义。

2.1 models：主 LLM 的声明

models段声明对话系统使用的主模型：

type: main：标记这是主对话模型；
engine: openai：使用 OpenAI 兼容的推理引擎；
model: gpt-3.5-turbo-instruct：指定具体模型标识符。

该字段属于 NeMo Guardrails 通用的模型声明语法，与越狱检测本身无直接耦合——它决定的是"被保护的对象"（即正常对话所依赖的 LLM）。

2.2 rails.config.jailbreak_detection：检测参数

这里正是越狱检测 Rail 的配置入口。参数对应的数据结构定义在源码 rail_config.py 的JailbreakDetectionConfig中，各字段说明如下：

字段	示例值	类型	语义
`server_endpoint`	`http://localhost:1337/heuristics`	str（可选）	越狱检测服务（heuristics/模型容器）的 HTTP 端点；不设置则退化为在进程内运行（见第五节）
`lp_threshold`	`89.79`	float（默认 89.79，须 > 0）	length/perplexity（长度-困惑度）启发式的判定阈值
`ps_ppl_threshold`	`1845.65`	float（默认 1845.65，须 > 0）	prefix/suffix perplexity（前后缀困惑度）启发式的判定阈值
`embedding`	`Snowflake/snowflake-arctic-embed-m-long`	str（可选）	已废弃：该字段不再被使用（见源码 rail_config.py 的 deprecated 标注）
`nim_base_url`	例如`http://localhost:8000/v1`	str（可选）	使用 NVIDIA NIM 托管越狱检测模型时的 Base URL（示例未配置，按需补充）
`nim_server_endpoint`	`classify`	str（默认`classify`）	NIM 分类路径，默认指向 NemoGuard JailbreakDetect 的`classify`端点
`api_key`	—	SecretStr（可选）	NIM 请求的 API Key，优先级高于`api_key_env_var`
`api_key_env_var`	—	str（可选）	存放 NIM API Key 的环境变量名

值得注意的几点实现细节：

字段校验：源码中的validate_urls校验器要求server_endpoint与nim_base_url必须以http://或https://开头，否则直接抛出ValueError（见 rail_config.py）。
废弃字段迁移：旧的nim_url/nim_port字段已被nim_base_url取代，migrate_deprecated_fields校验器会在配置仍使用旧字段时自动将其转换为http://{nim_url}:{nim_port}/v1格式（见 rail_config.py），embedding字段同样已废弃。
API Key 解析优先级：get_api_key()方法按api_key字段 →api_key_env_var指向的环境变量依次取用（见 rail_config.py）。

2.3 rails.input.flows：启用两条输入 Rail

rails.input.flows中的两个名字直接对应越狱检测库中注册的两条 Colang 流：

input: flows: - jailbreak detection heuristics - jailbreak detection model

jailbreak detection heuristics：对用户输入执行启发式检查（长度-困惑度、前后缀困惑度）；
jailbreak detection model：调用基于嵌入的越狱检测分类器进行判别。

这两条流的定义、元信息与动作绑定关系，全部声明在 rail.py 的RailManifest中：该清单将该 Rail 标记为input方向，能力为allow / block / classify / detect_jailbreak，并把两条流分别绑定到jailbreak_detection_heuristics与jailbreak_detection_model两个动作（见 rail.py）。从源码结构可以推断，两条流以"用户输入"为绑定上下文（Binding.context("user_message", "user_message")），因此每次用户发消息都会触发检查。

三、flows.co 示例对话流解析

flows.co 定义了一个供演示的迷你机器人，包含四类内容：

用户意图：user express greeting（问候）、user ask name（询问名字）、user ask capabilities（询问能力）、user request repeat（要求重复）、user ask general question（各类普通问题，如股票推荐、餐厅推荐、写邮件、选举话题等 14 条具体话术）。
机器人消息：bot inform capabilities——"I am an example bot that illustrates jailbreak detection capabilities. Try to jailbreak me!"（示例机器人会主动邀请读者尝试越狱，便于演示拦截效果）。
两条简单对话流：
- 问候流：user express greeting→bot express greeting；
- 能力流：user ask capabilities→bot inform capabilities。
兜底对话流：user ask general question→bot provide response（普通问题走通用回复）。

这个文件的用意是构造一个"什么都能聊"的对话示例，让越狱检测 Rail 的效果直观可见：正常提问正常回复，越狱话术则被输入 Rail 拦截。

四、两条越狱检测 Rail 的底层实现

4.1 启发式检测流：jailbreak detection heuristics

该流对应的动作是jailbreak_detection_heuristics，实现在 actions.py。其执行逻辑为：

从配置读取server_endpoint、lp_threshold、ps_ppl_threshold；
取得当前用户消息作为待检prompt；
若配置了server_endpoint，则通过 request.py 中的jailbreak_detection_heuristics_request向端点发送POST请求，请求体为{"prompt": ..., "lp_threshold": ..., "ps_ppl_threshold": ...}，解析响应中的jailbreak布尔字段；
若未配置端点，则回退到进程内直接调用 heuristics/checks.py 中的两个检查函数，并输出警告 "Running in-process, NOT RECOMMENDED FOR PRODUCTION."；
若端点请求失败（非 200 或字段缺失），按"非越狱"放行并记录警告；
最终通过RailOutcome.block()或RailOutcome.allow()返回拦截/放行决策。

启发式检查本身基于 GPT-2 语言模型的困惑度（perplexity）计算，核心实现在 heuristics/checks.py：

长度-困惑度启发式（check_jailbreak_length_per_perplexity）：先以滑动窗口（stride=512）在gpt2-large上计算整个输入字符串的困惑度perplexity，再计算score = len(input_string) / perplexity，当score >= lp_threshold（默认 89.79）时判定为越狱。其背后的直觉是：典型的 DAN（Do Anything Now）式越狱话术往往"长度很长但困惑度异常低"，即文本高度重复、可预测。
前后缀困惑度启发式（check_jailbreak_prefix_suffix_perplexity）：先将输入按空白切分为词列表；当词数少于 20 时直接判定安全（源码注释明确说明对 GCG 式攻击，少于 20 个词无评估意义）；否则取前 19 个词作为prefix、取倒数第 2~21 个词作为suffix，分别计算困惑度，只要其中任何一个>= ps_ppl_threshold（默认 1845.65）即判定为越狱。这类攻击的典型特征是"正常前缀 + 无意义的高困惑度后缀"。

两个启发式检查在 server.py 的/heuristics端点中以any(...)逻辑合并，返回{"jailbreak": ..., "length_per_perplexity": ..., "prefix_suffix_perplexity": ...}。

4.2 模型分类器流：jailbreak detection model

该流对应的动作是jailbreak_detection_model，实现在 actions.py。执行逻辑依次为：

读取server_endpoint、nim_base_url、nim_server_endpoint、API Key（经get_api_key()解析）；
若启用了缓存（model_caches中名为jailbreak_detection的缓存），先按规范化后的 prompt 查询缓存，命中则直接返回缓存结果（该动作被当作一次 LLM 调用记录到追踪与日志中）；
分发检测路径：
- 若配置了nim_base_url：调用jailbreak_nim_request走 NVIDIA NIM 托管分类器，鉴权用api_key/api_key_env_var；
- 否则若配置了server_endpoint：调用jailbreak_detection_model_request请求/model端点；
- 否则：退化为进程内调用 model_based/checks.py 的check_jailbreak，同样给出 "NOT RECOMMENDED FOR PRODUCTION" 警告；
将结果写入缓存；
按jailbreak_result返回RailOutcome.block()或RailOutcome.allow()。

模型侧的实现要点（见 model_based/checks.py）：

分类器模型文件为snowflake.onnx，来源于 Hugging Face 仓库nvidia/NemoGuard-JailbreakDetect；
模型路径由环境变量EMBEDDING_CLASSIFIER_PATH指定，未设置时/model端点不可用（initialize_model()返回None并告警）；
check_jailbreak(prompt)返回{"jailbreak": 0/1, "score": ...}，其中分类结果被转换为布尔值。

4.3 两条流的拦截动作：flows.co 中的判定逻辑

仓库库目录下的 flows.co 展示了检测到越狱后的统一处置逻辑（示例配置通过rails.input.flows引用同名流）：

flow jailbreak detection heuristics $response = await JailbreakDetectionHeuristicsAction $is_jailbreak = $response.is_blocked if $is_jailbreak if $system.config.enable_rails_exceptions send JailbreakDetectionRailException(message="Jailbreak attempt detected. ...") else bot refuse to respond abort

即：一旦动作返回is_blocked，流会发送JailbreakDetectionRailException（若开启了 rails 异常）或触发bot refuse to respond并abort中断对话。模型流jailbreak detection model采用完全相同的处理结构。

五、检测服务部署与运行模式

示例中的server_endpoint: "http://localhost:1337/heuristics"指向独立部署的检测服务。该服务的源码位于 server.py，是基于 FastAPI + Typer 的轻量服务，主要端点如下：

端点	方法	说明
`/`	GET	返回服务介绍与端点指引
`/jailbreak_lp_heuristic`	POST	单独执行长度-困惑度启发式
`/jailbreak_ps_heuristic`	POST	单独执行前后缀困惑度启发式
`/heuristics`	POST	一次执行全部启发式并合并结果（示例配置使用的端点）
`/model`	POST	调用已加载的嵌入分类器，返回`{"jailbreak": ..., "score": ...}`

服务启动命令（默认监听0.0.0.0:1337）：

python server.py --port=1337

启动时会在初始化阶段加载分类器模型（_ = mc.initialize_model()）。

仓库提供了两种容器化部署方式：Dockerfile（CPU）与Dockerfile-GPU。以 CPU 版为例，它完成以下事情：

预下载分类器模型snowflake.onnx并设置EMBEDDING_CLASSIFIER_PATH=/models；
安装 requirements.txt 中声明的最小依赖集；
设置JAILBREAK_CHECK_DEVICE=cpu，并预下载gpt2-large及其 tokenizer（启发式困惑度计算依赖）；
暴露 1337 端口，默认以python /app/server.py --port=1337启动。

关键环境变量汇总：

环境变量	作用
`EMBEDDING_CLASSIFIER_PATH`	本地嵌入分类器模型所在目录（缺失时`/model`端点与进程内模型检测不可用）
`JAILBREAK_CHECK_DEVICE`	本地模型加载设备，如`cpu`、`cuda:0`（默认`cpu`）
`NVIDIA_API_KEY`	使用 NVIDIA NIM 托管配置时的 API Key
`HF_TOKEN`/`HF_HOME`/`HF_HUB_OFFLINE`	可选：本地模型下载/缓存相关配置（见 rail.py 的`RailRequirements`声明）

运行模式小结：

远端服务模式（推荐生产）：配置server_endpoint（及可选的 NIM 配置），NeMo Guardrails 通过 HTTP 调用独立服务完成检测，检测逻辑与主进程解耦；
进程内模式（仅限原型/测试）：不配置任何端点，动作会回退到进程内直接加载 GPT-2 与分类器执行检查。源码在两条动作路径中均明确记录警告 "Running in-process, NOT RECOMMENDED FOR PRODUCTION."，并需要torch、transformers（以及模型检测所需的scikit-learn）等可选依赖，故仅适合本地验证。

六、阈值调参与测试验证

6.1 两个阈值的语义与调参方向

lp_threshold（默认 89.79）：len(prompt) / perplexity(prompt)的判定线。越狱话术若"冗长且低困惑度"，比值会显著偏高，可适当调低阈值提高召回、调高阈值降低误报。
ps_ppl_threshold（默认 1845.65）：前后缀困惑度的判定线。GCG 式攻击的"垃圾后缀"困惑度极高，阈值越高对正常长文本越宽容。

源码中的默认值同时出现在配置模型（rail_config.py）、FastAPI 请求模型（server.py）与请求转发（request.py）三处，三者保持一致。

6.2 测试用例作为调参参考

仓库的 tests/test_jailbreak_heuristics.py 提供了权威的行为基准：

test_jb_len_ppl_detected/test_jb_ps_ppl_detected：分别用典型的 DAN 式长文本与"正常前缀 + 高困惑度后缀"文本构造越狱样例，断言在默认阈值（89.79 / 1845.65）下会被判定为越狱并触发拒绝回复；
test_safe：普通教学场景文本不应被误判，机器人正常回复；
test_get_perplexity：正常句子的困惑度应远低于 20，而高困惑度乱码应大于 15000，直观反映困惑度区分的有效性；
test_check_jailbreak_length_per_perplexity/test_check_jailbreak_prefix_suffix_perplexity：直接对两个启发式函数做阈值断言。

注意这些测试依赖torch与transformers可选依赖，未安装时会被skipif跳过。若你使用 NIM 托管方案，还需参考 tests/test_jailbreak_nim.py 了解 NIM 路径的请求格式与鉴权行为。

七、从示例到生产：完整接入路径

将本示例落地到自己的对话系统，整体链路如下：

准备配置文件：参照 config.yml，声明主模型，并在rails.config.jailbreak_detection下配置端点与阈值；
启用 Rail 流：在rails.input.flows中加入jailbreak detection heuristics与jailbreak detection model（两条流均可在 flows.co 中查看其拦截行为定义）；
部署检测服务：按 Dockerfile 构建镜像并运行于 1337 端口，或改用 NVIDIA NIM（配置nim_base_url+api_key）作为模型分类路径；
定义对话流：参考 flows.co 编写普通对话流与兜底流，让正常交互不被误伤；
验证与调参：用 tests/test_jailbreak_heuristics.py 中的正反样例测试当前阈值配置，再结合自身业务数据微调两个阈值。

需要特别提醒：本示例采用的gpt-3.5-turbo-instruct与本地 GPT-2 困惑度计算仅用于演示；生产环境建议将检测服务独立部署（进程内模式会引入模型加载开销与明显的日志警告），并对越狱检测涉及的用户文本传输做好隐私评估——该 Rail 的RailPrivacy声明为sends_user_text=True（见 rail.py），即用户消息会发送给检测服务/NIM，接入前应确保符合自身的数据合规要求。

八、延伸阅读

越狱检测库完整实现：nemoguardrails/library/jailbreak_detection
配置模型与字段校验：rail_config.py
动作与请求链路：actions.py、request.py
检测服务：server.py
更多安全类输入 Rail 示例：可参考 examples/configs/injection_detection 与 examples/configs/prompt_security，构建多层次输入防护。