تخزين السياق مؤقتًا في Firebase AI Logic

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

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

توفر نماذج Gemini آليتين مختلفتين لتخزين المحتوى مؤقتًا:

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

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

النماذج المتوافقة

يتوفّر التخزين المؤقت عند استخدام النماذج التالية:

  • gemini-3.1-pro-preview
  • gemini-3-flash-preview
  • gemini-3.1-flash-lite
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite

لا تتيح النماذج التي تنشئ الوسائط (مثل نماذج Nana Banana مثل gemini-3.1-flash-image-preview) تخزين السياق مؤقتًا.

الحدود القصوى لحجم المحتوى المخزّن مؤقتًا

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

  • نماذج Gemini Pro: 4096 رمزًا مميزًا كحد أدنى
  • نماذج Gemini Flash: 1024 رمزًا مميزًا كحد أدنى

بالإضافة إلى ذلك، يبلغ الحد الأقصى لحجم المحتوى الذي يمكنك تخزينه مؤقتًا باستخدام كائن ثنائي كبير (blob) أو نص 10 ميغابايت.


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

التخزين المؤقت الضمني مفعَّل تلقائيًا ومتاح لمعظم Gemini النماذج.

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

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

يتم توفير عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من إدخالك في الحقل cachedContentTokenCount في البيانات الوصفية للرد.


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

التخزين المؤقت الصريح غير مفعَّل تلقائيًا، وهو إمكانية اختيارية في نماذج Gemini.

إليك كيفية إعداد ذاكرات التخزين المؤقت للمحتوى الصريح واستخدامها:

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


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

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

  1. إنشاء ذاكرة تخزين مؤقت صريحة

  2. الإشارة إلى ذاكرة التخزين المؤقت في نموذج طلب من الخادم

  3. الإشارة إلى نموذج الطلب من الخادم في طلب من تطبيقك

معلومات مهمة عن إنشاء ذاكرة تخزين مؤقت صريحة واستخدامها

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

  • تكون ذاكرة التخزين المؤقت خاصة بمقدّم خدمة Gemini API. يجب أن يستخدم طلب تطبيقك مقدّم الخدمة نفسه.
    بالنسبة إلى Firebase AI Logic، ننصحك بشدة باستخدام ذاكرات التخزين المؤقت للمحتوى الصريح فقط مع Vertex AI Gemini API. جميع المعلومات و الأمثلة في هذه الصفحة خاصة بمقدّم خدمة Gemini API هذا.

  • تكون ذاكرة التخزين المؤقت خاصة بنموذج Gemini. يجب أن يستخدم طلب تطبيقك النموذج نفسه.

  • تكون ذاكرة التخزين المؤقت خاصة بموقع جغرافي عند استخدام الـ Vertex AI Gemini API.
    يجب أن يتطابق الموقع الجغرافي لذاكرة التخزين المؤقت الصريحة مع الموقع الجغرافي لنموذج الطلب من الخادم و الموقع الجغرافي الذي تصل فيه إلى النموذج في طلب تطبيقك.

يُرجى أيضًا العِلم بالقيود والمتطلبات التالية للتخزين المؤقت الصريح:

  • بعد إنشاء ذاكرة تخزين مؤقت صريحة، لا يمكنك تغيير أي شيء فيها باستثناء مدة البقاء (TTL) أو وقت انتهاء الصلاحية.

  • يمكنك تخزين أي نوع MIME لملف إدخال متوافق أو حتى نص فقط يتم تقديمه ضمن طلب إنشاء ذاكرة التخزين المؤقت.

  • إذا أردت تضمين ملف في ذاكرة التخزين المؤقت، يجب تقديم الملف كـ Cloud Storage معرّف موارد منتظم (URI). لا يمكن أن يكون عنوان URL للمتصفح أو عنوان URL على YouTube.

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

  • إذا أردت استخدام تعليمات النظام أو الأدوات (مثل تنفيذ الرموز أو سياق عنوان URL أو Grounding with Google Search أو Grounding with Google Maps)، يجب أن تحتوي ذاكرة التخزين المؤقت نفسها على إعداداتها. لا يمكن ضبطها في نموذج الطلب من الخادم أو في طلب تطبيقك. يُرجى العِلم أنّ نماذج الطلبات من الخادم لا تتيح بعد استخدام ميزة "استدعاء الدوال" (أو المحادثة). للحصول على تفاصيل حول كيفية ضبط تعليمات النظام والأدوات في ذاكرة التخزين المؤقت، يُرجى الاطّلاع على واجهة برمجة تطبيقات REST الخاصة بـ Vertex AI Gemini API.

