企业官网建设流程全解析

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

本文基于 NeMo Guardrails 开源仓库中的nemoguardrails/library/README.md及其关联的录制测试说明，系统讲解该框架内置护栏库的整体架构：包含哪些预置 Rail、每个 Rail 由哪些文件组成、如何通过配置文件一键激活，以及社区贡献者在nemoguardrails/library/<feature>/下新增 Rail 时必须遵守的录制端到端（e2e）测试规范。读完本文，你将能够熟练使用内置 Rail 组装自己的护栏配置，并按照仓库标准为新增 Rail 补齐可回放、不依赖外部服务的测试覆盖。

一、什么是 NeMo Guardrails Library

NeMo Guardrails 是一个用于为基于 LLM 的对话系统添加可编程护栏的开源工具包。其中，nemoguardrails/library/目录（即文档所称的 Library）存放一组预构建好的 Rail，它们的共同特点是：

任何配置（config）都可以直接激活这些 Rail，无需自己从零编写 Colang 流程或动作代码。

也就是说，Library 相当于官方维护的"护栏插件商店"：输入护栏、输出护栏、检索护栏、工具护栏、事实核查、敏感数据检测等常见能力，都已经以标准化的目录结构封装好，使用者只需在 YAML 配置中声明对应流程名即可启用。

从源码结构看，Library 的每个功能子目录都遵循统一的"四件套"布局，以nemoguardrails/library/regex/为例：

• rail.py：声明 Rail 的清单（Manifest），定义名称、方向、动作、绑定与文档地址；
• rail_config.py：定义该 Rail 的配置项与校验逻辑（build_config_spec）；
• actions.py：实现具体的动作函数（@action装饰器标记）；
• flows.co/flows.v1.co：提供 Colang v2 / v1 两种语法下的流程定义；
• __init__.py：模块初始化（Apache-2.0 许可证头）。

二、内置 Rail 目录总览

当前仓库的nemoguardrails/library/下包含 40 余个功能目录，覆盖了从通用能力到第三方服务接入的广泛场景：

其中部分目录还附带自己的README.md（如cleanlab、context_bloat_detection、llama_guard），详细介绍各自的能力与用法。

三、Rail 的标准化结构：rail.py 清单（Manifest）

每个内置 Rail 的核心是rail.py中导出的RAIL对象，它是一个RailManifest。以 regex 的 rail.py 为例，它声明了：

• name="regex"：Rail 注册名；
• metadata：展示名、描述、所属类别（input/output/retrieval/tool_output/tool_input）、能力（block/classify/moderate/transform）、标签以及文档地址docs/configure-rails/guardrail-catalog/community/regex.mdx；
• config_schema：配置键为regex_detection，指向rail_config.py中的build_config_spec；
• flows：公开流程名，如regex check input、regex check output、regex check retrieval、regex check tool output、regex check tool input；
• actions：动作引用，如detect_regex_pattern指向nemoguardrails.library.regex.actions:detect_regex_pattern；
• surfaces：声明每个流程方向的绑定关系（Binding.literal("source", "input")、Binding.context("text", "user_message")等）。

类似的，content_safety 的 rail.py 将content safety check input绑定到content_safety_check_input动作与user_message上下文，并通过Binding.model_param("model_name", "model")支持在激活时指定专门的审核模型；injection_detection 的 rail.py 则声明了输出方向的injection detection流程，并把yara-python标记为可选依赖。

这些 Manifest 是如何被框架发现的？答案是 manifests/catalog.py 中的RailCatalog.discover_built_ins()：它递归扫描nemoguardrails/library/下所有rail.py文件，将其按模块路径导入并读取RAIL对象，汇总成 Rail 目录（catalog）。因此，新增一个 Rail 的"最小签名"就是在其目录下提供定义RAIL的rail.py。

四、配置层面的激活方式

文档指出 Library 中的 Rail "can be activated in any config"。激活方式是在配置文件的rails.config下填写对应 Rail 的配置，并在rails.input/rails.output等段落引用其公开流程名。

以录制测试中最小的 regex_detection/config.yml 为例：

models: [] rails: config: regex_detection: input: patterns: - "SECRET-[0-9]+" output: patterns: - "INTERNAL-[A-Z]+" input: flows: - regex check input output: flows: - regex check output

其中regex_detection下的patterns就是 rail_config.py 中RegexDetectionOptions定义的配置项，还支持case_insensitive开关；框架会在配置加载时调用model_validator预编译所有正则，并在遇到非法正则时抛出ValueError。

而 full_stack/config.yml 展示了多 Rail 组合的"全家桶"配置：输入侧依次串联regex check input、self check input、jailbreak detection model、content safety check input $model=content_safety、topic safety check input $model=topic_control；输出侧串联regex check output、self check output、self check facts、content safety check output $model=content_safety。可见：

• 流程可以带$model=xxx参数，将某类任务绑定到配置文件中声明的专用模型（如nvidia/llama-3.1-nemoguard-8b-content-safety）；
• 多个护栏按声明顺序依次执行，达到组合防护效果；
• passthrough: true时主模型直接透传生成，便于录制测试断言护栏行为。

五、贡献一个新 Rail 的完整路径

