שמירת הקשר במטמון

Python JavaScript Go REST

בתהליך עבודה טיפוסי של AI, יכול להיות שתעבירו את אותם אסימוני קלט שוב ושוב למודל. ‫Gemini API מציע שני מנגנוני שמירת נתונים במטמון:

• שמירה במטמון באופן מרומז (מופעלת אוטומטית ברוב המודלים של Gemini, אין הבטחה לחיסכון בעלויות)
• שמירה במטמון באופן מפורש (אפשר להפעיל אותה באופן ידני ברוב המודלים, מובטח חיסכון בעלויות)

שימוש במטמון מפורש מועיל במקרים שבהם רוצים להבטיח חיסכון בעלויות, אבל צריך להשקיע קצת יותר עבודה בפיתוח.

שמירה מרומזת במטמון

האפשרות 'שמירה במטמון באופן מרומז' מופעלת כברירת מחדל וזמינה ברוב המודלים של Gemini. אם הבקשה שלכם מגיעה למטמון, אנחנו מעבירים את החיסכון בעלויות באופן אוטומטי. לא צריך לעשות שום דבר כדי להפעיל את התכונה הזו. היא תיכנס לתוקף ב-8 במאי 2025. בטבלה הבאה מפורט מספר האסימונים המינימלי של הקלט לזיכרון מטמון של הקשר לכל מודל:

כדי להגדיל את הסיכוי לפגיעה במטמון משתמע:

• כדאי לנסות להוסיף תוכן גדול ונפוץ בתחילת ההנחיה
• ניסיון לשלוח בקשות עם קידומת דומה בפרק זמן קצר

אפשר לראות את מספר הטוקנים שהיו פגיעות במטמון בשדה usage_metadata של אובייקט התגובה.

שמירה מפורשת במטמון

באמצעות התכונה של Gemini API לניהול מטמון, אתם יכולים להעביר תוכן מסוים למודל פעם אחת, לשמור במטמון את טוקני הקלט ואז להפנות לטוקנים שנשמרו במטמון בבקשות הבאות. בנפחים מסוימים, העלות של שימוש בטוקנים במטמון נמוכה יותר מהעלות של העברת אותה קבוצת טוקנים שוב ושוב.

כשמטמנים קבוצה של טוקנים, אפשר לבחור כמה זמן המטמון יתקיים לפני שהטוקנים יימחקו אוטומטית. משך השמירה במטמון נקרא אורך חיים (TTL). אם לא מגדירים את ה-TTL, ברירת המחדל היא שעה אחת. העלות של שמירת נתונים במטמון תלויה בגודל של טוקן הקלט ובמשך הזמן שבו רוצים שהטוקנים יישמרו.

בסעיף הזה מניחים שהתקנתם Gemini SDK (או שהתקנתם curl) והגדרתם מפתח API, כמו שמוסבר במדריך למתחילים.

יצירת תוכן באמצעות מטמון

בדוגמה הבאה מוצג תהליך ליצירת תוכן באמצעות הוראה במערכת וקובץ וידאו שמאוחסנים במטמון.

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

client = genai.Client()

# Download a test video file and save it locally
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
    path_to_video_file.write_bytes(requests.get(url).content)

# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)

# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
    time.sleep(2.5)
    video_file = client.files.get(name=video_file.name)

print(f'Video processing complete: {video_file.uri}')

model='models/gemini-3-flash-preview'

# Create a cache with a 5 minute TTL (300 seconds)
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",
    )
)

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)

print(response.text)

from google import genai
from google.genai import types
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"

# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

document = client.files.upload(
  file=doc_io,
  config=dict(mime_type='application/pdf')
)

model_name = "gemini-3-flash-preview"
system_instruction = "You are an expert analyzing transcripts."

# Create a cached content object
cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
      system_instruction=system_instruction,
      contents=[document],
    )
)

print(f'{cache=}')

response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

print(f'{response.usage_metadata=}')

print('\n\n', 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)

שמירת נתונים במטמון באופן מפורש באמצעות ספריית OpenAI

אם אתם משתמשים בספריית OpenAI, אתם יכולים להפעיל שמירה במטמון באופן מפורש באמצעות המאפיין cached_content ב-extra_body.

מתי כדאי להשתמש בשמירת נתונים במטמון באופן מפורש

שמירת ההקשר במטמון מתאימה במיוחד לתרחישים שבהם בקשות קצרות יותר מפנות שוב ושוב להקשר ראשוני משמעותי. כדאי להשתמש בשמירה במטמון של ההקשר בתרחישים כמו:

• צ'אט בוטים עם הוראות מערכת מפורטות
• ניתוח חוזר של קובצי וידאו ארוכים
• שאילתות חוזרות על קבוצות גדולות של מסמכים
• ניתוח תכוף של מאגר קוד או תיקון באגים

איך שמירת מטמון מפורשת מפחיתה עלויות

שמירת ההקשר במטמון היא תכונה בתשלום שנועדה להפחית את העלויות. החיוב מבוסס על הגורמים הבאים:

1. מספר הטוקנים במטמון: מספר הטוקנים של הקלט שנשמרו במטמון. אם הם נכללים בהנחיות הבאות, הם מחויבים במחיר מופחת.
2. משך האחסון: משך הזמן שבו טוקנים במטמון מאוחסנים (TTL), החיוב מתבצע על סמך משך ה-TTL של ספירת הטוקנים במטמון. אין ערכי מינימום או מקסימום ל-TTL.
3. גורמים אחרים: חלים חיובים אחרים, למשל על טוקנים של קלט ופלט שלא נשמרו במטמון.

פרטים עדכניים על התמחור זמינים בדף התמחור של Gemini API. במדריך לאסימונים מוסבר איך לספור אסימונים.

שיקולים נוספים

כשמשתמשים בשמירת מטמון של הקשר, חשוב לזכור את הנקודות הבאות:

• מספר הטוקנים המינימלי של הקלט לזיכרון מטמון של ההקשר משתנה בהתאם למודל. הערך המקסימלי זהה לערך המקסימלי של המודל הנתון. (מידע נוסף על ספירת אסימונים זמין במדריך האסימונים).
• המודל לא מבחין בין טוקנים במטמון לבין טוקנים רגילים של קלט. התוכן שנשמר במטמון מופיע כקידומת להנחיה.
• אין הגבלות מיוחדות על שיעור השימוש או על שיעור הבקשות במטמון ההקשר. חלות ההגבלות הרגילות על שיעור הבקשות ב-GenerateContent, והגבלות האסימונים כוללות אסימונים במטמון.
• מספר האסימונים שנשמרו במטמון מוחזר ב-usage_metadata מפעולות היצירה, האחזור והרשימה של שירות המטמון, וגם ב-GenerateContent כשמשתמשים במטמון.