با Gemini API خروجی ساختاریافته تولید کنید


Gemini به طور پیش فرض متن بدون ساختار تولید می کند، اما برخی از برنامه ها به متن ساختاریافته نیاز دارند. برای این موارد استفاده، می‌توانید Gemini را محدود کنید تا با JSON، یک قالب داده ساختاریافته مناسب برای پردازش خودکار، پاسخ دهد. همچنین می توانید مدل را محدود کنید تا با یکی از گزینه های مشخص شده در enum پاسخ دهد.

در اینجا چند مورد استفاده وجود دارد که ممکن است به خروجی ساختاریافته از مدل نیاز داشته باشد:

  • با بیرون کشیدن اطلاعات شرکت از مقالات روزنامه، پایگاه داده ای از شرکت ها بسازید.
  • اطلاعات استاندارد شده را از رزومه خارج کنید.
  • مواد تشکیل دهنده را از دستور العمل ها استخراج کنید و پیوندی به یک وب سایت خواربار فروشی برای هر عنصر نمایش دهید.

در درخواست خود، می توانید از Gemini بخواهید خروجی با فرمت JSON تولید کند، اما توجه داشته باشید که این مدل تضمینی برای تولید JSON و چیزی جز JSON ندارد. برای پاسخ قطعی تر، می توانید یک طرح JSON خاص را در یک فیلد responseSchema ارسال کنید تا Gemini همیشه با ساختار مورد انتظار پاسخ دهد. برای کسب اطلاعات بیشتر در مورد کار با طرحواره ها، بیشتر در مورد طرحواره های JSON را ببینید.

این راهنما به شما نشان می دهد که چگونه با استفاده از روش generateContent از طریق SDK انتخابی خود یا با استفاده مستقیم از REST API، JSON تولید کنید. مثال‌ها فقط ورودی متنی را نشان می‌دهند، اگرچه Gemini همچنین می‌تواند پاسخ‌های JSON را به درخواست‌های چندوجهی که شامل تصاویر ، ویدیوها و صدا می‌شود، تولید کند.

اطلاعات بیشتر در مورد طرحواره های JSON

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

در اینجا یک نمایش شبه JSON از تمام فیلدهای Schema آمده است: 

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

Type طرحواره باید یکی از انواع داده های OpenAPI باشد. فقط یک زیر مجموعه از فیلدها برای هر Type معتبر است. لیست زیر هر Type به فیلدهای معتبر برای آن نوع نگاشت می کند:

  • string -> enum, format
  • integer -> قالب
  • number -> قالب
  • boolean
  • array -> minItems، maxItems، آیتم ها
  • object -> خواص، مورد نیاز، propertyOrdering، nullable

در اینجا چند نمونه طرحواره وجود دارد که ترکیبات نوع و فیلد معتبر را نشان می دهد: 

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "boolean" }

{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }

{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  },
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
}

برای مستندات کامل فیلدهای Schema همانطور که در Gemini API استفاده می شود، به مرجع Schema مراجعه کنید.

سفارش ملک

هنگامی که با طرحواره های JSON در Gemini API کار می کنید، ترتیب ویژگی ها مهم است. به‌طور پیش‌فرض، API ویژگی‌ها را بر اساس حروف الفبا مرتب می‌کند و ترتیب تعریف ویژگی‌ها را حفظ نمی‌کند (اگرچه Google Gen AI SDKs ممکن است این ترتیب را حفظ کند). اگر در حال ارائه مثال‌هایی برای مدل با طرح‌واره‌ای پیکربندی‌شده هستید، و ترتیب ویژگی‌های نمونه‌ها با ترتیب ویژگی‌های طرح سازگار نیست، خروجی می‌تواند نامشخص یا غیرمنتظره باشد.

برای اطمینان از یک ترتیب ثابت و قابل پیش‌بینی خواص، می‌توانید از فیلد اختیاری propertyOrdering[] استفاده کنید. 

"propertyOrdering": ["recipe_name", "ingredients"]

propertyOrdering[] - یک فیلد استاندارد در مشخصات OpenAPI نیست - آرایه ای از رشته ها است که برای تعیین ترتیب خواص در پاسخ استفاده می شود. با مشخص کردن ترتیب ویژگی ها و سپس ارائه مثال هایی با ویژگی ها به همان ترتیب، به طور بالقوه می توانید کیفیت نتایج را بهبود بخشید.