כברירת מחדל, הפונקציה Gemini API מחזירה תשובות כטקסט לא מובנה. עם זאת, בחלק מתרחישי השימוש נדרשים טקסטים מובְנים, כמו JSON. לדוגמה, יכול להיות שאתם משתמשים בתגובה למשימות אחרות במורד הזרם שדורשות סכימה מוגדרת של נתונים.
כדי לוודא שהפלט שנוצר על ידי המודל תמיד עומד בסכימה מסוימת, אפשר להגדיר סכימה של תגובה, שעובדת כמו תוכנית עבודה לתשובות של המודל. לאחר מכן תוכלו לחלץ נתונים ישירות מהפלט של המודל עם פחות עיבוד נתונים לאחר העיבוד.
הנה כמה דוגמאות:
מוודאים שהתגובה של המודל יוצרת קובץ JSON תקין ועומדת בדרישות הסכימה שסיפקתם.
לדוגמה, המודל יכול ליצור רשומות מובנות של מתכונים, שכוללות תמיד את שם המתכון, רשימת המצרכים והשלבים. כך תוכלו לנתח את המידע הזה בקלות רבה יותר ולהציג אותו בממשק המשתמש של האפליקציה.הגבלת האופן שבו מודל יכול להגיב במשימות סיווג
לדוגמה, אפשר להגדיר שהמודל יתווסף לטקסט הערות עם קבוצה ספציפית של תוויות (למשל, קבוצה ספציפית של ערכים מוגדרים מראש כמוpositive
ו-negative
), במקום תוויות שהמודל יוצר (שיכולות להיות עם מידה מסוימת של וריאציה, כמוgood
, positive
, negative
אוbad
).
במדריך הזה מוסבר איך ליצור פלט JSON על ידי העברת responseSchema
בקריאה ל-generateContent
. הוא מתמקד בקלט של טקסט בלבד, אבל Gemini יכול גם ליצור תשובות מובנות לבקשות מולטימודליות שכוללות תמונות, סרטונים ואודיו כקלט.
בתחתית הדף הזה מפורטות דוגמאות נוספות, למשל איך ליצור ערכים של 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. חשוב לוודא שכל הפעולות הבאות בוצעו:
מגדירים פרויקט Firebase חדש או קיים, כולל שימוש בחבילת התמחור Blaze והפעלה של ממשקי ה-API הנדרשים.
קישור האפליקציה ל-Firebase, כולל רישום האפליקציה והוספת הגדרות Firebase לאפליקציה.
מוסיפים את ה-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 (למעט דגמי Gemini 1.0).
import FirebaseVertexAI
// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
let jsonSchema = Schema.object(
properties: [
"characters": Schema.array(
items: .object(
properties: [
"name": .string(),
"age": .integer(),
"species": .string(),
"accessory": .enumeration(values: ["hat", "belt", "shoes"]),
],
optionalProperties: ["accessory"]
)
),
]
)
// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
modelName: "gemini-2.0-flash",
// In the generation config, set the `responseMimeType` to `application/json`
// and pass the JSON schema object into `responseSchema`.
generationConfig: GenerationConfig(
responseMIMEType: "application/json",
responseSchema: jsonSchema
)
)
let prompt = "For use in a children's card game, generate 10 animal-based characters."
let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")
כאן מוסבר איך בוחרים מודל, ואם רוצים גם מיקום, שמתאימים לתרחיש לדוגמה ולאפליקציה.
דוגמאות נוספות
דוגמאות נוספות לשימוש בפלט מובנה ויצירתו מפורטות ברשימה של דוגמאות לסכימות ולתשובות של מודלים במסמכי התיעוד של Google Cloud.
יצירת ערכי enum כפלט
בדוגמה הבאה מוסבר איך משתמשים בסכימת תגובה למשימות סיווג. המודל מתבקש לזהות את הז'אנר של סרט על סמך התיאור שלו. הפלט הוא ערך enum אחד בטקסט ללא סימון (plain text) שהמודל בוחר מתוך רשימה של ערכים שמוגדרים בסכימת התגובה שצוינה.
כדי לבצע את המשימה הזו של סיווג מובנה, צריך לציין במהלך האינטוליזציה של המודל את responseMimeType
המתאים (בדוגמה הזו, text/x.enum
) ואת responseSchema
שבו רוצים שהמודל ישתמש.
import FirebaseVertexAI
// Provide an enum schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
let enumSchema = Schema.enumeration(values: ["drama", "comedy", "documentary"])
// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
modelName: "gemini-2.0-flash",
// In the generation config, set the `responseMimeType` to `text/x.enum`
// and pass the enum schema object into `responseSchema`.
generationConfig: GenerationConfig(
responseMIMEType: "text/x.enum",
responseSchema: enumSchema
)
)
let prompt = """
The film aims to educate and inform viewers about real-life subjects, events, or people.
It offers a factual record of a particular topic by combining interviews, historical footage,
and narration. The primary purpose of a film is to present information and provide insights
into various aspects of reality.
"""
let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")
כאן מוסבר איך בוחרים מודל, ואם רוצים גם מיקום, שמתאימים לתרחיש לדוגמה ולאפליקציה.
אפשרויות נוספות לשליטה ביצירת תוכן
- מידע נוסף על עיצוב הנחיות כדי שתוכלו להשפיע על המודל כך שיניב פלט ספציפי לצרכים שלכם.
- מגדירים פרמטרים של מודל כדי לקבוע איך המודל ייצור תשובה. במודלים מסוג Gemini, הפרמטרים האלה כוללים את מספר האסימונים המקסימלי בפלט, הטמפרטורה, topK ו-topP. במודלים מסוג Imagen, האפשרויות האלה כוללות יחס גובה-רוחב, יצירת אנשים, הוספת סימני מים וכו'.
- אתם יכולים להשתמש בהגדרות הבטיחות כדי לשנות את הסבירות לקבלת תשובות שעשויות להיחשב כפוגעניות, כולל דברי שטנה ותוכן מיני בוטה.
- מגדירים הוראות מערכת כדי להשפיע על התנהגות המודל. התכונה הזו היא כמו 'מבוא' שמוסיפים לפני שהמודל נחשף להוראות נוספות ממשתמש הקצה.
שליחת משוב על חוויית השימוש ב-Vertex AI in Firebase