В типичном рабочем процессе ИИ вы можете передавать одни и те же входные токены модели снова и снова. API Gemini предлагает два различных механизма кэширования:
- Неявное кэширование (автоматически включается на большинстве моделей Gemini, гарантия экономии средств не предоставляется).
- Явное кэширование (можно включить вручную на большинстве моделей, гарантирует экономию средств)
Явное кэширование полезно в тех случаях, когда необходимо гарантировать экономию средств, но при этом требуется дополнительная работа со стороны разработчиков.
Неявное кэширование
Неявное кэширование включено по умолчанию и доступно для большинства моделей Gemini. Мы автоматически передаем экономию средств, если ваш запрос попадает в кэш. Вам ничего не нужно делать для его включения. Оно вступает в силу с 8 мая 2025 года. Минимальное количество входных токенов для контекстного кэширования указано в следующей таблице для каждой модели:
| Модель | Минимальный лимит токенов |
|---|---|
| Предварительный просмотр Gemini 3 Flash | 1024 |
| Предварительный просмотр Gemini 3 Pro | 4096 |
| Вспышка Gemini 2.5 | 1024 |
| Gemini 2.5 Pro | 4096 |
Чтобы повысить вероятность попадания в неявный кэш:
- Попробуйте разместить часто встречающиеся и распространенные элементы в начале вашего запроса.
- Постарайтесь отправлять запросы с похожим префиксом в течение короткого промежутка времени.
Количество токенов, попавших в кэш, можно увидеть в поле usage_metadata объекта ответа.
Явное кэширование
Используя функцию явного кэширования в API Gemini, вы можете передать модели некоторое содержимое один раз, кэшировать входные токены, а затем обращаться к кэшированным токенам для последующих запросов. При определенных объемах использование кэшированных токенов обходится дешевле, чем многократная передача одного и того же набора токенов.
При кэшировании набора токенов вы можете выбрать, как долго будет существовать кэш, прежде чем токены будут автоматически удалены. Эта продолжительность кэширования называется временем жизни (TTL). Если значение не задано, TTL по умолчанию составляет 1 час. Стоимость кэширования зависит от размера входных токенов и от того, как долго вы хотите, чтобы токены сохранялись.
В этом разделе предполагается, что вы установили Gemini SDK (или curl) и настроили ключ API, как показано в кратком руководстве .
Генерация контента с использованием кэша.
Python
В следующем примере показано, как создать контент, используя кэшированную системную инструкцию и видеофайл.
Видео
import os
import pathlib
import requests
import time
from google import genai
from google.genai import types
client = genai.Client()
# Download a test video file and save it locally
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
path_to_video_file.write_bytes(requests.get(url).content)
# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)
# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
time.sleep(2.5)
video_file = client.files.get(name=video_file.name)
print(f'Video processing complete: {video_file.uri}')
model='models/gemini-3-flash-preview'
# Create a cache with a 5 minute TTL (300 seconds)
cache = client.caches.create(
model=model,
config=types.CreateCachedContentConfig(
display_name='sherlock jr movie', # used to identify the cache
system_instruction=(
'You are an expert video analyzer, and your job is to answer '
'the user\'s query based on the video file you have access to.'
),
contents=[video_file],
ttl="300s",
)
)
response = client.models.generate_content(
model = model,
contents= (
'Introduce different characters in the movie by describing '
'their personality, looks, and names. Also list the timestamps '
'they were introduced for the first time.'),
config=types.GenerateContentConfig(cached_content=cache.name)
)
print(response.usage_metadata)
print(response.text)
PDF-файлы
from google import genai
from google.genai import types
import io
import httpx
client = genai.Client()
long_context_pdf_path = "https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"
# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)
document = client.files.upload(
file=doc_io,
config=dict(mime_type='application/pdf')
)
model_name = "gemini-3-flash-preview"
system_instruction = "You are an expert analyzing transcripts."
# Create a cached content object
cache = client.caches.create(
model=model_name,
config=types.CreateCachedContentConfig(
system_instruction=system_instruction,
contents=[document],
)
)
print(f'{cache=}')
response = client.models.generate_content(
model=model_name,
contents="Please summarize this transcript",
config=types.GenerateContentConfig(
cached_content=cache.name
))
print(f'{response.usage_metadata=}')
print('\n\n', response.text)
JavaScript
В следующем примере показано, как сгенерировать контент, используя кэшированную системную инструкцию и текстовый файл.
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();
Идти
В следующем примере показано, как генерировать контент с использованием кэша.
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: "GOOGLE_API_KEY",
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
modelName := "gemini-3-flash-preview"
document, err := client.Files.UploadFromPath(
ctx,
"media/a11.txt",
&genai.UploadFileConfig{
MIMEType: "text/plain",
},
)
if err != nil {
log.Fatal(err)
}
parts := []*genai.Part{
genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
Contents: contents,
SystemInstruction: genai.NewContentFromText(
"You are an expert analyzing transcripts.", genai.RoleUser,
),
})
if err != nil {
log.Fatal(err)
}
fmt.Println("Cache created:")
fmt.Println(cache)
// Use the cache for generating content.
response, err := client.Models.GenerateContent(
ctx,
modelName,
genai.Text("Please summarize this transcript"),
&genai.GenerateContentConfig{
CachedContent: cache.Name,
},
)
if err != nil {
log.Fatal(err)
}
printResponse(response) // helper for printing response parts
}
ОТДЫХ
В следующем примере показано, как создать кэш, а затем использовать его для генерации контента.
Видео
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
"model": "models/gemini-3-flash-preview",
"contents":[
{
"parts":[
{
"inline_data": {
"mime_type":"text/plain",
"data": "'$(base64 $B64FLAGS a11.txt)'"
}
}
],
"role": "user"
}
],
"systemInstruction": {
"parts": [
{
"text": "You are an expert at analyzing transcripts."
}
]
},
"ttl": "300s"
}' > request.json
curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json
CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [
{
"parts":[{
"text": "Please summarize this transcript"
}],
"role": "user"
},
],
"cachedContent": "'$CACHE_NAME'"
}'
PDF-файлы
DOC_URL="https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"
DISPLAY_NAME="A11_Mission_Report"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-3-flash-preview"
TTL="300s"
# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"
MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")
NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")
echo "MIME_TYPE: ${MIME_TYPE}"
echo "NUM_BYTES: ${NUM_BYTES}"
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
-D upload-header.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
echo "file_uri: ${file_uri}"
# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"
# Create the cached content request
echo '{
"model": "'$MODEL'",
"contents":[
{
"parts":[
{"file_data": {"mime_type": "'$MIME_TYPE'", "file_uri": '$file_uri'}}
],
"role": "user"
}
],
"system_instruction": {
"parts": [
{
"text": "'$SYSTEM_INSTRUCTION'"
}
],
"role": "system"
},
"ttl": "'$TTL'"
}' > request.json
# Send the cached content request
curl -X POST "${BASE_URL}/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json
CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)
echo "CACHE_NAME: ${CACHE_NAME}"
# Send the generateContent request using the cached content
curl -X POST "${BASE_URL}/${MODEL}:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [
{
"parts":[{
"text": "'$PROMPT'"
}],
"role": "user"
}
],
"cachedContent": "'$CACHE_NAME'"
}' > response.json
cat response.json
echo jq ".candidates[].content.parts[].text" response.json
Список кэшей
Получить или просмотреть кэшированное содержимое невозможно, но можно получить метаданные кэша ( name , model , display_name , usage_metadata , create_time , update_time и expire_time ).
Python
Чтобы вывести список метаданных для всех загруженных кэшей, используйте CachedContent.list() :
for cache in client.caches.list():
print(cache)
Чтобы получить метаданные для объекта кэша, если вам известно его имя, используйте get .
client.caches.get(name=name)
JavaScript
Чтобы получить список метаданных для всех загруженных кэшей, используйте 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();
}
Идти
В следующем примере приведен список всех кэшей.
caches, err := client.Caches.All(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println("Listing all caches:")
for _, item := range caches {
fmt.Println(" ", item.Name)
}
В следующем примере приведен список кэшей, использующих размер страницы 2.
page, err := client.Caches.List(ctx, &genai.ListCachedContentsConfig{PageSize: 2})
if err != nil {
log.Fatal(err)
}
pageIndex := 1
for {
fmt.Printf("Listing caches (page %d):\n", pageIndex)
for _, item := range page.Items {
fmt.Println(" ", item.Name)
}
if page.NextPageToken == "" {
break
}
page, err = page.Next(ctx)
if err == genai.ErrPageDone {
break
} else if err != nil {
return err
}
pageIndex++
}
ОТДЫХ
curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"
Обновить кэш
Вы можете установить новое ttl или expire_time для кэша. Изменение любых других параметров кэша не поддерживается.
Python
В следующем примере показано, как обновить ttl кэша с помощью client.caches.update() .
from google import genai
from google.genai import types
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
ttl='300s'
)
)
Для установки времени истечения срока действия принимается либо объект datetime , либо строка datetime в формате ISO (например, dt.isoformat() , например, 2025-01-27T16:02:36.473528+00:00 ). Ваше время должно включать часовой пояс ( datetime.utcnow() не добавляет часовой пояс, datetime.now(datetime.timezone.utc) добавляет).
from google import genai
from google.genai import types
import datetime
# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
expire_time=in10min
)
)
JavaScript
В следующем примере показано, как обновить 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);
Идти
В следующем примере показано, как обновить TTL кэша.
// Update the TTL (2 hours).
cache, err = client.Caches.Update(ctx, cache.Name, &genai.UpdateCachedContentConfig{
TTL: 7200 * time.Second,
})
if err != nil {
log.Fatal(err)
}
fmt.Println("After update:")
fmt.Println(cache)
ОТДЫХ
В следующем примере показано, как обновить ttl кэша.
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"ttl": "600s"}'
Удалить кэш
Служба кэширования предоставляет функцию удаления для ручного удаления содержимого из кэша. В следующем примере показано, как удалить кэш:
Python
client.caches.delete(cache.name)
JavaScript
await ai.caches.delete({ name: cache.name });
Идти
_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
if err != nil {
log.Fatal(err)
}
fmt.Println("Cache deleted:", cache.Name)
ОТДЫХ
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"
Явное кэширование с использованием библиотеки OpenAI.
Если вы используете библиотеку OpenAI , вы можете включить явное кэширование, используя свойство cached_content объекта extra_body .
Когда следует использовать явное кэширование?
Кэширование контекста особенно хорошо подходит для сценариев, где существенный начальный контекст многократно используется в более коротких запросах. Рассмотрите возможность использования кэширования контекста в таких случаях, как:
- Чат-боты с подробными инструкциями по использованию системы .
- Повторный анализ длинных видеофайлов
- Повторяющиеся запросы к большим наборам документов
- Регулярный анализ репозитория кода или исправление ошибок.
Как явное кэширование снижает затраты
Кэширование контекста — это платная функция, предназначенная для снижения затрат. Оплата производится на основе следующих факторов:
- Количество кэшированных токенов: число кэшированных входных токенов, оплата за которые производится по сниженной ставке при их включении в последующие запросы.
- Срок хранения: время, в течение которого кэшированные токены хранятся (TTL), оплата производится исходя из срока хранения количества кэшированных токенов. Минимальных или максимальных ограничений по TTL нет.
- Другие факторы: Взимаются дополнительные сборы, например, за некэшированные входные и выходные токены.
Актуальную информацию о ценах можно найти на странице цен Gemini API. Чтобы узнать, как подсчитывать токены, см. руководство по токенам .
Дополнительные соображения
При использовании контекстного кэширования следует учитывать следующие моменты:
- Минимальное количество входных токенов для контекстного кэширования варьируется в зависимости от модели. Максимальное значение совпадает с максимальным значением для данной модели. (Более подробную информацию о подсчете токенов см. в руководстве по токенам ).
- Данная модель не делает различий между кэшированными токенами и обычными входными токенами. Кэшированное содержимое является префиксом к подсказке.
- Для контекстного кэширования нет специальных ограничений по скорости или использованию; применяются стандартные ограничения скорости для
GenerateContent, а ограничения на токены включают кэшированные токены. - Количество кэшированных токенов возвращается в параметре
usage_metadataиз операций создания, получения и перечисления в службе кэширования, а также вGenerateContentпри использовании кэша.