יצירת פלט מובנה (כמו JSON) באמצעות Gemini API

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

כדי לוודא שהפלט שנוצר על ידי המודל תמיד עומד בסכימה מסוימת, אפשר להגדיר סכימה של תגובה, שמשמשת כתוכנית לתשובות של המודל. לאחר מכן תוכלו לחלץ נתונים ישירות מהפלט של המודל עם פחות עיבוד נתונים לאחר העיבוד.

הנה כמה דוגמאות:

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

• הגבלת האופן שבו מודל יכול להגיב במשימות סיווג
  לדוגמה, אפשר להגדיר שהמודל יתווסף לטקסט הערות עם קבוצה ספציפית של תוויות (למשל, קבוצה ספציפית של ערכים מוגדרים מראש כמו positive ו-negative), במקום תוויות שהמודל יוצר (שיכולות להיות עם מידה מסוימת של השתנות, כמו good, ‏ positive, ‏ negative או bad).

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

בתחתית הדף הזה מפורטות דוגמאות נוספות, למשל איך ליצור ערכים של enum כפלט. כדי לראות דוגמאות נוספות ליצירת פלט מובנה, אפשר לעיין ברשימה של דוגמאות לסכימות ולתגובות של מודלים במסמכי התיעוד של Google Cloud.

אפשרויות אחרות לעבודה עם Gemini API

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

  אחרי שתתמצאו באופן שבו פועל Gemini API, תוכלו לעבור ל-Vertex AI in Firebase SDKs (המסמכים האלה), שיש בהם תכונות נוספות רבות שחשובות לאפליקציות לנייד ולאפליקציות אינטרנט, כמו הגנה על ה-API מפני ניצול לרעה באמצעות Firebase App Check ותמיכה בבקשות עם קובצי מדיה גדולים.

• אפשר גם להפעיל את Vertex AI Gemini API בצד השרת (למשל באמצעות Python,‏ Node.js או Go)
  . משתמשים בערכות ה-SDK של Vertex AI בצד השרת, ב-Firebase Genkit או ב-Firebase Extensions עבור Gemini API.

לפני שמתחילים

אם עדיין לא עשיתם זאת, כדאי לעיין במדריך למתחילים בנושא ערכות ה-SDK של Vertex AI in Firebase. חשוב לוודא שכל הפעולות הבאות בוצעו:

1. מגדירים פרויקט Firebase חדש או קיים, כולל שימוש בתוכנית התמחור Blaze והפעלת ממשקי ה-API הנדרשים.

2. מקשרים את האפליקציה ל-Firebase, כולל רישום האפליקציה והוספת הגדרות Firebase לאפליקציה.

3. מוסיפים את ה-SDK ומפעילים את השירות Vertex AI ואת המודל הגנרטיבי באפליקציה.

אחרי שמחברים את האפליקציה ל-Firebase, מוסיפים את ה-SDK ומפעילים את השירות Vertex AI ואת המודל הגנרטיבי, אפשר לבצע קריאה ל-Gemini API.

שלב 1: מגדירים סכימה של תגובה

מגדירים סכימה של תגובה כדי לציין את המבנה של הפלט של המודל, את שמות השדות ואת סוג הנתונים הצפוי לכל שדה.

כשמודל יוצר את התשובה שלו, הוא משתמש בשם השדה ובהקשר מההנחיה. כדי שהכוונה שלכם תהיה ברורה, מומלץ להשתמש במבנה ברור, בשמות שדות ברורים ואפילו בתיאורים לפי הצורך.

שיקולים לגבי סכימות תגובה

כשכותבים את הסכימה של התשובה, חשוב לזכור את הדברים הבאים:

• הגודל של הסכימה של התשובה נספר במסגרת המגבלה על אסימוני הקלט.

• התכונה response schema תומכת בסוגי ה-MIME הבאים של תגובות:

  • application/json: פלט JSON כפי שמוגדר בסכימת התגובה (שימושי לדרישות של פלט מובנה)

  • text/x.enum: הפלט הוא ערך enum כפי שמוגדר בסכימת התגובה (שימושי למשימות סיווג)

• התכונה 'סכימה של תגובה' תומכת בשדות הסכימה הבאים:

  enum items

  maxItems nullable

  properties required

  אם משתמשים בשדה שלא נתמך, המודל עדיין יכול לטפל בבקשה, אבל הוא מתעלם מהשדה. הערה: הרשימה שלמעלה היא קבוצת משנה של אובייקט הסכימה של OpenAPI 3.0 (ראו חומר העזר בנושא סכימות של Vertex AI).

• כברירת מחדל, ב-SDKs של Vertex AI in Firebase, כל השדות נחשבים חובה, אלא אם מציינים אותם כאופציונליים במערך optionalProperties. בשדות האופציונליים האלה, המודל יכול לאכלס את השדות או לדלג עליהם.

  לתשומת ליבכם: זוהי התנהגות הפוכה להתנהגות ברירת המחדל של Vertex AI Gemini API.

שלב 2: שולחים הנחיה עם סכימה של תגובה כדי ליצור JSON

הדוגמה הבאה מראה איך ליצור פלט JSON מובנה.

כדי ליצור פלט מובנה, צריך לציין במהלך האתחול של המודל את responseMimeType המתאים (בדוגמאות האלה, application/json) ואת responseSchema שבו רוצים שהמודל ישתמש.

אפשר להשתמש ב-responseSchema ב-Gemini 1.5 Pro וב-Gemini 1.5 Flash.

כאן מוסבר איך בוחרים מודל Gemini, ואם רוצים גם מיקום שמתאים לאפליקציה ולתרחיש השימוש.

דוגמאות נוספות

דוגמאות נוספות לשימוש בפלט מובנה ויצירתו מפורטות ברשימה של דוגמאות לסכימות ותשובות של מודלים במסמכי התיעוד של Google Cloud.

יצירת ערכי enum כפלט

בדוגמה הבאה מוסבר איך משתמשים בסכימת תגובה למשימות סיווג. המודל מתבקש לזהות את הז'אנר של סרט על סמך התיאור שלו. הפלט הוא ערך enum אחד בטקסט ללא סימון (plain text) שהמודל בוחר מתוך רשימה של ערכים שמוגדרים בסכימת התגובה שצוינה.

כדי לבצע את המשימה הזו של סיווג מובנה, צריך לציין במהלך האינטוליזציה של המודל את responseMimeType המתאים (בדוגמה הזו, text/x.enum) ואת responseSchema שבו רוצים שהמודל ישתמש.

כאן מוסבר איך בוחרים מודל Gemini, ואם רוצים גם מיקום שמתאים לאפליקציה ולתרחיש השימוש.

אפשרויות נוספות לשליטה ביצירת תוכן

• מידע נוסף על עיצוב הנחיות כדי שתוכלו להשפיע על המודל וליצור פלט ספציפי לצרכים שלכם.
• מגדירים פרמטרים של מודל כדי לקבוע איך המודל ייצור תשובה. הפרמטרים האלה כוללים את מספר האסימונים המקסימלי בפלט, הטמפרטורה, topK ו-topP.
• אתם יכולים להשתמש בהגדרות הבטיחות כדי לשנות את הסבירות לקבלת תשובות שעשויות להיחשב כפוגעניות, כולל דברי שטנה ותוכן מיני בוטה.
• מגדירים הוראות מערכת כדי להשפיע על התנהגות המודל. התכונה הזו היא כמו 'מבוא' שמוסיפים לפני שהמודל נחשף להוראות נוספות ממשתמש הקצה.

שליחת משוב על חוויית השימוש ב-Vertex AI in Firebase