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

Python JavaScript Go REST

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

• שמירה במטמון באופן מרומז (מופעלת אוטומטית ברוב המודלים של Gemini, אין הבטחה לחיסכון בעלויות)
• שמירה במטמון באופן מפורש (אפשר להפעיל אותה באופן ידני ברוב המודלים, מובטח חיסכון בעלויות)

שימוש במטמון מפורש מועיל במקרים שבהם רוצים להבטיח חיסכון בעלויות, אבל צריך להשקיע קצת יותר עבודה בפיתוח.

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

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

כדי להגדיל את הסיכוי לפגיעה במטמון משתמע:

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

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

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

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

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

בסעיף הזה מניחים שהתקנתם 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-3-flash-preview";
  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), החיוב מתבצע על סמך משך ה-TTL של ספירת הטוקנים במטמון. אין ערכי מינימום או מקסימום ל-TTL.
3. גורמים אחרים: חלים חיובים אחרים, למשל על טוקנים של קלט ופלט שלא נשמרו במטמון.

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

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

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

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