sim/apps/docs/content/docs/zh/blocks/guardrails.mdx

---
title: Guardrails
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Image } from '@/components/ui/image'
import { Video } from '@/components/ui/video'

Guardrails 模块通过针对多种验证类型检查内容，验证并保护您的 AI 工作流。在内容进入工作流之前，确保数据质量、防止幻觉、检测 PII（个人身份信息）并强制执行格式要求。

<div className="flex justify-center">
  <Image
    src="/static/blocks/guardrails.png"
    alt="防护栏块"
    width={500}
    height={400}
    className="my-6"
  />
</div>

## 验证类型

### JSON 验证

验证内容是否为正确格式的 JSON。这是确保结构化 LLM 输出可以安全解析的理想方法。

**使用场景：**
- 在解析之前验证 Agent 块的 JSON 响应
- 确保 API 负载格式正确
- 检查结构化数据的完整性

**输出：**
- `passed`：如果是有效的 JSON，则为 `true`，否则为 `false`
- `error`：如果验证失败，则为错误消息（例如，“无效的 JSON：意外的标记...”）

### 正则表达式验证

检查内容是否符合指定的正则表达式模式。

**使用场景：**
- 验证电子邮件地址
- 检查电话号码格式
- 验证 URL 或自定义标识符
- 强制执行特定的文本模式

**配置：**
- **正则表达式模式**：要匹配的正则表达式（例如，`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$` 用于电子邮件）

**输出：**
- `passed`：如果内容匹配模式，则为 `true`，否则为 `false`
- `error`：如果验证失败，则为错误消息

### 幻觉检测

使用基于检索增强生成 (RAG) 的 LLM 评分来检测 AI 生成的内容是否与您的知识库相矛盾或不基于事实。

**工作原理：**
1. 查询您的知识库以获取相关上下文
2. 将 AI 输出和检索到的上下文发送到 LLM
3. LLM 分配一个置信评分（0-10 分制）
   - **0** = 完全幻觉（完全没有依据）
   - **10** = 完全基于事实（完全由知识库支持）
4. 如果评分 ≥ 阈值（默认值：3），验证通过

**配置：**
- **知识库**：从现有知识库中选择
- **模型**：选择用于评分的 LLM（需要强推理能力 - 推荐 GPT-4o、Claude 3.7 Sonnet）
- **API 密钥**：所选 LLM 提供商的身份验证（对于托管/Ollama 或 VLLM 兼容模型会自动隐藏）
- **置信度阈值**：通过的最低分数（0-10，默认值：3）
- **Top K**（高级）：要检索的知识库块数量（默认值：10）

**输出：**
- `passed`：如果置信度分数 ≥ 阈值，则为 `true`
- `score`：置信度分数（0-10）
- `reasoning`：LLM 对分数的解释
- `error`：验证失败时的错误信息

**用例：**
- 根据文档验证代理的回复
- 确保客户支持回答事实准确
- 验证生成的内容是否与源材料匹配
- RAG 应用的质量控制

### PII 检测

使用 Microsoft Presidio 检测个人身份信息。支持 40 多种实体类型，覆盖多个国家和语言。

<div className="flex justify-center">
  <Image
    src="/static/blocks/guardrails-2.png"
    alt="PII 检测配置"
    width={700}
    height={450}
    className="my-6"
  />
</div>

**工作原理：**
1. 提交要验证的内容（例如，`<agent1.content>`）
2. 使用模态选择器选择要检测的 PII 类型
3. 选择检测模式（检测或屏蔽）
4. 扫描内容以匹配 PII 实体
5. 返回检测结果，并可选择返回屏蔽后的文本

<div className="mx-auto w-3/5 overflow-hidden rounded-lg">
  <Video src="guardrails.mp4" width={500} height={350} />
</div>

