使用上下文缓存

您可以使用 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/publishers/PUBLISHER_NAME/models/MODEL_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

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 GenerateContentConfig, HttpOptions

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

# 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-1.5-pro-002",
    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....

REST

您可以借助 REST 通过提示使用上下文缓存，方法是使用 Vertex AI API 向发布方模型端点发送 POST 请求。

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

HTTP 方法和网址：

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

请求 JSON 正文： 

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

如需发送请求，请选择以下方式之一：

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

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

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

示例 curl 命令

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