در یک گردش کار معمول هوش مصنوعی، ممکن است توکن‌های ورودی یکسانی را بارها و بارها به یک مدل ارسال کنید. API Gemini دو مکانیسم ذخیره‌سازی مختلف ارائه می‌دهد:
- ذخیره سازی ضمنی (به طور خودکار در مدل های Gemini 2.5 فعال است، بدون تضمین صرفه جویی در هزینه)
- ذخیره سازی صریح (در اکثر مدل ها می توان به صورت دستی فعال کرد، تضمین صرفه جویی در هزینه)
ذخیره‌سازی صریح در مواردی مفید است که می‌خواهید صرفه‌جویی در هزینه را تضمین کنید، اما با مقداری کار توسعه‌دهنده‌ی اضافی.
ذخیره سازی ضمنی
ذخیره‌سازی ضمنی (Implicit caching) به طور پیش‌فرض برای همه مدل‌های Gemini 2.5 فعال است. اگر درخواست شما به حافظه پنهان (cache) برسد، ما به طور خودکار صرفه‌جویی در هزینه را اعمال می‌کنیم. برای فعال کردن این قابلیت، نیازی به انجام هیچ کاری از سوی شما نیست. این قابلیت از ۸ مه ۲۰۲۵ لازم‌الاجرا است. حداقل تعداد توکن ورودی برای ذخیره‌سازی زمینه (context caching) برای نسخه ۲.۵ Flash، ۱۰۲۴ و برای نسخه ۲.۵ Pro، ۴۰۹۶ است.
برای افزایش احتمال برخورد با حافظه پنهان ضمنی:
- سعی کنید مطالب بزرگ و رایج را در ابتدای درخواست خود قرار دهید.
- سعی کنید درخواست‌هایی با پیشوند مشابه را در مدت زمان کوتاهی ارسال کنید
می‌توانید تعداد توکن‌هایی که در حافظه پنهان (cache hits) بوده‌اند را در فیلد usage_metadata شیء پاسخ مشاهده کنید.
ذخیره سازی صریح
با استفاده از ویژگی ذخیره‌سازی صریح API Gemini، می‌توانید یک بار مقداری محتوا را به مدل ارسال کنید، توکن‌های ورودی را ذخیره کنید و سپس برای درخواست‌های بعدی به توکن‌های ذخیره‌شده مراجعه کنید. در حجم‌های خاص، استفاده از توکن‌های ذخیره‌شده هزینه کمتری نسبت به ارسال مکرر همان مجموعه توکن‌ها دارد.
وقتی مجموعه‌ای از توکن‌ها را ذخیره می‌کنید، می‌توانید مدت زمانی را که می‌خواهید حافظه پنهان وجود داشته باشد تا توکن‌ها به طور خودکار حذف شوند، انتخاب کنید. این مدت زمان ذخیره، زمان حیات (TTL) نامیده می‌شود. اگر تنظیم نشود، TTL به طور پیش‌فرض ۱ ساعت است. هزینه ذخیره سازی به اندازه توکن ورودی و مدت زمانی که می‌خواهید توکن‌ها باقی بمانند بستگی دارد.
این بخش فرض می‌کند که شما یک Gemini SDK نصب کرده‌اید (یا curl را نصب کرده‌اید) و یک کلید API را پیکربندی کرده‌اید، همانطور که در شروع سریع نشان داده شده است.
تولید محتوا با استفاده از حافظه پنهان (cache)
مثال زیر نحوه تولید محتوا با استفاده از یک دستورالعمل سیستمی ذخیره شده و فایل ویدیویی را نشان می‌دهد.
ویدیوها
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)
فهرست کردن حافظه‌های پنهان
بازیابی یا مشاهده محتوای ذخیره شده در حافظه پنهان (cache) امکان‌پذیر نیست، اما می‌توانید متادیتای حافظه پنهان ( 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 یک حافظه پنهان (cache) را با استفاده از client.caches.update() نشان می‌دهد.
from google import genai
from google.genai import types
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
ttl='300s'
)
)
برای تنظیم زمان انقضا، این تابع یا یک شیء datetime یا یک رشته 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 ذخیره‌سازی صریح را فعال کنید.
چه زمانی از ذخیره‌سازی صریح استفاده کنیم؟
ذخیره‌سازی زمینه (Context caching) به ویژه برای سناریوهایی مناسب است که در آن‌ها یک زمینه اولیه قابل توجه به طور مکرر توسط درخواست‌های کوتاه‌تر ارجاع داده می‌شود. استفاده از ذخیره‌سازی زمینه را برای موارد استفاده‌ای مانند موارد زیر در نظر بگیرید:
- چت‌بات‌ها با دستورالعمل‌های سیستمی گسترده
- تجزیه و تحلیل مکرر فایل‌های ویدیویی طولانی
- پرس‌وجوهای مکرر در برابر مجموعه‌های بزرگ اسناد
- تحلیل مکرر مخزن کد یا رفع اشکال
چگونه ذخیره‌سازی صریح هزینه‌ها را کاهش می‌دهد
ذخیره‌سازی محتوا یک ویژگی پولی است که برای کاهش هزینه‌های عملیاتی کلی طراحی شده است. هزینه آن بر اساس عوامل زیر محاسبه می‌شود:
- تعداد توکن‌های ورودی ذخیره‌شده در حافظه پنهان: تعداد توکن‌های ورودی ذخیره‌شده که در صورت اضافه شدن در درخواست‌های بعدی، با نرخ کاهش‌یافته محاسبه می‌شوند.
- مدت زمان ذخیره‌سازی: میزان زمانی که توکن‌های ذخیره‌شده در حافظه پنهان (TTL) ذخیره می‌شوند، که بر اساس مدت زمان TTL تعداد توکن‌های ذخیره‌شده محاسبه می‌شود. هیچ محدودیت حداقل یا حداکثری برای TTL وجود ندارد.
- عوامل دیگر: هزینه‌های دیگری نیز اعمال می‌شود، مانند توکن‌های ورودی غیر ذخیره شده و توکن‌های خروجی.
برای جزئیات به‌روز قیمت‌گذاری، به صفحه قیمت‌گذاری Gemini API مراجعه کنید. برای یادگیری نحوه شمارش توکن‌ها، به راهنمای توکن مراجعه کنید.
ملاحظات اضافی
هنگام استفاده از ذخیره‌سازی زمینه‌ای (context caching)، ملاحظات زیر را در نظر داشته باشید:
- حداقل تعداد توکن ورودی برای ذخیره سازی متن، برای نسخه ۲.۵ فلش، ۱۰۲۴ و برای نسخه ۲.۵ پرو، ۴۰۹۶ است. حداکثر تعداد توکن ورودی، مشابه حداکثر تعداد توکن‌های مدل ارائه شده است. (برای اطلاعات بیشتر در مورد شمارش توکن‌ها، به راهنمای توکن مراجعه کنید).
- این مدل هیچ تمایزی بین توکن‌های ذخیره‌شده در حافظه پنهان و توکن‌های ورودی معمولی قائل نمی‌شود. محتوای ذخیره‌شده پیشوندی برای اعلان است.
- هیچ محدودیت نرخ یا استفاده خاصی برای ذخیره‌سازی زمینه وجود ندارد؛ محدودیت‌های نرخ استاندارد برای
GenerateContentاعمال می‌شود و محدودیت‌های توکن شامل توکن‌های ذخیره شده نیز می‌شود. - تعداد توکن‌های ذخیره‌شده در
usage_metadataاز عملیات ایجاد، دریافت و فهرست سرویس حافظه پنهان و همچنین درGenerateContentهنگام استفاده از حافظه پنهان، بازگردانده می‌شود.