Guardrails项目自定义验证器开发指南

最新推荐文章于 2025-06-09 09:01:11 发布

余印榕

最新推荐文章于 2025-06-09 09:01:11 发布

阅读量338

点赞数 4

本文链接：https://blog.csdn.net/gitblog_00683/article/details/148507868

版权

Guardrails项目自定义验证器开发指南

guardrails Adding guardrails to large language models. 项目地址: https://gitcode.com/gh_mirrors/gu/guardrails

前言

在现代软件开发中，数据验证是确保系统健壮性和安全性的关键环节。Guardrails项目提供了一套强大的验证框架，允许开发者创建自定义验证器来处理特定的业务需求。本文将深入探讨如何在Guardrails项目中开发自定义验证器，从基础实现到高级应用场景。

自定义验证器基础

函数式验证器

对于简单的验证需求，可以使用函数式验证器。这种方式适合不需要额外参数且逻辑简单的验证场景。

from typing import Dict
from guardrails.validators import (
    FailResult,
    PassResult,
    register_validator,
    ValidationResult,
)

@register_validator(name="toxic-words", data_type="string")
def toxic_words(value, metadata: Dict) -> ValidationResult:
    """检查文本中是否包含不当词汇"""
    banned_words = ["butt", "poop", "booger"]
    found_words = [word for word in banned_words if word in value]

    if found_words:
        return FailResult(
            error_message=f"检测到不当词汇: {', '.join(found_words)}",
        )
    return PassResult()

这种实现方式简洁明了，适合快速实现简单的验证逻辑。

类式验证器

当验证逻辑需要更复杂的配置或状态管理时，推荐使用类式验证器。这种方式提供了更好的封装性和扩展性。

from typing import Callable, Dict, Optional, List
from guardrails.validators import Validator, register_validator

@register_validator(name="toxic-words", data_type="string")
class ToxicWords(Validator):
    def __init__(self, search_words: List[str] = None, on_fail: Optional[Callable] = None):
        super().__init__(on_fail=on_fail)
        self.search_words = search_words or ["booger", "butt"]

    def _validate(self, value: str, metadata: Dict) -> ValidationResult:
        found_words = [word for word in self.search_words if word in value]
        
        if found_words:
            return FailResult(
                error_message=f"检测到不当词汇: {', '.join(found_words)}",
            )
        return PassResult()

类式验证器的主要优势在于：

可以维护内部状态
支持更复杂的初始化参数
便于扩展和复用

高级验证功能

验证失败处理

Guardrails提供了灵活的验证失败处理机制，开发者可以指定不同的失败处理策略。

@register_validator(name="toxic-words", data_type="string")
class ToxicWords(Validator):
    def __init__(self, search_words: List[str] = None, on_fail: Optional[Callable] = None):
        super().__init__(on_fail=on_fail)
        self.search_words = search_words or ["booger", "butt"]

    def _validate(self, value: str, metadata: Dict) -> ValidationResult:
        found_words = [word for word in self.search_words if word in value]
        
        if found_words:
            # 自动过滤不当词汇
            fixed_value = ' '.join([w for w in value.split() if w not in self.search_words])
            return FailResult(
                error_message=f"检测到不当词汇: {', '.join(found_words)}",
                fix_value=fixed_value
            )
        return PassResult()

这种自动修复功能特别适合在交互式应用中使用，可以自动修正用户输入中的问题。

集成机器学习模型

Guardrails验证器可以轻松集成各种机器学习模型，实现复杂的语义验证。

from transformers import pipeline

@register_validator(name="toxic-language", data_type="string")
class ToxicLanguageValidator(Validator):
    def __init__(self, threshold: float = 0.9, model_name: str = "unitary/toxic-bert"):
        super().__init__()
        self.threshold = threshold
        self.classifier = pipeline("text-classification", model=model_name)

    def _validate(self, value: str, metadata: Dict) -> ValidationResult:
        result = self.classifier(value)[0]
        if result['label'] == 'toxic' and result['score'] > self.threshold:
            return FailResult(
                error_message=f"文本毒性评分过高: {result['score']}"
            )
        return PassResult()

这种验证器可以检测文本中的潜在有害内容，适用于内容审核等场景。

流式数据处理

对于实时数据流，Guardrails提供了流式验证支持。

@register_validator(name="stream-validator", data_type="string")
class StreamValidator(Validator):
    def _chunking_function(self, chunk: str) -> List[str]:
        """自定义数据分块策略"""
        if "\n\n" not in chunk:
            return []
        fragments = chunk.split("\n\n")
        return [fragments[0] + "\n\n", "\n\n".join(fragments[1:])]
    
    def _validate(self, value: str, metadata: Dict) -> ValidationResult:
        # 验证逻辑
        return PassResult()

这种流式处理能力特别适合实时聊天、日志监控等场景。

实际应用示例

在Pydantic模型中使用

from pydantic import BaseModel, Field
from guardrails import Guard

class UserContent(BaseModel):
    comment: str = Field(validators=[ToxicWords(search_words=["bad", "inappropriate"])])
    bio: str = Field(validators=[ToxicLanguageValidator(threshold=0.7)])

guard = Guard.for_pydantic(UserContent)

在RAIL规范中使用

<rail version="0.1">
<output>
    <string name="user_comment" validators="toxic-words:search_words=bad|inappropriate" />
    <string name="user_bio" validators="toxic-language:threshold=0.7" />
</output>
</rail>