Lưu vào bộ nhớ đệm theo bối cảnh trong Firebase AI Logic

Đối với tính năng AI, bạn có thể truyền cùng một mã thông báo đầu vào (nội dung) nhiều lần đến một mô hình. Đối với những trường hợp sử dụng này, bạn có thể lưu vào bộ nhớ đệm nội dung này. Tức là bạn truyền nội dung đến mô hình một lần, lưu trữ nội dung đó và tham chiếu nội dung đó trong các yêu cầu tiếp theo.

Tính năng lưu vào bộ nhớ đệm theo bối cảnh có thể giảm đáng kể độ trễ và chi phí cho các tác vụ lặp đi lặp lại liên quan đến lượng lớn nội dung, chẳng hạn như lượng lớn văn bản, tệp âm thanh hoặc tệp video. Một số trường hợp sử dụng phổ biến cho nội dung được lưu vào bộ nhớ đệm bao gồm tài liệu chi tiết về cá tính, cơ sở mã hoặc sổ tay.

Các mô hình Gemini cung cấp 2 cơ chế lưu vào bộ nhớ đệm:

Việc lưu vào bộ nhớ đệm rõ ràng sẽ hữu ích trong trường hợp bạn muốn đảm bảo tiết kiệm chi phí hơn, nhưng cần thêm một số công việc cho nhà phát triển.

Đối với cả hoạt động lưu vào bộ nhớ đệm ngầm và lưu vào bộ nhớ đệm rõ ràng, trường cachedContentTokenCount trong siêu dữ liệu của phản hồi cho biết số lượng token trong phần được lưu vào bộ nhớ đệm của thông tin đầu vào. Đối với tính năng lưu vào bộ nhớ đệm rõ ràng, hãy nhớ xem thông tin định giá ở cuối trang này.

Các mô hình được hỗ trợ

Tính năng lưu vào bộ nhớ đệm được hỗ trợ khi bạn sử dụng các mô hình sau:

  • gemini-3.1-pro-preview
  • gemini-3-flash-preview
  • gemini-3.1-flash-lite-preview
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite

Các mô hình tạo nội dung nghe nhìn (ví dụ: các mô hình Nana Banana như gemini-3.1-flash-image-preview) không hỗ trợ tính năng lưu vào bộ nhớ đệm theo ngữ cảnh.

Giới hạn kích thước nội dung trong bộ nhớ đệm

Mỗi mô hình đều có yêu cầu về số lượng mã thông báo tối thiểu đối với nội dung được lưu vào bộ nhớ đệm. Giới hạn tối đa được quy định bởi cửa sổ ngữ cảnh của mô hình.

  • Gemini Mô hình Pro: Tối thiểu 4096 mã thông báo
  • Gemini Mô hình Flash: tối thiểu 1024 mã thông báo

Ngoài ra, kích thước tối đa của nội dung mà bạn có thể lưu vào bộ nhớ đệm bằng một đối tượng lớn nhị phân (blob) hoặc văn bản là 10 MB.


Lưu vào bộ nhớ đệm ngầm

Tính năng lưu vào bộ nhớ đệm ngầm định được bật theo mặc định và có sẵn cho hầu hết các mô hình Gemini.

Google tự động chuyển khoản tiết kiệm chi phí nếu yêu cầu của bạn truy cập vào nội dung được lưu vào bộ nhớ đệm. Sau đây là một số cách để tăng khả năng yêu cầu của bạn sử dụng tính năng lưu vào bộ nhớ đệm ngầm:

  • Hãy thử đặt nội dung lớn và phổ biến vào đầu câu lệnh.
  • Hãy thử gửi các yêu cầu có tiền tố tương tự trong một khoảng thời gian ngắn.

Số lượng mã thông báo trong phần được lưu vào bộ nhớ đệm của dữ liệu đầu vào được cung cấp trong trường cachedContentTokenCount trong siêu dữ liệu của một phản hồi.


Lưu vào bộ nhớ đệm một cách rõ ràng

Tính năng lưu vào bộ nhớ đệm rõ ràng không được bật theo mặc định và đây là một chức năng không bắt buộc của các mô hình Gemini.

Sau đây là cách bạn có thể thiết lập và sử dụng bộ nhớ đệm nội dung phản cảm:

Xin lưu ý rằng bộ nhớ đệm nội dung rõ ràng tương tác với bộ nhớ đệm ngầm ẩn, có thể dẫn đến việc lưu vào bộ nhớ đệm ngoài nội dung rõ ràng được lưu vào bộ nhớ đệm. Bạn có thể ngăn việc lưu giữ dữ liệu trong bộ nhớ đệm bằng cách tắt tính năng lưu vào bộ nhớ đệm ngầm ẩn và không tạo bộ nhớ đệm rõ ràng. Để biết thêm thông tin, hãy xem phần Bật và tắt tính năng lưu vào bộ nhớ đệm.


