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

کلیدهای JSON

گاردریل json_keys بررسی می‌کند یک متن، شیء JSON معتبر باشد و کلیدهای سطح اول آن با شرطی که تعریف کرده‌اید سازگار باشد. این نوع برای زمانی مناسب است که سیاست شما درباره نام کلیدهاست، نه نوع یا مقدار آن‌ها.

اطلاع

json_keys سبک‌تر از JSON Schema است. اگر فقط می‌خواهید مطمئن شوید پاسخ فیلدهایی مثل answer و sources دارد، معمولاً همین گاردریل کافی است.

چه زمانی استفاده کنید؟​

از json_keys برای این سناریوها استفاده کنید:

  • همه فیلدهای اصلی پاسخ باید وجود داشته باشند.
  • حداقل یکی از چند فیلد اختیاری باید وجود داشته باشد.
  • کلیدهای داخلی مثل debug، internal_notes یا raw_prompt نباید در پاسخ نهایی دیده شوند.

اگر نوع فیلدها، مقدارها یا ساختار پیچیده‌تر مهم است، از JSON Schema استفاده کنید.

رفتار اجرایی​

این نوع فقط از «اعتبارسنجی» (operation: "validate") پشتیبانی می‌کند. کل متن باید یک شیء JSON معتبر باشد. آرایه، مقدار ساده، متن ترکیبی یا JSON داخل بلوک کد رد می‌شود.

«نحوه بررسی کلیدها» یکی از حالت‌های زیر است:

عنوان UIمقدار APIشرط قبولی
همه کلیدهاallهمه کلیدهای واردشده در سطح اول وجود داشته باشند. مقدار پیش‌فرض است.
حداقل یکیanyحداقل یکی از کلیدهای واردشده وجود داشته باشد.
هیچ‌کدامnoneهیچ‌کدام از کلیدهای واردشده وجود نداشته باشند.

تنظیمات​

عنوان UIمقدار APIتوضیح
کلیدهاkeysهر خط یک نام کلید است. دست‌کم یک کلید لازم است.
نحوه بررسی کلیدهاmodeیکی از مقدارهای all، any یا none.
نکته

برای سیاست‌های ممنوعیت کلید، از mode: "none" استفاده کنید. این الگو برای جلوگیری از برگشت فیلدهای داخلی، مثل debug، خواناتر از نوشتن یک schema پیچیده است.

نمونه تعریف​

نمونه زیر فقط وقتی پاسخ را می‌پذیرد که هر دو کلید answer و sources در سطح اول وجود داشته باشند:

{
  "slug": "public-answer-keys",
  "name": "Public answer keys",
  "type": "json_keys",
  "operation": "validate",
  "enforcement": "enforce",
  "enabled": true,
  "config": {
    "keys": ["answer", "sources"],
    "mode": "all"
  }
}

برای منع کلیدهای داخلی:

{
  "slug": "no-internal-json-keys",
  "name": "No internal JSON keys",
  "type": "json_keys",
  "operation": "validate",
  "enforcement": "enforce",
  "enabled": true,
  "config": {
    "keys": ["internal_notes", "debug"],
    "mode": "none"
  }
}

نمونه استفاده​

x-godarai-guardrails: {"llm_output_guardrails":["guardrails/public-answer-keys"]}
هشدار

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

بررسی نتیجه​

اگر متن JSON معتبر نباشد، علت Response is not valid JSON ثبت می‌شود. اگر شرط کلیدها برقرار نباشد، علت JSON keys validation failed ثبت می‌شود.

با «عدم عبور و لاگ»، پاسخ یا درخواست متوقف می‌شود. با «عبور همراه با نشانه‌گذاری»، وضعیت flagged ثبت می‌شود و مسیر ادامه پیدا می‌کند.

محدودیت‌ها​

  • فقط کلیدهای سطح اول بررسی می‌شوند. مقدارهایی مثل user.email مسیر تودرتو محسوب نمی‌شوند.
  • مقدار و نوع کلید بررسی نمی‌شود.
  • نام کلیدها به بزرگی و کوچکی حروف حساس است.
  • هر متن انتخاب‌شده جداگانه باید شیء JSON معتبر باشد.

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

آیا می‌توانم کلیدهای تودرتو را بررسی کنم؟​

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

اگر مقدار کلید خالی باشد چه می‌شود؟​

json_keys فقط وجود کلید را بررسی می‌کند. برای الزام مقدار غیرخالی، طراحی schema یا اعتبارسنجی سمت اپلیکیشن لازم است.

گام بعدی​