پرش به مطلب اصلی
جستجو

قابلیت‌ها و محدوده پشتیبانی گاردریل‌ها

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

اطلاع

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

محل اجرا​

گاردریل‌ها در مسیر درگاه گدارAI اجرا می‌شوند:

  • گاردریل ورودی پیش از ارسال درخواست به ارائه‌دهنده مدل اجرا می‌شود.
  • گاردریل خروجی پس از دریافت پاسخ کامل و پیش از تحویل پاسخ به کلاینت اجرا می‌شود.

این قابلیت برای مسیر زیر قابل استفاده است:

POST /v1/chat/completions

برای مسیرهای دیگر، مثل Responses، Messages، Embeddings، تصویر یا صوت، فقط وقتی از همین سرآیندها استفاده کنید که در مستندات همان مسیر پشتیبانی آن صریحاً آمده باشد.

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

محل اجرازمان اجراکلید انتخاب در x-godarai-guardrailsکاربرد رایج
گاردریل ورودیپیش از تماس با ارائه‌دهنده مدلllm_input_guardrails یا input_guardrailsماسک‌کردن داده حساس، کنترل تزریق پرامپت، اعتبارسنجی متن کاربر
گاردریل خروجیپس از پاسخ کامل مدلllm_output_guardrails یا output_guardrailsکنترل پاسخ نهایی، جلوگیری از نمایش داده حساس، اعتبارسنجی ساختار خروجی

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

هشدار

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

متن قابل بررسی​

گاردریل‌ها متن را از این بخش‌ها استخراج می‌کنند:

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

اگر چند پیام یا چند بخش متنی انتخاب شود، هر متن جداگانه بررسی می‌شود. برای نمونه، در گاردریل «تعداد کلمه»، مجموع کلمه‌های همه پیام‌ها ملاک نیست؛ هر بخش متنی جدا ارزیابی می‌شود.

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

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

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

نمونه:

x-godarai-guardrails-scope: last

اگر مقدار دیگری بفرستید، درخواست با پیام guardrails scope must be all or last رد می‌شود.

نکته

برای چت‌های چندپیامی، last معمولاً شروع امن‌تری است؛ چون سیاست را روی پیام تازه کاربر اعمال می‌کند و تاریخچه مکالمه را کمتر درگیر تغییر ناخواسته می‌کند.

شناسه فنی گاردریل​

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

guardrails/<slug>

نمونه:

guardrails/mask-contact

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

  • guardrails/keyword-blocklist
  • guardrails/regex
  • guardrails/secrets-detection
  • guardrails/basic-pii
  • guardrails/pii-redaction
  • guardrails/pii-detection

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

عملیات و شیوه اعمال​

هر گاردریل دو تصمیم مهم دارد:

تصمیممقدارهای رایجاثر
نوع اقدامvalidate یا mutateمشخص می‌کند گاردریل فقط بررسی کند یا متن را تغییر دهد.
شیوه اعمالaudit، enforce، enforce_ignore_errorمشخص می‌کند تخطی فقط ثبت شود یا مسیر را متوقف کند.

نوع گاردریل تعیین می‌کند کدام نوع اقدام مجاز است. برای نمونه، keyword_blocklist فقط validate را می‌پذیرد، اما regex می‌تواند هم validate و هم mutate باشد.

بررسی نتیجه​

نتیجه اجرای گاردریل در guardrail_checks و لاگ درخواست‌ها قابل مشاهده است:

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

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

پرسش‌های پرتکرار​

آیا گاردریل‌ها روی همه APIهای گدارAI کار می‌کنند؟​

خیر. این سرآیندها برای POST /v1/chat/completions استفاده می‌شوند. برای مسیرهای دیگر، به مستندات همان مسیر تکیه کنید.

آیا تصویرهای پیام چندبخشی بررسی می‌شوند؟​

خیر. فقط بخش‌های متنی بررسی یا اصلاح می‌شوند. برای تبدیل URL تصویر داخل متن به data URL، درون‌خطی‌سازی تصویر را ببینید.

آیا می‌توانم گاردریل خروجی را با پاسخ جریانی فعال کنم؟​

خیر. گاردریل خروجی فقط برای پاسخ غیرجریانی پشتیبانی می‌شود.

اگر شناسه فنی اشتباه باشد چه می‌شود؟​

در نتیجه بررسی، وضعیت error با علت Unknown guardrail selector ثبت می‌شود. مقدار را با قالب guardrails/<slug> بررسی کنید و مطمئن شوید گاردریل اختصاصی شما فعال است.

گام بعدی​