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

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

  • Неявное кэширование (автоматическое, без гарантии экономии)
  • Явное кэширование (ручное, гарантия экономии)

Неявное кэширование включено в моделях Gemini 2.5 по умолчанию. Если запрос содержит контент, попадающий в кеш, мы автоматически возвращаем вам экономию средств.

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

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

Неявное кэширование включено по умолчанию для всех моделей Gemini 2.5. Мы автоматически снижаем затраты, если ваш запрос попадает в кэш. Для этого вам не нужно ничего делать. Он вступает в силу с 8 мая 2025 г. Минимальное количество входных токенов для кэширования контекста составляет 1024 для 2.5 Flash и 2048 для 2.5 Pro.

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

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

Вы можете увидеть количество токенов, попавших в кэш, в поле usage_metadata объекта ответа.

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

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

Когда вы кэшируете набор токенов, вы можете выбрать, как долго вы хотите, чтобы кеш существовал, прежде чем токены будут автоматически удалены. Эта продолжительность кэширования называется временем жизни (TTL). Если этот параметр не установлен, значение TTL по умолчанию составляет 1 час. Стоимость кэширования зависит от размера входного токена и того, как долго вы хотите, чтобы токены сохранялись.

В этом разделе предполагается, что вы установили Gemini SDK (или установили Curl) и настроили ключ API, как показано в кратком руководстве .

Генерация контента с использованием кеша

В следующем примере показано, как создать кэш и затем использовать его для создания контента.

Видео PDF-файлы 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "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-2.0-flash-001:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

DOC_URL="https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
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 , displayName , usageMetadata , createTime , updateTime и expireTime ). 

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

Обновить кэш

Вы можете установить новый ttl или expireTime для кеша. Изменение чего-либо еще в кеше не поддерживается.

В следующем примере показано, как обновить ttl кэша. 

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

Удалить кэш

Служба кэширования предоставляет операцию удаления для ручного удаления содержимого из кэша. В следующем примере показано, как удалить кэш. 

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

Когда использовать явное кэширование

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

  • Чат-боты с подробными системными инструкциями
  • Повторный анализ длинных видеофайлов
  • Повторяющиеся запросы к большим наборам документов
  • Частый анализ репозитория кода или исправление ошибок

Как явное кэширование снижает затраты

Кэширование контекста — это платная функция, предназначенная для снижения общих эксплуатационных расходов. Выставление счетов зависит от следующих факторов:

  1. Количество токенов кэша: количество кэшированных входных токенов, оплачиваемых по сниженной ставке при включении в последующие запросы.
  2. Продолжительность хранения: количество времени хранения кэшированных токенов (TTL), оплата взимается на основе продолжительности TTL количества кэшированных токенов. Для TTL нет минимальных или максимальных границ.
  3. Другие факторы: взимаются другие сборы, например, за некэшированные входные токены и выходные токены.

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

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

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

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

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

  • Неявное кэширование (автоматическое, без гарантии экономии)
  • Явное кэширование (ручное, гарантия экономии)

Неявное кэширование включено в моделях Gemini 2.5 по умолчанию. Если запрос содержит контент, попадающий в кеш, мы автоматически возвращаем вам экономию средств.

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

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

Неявное кэширование включено по умолчанию для всех моделей Gemini 2.5. Мы автоматически снижаем затраты, если ваш запрос попадает в кэш. Для этого вам не нужно ничего делать. Он вступает в силу с 8 мая 2025 г. Минимальное количество входных токенов для кэширования контекста составляет 1024 для 2.5 Flash и 2048 для 2.5 Pro.

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

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

Вы можете увидеть количество токенов, попавших в кэш, в поле usage_metadata объекта ответа.

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

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

Когда вы кэшируете набор токенов, вы можете выбрать, как долго вы хотите, чтобы кеш существовал, прежде чем токены будут автоматически удалены. Эта продолжительность кэширования называется временем жизни (TTL). Если значение не установлено, значение TTL по умолчанию составляет 1 час. Стоимость кэширования зависит от размера входного токена и того, как долго вы хотите, чтобы токены сохранялись.

В этом разделе предполагается, что вы установили Gemini SDK (или установили Curl) и настроили ключ API, как показано в кратком руководстве .

Генерация контента с использованием кеша

В следующем примере показано, как создать кэш и затем использовать его для создания контента.

Видео PDF-файлы 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "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-2.0-flash-001:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

DOC_URL="https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
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 , displayName , usageMetadata , createTime , updateTime и expireTime ). 

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

Обновить кэш

Вы можете установить новый ttl или expireTime для кеша. Изменение чего-либо еще в кеше не поддерживается.

В следующем примере показано, как обновить ttl кэша. 

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

Удалить кэш

Служба кэширования предоставляет операцию удаления для ручного удаления содержимого из кэша. В следующем примере показано, как удалить кэш. 

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

Когда использовать явное кэширование

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

  • Чат-боты с подробными системными инструкциями
  • Повторный анализ длинных видеофайлов
  • Повторяющиеся запросы к большим наборам документов
  • Частый анализ репозитория кода или исправление ошибок

Как явное кэширование снижает затраты

Кэширование контекста — это платная функция, предназначенная для снижения общих эксплуатационных расходов. Выставление счетов зависит от следующих факторов:

  1. Количество токенов кэша: количество кэшированных входных токенов, оплачиваемых по сниженной ставке при включении в последующие запросы.
  2. Продолжительность хранения: количество времени хранения кэшированных токенов (TTL), оплата взимается на основе продолжительности TTL количества кэшированных токенов. Для TTL нет минимальных или максимальных границ.
  3. Другие факторы: взимаются другие сборы, например, за некэшированные входные токены и выходные токены.

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

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

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

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

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

  • Неявное кэширование (автоматическое, без гарантии экономии)
  • Явное кэширование (ручное, гарантия экономии)

