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

Для работы ИИ-функции может потребоваться многократно передавать модели одни и те же входные токены (контент). В таких случаях вы можете кешировать этот контент, то есть передать его модели один раз, сохранить и ссылаться на него в последующих запросах.

Кеширование контекста может значительно снизить задержку и стоимость повторяющихся задач, связанных с большим объемом контента, например с большим количеством текста, аудио- или видеофайлом. Некоторые распространенные варианты использования кэшированного контента включают подробные документы о персонажах, базы кода или руководства.

Модели Gemini предлагают два разных механизма кеширования:

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

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

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

Как при явном, так и при неявном кешировании поле cachedContentTokenCount в метаданных ответа указывает количество токенов в кешированной части входных данных. Если вы используете явное кеширование, ознакомьтесь с информацией о ценах внизу этой страницы.

Поддерживаемые модели

Кеширование поддерживается при использовании следующих моделей:

  • gemini-4-hydrogen (только неявное кеширование; явное кеширование не поддерживается)
  • gemini-4-argon (только неявное кеширование; явное кеширование не поддерживается)
  • gemini-4-carbon (только неявное кеширование; явное кеширование не поддерживается)
  • gemini-3.8-flash
  • gemini-3.5-flash-lite (и более старая версия gemini-3.1-flash-lite)

Более старые модели Gemini 3.x Flash общего назначения поддерживают эту функцию, но мы не рекомендуем их использовать, поскольку они скоро будут отключены и/или запросы к ним будут автоматически перенаправляться к более новым моделям.

Модели, генерирующие медиаконтент (например, модели Gemini Nano Banana, такие как gemini-nano-banana-2.1), не поддерживают кеширование контекста.

Ограничения на размер кешированного контента

Для каждой модели установлено минимальное количество токенов в кешированном контенте. Максимальное значение определяется окном контекста модели.

  • Gemini 4 Hydrogen, Gemini 4 Carbon и Gemini 4 Argon: минимум 4096 токенов (Gemini Developer API) или минимум 6144 токена (Agent Platform Gemini API (formerly Vertex AI)).
  • Gemini Pro: минимум 4096 токенов.
  • Модели Gemini Flash: минимум 1024 токена.

Кроме того, максимальный размер контента, который можно кешировать с помощью большого двоичного объекта или текста, составляет 10 МБ.



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

Неявное кеширование включено по умолчанию и доступно для большинства моделей Gemini.

Google автоматически снижает стоимость, если ваш запрос попадает в кешированный контент. Вот несколько способов повысить вероятность того, что в вашем запросе будет использоваться неявное кеширование:

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

Количество токенов в кешированной части входных данных указывается в поле cachedContentTokenCount в метаданных ответа.



Явное кеширование

Явное кеширование не включено по умолчанию и является необязательной функцией моделей Gemini.

Обратите внимание, что модели gemini-4-hydrogen, gemini-4-carbon и gemini-4-argon не поддерживают явное кеширование.

Вот как можно настроить кеширование контента и работать с ним:

Обратите внимание, что явное кеширование контента взаимодействует с неявным кешированием, что может привести к дополнительному кешированию помимо явно кешированного контента. Чтобы предотвратить хранение данных в кеше, отключите неявное кеширование и не создавайте явные кеши. Подробнее о том, как включить или отключить кеширование…



Как создать и использовать явный кеш

Чтобы создать и использовать явный кеш контента, необходимо следующее:

  1. Создайте явный кеш.

  2. Укажите ссылку на кеш в шаблоне запроса к серверу.

  3. Укажите шаблон запроса к серверу в запросе из приложения.

Важная информация о создании и использовании явного кеша

Кэш должен быть согласован с запросами приложения и шаблоном запроса сервера:

  • Кеш относится к поставщику Gemini API. В запросе на показ подсказки в приложении должен использоваться тот же поставщик.
    Для Firebase AI Logic мы настоятельно рекомендуем использовать явные кеши контента только с Agent Platform Gemini API (formerly Vertex AI). Вся информация и примеры на этой странице относятся к поставщику Gemini API.

  • Кеш относится к модели Gemini. В запросе приложения должна использоваться та же модель.

  • При использовании Agent Platform Gemini API (formerly Vertex AI) кеш привязан к местоположению.
    Местоположение явного кеша должно совпадать с местоположением шаблона запроса на сервере и местоположением, где вы получаете доступ к модели в запросе приложения.

