שמירת הקשר במטמון

בתהליך עבודה טיפוסי של AI, יכול להיות שתעבירו שוב ושוב את אותם אסימוני קלט למודל. באמצעות התכונה של Gemini API לשמירת מטמון לפי הקשר, אפשר להעביר תוכן מסוים למודל פעם אחת, לשמור במטמון את אסימוני הקלט ואז להפנות לאסימונים שנשמרו במטמון לבקשות הבאות. בנפח מסוים, השימוש באסימונים ששמורים במטמון זול יותר מהעברה חוזרת של אותו גוף של אסימונים.

כששומרים במטמון קבוצה של אסימונים, אפשר לבחור את משך הזמן שבו האסימונים יישארו במטמון לפני שהם יימחקו באופן אוטומטי. משך הזמן הזה ששמור במטמון נקרא אורך החיים (TTL). אם לא מגדירים את ערך ה-TTL, ברירת המחדל היא שעה אחת. העלות של שמירת האסימונים במטמון תלויה בגודל אסימון הקלט ובמשך הזמן שבו רוצים לשמור את האסימונים.

יש תמיכה בשמירת הקשר במטמון בסדרת המודלים היציבה של Gemini 1.5 ו-2.0.

מתי כדאי להשתמש בשמירת הקשר במטמון

שמירת הקשר במטמון מתאימה במיוחד לתרחישים שבהם הקשר ראשוני משמעותי מופיע שוב ושוב בבקשות קצרות יותר. כדאי להשתמש בשמירה במטמון לפי הקשר בתרחישים לדוגמה כמו:

  • צ'אט בוטים עם הוראות מערכת מפורטות
  • ניתוח חוזר של קובצי וידאו ארוכים
  • שאילתות חוזרות על קבוצות גדולות של מסמכים
  • ניתוח תדיר של מאגר הקוד או תיקון באגים

איך אחסון במטמון מפחית עלויות

שמירת הקשר במטמון היא תכונה בתשלום שנועדה להפחית את העלויות הכוללות של התפעול. החיוב מבוסס על הגורמים הבאים:

  1. מספר האסימונים ששמורים במטמון: מספר האסימונים של הקלט ששמורים במטמון, שעבורם מתבצעת חיוב במחיר מופחת כשהם נכללים בהנחיות הבאות.
  2. משך האחסון: משך הזמן שבו טוקנים שמאוחסנים במטמון נשמרים (TTL). החיוב מתבצע על סמך משך ה-TTL של מספר הטוקנים במטמון. אין גבולות מינימום או מקסימום ל-TTL.
  3. גורמים אחרים: חלים חיובים אחרים, כמו על אסימוני קלט ואסימוני פלט שלא שמורים במטמון.

פרטי התמחור העדכניים מפורטים בדף התמחור של Gemini API. במאמר מדריך אסימונים מוסבר איך ספציפית מנהלים אסימונים.

איך משתמשים במטמון הקשר

בסעיף הזה נניח שכבר התקנתם את Gemini SDK (או ש-curl מותקן אצלכם) ושהגדרתם מפתח API, כפי שמתואר במדריך למתחילים.

יצירת תוכן באמצעות מטמון

הדוגמה הבאה מראה איך ליצור תוכן באמצעות הוראה מערכת שנשמרה במטמון וקובץ טקסט.

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

שיקולים נוספים

כשמשתמשים במטמון הקשר, חשוב לזכור את הנקודות הבאות:

  • המספר המינימלי של אסימוני הקלט לשמירת הקשר במטמון הוא 32,768, והמספר המקסימלי זהה למספר המקסימלי של המודל הנתון. (מידע נוסף על ספירת אסימונים זמין במדריך בנושא אסימונים).
  • המודל לא מבדיל בין אסימונים שנשמרו במטמון לבין אסימוני קלט רגילים. תוכן ששמור במטמון הוא פשוט קידומת להנחיה.
  • אין מגבלות מיוחדות על קצב או על שימוש בשמירת הקשר במטמון. מגבלות הקצב הרגילות של GenerateContent חלות, ומגבלות האסימונים כוללות אסימונים שנשמרו במטמון.
  • מספר האסימונים שנשמרו במטמון מוחזר ב-usage_metadata מהפעולות create,‏ get ו-list של שירות המטמון, וגם ב-GenerateContent כשמשתמשים במטמון.