取得背景資訊快取的相關資訊

您可以瞭解脈絡快取的建立時間、最近更新時間和到期時間。如要取得與 Google Cloud 專案相關聯的所有內容快取資訊 (包括快取 ID)，請使用指令列出內容快取。如果您知道內容快取的快取 ID，可以只取得該內容快取的相關資訊。

取得脈絡快取清單

如要取得與 Google Cloud 專案相關聯的內容快取清單，您需要建立專案的區域和 Google Cloud 專案 ID。以下說明如何取得 Google Cloud 專案的內容快取清單。

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# 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 HttpOptions

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

content_cache_list = client.caches.list()

# Access individual properties of a ContentCache object(s)
for content_cache in content_cache_list:
    print(f"Cache `{content_cache.name}` for model `{content_cache.model}`")
    print(f"Last updated at: {content_cache.update_time}")
    print(f"Expires at: {content_cache.expire_time}")

# Example response:
# * Cache `projects/111111111111/locations/us-central1/cachedContents/1111111111111111111` for
#       model `projects/111111111111/locations/us-central1/publishers/google/models/gemini-XXX-pro-XXX`
# * Last updated at: 2025-02-13 14:46:42.620490+00:00
# * CachedContentUsageMetadata(audio_duration_seconds=None, image_count=167, text_count=153, total_token_count=43130, video_duration_seconds=None)
# ...

Go

瞭解如何安裝或更新 Go。

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# 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"
	"net/http"
	"time"

	"google.golang.org/genai"
)

// listContentCache shows how to retrieve details about cached content.
func listContentCache(w io.Writer) 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)
	}

	// Retrieve cached content metadata
	cache, err := client.Caches.List(ctx, &genai.ListCachedContentsConfig{
		HTTPOptions: &genai.HTTPOptions{
			Headers:    http.Header{"X-Custom-Header": []string{"example"}},
			APIVersion: "v1",
		},
	})
	if err != nil {
		return fmt.Errorf("failed to get content cache: %w", err)
	}

	// Print basic info about the cached content
	fmt.Fprintf(w, "Cache name: %s\n", cache.Name)
	fmt.Fprintf(w, "Display name: %s\n", cache.Items[0].DisplayName)
	fmt.Fprintf(w, "Model: %s\n", cache.Items[0].Model)
	fmt.Fprintf(w, "Create time: %s\n", cache.Items[0].CreateTime.Format(time.RFC3339))
	fmt.Fprintf(w, "Update time: %s\n", cache.Items[0].UpdateTime.Format(time.RFC3339))
	fmt.Fprintf(w, "Expire time: %s (in %s)\n", cache.Items[0].ExpireTime.Format(time.RFC3339), time.Until(cache.Items[0].ExpireTime).Round(time.Second))

	if cache.Items[0].UsageMetadata != nil {
		fmt.Fprintf(w, "Usage metadata: %+v\n", cache.Items[0].UsageMetadata)
	}

	// Example response:
	// Cache name: projects/111111111111/locations/us-central1/cachedContents/1234567890123456789
	// Display name: product_recommendations_prompt
	// Model: models/gemini-2.5-flash
	// Create time: 2025-04-08T02:15:23Z
	// Update time: 2025-04-08T03:05:11Z
	// Expire time: 2025-04-20T03:05:11Z (in 167h59m59s)
	// Usage metadata: &{AudioDurationSeconds:0 ImageCount:167 TextCount:153 TotalTokenCount:43124 VideoDurationSeconds:0}

	return nil
}

Java

瞭解如何安裝或更新 Java。

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# 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 com.google.genai.Client;
import com.google.genai.types.CachedContent;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.ListCachedContentsConfig;

public class ContentCacheList {

  public static void main(String[] args) {
    contentCacheList();
  }

  // Lists all cached contents
  public static void contentCacheList() {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      for (CachedContent content : client.caches.list(ListCachedContentsConfig.builder().build())) {
        content.name().ifPresent(name -> System.out.println("Name: " + name));
        content.model().ifPresent(model -> System.out.println("Model: " + model));
        content.updateTime().ifPresent(time -> System.out.println("Last updated at: " + time));
        content.expireTime().ifPresent(time -> System.out.println("Expires at: " + time));
      }
      // Example response:
      // Name: projects/111111111111/locations/global/cachedContents/1111111111111111111
      // Model:
      // projects/111111111111/locations/global/publishers/google/models/gemini-2.5-flash
      // Last updated at: 2025-07-28T21:54:19.125825Z
      // Expires at: 2025-08-04T21:54:18.328233500Z
      // ...
    }
  }
}

Node.js

安裝

