Dalam alur kerja AI standar, Anda dapat meneruskan token input yang sama berulang kali ke model. Dengan menggunakan fitur cache konteks 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 berulang kali.
Saat menyimpan kumpulan token dalam cache, Anda dapat memilih berapa lama cache tersebut akan ada 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.
Penyimpanan dalam cache konteks bervariasi dari model ke model.
Kapan harus menggunakan cache konteks
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 menggunakan cache konteks
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 konten menggunakan petunjuk sistem yang di-cache dan file teks.
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const doc = await ai.files.upload({
file: "path/to/file.txt",
config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", doc.name);
const modelName = "gemini-2.0-flash-001";
const cache = await ai.caches.create({
model: modelName,
config: {
contents: createUserContent(createPartFromUri(doc.uri, doc.mimeType)),
systemInstruction: "You are an expert analyzing transcripts.",
},
});
console.log("Cache created:", cache);
const response = await ai.models.generateContent({
model: modelName,
contents: "Please summarize this transcript",
config: { cachedContent: cache.name },
});
console.log("Response text:", response.text);
}
await main();
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
).
Untuk mencantumkan metadata untuk semua cache yang diupload, gunakan GoogleGenAI.caches.list()
:
console.log("My caches:");
const pager = await ai.caches.list({ config: { pageSize: 10 } });
let page = pager.page;
while (true) {
for (const c of page) {
console.log(" ", c.name);
}
if (!pager.hasNextPage()) break;
page = await pager.nextPage();
}
Mengupdate cache
Anda dapat menetapkan ttl
atau expireTime
baru untuk cache. Mengubah hal lain
tentang cache tidak didukung.
Contoh berikut menunjukkan cara mengupdate ttl
cache menggunakan
GoogleGenAI.caches.update()
.
const ttl = `${2 * 3600}s`; // 2 hours in seconds
const updatedCache = await ai.caches.update({
name: cache.name,
config: { ttl },
});
console.log("After update (TTL):", updatedCache);
Menghapus cache
Layanan penyimpanan dalam cache menyediakan operasi penghapusan untuk menghapus konten secara manual
dari cache. Contoh berikut menunjukkan cara menghapus cache menggunakan
GoogleGenAI.caches.delete()
.
await ai.caches.delete({ name: cache.name });
Cara penyimpanan dalam cache mengurangi biaya
Caching konteks adalah fitur berbayar yang dirancang untuk mengurangi biaya operasional secara keseluruhan. Penagihan didasarkan pada faktor-faktor berikut:
- Jumlah token cache: Jumlah token input yang di-cache, ditagih dengan tarif yang lebih rendah jika disertakan dalam perintah berikutnya.
- 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.
- 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 4.096, dan maksimum sama dengan maksimum untuk model tertentu. (Untuk mengetahui informasi selengkapnya tentang 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 diGenerateContent
saat menggunakan cache.