بالنسبة إلى ميزة الذكاء الاصطناعي، قد يتم تمرير رموز الإدخال (المحتوى) نفسها بشكل متكرّر إلى أحد النماذج. في حالات الاستخدام هذه، يمكنك بدلاً من ذلك تخزين هذا المحتوى مؤقتًا، ما يعني أنّك تمرّر المحتوى إلى النموذج مرة واحدة، وتخزّنه، وتشير إليه في الطلبات اللاحقة.
يمكن أن يؤدي تخزين السياق مؤقتًا إلى تقليل وقت الاستجابة والتكلفة بشكل كبير للمهام المتكرّرة التي تتضمّن كمية كبيرة من المحتوى، مثل كميات كبيرة من النصوص أو ملف صوتي أو ملف فيديو. تشمل بعض حالات الاستخدام الشائعة للمحتوى المخزّن مؤقتًا مستندات الشخصيات التفصيلية أو قواعد البيانات أو الأدلة.
توفر نماذج Gemini آليتين مختلفتين للتخزين المؤقت:
التخزين المؤقت الضمني: يتم تفعيله تلقائيًا في معظم النماذج، ولا يتم ضمان توفير التكاليف
التخزين المؤقت الصريح: يمكن تفعيله اختياريًا و يدويًا في معظم النماذج، وعادةً ما يؤدي إلى توفير التكاليف
يكون التخزين المؤقت الصريح مفيدًا في الحالات التي تريد فيها ضمان توفير التكاليف بشكل أكبر، ولكن مع بعض العمل الإضافي للمطوّرين.
بالنسبة إلى التخزين المؤقت الضمني والصريح، يشير الحقل cachedContentTokenCount في البيانات الوصفية لردّك إلى عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من إدخالك. بالنسبة إلى التخزين المؤقت الصريح، احرص على مراجعة معلومات
التسعير في أسفل هذه الصفحة.
النماذج المتوافقة
يكون التخزين المؤقت متاحًا عند استخدام النماذج التالية:
gemini-3.1-pro-previewgemini-3.6-flash(والنموذج الأقدمgemini-3.5-flash)gemini-3.5-flash-lite(والنموذج الأقدمgemini-3.1-flash-lite)
تتيح نماذج Gemini 2.5 للاستخدام العام هذه الإمكانية، ولكن تم إيقافها جميعًا.
لا تتيح النماذج التي تنشئ الوسائط (مثل نماذج "Nana Banana" مثل
gemini-3.1-flash-image) تخزين السياق مؤقتًا.
الحدود القصوى لحجم المحتوى المخزّن مؤقتًا
يفرض كل نموذج حدًا أدنى لعدد الرموز المميّزة للمحتوى المخزّن مؤقتًا. ويتم تحديد الحد الأقصى من خلال قدرة استيعاب النموذج.
- Gemini نماذج Pro: 4096 رمزًا مميّزًا كحد أدنى
- نماذج Gemini Flash: 1024 رمزًا مميّزًا كحد أدنى
بالإضافة إلى ذلك، يبلغ الحد الأقصى لحجم المحتوى الذي يمكنك تخزينه مؤقتًا باستخدام كائن ثنائي كبير أو نص 10 ميغابايت.
التخزين المؤقت الضمني
يكون التخزين المؤقت الضمني مفعّلاً تلقائيًا ومتاحًا لمعظم Gemini النماذج.
توفّر Google تلقائيًا التكاليف إذا كان طلبك يطابق المحتوى المخزّن مؤقتًا. في ما يلي بعض الطرق لزيادة احتمالية استخدام طلبك للتخزين المؤقت الضمني:
- حاوِل وضع المحتوى الكبير والشائع في بداية طلبك.
- حاوِل إرسال الطلبات التي تتضمّن بادئة مشابهة خلال فترة زمنية قصيرة.
يتم توفير عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من إدخالك في الحقل cachedContentTokenCount في البيانات الوصفية للرد.
التخزين المؤقت الصريح
لا يكون التخزين المؤقت الصريح مفعّلاً تلقائيًا، وهو إمكانية اختيارية لنماذج Gemini.
في ما يلي كيفية إعداد ذاكرات التخزين المؤقت للمحتوى الصريح واستخدامها:
إدارة ذاكرات التخزين المؤقت الصريح، بما في ذلك:
يُرجى العِلم أنّ ذاكرات التخزين المؤقت للمحتوى الصريح تتفاعل مع التخزين المؤقت الضمني، ما قد يؤدي إلى تخزين إضافي مؤقتًا بالإضافة إلى المحتوى الصريح المخزّن مؤقتًا. يمكنك منع الاحتفاظ ببيانات ذاكرة التخزين المؤقت من خلال إيقاف التخزين المؤقت الضمني وعدم إنشاء ذاكرات تخزين مؤقت صريح. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تفعيل التخزين المؤقت وإيقافه.
إنشاء ذاكرة تخزين مؤقت صريح واستخدامها
يتطلّب إنشاء ذاكرة تخزين مؤقت للمحتوى الصريح واستخدامها ما يلي:
معلومات مهمة حول إنشاء ذاكرة تخزين مؤقت صريح واستخدامها
يجب أن تتوافق ذاكرة التخزين المؤقت مع طلبات تطبيقك ونموذج الطلب من الخادم:
تكون ذاكرة التخزين المؤقت خاصة بمقدّم خدمة Gemini API. يجب أن يستخدم طلب تطبيقك مقدّم الخدمة نفسه.
بالنسبة إلى Firebase AI Logic، ننصحك بشدة باستخدام ذاكرات التخزين المؤقت للمحتوى الصريح فقط مع Agent Platform Gemini API (formerly Vertex AI). جميع المعلومات و الأمثلة الواردة في هذه الصفحة خاصة بمقدّم خدمة Gemini API هذا.تكون ذاكرة التخزين المؤقت خاصة بنموذج Gemini. يجب أن يستخدم طلب تطبيقك النموذج نفسه.
تكون ذاكرة التخزين المؤقت خاصة بموقع جغرافي عند استخدام Agent Platform Gemini API (formerly Vertex AI).
يجب أن يتطابق الموقع الجغرافي لذاكرة التخزين المؤقت الصريح مع الموقع الجغرافي لنموذج الطلب من الخادم و الموقع الجغرافي الذي تصل فيه إلى النموذج في طلب تطبيقك.
يُرجى أيضًا العِلم بالقيود والمتطلبات التالية للتخزين المؤقت الصريح:
بعد إنشاء ذاكرة تخزين مؤقت صريح، لا يمكنك تغيير أي شيء فيها باستثناء مدة البقاء أو وقت انتهاء الصلاحية.
يمكنك تخزين أي نوع MIME لملف إدخال متوافق أو حتى نص فقط يتم تقديمه ضمن طلب إنشاء ذاكرة التخزين المؤقت.
إذا أردت تضمين ملف في ذاكرة التخزين المؤقت، عليك تقديم الملف كـ Cloud Storage معرّف موارد منتظم (URI). لا يمكن أن يكون عنوان URL للمتصفّح أو عنوان URL على YouTube.
بالإضافة إلى ذلك، يتم التحقّق من قيود الوصول إلى الملف في وقت إنشاء ذاكرة التخزين المؤقت ، و لا يتم التحقّق من قيود الوصول مرة أخرى في وقت طلب المستخدم. لهذا السبب، تأكَّد من أنّ أي بيانات مضمّنة في ذاكرة التخزين المؤقت الصريح مناسبة لأي مستخدم يقدّم طلبًا يتضمّن ذاكرة التخزين المؤقت هذه.
إذا أردت استخدام تعليمات النظام أو الأدوات (مثل تطبيق الرموز البرمجية أو سياق عناوين URL أو تحديد المصدر باستخدام
Google Search أو تحديد المصدر باستخدامGoogle Maps )، يجب أن تحتوي ذاكرة التخزين المؤقت نفسها على إعداداتها. لا يمكن ضبطها في نموذج الطلب من الخادم أو في طلب تطبيقك. يُرجى العِلم أنّ نماذج الطلبات من الخادم لا تتيح بعد استدعاء الدوال (أو المحادثة). للحصول على تفاصيل حول كيفية ضبط تعليمات النظام والأدوات في ذاكرة التخزين المؤقت، يُرجى الاطّلاع على واجهة برمجة تطبيقات REST لواجهة برمجة التطبيقات Gemini على "منصة الوكلاء" (المعروفة سابقًا باسم Vertex AI).Agent Platform Gemini API (formerly Vertex AI)
الخطوة 1: إنشاء ذاكرة التخزين المؤقت
يمكنك إنشاء ذاكرة التخزين المؤقت باستخدام واجهة برمجة تطبيقات REST الخاصة بـ Agent Platform Gemini API (formerly Vertex AI).
في ما يلي مثال ينشئ ذاكرة تخزين مؤقت صريح لملف PDF كمحتوى لها.
البنية:
PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL" # for example, gemini-3.6-flash
LOCATION="LOCATION" # location for both the cache and the model
MIME_TYPE="MIME_TYPE"
CACHED_CONTENT_URI="CLOUD_STORAGE_FILE_URI" # must be a Cloud Storage URI
CACHE_DISPLAY_NAME="CACHE_DISPLAY_NAME" # optional
TTL="CACHE_TIME_TO_LIVE" # optional (if not specified, defaults to 3600s)
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
"model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
"contents": [
{
"role": "user",
"parts": [
{
"fileData": {
"mimeType": "${MIME_TYPE}",
"fileUri": "${CACHED_CONTENT_URI}"
}
}
]
}
],
"displayName": "${CACHE_DISPLAY_NAME}",
"ttl": "${TTL}"
}
EOF
مثال على الطلب:
PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3.6-flash"
LOCATION="global"
MIME_TYPE="application/pdf"
CACHED_CONTENT_URI="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
CACHE_DISPLAY_NAME="Gemini - A Family of Highly Capable Multimodal Model (PDF)"
TTL="7200s"
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
"model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
"contents": [
{
"role": "user",
"parts": [
{
"fileData": {
"mimeType": "${MIME_TYPE}",
"fileUri": "${CACHED_CONTENT_URI}"
}
}
]
}
],
"displayName": "${CACHE_DISPLAY_NAME}",
"ttl": "${TTL}"
}
EOF
مثال على الرد:
يتضمّن الرد موردًا مؤهلاً بالكامل name وفريدًا
على مستوى العالم لذاكرة التخزين المؤقت (يُرجى العِلم أنّ الجزء الأخير هو رقم تعريف ذاكرة التخزين المؤقت). ستستخدم
قيمة name الكاملة هذه في الخطوة التالية من سير العمل.
{
"name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
"model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3.6-flash",
"createTime": "2024-06-04T01:11:50.808236Z",
"updateTime": "2024-06-04T01:11:50.808236Z",
"expireTime": "2024-06-04T02:11:50.794542Z"
}
الخطوة 2: الإشارة إلى ذاكرة التخزين المؤقت في نموذج طلب من الخادم
بعد إنشاء ذاكرة التخزين المؤقت، أشِر إليها باستخدام name ضمن السمة cachedContent
property of a
server prompt template.
احرص على اتّباع هذه المتطلبات عند إنشاء نموذج الطلب من الخادم:
استخدِم المورد المؤهّل بالكامل
nameمن الرد عند إنشاء ذاكرة التخزين المؤقت. لا تستخدم الاسم المعروض الاختياري الذي حدّدته في الطلب.يجب أن يتطابق الـ موقع الجغرافي لنموذج الطلب من الخادم مع الموقع الجغرافي لذاكرة التخزين المؤقت.
لاستخدام تعليمات النظام أو الأدوات، يجب ضبطها كجزء من ذاكرة التخزين المؤقت وليس كجزء من نموذج الطلب من الخادم.
البنية:
{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}
{{role "user"}}
{{userPrompt}}
مثال:
{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}
{{role "user"}}
{{userPrompt}}
بدلاً من ذلك، يمكن أن تكون قيمة المَعلمة name في نموذج الطلب من الخادم
يمكن أن تكون
متغيّر إدخال ديناميكيًا.
على سبيل المثال،
{{cachedContent name=someVariable}}name لذاكرة التخزين المؤقت كإدخال للطلب من
تطبيقك.
الخطوة 3: الإشارة إلى نموذج الطلب من الخادم في الطلب من تطبيقك
يُرجى توخي الحذر الشديد بشأن ما يلي عند كتابة طلبك:
استخدِم Agent Platform Gemini API (formerly Vertex AI) بما أنّ ذاكرة التخزين المؤقت تم إنشاؤها باستخدام مقدّم خدمة Gemini API هذا.
يجب أن يتطابق الموقع الجغرافي الذي تصل فيه إلى النموذج في طلب تطبيقك مع الموقع الجغرافي لنموذج الطلب من الخادم وذاكرة التخزين المؤقت.
Swift
// ...
// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
let model = FirebaseAI.firebaseAI(backend: .vertexAI(location: "LOCATION"))
.templateGenerativeModel()
do {
let response = try await model.generateContent(
// Specify your template ID
templateID: "TEMPLATE_ID"
)
if let text = response.text {
print("Response Text: \(text)")
}
} catch {
print("An error occurred: \(error)")
}
print("\n")
Kotlin
// ...
// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
val model = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "LOCATION"))
.templateGenerativeModel()
val response = model.generateContent(
// Specify your template ID
"TEMPLATE_ID",
)
val text = response.text
println(text)
Java
// ...
// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();
TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);
Future<GenerateContentResponse> response = model.generateContent(
// Specify your template ID
"TEMPLATE_ID"
);
addCallback(response,
new FutureCallback<GenerateContentResponse>() {
public void onSuccess(GenerateContentResponse result) {
System.out.println(result.getText());
}
public void onFailure(Throwable t) {
reportError(t);
}
}
executor);
Web
// ...
// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
const ai = getAI(app, { backend: new VertexAIBackend('LOCATION') });
// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);
const result = await model.generateContent(
// Specify your template ID
'TEMPLATE_ID'
);
const response = result.response;
const text = response.text();
Dart
// ...
// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
var _model = FirebaseAI.vertexAI(location: 'LOCATION').templateGenerativeModel()
var response = await _model.generateContent(
// Specify your template ID
'TEMPLATE_ID',
);
var text = response?.text;
print(text);
Unity
// ...
// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "LOCATION"));
// Create a `TemplateGenerativeModel` instance
var model = firebaseAI.GetTemplateGenerativeModel();
try
{
var response = await model.GenerateContentAsync(
// Specify your template ID
"TEMPLATE_ID"
);
Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
Debug.LogError($"An error occurred: {e.Message}");
}
إدارة ذاكرات التخزين المؤقت الصريح
يتناول هذا القسم إدارة ذاكرات التخزين المؤقت للمحتوى الصريح، بما في ذلك كيفية عرض جميع ذاكرات التخزين المؤقت، الحصول على بيانات وصفية حول ذاكرة تخزين مؤقت، تعديل مدة البقاء أو وقت انتهاء صلاحية ذاكرة تخزين مؤقت، و حذف ذاكرة تخزين مؤقت.
يمكنك إدارة ذاكرات التخزين المؤقت الصريح باستخدام واجهة برمجة تطبيقات REST الخاصة بـ Agent Platform Gemini API (formerly Vertex AI).
بعد إنشاء ذاكرة تخزين مؤقت للمحتوى الصريح، لا يمكنك تغيير أي شيء فيها باستثناء مدة البقاء أو وقت انتهاء الصلاحية.
عرض جميع ذاكرات التخزين المؤقت
يمكنك عرض جميع ذاكرات التخزين المؤقت الصريح المتاحة لمشروعك. لن يعرض هذا الأمر سوى ذاكرات التخزين المؤقت في الموقع الجغرافي المحدّد.
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents
الحصول على بيانات وصفية حول ذاكرة تخزين مؤقت
لا يمكن استرداد المحتوى المخزّن مؤقتًا الفعلي أو عرضه. ومع ذلك، يمكنك استرداد البيانات الوصفية حول ذاكرة تخزين مؤقت صريح، بما في ذلك name وmodel وdisplay_name وusage_metadata وcreate_time وupdate_time وexpire_time.
عليك تقديم CACHE_ID، وهو الجزء الأخير في
للمورد المؤهّل بالكامل name لذاكرة التخزين المؤقت.
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}
تعديل مدة البقاء أو وقت انتهاء صلاحية ذاكرة تخزين مؤقت
عند إنشاء ذاكرة تخزين مؤقت صريح، يمكنك اختياريًا ضبط ttl أو الـ
expire_time.
ttl: مدة البقاء لذاكرة التخزين المؤقت، وتحديدًا عدد الثواني وأجزاء الثانية التي تبقى فيها ذاكرة التخزين المؤقت بعد إنشائها أو بعد تعديلttlقبل انتهاء صلاحيتها. عند ضبطttl، يتم تعديلexpireTimeلذاكرة التخزين المؤقت تلقائيًا.expire_time:Timestamp(مثل2024-06-30T09:00:00.000000Z) يحدّد التاريخ والوقت المطلَقَين لانتهاء صلاحية ذاكرة التخزين المؤقت.
إذا لم تضبط أيًا من هاتَين القيمتَين، ستكون مدة البقاء التلقائية ساعة واحدة. ما مِن حدود دنيا أو قصوى لـ "مدة البقاء".
بالنسبة إلى ذاكرات التخزين المؤقت الصريح الحالية، يمكنك إضافة ttl أو expire_time أو تعديلهما.
عليك تقديم CACHE_ID، وهو الجزء الأخير في
للمورد المؤهّل بالكامل name لذاكرة التخزين المؤقت.
تعديل ttl
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
TTL="CACHE_TIME_TO_LIVE"
curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
"ttl": "'$TTL'"
}'
تعديل expire_time
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
EXPIRE_TIME="ABSOLUTE_TIME_CACHE_EXPIRES"
curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
"expire_time": "'$EXPIRE_TIME'"
}'
حذف ذاكرة تخزين مؤقت
إذا لم تعُد بحاجة إلى ذاكرة تخزين مؤقت صريح، يمكنك حذفها.
عليك تقديم CACHE_ID، وهو الجزء الأخير في
للمورد المؤهّل بالكامل name لذاكرة التخزين المؤقت.
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}
تسعير التخزين المؤقت الصريح
التخزين المؤقت الصريح هو ميزة مدفوعة مصمّمة لتقليل التكلفة. يستند التسعير إلى العوامل التالية:
رموز الإدخال لإنشاء ذاكرة التخزين المؤقت: بالنسبة إلى التخزين المؤقت الضمني والصريح، يتم تحصيل رسوم منك مقابل رموز الإدخال المستخدَمة لإنشاء ذاكرة التخزين المؤقت بسعر رموز الإدخال العادي.
تخزين ذاكرة التخزين المؤقت: بالنسبة إلى التخزين المؤقت الصريح، هناك أيضًا تكاليف تخزين استنادًا إلى مدة تخزين ذاكرات التخزين المؤقت. ما مِن تكاليف تخزين للتخزين المؤقت الضمني. لمزيد من المعلومات، يُرجى الاطّلاع على تسعير Agent Platform Gemini API (formerly Vertex AI).
استخدام المحتوى المخزّن مؤقتًا: يضمن التخزين المؤقت الصريح الحصول على خصم عند الإشارة إلى ذاكرات التخزين المؤقت الصريح ، ما يعني أنّك تحصل على خصم على رموز الإدخال عندما تشير إلى ذاكرة تخزين مؤقت حالية. بالنسبة إلى Gemini 2.5 والإصدارات الأحدث، يبلغ هذا الخصم %90.
يتم توفير عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من إدخالك في الحقل cachedContentTokenCount في البيانات الوصفية للرد.