コンテキストキャッシュを作成する

コンテキストキャッシュは、使用する前に作成する必要があります。作成するコンテキストキャッシュには、Gemini モデルへの複数のリクエストで使用できる大量のデータが含まれています。キャッシュに保存されたコンテンツは、キャッシュの作成をリクエストしたリージョンに保存されます。

キャッシュには、Gemini マルチモーダルモデルでサポートされている任意の MIME タイプのコンテンツを保存できます。たとえば、大量のテキスト、音声、動画をキャッシュに保存できます。キャッシュに保存するファイルは複数指定できます。詳細は、次のメディア要件をご覧ください。

キャッシュに保存するコンテンツは、blob、テキスト、または Cloud Storage バケットに保存されているファイルのパスで指定します。キャッシュに保存するコンテンツのサイズが 10 MB を超える場合は、Cloud Storage バケットに保存されているファイルの URI を使用して指定する必要があります。

キャッシュに保存されたコンテンツの有効期間は有限です。コンテキストキャッシュのデフォルトの有効期限は、作成後 60 分です。異なる有効期限を希望する場合は、コンテキストキャッシュの作成時に ttl プロパティまたは expire_time プロパティを使用して、異なる有効期限を指定できます。有効期限が切れていないコンテキストキャッシュの有効期限を更新することもできます。ttl と expire_time を指定する方法については、有効期限を更新するをご覧ください。

コンテキストキャッシュは、有効期限が切れると使用できなくなります。今後のプロンプトリクエストで有効期限切れのコンテキストキャッシュ内のコンテンツを参照する場合は、コンテキストキャッシュを再作成する必要があります。

コンテキストキャッシュの上限

キャッシュに保存するコンテンツについては、次の上限を遵守する必要があります。

コンテキストキャッシュ保存の上限
キャッシュの最小サイズ	32,769 個のトークン
blob またはテキストを使用してキャッシュに保存できるコンテンツの最大サイズ	10 MB
キャッシュの作成後に有効期限切れになるまでの最小時間	1 分
キャッシュの作成後、キャッシュが有効期限切れになるまでの最大時間	キャッシュの最大保存期間はありません

コンテキストキャッシュの作成例

コンテキストキャッシュを作成するには、以下の方法があります。

Python

Vertex AI SDK for Python のインストールまたは更新方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Vertex AI SDK for Python API リファレンスドキュメントをご覧ください。

ストリーミングレスポンスと非ストリーミングレスポンス

モデルがストリーミングレスポンスを生成するのか、非ストリーミングレスポンスを生成するのかについては、選択が可能です。ストリーミングレスポンスの場合、出力トークンが生成されるとすぐに各レスポンスが返されます。非ストリーミングレスポンスの場合、すべての出力トークンが生成された後にすべてのレスポンスが返されます。

ストリーミングレスポンスの場合は、generate_content で stream パラメータを使用します。

  response = model.generate_content(contents=[...], stream = True)

非ストリーミングレスポンスの場合は、パラメータを削除するか、パラメータを False に設定します。

サンプルコード

import vertexai
import datetime

from vertexai.generative_models import Part
from vertexai.preview import caching

# TODO(developer): Update and un-comment below line
# project_id = "PROJECT_ID"

vertexai.init(project=project_id, location="us-central1")

system_instruction = """
You are an expert researcher. You always stick to the facts in the sources provided, and never make up new facts.
Now look at these research papers, and answer the following questions.
"""

contents = [
    Part.from_uri(
        "gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf",
        mime_type="application/pdf",
    ),
    Part.from_uri(
        "gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf",
        mime_type="application/pdf",
    ),
]

cached_content = caching.CachedContent.create(
    model_name="gemini-1.5-pro-001",
    system_instruction=system_instruction,
    contents=contents,
    ttl=datetime.timedelta(minutes=60),
)

print(cached_content.name)

Go

このサンプルを試す前に、Vertex AI クイックスタートの Go の設定手順を実施してください。詳細については、Vertex AI Go SDK for Gemini リファレンスドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

ストリーミングレスポンスと非ストリーミングレスポンス

ストリーミングレスポンスの場合は、GenerateContentStream メソッドを使用します。

  iter := model.GenerateContentStream(ctx, genai.Text("Tell me a story about a lumberjack and his giant ox. Keep it very short."))