Также учитывайте следующие ограничения и требования для явного кеширования:

  • После создания явного кеша вы не можете изменить в нем ничего, кроме TTL или срока действия.

  • Вы можете кешировать любой поддерживаемый MIME-тип входного файла или даже просто текст, указанный в запросе на создание кеша.

  • Если вы хотите включить файл в кеш, укажите его в виде URI Cloud Storage. Это не может быть URL браузера или YouTube.

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

  • Если вы хотите использовать системные инструкции или инструменты (например, выполнение кода, URL-контекст, заземление с помощью Google Search или заземление с помощью Google Maps), то сам кеш должен содержать их конфигурации. Их нельзя настроить в шаблоне запроса на сервере или в запросе приложения. Обратите внимание, что шаблоны запросов на сервере пока не поддерживают вызов функций и чат. Подробную информацию о том, как настроить системные инструкции и инструменты в кеше, можно найти в REST API Agent Platform Gemini API (formerly Vertex AI).

Шаг 1. Создайте кеш

Создайте кеш, напрямую используя REST API Agent Platform Gemini API (formerly Vertex AI).

Ниже приведен пример, в котором создается явный кеш PDF-файла в качестве его контента.

Синтаксис:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3.8-flash
LOCATION="LOCATION"  # location for both the cache and the model
MIME_TYPE="MIME_TYPE"
CACHED_CONTENT_URI="CLOUD_STORAGE_FILE_URI"  # must be a Cloud Storage URI
CACHE_DISPLAY_NAME="CACHE_DISPLAY_NAME"  # optional
TTL="CACHE_TIME_TO_LIVE"  # optional (if not specified, defaults to 3600s)

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Пример запроса:

PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3.8-flash"
LOCATION="global"
MIME_TYPE="application/pdf"
CACHED_CONTENT_URI="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
CACHE_DISPLAY_NAME="Gemini - A Family of Highly Capable Multimodal Model (PDF)"
TTL="7200s"

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Пример ответа:

Ответ содержит полное имя ресурса name, которое является глобально уникальным для кеша (обратите внимание, что последний сегмент – это идентификатор кеша). Это значение name понадобится вам на следующем этапе.

{
  "name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
  "model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3.8-flash",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

Шаг 2. Ссылка на кеш в шаблоне запроса к серверу

После создания кеша сошлитесь на него по name в свойстве cachedContent шаблона запроса к серверу.

При создании шаблона запроса к серверу соблюдайте следующие требования:

  • Используйте полное название ресурса name из ответа, полученного при создании кеша. Это не необязательное отображаемое название, которое вы указали в запросе.

  • Местоположение шаблона запроса на сервере должно совпадать с местоположением кеша.

  • Чтобы использовать системные инструкции или инструменты, их нужно настроить как часть кеша, а не как часть шаблона запроса к серверу.

Синтаксис:

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

{{role "user"}}
{{userPrompt}}

Пример

{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}

{{role "user"}}
{{userPrompt}}

Значением параметра name в шаблоне запроса к серверу также может быть динамическая входная переменная. Например, {{cachedContent name=someVariable}} позволяет включить name кеша в качестве входных данных для запроса из вашего приложения.

Шаг 3. Укажите шаблон запроса к серверу в запросе из приложения

При составлении запроса обратите особое внимание на следующее:

Swift

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform(location: "LOCATION"))
                                  .templateGenerativeModel()

