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

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

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

يتوافق التخزين المؤقت للسياق مع كل من Gemini 1.5 Pro وGemini 1.5 Flash.

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

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

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

كيف يؤدي التخزين المؤقت إلى تقليل التكاليف

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

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

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

كيفية استخدام ميزة "تخزين السياق مؤقتًا"

يفترض هذا القسم أنّك ثبَّت حزمة تطوير برامج Gemini (أو حزمة curl) وضبطت مفتاح واجهة برمجة تطبيقات، كما هو موضّح في Quickstart.

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

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

import { GoogleGenerativeAI } from '@google/generative-ai';
import {
  FileState,
  GoogleAICacheManager,
  GoogleAIFileManager,
} from '@google/generative-ai/server';

// A helper function that uploads the video to be cached.
async function uploadMp4Video(filePath, displayName) {
  const fileManager = new GoogleAIFileManager(process.env.API_KEY);
  const fileResult = await fileManager.uploadFile(filePath, {
    displayName,
    mimeType: 'video/mp4',
  });

  const { name, uri } = fileResult.file;

  // Poll getFile() on a set interval (2 seconds here) to check file state.
  let file = await fileManager.getFile(name);
  while (file.state === FileState.PROCESSING) {
    console.log('Waiting for video to be processed.');
    // Sleep for 2 seconds
    await new Promise((resolve) => setTimeout(resolve, 2_000));
    file = await fileManager.getFile(name);
  }

  console.log(`Video processing complete: ${uri}`);

  return fileResult;
}

// Download video file
// curl -O https://storage.googleapis.com/generativeai-downloads/data/Sherlock_Jr_FullMovie.mp4
const pathToVideoFile = 'Sherlock_Jr_FullMovie.mp4';

// Upload the video.
const fileResult = await uploadMp4Video(pathToVideoFile, 'Sherlock Jr. video');

// Construct a GoogleAICacheManager using your API key.
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);

// Create a cache with a 5 minute TTL.
const displayName = 'sherlock jr movie';
const model = 'models/gemini-1.5-flash-001';
const systemInstruction =
  'You are an expert video analyzer, and your job is to answer ' +
  "the user's query based on the video file you have access to.";
let ttlSeconds = 300;
const cache = await cacheManager.create({
  model,
  displayName,
  systemInstruction,
  contents: [
    {
      role: 'user',
      parts: [
        {
          fileData: {
            mimeType: fileResult.file.mimeType,
            fileUri: fileResult.file.uri,
          },
        },
      ],
    },
  ],
  ttlSeconds,
});

// Get your API key from https://aistudio.google.com/app/apikey
// Access your API key as an environment variable.
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Construct a `GenerativeModel` which uses the cache object.
const genModel = genAI.getGenerativeModelFromCachedContent(cache);

// Query the model.
const result = await genModel.generateContent({
  contents: [
    {
      role: 'user',
      parts: [
        {
          text:
            'Introduce different characters in the movie by describing ' +
            'their personality, looks, and names. Also list the ' +
            'timestamps they were introduced for the first time.',
        },
      ],
    },
  ],
});

console.log(result.response.usageMetadata);

// The output should look something like this:
//
// {
//   promptTokenCount: 696220,
//   candidatesTokenCount: 270,
//   totalTokenCount: 696490,
//   cachedContentTokenCount: 696191
// }

console.log(result.response.text());

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

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

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

const listResult = await cacheManager.list();
listResult.cachedContents.forEach((cache) => {
  console.log(cache);
});

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

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

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

const ttlSeconds = 2 * 60 * 60;
const updateParams = { cachedContent: { ttlSeconds } };
const updatedCache = await cacheManager.update(cacheName, updateParams);

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

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

await cacheManager.delete(cacheName);

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

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

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