إعداد وبنية Guardrails AI

Guardrails AI هو إطار عمل مفتوح المصدر يركز على التحقق من صحة المخرجات المنظمة والتصحيح التلقائي لتطبيقات LLM. يتفوق في ضمان أن ردود LLM تتوافق مع مخططات وقواعد عمل محددة.

التثبيت

pip install guardrails-ai

# تثبيت مدققات محددة من Guardrails Hub
guardrails hub install hub://guardrails/regex_match
guardrails hub install hub://guardrails/valid_length
guardrails hub install hub://guardrails/toxic_language

البنية الأساسية

┌─────────────────────────────────────────────────────────┐
│                    Guardrails AI                         │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │   Guard     │───▶│  المدققات  │───▶│   المخرج   │  │
│  │  (المخطط)  │    │  (سلسلة)   │    │  (مكتوب)   │  │
│  └─────────────┘    └─────────────┘    └─────────────┘  │
├─────────────────────────────────────────────────────────┤
│           ┌───────────────────────────┐                  │
│           │    إعادة السؤال/التصحيح  │                  │
│           │    (إعادة المحاولة)      │                  │
│           └───────────────────────────┘                  │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │  LiteLLM    │    │  OpenAI     │    │  Anthropic  │  │
│  │  Backend    │    │  Backend    │    │  Backend    │  │
│  └─────────────┘    └─────────────┘    └─────────────┘  │
└─────────────────────────────────────────────────────────┘

الاستخدام الأساسي

from guardrails import Guard
from guardrails.hub import ValidLength, ToxicLanguage
from pydantic import BaseModel, Field
from typing import List

# تعريف مخطط المخرجات
class ProductReview(BaseModel):
    summary: str = Field(
        description="ملخص موجز للمراجعة",
        json_schema_extra={"validators": [ValidLength(min=10, max=200)]}
    )
    sentiment: str = Field(
        description="المشاعر العامة: إيجابي أو سلبي أو محايد"
    )
    key_points: List[str] = Field(
        description="النقاط الرئيسية من المراجعة",
        json_schema_extra={"validators": [ValidLength(min=1, max=5, on_fail="fix")]}
    )

# إنشاء الحارس
guard = Guard.for_pydantic(ProductReview)

# التوليد مع التحقق
result = guard(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": "حلل هذه المراجعة: 'منتج رائع، شحن سريع، جودة ممتازة. سأشتري مرة أخرى!'"
    }]
)

# الوصول للمخرج المتحقق منه
print(result.validated_output)
# ProductReview(summary="...", sentiment="positive", key_points=["..."])

خيارات تكوين Guard

from guardrails import Guard, OnFailAction

guard = Guard.for_pydantic(ProductReview)

# تكوين السلوك عند فشل التحقق
guard = guard.use_many(
    ValidLength(min=10, max=200, on_fail=OnFailAction.FIX),
    ToxicLanguage(on_fail=OnFailAction.EXCEPTION)
)

# تكوين سلوك إعادة السؤال
result = guard(
    model="gpt-4o",
    messages=[...],
    num_reasks=3,  # إعادة المحاولة حتى 3 مرات عند فشل التحقق
    reask_prompt="المخرج غير صالح. يرجى الإصلاح: {error_message}"
)

إجراءات OnFail

الإجراء	السلوك
EXCEPTION	إثارة ValidationError
FIX	محاولة التصحيح التلقائي
REASK	طلب إعادة التوليد من LLM
FILTER	إزالة الحقل غير الصالح
REFRAIN	إرجاع None للحقل
NOOP	تسجيل تحذير، متابعة

Guard مع مدققات متعددة

from guardrails import Guard
from guardrails.hub import (
    ValidLength,
    RegexMatch,
    ToxicLanguage,
    ValidChoices
)
from pydantic import BaseModel, Field

class CustomerResponse(BaseModel):
    greeting: str = Field(
        json_schema_extra={
            "validators": [
                ValidLength(min=5, max=50),
                ToxicLanguage(threshold=0.5, on_fail="exception")
            ]
        }
    )
    response_type: str = Field(
        json_schema_extra={
            "validators": [
                ValidChoices(choices=["answer", "clarification", "escalation"])
            ]
        }
    )
    ticket_id: str = Field(
        json_schema_extra={
            "validators": [
                RegexMatch(regex=r"^TKT-\d{6}$", on_fail="fix")
            ]
        }
    )

guard = Guard.for_pydantic(CustomerResponse)

دعم البث

from guardrails import Guard

guard = Guard.for_pydantic(ProductReview)

# توليد البث مع التحقق
async for chunk in guard.stream(
    model="gpt-4o",
    messages=[{"role": "user", "content": "حلل هذه المراجعة..."}]
):
    if chunk.validated_output:
        print(chunk.validated_output)

التكامل مع استدعاءات LLM الموجودة

from guardrails import Guard
from openai import OpenAI

client = OpenAI()

# تغليف العميل الموجود
guard = Guard.for_pydantic(ProductReview)

@guard
def analyze_review(review_text: str) -> ProductReview:
    """Guardrails يغلف هذه الدالة."""
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "user", "content": f"حلل: {review_text}"}
        ]
    )
    return response.choices[0].message.content

# الاستدعاء مع التحقق التلقائي
result = analyze_review("منتج رائع!")

سجل التحقق

result = guard(
    model="gpt-4o",
    messages=[...],
    num_reasks=3
)

# الوصول لسجل التحقق
for call in result.call_log:
    print(f"المحاولة: {call.iteration}")
    print(f"المخرج الخام: {call.raw_output}")
    print(f"نجح التحقق: {call.validated_output is not None}")
    if call.error:
        print(f"الخطأ: {call.error}")

معالجة الأخطاء

from guardrails import Guard
from guardrails.errors import ValidationError

guard = Guard.for_pydantic(ProductReview)

try:
    result = guard(
        model="gpt-4o",
        messages=[...],
        num_reasks=3
    )

    if result.validated_output:
        process_review(result.validated_output)
    else:
        # فشلت جميع إعادات السؤال
        handle_validation_failure(result.raw_output)

except ValidationError as e:
    # المدقق أثار استثناء (on_fail="exception")
    log_validation_error(e)

نصيحة الإعداد: ابدأ بـ on_fail="fix" لمعظم المدققات أثناء التطوير، ثم شدد إلى "exception" للإنتاج حيث جودة البيانات حاسمة.

التالي: بناء مخططات معقدة مع مدققات Pydantic. :::