W typowym procesie sztucznej inteligencji możesz wielokrotnie przekazywać te same tokeny wejściowe do modelu. Korzystając z funkcji buforowania kontekstu w interfejsie Gemini API, możesz przekazać modelowi pewną treść, zapisać w pamięci podręcznej tokeny wejściowe, a następnie odwoływać się do tych tokenów w kolejnych żądaniach. Przy pewnych wolumenach korzystanie z tokenów w pamięci podręcznej jest tańsze niż wielokrotne przekazywanie tego samego zbioru tokenów.
Gdy przechowujesz w pamięci podręcznej zestaw tokenów, możesz określić, jak długo ma ona istnieć, zanim tokeny zostaną automatycznie usunięte. Czas przechowywania w pamięci podręcznej nazywany jest czasem życia danych (TTL). Jeśli nie określisz tego ustawienia, domyślnie są to 24 godziny. Koszt buforowania zależy od rozmiaru tokena wejściowego i czasu, przez jaki mają być przechowywane tokeny.
Buforowanie kontekstu obsługuje modele Gemini 1.5 Pro i Gemini 1.5 Flash.
Kiedy używać buforowania kontekstu
Buforowanie kontekstu jest szczególnie przydatne w sytuacjach, gdy obszerny początkowy kontekst jest wielokrotnie odwoływany przez krótsze żądania. Zastanów się nad użyciem buforowania kontekstu w takich przypadkach:
- Czatboty z obszernymi instrukcjami systemowymi
- powtarzająca się analiza długich plików wideo;
- powtarzające się zapytania dotyczące dużych zbiorów dokumentów;
- częsta analiza repozytorium kodu lub poprawianie błędów;
Jak 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:
- Liczba tokenów w pamięci podręcznej:liczba tokenów wejściowych przechowywanych w pamięci podręcznej, za które pobierana jest opłata po obniżonej stawce, gdy są uwzględniane w kolejnych promptach.
- Czas przechowywania: czas przechowywania tokenów w pamięci podręcznej (TTL), naliczany na podstawie czasu życia tokenów w pamięci podręcznej. Nie ma minimalnych ani maksymalnych wartości TTL.
- Inne czynniki: obowiązują inne opłaty, np. za tokeny wejściowe i wyjściowe, które nie są przechowywane w pamięci podręcznej.
Aktualne informacje o cenach znajdziesz na tej stronie dotyczącej Gemini API. Aby dowiedzieć się, jak zliczać tokeny, zapoznaj się z przewodnikiem dotyczącym tokenów.
Jak korzystać z buforowania kontekstu
W tej sekcji zakładamy, że masz zainstalowany pakiet SDK Gemini (lub masz zainstalowany curl) oraz skonfigurowany klucz API zgodnie z instrukcjami w artykule Szybki start.
Generowanie treści z wykorzystaniem pamięci podręcznej
Ten przykład pokazuje, jak generować treści za pomocą instrukcji i pliku wideo z pamięci podręcznej.
import os
import pathlib
import requests
import time
from google import genai
from google.genai import types
# Get your API key from https://aistudio.google.com/app/apikey
# Put it in a "GOOGLE_API_KEY" environment variable.
# For more details, see
# https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb
client = genai.Client()
# Download video file
url = 'https://storage.googleapis.com/generativeai-downloads/data/Sherlock_Jr_FullMovie.mp4'
path_to_video_file = pathlib.Path('Sherlock_Jr_FullMovie.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(path=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-1.5-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)
Wyświetlanie pamięci podręcznej
Nie można pobrać ani wyświetlić treści z pamięci podręcznej, ale można pobrać metadane z 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 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ć nową wartość ttl
lub expire_time
dla pamięci podręcznej. Zmiana innych ustawień pamięci podręcznej nie jest obsługiwana.
Ten przykład pokazuje, jak za pomocą funkcji client.caches.update()
zaktualizować ttl
pamięci podręcznej.
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ć obiekt datetime
lub ciąg znaków daty i godziny w formacie ISO (dt.isoformat()
, np. 2025-01-27T16:02:36.473528+00:00
). Czas musi zawierać 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. Ten przykład pokazuje, jak usunąć pamięć podręczną:
client.caches.delete(cache.name)
Uwagi dodatkowe
Podczas korzystania z buforowania kontekstu pamiętaj o tych kwestiach:
- Minimalna liczba tokenów wejściowych do przechowywania w pamięci podręcznej w kontekście to 32 768, a maksymalna jest taka sama jak maksymalna liczba tokenów dla danego modelu. (więcej informacji o liczeniu tokenów znajdziesz w tym przewodniku).
- Model nie rozróżnia tokenów z pamięci podręcznej i zwykłych tokenów wejściowych. Treści w pamięci podręcznej to po prostu prefiks promptu.
- Nie ma żadnych specjalnych limitów szybkości ani limitów użycia w przypadku buforowania kontekstu. Obowiązują standardowe limity szybkości dla
GenerateContent
, a limity tokenów obejmują tokeny buforowane. - Liczba tokenów w pamięci podręcznej jest zwracana w
usage_metadata
z operacji tworzenia, pobierania i wyświetlania listy w usłudze pamięci podręcznej, a także wGenerateContent
podczas korzystania z pamięci podręcznej.