שמירת מטמון של הקשר מאפשרת לכם לשמור ולעשות שימוש חוזר בטוקנים של קלט שחושבו מראש שאתם רוצים להשתמש בהם שוב ושוב, למשל כשאתם שואלים שאלות שונות לגבי אותו קובץ מדיה. השימוש ב-API יכול להוביל לחיסכון בעלויות ולשיפור המהירות, בהתאם לשימוש. למידע נוסף, אפשר לעיין במדריך בנושא שמירת נתונים במטמון לפי הקשר.
שיטה: cachedContents.create
יוצרת משאב CachedContent.
נקודת קצה
posthttps: / /generativelanguage.googleapis.com /v1beta /cachedContents
גוף הבקשה
גוף הבקשה מכיל מופע של CachedContent
.
contents[]
object (Content
)
אופציונלי. קלט בלבד. אי אפשר לשנות אותו. התוכן שרוצים להוסיף למטמון.
tools[]
object (Tool
)
אופציונלי. קלט בלבד. אי אפשר לשנות אותו. רשימה של Tools
שהמודל עשוי להשתמש בה כדי ליצור את התשובה הבאה
expiration
Union type
expiration
יכול להיות רק אחד מהבאים:expireTime
string (Timestamp
format)
חותמת הזמן בשעון UTC שבה המשאב הזה נחשב כמשאב שתוקפו פג. הערך הזה תמיד מופיע בפלט, לא משנה מה נשלח בקלט.
הפונקציה משתמשת ב-RFC 3339, והפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות חלקיות. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
או "2014-10-02T15:01:23+05:30"
.
ttl
string (Duration
format)
קלט בלבד. ערך TTL חדש למשאב הזה, קלט בלבד.
משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-'s
'. דוגמה: "3.5s"
.
displayName
string
אופציונלי. אי אפשר לשנות אותו. שם התצוגה המשמעותי של התוכן שבמטמון, שנוצר על ידי המשתמש. 128 תווים לכל היותר ב-Unicode.
model
string
חובה. אי אפשר לשנות אותו. השם של Model
שבו רוצים להשתמש לתוכן שנשמר במטמון. הפורמט: models/{model}
systemInstruction
object (Content
)
אופציונלי. קלט בלבד. אי אפשר לשנות אותו. הוראות מערכת שהוגדרו על ידי מפתח. בשלב הזה רק טקסט.
toolConfig
object (ToolConfig
)
אופציונלי. קלט בלבד. אי אפשר לשנות אותו. הגדרת הכלי. ההגדרה הזו משותפת לכל הכלים.
דוגמה לבקשה
בסיסית
Python
Node.js
Go
קונכייה
שם השולח
Python
Node.js
Go
מצ'אט
Python
Node.js
Go
גוף התשובה
אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע חדש של CachedContent
.
שיטה: cachedContents.list
רשימות CachedContents.
נקודת קצה
gethttps: / /generativelanguage.googleapis.com /v1beta /cachedContents
פרמטרים של שאילתה
pageSize
integer
אופציונלי. המספר המקסימלי של תכנים שמורים במטמון שיוחזרו. יכול להיות שהשירות יחזיר פחות מהערך הזה. אם לא מציינים ערך, יוחזר מספר ברירת מחדל של פריטים (מתחת למקסימום). הערך המקסימלי הוא 1,000. ערכים גבוהים יותר יומרו ל-1,000.
pageToken
string
אופציונלי. טוקן של דף שהתקבל מקריאה קודמת של cachedContents.list
. צריך להזין את הטוקן כדי לאחזר את הדף הבא.
כשמבצעים חלוקה לעמודים, כל הפרמטרים האחרים שסופקו ל-cachedContents.list
חייבים להיות זהים לקריאה שסיפקה את הטוקן של הדף.
גוף הבקשה
גוף הבקשה צריך להיות ריק.
גוף התשובה
תגובה עם רשימה של CachedContents.
אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:
cachedContents[]
object (CachedContent
)
רשימת התוכן שנשמר במטמון.
nextPageToken
string
טוקן שאפשר לשלוח כ-pageToken
כדי לאחזר את הדף הבא. אם משמיטים את השדה הזה, לא יופיעו דפים נוספים.
ייצוג ב-JSON |
---|
{
"cachedContents": [
{
object ( |
שיטה: cachedContents.get
קורא את המשאב CachedContent.
נקודת קצה
gethttps: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}
פרמטרים של נתיב
name
string
חובה. שם המשאב שמתייחס לרשומה במטמון התוכן. פורמט: cachedContents/{id}
הוא מקבל את הצורה cachedContents/{cachedcontent}
.
גוף הבקשה
גוף הבקשה צריך להיות ריק.
דוגמה לבקשה
Python
Node.js
Go
קונכייה
גוף התשובה
אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של CachedContent
.
שיטה: cachedContents.patch
עדכון של משאב CachedContent (אפשר לעדכן רק את תאריך התפוגה).
נקודת קצה
patchhttps: / /generativelanguage.googleapis.com /v1beta /{cachedContent.name=cachedContents /*}
PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
פרמטרים של נתיב
cachedContent.name
string
פלט בלבד. מזהה. שם המשאב שאליו מתייחס התוכן שבמטמון. פורמט: cachedContents/{id}
הוא מקבל את הצורה cachedContents/{cachedcontent}
.
פרמטרים של שאילתה
updateMask
string (FieldMask
format)
רשימת השדות לעדכון.
זוהי רשימה של שמות שדות שמוגדרים במלואם, שמופרדים באמצעות פסיקים. דוגמה: "user.displayName,photo"
גוף הבקשה
גוף הבקשה מכיל מופע של CachedContent
.
expiration
Union type
expiration
יכול להיות רק אחד מהבאים:expireTime
string (Timestamp
format)
חותמת הזמן בשעון UTC שבה המשאב הזה נחשב כמשאב שתוקפו פג. הערך הזה תמיד מופיע בפלט, לא משנה מה נשלח בקלט.
הפונקציה משתמשת ב-RFC 3339, והפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות חלקיות. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
או "2014-10-02T15:01:23+05:30"
.
ttl
string (Duration
format)
קלט בלבד. ערך TTL חדש למשאב הזה, קלט בלבד.
משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-'s
'. דוגמה: "3.5s"
.
דוגמה לבקשה
Python
Node.js
Go
קונכייה
גוף התשובה
אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של CachedContent
.
שיטה: cachedContents.delete
מחיקת משאב CachedContent.
נקודת קצה
deletehttps: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}
פרמטרים של נתיב
name
string
חובה. שם המשאב שאליו מתייחסת רשומת מטמון התוכן. הפורמט: cachedContents/{id}
. הוא מופיע באופן הבא: cachedContents/{cachedcontent}
.
גוף הבקשה
גוף הבקשה צריך להיות ריק.
דוגמה לבקשה
Python
Node.js
Go
קונכייה
גוף התשובה
אם הפעולה בוצעה ללא שגיאות, גוף התגובה הוא אובייקט JSON ריק.
משאב REST: cachedContents
- Resource: CachedContent
- Content
- Part
- Blob
- FunctionCall
- FunctionResponse
- FunctionResponsePart
- FunctionResponseBlob
- תזמון
- FileData
- ExecutableCode
- שפה
- CodeExecutionResult
- תוצאה
- VideoMetadata
- כלי
- FunctionDeclaration
- סכימה
- סוג
- התנהגות
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- המצב
- CodeExecution
- GoogleSearch
- Interval
- ComputerUse
- סביבה
- UrlContext
- FileSearch
- RetrievalResource
- RetrievalConfig
- GoogleMaps
- ToolConfig
- FunctionCallingConfig
- המצב
- RetrievalConfig
- LatLng
- UsageMetadata
- Methods
משאב: CachedContent
תוכן שעבר עיבוד מראש ואפשר להשתמש בו בבקשה הבאה אל GenerativeService.
אפשר להשתמש בתוכן שמור במטמון רק עם המודל שעבורו הוא נוצר.
contents[]
object (Content
)
אופציונלי. קלט בלבד. אי אפשר לשנות אותו. התוכן שרוצים להוסיף למטמון.
tools[]
object (Tool
)
אופציונלי. קלט בלבד. אי אפשר לשנות אותו. רשימה של Tools
שהמודל עשוי להשתמש בה כדי ליצור את התשובה הבאה
createTime
string (Timestamp
format)
פלט בלבד. שעת היצירה של רשומת המטמון.
הפונקציה משתמשת ב-RFC 3339, והפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות חלקיות. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
או "2014-10-02T15:01:23+05:30"
.
updateTime
string (Timestamp
format)
פלט בלבד. הזמן שבו רשומת המטמון עודכנה בפעם האחרונה לפי שעון UTC.
הפונקציה משתמשת ב-RFC 3339, והפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות חלקיות. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
או "2014-10-02T15:01:23+05:30"
.
usageMetadata
object (UsageMetadata
)
פלט בלבד. מטא-נתונים על השימוש בתוכן שבמטמון.
expiration
Union type
expiration
יכול להיות רק אחד מהבאים:expireTime
string (Timestamp
format)
חותמת הזמן בשעון UTC שבה המשאב הזה נחשב כמשאב שתוקפו פג. הערך הזה תמיד מופיע בפלט, לא משנה מה נשלח בקלט.
הפונקציה משתמשת ב-RFC 3339, והפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות חלקיות. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
או "2014-10-02T15:01:23+05:30"
.
ttl
string (Duration
format)
קלט בלבד. ערך TTL חדש למשאב הזה, קלט בלבד.
משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-'s
'. דוגמה: "3.5s"
.
name
string
פלט בלבד. מזהה. שם המשאב שאליו מתייחס התוכן שבמטמון. פורמט: cachedContents/{id}
displayName
string
אופציונלי. אי אפשר לשנות אותו. שם התצוגה המשמעותי של התוכן שבמטמון, שנוצר על ידי המשתמש. 128 תווים לכל היותר ב-Unicode.
model
string
חובה. אי אפשר לשנות אותו. השם של Model
שבו רוצים להשתמש לתוכן שנשמר במטמון. הפורמט: models/{model}
systemInstruction
object (Content
)
אופציונלי. קלט בלבד. אי אפשר לשנות אותו. הוראות מערכת שהוגדרו על ידי מפתח. בשלב הזה רק טקסט.
toolConfig
object (ToolConfig
)
אופציונלי. קלט בלבד. אי אפשר לשנות אותו. הגדרת הכלי. ההגדרה הזו משותפת לכל הכלים.
ייצוג ב-JSON |
---|
{ "contents": [ { object ( |
תוכן
סוג הנתונים המובְנים הבסיסי שמכיל תוכן של הודעה שמורכב מכמה חלקים.
Content
כולל שדה role
שמציין את היוצר של Content
ושדה parts
שמכיל נתונים מרובי חלקים שמכילים את התוכן של תור ההודעה.
parts[]
object (Part
)
מסודרות Parts
שמהוות הודעה אחת. יכול להיות שלחלקים יהיו סוגי MIME שונים.
role
string
אופציונלי. יוצר התוכן. הערך צריך להיות user או model.
מומלץ להגדיר את הפרמטר הזה לשיחות עם כמה תורות, אחרת אפשר להשאיר אותו ריק או לא מוגדר.
ייצוג ב-JSON |
---|
{
"parts": [
{
object ( |
חלק
סוג נתונים שמכיל מדיה שהיא חלק מהודעה Content
מרובת חלקים.
Part
מורכב מנתונים שמשויך אליהם סוג נתונים. Part
יכול להכיל רק סוג אחד מבין הסוגים הקבילים שמופיעים ב-Part.data
.
ל-Part
צריך להיות סוג MIME קבוע של IANA שמזהה את הסוג ותת-הסוג של המדיה אם השדה inlineData
מלא בבייטים גולמיים.
thought
boolean
אופציונלי. מציין אם החלק נוצר על ידי המודל.
thoughtSignature
string (bytes format)
אופציונלי. חתימה אטומה למחשבה, כדי שאפשר יהיה לעשות בה שימוש חוזר בבקשות הבאות.
מחרוזת בקידוד Base64.
partMetadata
object (Struct
format)
מטא-נתונים בהתאמה אישית שמשויכים לחלק. סוכנים שמשתמשים ב-genai.Part כייצוג תוכן צריכים לעקוב אחרי המידע הנוסף. לדוגמה, זה יכול להיות השם של קובץ או מקור שממנו נוצר החלק, או דרך לבצע מולטיפלקס של כמה זרמי חלקים.
data
Union type
data
יכול להיות רק אחד מהבאים:text
string
טקסט מוטבע.
inlineData
object (Blob
)
בייטים של מדיה בתוך הטקסט.
functionCall
object (FunctionCall
)
ערך FunctionCall
שחזוי על ידי המודל ומכיל מחרוזת שמייצגת את FunctionDeclaration.name
עם הארגומנטים והערכים שלהם.
functionResponse
object (FunctionResponse
)
פלט התוצאה של FunctionCall
שמכיל מחרוזת שמייצגת את FunctionDeclaration.name
ואובייקט JSON מובנה שמכיל פלט מהפונקציה, משמש כהקשר למודל.
fileData
object (FileData
)
נתונים שמבוססים על URI.
executableCode
object (ExecutableCode
)
קוד שנוצר על ידי המודל ומיועד להרצה.
codeExecutionResult
object (CodeExecutionResult
)
התוצאה של הפעלת ExecutableCode
.
metadata
Union type
metadata
יכול להיות רק אחד מהבאים:videoMetadata
object (VideoMetadata
)
אופציונלי. מטא-נתונים של סרטונים. צריך לציין את המטא-נתונים רק כשנתוני הסרטון מוצגים ב-inlineData או ב-fileData.
ייצוג ב-JSON |
---|
{ "thought": boolean, "thoughtSignature": string, "partMetadata": { object }, // data "text": string, "inlineData": { object ( |
Blob
בייטים גולמיים של מדיה.
אין לשלוח טקסט כבייטים גולמיים, אלא להשתמש בשדה 'text'.
mimeType
string
סוג ה-MIME התקני של IANA של נתוני המקור. דוגמאות: - image/png - image/jpeg אם יסופק סוג MIME לא נתמך, תוחזר שגיאה. רשימה מלאה של הסוגים הנתמכים זמינה במאמר פורמטים נתמכים של קבצים.
data
string (bytes format)
בייטים גולמיים לפורמטים של מדיה.
מחרוזת בקידוד Base64.
ייצוג ב-JSON |
---|
{ "mimeType": string, "data": string } |
FunctionCall
ערך FunctionCall
שחזוי על ידי המודל ומכיל מחרוזת שמייצגת את FunctionDeclaration.name
עם הארגומנטים והערכים שלהם.
id
string
אופציונלי. המזהה הייחודי של הקריאה לפונקציה. אם השדה הזה מאוכלס, הלקוח יבצע את functionCall
ויחזיר את התשובה עם id
תואם.
name
string
חובה. השם של הפונקציה שרוצים להפעיל. הערך חייב להיות a-z, A-Z, 0-9, או להכיל קווים תחתונים ומקפים, עם אורך מקסימלי של 64 תווים.
args
object (Struct
format)
אופציונלי. הפרמטרים והערכים של הפונקציה בפורמט של אובייקט JSON.
ייצוג ב-JSON |
---|
{ "id": string, "name": string, "args": { object } } |
FunctionResponse
הפלט שמתקבל מ-FunctionCall
שמכיל מחרוזת שמייצגת את FunctionDeclaration.name
ואובייקט JSON מובנה שמכיל את הפלט מהפונקציה, משמש כהקשר למודל. המאפיין הזה צריך להכיל את התוצאה של FunctionCall
שנוצרה על סמך חיזוי של מודל.
id
string
אופציונלי. המזהה של הקריאה לפונקציה שאליה מתייחסת התשובה הזו. הלקוח מאכלס את הערך הזה כדי להתאים לקריאה המתאימה לפונקציה id
.
name
string
חובה. השם של הפונקציה שרוצים להפעיל. הערך חייב להיות a-z, A-Z, 0-9, או להכיל קווים תחתונים ומקפים, עם אורך מקסימלי של 64 תווים.
response
object (Struct
format)
חובה. התגובה של הפונקציה בפורמט אובייקט JSON. המשתמשים יכולים להשתמש בכל מקש שמתאים לתחביר של הפונקציה כדי להחזיר את הפלט של הפונקציה, למשל'פלט', 'תוצאה' וכו'. בפרט, אם קריאת הפונקציה נכשלה, התגובה יכולה לכלול מקש 'שגיאה' כדי להחזיר פרטי שגיאה למודל.
parts[]
object (FunctionResponsePart
)
אופציונלי. מסודרים Parts
שמהווים תגובה של פונקציה. יכול להיות שלחלקים יהיו סוגי MIME שונים של IANA.
willContinue
boolean
אופציונלי. האות הזה מציין שהבקשה להפעלת הפונקציה נמשכת, ויוחזרו עוד תשובות. כך הבקשה להפעלת הפונקציה הופכת לגנרטור. ההגדרה הזו רלוונטית רק להפעלות של פונקציות מסוג NON_BLOCKING, אחרת המערכת מתעלמת ממנה. אם המדיניות מוגדרת כ-False, תשובות חדשות לא ייכללו. מותר להחזיר response
ריק עם willContinue=False
כדי לציין שהקריאה לפונקציה הסתיימה. יכול להיות שהפעולה הזו עדיין תפעיל את יצירת המודל. כדי למנוע הפעלה של יצירה ולסיים את הקריאה לפונקציה, צריך להגדיר בנוסף את scheduling
ל-SILENT
.
scheduling
enum (Scheduling
)
אופציונלי. מציינים איך לתזמן את התשובה בשיחה. ההגדרה רלוונטית רק להפעלות של פונקציות מסוג NON_BLOCKING, אחרת המערכת מתעלמת ממנה. ברירת המחדל היא WHEN_IDLE.
ייצוג ב-JSON |
---|
{ "id": string, "name": string, "response": { object }, "parts": [ { object ( |
FunctionResponsePart
סוג נתונים שמכיל מדיה שמהווה חלק מהודעה ב-FunctionResponse
.
FunctionResponsePart
מורכב מנתונים שמשויך אליהם סוג נתונים. FunctionResponsePart
יכול להכיל רק סוג אחד מבין הסוגים הקבילים שמופיעים ב-FunctionResponsePart.data
.
ל-FunctionResponsePart
צריך להיות סוג MIME קבוע של IANA שמזהה את הסוג ותת-הסוג של המדיה אם השדה inlineData
מלא בבייטים גולמיים.
data
Union type
data
יכול להיות רק אחד מהבאים:inlineData
object (FunctionResponseBlob
)
בייטים של מדיה בתוך הטקסט.
ייצוג ב-JSON |
---|
{
// data
"inlineData": {
object ( |
FunctionResponseBlob
בייטים של מדיה גולמית בתגובה של הפונקציה.
אסור לשלוח טקסט כבייטים גולמיים, צריך להשתמש בשדה FunctionResponse.response.
mimeType
string
סוג ה-MIME התקני של IANA של נתוני המקור. דוגמאות: - image/png - image/jpeg אם יסופק סוג MIME לא נתמך, תוחזר שגיאה. רשימה מלאה של הסוגים הנתמכים זמינה במאמר פורמטים נתמכים של קבצים.
data
string (bytes format)
בייטים גולמיים לפורמטים של מדיה.
מחרוזת בקידוד Base64.
ייצוג ב-JSON |
---|
{ "mimeType": string, "data": string } |
תזמון
מציינים איך לתזמן את התשובה בשיחה.
טיפוסים בני מנייה (enum) | |
---|---|
SCHEDULING_UNSPECIFIED |
הערך הזה לא בשימוש. |
SILENT |
רק תוסיף את התוצאה להקשר של השיחה, אל תקטע את השיחה ואל תפעיל יצירה. |
WHEN_IDLE |
להוסיף את התוצאה להקשר של השיחה ולתת הנחיה ליצירת פלט בלי להפריע ליצירה המתמשכת. |
INTERRUPT |
הוספת התוצאה להקשר של השיחה, הפסקת היצירה המתמשכת והנחיה ליצירת פלט. |
FileData
נתונים שמבוססים על URI.
mimeType
string
אופציונלי. סוג ה-MIME התקני של IANA של נתוני המקור.
fileUri
string
חובה. URI.
ייצוג ב-JSON |
---|
{ "mimeType": string, "fileUri": string } |
ExecutableCode
קוד שנוצר על ידי המודל ומיועד להרצה, והתוצאה מוחזרת למודל.
נוצר רק כשמשתמשים בכלי CodeExecution
, שבו הקוד יופעל באופן אוטומטי, וגם ייווצר CodeExecutionResult
תואם.
language
enum (Language
)
חובה. שפת התכנות של code
.
code
string
חובה. הקוד שיופעל.
ייצוג ב-JSON |
---|
{
"language": enum ( |
שפה
שפות התכנות הנתמכות לקוד שנוצר.
טיפוסים בני מנייה (enum) | |
---|---|
LANGUAGE_UNSPECIFIED |
לא נבחרה שפה. אין להשתמש בערך הזה. |
PYTHON |
Python >= 3.10, עם numpy ו-simpy. |
CodeExecutionResult
התוצאה של הפעלת ExecutableCode
.
נוצר רק כשמשתמשים ב-CodeExecution
, ותמיד מופיע אחרי part
שמכיל את ExecutableCode
.
outcome
enum (Outcome
)
חובה. התוצאה של הרצת הקוד.
output
string
אופציונלי. התשובה מכילה את הפלט הרגיל (stdout) אם ביצוע הקוד מצליח, או את הפלט של שגיאות (stderr) או תיאור אחר אם הביצוע נכשל.
ייצוג ב-JSON |
---|
{
"outcome": enum ( |
תוצאה
ספירה של התוצאות האפשריות של הרצת הקוד.
טיפוסים בני מנייה (enum) | |
---|---|
OUTCOME_UNSPECIFIED |
הסטטוס לא צוין. אין להשתמש בערך הזה. |
OUTCOME_OK |
ביצוע הקוד הושלם בהצלחה. |
OUTCOME_FAILED |
ביצוע הקוד הסתיים אבל נכשל. השדה stderr צריך להכיל את הסיבה. |
OUTCOME_DEADLINE_EXCEEDED |
ההרצה של הקוד נמשכה יותר מדי זמן והיא בוטלה. יכול להיות שיוצג פלט חלקי, אבל לא בהכרח. |
VideoMetadata
המטא-נתונים מתארים את תוכן הווידאו של הקלט.
startOffset
string (Duration
format)
אופציונלי. ההיסט מתחילת הסרטון.
משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-'s
'. דוגמה: "3.5s"
.
endOffset
string (Duration
format)
אופציונלי. ההיסט של סוף הסרטון.
משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-'s
'. דוגמה: "3.5s"
.
fps
number
אופציונלי. קצב הפריימים של הסרטון שנשלח למודל. אם לא מציינים ערך, ברירת המחדל היא 1.0. טווח ה-fps הוא (0.0, 24.0].
ייצוג ב-JSON |
---|
{ "startOffset": string, "endOffset": string, "fps": number } |
כלי
פרטי כלי שהמודל עשוי להשתמש בהם כדי ליצור תשובה.
Tool
הוא קטע קוד שמאפשר למערכת ליצור אינטראקציה עם מערכות חיצוניות כדי לבצע פעולה או סדרת פעולות, ללא ידיעת המודל או מחוץ לתחום הפעולה שלו.
המזהה הבא: 12
functionDeclarations[]
object (FunctionDeclaration
)
אופציונלי. רשימה של FunctionDeclarations
שזמינות למודל שאפשר להשתמש בהן לקריאה לפונקציות.
המודל או המערכת לא מבצעים את הפונקציה. במקום זאת, הפונקציה המוגדרת עשויה להיות מוחזרת כ-FunctionCall
עם ארגומנטים לצד הלקוח לצורך ביצוע. יכול להיות שהמודל יחליט לקרוא לתת-קבוצה של הפונקציות האלה על ידי מילוי FunctionCall
בתגובה. התור הבא בשיחה עשוי להכיל FunctionResponse
עם הקשר ליצירת Content.role
'פונקציה' לתור הבא של המודל.
googleSearchRetrieval
object (GoogleSearchRetrieval
)
אופציונלי. כלי לאחזור מידע שמבוסס על חיפוש Google.
codeExecution
object (CodeExecution
)
אופציונלי. ההגדרה הזו מאפשרת למודל להריץ קוד כחלק מהיצירה.
googleSearch
object (GoogleSearch
)
אופציונלי. סוג הכלי GoogleSearch. כלי לתמיכה בחיפוש Google במודל. מופעל על ידי Google.
computerUse
object (ComputerUse
)
אופציונלי. כלי לתמיכה באינטראקציה של המודל ישירות עם המחשב. אם האפשרות הזו מופעלת, המערכת מאכלסת באופן אוטומטי הצהרות פונקציה ספציפיות לשימוש במחשב.
urlContext
object (UrlContext
)
אופציונלי. כלי לתמיכה באחזור הקשר של כתובת URL.
fileSearch
object (FileSearch
)
אופציונלי. סוג הכלי FileSearch. כלי לאחזור ידע ממאגרי מידע של אחזור סמנטי.
googleMaps
object (GoogleMaps
)
אופציונלי. כלי שמאפשר להוסיף לתשובה של המודל הקשר גיאוספציאלי שקשור לשאילתה של המשתמש.
ייצוג ב-JSON |
---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
ייצוג מובנה של הצהרת פונקציה כמוגדר במפרט OpenAPI 3.03. ההצהרה כוללת את שם הפונקציה והפרמטרים שלה. ה-FunctionDeclaration הזה הוא ייצוג של בלוק קוד שאפשר להשתמש בו כTool
על ידי המודל, והוא מופעל על ידי הלקוח.
name
string
חובה. שם הפונקציה. הערך חייב להיות a-z, A-Z, 0-9, או להכיל קווים תחתונים, נקודותיים, נקודות ומקפים, עם אורך מקסימלי של 64 תווים.
description
string
חובה. תיאור קצר של הפונקציה.
behavior
enum (Behavior
)
אופציונלי. מציינת את התנהגות הפונקציה. בשלב הזה, יש תמיכה רק בשיטה BidiGenerateContent.
parameters
object (Schema
)
אופציונלי. מתאר את הפרמטרים של הפונקציה. משקף את מחרוזת המפתח של אובייקט הפרמטר Open API 3.03: שם הפרמטר. השמות של הפרמטרים הם תלויי אותיות רישיות. ערך הסכימה: הסכימה שמגדירה את הסוג שמשמש לפרמטר.
parametersJsonSchema
value (Value
format)
אופציונלי. תיאור הפרמטרים של הפונקציה בפורמט JSON Schema. הסכימה צריכה לתאר אובייקט שבו המאפיינים הם הפרמטרים של הפונקציה. לדוגמה:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
},
"additionalProperties": false,
"required": ["name", "age"],
"propertyOrdering": ["name", "age"]
}
השדה הזה בלעדי לשדה parameters
.
response
object (Schema
)
אופציונלי. מתאר את הפלט מהפונקציה הזו בפורמט JSON Schema. משקף את אובייקט התגובה של Open API 3.03. הסכימה מגדירה את הסוג שמשמש לערך התגובה של הפונקציה.
responseJsonSchema
value (Value
format)
אופציונלי. מתאר את הפלט מהפונקציה הזו בפורמט JSON Schema. הערך שצוין בסכימה הוא ערך התגובה של הפונקציה.
השדה הזה בלעדי לשדה response
.
סכימה
אובייקט Schema
מאפשר להגדיר את סוגי הנתונים של הקלט והפלט. הסוגים האלה יכולים להיות אובייקטים, אבל גם פרימיטיבים ומערכים. מייצג קבוצת משנה נבחרת של אובייקט סכימה של OpenAPI 3.0.
type
enum (Type
)
חובה. סוג הנתונים.
format
string
אופציונלי. הפורמט של הנתונים. מותר להשתמש בכל ערך, אבל ברוב המקרים לא מופעלת פונקציונליות מיוחדת.
title
string
אופציונלי. השם של הסכימה.
description
string
אופציונלי. תיאור קצר של הפרמטר. יכול להיות שהמידע הזה יכלול דוגמאות לשימוש. התיאור של הפרמטר יכול להיות בפורמט Markdown.
nullable
boolean
אופציונלי. מציין אם הערך יכול להיות null.
enum[]
string
אופציונלי. ערכים אפשריים של רכיב מסוג STRING עם פורמט enum. לדוגמה, אפשר להגדיר Enum Direction כך : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
maxItems
string (int64 format)
אופציונלי. המספר המקסימלי של הרכיבים עבור Type.ARRAY.
minItems
string (int64 format)
אופציונלי. מספר המינימלי של הרכיבים עבור Type.ARRAY.
properties
map (key: string, value: object (Schema
))
אופציונלי. מאפיינים של Type.OBJECT.
אובייקט שמכיל רשימה של "key": value
זוגות. דוגמה: { "name": "wrench", "mass": "1.3kg", "count": "3" }
.
required[]
string
אופציונלי. מאפייני חובה של Type.OBJECT.
minProperties
string (int64 format)
אופציונלי. מספר המינימלי של המאפיינים עבור Type.OBJECT.
maxProperties
string (int64 format)
אופציונלי. מספר המאפיינים המקסימלי עבור Type.OBJECT.
minLength
string (int64 format)
אופציונלי. שדות סכימה לסוג STRING אורך מינימלי של Type.STRING
maxLength
string (int64 format)
אופציונלי. האורך המקסימלי של Type.STRING
pattern
string
אופציונלי. תבנית של Type.STRING להגבלת מחרוזת לביטוי רגולרי.
example
value (Value
format)
אופציונלי. דוגמה לאובייקט. השדה יאוכלס רק אם האובייקט הוא השורש.
anyOf[]
object (Schema
)
אופציונלי. הערך צריך לעבור אימות מול כל אחת (אחת או יותר) מתתי-הסכימות ברשימה.
propertyOrdering[]
string
אופציונלי. סדר המאפיינים. זה לא שדה רגיל במפרט של Open API. הוא משמש לקביעת סדר המאפיינים בתגובה.
default
value (Value
format)
אופציונלי. ערך ברירת המחדל של השדה. לפי JSON Schema, השדה הזה מיועד לגנרטורים של תיעוד ולא משפיע על האימות. לכן הוא נכלל כאן ומתעלמים ממנו, כדי שמפתחים ששולחים סכימות עם שדה default
לא יקבלו שגיאות של שדה לא ידוע.
items
object (Schema
)
אופציונלי. סכימה של רכיבי Type.ARRAY.
minimum
number
אופציונלי. שדות סכמה לסוגים INTEGER ו-NUMBER הערך המינימלי של Type.INTEGER ו-Type.NUMBER
maximum
number
אופציונלי. הערך המקסימלי של Type.INTEGER ו-Type.NUMBER
ייצוג ב-JSON |
---|
{ "type": enum ( |
סוג
הסוג מכיל את רשימת סוגי הנתונים של OpenAPI כפי שהוגדרו בכתובת https://spec.openapis.org/oas/v3.0.3#data-types
טיפוסים בני מנייה (enum) | |
---|---|
TYPE_UNSPECIFIED |
לא צוין, אין להשתמש. |
STRING |
סוג מחרוזת. |
NUMBER |
סוג המספר. |
INTEGER |
סוג Integer. |
BOOLEAN |
טיפוס בוליאני. |
ARRAY |
סוג המערך. |
OBJECT |
סוג האובייקט. |
NULL |
סוג Null. |
התנהגות
הגדרת אופן הפעולה של הפונקציה. ברירת המחדל היא BLOCKING
.
טיפוסים בני מנייה (enum) | |
---|---|
UNSPECIFIED |
הערך הזה לא בשימוש. |
BLOCKING |
אם מוגדרת פונקציה, המערכת תמתין לקבלת התשובה מהפונקציה לפני שתמשיך את השיחה. |
NON_BLOCKING |
אם ההגדרה הזו מוגדרת, המערכת לא תמתין לקבלת התגובה של הפונקציה. במקום זאת, הוא ינסה לטפל בתשובות לפונקציות כשהן יהיו זמינות, תוך שמירה על השיחה בין המשתמש לבין המודל. |
GoogleSearchRetrieval
כלי לאחזור נתונים ציבוריים מהאינטרנט לצורך ביסוס, מבית Google.
dynamicRetrievalConfig
object (DynamicRetrievalConfig
)
מציינת את הגדרת האחזור הדינמי של המקור הנתון.
ייצוג ב-JSON |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
מצב
המצב של כלי החיזוי שישמש לאחזור דינמי.
טיפוסים בני מנייה (enum) | |
---|---|
MODE_UNSPECIFIED |
תמיד מפעילים אחזור. |
MODE_DYNAMIC |
הפעלה של אחזור רק כשהמערכת מחליטה שזה נחוץ. |
CodeExecution
בסוג הזה אין שדות.
כלי שמריץ קוד שנוצר על ידי המודל ומחזיר את התוצאה למודל באופן אוטומטי.
אפשר גם לעיין בExecutableCode
ובCodeExecutionResult
, שנוצרים רק כשמשתמשים בכלי הזה.
GoogleSearch
מרווח
מייצג מרווח זמן, שמקודד כחותמת זמן של התחלה (כולל) וכחותמת זמן של סיום (לא כולל).
ערך ההתחלה חייב להיות קטן מערך הסיום או שווה לו. אם שעת ההתחלה זהה לשעת הסיום, המרווח ריק (לא תואם לאף שעה). אם לא מציינים את שעת ההתחלה ואת שעת הסיום, המרווח מתאים לכל שעה.
startTime
string (Timestamp
format)
אופציונלי. ההתחלה של מרווח הזמן, כולל.
אם מציינים חותמת זמן, היא צריכה להיות זהה לזמן ההתחלה או מאוחרת ממנו.
הפונקציה משתמשת ב-RFC 3339, והפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות חלקיות. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
או "2014-10-02T15:01:23+05:30"
.
endTime
string (Timestamp
format)
אופציונלי. סוף המרווח, לא כולל.
אם מציינים חותמת זמן, היא צריכה להיות לפני סוף המרווח.
הפונקציה משתמשת ב-RFC 3339, והפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות חלקיות. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
או "2014-10-02T15:01:23+05:30"
.
ייצוג ב-JSON |
---|
{ "startTime": string, "endTime": string } |
ComputerUse
סוג הכלי לשימוש במחשב.
environment
enum (Environment
)
חובה. הסביבה שבה מתבצעת הפעולה.
excludedPredefinedFunctions[]
string
אופציונלי. כברירת מחדל, פונקציות מוגדרות מראש נכללות בקריאה הסופית למודל. אפשר להחריג חלק מהם כך שלא ייכללו באופן אוטומטי. הפעולה הזו יכולה לשמש לשתי מטרות: 1. שימוש במרחב פעולה מוגבל יותר או שונה. 2. שיפור ההגדרות או ההוראות של פונקציות מוגדרות מראש.
ייצוג ב-JSON |
---|
{
"environment": enum ( |
סביבה
מייצג את הסביבה שבה מתבצעת הפעולה, כמו דפדפן אינטרנט.
טיפוסים בני מנייה (enum) | |
---|---|
ENVIRONMENT_UNSPECIFIED |
ברירת המחדל היא דפדפן. |
ENVIRONMENT_BROWSER |
פועל בדפדפן אינטרנט. |
UrlContext
בסוג הזה אין שדות.
כלי לתמיכה באחזור הקשר של כתובת URL.
FileSearch
הכלי FileSearch שמאחזר ידע ממאגרי מידע של Semantic Retrieval. קבצים מיובאים למאגרי מידע של כלי האחזור הסמנטי באמצעות ImportFile API.
retrievalResources[]
object (RetrievalResource
)
חובה. משאבים לאחזור סמנטי שאפשר לאחזר מהם. בשלב הזה יש תמיכה רק במאגר אחד. יכול להיות שבעתיד נפתח תמיכה בכמה מאגרי מידע.
retrievalConfig
object (RetrievalConfig
)
אופציונלי. ההגדרה של השליפה.
ייצוג ב-JSON |
---|
{ "retrievalResources": [ { object ( |
RetrievalResource
משאב האחזור הסמנטי שממנו יתבצע האחזור.
ragStoreName
string
חובה. השם של משאב השליפה הסמנטית שממנו יתבצע האחזור. לדוגמה: ragStores/my-rag-store-123
ייצוג ב-JSON |
---|
{ "ragStoreName": string } |
RetrievalConfig
הגדרת אחזור סמנטי.
metadataFilter
string
אופציונלי. מסנן מטא-נתונים להחלה על המסמכים ועל חלקי הטקסט שחולצו באמצעות אחזור סמנטי.
topK
integer
אופציונלי. מספר החלקים של אחזור סמנטי שיש לאחזר.
ייצוג ב-JSON |
---|
{ "metadataFilter": string, "topK": integer } |
GoogleMaps
כלי Google Maps שמספק הקשר גיאוגרפי לשאילתה של המשתמש.
enableWidget
boolean
אופציונלי. האם להחזיר אסימון הקשר של הווידג'ט ב-GroundingMetadata של התגובה. מפתחים יכולים להשתמש באסימון ההקשר של הווידג'ט כדי להציג ווידג'ט של מפות Google עם הקשר גיאוספציאלי שקשור למקומות שהמודל מתייחס אליהם בתשובה.
ייצוג ב-JSON |
---|
{ "enableWidget": boolean } |
ToolConfig
הגדרת הכלי שמכילה פרמטרים לציון השימוש ב-Tool
בבקשה.
functionCallingConfig
object (FunctionCallingConfig
)
אופציונלי. הגדרת בקשות להפעלת פונקציה.
retrievalConfig
object (RetrievalConfig
)
אופציונלי. הגדרת אחזור.
ייצוג ב-JSON |
---|
{ "functionCallingConfig": { object ( |
FunctionCallingConfig
הגדרות לציון ההתנהגות של קריאה לפונקציה.
mode
enum (Mode
)
אופציונלי. מציינים את המצב שבו הפעלת הפונקציה תתבצע. אם לא מציינים ערך, ערך ברירת המחדל יהיה AUTO.
allowedFunctionNames[]
string
אופציונלי. קבוצה של שמות פונקציות, שאם מספקים אותם, המודל יפעיל רק את הפונקציות האלה.
צריך להגדיר את הערך הזה רק אם המצב הוא ANY או VALIDATED. שמות הפונקציות צריכים להיות זהים לערך [FunctionDeclaration.name]. אם המאפיין הזה מוגדר, המודל ינבא קריאה לפונקציה רק משמות פונקציות מותרים.
ייצוג ב-JSON |
---|
{
"mode": enum ( |
מצב
הגדרת אופן הפעולה של הפעלת פונקציות על ידי הגדרת מצב ההפעלה.
טיפוסים בני מנייה (enum) | |
---|---|
MODE_UNSPECIFIED |
מצב לא מוגדר של הפעלת פונקציות. אין להשתמש בערך הזה. |
AUTO |
התנהגות ברירת המחדל של המודל, המודל מחליט לחזות קריאה לפונקציה או תגובה בשפה טבעית. |
ANY |
המודל מוגבל לחיזוי של קריאה לפונקציה בלבד. אם מוגדרים שמות של פונקציות מותרות (allowedFunctionNames), הקריאה החזויה לפונקציה תוגבל לאחד מהשמות האלה. אחרת, הקריאה החזויה לפונקציה תהיה אחת מההצהרות על הפונקציות (functionDeclarations) שסופקו. |
NONE |
המודל לא יבצע חיזוי של הפעלה של פונקציה כלשהי. התנהגות המודל זהה למצב שבו לא מועברות הצהרות פונקציה. |
VALIDATED |
המודל מחליט לחזות קריאה לפונקציה או תשובה בשפה טבעית, אבל יאמת קריאות לפונקציה באמצעות פענוח מוגבל. אם מוגדרים שמות של פונקציות מותרות (allowedFunctionNames), הקריאה החזויה לפונקציה תוגבל לאחד מהשמות האלה. אחרת, הקריאה החזויה לפונקציה תהיה אחת מההצהרות על הפונקציות (functionDeclarations) שסופקו. |
RetrievalConfig
LatLng
אובייקט שמייצג זוג של קווי רוחב ואורך. הערך הזה מבוטא כזוג מספרים ממשיים שמייצגים מעלות של קו רוחב ומעלות של קו אורך. אלא אם צוין אחרת, האובייקט הזה חייב להיות תואם ל תקן WGS84. הערכים צריכים להיות בטווחים מנורמלים.
latitude
number
קו הרוחב במעלות. הערך צריך להיות בטווח [-90.0, +90.0].
longitude
number
קו האורך במעלות. הערך חייב להיות בטווח [-180.0, +180.0].
ייצוג ב-JSON |
---|
{ "latitude": number, "longitude": number } |
UsageMetadata
מטא-נתונים על השימוש בתוכן שבמטמון.
totalTokenCount
integer
המספר הכולל של האסימונים שהתוכן שנשמר במטמון צורך.
ייצוג ב-JSON |
---|
{ "totalTokenCount": integer } |