Кэширование контекста

Python JavaScript Go REST

В типичном рабочем процессе ИИ вы можете передавать одни и те же входные токены модели снова и снова. API Gemini предлагает два различных механизма кэширования:

• Неявное кэширование (автоматически включается на большинстве моделей Gemini, гарантия экономии средств не предоставляется).
• Явное кэширование (можно включить вручную на большинстве моделей, гарантирует экономию средств)

Явное кэширование полезно в тех случаях, когда необходимо гарантировать экономию средств, но при этом требуется дополнительная работа со стороны разработчиков.

Неявное кэширование

Неявное кэширование включено по умолчанию и доступно для большинства моделей Gemini. Мы автоматически передаем экономию средств, если ваш запрос попадает в кэш. Вам ничего не нужно делать для его включения. Оно вступает в силу с 8 мая 2025 года. Минимальное количество входных токенов для контекстного кэширования указано в следующей таблице для каждой модели:

Чтобы повысить вероятность попадания в неявный кэш:

• Попробуйте разместить часто встречающиеся и распространенные элементы в начале вашего запроса.
• Постарайтесь отправлять запросы с похожим префиксом в течение короткого промежутка времени.

Количество токенов, попавших в кэш, можно увидеть в поле 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-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 нет.
3. Другие факторы: Взимаются дополнительные сборы, например, за некэшированные входные и выходные токены.

Актуальную информацию о ценах можно найти на странице цен Gemini API. Чтобы узнать, как подсчитывать токены, см. руководство по токенам .

Дополнительные соображения

При использовании контекстного кэширования следует учитывать следующие моменты:

• Минимальное количество входных токенов для контекстного кэширования варьируется в зависимости от модели. Максимальное значение совпадает с максимальным значением для данной модели. (Более подробную информацию о подсчете токенов см. в руководстве по токенам ).
• Данная модель не делает различий между кэшированными токенами и обычными входными токенами. Кэшированное содержимое является префиксом к подсказке.
• Для контекстного кэширования нет специальных ограничений по скорости или использованию; применяются стандартные ограничения скорости для GenerateContent , а ограничения на токены включают кэшированные токены.
• Количество кэшированных токенов возвращается в переменной usage_metadata из операций создания, получения и перечисления в службе кэширования, а также в GenerateContent при использовании кэша.