根据 library/README.md 的要求，在nemoguardrails/library/<feature>/下新增 Rail 时，必须同时添加录制式端到端测试覆盖，以"钉住"（pin）该 Rail 的公开契约，并保证测试可以在没有外部服务的情况下回放。

结合仓库实际，一个完整的贡献流程通常包含以下步骤：

1. 创建功能目录：在nemoguardrails/library/<feature>/下新建__init__.py、rail.py、rail_config.py、actions.py与flows.co（如兼容 v1 还需flows.v1.co）。
2. 声明 Manifest：在rail.py中导出RAIL = RailManifest(...)，被 catalog.py 的discover_built_ins()自动发现。
3. 实现动作：在actions.py中用@action(is_system_action=True)装饰动作函数，返回RailOutcome.block/allow/transform等结果。例如 regex 的detect_regex_pattern会将匹配结果组装为RailOutcome.block(metadata=...)（actions.py）。
4. 添加录制测试：在tests/recorded/rails/library/下按行为归类新建测试模块。

六、录制式 e2e 测试规范详解

关联文档 tests/recorded/rails/library/README.md 对录制测试的约束非常明确，这是贡献新 Rail 时的硬性要求。

1. 按行为分组，不按功能混放

测试按行为（behavior）分组到对应模块：

• test_regex.py
• test_injection.py
• test_self_check.py
• test_content_safety.py
• test_topic_control.py
• test_jailbreak.py
• test_composition.py

此外仓库还包含test_f5_guardrails.py、test_iorails_parity.py等模块。新场景应直接加入拥有该行为的模块；共享代码只允许放在configs.py（配置常量）与helpers.py（执行辅助函数）中。

2. 使用正确的 API 形态

• 直接断言护栏判定时，使用check_async（见 helpers.py 中的check_rails，内部调用rails.check_async(messages, rail_types=...)）；
• 仅当被测行为确实涉及生成或流式输出时，才使用generate_async或stream_async；
• 输出护栏需要确定性主模型文本时，优先使用FakeLLMModel注入固定响应（generate_with_fake_main），或为流式场景提供流生成器（stream_with_fake_main中的async_chunks）。

3. 依赖外部提供商的测试走 VCR 录制

Provider 类测试使用 pytest-recording，默认 cassette 存放于：

tests/recorded/rails/library/cassettes/<test_module>/<test_name>.yaml

仓库中已录制的 cassette 覆盖了内容安全（含 Nemotron-3.5 系列）、越狱检测、话题控制、自我检查、组合执行顺序等多种场景，例如test_composition/test_input_jailbreak_runs_before_content_safety.yaml记录了"越狱检测先于内容安全执行"的组合行为。

4. 运行与刷新测试

# 运行（阻断网络，确保完全依赖录制回放） uv run pytest tests/recorded/rails/library --block-network -v # 刷新（重写 cassette，跳过 fake_cassette 场景） uv run pytest tests/recorded/rails/library --record-mode=rewrite -m "not fake_cassette" -v

第一条命令是 CI 式的验证路径：--block-network强制测试只能消费已有 cassette；第二条命令用于在 Rail 行为发生变化时重新录制，将新的真实调用结果写回 cassette。

5. 测试常量与配置集中管理

所有测试共享的配置常量集中在 configs.py，它通过RailsConfigSource.from_path(CONFIGS_DIR, "regex_detection")等加载configs/下的 YAML，并定义了JAILBREAK_PROMPT等标准攻击样本。测试配置目录tests/recorded/rails/library/configs/则提供了从最小regex_detection到openai_input_stack、openai_output_stack、full_stack、full_stack_no_topic以及各类 NIM 配置的完整样例，是编写新测试配置的最佳参照。

七、验证示例：regex Rail 的录制测试如何"钉住"契约

以 test_regex.py 为例，直观展示录制测试的形态：

async def test_regex_input_blocks_secret(): result = await check_rails( REGEX_CONFIG, [{"role": "user", "content": "my token is SECRET-1234"}], rail_types=(RailType.INPUT,), ) assert_rails_result(result, status=RailStatus.BLOCKED, rail="regex check input") assert normalize_rails_result(result) == snapshot( {"status": "blocked", "rail": "regex check input", "content": "I'm sorry, I can't respond to that."} )

它验证了：当用户消息命中SECRET-[0-9]+模式时，regex check input流程返回BLOCKED状态与标准拒绝文本；输出侧测试则验证机器人若生成INTERNAL-SECRET会被regex check output阻断。这类断言把 Rail 的公开行为以快照（snapshot）形式固定下来——这正是 README 所说"public contract is pinned and replayable"的具体落地。

八、小结

NeMo Guardrails Library 是官方预置护栏的集合：每个 Rail 以rail.pyManifest 为入口、由rail_config.py/actions.py/flows.co支撑实现，通过RailCatalog.discover_built_ins()自动发现，在任意配置中按流程名即可激活。对于想要向社区贡献新 Rail 的开发者，遵循tests/recorded/rails/library/的录制测试规范（按行为分组、check_async为主、Provider 调用走 VCR、--block-network验证）是让新 Rail 获得可回放契约保证的必备步骤。

进一步阅读：

• Library 主文档
• 录制测试规范
• Rail Manifest 与目录发现实现
• regex Rail 配置项定义
• 完整组合配置示例

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