Kontext-Cache verwenden

Sie können REST APIs oder das Python SDK verwenden, um in einer generativen KI-Anwendung auf Inhalte zu verweisen, die in einem Kontextcache gespeichert sind. Bevor Sie ihn verwenden können, müssen Sie zuerst den Kontext-Cache erstellen.

Das Kontextcache-Objekt, das Sie in Ihrem Code verwenden, enthält die folgenden Attribute:

  • name: Der Ressourcenname des Kontextcaches. Das Format ist projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID. Wenn Sie einen Kontext-Cache erstellen, finden Sie den zugehörigen Ressourcennamen in der Antwort. Die Projektnummer ist eine eindeutige Kennung für Ihr Projekt. Die Cache-ID ist eine ID für Ihren Cache. Wenn Sie in Ihrem Code einen Kontext-Cache angeben, müssen Sie den vollständigen Ressourcennamen des Kontext-Caches verwenden. Das folgende Beispiel zeigt, wie Sie den Namen einer Ressource für zwischengespeicherte Inhalte in einem Anfragetext angeben:

    "cached_content": "projects/123456789012/locations/us-central1/123456789012345678"
    
  • model: Der Ressourcenname für das Modell, mit dem der Cache erstellt wurde. Das Format ist projects/PROJECT_NUMBER/locations/LOCATION/publishers/PUBLISHER_NAME/models/MODEL_ID.

  • createTime: Ein Timestamp, der die Erstellungszeit des Kontext-Cache angibt.

  • updateTime: Ein Timestamp, der den Zeitpunkt der letzten Aktualisierung eines Kontext-Caches angibt. Nachdem ein Kontext-Cache erstellt wurde und bevor er aktualisiert wird, sind seine createTime und updateTime identisch.

  • expireTime: Eine Timestamp, die angibt, wann ein Kontext-Cache abläuft. Die Standardeinstellung für expireTime ist 60 Minuten nach dem createTime. Sie können den Cache mit einer neuen Ablaufzeit aktualisieren. Weitere Informationen finden Sie unter Kontextcache aktualisieren. Nachdem ein Cache abgelaufen ist, wird er zum Löschen markiert. Sie sollten nicht davon ausgehen, dass er verwendet oder aktualisiert werden kann. Wenn Sie einen abgelaufenen Kontext-Cache verwenden müssen, müssen Sie ihn mit einer entsprechenden Ablaufzeit neu erstellen.

Einschränkungen für die Verwendung des Kontext-Cache

Die folgenden Funktionen können beim Erstellen eines Kontext-Cache angegeben werden. Sie sollten sie in Ihrer Anfrage nicht noch einmal angeben:

  • Das Attribut GenerativeModel.system_instructions. Mit dieser Eigenschaft werden dem Modell Anweisungen gegeben, bevor es Anweisungen von einem Nutzer erhält. Weitere Informationen finden Sie unter Systemanweisungen.

  • Das Attribut GenerativeModel.tool_config. Mit der Property tool_config werden Tools angegeben, die vom Gemini-Modell verwendet werden, z. B. ein Tool, das vom Funktionsaufruf verwendet wird.

  • Das Attribut GenerativeModel.tools. Mit der GenerativeModel.tools-Property werden Funktionen zum Erstellen einer Anwendung für Funktionsaufrufe angegeben. Weitere Informationen finden Sie unter Funktionsaufrufe.

Beispiel für Kontext-Cache verwenden

Im Folgenden wird gezeigt, wie ein Kontext-Cache verwendet wird. Wenn Sie einen Kontext-Cache verwenden, können Sie die folgenden Eigenschaften nicht angeben:

  • GenerativeModel.system_instructions
  • GenerativeModel.tool_config
  • GenerativeModel.tools

Python

Installieren

pip install --upgrade google-genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen:

# 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

Informationen zum Installieren oder Aktualisieren von Go

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen:

# 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.0-flash-001",
		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

Sie können mit REST einen Kontext-Cache mit einem Prompt verwenden. Dazu senden Sie mit der Vertex AI API eine POST-Anfrage an den Endpunkt des Publisher-Modells.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage zum Erstellen des Kontext-Cache verarbeitet wurde.
  • MIME_TYPE: Der Text-Prompt, der an das Modell gesendet werden soll.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

{
  "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"
      }
  ],
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

Beispiel: cURL-Befehls

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"
    }
  ],
}'