您可以使用 REST API 或 Python SDK 在生成式 AI 应用中引用存储在上下文缓存中的内容。您必须先创建上下文缓存,然后才能使用上下文缓存。 您在代码中使用的上下文缓存对象包含以下属性: 请求正文示例: 创建上下文缓存时,您可以指定以下功能。在后续使用缓存的请求中,您不应再次指定这些功能: 以下代码示例演示了如何在请求中使用上下文缓存。
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用:
了解如何安装或更新 Go。
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用:
您可以借助 REST 通过提示使用上下文缓存,方法是使用 Vertex AI API 向发布方模型端点发送 POST 请求。 在使用任何请求数据之前,请先进行以下替换: HTTP 方法和网址: 请求 JSON 正文:
如需发送请求,请选择以下方式之一:
将请求正文保存在名为
将请求正文保存在名为 您应该收到类似以下内容的 JSON 响应。
上下文缓存属性
name
:上下文缓存的完整资源名称。在请求中引用缓存时,必须使用此名称。创建上下文缓存时,系统会在响应中返回该名称。
projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_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
,用于指定上下文缓存的过期时间。默认过期时间为 createTime
后的 60 分钟。您可以使用新的到期时间更新缓存。缓存过期后,系统会将其标记为待删除,并且无法使用或更新该缓存。如需使用已过期的缓存,您必须重新创建该缓存。上下文缓存使用限制
GenerativeModel.system_instructions
:指定模型在收到用户指令之前要使用的指令。如需了解详情,请参阅系统指令。GenerativeModel.tool_config
:指定 Gemini 模型要使用的工具,例如函数调用功能使用的工具。如需了解详情,请参阅 tool_config
参考文档。GenerativeModel.tools
:指定用于创建函数调用应用的函数。如需了解详情,请参阅函数调用。使用上下文缓存示例
Python
安装
pip install --upgrade google-genai
# 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
Go
# 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
REST
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent
{
"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-2.0-flash-001: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-2.0-flash-001:generateContent" | Select-Object -Expand Content示例 curl 命令
LOCATION="us-central1"
MODEL_ID="gemini-2.0-flash-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 \
'{
"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"
}
],
}'
使用上下文缓存
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-19。