אתם יכולים להבטיח שהפלט שהמודל יוצר תמיד יתאים לסכימה ספציפית, כדי שתקבלו תשובות בפורמט עקבי. לדוגמה, יכול להיות שיש לכם סכימת נתונים קבועה שאתם משתמשים בה למשימות אחרות. אם המודל פועל לפי אותה סכימה, אתם יכולים לחלץ נתונים ישירות מהפלט של המודל בלי עיבוד נוסף.
כדי לציין את המבנה של פלט המודל, מגדירים סכֵימת תשובה, שפועלת כמו תוכנית לתשובות של המודל. כששולחים הנחיה וכוללים את סכמת התשובה, התשובה של המודל תמיד תואמת לסכמה שהגדרתם.
אתם יכולים לשלוט בפלט שנוצר כשאתם משתמשים במודלים הבאים:
- מודלים של Gemini:
לחצו כדי להרחיב את רשימת המודלים הנתמכים
- Gemini Robotics ER 2
- Gemini 4 Hydrogen
- Gemini 4 Carbon לסייבר
- Gemini 4 Carbon
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Flash Cyber
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
- Gemini 3 Flash
- Gemini 2.5 Pro
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash
מודלים פתוחים:
במודלים פתוחים, פועלים לפי המדריך למשתמש הזה.
תרחישים לדוגמה
תרחיש לדוגמה שבו כדאי להשתמש בסכמת תשובה הוא כשרוצים לוודא שהתשובה של המודל תהיה בפורמט JSON תקין ותתאים לסכימה. הפלט מהמודל הגנרטיבי יכול להשתנות במידה מסוימת, ולכן הכללת סכֵימת תשובה מבטיחה שתמיד תקבלו קובץ JSON תקין. כתוצאה מכך, המשימות הבאות בתהליך יכולות לצפות לקבל קלט JSON תקין מהתשובות שנוצרו.
דוגמה נוספת היא להגביל את האופן שבו המודל יכול להגיב. לדוגמה, אתם יכולים להגדיר למודל להוסיף הערות לטקסט עם תוויות שהמשתמש מגדיר, ולא עם תוויות שהמודל מייצר. האילוץ הזה שימושי כשמצפים לקבל קבוצה ספציפית של תוויות, כמו positive או negative, ולא רוצים לקבל שילוב של תוויות אחרות שהמודל עשוי ליצור, כמו good, positive, negative או bad.
לתשומת ליבכם
אם אתם מתכננים להשתמש בסכֵימת תשובה, כדאי להביא בחשבון את המגבלות הפוטנציאליות הבאות:
- כדי להגדיר סכֵימת תשובה ולהשתמש בה, צריך להשתמש ב-API. אין תמיכה בקונסולות.
- גודל סכמת התשובה נכלל במגבלת הטוקנים של הקלט.
יש תמיכה רק בפורמטים מסוימים של פלט, כמו
application/jsonאוtext/x.enum. לגבי פלט JSON:- אם מגדירים את
response_mime_typeל-application/jsonבלי לצייןresponse_schema, זה משמש רק כרמז חזק, ויש סיכון קטן ליצירת JSON בפורמט שגוי. - כדי להבטיח שאובייקטים של JSON יהיו תקינים ב-100%, הבקשות חייבות לכלול גם
response_schemaוגםresponse_mime_typeשמוגדרים ל-application/json. - כשיטה מומלצת, אם תרחיש השימוש שלכם מונע מכם להגדיר מראש סכימה, הטמיעו מאמת JSON בצד הלקוח עם מנגנון ניסיון חוזר.
- אם מגדירים את
פלט מובנה תומך בקבוצת משנה של הסכימה של Gemini Enterprise Agent Platform. מידע נוסף זמין במאמר שדות סכימה נתמכים.
סכימה מורכבת עלולה לגרום לשגיאת
InvalidArgument: 400. המורכבות יכולה לנבוע משמות ארוכים של מאפיינים, מגבלות ארוכות על אורך המערך, ערכים מרובים של enum, אובייקטים עם הרבה מאפיינים אופציונליים או שילוב של הגורמים האלה.אם קיבלתם את השגיאה הזו עם סכימה תקינה, נסו לבצע אחד או יותר מהשינויים הבאים כדי לפתור את השגיאה:
- מקצרים את שמות המאפיינים או את שמות ה-enum.
- השטחת מערכים בתוך מערכים.
- צמצמו את מספר המאפיינים עם אילוצים, כמו מספרים עם מגבלות מינימום ומקסימום.
- צמצמו את מספר המאפיינים עם אילוצים מורכבים, כמו מאפיינים עם פורמטים מורכבים כמו
date-time. - צמצמו את מספר המאפיינים האופציונליים.
- צריך לצמצם את מספר הערכים התקינים של מאפייני enum.
שדות סכימה נתמכים
אפשר לציין response_schema שמתאר את פורמט הפלט.
המודל יוצר תשובה שתואמת לסכימה שסופקה. כשמשתמשים בפלט מובנה, המודל יוצר פלט באותו סדר כמו המפתחות בסכימה.
השדות הבאים מסכימת Agent Platform נתמכים. אם תשתמשו בשדה לא נתמך, פלטפורמת הסוכנים עדיין תוכל לטפל בבקשה, אבל תתעלם מהשדה:
anyOf-
enum: יש תמיכה רק ברכיביstringלא ריקים. אם תכללו מחרוזת ריקה (""), תוחזר שגיאת400 INVALID_ARGUMENT(cannot be empty). formatitemsmaximummaxItemsminimumminItemsnullable-
properties: מפתחות המאפיינים חייבים להיות מחרוזות לא ריקות. אם כוללים מפתח מחרוזת ריק (""), מוחזרת שגיאת400 INVALID_ARGUMENT(key cannot be empty). descriptionpropertyOrdering*required
* propertyOrdering מיועד ספציפית לפלט מובנה, והוא לא חלק מהסכימה של פלטפורמת הסוכנים. השדה הזה מגדיר את הסדר שבו הנכסים נוצרים. המאפיינים שברשימה חייבים להיות ייחודיים וחייבים להיות מפתחות חוקיים במילון properties.
כשמגדירים סכימה, המודל לא פועל בדיוק לפי סדר המאפיינים שמוגדר בשדה properties. כדי לאכוף סדר ספציפי ליצירת נכסים, משתמשים בשדה propertyOrdering. המאפיינים שמופיעים ב-propertyOrdering נוצרים קודם, לפי הסדר שצוין, ואחריהם נוצרים כל המאפיינים האחרים.
אם אתם משתמשים ב-Python SDK, סדר ברירת המחדל של המאפיינים הוא לפי הסדר שמוגדר בסכימה. בכל שאר המקרים, המאפיינים נוצרים בסדר אלפביתי, כשהמאפיינים הנדרשים מקובצים קודם ואחריהם המאפיינים האופציונליים.
בשדה format, פלטפורמת Agent תומכת בערכים הבאים: date, date-time, duration ו-time. התיאור והפורמט של כל ערך מפורטים במרשם של OpenAPI Initiative.
לפני שמתחילים
מגדירים סכֵימת תשובה כדי לציין את מבנה הפלט של המודל, את שמות השדות ואת סוג הנתונים הצפוי בכל שדה. השתמשו רק בשדות הנתמכים שמפורטים בקטע שיקולים. המערכת תתעלם מכל שאר השדות.
כוללים את סכמת התשובה רק כחלק מהשדה responseSchema. אל תשכפלו את הסכימה בהנחיית הקלט. אם תעשו את זה, יכול להיות שהפלט שייווצר יהיה באיכות נמוכה יותר.
בקטע סכמות לדוגמה ותשובות של מודלים יש סכמות לדוגמה.
התנהגות המודל וסכֵימת התשובה
כשהמודל יוצר תשובה, הוא משתמש בשם השדה ובתיאור מהסכימה שסופקה. השתמשו במבנה ברור ובשמות שדות חד-משמעיים כדי שהכוונה שלכם תהיה ברורה. מומלץ להשתמש בשדה description במאפייני הסכימה כדי להגדיר את המטרה של כל שדה.
כברירת מחדל, השדות הם אופציונליים, כלומר המודל יכול לאכלס את השדות או לדלג עליהם. אתם יכולים להגדיר שדות כחובה כדי לאלץ את המודל לספק ערך. אם אין מספיק הקשר בהנחיית הקלט המשויכת, המודל יוצר תשובות שמבוססות בעיקר על הנתונים ששימשו לאימון שלו.
אם אתם לא מקבלים את התוצאות שציפיתם להן, נסו לשנות את התיאורים בסכימה. אם אתם לא מצליחים להעביר את הניואנסים של הסכימה בתיאור הסכימה בלבד, אתם יכולים לדון בסכימה בהנחיה לפי ההנחיות הבאות:
צריך לציין את הסכימה רק באובייקט הסכימה. אל תציינו את הסכימה גם בהנחיה. אם תעשו את שניהם, הביצועים עלולים להיפגע.
אל תתייחסו לסכימה בהנחיה (מעבר ל "פעלו לפי הסכימה שסופקה" או משהו דומה), אלא אם זה הכרחי. כך קל יותר לתחזק את הקוד. אם צריך לשנות את הסכימה, אפשר לעדכן רק את הסכימה במקום לעדכן גם את ההנחיה וגם את הסכימה.
אם אתם חייבים לדון בסכימה בהנחיה (כדי לספק דוגמאות או הוראות מפורטות במיוחד, שאחרת יובילו לערכי
descriptionארוכים בסכימה), הקפידו על סדר שדות exact לזה שבסכימה שסופקה. אם סדר השדות בסכימה שונה מהסדר בהנחיה, עלולות להיווצר שגיאות בפלט.
שליחת הנחיה עם סכֵימת תשובה
כברירת מחדל, כל השדות הם אופציונליים, כלומר המודל יכול ליצור תשובה לשדה. כדי לאלץ את המודל תמיד ליצור תשובה לשדה, מגדירים את השדה כחובה.
Python
התקנה
pip install --upgrade google-genai
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
התקנה
npm install @google/genai
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
איך מתקינים או מעדכנים את Java
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
REST
GenerateContent API
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- GENERATE_RESPONSE_METHOD: סוג התשובה שרוצים שהמודל ייצור.
בוחרים שיטה שקובעת איך התשובה של המודל תוחזר:
-
streamGenerateContent: התשובה מועברת בסטרימינג בזמן שהיא נוצרת, כדי להפחית את תפיסת זמן האחזור אצל קהל אנושי. -
generateContent: התשובה מוחזרת אחרי שהיא נוצרת במלואה.
-
- LOCATION: האזור שבו הבקשה תעובד.
- PROJECT_ID: מזהה הפרויקט.
- MODEL_ID: מזהה המודל של המודל המולטי-מודאלי שבו רוצים להשתמש.
- ROLE:
התפקיד בשיחה שמשויך לתוכן. חובה לציין תפקיד גם בתרחישי שימוש של פנייה אחת.
הערכים הקבילים כוללים:
USER: מציין תוכן שאתם שלחתם.
- TEXT: ההוראות בטקסט שצריך לכלול בהנחיה.
- RESPONSE_MIME_TYPE: סוג הפורמט של הטקסט שנוצר. רשימה של הערכים הנתמכים מופיעה בפרמטר
responseMimeTypeב-Gemini API. - RESPONSE_SCHEMA: הסכימה שהמודל צריך לפעול לפיה כשהוא יוצר תשובות. מומלץ להשתמש בשדה
descriptionכדי לתאר את מטרת הסכימה ואת המאפיינים שלה. מידע נוסף זמין במאמרי העזרה בנושא סכימה.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD
גוף בקשת JSON:
{
"contents": {
"role": "user",
"parts": {
"text": "List a few popular cookie recipes."
}
},
"generation_config": {
"maxOutputTokens": 2048,
"responseMimeType": "application/json",
"responseSchema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
"description": "The name of the cookie recipe."
}
},
"required": ["recipe_name"]
}
}
}
}
כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:
curl
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"
PowerShell
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content
אתם אמורים לקבל תגובת JSON שדומה לזו:
Interactions API
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- PROJECT_ID: מזהה הפרויקט.
- MODEL_ID: מזהה המודל של המודל המולטי-מודאלי שבו רוצים להשתמש.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
גוף בקשת JSON:
{
"model": "MODEL_ID",
"input": [
{
"type": "user_input",
"content": [
{
"type": "text",
"text": "List a few popular cookie recipes."
}
]
}
],
"generation_config": {
"max_output_tokens": 2048
},
"response_format": {
"type": "text",
"mime_type": "application/json",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
"description": "The name of the cookie recipe."
}
},
"required": ["recipe_name"]
}
}
}
}
כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:
curl
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions"
PowerShell
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" | Select-Object -Expand Content
אתם אמורים לקבל תגובת JSON שדומה לזו:
סכימות לדוגמה לפלט JSON
בקטעים הבאים מוצגות מגוון הנחיות לדוגמה וסכמות תשובה. אחרי כל דוגמת קוד יש גם דוגמה לתשובה מהמודל.
תחזית מזג האוויר לכל יום בשבוע
בדוגמה הבאה, הפלט הוא אובייקט forecast לכל יום בשבוע, שכולל מערך של מאפיינים כמו הטמפרטורה ורמת הלחות הצפויות באותו יום. חלק מהמאפיינים מוגדרים כ-nullable, כדי שהמודל יוכל להחזיר ערך null כשאין לו מספיק הקשר כדי ליצור תשובה משמעותית. האסטרטגיה הזו עוזרת לצמצם הזיות.
Python
התקנה
pip install --upgrade google-genai
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
התקנה
npm install @google/genai
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
איך מתקינים או מעדכנים את Java
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
סיווג מוצר
הדוגמה הבאה כוללת ערכי enum שבהם המודל צריך לסווג את הסוג והמצב של אובייקט מתוך רשימה של ערכים נתונים.
Python
התקנה
pip install --upgrade google-genai
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
התקנה
npm install @google/genai
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
איך מתקינים או מעדכנים את Java
מידע נוסף זמין במאמרי העזרה של ה-SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True