创建上下文缓存

您必须先创建上下文缓存，然后才能使用它。您创建的上下文缓存包含大量数据，您可以在对 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

如需了解如何安装或更新 Python 版 Vertex AI SDK，请参阅安装 Python 版 Vertex AI SDK。如需了解详情，请参阅 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 = "your-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-002",
    system_instruction=system_instruction,
    contents=contents,
    ttl=datetime.timedelta(minutes=60),
    display_name="example-cache",
)

print(cached_content.name)
# Example response:
# 1234567890

Go

在尝试此示例之前，请按照《Vertex AI 快速入门》中的 Go 设置说明执行操作。如需了解详情，请参阅适用于 Gemini 的 Vertex AI Go SDK 参考文档。

如需向 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 方法和网址：

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

后续步骤

了解如何使用上下文缓存。
了解如何更新上下文缓存的过期时间。