Lưu ngữ cảnh vào bộ nhớ đệm

Trong quy trình AI thông thường, bạn có thể truyền đi truyền lại các mã thông báo đầu vào giống nhau cho một mô hình. Gemini API cung cấp 2 cơ chế lưu vào bộ nhớ đệm:

  • Lưu vào bộ nhớ đệm ngầm (tự động bật trên các mô hình Gemini 2.5, không đảm bảo tiết kiệm chi phí)
  • Lưu vào bộ nhớ đệm một cách rõ ràng (có thể bật theo cách thủ công trên hầu hết các mô hình, đảm bảo tiết kiệm chi phí)

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í, nhưng cần thêm một số công việc cho nhà phát triển.

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

Tính năng lưu vào bộ nhớ đệm ngầm được bật theo mặc định cho tất cả các mô hình Gemini 2.5. Chúng tôi tự động chuyển các khoản tiết kiệm chi phí nếu yêu cầu của bạn truy cập vào bộ nhớ đệm. Bạn không cần làm gì để bật tính năng này. Chính sách này có hiệu lực từ ngày 8 tháng 5 năm 2025. Số lượng mã thông báo đầu vào tối thiểu để lưu vào bộ nhớ đệm theo bối cảnh là 1.024 đối với 2.5 Flash và 4.096 đối với 2.5 Pro.

Để tăng cơ hội đạt được lượt truy cập bộ nhớ đệm ngầm:

  • Hãy thử đặt nội dung lớn và phổ biến ở đầ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

Bạn có thể xem số lượng mã thông báo là lượt truy cập vào bộ nhớ đệm trong trường usage_metadata của đối tượng phản hồi.

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

Khi sử dụng tính năng lưu vào bộ nhớ đệm rõ ràng của Gemini API, bạn có thể truyền một số nội dung đến mô hình một lần, lưu mã thông báo đầu vào vào bộ nhớ đệm, sau đó tham chiếu đến mã thông báo đã lưu vào bộ nhớ đệm cho các yêu cầu tiếp theo. Ở một số lượng nhất định, việc sử dụng mã thông báo được lưu vào bộ nhớ đệm sẽ có chi phí thấp hơn so với việc truyền cùng một tập hợp mã thông báo nhiều lần.

Khi lưu trữ một nhóm mã thông báo vào bộ nhớ đệm, bạn có thể chọn khoảng thời gian bạn muốn bộ nhớ đệm tồn tại trước khi mã thông báo tự động bị xoá. Khoảng thời gian lưu vào bộ nhớ đệm này được gọi là thời gian tồn tại (TTL). Nếu bạn không đặt, TTL sẽ mặc định là 1 giờ. Chi phí lưu vào bộ nhớ đệm phụ thuộc vào kích thước mã thông báo đầu vào và thời gian bạn muốn mã thông báo duy trì.

Phần này giả định rằng bạn đã cài đặt Gemini SDK (hoặc đã cài đặt curl) và bạn đã định cấu hình khoá API, như trong phần bắt đầu nhanh.

Tạo nội dung bằng bộ nhớ đệm

Ví dụ sau đây cho biết cách tạo nội dung bằng chỉ dẫn hệ thống và tệp video được lưu vào bộ nhớ đệm.

Video

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

client = genai.Client()

# Download video file
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
  with path_to_video_file.open('wb') as wf:
    response = requests.get(url, stream=True)
    for chunk in response.iter_content(chunk_size=32768):
      wf.write(chunk)

# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)

# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
  print('Waiting for video to be processed.')
  time.sleep(2)
  video_file = client.files.get(name=video_file.name)

print(f'Video processing complete: {video_file.uri}')

# You must use an explicit version suffix: "-flash-001", not just "-flash".
model='models/gemini-2.0-flash-001'

# Create a cache with a 5 minute TTL
cache = client.caches.create(
    model=model,
    config=types.CreateCachedContentConfig(
      display_name='sherlock jr movie', # used to identify the cache
      system_instruction=(
          'You are an expert video analyzer, and your job is to answer '
          'the user\'s query based on the video file you have access to.'
      ),
      contents=[video_file],
      ttl="300s",
  )
)

# Construct a GenerativeModel which uses the created cache.
response = client.models.generate_content(
  model = model,
  contents= (
    'Introduce different characters in the movie by describing '
    'their personality, looks, and names. Also list the timestamps '
    'they were introduced for the first time.'),
  config=types.GenerateContentConfig(cached_content=cache.name)
)

print(response.usage_metadata)

# The output should look something like this:
#
# prompt_token_count: 696219
# cached_content_token_count: 696190
# candidates_token_count: 214
# total_token_count: 696433

print(response.text)

PDF

from google import genai
from google.genai import types
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"

# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

document = client.files.upload(
  file=doc_io,
  config=dict(mime_type='application/pdf')
)

model_name = "gemini-2.0-flash-001"
system_instruction = "You are an expert analyzing transcripts."

# Create a cached content object
cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
      system_instruction=system_instruction,
      contents=[document],
    )
)

# Display the cache details
print(f'{cache=}')

# Generate content using the cached prompt and document
response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

# (Optional) Print usage metadata for insights into the API call
print(f'{response.usage_metadata=}')

# Print the generated text
print('\n\n', response.text)

Liệt kê bộ nhớ đệm

Bạn không thể truy xuất hoặc xem nội dung trong bộ nhớ đệm, nhưng có thể truy xuất siêu dữ liệu bộ nhớ đệm (name, model, display_name, usage_metadata, create_time, update_time và expire_time).

