Kontext-Caching

In einem typischen KI-Workflow übergeben Sie möglicherweise immer wieder dieselben Eingabetokens an ein Modell. Mit der Kontext-Caching-Funktion der Gemini API können Sie Inhalte einmal an das Modell übergeben, die Eingabetokens im Cache speichern und dann bei nachfolgenden Anfragen auf die im Cache gespeicherten Tokens verweisen. Bei bestimmten Volumina ist die Verwendung von gecachten Tokens kostengünstiger als die wiederholte Weitergabe desselben Token-Korpus.

Wenn Sie eine Reihe von Tokens im Cache speichern, können Sie festlegen, wie lange der Cache vorhanden sein soll, bevor die Tokens automatisch gelöscht werden. Diese Caching-Dauer wird als Gültigkeitsdauer (TTL) bezeichnet. Wenn die Richtlinie nicht konfiguriert ist, wird die TTL standardmäßig auf 1 Stunde festgelegt. Die Kosten für das Caching hängen von der Größe des Eingabetokens ab und davon, wie lange die Tokens bestehen bleiben sollen.

Kontext-Caching unterstützt sowohl Gemini 1.5 Pro als auch Gemini 1.5 Flash.

Wann Kontext-Caching verwendet werden sollte

Kontext-Caching eignet sich besonders für Szenarien, bei denen in kürzeren Anfragen wiederholt auf eine hohe anfängliche Kontextmenge verwiesen wird. Ziehen Sie die Verwendung von Kontext-Caching für Anwendungsfälle wie diese in Betracht:

  • Chatbots mit ausführlichen Systemanweisungen
  • Wiederholte Analyse langer Videodateien
  • Wiederkehrende Abfragen großer Dokumentgruppen
  • Häufige Analyse oder Behebung von Fehlern im Code-Repository

Wie Caching die Kosten senkt

Kontext-Caching ist eine kostenpflichtige Funktion, mit der sich die Gesamtbetriebskosten senken lassen. Die Abrechnung erfolgt anhand der folgenden Faktoren:

  1. Anzahl der Cache-Tokens: Die Anzahl der im Cache gespeicherten Eingabetokens, für die ein ermäßigter Tarif für die Nutzung in nachfolgenden Prompts gilt.
  2. Speicherdauer:Die Dauer, für die im Cache gespeicherte Tokens gespeichert werden (TTL). Sie wird basierend auf der TTL-Dauer der im Cache gespeicherten Tokenanzahl berechnet. Es gibt keine Mindest- oder Höchstwerte für die TTL.
  3. Andere Faktoren: Es fallen weitere Gebühren an, z. B. für nicht im Cache gespeicherte Eingabe- und Ausgabetokens.

Aktuelle Preisinformationen finden Sie in der Preisübersicht für die Gemini API. Weitere Informationen zum Zählen von Tokens finden Sie im Token-Leitfaden.

Kontext-Caching verwenden

In diesem Abschnitt wird davon ausgegangen, dass Sie ein Gemini SDK (oder curl) installiert und einen API-Schlüssel konfiguriert haben, wie in der Kurzanleitung gezeigt.

Inhalte mit einem Cache generieren

Im folgenden Beispiel wird gezeigt, wie Inhalte mit einer im Cache gespeicherten Anleitung und Videodatei generiert werden.

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

Caches auflisten

Im Cache gespeicherte Inhalte können nicht abgerufen oder angesehen werden. Sie können aber Cache-Metadaten (name, model, displayName, usageMetadata, createTime, updateTime und expireTime) abrufen.

Verwenden Sie GoogleAICacheManager.list(), um Metadaten für alle hochgeladenen Caches aufzulisten:

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

Cache aktualisieren

Sie können eine neue ttl oder expireTime für einen Cache festlegen. Andere Änderungen am Cache werden nicht unterstützt.

Das folgende Beispiel zeigt, wie die ttl eines Caches mit GoogleAICacheManager.update() aktualisiert wird.

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

Cache löschen

Der Caching-Dienst bietet einen Löschvorgang zum manuellen Entfernen von Inhalten aus dem Cache. Im folgenden Beispiel wird gezeigt, wie ein Cache mit GoogleAICacheManager.delete() gelöscht wird.

await cacheManager.delete(cacheName);

Weitere Überlegungen

Beachten Sie bei der Verwendung von Kontext-Caching die folgenden Überlegungen:

  • Die minimale Anzahl der Eingabetokens für das Kontext-Caching beträgt 32.768 und das Maximum ist mit dem Maximum des jeweiligen Modells identisch. Weitere Informationen zum Zählen von Tokens finden Sie im Leitfaden zu Tokens.
  • Das Modell unterscheidet nicht zwischen im Cache gespeicherten Tokens und regulären Eingabetokens. Im Cache gespeicherte Inhalte sind einfach ein Präfix für die Aufforderung.
  • Es gibt keine speziellen Raten- oder Nutzungslimits für das Kontext-Caching. Es gelten die standardmäßigen Ratenbegrenzungen für GenerateContent und Tokenlimits umfassen im Cache gespeicherte Tokens.
  • Die Anzahl der im Cache gespeicherten Tokens wird im usage_metadata der Erstellungs-, Abruf- und Listenvorgänge des Cache-Dienstes sowie bei Verwendung des Caches in GenerateContent zurückgegeben.