‫Gemini 2.5 Flash Image (שנקרא גם Nano Banana) זמין עכשיו ב-Gemini API! מידע נוסף

דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

שמירת מטמון משתמעת מופעלת כברירת מחדל בכל מודלי Gemini 2.5. אם הבקשה שלכם מגיעה למטמון, אנחנו מעבירים לכם באופן אוטומטי את החיסכון בעלויות. לא צריך לעשות שום דבר כדי להפעיל את התכונה הזו. היא תיכנס לתוקף ב-8 במאי 2025. מספר הטוקנים המינימלי של הקלט לשימוש במטמון ההקשר הוא 1,024 ל-2.5 Flash ו-4,096 ל-2.5 Pro.

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

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

אפשר לראות את מספר הטוקנים שהיו פגיעות במטמון בשדה 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 video file
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():
  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(file=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-2.0-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)

קובצי PDF

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

client = genai.Client()

long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.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-2.0-flash-001"
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],
    )
)

# Display the cache details
print(f'{cache=}')

# Generate content using the cached prompt and document
response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

# (Optional) Print usage metadata for insights into the API call
print(f'{response.usage_metadata=}')

# Print the generated text
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.

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

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

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

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

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

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

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

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

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

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