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

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

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

تقدّم نماذج Gemini آليتَين مختلفتَين للتخزين المؤقت:

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

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

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

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

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

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

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

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

  • Gemini نماذج Pro: 4,096 رمزًا مميزًا كحد أدنى
  • 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. يجب ألا يكون عنوان URL للمتصفّح أو عنوان URL على YouTube.

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

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

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

أنشئ ذاكرة التخزين المؤقت باستخدام REST API الخاص بـ 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 الخاصة بنموذج طلب من الخادم.

يُرجى اتّباع المتطلبات التالية عند إنشاء نموذج طلب من الخادم:

  • استخدِم المورد المؤهَّل بالكامل 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.

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

عرض جميع الذاكرات المؤقتة

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

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 أو 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 ضمن البيانات الوصفية للرد.