Guardrails

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

验证类型

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 多种实体类型，覆盖多个国家和语言。

工作原理：

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

配置：

• 要检测的 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、HIPAA 和其他隐私法规
• 在处理之前清理用户输入

配置

要验证的内容

要验证的输入内容。通常来源于：

• 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> 消息以识别常见的验证问题