更新上下文缓存

本指南介绍了如何更新上下文缓存的到期时间。默认情况下,上下文缓存会在创建 60 分钟后过期。过期的缓存会被删除,无法再使用或更新。如需延长未过期缓存的有效期,您可以设置相对时长 (ttl) 或具体时间戳 (expire_time) 来更新其到期时间。

下表比较了用于更新上下文缓存的这两个参数。

参数 说明 使用场景
ttl(存留时间) 设置相对过期时间。缓存会在自更新时间起经过指定时长后过期。 当您希望缓存在特定时长内可用时使用,例如“在未来 2 小时内保持活动状态”。
expire_time 设置绝对到期时间。无论何时进行更新,缓存都会在指定日期和时间失效。 当您需要缓存在精确的时间过期时使用,例如“此缓存必须在 6 月 30 日午夜之前删除”。

使用 ttl 参数更新上下文缓存

以下示例展示了如何将缓存的过期时间延长 3,600 秒。

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 datetime import datetime as dt from datetime import timezone as tz from datetime import timedelta  from google import genai from google.genai.types import HttpOptions, UpdateCachedContentConfig  client = genai.Client(http_options=HttpOptions(api_version="v1"))  # Get content cache by name # cache_name = "projects/111111111111/locations/us-central1/cachedContents/1111111111111111111" content_cache = client.caches.get(name=cache_name) print("Expire time", content_cache.expire_time) # Example response #   Expire time 2025-02-20 15:50:18.434482+00:00  # Update expire time using TTL content_cache = client.caches.update(     name=cache_name, config=UpdateCachedContentConfig(ttl="36000s") ) time_diff = content_cache.expire_time - dt.now(tz.utc) print("Expire time(after update):", content_cache.expire_time) print("Expire time(in seconds):", time_diff.seconds) # Example response #   Expire time(after update): 2025-02-14 01:51:42.571696+00:00 #   Expire time(in seconds): 35999  # Update expire time using specific time stamp next_week_utc = dt.now(tz.utc) + timedelta(days=7) content_cache = client.caches.update(     name=cache_name, config=UpdateCachedContentConfig(expireTime=next_week_utc) ) print("Expire time(after update):", content_cache.expire_time) # Example response #   Expire time(after update): 2025-02-20 15:51:42.614968+00:00

Go

了解如何安装或更新 Go

如需了解详情,请参阅 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

import ( 	"context" 	"fmt" 	"io" 	"time"  	genai "google.golang.org/genai" )  // updateContentCache shows how to update content cache expiration time. func updateContentCache(w io.Writer, cacheName string) error { 	ctx := context.Background()  	client, err := genai.NewClient(ctx, &genai.ClientConfig{ 		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"}, 	}) 	if err != nil { 		return fmt.Errorf("failed to create genai client: %w", err) 	}  	// Update expire time using TTL 	resp, err := client.Caches.Update(ctx, cacheName, &genai.UpdateCachedContentConfig{ 		TTL: time.Duration(time.Duration.Seconds(36000)), 	}) 	if err != nil { 		return fmt.Errorf("failed to update content cache exp. time with TTL: %w", err) 	}  	fmt.Fprintf(w, "Cache expires in: %s\n", time.Until(resp.ExpireTime)) 	// Example response: 	// Cache expires in: 10h0m0.005875s  	// Update expire time using specific time stamp 	inSevenDays := time.Now().Add(7 * 24 * time.Hour) 	resp, err = client.Caches.Update(ctx, cacheName, &genai.UpdateCachedContentConfig{ 		ExpireTime: inSevenDays, 	}) 	if err != nil { 		return fmt.Errorf("failed to update content cache expire time: %w", err) 	}  	fmt.Fprintf(w, "Cache expires in: %s\n", time.Until(resp.ExpireTime)) 	// Example response: 	// Cache expires in: 167h59m59.80327s  	return nil } 

REST

如需使用 REST API 更新上下文缓存,请向 Vertex AI API 发送 PATCH 请求。以下示例使用 ttl 参数更新了到期日期。

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

  • PROJECT_ID:您的项目 ID
  • LOCATION:处理该上下文缓存创建请求的区域。
  • CACHE_ID:相应上下文缓存的 ID。创建上下文缓存时,系统会返回上下文缓存 ID。您还可以通过列出 Google Cloud 项目的上下文缓存来查找上下文缓存 ID。如需了解详情,请参阅创建上下文缓存列出上下文缓存
  • SECONDS:一个 float,用于指定缓存过期前时长的秒组成部分。
  • NANOSECONDS:一个 float,用于指定缓存过期前持续时间的纳秒部分。

HTTP 方法和网址:

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

请求 JSON 正文:

 {   "seconds":"SECONDS",   "nanos":"NANOSECONDS" } 

如需发送请求,请选择以下方式之一:

curl

将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

curl -X PATCH \
-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/CACHE_ID"

PowerShell

将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID" | Select-Object -Expand Content

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

示例 curl 命令

PROJECT_ID="PROJECT_ID" LOCATION="us-central1" CACHE_ID="CACHE_ID"  curl \ -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json"\ "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}" -d \ '{    "ttl": {"seconds":"3600","nanos":"0"} }' 

使用 expire_time 参数更新上下文缓存

以下示例展示了如何使用 expire_time 参数将缓存的过期时间更新为 2024 年 6 月 30 日上午 9 点。

REST

如需使用 REST API 更新上下文缓存,请向 Vertex AI API 发送 PATCH 请求。以下示例使用 expire_time 参数更新了到期日期。

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

  • PROJECT_ID:。
  • LOCATION:处理该上下文缓存创建请求的区域。
  • CACHE_ID:相应上下文缓存的 ID。创建上下文缓存时,您可以在响应中找到此 ID。
  • EXPIRE_TIME:一个 Timestamp,用于指定上下文缓存的到期时间。

HTTP 方法和网址:

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

请求 JSON 正文:

 {    "expire_time":"EXPIRE_TIME" } 

如需发送请求,请选择以下方式之一:

curl

将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

curl -X PATCH \
-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/CACHE_ID"

PowerShell

将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID" | Select-Object -Expand Content

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

示例 curl 命令

PROJECT_ID="PROJECT_ID" LOCATION="us-central1" CACHE_ID="CACHE_ID"  curl \ -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json"\ "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}" -d \ '{    "expire_time":"2024-06-30T09:00:00.000000Z" }' 

后续步骤