Для работы ИИ-функции может потребоваться многократно передавать модели одни и те же входные токены (контент). В таких случаях вы можете кешировать этот контент, то есть передать его модели один раз, сохранить и ссылаться на него в последующих запросах.
Кеширование контекста может значительно снизить задержку и стоимость повторяющихся задач, связанных с большим объемом контента, например с большим количеством текста, аудио- или видеофайлом. Некоторые распространенные варианты использования кэшированного контента включают подробные документы о персонажах, базы кода или руководства.
Модели Gemini предлагают два разных механизма кеширования:
Неявное кеширование автоматически включается для большинства моделей, но не гарантирует экономию.
Явное кеширование можно вручную включить для большинства моделей, чтобы снизить расходы.
Явное кеширование полезно, когда вы хотите гарантировать экономию средств, но при этом готовы к дополнительной работе по разработке.
Как при явном, так и при неявном кешировании поле cachedContentTokenCount в метаданных ответа указывает количество токенов в кешированной части входных данных. Если вы используете явное кеширование, ознакомьтесь с информацией о ценах внизу этой страницы.
Поддерживаемые модели
Кеширование поддерживается при использовании следующих моделей:
gemini-4-argon(только неявное кеширование; явное кеширование не поддерживается)gemini-3.8-flashgemini-3.5-flash-lite(и более старая версияgemini-3.1-flash-lite)
Старые модели общего назначения Gemini 3.x Flash и Gemini 2.5 поддерживают эту функцию, но мы не рекомендуем их использовать, поскольку скоро они будут отключены и/или запросы будут автоматически перенаправляться в более новые модели.
Модели, генерирующие медиаконтент (например, модели Gemini Nano Banana, такие как gemini-nano-banana-2.1), не поддерживают кеширование контекста.
Ограничения на размер кешированного контента
Для кешированного контента у каждой модели есть минимальное требование к количеству токенов. Максимальное значение определяется окном контекста модели.
- 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-argon не поддерживает явное кеширование.
Вот как можно настроить кеширование явного контента и работать с ним:
Управление явными кешами, в том числе:
Обратите внимание, что явное кеширование контента взаимодействует с неявным кешированием, что может привести к дополнительному кешированию помимо явно кешированного контента. Чтобы предотвратить хранение данных в кеше, отключите неявное кеширование и не создавайте явные кеши. Подробнее о том, как включить или отключить кеширование…
Как создать и использовать явный кеш
Чтобы создать и использовать явный кеш контента, необходимо следующее:
Важная информация о создании и использовании явного кеша
Кэш должен соответствовать запросам приложения и шаблону запроса сервера:
Кеш относится к поставщику 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. Добавьте ссылку на шаблон запроса к серверу в запрос из приложения
При составлении запроса обратите особое внимание на следующее:
Используйте Agent Platform Gemini API (formerly Vertex AI), поскольку кеш был создан с помощью этого поставщика Gemini API.
Местоположение, из которого вы получаете доступ к модели в запросе подсказки приложения, должно совпадать с местоположением шаблона подсказки сервера и кеша.
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до истечения срока действия. При настройкеttlexpireTimeкеша обновляется автоматически.expire_time–Timestamp(например,2024-06-30T09:00:00.000000Z), в котором указывается абсолютная дата и время окончания срока действия кеша.
Если вы не зададите ни одно из этих значений, TTL по умолчанию составит один час. Минимальных и максимальных ограничений для 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 в метаданных ответа.