Buforowanie kontekstu

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:

  1. 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.
  2. 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.
  3. 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 w GenerateContent podczas korzystania z pamięci podręcznej.