Buforowanie kontekstu

Python JavaScript Go REST

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);
• Jawne buforowanie (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 zostanie obsłużone z 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 jest podana w tabeli poniżej dla każdego modelu:

Aby zwiększyć szansę na 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 pobrane z 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 z 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 przy użyciu pamięci podręcznej

Poniższy przykład pokazuje, jak utworzyć pamięć podręczną, a następnie użyć jej do wygenerowania treści.

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 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, 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ć nowy ttl lub expireTime 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.

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. Poniższy przykład pokazuje, jak usunąć pamięć podręczną.

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

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 sytuacjach, w których obszerny kontekst początkowy jest wielokrotnie przywoływany przez krótsze żądania. Rozważ użycie buforowania kontekstu 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ą one uwzględniane w kolejnych promptach.
2. Czas przechowywania: czas przechowywania tokenów w pamięci podręcznej (TTL), rozliczany na podstawie czasu trwania TTL i 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 i wyjściowe, które nie są przechowywane w pamięci podręcznej.

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, 4096 w przypadku modelu 2.5 Pro i 2048 w przypadku modelu 3 Pro w wersji testowej. 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 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.