בפיצ'ר מבוסס-AI, יכול להיות שתעבירו למודל את אותם אסימוני קלט (תוכן) שוב ושוב. במקרים כאלה, אתם יכולים לשמור במטמון את התוכן הזה. כלומר, אתם מעבירים את התוכן למודל פעם אחת, שומרים אותו ומפנים אליו בבקשות הבאות.
שמירת הקשר במטמון יכולה להפחית משמעותית את זמן האחזור ואת העלות של משימות שחוזרות על עצמן וכוללות כמות גדולה של תוכן, כמו כמויות גדולות של טקסט, קובץ אודיו או קובץ וידאו. תרחישים נפוצים לשימוש בתוכן שנשמר במטמון כוללים מסמכים מפורטים של פרסונות, בסיסי קוד או מדריכים.
במודלים של Gemini יש שני מנגנוני שמירה במטמון:
שמירה במטמון באופן משתמע: מופעלת באופן אוטומטי ברוב המודלים, לא מבטיחה חיסכון בעלויות
שמירה מפורשת במטמון: אפשר להפעיל אותה באופן ידני ואופציונלי ברוב המודלים, ובדרך כלל היא חוסכת בעלויות.
שמירה מפורשת במטמון שימושית במקרים שבהם רוצים להבטיח חיסכון בעלויות, אבל נדרשת עבודת פיתוח נוספת.
בשמירה במטמון, גם המפורשת וגם המשתמעת, השדה cachedContentTokenCount במטא-נתונים של התשובה מציין את מספר הטוקנים בחלק של הקלט שנשמר במטמון. לגבי שמירה מפורשת במטמון, חשוב לעיין במידע על התמחור שמופיע בתחתית הדף הזה.
מודלים נתמכים
אפשר להשתמש בשמירה במטמון במודלים הבאים:
-
gemini-4-hydrogen(רק שמירה מרומזת במטמון, אין תמיכה בשמירה מפורשת במטמון) -
gemini-4-argon(רק שמירה מרומזת במטמון, אין תמיכה בשמירה מפורשת במטמון) -
gemini-4-carbon(רק שמירה מרומזת במטמון, אין תמיכה בשמירה מפורשת במטמון) gemini-3.8-flash-
gemini-3.5-flash-lite(והגרסה הישנה יותרgemini-3.1-flash-lite)
מודלים ישנים יותר של Gemini 3.x Flash לשימוש כללי תומכים ביכולת הזו, אבל אנחנו לא ממליצים להשתמש בהם כי הם יושבתו בקרוב או שהבקשות ינותבו אוטומטית למודלים חדשים יותר.
מודלים ליצירת מדיה (לדוגמה, מודלים של Gemini Nano Banana כמו gemini-nano-banana-2.1) לא תומכים בשמירת הקשר במטמון.
מגבלות הגודל של תוכן במטמון
לכל מודל יש דרישה למספר מינימלי של אסימונים לתוכן במטמון. המספר המקסימלי נקבע לפי חלון ההקשר של המודל.
- Gemini 4 Hydrogen, Gemini 4 Carbon ו-Gemini 4 Argon: מינימום 4,096 טוקנים (Gemini Developer API) או מינימום 6,144 טוקנים (Agent Platform Gemini API (formerly Vertex AI))
- מודלים של Gemini Pro: לפחות 4,096 טוקנים
- מודלים של Gemini Flash: מינימום 1,024 טוקנים
בנוסף, הגודל המקסימלי של תוכן שאפשר לשמור במטמון באמצעות blob או טקסט הוא 10MB.
שמירה מרומזת במטמון
שמירה במטמון באופן משתמע מופעלת כברירת מחדל וזמינה ברוב המודלים של Gemini.
Google מעבירה באופן אוטומטי את החיסכון בעלויות אם הבקשה שלכם מגיעה לתוכן שנשמר במטמון. הנה כמה דרכים להגדיל את הסיכוי שהבקשה תשתמש במטמון משתמע:
- נסו להציב תוכן נפוץ וגדול בתחילת ההנחיה.
- נסו לשלוח בקשות עם קידומת דומה בפרק זמן קצר.
מספר הטוקנים בחלק של הקלט שנשמר במטמון מופיע בשדה cachedContentTokenCount במטא-נתונים של התשובה.
שמירה מפורשת במטמון
שמירה מפורשת במטמון לא מופעלת כברירת מחדל, והיא יכולת אופציונלית של מודלי Gemini.
שימו לב שהמודלים gemini-4-hydrogen, gemini-4-carbon ו-gemini-4-argon לא תומכים בשמירה מפורשת במטמון.
כך מגדירים מטמונים מפורשים ועובדים איתם:
ניהול מטמונים מפורשים, כולל:
חשוב לדעת שהמטמונים של התוכן המפורש פועלים יחד עם המטמון המשתמע, מה שעלול להוביל לשמירה נוספת במטמון מעבר לתוכן המפורש שנשמר במטמון. כדי למנוע שמירת נתונים במטמון, אפשר להשבית את השמירה המשתמעת במטמון ולא ליצור מטמונים מפורשים. מידע נוסף זמין במאמר הפעלה והשבתה של שמירה במטמון.
יצירה ושימוש במטמון מפורש
כדי ליצור מטמון תוכן מפורש ולהשתמש בו, צריך:
מידע חשוב על יצירה ושימוש במטמון מפורש
המטמון צריך להיות תואם לבקשות הפרומפטים של האפליקציה ולתבנית לפרומפט של השרת:
המטמון ספציפי לספק 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, Grounding עם
Google Search או Grounding עם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.
templateId: 'TEMPLATE_ID',
templateVariables: {},
});
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',
inputs: {},
);
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",
new Dictionary<string, object>()
);
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 במטא-נתונים של התשובה.