非ストリーミングレスポンスの場合は、GenerateContent メソッドを使用します。

  resp, err := model.GenerateContent(ctx, genai.Text("What is the average size of a swallow?"))

サンプルコード

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/vertexai/genai"
)

// createContextCache shows how to create a cached content, and returns its name.
func createContextCache(w io.Writer, projectID, location, modelName string) (string, error) {
	// location := "us-central1"
	// modelName := "gemini-1.5-pro-001"
	ctx := context.Background()

	systemInstruction := `
    	You are an expert researcher. You always stick to the facts in the sources provided, and never make up new facts.
    	Now look at these research papers, and answer the following questions.
    `

	client, err := genai.NewClient(ctx, projectID, location)
	if err != nil {
		return "", fmt.Errorf("unable to create client: %w", err)
	}
	defer client.Close()

	// These PDF are viewable at
	//   https://storage.googleapis.com/cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf
	//   https://storage.googleapis.com/cloud-samples-data/generative-ai/pdf/2403.05530.pdf

	part1 := genai.FileData{
		MIMEType: "application/pdf",
		FileURI:  "gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf",
	}

	part2 := genai.FileData{
		MIMEType: "application/pdf",
		FileURI:  "gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf",
	}

	content := &genai.CachedContent{
		Model: modelName,
		SystemInstruction: &genai.Content{
			Parts: []genai.Part{genai.Text(systemInstruction)},
		},
		Expiration: genai.ExpireTimeOrTTL{TTL: 60 * time.Minute},
		Contents: []*genai.Content{
			{
				Role:  "user",
				Parts: []genai.Part{part1, part2},
			},
		},
	}

	result, err := client.CreateCachedContent(ctx, content)
	if err != nil {
		return "", fmt.Errorf("CreateCachedContent: %w", err)
	}
	fmt.Fprint(w, result.Name)
	return result.Name, nil
}

REST

REST を使用してコンテキストキャッシュを作成するには、Vertex AI API を使用してパブリッシャーモデルエンドポイントに POST リクエストを送信します。次の例は、Cloud Storage バケットに保存されているファイルを使用してコンテキストキャッシュを作成する方法を示しています。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 実際のプロジェクト ID。
LOCATION: リクエストを処理し、キャッシュに保存されたコンテンツが保存されるリージョン。サポートされているリージョンの一覧については、利用できるリージョンをご覧ください。
MIME_TYPE: キャッシュに保存するコンテンツの MIME タイプ。
CONTENT_TO_CACHE_URI: キャッシュに保存するコンテンツの Cloud Storage URI。

HTTP メソッドと URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/cachedContents

リクエストの本文（JSON）:

{
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-1.5-pro-001",
  "contents": [{
    "role": "user",
      "parts": [{
        "fileData": {
          "mimeType": "MIME_TYPE",
          "fileUri": "CONTENT_TO_CACHE_URI"
        }
      }]
  },
  {
    "role": "model",
      "parts": [{
        "text": "This is sample text to demonstrate explicit caching."
      }]
  }]
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/cachedContents"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/cachedContents" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

レスポンス

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID",
  "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.5-pro-001",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

curl コマンドの例

LOCATION="us-central1"
MODEL_ID="gemini-1.5-pro-001"
PROJECT_ID="test-project"
MIME_TYPE="video/mp4"
CACHED_CONTENT_URI="gs://path-to-bucket/video-file-name.mp4"

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}/cachedContents -d \
'{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ]
}'

次のステップ

コンテキストキャッシュを使用する方法を学習する。
コンテキストキャッシュの有効期限を更新する方法を学習する。

コンテキスト キャッシュを作成する

コンテキスト キャッシュの上限

コンテキスト キャッシュの作成例

Python

ストリーミング レスポンスと非ストリーミング レスポンス

サンプルコード

Go

ストリーミング レスポンスと非ストリーミング レスポンス

サンプルコード

REST

curl

PowerShell

レスポンス

curl コマンドの例

次のステップ

コンテキストキャッシュを作成する

コンテキストキャッシュの上限

コンテキストキャッシュの作成例

ストリーミングレスポンスと非ストリーミングレスポンス

ストリーミングレスポンスと非ストリーミングレスポンス