יכול להיות שתעבירו את אותם טוקנים של קלט (תוכן) שוב ושוב למודל של תכונת ה-AI. במקרים כאלה, אפשר במקום זאת לשמור במטמון את התוכן הזה. כלומר, מעבירים את התוכן למודל פעם אחת, שומרים אותו ומתייחסים אליו בבקשות הבאות.
שמירת הקשר במטמון יכולה להפחית באופן משמעותי את זמן הטעינה ואת העלויות של משימות חוזרות שכוללות כמות גדולה של תוכן, כמו כמויות גדולות של טקסט, קובץ אודיו או קובץ וידאו. כמה דוגמאות לתרחישי שימוש נפוצים בתוכן שמור במטמון: מסמכים מפורטים של פרסונות, בסיסי קוד או מדריכים.
מודלים של Gemini מציעים שני מנגנוני שמירה במטמון:
שמירה במטמון באופן מרומז: מופעלת באופן אוטומטי ברוב המודלים, אין הבטחה לחיסכון בעלויות
שמירה במטמון עם הגדרה מפורשת: אפשר להפעיל אותה באופן אופציונלי וידני ברוב המודלים, ובדרך כלל היא מובילה לחיסכון בעלויות
שמירה במטמון באופן מפורש שימושית במקרים שבהם רוצים להגדיל את הסיכוי לחיסכון בעלויות, אבל צריך להשקיע יותר עבודה בפיתוח.
גם במקרים של שמירה במטמון באופן מרומז וגם במקרים של שמירה במטמון באופן מפורש, השדה cachedContentTokenCount במטא-נתונים של התשובה מציין את מספר הטוקנים בחלק של הקלט שנשמר במטמון. לגבי שמירה במטמון באופן מפורש, חשוב לעיין במידע על תמחור בתחתית הדף הזה.
מודלים נתמכים
יש תמיכה בשמירת נתונים במטמון כשמשתמשים במודלים הבאים:
gemini-3.1-pro-preview-
gemini-3.8-flash(וגרסאות ישנות יותר:gemini-3.7-flash,gemini-3.6-flashו-gemini-3.5-flash) -
gemini-3.5-flash-lite(וגםgemini-3.1-flash-lite)
מודלים של Gemini 2.5 לשימוש כללי תומכים ביכולת הזו, אבל כולם הוצאו משימוש.
מודלים ליצירת מדיה (לדוגמה, מודלים של Nana Banana כמו
gemini-3.1-flash-image) לא תומכים בשמירת הקשר במטמון.
מגבלות גודל של תוכן במטמון
לכל מודל יש דרישה למספר מינימלי של טוקנים לתוכן שנשמר במטמון. הגודל המקסימלי נקבע על ידי חלון ההקשר של המודל.
- Gemini מודלים של Pro: לפחות 4,096 טוקנים
- Gemini מודלים של Flash: מינימום 1,024 טוקנים
בנוסף, הגודל המקסימלי של תוכן שאפשר לשמור במטמון באמצעות blob או טקסט הוא 10MB.
שמירה מרומזת במטמון
שמירה במטמון משתמעת מופעלת כברירת מחדל וזמינה ברוב המודלים של Gemini.
אם הבקשה שלכם תגיע לתוכן שנשמר במטמון, Google תעביר באופן אוטומטי את החיסכון בעלויות. ריכזנו כאן כמה דרכים להגדיל את הסיכוי שהבקשה שלכם תשתמש במטמון מרומז:
- כדאי לנסות להוסיף תוכן גדול ונפוץ בתחילת הפרומפט.
- לנסות לשלוח בקשות עם קידומת דומה בפרק זמן קצר.
מספר הטוקנים בחלק של הקלט שנשמר במטמון מופיע בשדה cachedContentTokenCount במטא-נתונים של התשובה.
שמירה מפורשת במטמון
האפשרות 'שמירת נתונים במטמון באופן מפורש' לא מופעלת כברירת מחדל, והיא יכולת אופציונלית של מודלים מסוג Gemini.
כך מגדירים מטמון של תוכן בוטה ועובדים איתו:
ניהול מטמונים של תוכן בוטה, כולל:
שימו לב שמטמון של תוכן בוטה פועל באינטראקציה עם מטמון מרומז, ולכן יכול להיות שייווצר מטמון נוסף מעבר לתוכן הבוטה שנשמר במטמון. כדי למנוע שמירה של נתונים במטמון, אפשר להשבית את השמירה במטמון באופן מרומז ולא ליצור מטמונים מפורשים. מידע נוסף מופיע במאמר הפעלה והשבתה של שמירה במטמון.
יצירה ושימוש במטמון מפורש
כדי ליצור מטמון של תוכן בוטה ולהשתמש בו, צריך:
מידע חשוב על יצירה ושימוש במטמון מפורש
המטמון צריך להיות מיושר עם בקשות הפרומפט של האפליקציה ותבנית לפרומפט של השרת:
הזיכרון מטמון ספציפי לספק Gemini API. הבקשה להצגת ההנחיה באפליקציה צריכה להשתמש באותו ספק.
במקרה של Firebase AI Logic, מומלץ מאוד להשתמש במטמוני תוכן מפורשים רק עם Agent Platform Gemini API (formerly Vertex AI). כל המידע והדוגמאות בדף הזה ספציפיים לספק Gemini API הזה.המטמון ספציפי למודל Gemini. בקשת ההנחיה של האפליקציה צריכה להשתמש באותו מודל.
המטמון ספציפי למיקום כשמשתמשים ב-Agent Platform Gemini API (formerly Vertex AI).
המיקום של המטמון הגלוי צריך להיות זהה למיקום של תבנית לפרומפט של השרת ולמיקום שבו ניגשים למודל בבקשת הפרומפט של האפליקציה.
חשוב לשים לב גם למגבלות ולדרישות הבאות שחלות על שמירת נתונים במטמון באופן מפורש:
אחרי שיוצרים מטמון מפורש, אי אפשר לשנות בו שום דבר חוץ מה-TTL או זמן התפוגה.
אפשר לשמור במטמון כל סוג MIME של קובץ קלט נתמך או אפילו רק טקסט שסופק בבקשה ליצירת המטמון.
אם רוצים לכלול קובץ במטמון, צריך לספק את הקובץ כמזהה URI של Cloud Storage. אסור להשתמש בכתובת URL של דפדפן או של YouTube.
בנוסף, הגבלות הגישה לקובץ נבדקות בזמן יצירת המטמון, והגבלות הגישה לא נבדקות שוב בזמן בקשת המשתמש. לכן, חשוב לוודא שכל הנתונים שנכללים במטמון הגלוי מתאימים לכל משתמש שמבצע בקשה שכוללת את המטמון הזה.
אם רוצים להשתמש בהוראות או בכלים של המערכת (כמו הרצת קוד, URL Context, עיגון עם
Google Search או עיגון עםGoogle Maps ), המטמון עצמו צריך להכיל את ההגדרות שלהם. אי אפשר להגדיר אותם בתבנית לפרומפט של השרת או בבקשת הפרומפט של האפליקציה. שימו לב שתבניות לפרומפט של שרת עדיין לא תומכות בקריאה להפעלת פונקציות (או בצ'אט). לפרטים על הגדרת הוראות ומערכות במטמון, אפשר לעיין במאמר בנושא API בארכיטקטורת REST של Agent Platform Gemini API (formerly Vertex AI).
שלב 1: יצירת המטמון
יוצרים את המטמון באמצעות API בארכיטקטורת REST של Agent Platform Gemini API (formerly Vertex AI).
בדוגמה הבאה נוצר מטמון מפורש של קובץ PDF כתוכן שלו.
תחביר:
PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL" # for example, gemini-3.8-flash
LOCATION="LOCATION" # location for both the cache and the model
MIME_TYPE="MIME_TYPE"
CACHED_CONTENT_URI="CLOUD_STORAGE_FILE_URI" # must be a Cloud Storage URI
CACHE_DISPLAY_NAME="CACHE_DISPLAY_NAME" # optional
TTL="CACHE_TIME_TO_LIVE" # optional (if not specified, defaults to 3600s)
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
"model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
"contents": [
{
"role": "user",
"parts": [
{
"fileData": {
"mimeType": "${MIME_TYPE}",
"fileUri": "${CACHED_CONTENT_URI}"
}
}
]
}
],
"displayName": "${CACHE_DISPLAY_NAME}",
"ttl": "${TTL}"
}
EOF
דוגמה לבקשה:
PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3.8-flash"
LOCATION="global"
MIME_TYPE="application/pdf"
CACHED_CONTENT_URI="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
CACHE_DISPLAY_NAME="Gemini - A Family of Highly Capable Multimodal Model (PDF)"
TTL="7200s"
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
"model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
"contents": [
{
"role": "user",
"parts": [
{
"fileData": {
"mimeType": "${MIME_TYPE}",
"fileUri": "${CACHED_CONTENT_URI}"
}
}
]
}
],
"displayName": "${CACHE_DISPLAY_NAME}",
"ttl": "${TTL}"
}
EOF
דוגמה לתגובה:
התשובה כוללת משאב name שמוגדר במלואו והוא ייחודי למטמון ברמה הגלובלית (שימו לב שהקטע האחרון הוא מזהה המטמון). תצטרכו להשתמש בכל הערך name הזה בשלב הבא של תהליך העבודה.
{
"name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
"model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3.8-flash",
"createTime": "2024-06-04T01:11:50.808236Z",
"updateTime": "2024-06-04T01:11:50.808236Z",
"expireTime": "2024-06-04T02:11:50.794542Z"
}
שלב 2: הפניה למטמון בתבנית של הנחיה לשרת
אחרי שיוצרים את המטמון, מפנים אליו באמצעות name בתוך המאפיין cachedContent של תבנית לפרומפט לשרת.
כשיוצרים תבנית לפרומפט לשרת, צריך לוודא שהיא עומדת בדרישות הבאות:
משתמשים במשאב
nameעם שם מלא מהתשובה כשיוצרים את המטמון. זה לא השם המוצג האופציונלי שציינתם בבקשה.המיקום של תבנית לפרומפט של השרת צריך להיות זהה למיקום של המטמון.
כדי להשתמש בהוראות או בכלים של המערכת, צריך להגדיר אותם כחלק מהמטמון ולא כחלק מתבנית לפרומפט של השרת.
תחביר:
{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}
{{role "user"}}
{{userPrompt}}
לדוגמה:
{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}
{{role "user"}}
{{userPrompt}}
לחלופין, הערך של הפרמטר name בתבנית לפרומפט של השרת יכול להיות משתנה קלט דינמי.
לדוגמה, {{cachedContent name=someVariable}}name של המטמון כקלט לבקשה מהאפליקציה שלכם.
שלב 3: הפניה לתבנית של הנחיית השרת בבקשה מהאפליקציה
כשכותבים את הבקשה, חשוב לשים לב לדברים הבאים:
צריך להשתמש ב-Agent Platform Gemini API (formerly Vertex AI) כי המטמון נוצר באמצעות ספק Gemini API הזה.
המיקום שבו אתם ניגשים למודל בבקשת ההנחיה של האפליקציה צריך להיות זהה למיקום של תבנית ההנחיה של השרת ולמיקום של המטמון.
Swift
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform(location: "LOCATION"))
.templateGenerativeModel()
do {
let response = try await model.generateContent(
// Specify your template ID.
templateID: "TEMPLATE_ID"
)
if let text = response.text {
print("Response Text: \(text)")
}
} catch {
print("An error occurred: \(error)")
}
print("\n")
Kotlin
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
val model = Firebase.ai(backend = GenerativeBackend.agentPlatform(location = "LOCATION"))
.templateGenerativeModel()
val response = model.generateContent(
// Specify your template ID.
"TEMPLATE_ID",
)
val text = response.text
println(text)
Java
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION"))
.templateGenerativeModel();
TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);
Future<GenerateContentResponse> response = model.generateContent(
// Specify your template ID.
"TEMPLATE_ID"
);
addCallback(response,
new FutureCallback<GenerateContentResponse>() {
public void onSuccess(GenerateContentResponse result) {
System.out.println(result.getText());
}
public void onFailure(Throwable t) {
reportError(t);
}
}
executor);
Web
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
const ai = getAI(app, { backend: new AgentPlatformBackend('LOCATION') });
// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);
const result = await model.generateContent(
// Specify your template ID.
'TEMPLATE_ID'
);
const response = result.response;
const text = response.text();
Dart
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
var _model = FirebaseAI.agentPlatform(location: 'LOCATION').templateGenerativeModel()
var response = await _model.generateContent(
// Specify your template ID.
'TEMPLATE_ID',
);
var text = response?.text;
print(text);
Unity
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform(location: "LOCATION"));
// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();
try
{
var response = await model.GenerateContentAsync(
// Specify your template ID.
"TEMPLATE_ID"
);
Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
Debug.LogError($"An error occurred: {e.Message}");
}
ניהול מטמונים מפורשים
בקטע הזה מוסבר איך לנהל מטמונים של תוכן גלוי, כולל איך לפרט את כל המטמונים, לקבל מטא-נתונים על מטמון, לעדכן את ה-TTL או את תאריך התפוגה של מטמון ולמחוק מטמון.
אתם מנהלים מטמונים מפורשים באמצעות API בארכיטקטורת REST של Agent Platform Gemini API (formerly Vertex AI).
אחרי שיוצרים מטמון של תוכן בוטה, אי אפשר לשנות שום דבר במטמון חוץ מה-TTL או זמן התפוגה.
רשימה של כל מטמוני הנתונים
אתם יכולים להציג רשימה של כל המטמונים הגלויים שזמינים לפרויקט. הפקודה הזו תחזיר רק את המטמונים במיקום שצוין.
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents
אחזור מטא-נתונים של מטמון
אי אפשר לאחזר או לראות את התוכן בפועל שנשמר במטמון. עם זאת, אפשר לאחזר מטא-נתונים לגבי מטמון מפורש, כולל name, model, display_name, usage_metadata, create_time, update_time ו-expire_time.
צריך לספק את CACHE_ID, שהוא הפלח האחרון בname המלא של המשאב במטמון.
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}
עדכון ה-TTL או תאריך התפוגה של מטמון
כשיוצרים מטמון מפורש, אפשר להגדיר את ttl או את expire_time.
ttl: אורך החיים (TTL) של המטמון, כלומר מספר השניות והננו-שניות שבהן המטמון פעיל אחרי שהוא נוצר או אחרי שמתבצע עדכון שלttlלפני שהוא פג. כשמגדירים אתttl, ה-expireTimeשל המטמון מתעדכן באופן אוטומטי.
expire_time: ערךTimestamp(לדוגמה,2024-06-30T09:00:00.000000Z) שמציין את התאריך והשעה המוחלטים שבהם תוקף המטמון פג.
אם לא מגדירים אף אחד מהערכים האלה, ערך ברירת המחדל של TTL הוא שעה אחת. אין גבולות מינימליים או מקסימליים ל-TTL.
במטמון קיים עם הגדרה מפורשת, אפשר להוסיף או לעדכן את ttl או expire_time.
צריך לספק את CACHE_ID, שהוא הפלח האחרון בname המלא של המשאב במטמון.
עדכון ttl
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
TTL="CACHE_TIME_TO_LIVE"
curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
"ttl": "'$TTL'"
}'
עדכון expire_time
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
EXPIRE_TIME="ABSOLUTE_TIME_CACHE_EXPIRES"
curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
"expire_time": "'$EXPIRE_TIME'"
}'
מחיקת מטמון
כשאין יותר צורך במטמון מפורש, אפשר למחוק אותו.
צריך לספק את CACHE_ID, שהוא הפלח האחרון בname המלא של המשאב במטמון.
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}
תמחור של שמירת נתונים במטמון
שמירת נתונים במטמון באופן מפורש היא תכונה בתשלום שנועדה להפחית את העלויות. התמחור מבוסס על הגורמים הבאים:
אסימוני קלט ליצירת מטמון: גם במטמון מרומז וגם במטמון מפורש, אתם מחויבים על אסימוני הקלט שמשמשים ליצירת המטמון במחיר הרגיל של אסימוני הקלט.
אחסון המטמון: בשמירה מפורשת במטמון, יש גם עלויות אחסון שמבוססות על משך הזמן שבו המטמון מאוחסן. אין עלויות אחסון עבור שמירה במטמון באופן מרומז. מידע נוסף מופיע במחירון של Agent Platform Gemini API (formerly Vertex AI).
שימוש בתוכן במטמון: שמירה במטמון באופן מפורש מבטיחה הנחה כשמתייחסים למטמונים מפורשים, כלומר מקבלים הנחה על אסימוני הקלט כשמתייחסים למטמון קיים. בדגמים Gemini 2.5 ואילך, ההנחה היא 90%.
מספר הטוקנים בחלק של הקלט שנשמר במטמון מופיע בשדה cachedContentTokenCount במטא-נתונים של התשובה.