do {
    let response = try await model.generateContent(
        // Specify your template ID.
        templateID: "TEMPLATE_ID"
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
val model = Firebase.ai(backend = GenerativeBackend.agentPlatform(location = "LOCATION"))
                        .templateGenerativeModel()

val response = model.generateContent(
    // Specify your template ID.
    "TEMPLATE_ID",
)

val text = response.text
println(text)

Java

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION"))
      .templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

Future<GenerateContentResponse> response = model.generateContent(
    // Specify your template ID.
    "TEMPLATE_ID"
);
addCallback(response,
      new FutureCallback<GenerateContentResponse>() {
          public void onSuccess(GenerateContentResponse result) {
            System.out.println(result.getText());
          }
          public void onFailure(Throwable t) {
            reportError(t);
          }
    }
executor);

Web

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
const ai = getAI(app, { backend: new AgentPlatformBackend('LOCATION') });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const result = await model.generateContent({
  // Specify your template ID.
  templateId: 'TEMPLATE_ID',
  templateVariables: {},
});

const response = result.response;
const text = response.text();

Dart

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
var _model = FirebaseAI.agentPlatform(location: 'LOCATION').templateGenerativeModel();

var response = await _model.generateContent(
        // Specify your template ID.
        'TEMPLATE_ID',
        inputs: {},
      );

var text = response?.text;
print(text);

Unity

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform(location: "LOCATION"));

// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();

try
{
  var response = await model.GenerateContentAsync(
      // Specify your template ID.
      "TEMPLATE_ID",
      new Dictionary<string, object>()
  );
  Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}



Управление явными кешами

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

Управлять явными кешами можно с помощью REST API Agent Platform Gemini API (formerly Vertex AI).

После создания явного кеша контента вы не можете изменить в нем ничего, кроме TTL или времени окончания срока действия.

Список всех кешей

Вы можете получить список всех явных кешей, доступных для вашего проекта. Эта команда возвращает только кеши в указанном местоположении.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents

Получение метаданных о кеше

Получить или посмотреть кешированный контент невозможно. Однако вы можете получить метаданные о явном кеше, включая name, model, display_name, usage_metadata, create_time, update_time и expire_time.

Вам нужно указать CACHE_ID – последний сегмент полного ресурса name кеша.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}

Как изменить TTL или срок действия кеша

При создании явного кеша можно задать ttl или expire_time.

  • ttl – время жизни кеша, а именно количество секунд и наносекунд, в течение которых кеш существует после создания или после обновления ttl до истечения срока действия. При настройке ttl expireTime кеша обновляется автоматически.

  • expire_time – Timestamp (например, 2024-06-30T09:00:00.000000Z), в котором указывается абсолютная дата и время окончания срока действия кеша.

Если вы не зададите ни одно из этих значений, время жизни по умолчанию составит 1 час. Минимальных и максимальных ограничений для TTL нет.

Для существующих явных кешей можно добавить или обновить ttl или expire_time. Вам нужно указать CACHE_ID – последний сегмент полного ресурса name кеша.

Обновить ttl

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
TTL="CACHE_TIME_TO_LIVE"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "ttl": "'$TTL'"
}'

Обновить expire_time

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
EXPIRE_TIME="ABSOLUTE_TIME_CACHE_EXPIRES"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "expire_time": "'$EXPIRE_TIME'"
}'

Как удалить кеш

Если явный кеш больше не нужен, его можно удалить.

Вам нужно указать CACHE_ID – последний сегмент полного ресурса name кеша.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}



Цены на явное кеширование

Явное кеширование – это платная функция, предназначенная для снижения затрат. Цена зависит от следующих факторов:

  • Входные токены для создания кеша. Как при явном, так и при неявном кешировании вы платите за входные токены, используемые для создания кеша, по стандартной цене.

  • Хранение кеша. При явном кешировании также взимается плата за хранение, которая зависит от того, как долго хранятся кеши. За неявное кеширование плата не взимается. Дополнительную информацию можно найти в разделе Цены на Agent Platform Gemini API (formerly Vertex AI).

  • Использование кешированного контента. Явное кеширование обеспечивает скидку при ссылке на явные кеши, то есть вы получаете скидку на входные токены, когда они ссылаются на существующий кеш. Для моделей Gemini 2.5 и более поздних версий скидка составляет 90 %.

Количество токенов в кешированной части входных данных указывается в поле cachedContentTokenCount в метаданных ответа.