Buforowanie kontekstu

W typowym przepływie pracy AI możesz wielokrotnie przekazywać do modelu te same tokeny wejściowe. Interfejs Gemini API oferuje 2 różne mechanizmy buforowania:

  • niejawne buforowanie (automatycznie włączone w przypadku modeli Gemini 2.5, bez gwarancji oszczędności);
  • Buforowanie jawne (można je włączyć ręcznie w przypadku większości modeli, gwarancja oszczędności)

Jawne buforowanie jest przydatne w sytuacjach, w których chcesz zagwarantować oszczędności, ale wymaga to dodatkowej pracy programisty.

Niejawne buforowanie

Pamięć podręczna jest domyślnie włączona we wszystkich modelach Gemini 2.5. Jeśli Twoje żądanie trafi do pamięci podręcznej, automatycznie przekażemy Ci oszczędności. Aby to włączyć, nie musisz nic robić. Obowiązuje od 8 maja 2025 r. Minimalna liczba tokenów wejściowych w przypadku buforowania kontekstu wynosi 1024 w przypadku modelu 2.5 Flash i 4096 w przypadku modelu 2.5 Pro.

Aby zwiększyć szansę na niejawne trafienie w pamięci podręcznej:

  • Spróbuj umieścić na początku promptu duże i popularne treści.
  • Wysyłanie w krótkim czasie żądań z podobnym prefiksem

Liczbę tokenów, które zostały znalezione w pamięci podręcznej, możesz sprawdzić w polu usage_metadata obiektu odpowiedzi.

Jawne buforowanie

Korzystając z funkcji jawnego buforowania interfejsu Gemini API, możesz przekazać niektóre treści do modelu tylko raz, zapisać w pamięci podręcznej tokeny wejściowe, a następnie odwoływać się do nich w kolejnych żądaniach. Przy określonych ilościach używanie tokenów w pamięci podręcznej jest tańsze niż wielokrotne przekazywanie tego samego korpusu tokenów.

Gdy zapisujesz w pamięci podręcznej zestaw tokenów, możesz określić, jak długo ma ona istnieć, zanim tokeny zostaną automatycznie usunięte. Ten czas przechowywania w pamięci podręcznej nazywa się czasem życia danych (TTL). Jeśli nie jest ustawiony, domyślny TTL wynosi 1 godzinę. Koszt buforowania zależy od rozmiaru tokena wejściowego i czasu, przez jaki chcesz przechowywać tokeny.

W tej sekcji zakładamy, że masz zainstalowany pakiet Gemini SDK (lub narzędzie curl) i skonfigurowany klucz interfejsu API, jak pokazano w szybkim wprowadzeniu.

Generowanie treści za pomocą pamięci podręcznej

Poniższy przykład pokazuje, jak wygenerować treść za pomocą instrukcji systemowej i pliku wideo z pamięci podręcznej.

Filmy

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

client = genai.Client()

# Download video file
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():
  with path_to_video_file.open('wb') as wf:
    response = requests.get(url, stream=True)
    for chunk in response.iter_content(chunk_size=32768):
      wf.write(chunk)

# 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':
  print('Waiting for video to be processed.')
  time.sleep(2)
  video_file = client.files.get(name=video_file.name)

print(f'Video processing complete: {video_file.uri}')

# You must use an explicit version suffix: "-flash-001", not just "-flash".
model='models/gemini-2.0-flash-001'

# Create a cache with a 5 minute TTL
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",
  )
)

# Construct a GenerativeModel which uses the created cache.
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)

# The output should look something like this:
#
# prompt_token_count: 696219
# cached_content_token_count: 696190
# candidates_token_count: 214
# total_token_count: 696433

print(response.text)

Pliki PDF

from google import genai
from google.genai import types
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.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-2.0-flash-001"
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],
    )
)

# Display the cache details
print(f'{cache=}')

# Generate content using the cached prompt and document
response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

# (Optional) Print usage metadata for insights into the API call
print(f'{response.usage_metadata=}')

# Print the generated text
print('\n\n', response.text)

Wyświetlanie listy pamięci podręcznych

Nie można pobrać ani wyświetlić treści z pamięci podręcznej, ale można pobrać metadane pamięci podręcznej (name, model, display_name, usage_metadata, create_time, update_time i expire_time).

Aby wyświetlić metadane wszystkich przesłanych pamięci podręcznych, użyj tego polecenia: CachedContent.list()