Để liệt kê siêu dữ liệu cho tất cả bộ nhớ đệm đã tải lên, hãy sử dụng CachedContent.list():

for cache in client.caches.list():
  print(cache)

Để tìm nạp siêu dữ liệu cho một đối tượng trong bộ nhớ đệm, nếu bạn biết tên của đối tượng đó, hãy sử dụng get:

client.caches.get(name=name)

Cập nhật bộ nhớ đệm

Bạn có thể đặt ttl hoặc expire_time mới cho bộ nhớ đệm. Không hỗ trợ việc thay đổi bất kỳ thông tin nào khác về bộ nhớ đệm.

Ví dụ sau đây cho thấy cách cập nhật ttl của một bộ nhớ đệm bằng client.caches.update().

from google import genai
from google.genai import types

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      ttl='300s'
  )
)

Để đặt thời gian hết hạn, phương thức này sẽ chấp nhận đối tượng datetime hoặc chuỗi ngày giờ theo định dạng ISO (dt.isoformat(), chẳng hạn như 2025-01-27T16:02:36.473528+00:00). Thời gian của bạn phải bao gồm múi giờ (datetime.utcnow() không đính kèm múi giờ, datetime.now(datetime.timezone.utc) có đính kèm múi giờ).

from google import genai
from google.genai import types
import datetime

# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      expire_time=in10min
  )
)

Xoá bộ nhớ đệm

Dịch vụ lưu vào bộ nhớ đệm cung cấp một thao tác xoá để xoá nội dung khỏi bộ nhớ đệm theo cách thủ công. Ví dụ sau đây cho thấy cách xoá bộ nhớ đệm:

client.caches.delete(cache.name)

Bộ nhớ đệm rõ ràng bằng thư viện OpenAI

Nếu đang dùng thư viện OpenAI, bạn có thể bật tính năng lưu vào bộ nhớ đệm rõ ràng bằng cách dùng thuộc tính cached_content trên extra_body.

Trường hợp sử dụng tính năng lưu vào bộ nhớ đệm rõ ràng

Tính năng lưu vào bộ nhớ đệm theo bối cảnh đặc biệt phù hợp với những trường hợp mà một ngữ cảnh ban đầu đáng kể được các yêu cầu ngắn hơn tham chiếu nhiều lần. Hãy cân nhắc sử dụng tính năng lưu vào bộ nhớ đệm theo bối cảnh cho các trường hợp sử dụng như:

  • Chatbot có hướng dẫn chi tiết về hệ thống
  • Phân tích lặp đi lặp lại các tệp video dài
  • Truy vấn định kỳ đối với các tập tài liệu lớn
  • Thường xuyên phân tích kho lưu trữ mã hoặc sửa lỗi

Cách bộ nhớ đệm rõ ràng giúp giảm chi phí

Lưu vào bộ nhớ đệm theo bối cảnh là một tính năng có tính phí được thiết kế để giảm chi phí vận hành tổng thể. Việc tính phí dựa trên các yếu tố sau:

  1. Số lượng mã thông báo trong bộ nhớ đệm: Số lượng mã thông báo đầu vào được lưu vào bộ nhớ đệm, được tính phí với mức giá thấp hơn khi có trong các câu lệnh tiếp theo.
  2. Thời gian lưu trữ: Khoảng thời gian lưu trữ mã thông báo được lưu vào bộ nhớ đệm (TTL), được tính phí dựa trên thời lượng TTL của số lượng mã thông báo được lưu vào bộ nhớ đệm. Không có giới hạn tối thiểu hoặc tối đa về TTL.
  3. Các yếu tố khác: Các khoản phí khác được áp dụng, chẳng hạn như đối với mã thông báo đầu vào và đầu ra không được lưu vào bộ nhớ đệm.

Để biết thông tin chi tiết mới nhất về giá, hãy tham khảo trang định giá của Gemini API. Để tìm hiểu cách đếm mã thông báo, hãy xem Hướng dẫn về mã thông báo.

Các yếu tố cần cân nhắc khác

Khi sử dụng tính năng lưu vào bộ nhớ đệm theo bối cảnh, hãy lưu ý những điểm sau:

  • Số lượng mã thông báo đầu vào tối thiểu để lưu vào bộ nhớ đệm theo bối cảnh là 1.024 cho 2.5 Flash và 2.048 cho 2.5 Pro. Tối đa cũng giống như mức tối đa của mô hình đã cho. (Để biết thêm thông tin về cách đếm mã thông báo, hãy xem Hướng dẫn về mã thông báo).
  • Mô hình này không phân biệt giữa các mã thông báo được lưu vào bộ nhớ đệm và các mã thông báo đầu vào thông thường. Nội dung được lưu vào bộ nhớ đệm là tiền tố của câu lệnh.
  • Không có giới hạn đặc biệt về tốc độ hoặc mức sử dụng đối với tính năng lưu vào bộ nhớ đệm theo bối cảnh; các giới hạn tốc độ tiêu chuẩn đối với GenerateContent sẽ được áp dụng và giới hạn mã thông báo bao gồm cả mã thông báo được lưu vào bộ nhớ đệm.
  • Số lượng mã thông báo được lưu vào bộ nhớ đệm sẽ được trả về trong usage_metadata từ các thao tác tạo, nhận và liệt kê của dịch vụ bộ nhớ đệm, cũng như trong GenerateContent khi sử dụng bộ nhớ đệm.