**配置：**
- **要检测的 PII 类型**：通过模态选择器从分组类别中选择
  - **常见**：姓名、电子邮件、电话、信用卡、IP 地址等
  - **美国**：社会安全号码、驾照、护照等
  - **英国**：NHS 编号、国家保险号码
  - **西班牙**：NIF、NIE、CIF
  - **意大利**：税号、驾照、增值税号
  - **波兰**：PESEL、NIP、REGON
  - **新加坡**：NRIC/FIN、UEN
  - **澳大利亚**：ABN、ACN、TFN、Medicare
  - **印度**：Aadhaar、PAN、护照、选民编号
- **模式**：
  - **检测**：仅识别 PII（默认）
  - **屏蔽**：将检测到的 PII 替换为屏蔽值
- **语言**：检测语言（默认：英语）

**输出：**
- `passed`：如果检测到任何选定的 PII 类型，则为 `false`
- `detectedEntities`：包含类型、位置和置信度的检测到的 PII 数组
- `maskedText`：屏蔽 PII 的内容（仅当模式为 "屏蔽" 时）
- `error`：验证失败时的错误信息

**使用场景：**
- 阻止包含敏感个人信息的内容
- 在记录或存储数据之前屏蔽 PII
- 符合 GDPR 和其他隐私法规
- 在处理之前清理用户输入

## 配置

### 要验证的内容

要验证的输入内容。通常来源于：
- Agent 块的输出：`<agent.content>`
- Function 块的结果：`<function.output>`
- API 响应：`<api.output>`
- 任何其他块的输出

### 验证类型

从以下四种验证类型中选择：
- **有效 JSON**：检查内容是否为正确格式的 JSON
- **正则表达式匹配**：验证内容是否匹配正则表达式模式
- **幻觉检查**：通过 LLM 评分与知识库进行验证
- **PII 检测**：检测并可选择屏蔽个人身份信息

## 输出

所有验证类型返回：

- **`<guardrails.passed>`**：布尔值，指示验证是否通过
- **`<guardrails.validationType>`**：执行的验证类型
- **`<guardrails.input>`**：被验证的原始输入
- **`<guardrails.error>`**：如果验证失败，返回错误信息（可选）

按类型的额外输出：

**幻觉检查：**
- **`<guardrails.score>`**：置信分数（0-10）
- **`<guardrails.reasoning>`**：LLM 的解释

**PII 检测：**
- **`<guardrails.detectedEntities>`**：检测到的 PII 实体数组
- **`<guardrails.maskedText>`**：屏蔽 PII 后的内容（如果模式为 "Mask"）

## 示例使用场景

**在解析之前验证 JSON** - 确保 Agent 输出为有效的 JSON

```
Agent (Generate) → Guardrails (Validate) → Condition (Check passed) → Function (Parse)
```

**防止幻觉** - 验证客户支持响应是否符合知识库

```
Agent (Response) → Guardrails (Check KB) → Condition (Score ≥ 3) → Send or Flag
```

**阻止用户输入中的 PII** - 清理用户提交的内容

```
Input → Guardrails (Detect PII) → Condition (No PII) → Process or Reject
```

## 最佳实践

- **与条件块链式使用**：使用 `<guardrails.passed>` 根据验证结果分支工作流逻辑
- **在解析之前使用 JSON 验证**：在尝试解析 LLM 输出之前始终验证 JSON 结构
- **选择合适的 PII 类型**：仅选择与您的使用场景相关的 PII 实体类型以提高性能
- **设置合理的置信阈值**：对于幻觉检测，根据您的准确性要求调整阈值（值越高越严格）
- **使用强大的模型进行幻觉检测**：GPT-4o 或 Claude 3.7 Sonnet 提供更准确的置信评分
- **为日志记录屏蔽 PII**：当需要记录或存储可能包含 PII 的内容时，使用 "Mask" 模式
- **测试正则表达式模式**：在生产环境部署之前彻底验证您的正则表达式模式
- **监控验证失败**：跟踪 `<guardrails.error>` 消息以识别常见的验证问题

<Callout type="info">
  Guardrails 验证会在您的工作流程中同步进行。对于幻觉检测，如果延迟至关重要，请选择更快的模型（例如 GPT-4o-mini）。
</Callout>