Tạo và sử dụng bộ nhớ đệm rõ ràng

Để tạo và sử dụng bộ nhớ đệm nội dung rõ ràng, bạn cần phải có những điều kiện sau:

  1. Tạo bộ nhớ đệm rõ ràng.

  2. Tham chiếu bộ nhớ đệm trong mẫu câu lệnh của máy chủ.

  3. Tham chiếu mẫu câu lệnh của máy chủ trong một yêu cầu câu lệnh từ ứng dụng của bạn.

Thông tin quan trọng về việc tạo và sử dụng bộ nhớ đệm rõ ràng

Bộ nhớ đệm phải phù hợp với các yêu cầu về câu lệnh của ứng dụng và mẫu câu lệnh của máy chủ:

  • Bộ nhớ đệm dành riêng cho một nhà cung cấp Gemini API. Yêu cầu về lời nhắc của ứng dụng phải sử dụng cùng một nhà cung cấp.
    Đối với Firebase AI Logic, bạn chỉ nên sử dụng bộ nhớ đệm nội dung tường minh với Vertex AI Gemini API    . Tất cả thông tin và ví dụ trên trang này đều dành riêng cho nhà cung cấp Gemini API đó.

  • Bộ nhớ đệm này dành riêng cho một mô hình Gemini. Yêu cầu câu lệnh của ứng dụng phải sử dụng cùng một mô hình.

  • Bộ nhớ đệm dành riêng cho một vị trí khi sử dụng Vertex AI Gemini API.
    Vị trí của bộ nhớ đệm rõ ràng phải khớp với vị trí của mẫu lời nhắc trên máy chủ và vị trí mà bạn truy cập vào mô hình trong yêu cầu lời nhắc của ứng dụng.

Ngoài ra, hãy lưu ý các yêu cầu và giới hạn sau đây đối với tính năng lưu vào bộ nhớ đệm tường minh:

  • Sau khi tạo bộ nhớ đệm rõ ràng, bạn không thể thay đổi bất cứ điều gì về bộ nhớ đệm, ngoại trừ TTL hoặc thời gian hết hạn.

  • Bạn có thể lưu vào bộ nhớ đệm mọi loại MIME của tệp đầu vào được hỗ trợ hoặc thậm chí chỉ văn bản được cung cấp trong yêu cầu tạo bộ nhớ đệm.

  • Nếu muốn đưa một tệp vào bộ nhớ đệm, bạn phải cung cấp tệp đó dưới dạng URI Cloud Storage. Đó không được là URL của trình duyệt hoặc URL của YouTube.

    Ngoài ra, các hạn chế về quyền truy cập vào tệp sẽ được kiểm tra tại cache-creation-time và các hạn chế về quyền truy cập sẽ không được kiểm tra lại tại user-request-time. Vì lý do này, hãy đảm bảo rằng mọi dữ liệu có trong bộ nhớ đệm rõ ràng đều phù hợp với mọi người dùng đưa ra yêu cầu có chứa bộ nhớ đệm đó.

  • Nếu bạn muốn sử dụng các chỉ dẫn hoặc công cụ hệ thống (như thực thi mã, ngữ cảnh URL hoặc liên kết thực tế với Google Tìm kiếm), thì bản thân bộ nhớ đệm phải chứa các cấu hình của chúng. Bạn không thể định cấu hình các tham số này trong mẫu lời nhắc của máy chủ hoặc trong yêu cầu lời nhắc của ứng dụng. Xin lưu ý rằng mẫu câu lệnh trên máy chủ chưa hỗ trợ lệnh gọi hàm (hoặc trò chuyện). Để biết thông tin chi tiết về cách định cấu hình các chỉ dẫn và công cụ hệ thống trong bộ nhớ đệm, hãy xem API REST của Vertex AI Gemini API.

Bước 1: Tạo bộ nhớ đệm

Tạo bộ nhớ đệm bằng cách trực tiếp sử dụng API REST của Vertex AI Gemini API.

Sau đây là ví dụ về việc tạo bộ nhớ đệm rõ ràng của một tệp PDF làm nội dung.

Cú pháp:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3-flash-preview
LOCATION="LOCATION"  # location for both the cache and the model
MIME_TYPE="MIME_TYPE"
CACHED_CONTENT_URI="CLOUD_STORAGE_FILE_URI"  # must be a Cloud Storage URI
CACHE_DISPLAY_NAME="CACHE_DISPLAY_NAME"  # optional
TTL="CACHE_TIME_TO_LIVE"  # optional (if not specified, defaults to 3600s)

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Yêu cầu minh hoạ:

PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3-flash-preview"
LOCATION="global"
MIME_TYPE="application/pdf"
CACHED_CONTENT_URI="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
CACHE_DISPLAY_NAME="Gemini - A Family of Highly Capable Multimodal Model (PDF)"
TTL="7200s"

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Ví dụ về câu trả lời:

Phản hồi này bao gồm một tài nguyên đủ điều kiện name, có tính duy nhất trên toàn cầu đối với bộ nhớ đệm (lưu ý rằng phân đoạn cuối cùng là mã nhận dạng bộ nhớ đệm). Bạn sẽ sử dụng toàn bộ giá trị name này trong bước tiếp theo của quy trình.

{
  "name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
  "model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3-flash-preview",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

Bước 2: Tham chiếu bộ nhớ đệm trong mẫu câu lệnh của máy chủ

Sau khi tạo bộ nhớ đệm, hãy tham chiếu bộ nhớ đệm đó bằng name trong thuộc tính cachedContent của mẫu lời nhắc của máy chủ.

Đảm bảo bạn tuân thủ các yêu cầu sau khi tạo mẫu câu lệnh trên máy chủ:

  • Sử dụng tài nguyên đủ điều kiện name từ phản hồi khi bạn tạo bộ nhớ đệm. Đây không phải là tên hiển thị không bắt buộc mà bạn đã chỉ định trong yêu cầu.

  • Vị trí của mẫu lời nhắc trên máy chủ phải khớp với vị trí của bộ nhớ đệm.

  • Để sử dụng các chỉ dẫn hoặc công cụ hệ thống, bạn phải định cấu hình chúng như một phần của bộ nhớ đệm và không phải là một phần của mẫu câu lệnh máy chủ.

Cú pháp:

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

{{role "user"}}
{{userPrompt}}

Ví dụ:

{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}

{{role "user"}}
{{userPrompt}}

Ngoài ra, giá trị của tham số name trong mẫu câu lệnh của máy chủ có thể là một biến đầu vào động. Ví dụ: {{cachedContent name=someVariable}} cho phép bạn đưa name của bộ nhớ đệm làm thông tin đầu vào cho yêu cầu từ ứng dụng của bạn.

Bước 3: Tham chiếu mẫu câu lệnh của máy chủ trong yêu cầu từ ứng dụng của bạn

Hãy thật cẩn thận về những điều sau đây khi viết yêu cầu:

  • Sử dụng Vertex AI Gemini API vì bộ nhớ đệm được tạo bằng trình cung cấp Gemini API đó.

  • Vị trí mà bạn truy cập vào mô hình trong yêu cầu về câu lệnh của ứng dụng phải khớp với vị trí của mẫu câu lệnh máy chủ và bộ nhớ đệm.

Swift 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
let model = FirebaseAI.firebaseAI(backend: .vertexAI(location: "LOCATION"))
                                  .templateGenerativeModel()

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "TEMPLATE_ID"
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
val model = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "LOCATION"))
                        .templateGenerativeModel()

val response = model.generateContent(
    // Specify your template ID
    "TEMPLATE_ID",
)

val text = response.text
println(text)

Java 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

Future<GenerateContentResponse> response = model.generateContent(
    // Specify your template ID
    "TEMPLATE_ID"
);
addCallback(response,
      new FutureCallback<GenerateContentResponse>() {
          public void onSuccess(GenerateContentResponse result) {
            System.out.println(result.getText());
          }
          public void onFailure(Throwable t) {
            reportError(t);
          }
    }
executor);

Web 

// ...

// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
const ai = getAI(app, { backend: new VertexAIBackend('LOCATION') });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const result = await model.generateContent(
  // Specify your template ID
  'TEMPLATE_ID'
);

const response = result.response;
const text = response.text();

Dart 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
var _model = FirebaseAI.vertexAI(location: 'LOCATION').templateGenerativeModel()

var response = await _model.generateContent(
        // Specify your template ID
        'TEMPLATE_ID',
      );

var text = response?.text;
print(text);

Unity 

// ...

// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "LOCATION"));

// Create a `TemplateGenerativeModel` instance
var model = firebaseAI.GetTemplateGenerativeModel();

try
{
  var response = await model.GenerateContentAsync(
      // Specify your template ID
      "TEMPLATE_ID"
  );
  Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}


Quản lý bộ nhớ đệm rõ ràng

Phần này mô tả cách quản lý bộ nhớ đệm nội dung phản cảm, bao gồm cả cách liệt kê tất cả bộ nhớ đệm, lấy siêu dữ liệu về bộ nhớ đệm, cập nhật TTL hoặc thời gian hết hạn của bộ nhớ đệm và xoá bộ nhớ đệm.

