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

JSON Schema

گاردریل json_schema متن انتخاب‌شده را به‌عنوان JSON می‌خواند و بررسی می‌کند با ساختاری که در schema تعریف کرده‌اید سازگار باشد. این گاردریل برای مسیرهایی مناسب است که پاسخ مدل قرار است مستقیماً در محصول شما پردازش شود؛ برای نمونه پاسخ پشتیبانی، نتیجه استخراج داده یا خروجی قابل ذخیره در پایگاه داده.

اطلاع

این گاردریل جایگزین طراحی خوب response_format نیست. معمولاً بهترین نتیجه وقتی به دست می‌آید که ابتدا در درخواست مدل از خروجی ساخت‌یافته استفاده کنید و سپس با json_schema در گدارAI نتیجه نهایی را کنترل کنید.

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

از json_schema وقتی استفاده کنید که:

  • پاسخ باید JSON معتبر باشد و متن توضیحی کنار آن پذیرفته نشود.
  • ریشه پاسخ باید نوع مشخصی مثل شیء یا آرایه باشد.
  • چند کلید اصلی باید حتماً وجود داشته باشند.
  • نوع فیلدهای مستقیم، مثل رشته، عدد یا بولین، مهم است.

اگر فقط می‌خواهید وجود یا نبودن چند کلید سطح اول را بررسی کنید، کلیدهای JSON ساده‌تر است.

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

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

بخش پشتیبانی‌شده از JSON Schema محدود و قابل پیش‌بینی است:

کلیدرفتار پشتیبانی‌شده
typeنوع مقدار ریشه: object، array، string، number، integer، boolean یا null.
requiredوجود کلیدهای لازم در شیء سطح اول.
properties.<key>.typeنوع فیلدهای مستقیم شیء سطح اول، فقط وقتی آن فیلد وجود دارد.
هشدار

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

تنظیمات​

عنوان UIمقدار APIتوضیح
JSON Schemaschemaشیء JSON غیرخالی که ساختار مورد انتظار را تعریف می‌کند.

نمونه تعریف​

نمونه زیر پاسخ را به یک شیء JSON با دو فیلد answer و confidence محدود می‌کند:

{
  "slug": "answer-schema",
  "name": "Structured answer schema",
  "type": "json_schema",
  "operation": "validate",
  "enforcement": "enforce",
  "enabled": true,
  "config": {
    "schema": {
      "type": "object",
      "required": ["answer", "confidence"],
      "properties": {
        "answer": {"type": "string"},
        "confidence": {"type": "number"}
      }
    }
  }
}

پس از ذخیره، شناسه فنی این گاردریل guardrails/answer-schema است.

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

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

x-godarai-guardrails: {"llm_output_guardrails":["guardrails/answer-schema"]}

پاسخ زیر پذیرفته می‌شود:

{"answer":"تهران","confidence":0.98}

اما پاسخ زیر رد می‌شود، چون متن توضیحی قبل از JSON دارد:

نتیجه:
{"answer":"تهران","confidence":0.98}
نکته

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

بررسی نتیجه​

نتیجه اجرا در guardrail_checks و گزارش رخدادها دیده می‌شود:

وضعیتعلت رایج
passedمتن JSON معتبر است و با بخش پشتیبانی‌شده از schema سازگار است.
blocked یا flaggedمتن JSON معتبر نیست یا با schema سازگار نیست.

علت‌های رایج:

  • Response is not valid JSON
  • JSON schema validation failed

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

محدودیت‌ها​

  • هر متن انتخاب‌شده جداگانه بررسی می‌شود؛ چند پیام با هم یک JSON واحد ساخته نمی‌شوند.
  • نوع ناشناخته در schema باعث ردشدن مقدار نمی‌شود؛ فقط نوع‌های پشتیبانی‌شده را به کار ببرید.
  • هر choice خروجی باید جداگانه JSON کامل و معتبر باشد.
  • گاردریل خروجی با پاسخ جریانی پشتیبانی نمی‌شود.

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

آیا این گاردریل خروجی مدل را به JSON تبدیل می‌کند؟​

خیر. فقط اعتبارسنجی می‌کند. برای کمک به تولید JSON، از خروجی ساخت‌یافته یا پرامپت دقیق استفاده کنید.

اگر فقط چند کلید لازم دارم، همین صفحه کافی است؟​

می‌توانید از json_schema استفاده کنید، اما کلیدهای JSON برای این نیاز ساده‌تر و خواناتر است.

گام بعدی​