ذخیره‌سازی متن، ذخیره‌سازی متن

پایتون جاوا اسکریپت گو رست

در یک گردش کار معمول هوش مصنوعی، ممکن است توکن‌های ورودی یکسانی را بارها و بارها به یک مدل ارسال کنید. API Gemini دو مکانیسم ذخیره‌سازی مختلف ارائه می‌دهد:

• ذخیره سازی ضمنی (به طور خودکار در مدل های Gemini 2.5 فعال است، بدون تضمین صرفه جویی در هزینه)
• ذخیره سازی صریح (در اکثر مدل ها می توان به صورت دستی فعال کرد، تضمین صرفه جویی در هزینه)

ذخیره‌سازی صریح در مواردی مفید است که می‌خواهید صرفه‌جویی در هزینه را تضمین کنید، اما با کمی کار اضافی برای توسعه‌دهندگان.

ذخیره سازی ضمنی

ذخیره‌سازی ضمنی (implicit caching) به طور پیش‌فرض برای همه مدل‌های Gemini 2.5 فعال است. اگر درخواست شما به حافظه پنهان (cache) برسد، ما به طور خودکار صرفه‌جویی در هزینه را اعمال می‌کنیم. برای فعال کردن این قابلیت، نیازی به انجام هیچ کاری ندارید. این قابلیت از ۸ مه ۲۰۲۵ فعال است. حداقل تعداد توکن ورودی برای ذخیره‌سازی زمینه (context caching) برای هر مدل در جدول زیر ذکر شده است:

برای افزایش احتمال برخورد با حافظه پنهان ضمنی:

• سعی کنید مطالب بزرگ و رایج را در ابتدای درخواست خود قرار دهید.
• سعی کنید درخواست‌هایی با پیشوند مشابه را در مدت زمان کوتاهی ارسال کنید

می‌توانید تعداد توکن‌هایی که در حافظه پنهان (cache hits) بوده‌اند را در فیلد usage_metadata شیء پاسخ مشاهده کنید.

ذخیره سازی صریح

با استفاده از ویژگی ذخیره‌سازی صریح API Gemini، می‌توانید یک بار مقداری محتوا را به مدل ارسال کنید، توکن‌های ورودی را ذخیره کنید و سپس برای درخواست‌های بعدی به توکن‌های ذخیره‌شده مراجعه کنید. در حجم‌های خاص، استفاده از توکن‌های ذخیره‌شده هزینه کمتری نسبت به ارسال مکرر همان مجموعه توکن‌ها دارد.

وقتی مجموعه‌ای از توکن‌ها را ذخیره می‌کنید، می‌توانید مدت زمانی را که می‌خواهید حافظه پنهان وجود داشته باشد تا توکن‌ها به طور خودکار حذف شوند، انتخاب کنید. این مدت زمان ذخیره، زمان حیات (TTL) نامیده می‌شود. اگر تنظیم نشود، TTL به طور پیش‌فرض ۱ ساعت است. هزینه ذخیره سازی به اندازه توکن ورودی و مدت زمانی که می‌خواهید توکن‌ها باقی بمانند بستگی دارد.

این بخش فرض می‌کند که شما یک Gemini SDK نصب کرده‌اید (یا curl را نصب کرده‌اید) و یک کلید API پیکربندی کرده‌اید، همانطور که در شروع سریع نشان داده شده است.

تولید محتوا با استفاده از حافظه پنهان (cache)

مثال زیر نحوه تولید محتوا با استفاده از یک دستورالعمل سیستمی ذخیره شده در حافظه پنهان و یک فایل متنی را نشان می‌دهد.

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();

فهرست کردن حافظه‌های پنهان

بازیابی یا مشاهده محتوای ذخیره شده در حافظه پنهان (cache) امکان‌پذیر نیست، اما می‌توانید متادیتای حافظه پنهان ( 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 یک حافظه پنهان (cache) را با استفاده از 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 ، ذخیره‌سازی صریح را فعال کنید.

چه زمانی از ذخیره‌سازی صریح استفاده کنیم؟

ذخیره‌سازی زمینه (Context caching) به ویژه برای سناریوهایی مناسب است که در آن‌ها یک زمینه اولیه قابل توجه به طور مکرر توسط درخواست‌های کوتاه‌تر ارجاع داده می‌شود. استفاده از ذخیره‌سازی زمینه را برای موارد استفاده‌ای مانند موارد زیر در نظر بگیرید:

• چت‌بات‌ها با دستورالعمل‌های سیستمی گسترده
• تجزیه و تحلیل مکرر فایل‌های ویدیویی طولانی
• پرس‌وجوهای مکرر در برابر مجموعه‌های بزرگ اسناد
• تحلیل مکرر مخزن کد یا رفع اشکال

چگونه ذخیره‌سازی صریح هزینه‌ها را کاهش می‌دهد

ذخیره‌سازی محتوا یک ویژگی پولی است که برای کاهش هزینه‌های عملیاتی کلی طراحی شده است. هزینه آن بر اساس عوامل زیر محاسبه می‌شود:

1. تعداد توکن‌های ورودی ذخیره‌شده در حافظه پنهان: تعداد توکن‌های ورودی ذخیره‌شده که در صورت اضافه شدن به درخواست‌های بعدی، با نرخ کاهش‌یافته محاسبه می‌شوند.
2. مدت زمان ذخیره‌سازی: میزان زمانی که توکن‌های ذخیره‌شده در حافظه پنهان (TTL) ذخیره می‌شوند، که بر اساس مدت زمان TTL تعداد توکن‌های ذخیره‌شده محاسبه می‌شود. هیچ محدودیت حداقل یا حداکثری برای TTL وجود ندارد.
3. عوامل دیگر: هزینه‌های دیگری نیز اعمال می‌شود، مانند توکن‌های ورودی غیر ذخیره شده و توکن‌های خروجی.

برای جزئیات به‌روز قیمت‌گذاری، به صفحه قیمت‌گذاری API Gemini مراجعه کنید. برای یادگیری نحوه شمارش توکن‌ها، به راهنمای توکن مراجعه کنید.

ملاحظات اضافی

هنگام استفاده از ذخیره‌سازی زمینه‌ای (context caching)، نکات زیر را در نظر داشته باشید:

• حداقل تعداد توکن ورودی برای ذخیره سازی زمینه برای نسخه ۲.۵ فلش ۱۰۲۴، برای نسخه ۲.۵ پرو ۴۰۹۶ و برای نسخه ۳ پرو پیش نمایش ۲۰۴۸ است. حداکثر تعداد توکن ورودی مشابه حداکثر مدل ارائه شده است. (برای اطلاعات بیشتر در مورد شمارش توکن‌ها، به راهنمای توکن مراجعه کنید).
• این مدل هیچ تمایزی بین توکن‌های ذخیره‌شده در حافظه پنهان و توکن‌های ورودی معمولی قائل نمی‌شود. محتوای ذخیره‌شده پیشوندی برای اعلان است.
• هیچ محدودیت نرخ یا استفاده خاصی برای ذخیره‌سازی زمینه وجود ندارد؛ محدودیت‌های نرخ استاندارد برای GenerateContent اعمال می‌شود و محدودیت‌های توکن شامل توکن‌های ذخیره شده نیز می‌شود.
• تعداد توکن‌های ذخیره‌شده در usage_metadata از عملیات ایجاد، دریافت و فهرست سرویس حافظه پنهان و همچنین در GenerateContent هنگام استفاده از حافظه پنهان، بازگردانده می‌شود.