گاردریل‌ها در گدارAI

گاردریل (Guardrail) قاعده‌ای است که متن ورودی یا خروجی مدل را پیش از ادامه مسیر بررسی یا اصلاح می‌کند. با گاردریل‌ها می‌توانید جلوی ارسال داده حساس به مدل را بگیرید، پاسخ پرریسک را پیش از نمایش کنترل کنید، یا متن را به شکل امن‌تری به مسیر بعدی بفرستید.

گاردریل‌ها در مسیر Chat Completions اجرا می‌شوند و از سمت درخواست با سرآیند x-godarai-guardrails انتخاب می‌شوند. نتیجه هر اجرا در guardrail_checks و لاگ درخواست‌ها قابل پیگیری است.

اطلاع

Moderation و گاردریل‌ها نقش یکسانی ندارند. Moderation یک API مدل برای ارزیابی ایمنی محتواست؛ گاردریل‌ها لایه اعمال سیاست در گدارAI هستند و می‌توانند مسیر را متوقف کنند، نشانه‌گذاری کنند یا متن را تغییر دهند.

پیش‌نیازها

• یک توکن معتبر گدارAI داشته باشید.
• درخواست را به مسیر POST /v1/chat/completions بفرستید.
• برای گاردریل اختصاصی، گاردریل باید در فضای کاری شما ساخته و فعال شده باشد.
• شناسه فنی گاردریل را با قالب guardrails/<slug> بدانید.

شروع سریع

نمونه زیر گاردریل آماده guardrails/pii-redaction را روی ورودی مدل اجرا می‌کند تا داده شخصی پایه پیش از ارسال به مدل ماسک شود.

Python

import requests

response = requests.post(
  "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
  headers={
      "Authorization": "Bearer YOUR_GODARAI_TOKEN",
      "Content-Type": "application/json",
      "x-godarai-guardrails": '{"llm_input_guardrails":["guardrails/pii-redaction"]}',
  },
  json={
      "model": "openai:default:gpt-4o-mini",
      "messages": [
          {"role": "user", "content": "ایمیل من customer@company.ir است. لطفاً متن را خلاصه کن."}
      ],
  },
  timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions", {
method: "POST",
headers: {
  Authorization: "Bearer YOUR_GODARAI_TOKEN",
  "Content-Type": "application/json",
  "x-godarai-guardrails": JSON.stringify({ llm_input_guardrails: ["guardrails/pii-redaction"] }),
},
body: JSON.stringify({
  model: "openai:default:gpt-4o-mini",
  messages: [
    { role: "user", content: "ایمیل من customer@company.ir است. لطفاً متن را خلاصه کن." },
  ],
}),
});

if (!response.ok) {
throw new Error("Request failed with status " + response.status);
}

const data = await response.json();
console.log(data);

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions" --header "Authorization: Bearer YOUR_GODARAI_TOKEN" --header "Content-Type: application/json" --header 'x-godarai-guardrails: {"llm_input_guardrails":["guardrails/pii-redaction"]}' --data '{
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "ایمیل من customer@company.ir است. لطفاً متن را خلاصه کن."
    }
  ]
}'

اگر گاردریل تطابق پیدا کند، متن ورودی پیش از ارسال به ارائه‌دهنده مدل تغییر می‌کند. در لاگ درخواست‌ها، وضعیت اجرای گاردریل را با mutated می‌بینید.

نکته

برای اولین آزمایش، گاردریل را روی ورودی و با محدوده last اجرا کنید. این کار فقط آخرین پیام کاربر را بررسی می‌کند و اثر سیاست را ساده‌تر می‌توانید در لاگ درخواست‌ها ببینید.

گاردریل ورودی و خروجی

گاردریل‌ها در دو نقطه اجرا می‌شوند:

محل اجرا	زمان اجرا	کلید انتخاب
گاردریل ورودی	پیش از ارسال درخواست به ارائه‌دهنده مدل	llm_input_guardrails یا input_guardrails
گاردریل خروجی	پس از دریافت پاسخ کامل و پیش از تحویل به کاربر	llm_output_guardrails یا output_guardrails

گاردریل ورودی برای جلوگیری از نشت داده حساس، کنترل عبارت‌های پرریسک و اصلاح پرامپت مناسب است. گاردریل خروجی برای کنترل پاسخ مدل، جلوگیری از نمایش داده حساس و اعتبارسنجی خروجی کاربرد دارد.

هشدار

گاردریل خروجی به پاسخ کامل نیاز دارد. اگر درخواست شما stream: true داشته باشد، استفاده هم‌زمان از llm_output_guardrails با خطای 400 رد می‌شود.

نوع اقدام

رفتار اصلی هر گاردریل با «نوع اقدام» مشخص می‌شود:

عنوان UI	مقدار API	رفتار
اعتبارسنجی	validate	متن را بررسی می‌کند. اگر تخطی پیدا شود، بسته به «شیوه اعمال» مسیر ادامه پیدا می‌کند یا متوقف می‌شود.
اصلاح محتوا	mutate	متن را تغییر می‌دهد؛ برای نمونه، توکن یا ایمیل را با متن جایگزین ماسک می‌کند.