npm install @google/genai

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# 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

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';
async function listContentCaches(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
    httpOptions: {
      apiVersion: 'v1',
    },
  });

  const contentCacheList = await client.caches.list();

  // Access individual properties of a ContentCache object(s)
  const contentCacheNames = [];
  for (const contentCache of contentCacheList.pageInternal) {
    console.log(
      `Cache \`${contentCache.name}\` for model \`${contentCache.model}\``
    );
    console.log(`Last updated at: ${contentCache.updateTime}`);
    console.log(`Expires at: ${contentCache.expireTime}`);
    contentCacheNames.push(contentCache.name);
  }
  console.log(contentCacheNames);

  // Example response:
  //  * Cache `projects/111111111111/locations/us-central1/cachedContents/1111111111111111111` for
  //  model `projects/111111111111/locations/us-central1/publishers/google/models/gemini-XXX-pro-XXX`
  //  * Last updated at: 2025-02-13 14:46:42.620490+00:00
  //  * CachedContentUsageMetadata(audio_duration_seconds=None, image_count=167, text_count=153, total_token_count=43130, video_duration_seconds=None)
  // ...

  return contentCacheNames;
}

REST

以下說明如何使用 REST，將 GET 要求傳送至發布商模型端點，列出與 Google Cloud 專案相關聯的內容快取。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：您的專案 ID。
• LOCATION：處理建立脈絡快取要求的區域。

HTTP 方法和網址：

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

如要傳送要求，請選擇以下其中一個選項：

curl

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents" | Select-Object -Expand Content

您應該會收到類似以下的 JSON 回應：

回應

{
  "cachedContents": [
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID_1",
      "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.0-flash-001",
      "createTime": "2024-05-31T19:04:35.380412Z",
      "updateTime": "2024-05-31T19:04:35.380412Z",
      "expireTime": "2024-05-31T20:04:35.349680Z"
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID_2",
      "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.0-flash-001",
      "createTime": "2024-05-30T21:14:39.880235Z",
      "updateTime": "2024-05-31T00:21:15.350969Z",
      "expireTime": "2024-05-31T01:21:15.348014Z"
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID_N",
      "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.0-flash-001",
      "createTime": "2024-05-30T21:14:39.880235Z",
      "updateTime": "2024-05-31T00:21:15.350969Z",
      "expireTime": "2024-05-31T01:21:15.348014Z"
    }
  ]
}

cURL 指令範例

LOCATION="us-central1"
PROJECT_ID="PROJECT_ID"

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents

取得內容快取的相關資訊

如要取得單一內容快取資訊，您需要快取 ID、與內容快取相關聯的Google Cloud 專案 ID，以及處理建立內容快取要求的區域。建立脈絡快取時，系統會傳回脈絡快取的快取 ID。您也可以使用內容快取清單指令，取得與專案相關聯的每個內容快取 ID。

以下說明如何取得單一內容快取的相關資訊。

Go

在試用這個範例之前，請先按照 Vertex AI 快速入門導覽課程中的 Go 設定說明操作。詳情請參閱 Vertex AI Go 版 Gemini SDK 參考說明文件。

如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。 詳情請參閱「 為本機開發環境設定 ADC」。

串流和非串流回應

您可以選擇模型要生成串流回覆還是非串流回覆。如果是串流回覆，系統會在生成輸出權杖後立即傳送回覆。如果是非串流回覆，所有輸出權杖生成後，您就會收到所有回覆。

如要取得串流回應，請使用 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"

	"cloud.google.com/go/vertexai/genai"
)

// getContextCache shows how to retrieve the metadata of a cached content
// contentName is the ID of the cached content to retrieve
func getContextCache(w io.Writer, contentName string, projectID, location string) error {
	// location := "us-central1"
	ctx := context.Background()

	client, err := genai.NewClient(ctx, projectID, location)
	if err != nil {
		return fmt.Errorf("unable to create client: %w", err)
	}
	defer client.Close()

	cachedContent, err := client.GetCachedContent(ctx, contentName)
	if err != nil {
		return fmt.Errorf("GetCachedContent: %w", err)
	}
	fmt.Fprintf(w, "Retrieved cached content %q", cachedContent.Name)
	return nil
}

REST

以下說明如何使用 REST，將 GET 要求傳送至發布商模型端點，列出與 Google Cloud 專案相關聯的內容快取。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：。
• LOCATION：處理建立脈絡快取要求的區域。
• CACHE_ID：內容快取的 ID。建立脈絡快取時，系統會傳回脈絡快取 ID。您也可以列出 Google Cloud 專案的脈絡快取，找出脈絡快取 ID。詳情請參閱「建立脈絡快取」和「列出脈絡快取」。

HTTP 方法和網址：

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

如要傳送要求，請選擇以下其中一個選項：

curl

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID" | 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-2.0-flash-001",
  "createTime": "2024-05-31T19:04:35.380412Z",
  "updateTime": "2024-05-31T19:04:35.380412Z",
  "expireTime": "2024-05-31T20:04:35.349680Z"
}

cURL 指令範例

LOCATION="us-central1"
PROJECT_ID="PROJECT_ID"
CACHE_ID="CACHE_ID"

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/${CACHE_ID}

• 瞭解如何使用脈絡快取。
• 瞭解如何更新脈絡快取的到期時間。
• 瞭解如何刪除脈絡快取。