Bạn quản lý bộ nhớ đệm rõ ràng bằng API REST của Vertex AI Gemini API.

Sau khi tạo bộ nhớ đệm nội dung rõ ràng, bạn không thể thay đổi bất kỳ thông tin nào về bộ nhớ đệm, ngoại trừ TTL hoặc thời gian hết hạn.

Liệt kê tất cả các bộ nhớ đệm

Bạn có thể liệt kê tất cả các bộ nhớ đệm rõ ràng có sẵn cho dự án của mình. Lệnh này sẽ chỉ trả về các bộ nhớ đệm ở vị trí được chỉ định.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"

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

Lấy siêu dữ liệu về bộ nhớ đệm

Bạn không thể truy xuất hoặc xem nội dung thực tế được lưu vào bộ nhớ đệm. Tuy nhiên, bạn có thể truy xuất siêu dữ liệu về bộ nhớ đệm rõ ràng, bao gồm name, model, display_name, usage_metadata, create_time, update_time và expire_time.

Bạn cần cung cấp CACHE_ID, đây là phân đoạn cuối cùng trong name tài nguyên đủ điều kiện của bộ nhớ đệm.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

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

Cập nhật TTL hoặc thời gian hết hạn cho bộ nhớ đệm

Khi tạo bộ nhớ đệm rõ ràng, bạn có thể tuỳ ý đặt ttl hoặc expire_time.

  • ttl: TTL (thời gian tồn tại) cho bộ nhớ đệm, cụ thể là số giây và nano giây mà bộ nhớ đệm tồn tại sau khi được tạo hoặc sau khi ttl được cập nhật trước khi hết hạn. Khi bạn đặt ttl, expireTime của bộ nhớ đệm sẽ tự động cập nhật.

  • expire_time: Một Timestamp (chẳng hạn như 2024-06-30T09:00:00.000000Z) chỉ định ngày và giờ tuyệt đối khi bộ nhớ đệm hết hạn.

Nếu bạn không đặt một trong hai giá trị này, TTL mặc định là 1 giờ. Không có giới hạn tối thiểu hoặc tối đa về TTL.

Đối với các bộ nhớ đệm rõ ràng hiện có, bạn có thể thêm hoặc cập nhật ttl hoặc expire_time. Bạn cần cung cấp CACHE_ID, đây là phân đoạn cuối cùng trong name tài nguyên đủ điều kiện của bộ nhớ đệm.

Cập nhật ttl

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
TTL="CACHE_TIME_TO_LIVE"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "ttl": "'$TTL'"
}'

Cập nhật expire_time

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
EXPIRE_TIME="ABSOLUTE_TIME_CACHE_EXPIRES"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "expire_time": "'$EXPIRE_TIME'"
}'

Xoá bộ nhớ đệm

Khi không cần bộ nhớ đệm rõ ràng nữa, bạn có thể xoá bộ nhớ đệm đó.

Bạn cần cung cấp CACHE_ID, đây là phân đoạn cuối cùng trong name tài nguyên đủ điều kiện của bộ nhớ đệm.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

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


Giá cho tính năng lưu vào bộ nhớ đệm rõ ràng

Lưu vào bộ nhớ đệm rõ ràng là một tính năng có tính phí được thiết kế để giảm chi phí. Giá được xác định dựa trên các yếu tố sau:

  • Mã thông báo đầu vào để tạo bộ nhớ đệm: Đối với cả hoạt động lưu vào bộ nhớ đệm ngầm và lưu vào bộ nhớ đệm rõ ràng, bạn sẽ bị tính phí cho mã thông báo đầu vào được dùng để tạo bộ nhớ đệm theo giá mã thông báo đầu vào tiêu chuẩn.

  • Lưu trữ bộ nhớ đệm: Đối với việc lưu vào bộ nhớ đệm rõ ràng, cũng có chi phí lưu trữ dựa trên thời gian lưu trữ bộ nhớ đệm. Không có chi phí lưu trữ cho hoạt động lưu vào bộ nhớ đệm ngầm. Để biết thêm thông tin, hãy xem giá của Vertex AI Gemini API.

  • Sử dụng nội dung được lưu vào bộ nhớ đệm: Việc lưu vào bộ nhớ đệm một cách rõ ràng đảm bảo bạn được giảm giá khi tham chiếu đến bộ nhớ đệm rõ ràng, tức là bạn được giảm giá đối với các mã thông báo đầu vào khi chúng tham chiếu đến một bộ nhớ đệm hiện có. Đối với các mẫu Gemini 2.5 trở lên, mức chiết khấu này là 90%.

Số lượng mã thông báo trong phần được lưu vào bộ nhớ đệm của dữ liệu đầu vào được cung cấp trong trường cachedContentTokenCount trong siêu dữ liệu của một phản hồi.