Окей, разложу всё по полочкам, как для человека, который вообще не в теме API и токенов.

Сначала — в чём вообще проблема?

Когда ты общаешься с нейросетью через API (программный доступ), ты платишь за каждый токен (кусочек слова), который отправляешь и получаешь. Если у тебя есть большой документ — например, юридический кодекс на 500 000 токенов — и ты хочешь задавать по нему разные вопросы, то по-глупому это выглядит так:

Вопрос 1: отправляешь весь кодекс (500k токенов) + вопрос → платишь за 500k+
Вопрос 2: снова отправляешь весь кодекс (500k токенов) + другой вопрос → платишь ещё раз за 500k+
Вопрос 3: то же самое...

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

Что такое Context Caching (кэширование контекста)?

Это функция, которая говорит серверу Google: "Запомни этот документ на своей стороне на пару часов, чтобы я не пересылал его заново".

Аналогия: ты один раз привозишь книгу библиотекарю и говоришь "подержи её у себя 2 часа". Дальше ты просто звонишь и спрашиваешь: "Что там на странице 50?" — и платишь только за сам вопрос, а не за перевозку книги туда-обратно.

Экономия: Google даёт скидку ~75% на токены, которые лежат в кэше, по сравнению с обычной ценой.

Разбор кода по шагам
python
import os
import google.generativeai as genai
from google.generativeai import caching
import datetime

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

python
genai.configure(api_key=os.environ["GEMINI_API_KEY"])

Ты говоришь библиотеке: "вот мой ключ доступа" (пароль от твоего аккаунта в Gemini API). Ключ хранится в переменной окружения — то есть не написан прямо в коде текстом, а лежит отдельно в настройках системы (это безопаснее).

python
document = genai.upload_file("big_corporate_knowledge_base.pdf")

Загружаешь свой PDF-файл (например, 500-страничную базу знаний компании) на серверы Google. Это как отвезти книгу библиотекарю.

python
cache = caching.CachedContent.create(
    model='models/gemini-1.5-flash-001',
    display_name='corp_kb_cache',
    contents=[document],
    ttl=datetime.timedelta(hours=2),
)

Здесь ты создаёшь сам кэш:

model — какую модель Gemini использовать
display_name — просто имя-ярлычок для этого кэша, чтобы ты сам его узнавал
contents=[document] — что именно кэшируем (наш PDF)
ttl=datetime.timedelta(hours=2) — TTL = Time To Live, "время жизни". Через 2 часа кэш сам удалится с сервера, и если захочешь снова — придётся кэшировать заново.

Аналогия с библиотекарем: "подержи книгу у себя 2 часа, а потом можешь убрать обратно на склад".

python
model = genai.GenerativeModel.from_cached_content(cached_content=cache)
response = model.generate_content("Какие правила компенсации больничных в компании?")
print(response.text)

Теперь ты создаёшь "модель", которая уже привязана к закэшированному документу. Когда ты задаёшь вопрос — ты не пересылаешь документ заново, а просто спрашиваешь. Сервер сам достаёт документ из своей "памяти" (кэша) и отвечает.

Важный нюанс: в самом первом запросе (когда создаёшь кэш) ты платишь полную цену за загрузку документа. А вот все последующие вопросы к этому же кэшу — уже со скидкой 75% на входные токены, потому что документ уже "лежит на складе" у Google.

Шаг 2: чистка системных промптов (Token Pruning)

Это отдельная, более простая идея — экономия на том тексте, который ты сам пишешь как инструкцию модели (system prompt).

Пример "жирного" промпта:

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

Тот же промпт после "прунинга" (обрезки):

yaml
role: assistant
style: polite, detailed
task: answer product questions

Смысл один и тот же, но во втором варианте в разы меньше токенов, потому что убраны вводные слова-паразиты ("пожалуйста", "если это возможно", "я бы хотел") и убрана "разговорная вода" в пользу компактной структуры YAML/JSON.

Итог одной фразой

Context Caching = "не таскай туда-сюда один и тот же тяжёлый документ, оставь его на сервере и просто спрашивай" → экономия до 75% на повторяющемся контексте + ответы быстрее в разы, потому что серверу не нужно заново "читать" весь документ.

Если что-то из шагов непонятно на практике (например, как достать API-ключ или где взять переменные окружения) — спрашивай, разберём отдельно.