创建上下文缓存

您必须先创建上下文缓存，然后才能使用它。您创建的上下文缓存包含大量数据，您可以在向 Gemini 模型发出的多次请求中使用这些数据。缓存的内容会存储在您发出创建缓存请求的区域中。

缓存的内容可以是 Gemini 多模态模型支持的任何 MIME 类型。例如，您可以缓存大量文本、音频或视频。您可以指定多个要缓存的文件。如需了解详情，请参阅以下媒体要求：

您可以使用 Blob、文本或存储在 Cloud Storage 存储分区中的文件的路径指定要缓存的内容。如果要缓存的内容大小超过 10 MB，则必须使用存储在 Cloud Storage 存储桶中的文件的 URI 指定该内容。

缓存内容的有效期是有限的。上下文缓存的默认到期时间为其创建时间 60 分钟后。如果您希望使用其他到期时间，可以在创建上下文缓存时使用 ttl 或 expire_time 属性指定其他到期时间。您还可以更新尚未过期的上下文缓存的到期时间。如需了解如何指定 ttl 和 expire_time，请参阅更新过期时间。

上下文缓存过期后，将无法再使用。如果您想在未来的提示请求中引用已过期的上下文缓存中的内容，则需要重新创建上下文缓存。

限制

您缓存的内容必须遵守下表中显示的限制：

上下文缓存限制

缓存的大小下限

 32,769 个词元

您可以使用 Blob 或文本缓存的内容的大小上限

 10 MB

缓存创建后到过期所需的最短时间

 1 分钟

缓存创建后到过期前的最长时间

 没有缓存时长上限

位置信息支持

澳大利亚悉尼 (australia-southeast1) 地区不支持上下文缓存。

加密密钥支持

上下文缓存不支持客户管理的加密密钥 (CMEK)。

支持 Access Transparency

上下文缓存支持 Access Transparency。

创建上下文缓存示例

以下示例展示了如何创建上下文缓存。

Gen AI SDK for Python

安装

pip install --upgrade google-genai
 如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 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 Content, CreateCachedContentConfig, HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))

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 = [
    Content(
        role="user",
        parts=[
            Part.from_uri(
                file_uri="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf",
                mime_type="application/pdf",
            ),
            Part.from_uri(
                file_uri="gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf",
                mime_type="application/pdf",
            ),
        ],
    )
]

content_cache = client.caches.create(
    model="gemini-1.5-pro-002",
    config=CreateCachedContentConfig(
        contents=contents,
        system_instruction=system_instruction,
        display_name="example-cache",
        ttl="86400s",
    ),
)

print(content_cache.name)
print(content_cache.usage_metadata)
# Example response:
#   projects/111111111111/locations/us-central1/cachedContents/1111111111111111111
#   CachedContentUsageMetadata(audio_duration_seconds=None, image_count=167,
#       text_count=153, total_token_count=43130, video_duration_seconds=None)

REST

您可以使用 REST 创建上下文缓存，方法是使用 Vertex AI API 向发布方模型端点发送 POST 请求。以下示例展示了如何使用存储在 Cloud Storage 存储分区中的文件创建上下文缓存。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。
  • LOCATION：处理请求并存储缓存内容的区域。 如需查看支持的区域列表，请参阅可用区域。
  • CACHE_DISPLAY_NAME：一个有意义的显示名称，用于描述每个上下文缓存并帮助您识别它们。
  • MIME_TYPE：要缓存的内容的 MIME 类型。
  • CONTENT_TO_CACHE_URI：要缓存的内容的 Cloud Storage URI。

HTTP 方法和网址：

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

请求 JSON 正文： 

{
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-1.5-pro-002",
  "displayName": "CACHE_DISPLAY_NAME",
  "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

将请求正文保存在名为 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/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents"

PowerShell

将请求正文保存在名为 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/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

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

后续步骤