Menggunakan cache konteks

Panduan ini menunjukkan cara menggunakan cache konteks dalam aplikasi AI generatif dan mencakup topik berikut:

Anda dapat menggunakan REST API atau Python SDK untuk mereferensikan konten yang disimpan dalam cache konteks di aplikasi AI generatif. Sebelum dapat menggunakan context cache, Anda harus membuat context cache terlebih dahulu.

Properti cache konteks

Objek cache konteks yang Anda gunakan dalam kode Anda mencakup properti berikut:

  • name: Nama lengkap resource cache konteks. Anda harus menggunakan nama ini saat mereferensikan cache dalam permintaan. Nama ditampilkan dalam respons saat Anda membuat cache konteks.

    • Format: projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID

    • Contoh isi permintaan:

      "cached_content": "projects/123456789012/locations/us-central1/123456789012345678"

  • model: Nama resource model yang digunakan untuk membuat cache.

    • Format: projects/PROJECT_NUMBER/locations/LOCATION/publishers/PUBLISHER_NAME/models/MODEL_ID

  • createTime: Timestamp yang menentukan kapan context cache dibuat.

  • updateTime: Timestamp yang menentukan waktu update terbaru cache konteks. Sebelum cache diupdate, createTime dan updateTime-nya sama.

  • expireTime: Timestamp yang menentukan kapan cache konteks berakhir. Waktu habis masa berlaku default adalah 60 menit setelah createTime. Anda dapat memperbarui cache dengan waktu habis masa berlaku baru. Setelah masa berlaku cache berakhir, cache akan ditandai untuk dihapus dan tidak dapat digunakan atau diupdate. Untuk menggunakan cache yang sudah tidak berlaku, Anda harus membuatnya ulang.

Batasan penggunaan cache konteks

Saat membuat cache konteks, Anda dapat menentukan fitur berikut. Anda tidak boleh menentukan fitur ini lagi dalam permintaan berikutnya yang menggunakan cache:

  • GenerativeModel.system_instructions: Menentukan petunjuk yang akan digunakan model sebelum menerima petunjuk dari pengguna. Untuk mengetahui informasi selengkapnya, lihat Petunjuk sistem.

  • GenerativeModel.tool_config: Menentukan alat yang akan digunakan model Gemini, seperti alat untuk fitur panggilan fungsi. Untuk informasi selengkapnya, lihat referensi tool_config.

  • GenerativeModel.tools: Menentukan fungsi untuk membuat aplikasi panggilan fungsi. Untuk mengetahui informasi selengkapnya, lihat Panggilan fungsi.

Menggunakan contoh context cache

Contoh kode berikut menunjukkan cara menggunakan cache konteks dalam permintaan.

Python

Instal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Gen AI SDK dengan Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import GenerateContentConfig, HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))
# Use content cache to generate text response
# E.g cache_name = 'projects/111111111111/locations/us-central1/cachedContents/1111111111111111111'
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Summarize the pdfs",
    config=GenerateContentConfig(
        cached_content=cache_name,
    ),
)
print(response.text)
# Example response
#   The Gemini family of multimodal models from Google DeepMind demonstrates remarkable capabilities across various
#   modalities, including image, audio, video, and text....

Go

Pelajari cara menginstal atau mengupdate Go.

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Gen AI SDK dengan Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// useContentCacheWithTxt shows how to use content cache to generate text content.
func useContentCacheWithTxt(w io.Writer, cacheName string) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	resp, err := client.Models.GenerateContent(ctx,
		"gemini-2.5-flash",
		genai.Text("Summarize the pdfs"),
		&genai.GenerateContentConfig{
			CachedContent: cacheName,
		},
	)
	if err != nil {
		return fmt.Errorf("failed to use content cache to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The provided research paper introduces Gemini 1.5 Pro, a multimodal model capable of recalling
	// and reasoning over information from very long contexts (up to 10 million tokens).  Key findings include:
	//
	// * **Long Context Performance:**
	// ...

	return nil
}

REST

Anda dapat menggunakan REST untuk menggunakan cache konteks dengan perintah menggunakan Vertex AI API untuk mengirim permintaan POST ke endpoint model penayang.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda.
  • LOCATION: Region tempat permintaan untuk membuat cache konteks diproses.
  • MIME_TYPE: Perintah teks yang akan dikirimkan ke model.

Metode HTTP dan URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent

Isi JSON permintaan: 

{
  "cachedContent": "projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID",
  "contents": [
      {"role":"user","parts":[{"text":"PROMPT_TEXT"}]}
  ],
  "generationConfig": {
      "maxOutputTokens": 8192,
      "temperature": 1,
      "topP": 0.95,
  },
  "safetySettings": [
      {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      },
      {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      },
      {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      },
      {
          "category": "HARM_CATEGORY_HARASSMENT",
          "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      }
  ],
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent"

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent" | Select-Object -Expand Content

Anda akan melihat respons JSON yang mirip seperti berikut:

Contoh perintah curl

LOCATION="us-central1"
MODEL_ID="gemini-2.0-flash-001"
PROJECT_ID="test-project"

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent" -d \
'{
  "cachedContent": "projects/${PROJECT_NUMBER}/locations/${LOCATION}/cachedContents/${CACHE_ID}",
  "contents": [
      {"role":"user","parts":[{"text":"What are the benefits of exercise?"}]}
  ],
  "generationConfig": {
      "maxOutputTokens": 8192,
      "temperature": 1,
      "topP": 0.95,
  },
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HATE_SPEECH",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
      "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
      "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    }
  ],
}'