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

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

  • التخزين المؤقت الضمني (تلقائي، ولا يمكن ضمان توفير التكلفة)
  • التخزين المؤقت الصريح (يدوي، ضمان توفير التكلفة)

يكون التخزين المؤقت الضمني مفعّلاً تلقائيًا في طُرز Gemini 2.5. إذا كان أحد الطلبات يحتوي على محتوى من ذاكرة التخزين المؤقت، سنردّ إليك تلقائيًا التوفير في التكلفة.

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

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

يكون التخزين المؤقت الضمني مفعّلاً تلقائيًا في جميع نماذج Gemini 2.5. ونقدّم تلقائيًا تخفيضات في التكلفة إذا كان طلبك يبحث في ذاكرات التخزين المؤقت. ما مِن إجراءات مطلوبة لتفعيل هذه الميزة. وبدأ تطبيقها اعتبارًا من 8 أيار (مايو) 2025. الحد الأدنى لعدد علامات الإدخال لتخزين السياق المؤقت هو 1,024 لإصدار 2.5 Flash و2,048 لإصدار 2.5 Pro.

لزيادة فرصة الوصول إلى ذاكرة التخزين المؤقت بشكل ضمني:

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

يمكنك الاطّلاع على عدد الرموز المميّزة التي كانت نتائج ذاكرة التخزين المؤقت في حقل usage_metadata الخاص بعنصر الاستجابة.

التخزين المؤقت الصريح

باستخدام ميزة التخزين المؤقت الصريح لواجهة برمجة التطبيقات Gemini API، يمكنك تمرير بعض المحتوى إلى النموذج مرة واحدة وتخزين الرموز المميّزة للدخل في ذاكرة التخزين المؤقت، ثم الرجوع إلى الرموز المميّزة المخزّنة في ذاكرة التخزين المؤقت للطلبات اللاحقة. عند استخدام أحجام معيّنة، يكون استخدام الرموز المُخزَّنة مؤقتًا أقل تكلفة مقارنةً بإدخال مجموعة الرموز نفسها بشكل متكرّر.

عند تخزين مجموعة من الرموز المميّزة في ذاكرة التخزين المؤقت، يمكنك اختيار المدة التي تريد خلالها أن تظل ذاكرة التخزين المؤقت متوفّرة قبل حذف الرموز المميّزة تلقائيًا. تُعرف مدة التخزين المؤقت هذه باسم مدة البقاء (TTL). إذا لم يتم ضبطها، تكون مدة البقاء التلقائية هي ساعة واحدة. تعتمد تكلفة التخزين المؤقت على حجم الرمز المميّز الذي يتم إدخاله ومدة الاحتفاظ بالرموز المميّزة.

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

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

يوضّح المثال التالي كيفية إنشاء ذاكرة تخزين مؤقت ثم استخدامها لإنشاء محتوى.

الفيديوهاتملفات PDF 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "contents":[
    {
      "parts":[
        {
          "inline_data": {
            "mime_type":"text/plain",
            "data": "'$(base64 $B64FLAGS a11.txt)'"
          }
        }
      ],
    "role": "user"
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are an expert at analyzing transcripts."
      }
    ]
  },
  "ttl": "300s"
}' > request.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-001:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

DOC_URL="https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
TTL="300s"

# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"

MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")
NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")

echo "MIME_TYPE: ${MIME_TYPE}"
echo "NUM_BYTES: ${NUM_BYTES}"

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo "file_uri: ${file_uri}"

# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"

# Create the cached content request
echo '{
  "model": "'$MODEL'",
  "contents":[
    {
      "parts":[
        {"file_data": {"mime_type": "'$MIME_TYPE'", "file_uri": '$file_uri'}}
      ],
    "role": "user"
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "'$SYSTEM_INSTRUCTION'"
      }
    ],
    "role": "system"
  },
  "ttl": "'$TTL'"
}' > request.json

# Send the cached content request
curl -X POST "${BASE_URL}/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)
echo "CACHE_NAME: ${CACHE_NAME}"
# Send the generateContent request using the cached content
curl -X POST "${BASE_URL}/${MODEL}:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "'$PROMPT'"
          }],
          "role": "user"
        }
      ],
      "cachedContent": "'$CACHE_NAME'"
    }' > response.json

cat response.json

echo jq ".candidates[].content.parts[].text" response.json

ذاكرات التخزين المؤقت

لا يمكن استرداد المحتوى المخزّن مؤقتًا أو عرضه، ولكن يمكنك استرداد البيانات الوصفية المخزّنة مؤقتًا (name وmodel وdisplayName وusageMetadata وcreateTime وupdateTime وexpireTime).

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

تعديل ذاكرة تخزين مؤقت

يمكنك ضبط ttl أو expireTime جديدَين لمخزن مؤقت. لا يمكن تغيير أي شيء آخر بشأن ذاكرة التخزين المؤقت.

يوضّح المثال التالي كيفية تعديل ttl لمخزن مؤقت.

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

حذف ذاكرة تخزين مؤقت

توفّر خدمة التخزين المؤقت عملية حذف لإزالة المحتوى يدوياً من ذاكرة التخزين المؤقت. يوضّح المثال التالي كيفية حذف ذاكرة تخزين مؤقت.

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

حالات استخدام التخزين المؤقّت الصريح

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

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

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

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

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

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

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

يجب مراعاة النقاط التالية عند استخدام ميزة "تخزين السياق في ذاكرة التخزين المؤقت":

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