Cache konteks

Dalam alur kerja AI standar, Anda dapat meneruskan token input yang sama berulang kali ke model. Gemini API menawarkan dua mekanisme penyimpanan dalam cache yang berbeda:

  • Cache implisit (otomatis, tidak ada jaminan penghematan biaya)
  • Cache eksplisit (manual, jaminan penghematan biaya)

Caching implisit diaktifkan pada model Gemini 2.5 secara default. Jika permintaan berisi konten yang merupakan hit cache, kami akan otomatis meneruskan penghematan biaya kembali kepada Anda.

Cache eksplisit berguna jika Anda ingin menjamin penghematan biaya, tetapi dengan beberapa pekerjaan developer tambahan.

Caching implisit

Caching implisit diaktifkan secara default untuk semua model Gemini 2.5. Kami secara otomatis meneruskan penghematan biaya jika permintaan Anda menggunakan cache. Anda tidak perlu melakukan tindakan apa pun untuk mengaktifkannya. Kebijakan ini berlaku mulai 8 Mei 2025. Jumlah token input minimum untuk penyimpanan dalam cache konteks adalah 1.024 untuk Flash 2.5 dan 2.048 untuk Pro 2.5.

Untuk meningkatkan peluang hit cache implisit:

  • Coba tempatkan konten besar dan umum di awal perintah Anda
  • Mencoba mengirim permintaan dengan awalan yang serupa dalam waktu singkat

Anda dapat melihat jumlah token yang merupakan hit cache di kolom usage_metadata objek respons.

Caching eksplisit

Dengan menggunakan fitur cache eksplisit Gemini API, Anda dapat meneruskan beberapa konten ke model satu kali, meng-cache token input, lalu merujuk ke token yang di-cache untuk permintaan berikutnya. Pada volume tertentu, penggunaan token yang di-cache lebih hemat biaya daripada meneruskan korpus token yang sama secara berulang.

Saat meng-cache kumpulan token, Anda dapat memilih berapa lama cache akan disimpan sebelum token dihapus secara otomatis. Durasi penyimpanan dalam cache ini disebut time to live (TTL). Jika tidak disetel, TTL akan ditetapkan secara default ke 1 jam. Biaya untuk penyimpanan dalam cache bergantung pada ukuran token input dan berapa lama Anda ingin token tetap ada.

Bagian ini mengasumsikan bahwa Anda telah menginstal Gemini SDK (atau telah menginstal curl) dan telah mengonfigurasi kunci API, seperti yang ditunjukkan dalam mulai cepat.

Membuat konten menggunakan cache

Contoh berikut menunjukkan cara membuat cache, lalu menggunakannya untuk membuat konten.

VideoPDF 
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

Mencantumkan cache

Anda tidak dapat mengambil atau melihat konten dalam cache, tetapi Anda dapat mengambil metadata cache (name, model, displayName, usageMetadata, createTime, updateTime, dan expireTime).

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

Mengupdate cache

Anda dapat menetapkan ttl atau expireTime baru untuk cache. Mengubah hal lain tentang cache tidak didukung.

Contoh berikut menunjukkan cara memperbarui ttl cache.

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

Menghapus cache

Layanan penyimpanan dalam cache menyediakan operasi penghapusan untuk menghapus konten secara manual dari cache. Contoh berikut menunjukkan cara menghapus cache.

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

Cache eksplisit menggunakan library OpenAI

Jika menggunakan library OpenAI, Anda dapat mengaktifkan caching eksplisit menggunakan properti cached_content di extra_body.

Kapan harus menggunakan cache eksplisit

Cache konteks sangat cocok untuk skenario saat konteks awal yang substansial dirujuk berulang kali oleh permintaan yang lebih singkat. Pertimbangkan untuk menggunakan cache konteks untuk kasus penggunaan seperti:

  • Chatbot dengan petunjuk sistem yang lengkap
  • Analisis berulang pada file video yang panjang
  • Kueri berulang terhadap set dokumen besar
  • Analisis repositori kode atau perbaikan bug yang sering dilakukan

Cara penyimpanan dalam cache eksplisit mengurangi biaya

Caching konteks adalah fitur berbayar yang dirancang untuk mengurangi biaya operasional secara keseluruhan. Penagihan didasarkan pada faktor-faktor berikut:

  1. Jumlah token cache: Jumlah token input yang di-cache, ditagih dengan tarif yang lebih rendah jika disertakan dalam perintah berikutnya.
  2. Durasi penyimpanan: Jumlah waktu token yang di-cache disimpan (TTL), ditagih berdasarkan durasi TTL jumlah token yang di-cache. Tidak ada batas minimum atau maksimum pada TTL.
  3. Faktor lainnya: Biaya lain berlaku, seperti untuk token input dan token output yang tidak di-cache.

Untuk mengetahui detail harga terbaru, lihat halaman harga Gemini API. Untuk mempelajari cara menghitung token, lihat Panduan token.

Pertimbangan tambahan

Perhatikan pertimbangan berikut saat menggunakan penyimpanan dalam cache konteks:

  • Jumlah token input minimum untuk penyimpanan dalam cache konteks adalah 1.024 untuk Flash 2.5 dan 2.048 untuk Pro 2.5. Maksimum sama dengan maksimum untuk model tertentu. (Untuk mengetahui informasi selengkapnya tentang cara menghitung token, lihat Panduan token).
  • Model ini tidak membedakan antara token yang di-cache dan token input reguler. Konten yang di-cache adalah awalan untuk perintah.
  • Tidak ada batas kapasitas atau penggunaan khusus pada penyimpanan dalam cache konteks; batas kapasitas standar untuk GenerateContent berlaku, dan batas token mencakup token yang disimpan dalam cache.
  • Jumlah token yang di-cache ditampilkan di usage_metadata dari operasi pembuatan, pengambilan, dan listingan layanan cache, dan juga di GenerateContent saat menggunakan cache.