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

في سير عمل الذكاء الاصطناعي النموذجي، قد تُمرِّر علامات إدخال البيانات نفسها مرارًا وتكرارًا إلى نموذج. توفّر 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) وأنّك أعددت مفتاح واجهة برمجة التطبيقات، كما هو موضّح في الخطوات المُبسّطة.

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

يوضّح المثال التالي كيفية إنشاء محتوى باستخدام تعليمات نظام مخزّنة مؤقتًا وملف نصي.

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const doc = await ai.files.upload({
    file: "path/to/file.txt",
    config: { mimeType: "text/plain" },
  });
  console.log("Uploaded file name:", doc.name);

  const modelName = "gemini-2.0-flash-001";
  const cache = await ai.caches.create({
    model: modelName,
    config: {
      contents: createUserContent(createPartFromUri(doc.uri, doc.mimeType)),
      systemInstruction: "You are an expert analyzing transcripts.",
    },
  });
  console.log("Cache created:", cache);

  const response = await ai.models.generateContent({
    model: modelName,
    contents: "Please summarize this transcript",
    config: { cachedContent: cache.name },
  });
  console.log("Response text:", response.text);
}

await main();

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

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

لعرض البيانات الوصفية لجميع ذاكرات التخزين المؤقت التي تم تحميلها، استخدِم GoogleGenAI.caches.list():

console.log("My caches:");
const pager = await ai.caches.list({ config: { pageSize: 10 } });
let page = pager.page;
while (true) {
  for (const c of page) {
    console.log("    ", c.name);
  }
  if (!pager.hasNextPage()) break;
  page = await pager.nextPage();
}

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

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

يوضّح المثال التالي كيفية تعديل ttl لمخزن مؤقت باستخدام GoogleGenAI.caches.update().

const ttl = `${2 * 3600}s`; // 2 hours in seconds
const updatedCache = await ai.caches.update({
  name: cache.name,
  config: { ttl },
});
console.log("After update (TTL):", updatedCache);

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

توفّر خدمة التخزين المؤقت عملية حذف لإزالة المحتوى يدوياً من ذاكرة التخزين المؤقت. يوضّح المثال التالي كيفية حذف ذاكرة التخزين المؤقت باستخدام GoogleGenAI.caches.delete().

await ai.caches.delete({ name: cache.name });

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

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

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

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

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

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

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

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

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

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