Bu sayfa, Cloud Translation API ile çevrilmiştir.

Bağlamı önbelleğe alma

Tipik bir yapay zeka iş akışında, bir modele aynı giriş jetonlarını tekrar tekrar iletebilirsiniz. Gemini API iki farklı önbelleğe alma mekanizması sunar:

Örtük önbelleğe alma (otomatik, maliyet tasarrufu garantisi yok)
Açık önbelleğe alma (manuel, maliyet tasarrufu garantisi)

Gizli önbelleğe alma, Gemini 2.5 modellerinde varsayılan olarak etkindir. Bir istek, önbelleğe isabet eden içerik içeriyorsa maliyet tasarrufunu otomatik olarak size geri veririz.

Açık önbelleğe alma, maliyet tasarrufu sağlamak istediğiniz ancak geliştirici çalışması gerektiren durumlarda kullanışlıdır.

Örtük önbelleğe alma

Örtük önbelleğe alma, tüm Gemini 2.5 modelleri için varsayılan olarak etkindir. İsteğiniz önbelleğe ulaşırsa maliyet tasarruflarını otomatik olarak iletiriz. Bunu etkinleştirmek için herhangi bir işlem yapmanız gerekmez. 8 Mayıs 2025'ten itibaren geçerlidir. Bağlam önbelleğe alma için minimum giriş jetonu sayısı 2.5 Flash için 1.024 ve 2.5 Pro için 2.048'dir.

Örtük önbellek isabeti olasılığını artırmak için:

İsteminizi büyük ve yaygın içeriklerle başlatmayı deneyin
Kısa süre içinde benzer ön eklerle istek göndermeye çalıştıysanız

Yanıt nesnesinin usage_metadata alanında, önbelleğe alınan isabetlerin jeton sayısını görebilirsiniz.

Açık önbelleğe alma

Gemini API'nin açık önbelleğe alma özelliğini kullanarak bazı içerikleri modele bir kez iletebilir, giriş jetonlarını önbelleğe alabilir ve ardından sonraki istekler için önbelleğe alınan jetonlara başvurabilirsiniz. Belirli hacimlerde, önbelleğe alınmış jetonları kullanmak aynı jeton grubunu tekrar tekrar iletmek yerine daha düşük maliyetlidir.

Bir jeton grubunu önbelleğe aldığınızda, jetonlar otomatik olarak silinmeden önce önbelleğin ne kadar süre boyunca var olmasını istediğinizi seçebilirsiniz. Bu önbelleğe alma süresine geçerlilik süresi (TTL) denir. Ayarlanmazsa TTL varsayılan olarak 1 saat olur. Önbelleğe alma maliyeti, giriş jetonu boyutuna ve jetonların ne kadar süreyle kalmasını istediğinize bağlıdır.

Bu bölümde, bir Gemini SDK'sı (veya curl) yüklediğiniz ve hızlı başlangıç bölümünde gösterildiği gibi bir API anahtarı yapılandırdığınız varsayılmaktadır.

Önbelleği kullanarak içerik oluşturma

Aşağıdaki örnekte, nasıl önbelleğe alınacağı ve ardından içerik oluşturmak için nasıl kullanılacağı gösterilmektedir.

VideolarPDF'ler

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

Önbellekleri listeleme

Önbelleğe alınmış içeriği almak veya görüntülemek mümkün değildir ancak önbelleğe alınmış meta verileri (name, model, displayName, usageMetadata, createTime, updateTime ve expireTime) alabilirsiniz.

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

Önbelleği güncelleme

Önbelleğe yeni bir ttl veya expireTime ayarlayabilirsiniz. Önbelleğe alma ile ilgili başka bir şeyin değiştirilmesi desteklenmez.

Aşağıdaki örnekte, bir önbelleğin ttl değerinin nasıl güncelleneceği gösterilmektedir.

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

Önbelleği silme

Önbelleğe alma hizmeti, içeriği önbellekten manuel olarak kaldırmak için bir silme işlemi sağlar. Aşağıdaki örnekte bir önbelleğin nasıl silineceği gösterilmektedir.

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

OpenAI kitaplığını kullanarak açık önbelleğe alma

OpenAI kitaplığı kullanıyorsanız extra_body üzerinde cached_content mülkünü kullanarak açık önbelleğe almayı etkinleştirebilirsiniz.

Belirli önbelleğe alma ne zaman kullanılır?

Bağlam önbelleğe alma, özellikle önemli bir başlangıç bağlamının daha kısa istekler tarafından tekrar tekrar referans verildiği senaryolara uygundur. Aşağıdaki gibi kullanım alanları için bağlama dayalı önbelleğe alma özelliğini kullanabilirsiniz:

Kapsamlı sistem talimatları içeren chatbot'lar
Uzun video dosyalarının tekrarlı analizi
Büyük doküman kümelerine yönelik yinelenen sorgular
Sık sık kod deposu analizi veya hata düzeltme

Açık önbelleğe alma maliyetleri nasıl azaltır?

Bağlam önbelleğe alma, genel operasyon maliyetlerini azaltmak için tasarlanmış ücretli bir özelliktir. Faturalandırma aşağıdaki faktörlere göre yapılır:

Önbelleğe alınan jeton sayısı: Sonraki istemlere dahil edildiğinde daha düşük bir oranda faturalandırılan, önbelleğe alınan giriş jetonlarının sayısı.
Depolama süresi: Önbelleğe alınan jetonların depolandığı süre (TTL). Önbelleğe alınan jeton sayısının TTL süresine göre faturalandırılır. TTL için minimum veya maksimum sınır yoktur.
Diğer faktörler: Önbelleğe alınmamış giriş jetonları ve çıkış jetonları gibi diğer ücretler geçerlidir.

Güncel fiyatlandırma ayrıntıları için Gemini API fiyatlandırma sayfasına bakın. Jetonları nasıl sayacağınızı öğrenmek için Jeton kılavuzuna göz atın.

Göz önünde bulundurulacak diğer noktalar

Bağlam önbelleğe alma özelliğini kullanırken aşağıdaki hususları göz önünde bulundurun:

Bağlam önbelleğe alma için minimum giriş jetonu sayısı 2.5 Flash için 1.024 ve 2.5 Pro için 2.048'dir. Maksimum, belirli modelin maksimum değeriyle aynıdır. (Jeton sayma hakkında daha fazla bilgi için Jeton rehberi başlıklı makaleyi inceleyin.)
Model, önbelleğe alınmış jetonlar ile normal giriş jetonları arasında herhangi bir ayrım yapmaz. Önbelleğe alınan içerik, istemin ön ekinde yer alır.
Bağlam önbelleğe alma işleminde özel bir ücret veya kullanım sınırı yoktur. GenerateContent için standart ücret sınırları geçerlidir ve jeton sınırları, önbelleğe alınmış jetonları içerir.
Önbelleğe alınan jetonların sayısı, önbelleğe alma hizmetinin oluşturma, alma ve listeleme işlemlerinden usage_metadata içinde ve önbelleğe alma işlemi sırasında GenerateContent içinde döndürülür.