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

Python JavaScript Go REST

في سير عمل الذكاء الاصطناعي العادي، قد يتم تمرير رموز الإدخال نفسها مرارًا وتكرارًا إلى أحد النماذج. يوفّر Gemini API آليتَي تخزين مؤقت مختلفتَين:

• التخزين المؤقت الضمني (مفعّل تلقائيًا في معظم نماذج Gemini، ولا نضمن توفير التكاليف)
• التخزين المؤقت الصريح (يمكن تفعيله يدويًا في معظم النماذج، وضمان توفير التكلفة)

تكون ميزة التخزين المؤقت الواضح مفيدة في الحالات التي تريد فيها ضمان توفير التكاليف، ولكن مع بعض العمل الإضافي من المطوّر.

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

يتم تفعيل التخزين المؤقت الضمني تلقائيًا وهو متاح لمعظم نماذج Gemini. ننقل إليك تلقائيًا أي توفير في التكاليف إذا وصل طلبك إلى ذاكرات التخزين المؤقت. ليس عليك اتّخاذ أي إجراء لتفعيل هذه الميزة. تسري هذه السياسة اعتبارًا من 8 مايو 2025. يتم إدراج الحد الأدنى لعدد الرموز المميزة للإدخال المطلوب لتفعيل التخزين المؤقت للسياق في الجدول التالي لكل نموذج:

لزيادة فرصة تحقيق نتيجة إيجابية في ذاكرة التخزين المؤقت الضمنية، اتّبِع الخطوات التالية:

• جرِّب وضع المحتوى الكبير والشائع في بداية الطلب
• محاولة إرسال طلبات تتضمّن بادئة مشابهة في فترة زمنية قصيرة

يمكنك الاطّلاع على عدد الرموز المميزة التي تم العثور عليها في ذاكرة التخزين المؤقت في الحقل 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 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.
3. عوامل أخرى: تنطبق رسوم أخرى، مثل رسوم الرموز المميزة للإدخال غير المخزّنة مؤقتًا والرموز المميزة للإخراج.

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

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

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

• يختلف الحد الأدنى لعدد الرموز المميزة للإدخال في التخزين المؤقت للسياق حسب النموذج. الحد الأقصى هو الحد الأقصى للنموذج المحدّد. (لمزيد من المعلومات حول احتساب الرموز المميزة، اطّلِع على دليل الرموز المميزة).
• لا يميّز النموذج بين الرموز المميّزة المخزّنة مؤقتًا والرموز المميّزة العادية. المحتوى المخزّن مؤقتًا هو بادئة للطلب.
• لا توجد حدود خاصة للمعدّل أو الاستخدام في ما يتعلق بالتخزين المؤقت للسياق، بل تنطبق حدود المعدّل العادية الخاصة بـ GenerateContent، وتشمل حدود الرموز المميزة الرموز المميزة المخزَّنة مؤقتًا.
• يتم عرض عدد الرموز المميزة المخزّنة مؤقتًا في usage_metadata من عمليات الإنشاء والحصول على البيانات وعرض القائمة الخاصة بخدمة التخزين المؤقت، وكذلك في GenerateContent عند استخدام التخزين المؤقت.