W typowym procesie AI możesz wielokrotnie przekazywać te same tokeny wejściowe do modelu. Interfejs Gemini API oferuje 2 różne mechanizmy buforowania:
- domyślne buforowanie (automatyczne, bez gwarancji oszczędności),
- Wyraźne buforowanie (ręczne, z gwarancją oszczędności)
W modelach Gemini 2.5 domyślnie jest włączone domyślne buforowanie. Jeśli żądanie zawiera treści, które znajdują się w pamięci podręcznej, automatycznie przekażemy Ci oszczędności.
Wyraźne buforowanie jest przydatne w przypadkach, gdy chcesz zapewnić oszczędności, ale wymaga to dodatkowej pracy programisty.
Buforowanie pośrednie
Domyślnie domyślnie włączone jest domyślne buforowanie w przypadku wszystkich modeli Gemini 2.5. Jeśli Twoje żądanie trafi do pamięci podręcznej, automatycznie przekażemy Ci oszczędności. Nie musisz nic robić, aby włączyć tę funkcję. Zmiany te wejdą w życie 8 maja 2025 r. Minimalna liczba tokenów wejściowych do przechowywania w pamięci podręcznej kontekstu to 1024 w przypadku wersji 2.5 Flash i 2048 w przypadku wersji 2.5 Pro.
Aby zwiększyć szansę na znalezienie danych w pamięci podręcznej:
- Spróbuj umieścić duże i częste treści na początku prompta.
- Próbowanie wysyłania żądań z podobnym prefiksem w krótkim czasie
Liczba tokenów, które zostały znalezione w pamięci podręcznej, jest widoczna w polu usage_metadata obiektu odpowiedzi.
jawna pamięć podręczna.
Korzystając z funkcji jawnego buforowania w interfejsie Gemini API, możesz raz przekazać modelowi treści, 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.
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 pobierać ani wyświetlać 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 });
Kiedy używać pamięci podręcznej na potrzeby konkretnego adresu
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 jawne 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:
- Liczba tokenów w pamięci podręcznej:liczba tokenów wejściowych przechowywanych w pamięci podręcznej, za które pobierana jest obniżona stawka, gdy są one uwzględnione w kolejnych promptach.
- 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.
- 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 to 1024 dla wersji 2.5 Flash i 2048 dla wersji 2.5 Pro. Maksymalna wartość jest taka sama jak maksymalna wartość 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_metadataz operacji tworzenia, pobierania i wyświetlania listy w usłudze pamięci podręcznej, a także wGenerateContentpodczas korzystania z pamięci podręcznej.