コンテキストキャッシュを使用する

REST API または Python SDK を使用して、生成 AI アプリケーションのコンテキストキャッシュに保存されているコンテンツを参照できます。使用するには、まずコンテキストキャッシュを作成する必要があります。

コードで使用するコンテキストキャッシュオブジェクトには、次のプロパティが含まれます。

name - コンテキストキャッシュのリソース名。形式は　projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID　です。コンテキストキャッシュを作成すると、レスポンスにはそのリソース名が含まれます。プロジェクト番号はプロジェクトの固有識別子です。キャッシュ ID はキャッシュの ID です。コード内でコンテキストキャッシュを指定する場合、完全なコンテキストキャッシュリソース名を使用する必要があります。以下に示すのは、キャッシュに保存されたコンテンツのリソース名をリクエスト本文で指定する方法です。
```
"cached_content": "projects/123456789012/locations/us-central1/123456789012345678"
```
model - キャッシュの作成に使用されるモデルのリソース名。形式は　projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID　です。
createTime - コンテキストキャッシュの作成日時を指定する Timestamp。
updateTime - コンテキストキャッシュの最新更新時間を指定する Timestamp。コンテキストキャッシュが作成されてから更新されるまでの間、createTime と updateTime は同じです。
expireTime - コンテキストキャッシュの有効期限を指定する Timestamp。デフォルトの expireTime は createTime の 60 分後です。キャッシュに新しい有効期限を設定できます。詳細については、コンテキストキャッシュを更新するをご覧ください。
有効期限が切れたキャッシュは削除対象としてマークされます。そうしたキャッシュは使用または更新できません。期限切れのコンテキストキャッシュを使用する必要がある場合は、適切な有効期限を設定して再作成する必要があります。

コンテキストキャッシュの使用制限

コンテキストキャッシュの作成時に、次の機能を指定できます。リクエストで再度指定しないでください。

GenerativeModel.system_instructions プロパティ。このプロパティは、モデルがユーザーから指示を受け取る前に、モデルへの指示を指定するために使用されます。詳細については、システム指示をご覧ください。
GenerativeModel.tool_config プロパティ。tool_config プロパティは、関数呼び出し機能で使用されるツールなど、Gemini モデルで使用されるツールを指定するために使用されます。
GenerativeModel.tools プロパティ。GenerativeModel.tools プロパティは、関数呼び出しアプリケーションを作成する関数を指定するために使用されます。詳細については、関数呼び出しをご覧ください。

コンテキストキャッシュの使用例

コンテキストキャッシュを使用するには、以下の方法があります。コンテキストキャッシュを使用する場合は、これらのプロパティを指定できません。

GenerativeModel.system_instructions
GenerativeModel.tool_config
GenerativeModel.tools

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

from vertexai.preview.generative_models import GenerativeModel
from vertexai.preview import caching

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

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

cached_content = caching.CachedContent(cached_content_name=cache_id)

model = GenerativeModel.from_cached_content(cached_content=cached_content)

response = model.generate_content("What are the papers about?")

print(response.text)

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"
	"errors"
	"fmt"
	"io"

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

// useContextCache shows how to use an existing cached content, when prompting the model
// contentName is the ID of the cached content
func useContextCache(w io.Writer, contentName string, projectID, location, modelName string) error {
	// location := "us-central1"
	// modelName := "gemini-1.5-pro-001"
	ctx := context.Background()

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

	model := client.GenerativeModel(modelName)
	model.CachedContentName = contentName
	prompt := genai.Text("What are the papers about?")

	res, err := model.GenerateContent(ctx, prompt)
	if err != nil {
		return fmt.Errorf("error generating content: %w", err)
	}

	if len(res.Candidates) == 0 ||
		len(res.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	fmt.Fprintf(w, "generated response: %s\n", res.Candidates[0].Content.Parts[0])
	return nil
}

REST

REST を使用してプロンプトでコンテキストキャッシュを使用するには、Vertex AI API を使用してパブリッシャーモデルエンドポイントに POST リクエストを送信します。

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

PROJECT_ID: 実際のプロジェクト ID。
LOCATION: コンテキストキャッシュの作成のリクエストが処理されたリージョン。
MIME_TYPE: モデルに送信するテキストプロンプト。

HTTP メソッドと URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-1.5-pro-001:generateContent

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

{
  "cached_content": "projects/PROJECT_NUMBER/locations/LOCATION/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"
      }
  ],
}

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

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/publishers/google/models/gemini-1.5-pro-001:generateContent"

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/publishers/google/models/gemini-1.5-pro-001:generateContent" | Select-Object -Expand Content

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

レスポンス

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "MODEL_RESPONSE"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.21866937,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.19946389
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "MEDIUM",
          "probabilityScore": 0.6880493,
          "severity": "HARM_SEVERITY_MEDIUM",
          "severityScore": 0.43374163
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.4442634,
          "severity": "HARM_SEVERITY_LOW",
          "severityScore": 0.37903354
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.10502681,
          "severity": "HARM_SEVERITY_LOW",
          "severityScore": 0.28170192
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 55927,
    "candidatesTokenCount": 105,
    "totalTokenCount": 56032
  }
}

curl コマンドの例

LOCATION="us-central1"
MODEL_ID="gemini-1.5-pro-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 \
'{
  "cached_content": "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"
    }
  ],
}'

コンテキストキャッシュの有効期限を更新する方法を確認する。
新しいコンテキストキャッシュを作成する方法を確認する。
Google Cloud プロジェクトに関連付けられているすべてのコンテキストキャッシュに関する情報を取得する方法を確認する。
コンテキストキャッシュを削除する方法を確認する。

コンテキスト キャッシュを使用する

コンテキスト キャッシュの使用制限

コンテキスト キャッシュの使用例

Python

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

サンプルコード

Go

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

サンプルコード

REST

curl

PowerShell

レスポンス

curl コマンドの例

コンテキストキャッシュを使用する

コンテキストキャッシュの使用制限

コンテキストキャッシュの使用例

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

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