همه نوع‌های گاردریل هر دو نوع اقدام را پشتیبانی نمی‌کنند. در جدول نوع‌ها، مقدار مجاز هر گاردریل آمده است.

شیوه اعمال

«شیوه اعمال» تعیین می‌کند نتیجه گاردریل چه اثری روی مسیر درخواست یا پاسخ داشته باشد:

عنوان UI	مقدار API	رفتار
عبور همراه با نشانه‌گذاری	audit	تخطی را با وضعیت flagged ثبت می‌کند، اما مسیر را متوقف نمی‌کند.
عدم عبور و لاگ	enforce	تخطی را متوقف می‌کند و خطا برمی‌گرداند. اگر اجرای خود گاردریل خطا بدهد، مسیر هم متوقف می‌شود.
عدم عبور - بدون لاگ	enforce_ignore_error	تخطی را متوقف می‌کند، اما خطای اجرای خود گاردریل مانند enforce متوقف‌کننده نیست.

برای گاردریل‌هایی که «اصلاح محتوا» انجام می‌دهند، اگر متن تغییر کند، وضعیت mutated ثبت می‌شود و مسیر با متن اصلاح‌شده ادامه پیدا می‌کند.

نوع‌های پشتیبانی‌شده

در گدارAI این نوع‌های گاردریل قابل ساخت و استفاده هستند:

نوع	مقدار API	نوع اقدام قابل استفاده	راهنما
عبارت‌های مسدود	keyword_blocklist	فقط validate	عبارت‌های مسدود
Regex	regex	validate یا mutate	Regex
تشخیص Secret	secrets_detection	validate یا mutate	تشخیص Secret
PII پایه	basic_pii	validate یا mutate	PII پایه
جایگزینی با Regex	regex_replace	فقط mutate	جایگزینی با Regex
اعتبارسنجی JWT	jwt_validation	فقط validate	اعتبارسنجی JWT
تعداد جمله	sentence_count	فقط validate	تعداد جمله
تعداد کلمه	word_count	فقط validate	تعداد کلمه
تعداد کاراکتر	character_count	فقط validate	تعداد کاراکتر
JSON Schema	json_schema	فقط validate	JSON Schema
کلیدهای JSON	json_keys	فقط validate	کلیدهای JSON
تشخیص کد	contains_code	فقط validate	تشخیص کد
خالی نبودن	not_null	فقط validate	خالی نبودن
درون‌خطی‌سازی تصویر	inline_image_urls	فقط mutate	درون‌خطی‌سازی تصویر

برای جزئیات محل اجرا، پیام چندبخشی و پاسخ جریانی، قابلیت‌ها و محدوده پشتیبانی گاردریل‌ها را ببینید.

تعریف گاردریل اختصاصی

هر گاردریل اختصاصی با چند فیلد مشترک ساخته می‌شود. نمونه زیر داده شخصی پایه را پیش از ارسال پرامپت به مدل ماسک می‌کند:

{
  "slug": "mask-contact",
  "name": "ماسک‌کردن اطلاعات تماس",
  "description": "ایمیل و شماره تماس را پیش از ارسال به مدل ماسک می‌کند.",
  "type": "basic_pii",
  "operation": "mutate",
  "enforcement": "enforce",
  "enabled": true,
  "config": {
    "redaction_text": "[***]"
  }
}

فیلدهای مشترک:

فیلد	توضیح
slug	شناسه کوتاه گاردریل. شناسه فنی از همین مقدار ساخته می‌شود.
name	نام خوانا برای نمایش و بازبینی تیمی.
description	توضیح کوتاه درباره هدف گاردریل.
type	نوع گاردریل؛ مثل basic_pii یا keyword_blocklist.
operation	نوع اقدام؛ یکی از validate یا mutate.
enforcement	شیوه اعمال؛ یکی از audit، enforce یا enforce_ignore_error.
enabled	فقط گاردریل فعال در زمان درخواست قابل استفاده است.
config	تنظیمات اختصاصی همان نوع گاردریل.

شناسه‌ای که در درخواست می‌فرستید از slug ساخته می‌شود:

guardrails/mask-contact

انتخاب گاردریل در درخواست

برای اجرای گاردریل روی ورودی مدل:

x-godarai-guardrails: {"llm_input_guardrails":["guardrails/mask-contact"]}

برای اجرای گاردریل روی خروجی مدل:

x-godarai-guardrails: {"llm_output_guardrails":["guardrails/no-secrets"]}

برای سازگاری، کلیدهای input_guardrails و output_guardrails هم پذیرفته می‌شوند. اگر مقدار سرآیند را به شکل رشته ساده بفرستید، گدارAI آن را فهرست گاردریل‌های ورودی در نظر می‌گیرد:

