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

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

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

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

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