ذخیره‌سازی متن، ذخیره‌سازی متن

پایتون جاوا اسکریپت گو رست

در یک گردش کار معمول هوش مصنوعی، ممکن است توکن‌های ورودی یکسانی را بارها و بارها به یک مدل ارسال کنید. API Gemini دو مکانیسم ذخیره‌سازی مختلف ارائه می‌دهد:

• ذخیره سازی ضمنی (به طور خودکار در اکثر مدل های Gemini فعال است، بدون تضمین صرفه جویی در هزینه)
• ذخیره سازی صریح (در اکثر مدل ها می توان به صورت دستی فعال کرد، تضمین صرفه جویی در هزینه)

ذخیره‌سازی صریح در مواردی مفید است که می‌خواهید صرفه‌جویی در هزینه را تضمین کنید، اما با مقداری کار توسعه‌دهنده‌ی اضافی.

ذخیره سازی ضمنی

ذخیره‌سازی ضمنی (implicit caching) به طور پیش‌فرض فعال است و برای اکثر مدل‌های Gemini در دسترس است. اگر درخواست شما به حافظه پنهان (cache) برسد، ما به طور خودکار صرفه‌جویی در هزینه را اعمال می‌کنیم. برای فعال کردن این قابلیت، نیازی به انجام هیچ کاری از سوی شما نیست. این قابلیت از ۸ مه ۲۰۲۵ فعال است. حداقل تعداد توکن ورودی برای ذخیره‌سازی زمینه (context caching) برای هر مدل در جدول زیر ذکر شده است:

برای افزایش احتمال برخورد با حافظه پنهان ضمنی:

• سعی کنید مطالب بزرگ و رایج را در ابتدای درخواست خود قرار دهید.
• سعی کنید درخواست‌هایی با پیشوند مشابه را در مدت زمان کوتاهی ارسال کنید

می‌توانید تعداد توکن‌هایی که در حافظه پنهان (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 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)

فهرست کردن حافظه‌های پنهان

بازیابی یا مشاهده محتوای ذخیره شده در حافظه پنهان (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) به ویژه برای سناریوهایی مناسب است که در آن‌ها یک زمینه اولیه قابل توجه به طور مکرر توسط درخواست‌های کوتاه‌تر ارجاع داده می‌شود. استفاده از ذخیره‌سازی زمینه را برای موارد استفاده‌ای مانند موارد زیر در نظر بگیرید:

• چت‌بات‌ها با دستورالعمل‌های سیستمی گسترده
• تجزیه و تحلیل مکرر فایل‌های ویدیویی طولانی
• پرس‌وجوهای مکرر در برابر مجموعه‌های بزرگ اسناد
• تحلیل مکرر مخزن کد یا رفع اشکال

چگونه ذخیره‌سازی صریح هزینه‌ها را کاهش می‌دهد

ذخیره‌سازی متن یک ویژگی پولی است که برای کاهش هزینه طراحی شده است. هزینه بر اساس عوامل زیر محاسبه می‌شود:

1. تعداد توکن‌های ورودی ذخیره‌شده در حافظه پنهان: تعداد توکن‌های ورودی ذخیره‌شده که در صورت اضافه شدن در درخواست‌های بعدی، با نرخ کاهش‌یافته محاسبه می‌شوند.
2. مدت زمان ذخیره‌سازی: میزان زمانی که توکن‌های ذخیره‌شده در حافظه پنهان (TTL) ذخیره می‌شوند، که بر اساس مدت زمان TTL تعداد توکن‌های ذخیره‌شده محاسبه می‌شود. هیچ محدودیت حداقل یا حداکثری برای TTL وجود ندارد.
3. عوامل دیگر: هزینه‌های دیگری نیز اعمال می‌شود، مانند توکن‌های ورودی غیر ذخیره شده و توکن‌های خروجی.

برای جزئیات به‌روز قیمت‌گذاری، به صفحه قیمت‌گذاری Gemini API مراجعه کنید. برای یادگیری نحوه شمارش توکن‌ها، به راهنمای توکن مراجعه کنید.

ملاحظات اضافی

هنگام استفاده از ذخیره‌سازی زمینه‌ای (context caching)، ملاحظات زیر را در نظر داشته باشید:

• حداقل تعداد توکن‌های ورودی برای ذخیره‌سازی زمینه بر اساس مدل متفاوت است. حداکثر آن مشابه حداکثر برای مدل داده شده است. (برای اطلاعات بیشتر در مورد شمارش توکن‌ها، به راهنمای توکن مراجعه کنید).
• این مدل هیچ تمایزی بین توکن‌های ذخیره‌شده در حافظه پنهان و توکن‌های ورودی معمولی قائل نمی‌شود. محتوای ذخیره‌شده پیشوندی برای اعلان است.
• هیچ محدودیت نرخ یا استفاده خاصی برای ذخیره‌سازی زمینه وجود ندارد؛ محدودیت‌های نرخ استاندارد برای GenerateContent اعمال می‌شود و محدودیت‌های توکن شامل توکن‌های ذخیره شده نیز می‌شود.
• تعداد توکن‌های ذخیره‌شده در usage_metadata از عملیات ایجاد، دریافت و فهرست سرویس حافظه پنهان و همچنین در GenerateContent هنگام استفاده از حافظه پنهان، بازگردانده می‌شود.