التخزين المؤقت للسياق

في سير عمل الذكاء الاصطناعي النموذجي، قد يتم تمرير رموز الإدخال نفسها مرارًا وتكرارًا إلى أحد النماذج. يوفّر 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). إذا لم يتم ضبطها، تكون مدة البقاء التلقائية ساعة واحدة. تعتمد تكلفة التخزين المؤقت على حجم الرموز المميزة للإدخال ومدة الاحتفاظ بها.

يفترض هذا القسم أنّك ثبّت حزمة تطوير برامج (SDK) خاصة بـ Gemini (أو ثبّت curl) وأنّك أعددت مفتاح واجهة برمجة التطبيقات، كما هو موضّح في دليل البدء السريع.

إنشاء محتوى باستخدام ذاكرة تخزين مؤقت

يوضّح المثال التالي كيفية إنشاء محتوى باستخدام تعليمات نظام مخزّنة مؤقتًا وملف فيديو.

الفيديوهات

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.

حالات استخدام التخزين المؤقّت الواضح

تكون ميزة التخزين المؤقت للسياق مناسبة بشكل خاص للحالات التي تتم فيها الإشارة بشكل متكرر إلى سياق أولي كبير من خلال طلبات أقصر. يمكنك استخدام التخزين المؤقت للسياق في حالات الاستخدام التالية:

  • روبوتات الدردشة التي تتضمّن تعليمات نظام شاملة
  • التحليل المتكرّر لملفات الفيديو الطويلة
  • الاستعلامات المتكرّرة عن مجموعات المستندات الكبيرة
  • تحليل مستودع الرموز البرمجية أو إصلاح الأخطاء بشكل متكرّر

كيفية تقليل التكاليف باستخدام التخزين المؤقت الصريح

ميزة "التخزين المؤقت للسياق" هي ميزة مدفوعة مصمَّمة لتقليل التكاليف التشغيلية الإجمالية. تستند الفوترة إلى العوامل التالية:

  1. عدد الرموز المميزة المخزّنة مؤقتًا: عدد الرموز المميزة للإدخال المخزّنة مؤقتًا، والتي تتم فوترتها بسعر مخفّض عند تضمينها في الطلبات اللاحقة.
  2. مدة التخزين: هي المدة الزمنية التي يتم فيها تخزين الرموز المميّزة المخزَّنة مؤقتًا (مدة البقاء)، ويتم إصدار الفواتير استنادًا إلى مدة البقاء لعدد الرموز المميّزة المخزَّنة مؤقتًا. ليس هناك حد أدنى أو أقصى لقيمة TTL.
  3. عوامل أخرى: تنطبق رسوم أخرى، مثل رسوم الرموز المميزة للإدخال غير المخزّنة مؤقتًا والرموز المميزة للإخراج.

للاطّلاع على تفاصيل الأسعار الحديثة، يُرجى الرجوع إلى صفحة الأسعار الخاصة بواجهة Gemini API. للتعرّف على كيفية احتساب الرموز المميزة، اطّلِع على دليل الرموز المميزة.

اعتبارات أخرى

يجب مراعاة ما يلي عند استخدام التخزين المؤقت للسياق:

  • الحد الأدنى لعدد الرموز المميزة للإدخال من أجل التخزين المؤقت للسياق هو 1,024 لـ 2.5 Flash و2,048 لـ 2.5 Pro. الحد الأقصى هو نفسه الحد الأقصى للنموذج المحدّد. (لمزيد من المعلومات حول احتساب الرموز المميزة، يُرجى الاطّلاع على دليل الرموز المميزة).
  • لا يميّز النموذج بين الرموز المميزة المخزّنة مؤقتًا ورموز الإدخال العادية. المحتوى المخزّن مؤقتًا هو بادئة للطلب.
  • لا توجد حدود خاصة للمعدّل أو الاستخدام في ما يتعلق بالتخزين المؤقت للسياق، بل تنطبق حدود المعدّل العادية الخاصة بـ GenerateContent، وتشمل حدود الرموز المميزة الرموز المميزة المخزّنة مؤقتًا.
  • يتم عرض عدد الرموز المميزة المخزّنة مؤقتًا في usage_metadata من عمليات الإنشاء والحصول على البيانات وعرض القائمة في خدمة التخزين المؤقت، وكذلك في GenerateContent عند استخدام التخزين المؤقت.