יצירת פלט מובנה בעזרת Gemini API


Gemini יוצר טקסט לא מובנה כברירת מחדל, אבל יש אפליקציות שדורשות טקסט מובנה. בתרחישי השימוש האלה, אפשר להגביל את Gemini כך שתגיב באמצעות JSON, פורמט של נתונים מובְנים שמתאים לעיבוד אוטומטי. אפשר גם להגביל את המודל כך שיגיב באחת מהאפשרויות שצוינו ב-enum.

הנה כמה תרחישים לדוגמה שבהם יכול להיות שתצטרכו פלט מובנה מהמודל:

  • איך יוצרים מסד נתונים של חברות על ידי אחזור פרטי חברות ממאמרים בעיתונים.
  • אחזור מידע סטנדרטי קובצי קורות חיים.
  • לחלץ מרכיבים מתכונים ולהציג קישור לאתר מכולת לכל מרכיב.

בהנחיה, אפשר לבקש מ-Gemini ליצור פלט בפורמט JSON, אבל חשוב לזכור שלא בטוח שהמודל ייצור JSON ולא משהו אחר. כדי לקבל תשובה ודאית יותר, אפשר להעביר סכימה ספציפית של JSON בשדה responseSchema כדי ש-Gemini תמיד יגיב במבנה צפוי. למידע נוסף על עבודה עם סכימות, ראו מידע נוסף על סכימות JSON.

במדריך הזה נסביר איך ליצור קובץ JSON באמצעות השיטה generateContent דרך ה-SDK שבחרתם, או באמצעות ה-API ל-REST ישירות. בדוגמאות מוצג קלט של טקסט בלבד, אבל Gemini יכול גם ליצור תגובות JSON לבקשות עם מגוון מודלים שכוללות תמונות, סרטונים ואודיו.

מידע נוסף על סכימות JSON

כשמגדירים את המודל להחזרת תגובה בפורמט JSON, אפשר להשתמש באובייקט Schema כדי להגדיר את הצורה של נתוני ה-JSON. השדה Schema מייצג קבוצת משנה נבחרת של אובייקט הסכימה של OpenAPI 3.0.

זהו ייצוג פסאודו-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 -> format
  • number -> format
  • boolean
  • array -> minItems, ‏ maxItems, ‏ items
  • object -> properties, required, 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 מפורט מידע מלא על שדות ה-Schema כפי שהם משמשים ב-Gemini API.

סדר הנכסים

כשעובדים עם סכימות JSON ב-Gemini API, חשוב לשים לב לסדר המאפיינים. כברירת מחדל, ה-API מסדר את המאפיינים לפי סדר אלפביתי ולא שומר על הסדר שבו המאפיינים מוגדרים (אבל ערכות ה-SDK של Google Gen AI עשויות לשמור על הסדר הזה). אם אתם מספקים דוגמאות למודל עם סכימה מוגדרת, והסדר של המאפיינים בדוגמאות לא תואם לסדר של המאפיינים בסכימה, הפלט עשוי להיות לא ברור או לא צפוי.

כדי להבטיח סדר עקבי וצפוי של המאפיינים, אפשר להשתמש בשדה האופציונלי propertyOrdering[].

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

השדה propertyOrdering[] – שהוא לא שדה רגיל במפרט OpenAPI – הוא מערך של מחרוזות שמשמשות לקביעת סדר המאפיינים בתגובה. אם מציינים את הסדר של הנכסים ומספקים דוגמאות עם נכסים באותו סדר, אפשר לשפר את איכות התוצאות.