Неявное кэширование включено в моделях Gemini 2.5 по умолчанию. Если запрос содержит контент, попадающий в кеш, мы автоматически возвращаем вам экономию средств.

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

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

Неявное кэширование включено по умолчанию для всех моделей Gemini 2.5. Мы автоматически снижаем затраты, если ваш запрос попадает в кэш. Для этого вам не нужно ничего делать. Он вступает в силу с 8 мая 2025 г. Минимальное количество входных токенов для кэширования контекста составляет 1024 для 2.5 Flash и 2048 для 2.5 Pro.

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

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

Вы можете увидеть количество токенов, попавших в кэш, в поле usage_metadata объекта ответа.

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

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

Когда вы кэшируете набор токенов, вы можете выбрать, как долго вы хотите, чтобы кеш существовал, прежде чем токены будут автоматически удалены. Эта продолжительность кэширования называется временем жизни (TTL). Если этот параметр не установлен, значение TTL по умолчанию составляет 1 час. Стоимость кэширования зависит от размера входного токена и того, как долго вы хотите, чтобы токены сохранялись.

В этом разделе предполагается, что вы установили Gemini SDK (или установили Curl) и настроили ключ API, как показано в кратком руководстве .

Генерация контента с использованием кеша

В следующем примере показано, как создать кэш и затем использовать его для создания контента.

Видео PDF-файлы 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "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-2.0-flash-001:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

DOC_URL="https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
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 , displayName , usageMetadata , createTime , updateTime и expireTime ). 

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

Обновить кэш

Вы можете установить новый ttl или expireTime для кеша. Изменение чего-либо еще в кеше не поддерживается.

В следующем примере показано, как обновить ttl кэша. 

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

Удалить кэш

Служба кэширования предоставляет операцию удаления для ручного удаления содержимого из кэша. В следующем примере показано, как удалить кэш. 

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

Когда использовать явное кэширование

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

  • Чат-боты с подробными системными инструкциями
  • Повторный анализ длинных видеофайлов
  • Повторяющиеся запросы к большим наборам документов
  • Частый анализ репозитория кода или исправление ошибок

Как явное кэширование снижает затраты

Кэширование контекста — это платная функция, предназначенная для снижения общих эксплуатационных расходов. Выставление счетов зависит от следующих факторов:

  1. Количество токенов кэша: количество кэшированных входных токенов, оплачиваемых по сниженной ставке при включении в последующие запросы.
  2. Продолжительность хранения: количество времени хранения кэшированных токенов (TTL), оплата взимается на основе продолжительности TTL количества кэшированных токенов. Для TTL нет минимальных или максимальных границ.
  3. Другие факторы: взимаются другие сборы, например, за некэшированные входные токены и выходные токены.

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

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

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

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

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

  • Неявное кэширование (автоматическое, без гарантии экономии)
  • Явное кэширование (ручное, гарантия экономии)

Неявное кэширование включено в моделях Gemini 2.5 по умолчанию. Если запрос содержит контент, попадающий в кеш, мы автоматически возвращаем вам экономию средств.

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

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

Неявное кэширование включено по умолчанию для всех моделей Gemini 2.5. Мы автоматически снижаем затраты, если ваш запрос попадает в кэш. Для этого вам не нужно ничего делать. Он вступает в силу с 8 мая 2025 г. Минимальное количество входных токенов для кэширования контекста составляет 1024 для 2.5 Flash и 2048 для 2.5 Pro.

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

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

Вы можете увидеть количество токенов, попавших в кэш, в поле usage_metadata объекта ответа.

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

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

Когда вы кэшируете набор токенов, вы можете выбрать, как долго вы хотите, чтобы кеш существовал, прежде чем токены будут автоматически удалены. Эта продолжительность кэширования называется временем жизни (TTL). Если значение не установлено, значение TTL по умолчанию составляет 1 час. Стоимость кэширования зависит от размера входного токена и того, как долго вы хотите, чтобы токены сохранялись.

В этом разделе предполагается, что вы установили Gemini SDK (или установили Curl) и настроили ключ API, как показано в кратком руководстве .

Генерация контента с использованием кеша

В следующем примере показано, как создать кэш и затем использовать его для создания контента.

Видео PDF-файлы 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "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-2.0-flash-001:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

DOC_URL="https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
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 , displayName , usageMetadata , createTime , updateTime и expireTime ). 

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

Обновить кэш

Вы можете установить новый ttl или expireTime для кеша. Изменение чего-либо еще в кеше не поддерживается.

В следующем примере показано, как обновить ttl кэша. 

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

Удалить кэш

Служба кэширования предоставляет операцию удаления для ручного удаления содержимого из кэша. В следующем примере показано, как удалить кэш. 

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

Когда использовать явное кэширование

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

  • Чат-боты с подробными системными инструкциями
  • Повторный анализ длинных видеофайлов
  • Повторяющиеся запросы к большим наборам документов
  • Частый анализ репозитория кода или исправление ошибок

Как явное кэширование снижает затраты

Кэширование контекста — это платная функция, предназначенная для снижения общих эксплуатационных расходов. Выставление счетов зависит от следующих факторов:

  1. Количество токенов кэша: количество кэшированных входных токенов, оплачиваемых по сниженной ставке при включении в последующие запросы.
  2. Продолжительность хранения: количество времени хранения кэшированных токенов (TTL), оплата взимается на основе продолжительности TTL количества кэшированных токенов. Для TTL нет минимальных или максимальных границ.
  3. Другие факторы: взимаются другие сборы, например, за некэшированные входные токены и выходные токены.

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

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

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

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