الخطوة 1: إنشاء ذاكرة التخزين المؤقت

يمكنك إنشاء ذاكرة التخزين المؤقت باستخدام واجهة برمجة تطبيقات REST الخاصة بـ Vertex AI Gemini API مباشرةً.

في ما يلي مثال ينشئ ذاكرة تخزين مؤقت صريحة لملف PDF كمحتوى لها.

البنية:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3-flash-preview
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-flash-preview"
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-flash-preview",
  "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: الإشارة إلى نموذج الطلب من الخادم في الطلب من تطبيقك

يُرجى توخي الحذر الشديد بشأن ما يلي عند كتابة طلبك:

  • استخدِم Vertex AI Gemini API لأنّه تم إنشاء ذاكرة التخزين المؤقت باستخدام مقدّم الخدمة هذا 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}");
}


إدارة ذاكرات التخزين المؤقت الصريحة

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

يمكنك إدارة ذاكرات التخزين المؤقت الصريحة باستخدام الـ REST API الخاص بـ Vertex AI Gemini API.

بعد إنشاء ذاكرة تخزين مؤقت صريحة للمحتوى، لا يمكنك تغيير أي شيء فيها باستثناء مدة البقاء (TTL) أو وقت انتهاء الصلاحية.

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

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

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) أو وقت انتهاء صلاحية ذاكرة تخزين مؤقت

عند إنشاء ذاكرة تخزين مؤقت صريحة، يمكنك اختياريًا ضبط ttl أو expire_time.

  • ttl: مدة البقاء (TTL) لذاكرة التخزين المؤقت، وتحديدًا عدد الثواني وأجزاء النانو ثانية التي تبقى فيها ذاكرة التخزين المؤقت بعد إنشائها أو بعد تعديل ttl قبل انتهاء صلاحيتها. عند ضبط ttl، يتم تعديل expireTime لذاكرة التخزين المؤقت تلقائيًا.

  • expire_time: هي Timestamp (مثل 2024-06-30T09:00:00.000000Z) تحدّد التاريخ والوقت المطلَقَين لانتهاء صلاحية ذاكرة التخزين المؤقت.

إذا لم تضبط أيًا من هاتَين القيمتَين، ستكون مدة البقاء التلقائية (TTL) هي ساعة واحدة. ما مِن حدود دنيا أو قصوى لـ TTL.

بالنسبة إلى ذاكرات التخزين المؤقت الصريحة الحالية، يمكنك إضافة 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}


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

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

  • رموز الإدخال المميّزة لإنشاء ذاكرة التخزين المؤقت: بالنسبة إلى التخزين المؤقت الضمني والصريح، يتم تحصيل رسوم منك مقابل رموز الإدخال المميّزة المستخدَمة لإنشاء ذاكرة التخزين المؤقت بسعر رموز الإدخال المميّزة العادي.

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

  • استخدام المحتوى المخزّن مؤقتًا: يضمن التخزين المؤقت الصريح الحصول على خصم عند الإشارة إلى ذاكرات التخزين المؤقت الصريحة، ما يعني أنّك تحصل على خصم على رموز الإدخال المميّزة عند الإشارة إلى ذاكرة تخزين مؤقت حالية. بالنسبة إلى Gemini 2.5 والإصدارات الأحدث، يبلغ هذا الخصم %90.

يتم توفير عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من إدخالك في الحقل cachedContentTokenCount في البيانات الوصفية للرد.