- 人工智能
- 大模型
- AI 安全治理
- 模型安全
- 内容安全
- 提示词注入防护
- RAG
【免费下载链接】Guardrails
NeMo Guardrails is an open-source toolkit for easily adding programmable guardrails to LLM-based conversational systems.
本指南以 NeMo Guardrails 仓库中的examples/configs/clavata示例为主线，系统讲解如何将 Clavata 内容审核 API 接入 NeMo Guardrails，对 LLM 对话系统的用户输入（input）与机器人输出（output）进行基于策略的自动审核与拦截。读完本文，你将掌握该示例的完整配置语义、nemoguardrails chat快速验证方式，以及从 Colang 流到 Clavata HTTP 客户端调用的底层实现链路，可直接据此搭建自己的 Clavata 守卫配置。
一、示例概览：Clavata 集成做了什么
Clavata 是一个内容审核（content moderation）服务，允许用户创建自定义审核策略（policy），并为每条策略关联若干"标签/分段"（label/section），用于对文本进行威胁、毒性、仇恨言论等维度的分类判定。NeMo Guardrails 将 Clavata 作为内置的第三方守卫（rail）集成，支持在对话的输入侧和输出侧分别调用 Clavata API，依据策略结果对交互放行或拦截。
仓库中该示例的全部内容位于 examples/configs/clavata，目录结构如下：
README.md—— 集成示例说明（即本文所依托的文档主体）；config.yml—— 存放 Clavata 集成所需的全部配置选项。
示例的目标场景非常直观：用户消息经过Threats（威胁）策略审核，机器人回复经过Toxicity（毒性）策略审核，命中策略即阻断交互。同时示例还展示了如何通过labels参数把命中判定收窄到指定标签（如Hate Speech、Self-Harm），而不是一刀切地依据整个策略结果。
二、快速开始：用 CLI Chat 验证配置
在安装好 NeMo Guardrails 并设置好环境的前提下，从examples/configs/clavata目录执行以下命令即可启动命令行对话测试：
nemoguardrails chat命令会加载当前目录下的config.yml，启动一个可交互的聊天会话：输入任意文本后，NeMo Guardrails 会先运行 input 守卫调用 Clavata 审核你的输入；LLM 生成回复后，再运行 output 守卫审核回复内容。一旦命中策略，对话会被阻断，机器人会回复预设的拒绝话术（如 "I cannot respond to that request."）。
注意：该配置示例针对colang 1.0编写（
config.yml首行注释明确标注 "Example for colang 1.0"）。示例模型使用gpt-3.5-turbo-instruct（OpenAI 引擎），实际运行时需按你自己的模型提供方调整models段。
三、配置文件逐项解析
config.yml 是本次集成的核心，全文如下：
# Example for colang 1.0 models: - type: main engine: openai model: gpt-3.5-turbo-instruct rails: config: clavata: policies: Threats: 00000000-0000-0000-0000-000000000000 Toxicity: 00000000-0000-0000-0000-000000000000 # With colang 1.0, we can't pass parameters to flows, so we need to specify the policy to use # in the input and output rails. input: policy: Threats output: policy: Toxicity # You can specify labels to match against as part of the input/output rail configuration labels: - Hate Speech - Self-Harm input: flows: - clavata check input output: flows: - clavata check output3.1models：LLM 主模型
与 NeMo Guardrails 常规配置一致，指定对话主模型。示例使用 OpenAI 引擎的gpt-3.5-turbo-instruct。Clavata 守卫本身并不消耗 LLM 调用，模型仅用于生成对话回复；若只想验证守卫逻辑，可以替换为本地或自建推理端点。
3.2rails.config.clavata：Clavata 集成配置
这是守卫的核心配置块，按源码 rail_config.py 中的ClavataRailConfig模型，支持以下字段：
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
server_endpoint | string | https://gateway.app.clavata.ai:8443 | Clavata API 端点地址，一般无需修改 |
policies | map（别名 → 策略 ID） | {} | 策略别名到策略 UUID 的映射表，供配置与流中按别名引用 |
label_match_logic | "ANY"/"ALL" | "ANY" | 标签命中判定逻辑：ANY表示命中任一配置标签即判定为匹配；ALL表示必须全部命中才判定为匹配 |
input | 对象 | None | 输入守卫的 Clavata 选项（ClavataRailOptions） |
output | 对象 | None | 输出守卫的 Clavata 选项（ClavataRailOptions） |
其中input/output各自对应 ClavataRailOptions：
| 字段 | 类型 | 说明 |
|---|---|---|
policy | string | 评估输入/输出时使用的策略别名（需在policies中定义，或直接传 UUID） |
labels | list[string] | 要匹配的标签列表；不提供时返回整体策略结果，提供后仅命中指定标签才算命中 |
示例中的关键用法：
policies中定义了两个策略别名Threats与Toxicity，各映射到一个策略 UUID（示例中使用全零占位符00000000-0000-0000-0000-000000000000，实际部署时必须替换为你在 Clavata 控制台创建的真实策略 ID）。input.policy: Threats—— 输入侧使用威胁策略；注释明确指出：colang 1.0 无法向 flow 传参，因此策略必须在 input/output 配置中显式指定。output.policy: Toxicity且labels: [Hate Speech, Self-Harm]—— 输出侧使用毒性策略，且只在该策略的这两个标签命中时才判定为匹配。
3.3rails.input.flows/rails.output.flows：绑定守卫流
input: flows: - clavata check input output: flows: - clavata check output这两段把内置 Colang 流clavata check input和clavata check output分别挂载到输入守卫与输出守卫。流的定义位于 flows.co（colang 2.x 语法，仓库同时提供了 flows.v1.co 供 colang 1.0 使用），两个流分别调用ClavataCheckAction(text=$user_message, rail="input")与ClavataCheckAction(text=$bot_message, rail="output")，通过rail参数从配置中取对应侧的策略与标签。
四、标签匹配与判定逻辑：从配置到行为
labels与label_match_logic的组合决定了"命中"的精确语义，这一点在源码 actions.py 中有清晰实现：
get_labels()（actions.py）：若 action 调用时传入了labels，则直接使用（字符串会被按逗号拆分）；否则从config.<rail>.labels读取。is_label_match()（actions.py）：将 Clavata 返回的各分段报告（section report）中result == "OUTCOME_TRUE"的标签收集为labels_matched，再与配置的待匹配标签集合求交集：label_match_logic == "ALL"：要求待匹配标签全部出现在命中集合中；- 默认
"ANY"：只要任一待匹配标签被命中即判定为匹配。
- 判定结果：最终通过
_clavata_outcome()（actions.py）返回RailOutcome.block(...)（命中即拦截）或RailOutcome.allow(...)（放行），并附带{"policy_matched": ...}元数据供日志与可观测性使用。
配置层面对应的行为推演：
- 若
output.labels为空，则只要Toxicity策略整体判定OUTCOME_TRUE，输出即被拦截； - 若按示例配置了
labels: [Hate Speech, Self-Harm]，则只有这两个标签之一（ANY模式）命中才拦截，其余标签的命中不影响判定。
五、底层原理：守卫到 Clavata API 的调用链
5.1 策略 ID 解析
action 的policy参数既支持直接传 UUID，也支持传别名。源码get_policy_id()（actions.py）按以下顺序解析：
- 若未传
policy但传了rail，则从config.<rail>.policy取策略别名； - 尝试把传入值解析为
uuid.UUID，成功则直接使用； - 否则在
config.policies字典中按别名查找策略 ID；若别名不存在抛ClavataPluginValueError；若找到的 ID 不是合法 UUID，则抛出更友好的ClavataPluginConfigurationError，提示检查 Clavata 配置。
因此，实际生产配置中把00000000-...占位符替换为真实 UUID 后，policies段就变成了"别名 → 真实 UUID"的干净映射，后续配置与调试都只和别名打交道。
5.2 HTTP 调用与重试
Clavata 的通信封装在 request.py 的ClavataClient中：
- 认证：请求头
Authorization: Bearer <api_key>，API Key 优先取构造参数，否则读环境变量CLAVATA_API_KEY；两者皆无时抛出ClavataPluginConfigurationError（见 request.py）。因此运行前必须设置：
export CLAVATA_API_KEY=<你的 Clavata API Key>- 请求体：
JobRequest包含content_data（待审核文本列表）、policy_id以及wait_for_completion=True，即同步等待 Clavata 完成审核作业（request.py）。 - 端点：向
{server_endpoint}/v1/jobs发起POST（request.py）。 - 重试策略：
_CLAVATA_RETRY_POLICY（request.py）定义最多 3 次尝试、仅对POST且状态码429（限流）重试、初始延迟 0.1 秒、最大延迟 10 秒——对限流有内置的退避保护。 - 状态处理：作业状态为
JOB_STATUS_FAILED/JOB_STATUS_CANCELED时标记失败；非JOB_STATUS_COMPLETED时抛ClavataPluginAPIError；仅接受单条内容对应的单一报告（Expected 1 report per job），见PolicyResult.from_job()（actions.py）。
5.3 拦截行为与异常模式
流定义 flows.co 展示了命中后的两种处理路径：
- 默认路径：
bot refuse to respond并abort——机器人拒绝回复，交互终止； - 异常路径：当
$system.config.enable_rails_exceptions（colang 2.x）或$config.enable_rails_exceptions（colang 1.0）开启时，发送ClavataPolicyMatchException(message=...)事件，把拦截转交给应用层的异常处理机制，便于上层以编程方式捕获并自定义后续行为。
从源码结构看，该守卫的可插拔能力通过 RailManifest 统一注册：rail.py 声明了clavata check for/clavata check input/clavata check output三个流名、ClavataCheckAction动作、输入输出 surface 绑定、CLAVATA_API_KEY环境变量要求，以及隐私声明（sends_user_text=True, sends_bot_text=True, remote_services=("Clavata API",)）——即用户与机器人文本会被发送到 Clavata 远程服务，涉及敏感数据的场景需要评估合规要求。
六、测试验证与自定义扩展
仓库测试 tests/test_clavata.py 使用RecordingHTTPClient模拟 Clavata API 响应，覆盖了"无活跃策略时放行"（test_clavata_no_active_policy_check）、命中拦截、异常事件等场景，可作为理解动作行为与编写自测的参考：
- 通过
monkeypatch.setenv("CLAVATA_API_KEY", "")模拟缺失/空 Key 的场景； - 通过
add_clavata_response()注入构造好的CreateJobResponse（含Report、SectionReport、Result等模型，见 request.py），从而在不真正联网的情况下验证判定逻辑。
若你需要在示例基础上扩展，可从以下方向入手：
- 替换真实策略 ID：把
config.yml中policies的占位 UUID 换成 Clavata 控制台创建的真实策略，并设置CLAVATA_API_KEY环境变量； - 调整标签判定：为
input/output增加或精简labels，并按需把label_match_logic改为ALL收紧判定； - 新增策略侧：仿照示例在
policies中追加别名与 ID，再为input/output切换policy； - 开启异常模式：启用
enable_rails_exceptions，让命中拦截以ClavataPolicyMatchException事件形式暴露给上层应用处理，而非默认的机器人拒绝话术。
七、最佳实践与注意事项
- 务必先设置
CLAVATA_API_KEY：缺失时会分别在客户端构造与请求头生成阶段抛出ClavataPluginConfigurationError，报错信息会明确提示该环境变量未设置。 - 策略 ID 必须为合法 UUID：
policies中映射到非 UUID 值时，get_policy_id()会抛出专门的配置错误；调试时优先用别名，减少 UUID 散落各处的维护成本。 - 理解标签判定语义：不配
labels时依据策略整体结果，配置后仅按ANY/ALL逻辑收窄判定，二者行为差异明显，请结合审核需求选择。 - 评估数据出境：Clavata 属于远程第三方服务，用户输入与机器人输出都会发送至该 API（见 rail.py 的隐私声明），涉及 PII 或敏感业务数据时需先完成合规评估。
- 限流有内置退避：客户端对 429 响应自动重试（最多 3 次），无需自行处理；高并发场景仍建议结合自身流量评估 Clavata 配额。
综上，examples/configs/clavata示例以最小配置演示了"输入威胁审核 + 输出毒性审核"的完整闭环：从 config.yml 的策略别名映射与 input/output 流绑定，到 actions.py 的标签判定，再到 request.py 的带重试 HTTP 调用，任何一个环节都可以按上文的参数与源码线索做进一步定制，快速落地为生产可用的 Clavata 内容安全防线。
- 人工智能
- 大模型
- AI 安全治理
- 模型安全
- 内容安全
- 提示词注入防护
- RAG
【免费下载链接】Guardrails
NeMo Guardrails is an open-source toolkit for easily adding programmable guardrails to LLM-based conversational systems.
相关推荐
在 NeMo Guardrails 中集成 Clavata 内容审核：colang v2.x 配置实战与 Policy/Label 匹配机制解析
在 NeMo Guardrails 中集成 Clavata 内容审核：colang v2.x 配置实战与 Policy/Label 匹配机制解析 本文基于 Ne
人工智能大模型AI 安全治理模型安全内容安全提示词注入防护RAG在 NeMo Guardrails 中集成 Llama Guard：基于 vLLM 的输入输出内容审核实战
在 NeMo Guardrails 中集成 Llama Guard：基于 vLLM 的输入输出内容审核实战 本文围绕 examples/configs/llam
人工智能大模型AI 安全治理模型安全内容安全提示词注入防护RAGCivitai 基于 Clavata 的用户生成文本内容审核系统：架构、配置与实战指南
Civitai 基于 Clavata 的用户生成文本内容审核系统：架构、配置与实战指南 本文档基于 docs/features/text moderation
后端前端AI 应用
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
