В типичном рабочем процессе ИИ вы можете передавать одни и те же входные токены модели снова и снова. API Gemini предлагает два различных механизма кэширования:
- Неявное кэширование (автоматически включается на моделях Gemini 2.5, экономия средств не гарантируется)
- Явное кэширование (можно включить вручную на большинстве моделей, гарантия экономии средств)
Явное кэширование полезно в случаях, когда вы хотите гарантировать экономию средств, но с некоторой дополнительной работой разработчика.
Неявное кэширование
Неявное кэширование включено по умолчанию для всех моделей Gemini 2.5. Мы автоматически передаем экономию средств, если ваш запрос попадает в кэш. Для включения этой функции вам ничего делать не нужно. Она вступает в силу с 8 мая 2025 года. Минимальное количество входных токенов для кэширования контекста указано в следующей таблице для каждой модели:
| Модель | Минимальный лимит токенов |
|---|---|
| Предварительный обзор Gemini 3 Pro | 4096 |
| Джемини 2.5 Про | 4096 |
| Близнецы 2.5 Флэш | 1024 |
Чтобы увеличить вероятность неявного попадания в кэш:
- Попробуйте поместить объемное и распространенное содержимое в начало вашего запроса.
- Попробуйте отправлять запросы с похожим префиксом за короткий промежуток времени.
Количество токенов, попавших в кэш, можно увидеть в поле usage_metadata объекта ответа.
Явное кэширование
Используя функцию явного кэширования API Gemini, вы можете один раз передать часть контента модели, кэшировать входные токены, а затем обращаться к кэшированным токенам для последующих запросов. При определённых объёмах использование кэшированных токенов обходится дешевле, чем многократная передача одного и того же набора токенов.
При кэшировании набора токенов вы можете выбрать длительность существования кэша, после чего токены будут автоматически удалены. Этот срок кэширования называется временем жизни (TTL). Если значение не задано, TTL по умолчанию равен 1 часу. Стоимость кэширования зависит от размера входного токена и желаемого срока хранения токенов.
В этом разделе предполагается, что вы установили 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 });
Явное кэширование с использованием библиотеки OpenAI
Если вы используете библиотеку OpenAI , вы можете включить явное кэширование с помощью свойства cached_content в extra_body .
Когда следует использовать явное кэширование
Кэширование контекста особенно хорошо подходит для сценариев, где к существенному исходному контексту многократно обращаются короткие запросы. Рассмотрите возможность использования кэширования контекста в таких случаях:
- Чат-боты с подробными системными инструкциями
- Повторный анализ длинных видеофайлов
- Повторяющиеся запросы к большим наборам документов
- Частый анализ репозитория кода или исправление ошибок
Как явное кэширование снижает затраты
Кэширование контекста — платная функция, разработанная для снижения общих эксплуатационных расходов. Тарификация рассчитывается на основе следующих факторов:
- Количество кэшированных токенов ввода: количество кэшированных токенов ввода, тарифицируемых по сниженной ставке при включении в последующие запросы.
- Срок хранения: время хранения кэшированных токенов (TTL), тарифицируемое на основе срока хранения количества кэшированных токенов. Ограничений по минимальному или максимальному сроку хранения нет.
- Другие факторы: применяются другие сборы, например, за некэшированные входные токены и выходные токены.
Актуальную информацию о ценах можно найти на странице цен Gemini API. Чтобы узнать, как подсчитывать токены, см. руководство по токенам .
Дополнительные соображения
При использовании кэширования контекста следует учитывать следующие соображения:
- Минимальное количество входных токенов для кэширования контекста составляет 1024 для 2.5 Flash, 4096 для 2.5 Pro и 2048 для 3 Pro Preview. Максимальное количество совпадает с максимальным количеством для данной модели. (Подробнее о подсчёте токенов см. в руководстве по токенам ).
- Модель не делает различий между кэшированными токенами и обычными входными токенами. Кэшированное содержимое — это префикс к приглашению.
- Никаких специальных ограничений по скорости или использованию кэширования контекста не существует; действуют стандартные ограничения по скорости для
GenerateContent, а ограничения по токенам включают кэшированные токены. - Количество кэшированных токенов возвращается в
usage_metadataиз операций create, get и list службы кэширования, а также вGenerateContentпри использовании кэша.