في سير عمل الذكاء الاصطناعي النموذجي، قد تُمرِّر علامات إدخال البيانات نفسها مرارًا وتكرارًا إلى نموذج. باستخدام ميزة التخزين المؤقت للسياق في Gemini API، يمكنك تمرير بعض المحتوى إلى النموذج مرة واحدة وتخزين الرموز المميّزة للدخل مؤقتًا، ثم الرجوع إلى الرموز المميّزة المخزّنة مؤقتًا للطلبات اللاحقة. عند استخدام أعداد معيّنة من الرموز المميّزة، يكون استخدام الرموز المميّزة المخزّنة مؤقتًا أقل تكلفة مقارنةً بإدخال مجموعة الرموز المميّزة نفسها بشكل متكرّر.
عند تخزين مجموعة من الرموز المميّزة في ذاكرة التخزين المؤقت، يمكنك اختيار المدة التي تريد خلالها بقاء ذاكرة التخزين المؤقت متوفّرة قبل حذف الرموز المميّزة تلقائيًا. تُعرف مدة التخزين المؤقت هذه باسم مدة البقاء (TTL). في حال عدم ضبطها، تكون مدة البقاء التلقائية هي ساعة واحدة. تعتمد تكلفة التخزين المؤقت على حجم الرمز المميّز الذي يتم إدخاله ومدة الاحتفاظ بالرموز المميّزة.
تختلف ميزة التخزين المؤقت للسياق من طراز إلى آخر.
حالات استخدام ميزة "تخزين السياق في ذاكرة التخزين المؤقت"
إنّ ميزة "تخزين السياق في ذاكرة التخزين المؤقت" مناسبة بشكل خاص للسيناريوهات التي تتم فيها الإشارة بشكل متكرر إلى سياق أولي مهم من خلال طلبات أقصر. ننصحك باستخدام التخزين المؤقت للسياق في حالات الاستخدام التالية:
- روبوتات الدردشة التي تتضمّن تعليمات النظام المفصّلة
- التحليل المتكرّر لملفات فيديو طويلة
- الاستعلامات المتكرّرة في مجموعات كبيرة من المستندات
- تحليل مستودع الرموز البرمجية أو إصلاح الأخطاء بشكل متكرّر
كيفية استخدام ميزة "تخزين السياق مؤقتًا"
يفترض هذا القسم أنّك ثبّت حزمة تطوير برامج (SDK) لتطبيق Gemini (أو ثبّت curl) وأنّك أعددت مفتاح واجهة برمجة التطبيقات، كما هو موضّح في الخطوات الأساسية.
إنشاء محتوى باستخدام ذاكرة تخزين مؤقت
يوضّح المثال التالي كيفية إنشاء ذاكرة تخزين مؤقت ثم استخدامها لإنشاء محتوى.
الفيديوهات
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'"
}'
ملفات PDF
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"
كيفية تقليل ميزة التخزين المؤقت للتكاليف
ميزة "تخزين السياق في ذاكرة التخزين المؤقت" هي ميزة مدفوعة مصمّمة لخفض التكاليف التشغيلية الإجمالية. تستند الفوترة إلى العوامل التالية:
- عدد الرموز المميّزة المخزّنة مؤقتًا: عدد الرموز المميّزة التي يتم تخزينها مؤقتًا في ذاكرة التخزين المؤقت، ويتم تحصيل رسومها بمعدل مناقشة منخفض عند تضمينها في طلبات لاحقة.
- مدة التخزين: هي المدة التي يتم فيها تخزين الرموز المميّزة المخزّنة مؤقتًا (مدة البقاء)، ويُحصَّل السعر استنادًا إلى مدة مدة البقاء لعدد الرموز المميّزة المخزّنة مؤقتًا. ما مِن حدود أدنى أو أقصى لوقت الاسترجاع.
- عوامل أخرى: يتم تطبيق رسوم أخرى، مثل رسوم الرموز المميّزة للدخل وعدم تخزينها مؤقتًا والرموز المميّزة للإخراج.
للاطّلاع على تفاصيل الأسعار المحدّثة، يُرجى الرجوع إلى صفحة أسعار Gemini API. للتعرّف على كيفية احتساب الرموز المميّزة، اطّلِع على دليل الرموز المميّزة.
اعتبارات أخرى
يجب مراعاة النقاط التالية عند استخدام ميزة "تخزين السياق في ذاكرة التخزين المؤقت":
- الحد الأدنى لعدد الرموز المميّزة للدخل لتخزين السياق في ذاكرة التخزين المؤقت هو 4,096، والحد الأقصى هو نفسه الحد الأقصى للنموذج المحدّد. (لمزيد من المعلومات عن احتساب الرموز المميّزة، يُرجى الاطّلاع على دليل الرموز المميّزة).
- لا يُميّز النموذج بين الرموز المخزّنة مؤقتًا والرموز العادية لرموز الإدخال. المحتوى المخزّن مؤقتًا هو بادئة للطلب.
- لا تُفرض أي حدود خاصة على معدّل التخزين المؤقت للسياق أو على معدّل الاستخدام، بل تُطبَّق حدود المعدّل العادي
GenerateContent
، وتشمل حدود الرموز المميّزة الرموز المميّزة المخزّنة مؤقتًا. - يتم عرض عدد الرموز المميّزة المخزّنة مؤقتًا في
usage_metadata
من عمليات إنشاء وعرض وسرد خدمة ذاكرة التخزين المؤقت، وكذلك فيGenerateContent
عند استخدام ذاكرة التخزين المؤقت.