בתהליך עבודה טיפוסי של AI, יכול להיות שתעבירו שוב ושוב את אותם אסימוני קלט למודל. באמצעות התכונה של Gemini API לשמירת מטמון לפי הקשר, אפשר להעביר תוכן מסוים למודל פעם אחת, לשמור במטמון את אסימוני הקלט ואז להפנות לאסימונים ששמורים במטמון לבקשות הבאות. בנפח מסוים, השימוש באסימונים ששמורים במטמון זול יותר מהעברה חוזרת של אותו גוף של אסימונים.
כששומרים במטמון קבוצה של אסימונים, אפשר לבחור את משך הזמן שבו האסימונים יישארו במטמון לפני שהם יימחקו באופן אוטומטי. משך הזמן הזה ששמור במטמון נקרא אורך החיים (TTL). אם לא מגדירים את TTL, ברירת המחדל היא שעה אחת. העלות של שמירת האסימונים במטמון תלויה בגודל אסימון הקלט ובמשך הזמן שבו רוצים לשמור את האסימונים.
שמירת הקשר במטמון תומכת גם ב-Gemini 1.5 Pro וגם ב-Gemini 1.5 Flash.
מתי כדאי להשתמש בשמירת הקשר במטמון
שמירת הקשר במטמון מתאימה במיוחד לתרחישים שבהם הקשר ראשוני משמעותי מופיע שוב ושוב בבקשות קצרות יותר. כדאי להשתמש בשמירה במטמון לפי הקשר בתרחישים לדוגמה כמו:
- צ'אט בוטים עם הוראות מפורטות למערכת
- ניתוח חוזר של קובצי וידאו ארוכים
- שאילתות חוזרות על קבוצות גדולות של מסמכים
- ניתוח תדיר של מאגר הקוד או תיקון באגים
איך אחסון במטמון מפחית עלויות
שמירת הקשר במטמון היא תכונה בתשלום שנועדה להפחית את העלויות הכוללות של התפעול. החיוב מבוסס על הגורמים הבאים:
- מספר האסימונים ששמורים במטמון: מספר האסימונים של הקלט ששמורים במטמון, שעבורם מתבצעת חיוב במחיר מוזל כשהם נכללים בהנחיות הבאות.
- משך האחסון: משך הזמן שבו טוקנים נשמרים במטמון (TTL). החיוב מתבצע על סמך משך ה-TTL של ספירת הטוקנים במטמון. אין גבולות מינימום או מקסימום ל-TTL.
- גורמים אחרים: חלים חיובים אחרים, כמו על אסימוני קלט ואסימוני פלט שלא שמורים במטמון.
פרטי התמחור העדכניים מפורטים בדף התמחור של Gemini API. במאמר מדריך אסימונים מוסבר איך ספציפית מנהלים אסימונים.
איך משתמשים במטמון הקשר
בסעיף הזה נניח שכבר התקנתם את Gemini SDK (או ש-curl מותקן אצלכם) ושהגדרתם מפתח API, כפי שמתואר במדריך למתחילים.
יצירת תוכן באמצעות מטמון
בדוגמה הבאה מוסבר איך ליצור תוכן באמצעות הוראה מערכתית וקובץ וידאו שנשמרו במטמון.
import os
import pathlib
import requests
import time
from google import genai
from google.genai import types
# Get your API key from https://aistudio.google.com/app/apikey
# Put it in a "GOOGLE_API_KEY" environment variable.
# For more details, see
# https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb
client = genai.Client()
# Download video file
url = 'https://storage.googleapis.com/generativeai-downloads/data/Sherlock_Jr_FullMovie.mp4'
path_to_video_file = pathlib.Path('Sherlock_Jr_FullMovie.mp4')
if not path_to_video_file.exists():
with path_to_video_file.open('wb') as wf:
response = requests.get(url, stream=True)
for chunk in response.iter_content(chunk_size=32768):
wf.write(chunk)
# Upload the video using the Files API
video_file = client.files.upload(path=path_to_video_file)
# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
print('Waiting for video to be processed.')
time.sleep(2)
video_file = client.files.get(name=video_file.name)
print(f'Video processing complete: {video_file.uri}')
# You must use an explicit version suffix. "-flash-001", not just "-flash".
model='models/gemini-1.5-flash-001'
# Create a cache with a 5 minute TTL
cache = client.caches.create(
model=model,
config=types.CreateCachedContentConfig(
display_name='sherlock jr movie', # used to identify the cache
system_instruction=(
'You are an expert video analyzer, and your job is to answer '
'the user\'s query based on the video file you have access to.'
),
contents=[video_file],
ttl="300s",
)
)
# Construct a GenerativeModel which uses the created cache.
response = client.models.generate_content(
model = model,
contents= (
'Introduce different characters in the movie by describing '
'their personality, looks, and names. Also list the timestamps '
'they were introduced for the first time.'),
config=types.GenerateContentConfig(cached_content=cache.name)
)
print(response.usage_metadata)
# The output should look something like this:
#
# prompt_token_count: 696219
# cached_content_token_count: 696190
# candidates_token_count: 214
# total_token_count: 696433
print(response.text)
הצגת רשימה של מטמונים
אי אפשר לאחזר או להציג תוכן שנשמר במטמון, אבל אפשר לאחזר את המטא-נתונים של המטמון (name
, model
, display_name
, usage_metadata
, create_time
, update_time
ו-expire_time
).
כדי לקבל רשימה של המטא-נתונים של כל המטמון שהועלו, משתמשים ב-CachedContent.list()
:
for cache in client.caches.list():
print(cache)
כדי לאחזר את המטא-נתונים של אובייקט מטמון אחד, אם ידוע לכם השם שלו, השתמשו ב-get
:
client.caches.get(name=name)
עדכון מטמון
אפשר להגדיר ttl
או expire_time
חדשים למטמון. אין תמיכה בשינוי של פרטים אחרים במטמון.
בדוגמה הבאה מוסבר איך לעדכן את ttl
של מטמון באמצעות client.caches.update()
.
from google import genai
from google.genai import types
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
ttl='300s'
)
)
כדי להגדיר את זמן התפוגה, אפשר להשתמש באובייקט datetime
או במחרוזת תאריך ושעה בפורמט ISO (dt.isoformat()
, כמו 2025-01-27T16:02:36.473528+00:00
). השעה חייבת לכלול אזור זמן (datetime.utcnow()
לא מצרף אזור זמן, datetime.now(datetime.timezone.utc)
כן מצרף אזור זמן).
from google import genai
from google.genai import types
import datetime
# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
expire_time=in10min
)
)
מחיקת מטמון
שירות האחסון במטמון מספק פעולת מחיקה להסרת תוכן מהמטמון באופן ידני. הדוגמה הבאה ממחישה איך מוחקים מטמון:
client.caches.delete(cache.name)
שיקולים נוספים
כשמשתמשים במטמון הקשר, חשוב לזכור את הנקודות הבאות:
- המספר המינימלי של אסימוני הקלט לשמירת הקשר במטמון הוא 32,768, והמספר המקסימלי זהה למספר המקסימלי של המודל הנתון. (מידע נוסף על ספירת אסימונים זמין במדריך בנושא אסימונים).
- המודל לא מבדיל בין אסימונים שנשמרו במטמון לבין אסימוני קלט רגילים. תוכן ששמור במטמון הוא פשוט קידומת להנחיה.
- אין מגבלות מיוחדות על קצב או על שימוש בשמירת הקשר במטמון. מגבלות הקצב הרגילות של
GenerateContent
חלות, ומגבלות האסימונים כוללות אסימונים שנשמרו במטמון. - מספר האסימונים שנשמרו במטמון מוחזר ב-
usage_metadata
מהפעולות create, get ו-list של שירות המטמון, וגם ב-GenerateContent
כשמשתמשים במטמון.