Buforowanie kontekstu

W typowym procesie sztucznej inteligencji możesz wielokrotnie przekazywać te same tokeny wejściowe do modelu. Korzystając z funkcji Gemini API dotyczącej kontekstowego buforowania, możesz przekazać modelowi pewną treść, zapisać w pamięci podręcznej tokeny wejściowe, a następnie odwoływać się do tych tokenów w kolejnych żądaniach. Przy pewnych wolumenach korzystanie z tokenów w pamięci podręcznej jest tańsze niż wielokrotne przekazywanie tego samego zbioru tokenów.

Gdy przechowujesz w pamięci podręcznej zestaw tokenów, możesz określić, jak długo ma ona istnieć, zanim tokeny zostaną automatycznie usunięte. Czas przechowywania w pamięci podręcznej nazywany jest czasem życia danych (TTL). Jeśli nie określisz tego ustawienia, domyślnie są to 24 godziny. Koszt buforowania zależy od rozmiaru tokena wejściowego i czasu, przez jaki mają być przechowywane tokeny.

Buforowanie kontekstu różni się w zależności od modelu.

Kiedy używać buforowania kontekstu

Buforowanie kontekstu jest szczególnie przydatne w sytuacjach, gdy obszerny początkowy kontekst jest wielokrotnie odwoływany przez krótsze żądania. Zastanów się nad użyciem buforowania kontekstu w przypadku:

  • Czatboty z obszernymi instrukcjami systemowymi
  • powtarzająca się analiza długich plików wideo,
  • powtarzające się zapytania dotyczące dużych zbiorów dokumentów;
  • częsta analiza repozytorium kodu lub poprawianie błędów;

Jak korzystać z buforowania kontekstu

W tej sekcji zakładamy, że masz zainstalowany pakiet Gemini SDK (lub masz zainstalowany curl) oraz skonfigurowany klucz API zgodnie z instrukcjami w artykule Szybki start.

Generowanie treści z wykorzystaniem pamięci podręcznej

Ten przykład pokazuje, jak generować treści za pomocą instrukcji systemu z pamięci podręcznej i pliku tekstowego.

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

Wyświetlanie pamięci podręcznej

Nie można pobrać ani wyświetlić treści z pamięci podręcznej, ale można pobrać metadane z pamięci podręcznej (name, model, displayName, usageMetadata, createTime, updateTime i expireTime).

Aby wyświetlić metadane wszystkich przesłanych pamięci podręcznych, użyj 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();
}

Aktualizowanie pamięci podręcznej

Możesz ustawić nową wartość ttl lub expireTime dla pamięci podręcznej. Zmiana innych ustawień pamięci podręcznej nie jest obsługiwana.

Ten przykład pokazuje, jak za pomocą funkcji GoogleGenAI.caches.update() zaktualizować ttl pamięci podręcznej.

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

Usuwanie pamięci podręcznej

Usługa buforowania udostępnia operację usuwania, która umożliwia ręczne usuwanie treści z pamięci podręcznej. Z tego przykładu dowiesz się, jak usunąć pamięć podręczną za pomocą funkcji GoogleGenAI.caches.delete().

await ai.caches.delete({ name: cache.name });

Jak buforowanie zmniejsza koszty

Pamięć podręczna kontekstu to płatna funkcja, która ma na celu obniżenie ogólnych kosztów operacyjnych. Płatności są określane na podstawie tych czynników:

  1. Liczba tokenów w pamięci podręcznej:liczba tokenów wejściowych w pamięci podręcznej, za które pobierana jest obniżona stawka, gdy są one uwzględnione w kolejnych promptach.
  2. Czas przechowywania: czas przechowywania tokenów w pamięci podręcznej (TTL), naliczany na podstawie czasu życia tokenów w pamięci podręcznej. Nie ma minimalnych ani maksymalnych wartości TTL.
  3. Inne czynniki: obowiązują inne opłaty, np. za tokeny wejściowe i wyjściowe, które nie są przechowywane w pamięci podręcznej.

Aktualne informacje o cenach znajdziesz na tej stronie dotyczącej Gemini API. Aby dowiedzieć się, jak zliczać tokeny, zapoznaj się z przewodnikiem dotyczącym tokenów.

Uwagi dodatkowe

Podczas korzystania z buforowania kontekstu pamiętaj o tych kwestiach:

  • Minimalna liczba tokenów wejściowych do przechowywania w pamięci podręcznej w kontekście wynosi 4096, a maksymalna – taka sama jak maksymalna dla danego modelu. (więcej informacji o liczeniu tokenów znajdziesz w tym przewodniku).
  • Model nie rozróżnia tokenów z pamięci podręcznej i zwykłych tokenów wejściowych. Treści z pamięci podręcznej to prefiks promptu.
  • Nie ma żadnych specjalnych limitów szybkości ani limitów użycia w przypadku buforowania kontekstu. Obowiązują standardowe limity szybkości dla GenerateContent, a limity tokenów obejmują tokeny buforowane.
  • Liczba tokenów w pamięci podręcznej jest zwracana w usage_metadata z operacji tworzenia, pobierania i wyświetlania listy w usłudze pamięci podręcznej, a także w GenerateContent podczas korzystania z pamięci podręcznej.