יכול להיות שתעבירו את אותם טוקנים של קלט (תוכן) שוב ושוב למודל של תכונת ה-AI. בתרחישי השימוש האלה, אפשר במקום זאת לשמור במטמון את התוכן הזה. כלומר, מעבירים את התוכן למודל פעם אחת, שומרים אותו ומתייחסים אליו בבקשות הבאות.
שימוש במטמון הקשר יכול להקטין באופן משמעותי את זמן האחזור ואת העלות של משימות חוזרות שכוללות כמות גדולה של תוכן, כמו כמויות גדולות של טקסט, קובץ אודיו או קובץ וידאו. דוגמאות לתרחישים נפוצים שבהם כדאי להשתמש בתוכן שמור במטמון: מסמכים מפורטים של דמויות, בסיסי קוד או מדריכים.
מודלים של Gemini מציעים שני מנגנוני שמירה במטמון:
שמירה במטמון באופן מרומז: מופעלת באופן אוטומטי ברוב הדגמים, אין הבטחה לחיסכון בעלויות
שמירה במטמון באופן מפורש: אפשר להפעיל אותה באופן אופציונלי וידני ברוב המודלים, ובדרך כלל היא מובילה לחיסכון בעלויות
שמירת נתונים במטמון באופן מפורש שימושית במקרים שבהם רוצים להגדיל את הסיכוי לחיסכון בעלויות, אבל צריך להשקיע קצת יותר עבודה בפיתוח.
גם במקרים של שמירה במטמון באופן מרומז וגם במקרים של שמירה במטמון באופן מפורש, השדה cachedContentTokenCount במטא-נתונים של התשובה מציין את מספר הטוקנים בחלק של הקלט שנשמר במטמון. לגבי שמירה במטמון באופן מפורש, חשוב לעיין במידע על תמחור בתחתית הדף הזה.
מודלים נתמכים
יש תמיכה בשמירת נתונים במטמון כשמשתמשים במודלים הבאים:
gemini-3.1-pro-previewgemini-3-flash-previewgemini-3.1-flash-lite-previewgemini-2.5-progemini-2.5-flashgemini-2.5-flash-lite
מודלים ליצירת מדיה (לדוגמה, מודלים של Nana Banana כמו
gemini-3.1-flash-image-preview) לא תומכים בשמירת מטמון של ההקשר.
מגבלות גודל של תוכן במטמון
לכל מודל יש דרישה לגבי מספר האסימונים המינימלי לתוכן שנשמר במטמון. הגודל המקסימלי נקבע לפי חלון ההקשר של המודל.
- Gemini מודלים של Pro: מינימום 4,096 טוקנים
- Gemini מודלים של Flash: מינימום 1,024 טוקנים
בנוסף, הגודל המקסימלי של תוכן שאפשר לשמור במטמון באמצעות blob או טקסט הוא 10MB.
שמירה מרומזת במטמון
שמירת נתונים במטמון באופן מרומז מופעלת כברירת מחדל וזמינה ברוב המודלים של Gemini.
אם הבקשה שלכם מגיעה לתוכן שנשמר במטמון, Google מעבירה באופן אוטומטי את החיסכון בעלויות. ריכזנו כאן כמה דרכים להגדיל את הסיכוי שהבקשה תשתמש במטמון מרומז:
- כדאי לנסות להוסיף תוכן גדול ונפוץ בתחילת ההנחיה.
- לנסות לשלוח בקשות עם קידומת דומה בפרק זמן קצר.
מספר הטוקנים בחלק המאוחסן במטמון של הקלט מופיע בשדה cachedContentTokenCount במטא-נתונים של התשובה.
שמירה מפורשת במטמון
האפשרות 'שמירת נתונים במטמון' לא מופעלת כברירת מחדל, והיא יכולת אופציונלית של מודלים של Gemini.
כך מגדירים מטמון של תוכן בוטה ועובדים איתו:
ניהול מטמונים של תוכן בוטה, כולל:
שימו לב שמטמון של תוכן בוטה פועל באינטראקציה עם מטמון מרומז, ולכן יכול להיות שייווצר מטמון נוסף מעבר לתוכן הבוטה שנשמר במטמון. כדי למנוע שמירה של נתונים במטמון, אפשר להשבית את המטמון המרומז ולא ליצור מטמון מפורש. מידע נוסף מופיע במאמר הפעלה והשבתה של שמירה במטמון.
יצירה של מטמון מפורש ושימוש בו
כדי ליצור מטמון של תוכן בוטה ולהשתמש בו, צריך:
מידע חשוב על יצירה ושימוש במטמון מפורש
הזיכרון מטמון צריך להיות תואם לבקשות להנחיות באפליקציה ולתבנית ההנחיות בשרת:
הזיכרון מטמון ספציפי לספק Gemini API. הבקשה להצגת ההנחיה באפליקציה צריכה להשתמש באותו ספק.
במקרה של Firebase AI Logic, מומלץ מאוד להשתמש במטמוני תוכן מפורשים רק עם Vertex AI Gemini API. כל המידע והדוגמאות בדף הזה ספציפיים לספק Gemini API.המטמון ספציפי למודל Gemini. בקשת ההנחיה של האפליקציה צריכה להשתמש באותו מודל.
המטמון ספציפי למיקום כשמשתמשים ב-Vertex AI Gemini API.
המיקום של המטמון הגלוי צריך להיות זהה למיקום של תבנית ההנחיה לשרת ולמיקום שבו ניגשים למודל בבקשת ההנחיה של האפליקציה.
חשוב לשים לב גם למגבלות ולדרישות הבאות שחלות על שמירת מטמון מפורשת:
אחרי שיוצרים מטמון מפורש, אי אפשר לשנות שום דבר במטמון חוץ מה-TTL או זמן התפוגה.
אפשר לשמור במטמון כל סוג MIME של קובץ קלט נתמך או אפילו רק טקסט שסופק בבקשה ליצירת מטמון.
אם רוצים לכלול קובץ במטמון, צריך לספק את הקובץ כ-URI Cloud Storage. אסור להשתמש בכתובת URL של דפדפן או של YouTube.
בנוסף, הגבלות הגישה לקובץ נבדקות בזמן יצירת המטמון, והגבלות הגישה לא נבדקות שוב בזמן בקשת המשתמש. לכן, חשוב לוודא שכל הנתונים שנכללים במטמון הגלוי מתאימים לכל משתמש שמבצע בקשה שכוללת את המטמון הזה.
אם רוצים להשתמש בהוראות או בכלים של המערכת (כמו הפעלת קוד, הקשר של כתובת URL או ביסוס על חיפוש Google), המטמון עצמו צריך להכיל את ההגדרות שלהם. אי אפשר להגדיר אותם בתבנית של הנחיית השרת או בבקשת ההנחיה של האפליקציה. שימו לב שתבניות של הנחיות לשרת עדיין לא תומכות בהפעלת פונקציות (או בצ'אט). פרטים על הגדרת הוראות ומאגרי כלים במטמון זמינים במאמר בנושא API בארכיטקטורת REST של Vertex AI Gemini API.
שלב 1: יצירת המטמון
יוצרים את המטמון באמצעות API בארכיטקטורת REST של Vertex AI Gemini API.
בדוגמה הבאה נוצר מטמון מפורש של קובץ PDF כתוכן שלו.
תחביר:
PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL" # for example, gemini-3-flash-preview
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-flash-preview"
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-flash-preview",
"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: מפנים לתבנית ההנחיה של השרת בבקשה מהאפליקציה
כשכותבים את הבקשה, חשוב לשים לב לדברים הבאים:
צריך להשתמש ב-Vertex AI Gemini API כי המטמון נוצר באמצעות ספק Gemini API.
המיקום שבו ניגשים למודל בבקשת ההנחיה של האפליקציה צריך להיות זהה למיקום של תבנית ההנחיה של השרת ולמיקום של המטמון.
Swift
// ...
// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
let model = FirebaseAI.firebaseAI(backend: .vertexAI(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 Vertex AI Gemini API backend service
// 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.vertexAI(location = "LOCATION"))
.templateGenerativeModel()
val response = model.generateContent(
// Specify your template ID
"TEMPLATE_ID",
)
val text = response.text
println(text)
Java
// ...
// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().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 Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
const ai = getAI(app, { backend: new VertexAIBackend('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 Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
var _model = FirebaseAI.vertexAI(location: 'LOCATION').templateGenerativeModel()
var response = await _model.generateContent(
// Specify your template ID
'TEMPLATE_ID',
);
var text = response?.text;
print(text);
Unity
// ...
// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(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 של Vertex AI Gemini API.
אחרי שיוצרים מטמון של תוכן בוטה, אי אפשר לשנות שום דבר במטמון חוץ מה-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}
תמחור של שמירת נתונים במטמון
שמירת נתונים במטמון באופן מפורש היא תכונה בתשלום שנועדה להפחית את העלויות. התמחור מבוסס על הגורמים הבאים:
אסימוני קלט ליצירת מטמון: גם במטמון מרומז וגם במטמון מפורש, אתם מחויבים על אסימוני הקלט שמשמשים ליצירת המטמון במחיר הרגיל של אסימוני הקלט.
אחסון של מטמון: בשמירה מפורשת במטמון, יש גם עלויות אחסון שמבוססות על משך הזמן שבו המטמון מאוחסן. אין עלויות אחסון עבור שמירה במטמון באופן מרומז. מידע נוסף מפורט במחירון של Vertex AI Gemini API.
שימוש בתוכן שנשמר במטמון: שמירה במטמון באופן מפורש מבטיחה הנחה כשמתבצעת הפניה למטמון מפורש, כלומר מקבלים הנחה על אסימוני הקלט כשמתבצעת הפניה למטמון קיים. בדגמים Gemini 2.5 ואילך, ההנחה היא 90%.
מספר הטוקנים בחלק המאוחסן במטמון של הקלט מופיע בשדה cachedContentTokenCount במטא-נתונים של התשובה.