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

Python JavaScript Go REST

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

• التخزين المؤقت الضمني (مفعّل تلقائيًا في نماذج Gemini 2.5، ولا نضمن تحقيق أي توفير في التكلفة)
• التخزين المؤقت الصريح (يمكن تفعيله يدويًا في معظم النماذج، وضمان توفير التكلفة)

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

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

يكون التخزين المؤقت الضمني مفعَّلاً تلقائيًا لجميع نماذج Gemini 2.5. ننقل إليك تلقائيًا أي توفير في التكاليف إذا وصل طلبك إلى ذاكرات التخزين المؤقت. ليس عليك اتّخاذ أي إجراء لتفعيل هذه الميزة. تسري هذه السياسة اعتبارًا من 8 مايو 2025. يتم إدراج الحد الأدنى لعدد الرموز المميزة للإدخال المطلوب لتفعيل التخزين المؤقت للسياق في الجدول التالي لكل نموذج:

لزيادة فرصة تحقيق نتيجة إيجابية في ذاكرة التخزين المؤقت الضمنية، اتّبِع الخطوات التالية:

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

يمكنك الاطّلاع على عدد الرموز المميزة التي تم العثور عليها في ذاكرة التخزين المؤقت في الحقل 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 });

التخزين المؤقت الصريح باستخدام مكتبة OpenAI

إذا كنت تستخدم مكتبة OpenAI، يمكنك تفعيل التخزين المؤقت الصريح باستخدام السمة cached_content في extra_body.

حالات استخدام التخزين المؤقّت الواضح

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

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

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

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

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

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

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

يجب مراعاة ما يلي عند استخدام التخزين المؤقت للسياق:

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