for cache in client.caches.list():
  print(cache)

Aby pobrać metadane jednego obiektu pamięci podręcznej, jeśli znasz jego nazwę, użyj polecenia get:

client.caches.get(name=name)

Aktualizowanie pamięci podręcznej

Możesz ustawić nowy ttl lub expire_time dla pamięci podręcznej. Nie można zmienić żadnych innych ustawień pamięci podręcznej.

Poniższy przykład pokazuje, jak zaktualizować ttl pamięci podręcznej za pomocą client.caches.update().

from google import genai
from google.genai import types

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      ttl='300s'
  )
)

Aby ustawić czas wygaśnięcia, możesz podać datetimeobiektdatetime lub ciąg tekstowy daty i godziny w formacie ISO (dt.isoformat(), np. 2025-01-27T16:02:36.473528+00:00). Musisz podać strefę czasową (datetime.utcnow() nie dołącza strefy czasowej, datetime.now(datetime.timezone.utc) dołącza strefę czasową).

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
  )
)

Usuwanie pamięci podręcznej

Usługa buforowania udostępnia operację usuwania, która umożliwia ręczne usuwanie treści z pamięci podręcznej. Poniższy przykład pokazuje, jak usunąć pamięć podręczną:

client.caches.delete(cache.name)

Jawne buforowanie za pomocą biblioteki OpenAI

Jeśli używasz biblioteki OpenAI, możesz włączyć jawne buforowanie za pomocą właściwości cached_content w extra_body.

Kiedy używać jawnego buforowania

Pamięć podręczna kontekstu jest szczególnie przydatna w scenariuszach, w których obszerny kontekst początkowy jest wielokrotnie wykorzystywany w krótszych żądaniach. Pamięć podręczna kontekstu może być przydatna w przypadkach takich jak:

  • Czatboty z obszernymi instrukcjami systemowymi
  • Powtarzalna analiza długich plików wideo
  • Powtarzające się zapytania dotyczące dużych zbiorów dokumentów
  • częste analizowanie repozytorium kodu lub naprawianie błędów;

Jak jawne buforowanie zmniejsza koszty

Pamięć podręczna kontekstu to płatna funkcja, która ma na celu obniżenie ogólnych kosztów operacyjnych. Płatności są określane na podstawie tych czynników:

  1. Liczba tokenów w pamięci podręcznej: liczba tokenów wejściowych w pamięci podręcznej, za które naliczana jest niższa opłata, gdy są uwzględniane w kolejnych promptach.
  2. Czas przechowywania: czas przechowywania tokenów w pamięci podręcznej (TTL), rozliczany na podstawie czasu TTL liczby tokenów w pamięci podręcznej. Nie ma minimalnych ani maksymalnych ograniczeń dotyczących wartości TTL.
  3. Inne czynniki: obowiązują inne opłaty, np. za tokeny wejściowe niepochodzące z pamięci podręcznej i tokeny wyjściowe.

Aktualne informacje o cenach znajdziesz na stronie z cennikiem Gemini API. Aby dowiedzieć się, jak liczyć tokeny, zapoznaj się z przewodnikiem po tokenach.

Uwagi dodatkowe

Korzystając z pamięci podręcznej kontekstu, pamiętaj o tych kwestiach:

  • Minimalna liczba tokenów wejściowych w przypadku buforowania kontekstu wynosi 1024 w przypadku modelu 2.5 Flash i 2048 w przypadku modelu 2.5 Pro. Maksymalna wartość jest taka sama jak maksymalna wartość dla danego modelu. (Więcej informacji o liczeniu tokenów znajdziesz w przewodniku po tokenach).
  • Model nie rozróżnia tokenów w pamięci podręcznej od zwykłych tokenów wejściowych. Treści z pamięci podręcznej są umieszczane przed promptem.
  • Nie ma specjalnych limitów stawek ani limitów użycia w przypadku buforowania kontekstu. Obowiązują standardowe limity stawek dla GenerateContent, a limity tokenów obejmują tokeny w pamięci podręcznej.
  • Liczba tokenów w pamięci podręcznej jest zwracana w parametrze usage_metadata w operacjach tworzenia, pobierania i wyświetlania listy usługi pamięci podręcznej, a także w parametrze GenerateContent podczas korzystania z pamięci podręcznej.