Ta strona została przetłumaczona przez Cloud Translation API.

Buforowanie kontekstu

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

domyślne buforowanie (automatyczne, bez gwarancji oszczędności),
Wyraźne buforowanie (ręczne, z gwarancją oszczędności)

W modelach Gemini 2.5 domyślnie jest włączone domyślne buforowanie. Jeśli żądanie zawiera treści, które znajdują się w pamięci podręcznej, automatycznie przekażemy Ci oszczędności.

Wyraźne buforowanie jest przydatne w przypadkach, gdy chcesz zapewnić oszczędności, ale wymaga to dodatkowej pracy programisty.

Buforowanie pośrednie

Domyślnie domyślnie włączone jest domyślne buforowanie w przypadku wszystkich modeli Gemini 2.5. Jeśli Twoje żądanie trafi do pamięci podręcznej, automatycznie przekażemy Ci oszczędności. Nie musisz nic robić, aby włączyć tę funkcję. Zmiany te wejdą w życie 8 maja 2025 r. Minimalna liczba tokenów wejściowych do przechowywania w pamięci podręcznej kontekstu to 1024 w przypadku wersji 2.5 Flash i 2048 w przypadku wersji 2.5 Pro.

Aby zwiększyć szansę na znalezienie danych w pamięci podręcznej:

Spróbuj umieścić duże i częste treści na początku prompta.
Próbowanie wysyłania żądań z podobnym prefiksem w krótkim czasie

Liczba tokenów, które zostały znalezione w pamięci podręcznej, jest widoczna w polu usage_metadata obiektu odpowiedzi.

jawna pamięć podręczna.

Korzystając z funkcji jawnego buforowania w interfejsie Gemini API, możesz raz przekazać modelowi treści, zapisać w buforze 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.

W tej sekcji zakładamy, że masz zainstalowany pakiet Gemini SDK (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 utworzyć pamięć podręczną i wykorzystać ją do generowania treści.

FilmyPliki 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

Wyświetlanie pamięci podręcznej

Nie można pobierać ani wyświetlać treści z pamięci podręcznej, ale można pobrać metadane z pamięci podręcznej (name, model, displayName, usageMetadata, createTime, updateTime i expireTime).

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

Aktualizowanie pamięci podręcznej

Możesz ustawić nową wartość ttl lub expireTime dla pamięci podręcznej. Zmiana innych ustawień pamięci podręcznej nie jest obsługiwana.

Z poniższego przykładu dowiesz się, jak zaktualizować ttl pamięci podręcznej.

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

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. W tym przykładzie pokazano, jak usunąć pamięć podręczną.

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

Wyraźne 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ć pamięci podręcznej na potrzeby konkretnego adresu

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 przypadku:

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

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ą one uwzględnione 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.

Najnowsze informacje o cenach znajdziesz na tej stronie poświęconej Gemini API. Aby dowiedzieć się, jak zliczać tokeny, zapoznaj się z przewodnikiem dotyczącym tokenów.

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 1024 w przypadku wersji 2.5 Flash i 2048 w przypadku wersji 2.5 Pro. Maksymalna wartość jest taka sama jak maksymalna wartość 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 z pamięci podręcznej to 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.