Cache konteks

Dalam alur kerja AI standar, Anda dapat meneruskan token input yang sama berulang kali ke model. Dengan menggunakan fitur penyimpanan cache konteks Gemini API, Anda dapat meneruskan beberapa konten ke model sekali, meng-cache token input, lalu merujuk ke token yang di-cache untuk permintaan berikutnya. Pada volume tertentu, menggunakan token yang di-cache lebih murah daripada meneruskan korpus token yang sama berulang kali.

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 cache bergantung pada ukuran token input dan berapa lama Anda ingin token dipertahankan.

Penyimpanan dalam cache konteks mendukung Gemini 1.5 Pro dan Gemini 1.5 Flash.

Kapan harus menggunakan cache konteks

Cache konteks sangat cocok untuk skenario ketika 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 terhadap file video yang panjang
  • Kueri berulang pada kumpulan dokumen berukuran besar
  • Analisis repositori kode yang sering atau perbaikan bug

Bagaimana penyimpanan dalam cache dapat 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, yang ditagih dengan tarif lebih rendah saat disertakan dalam perintah berikutnya.
  2. Durasi penyimpanan: Jumlah waktu token yang di-cache disimpan (TTL), ditagih berdasarkan durasi TTL dari 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.

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 dan file video yang di-cache.

import { GoogleGenerativeAI } from '@google/generative-ai';
import {
  FileState,
  GoogleAICacheManager,
  GoogleAIFileManager,
} from '@google/generative-ai/server';

// A helper function that uploads the video to be cached.
async function uploadMp4Video(filePath, displayName) {
  const fileManager = new GoogleAIFileManager(process.env.API_KEY);
  const fileResult = await fileManager.uploadFile(filePath, {
    displayName,
    mimeType: 'video/mp4',
  });

  const { name, uri } = fileResult.file;

  // Poll getFile() on a set interval (2 seconds here) to check file state.
  let file = await fileManager.getFile(name);
  while (file.state === FileState.PROCESSING) {
    console.log('Waiting for video to be processed.');
    // Sleep for 2 seconds
    await new Promise((resolve) => setTimeout(resolve, 2_000));
    file = await fileManager.getFile(name);
  }

  console.log(`Video processing complete: ${uri}`);

  return fileResult;
}

// Download video file
// curl -O https://storage.googleapis.com/generativeai-downloads/data/Sherlock_Jr_FullMovie.mp4
const pathToVideoFile = 'Sherlock_Jr_FullMovie.mp4';

// Upload the video.
const fileResult = await uploadMp4Video(pathToVideoFile, 'Sherlock Jr. video');

// Construct a GoogleAICacheManager using your API key.
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);

// Create a cache with a 5 minute TTL.
const displayName = 'sherlock jr movie';
const model = 'models/gemini-1.5-flash-001';
const systemInstruction =
  'You are an expert video analyzer, and your job is to answer ' +
  "the user's query based on the video file you have access to.";
let ttlSeconds = 300;
const cache = await cacheManager.create({
  model,
  displayName,
  systemInstruction,
  contents: [
    {
      role: 'user',
      parts: [
        {
          fileData: {
            mimeType: fileResult.file.mimeType,
            fileUri: fileResult.file.uri,
          },
        },
      ],
    },
  ],
  ttlSeconds,
});

// Get your API key from https://aistudio.google.com/app/apikey
// Access your API key as an environment variable.
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Construct a `GenerativeModel` which uses the cache object.
const genModel = genAI.getGenerativeModelFromCachedContent(cache);

// Query the model.
const result = await genModel.generateContent({
  contents: [
    {
      role: 'user',
      parts: [
        {
          text:
            'Introduce different characters in the movie by describing ' +
            'their personality, looks, and names. Also list the ' +
            'timestamps they were introduced for the first time.',
        },
      ],
    },
  ],
});

console.log(result.response.usageMetadata);

// The output should look something like this:
//
// {
//   promptTokenCount: 696220,
//   candidatesTokenCount: 270,
//   totalTokenCount: 696490,
//   cachedContentTokenCount: 696191
// }

console.log(result.response.text());

Mencantumkan cache

Konten yang di-cache tidak dapat diambil atau dilihat, tetapi Anda dapat mengambil metadata cache (name, model, displayName, usageMetadata, createTime, updateTime, dan expireTime).

Guna mencantumkan metadata untuk semua cache yang diupload, gunakan GoogleAICacheManager.list():

const listResult = await cacheManager.list();
listResult.cachedContents.forEach((cache) => {
  console.log(cache);
});

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 GoogleAICacheManager.update().

const ttlSeconds = 2 * 60 * 60;
const updateParams = { cachedContent: { ttlSeconds } };
const updatedCache = await cacheManager.update(cacheName, updateParams);

Menghapus cache

Layanan penyimpanan dalam cache menyediakan operasi penghapusan untuk menghapus konten secara manual dari cache. Contoh berikut menunjukkan cara menghapus cache menggunakan GoogleAICacheManager.delete().

await cacheManager.delete(cacheName);

Pertimbangan tambahan

Perhatikan pertimbangan berikut saat menggunakan cache konteks:

  • Jumlah token input minimum untuk penyimpanan dalam cache konteks adalah 32.768, dan maksimum sama dengan jumlah maksimum untuk model yang diberikan. (Untuk informasi selengkapnya tentang penghitungan token, lihat Panduan token).
  • Model ini tidak membedakan antara token yang di-cache dan token input reguler. Konten yang di-cache hanyalah awalan untuk perintah.
  • Tidak ada batas penggunaan atau kapasitas khusus untuk penyimpanan dalam cache konteks; batas kapasitas standar untuk GenerateContent berlaku, dan batas token mencakup token yang di-cache.
  • Jumlah token yang di-cache ditampilkan dalam usage_metadata dari operasi pembuatan, perolehan, dan daftar layanan cache, dan juga di GenerateContent saat menggunakan cache.