x-godarai-guardrails: guardrails/pii-redaction, guardrails/secrets-detection

محدوده اجرای ورودی

سرآیند x-godarai-guardrails-scope فقط روی گاردریل‌های ورودی اثر دارد:

مقدار	رفتار
all	همه پیام‌های متنی انتخاب‌شده بررسی می‌شوند. مقدار پیش‌فرض است.
last	فقط آخرین پیام کاربر با نقش user بررسی می‌شود.

نمونه:

x-godarai-guardrails-scope: last

در پیام‌های چندبخشی، فقط بخش‌هایی با type: "text" بررسی یا اصلاح می‌شوند.

گاردریل‌های آماده

چند گاردریل آماده بدون ساخت گاردریل اختصاصی قابل استفاده‌اند:

شناسه فنی	رفتار پیش‌فرض
guardrails/keyword-blocklist	عبارت‌هایی مثل ignore previous instructions، jailbreak، rm -rf و drop table را مسدود می‌کند.
guardrails/regex	الگوهای رایج secret، token و password را با [REDACTED] ماسک می‌کند.
guardrails/secrets-detection	توکن‌ها، JWT، کلید خصوصی و چند قالب مقدار محرمانه رایج را ماسک می‌کند.
guardrails/basic-pii	داده شخصی پایه را با [REDACTED] ماسک می‌کند.
guardrails/pii-redaction	نام جایگزین برای guardrails/basic-pii.
guardrails/pii-detection	نام جایگزین برای guardrails/basic-pii.

نکته

برای محیط عملیاتی، معمولاً گاردریل اختصاصی بهتر از گاردریل آماده است؛ چون نام، هدف، تنظیمات، وضعیت فعال‌بودن و مالکیت آن برای تیم شما قابل بازبینی است.

پاسخ خطا و نتیجه اجرا

اگر گاردریل مسیر را متوقف کند، پاسخ با قالبی شبیه نمونه زیر برمی‌گردد:

{
  "error": {
    "message": "Request blocked by GodarAI guardrail",
    "type": "guardrail_checks_failed",
    "code": "guardrail_blocked"
  },
  "guardrail_checks": {
    "llm_input_guardrails": [
      {
        "selector": "guardrails/no-injection",
        "status": "blocked",
        "operation": "validate",
        "enforcement": "enforce",
        "reason": "Keyword blocklist matched",
        "latency_ms": 0
      }
    ]
  }
}

برای گاردریل خروجی، مقدار message برابر Response blocked by GodarAI guardrail است. نام انگلیسی محصول در این پیام خطا بخشی از قرارداد فنی پاسخ است و تغییر نمی‌کند.

وضعیت‌های رایج در guardrail_checks:

وضعیت	معنی
passed	گاردریل اجرا شد و تخطی یا تغییر پیدا نشد.
flagged	تخطی در حالت audit ثبت شد، اما مسیر متوقف نشد.
blocked	گاردریل مسیر را متوقف کرد.
mutated	متن تغییر کرد و مسیر با متن جدید ادامه پیدا کرد.
error	اجرای گاردریل یا انتخاب شناسه فنی با خطا روبه‌رو شد.

مشاهده‌پذیری

نتیجه هر بررسی در ردیابی درخواست و لاگ درخواست‌ها ثبت می‌شود. این داده‌ها شامل شناسه فنی، وضعیت، عملیات، شیوه اعمال، زمان اجرا، تغییر متن و علت هستند.

برای تحلیل عملیاتی، نتیجه گاردریل‌ها را کنار لاگ درخواست‌ها، ردیابی درخواست‌ها و OpenTelemetry بررسی کنید.

رفع مشکل‌های رایج

درخواست با خطای 400 رد می‌شود

اگر stream: true و llm_output_guardrails را هم‌زمان فرستاده‌اید، پاسخ جریانی را غیرفعال کنید یا گاردریل خروجی را حذف کنید.

پیام guardrails scope must be all or last می‌بینید

مقدار x-godarai-guardrails-scope فقط می‌تواند all یا last باشد. اگر این سرآیند را نفرستید، مقدار پیش‌فرض all است.

وضعیت error با علت Unknown guardrail selector ثبت می‌شود

شناسه فنی را بررسی کنید. مقدار باید با قالب guardrails/<slug> باشد و برای گاردریل اختصاصی، همان slug باید در فضای کاری شما فعال باشد.

از کجا شروع کنم؟

1. برای عبارت‌های ثابت و شناخته‌شده، عبارت‌های مسدود را بسازید.
2. برای الگوهای داخلی سازمان، Regex یا جایگزینی با Regex را انتخاب کنید.
3. برای توکن و کلید خصوصی، تشخیص Secret را فعال کنید.
4. برای ایمیل و شماره‌های رایج، PII پایه را ببینید.
5. برای شرط امنیتی مبتنی بر توکن، اعتبارسنجی JWT را بخوانید.
6. برای ساختار خروجی، JSON Schema و کلیدهای JSON را مقایسه کنید.