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

Trong quy trình làm việc thông thường của AI, bạn có thể truyền cùng một mã thông báo đầu vào lặp đi lặp lại vào mô hình. Khi sử dụng tính năng lưu ngữ cảnh API Gemini vào bộ nhớ đệm, bạn có thể truyền một số nội dung vào 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 các 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 một tập hợp 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 các 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 giá trị này, 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à khoảng thời gian bạn muốn mã thông báo tồn tại.

Tính năng lưu ngữ cảnh vào bộ nhớ đệm hỗ trợ cả Gemini 1.5 Pro và Gemini 1.5 Flash.

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

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

  • Chatbot có hướng dẫn hệ thống chi tiết
  • Phân tích 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 lưu vào bộ nhớ đệm 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 tổng chi phí vận hành. Hệ thống tính phí dựa trên các yếu tố sau:

  1. Số lượng mã thông báo được lưu vào 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í theo mức giá giảm khi được đưa vào các lời nhắc tiếp theo.
  2. Thời lượng 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 đối với TTL.
  3. Các yếu tố khác: Các khoản phí khác sẽ áp dụng, chẳng hạn như đối với mã thông báo đầu vào và mã thông báo đầ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 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ách sử dụng tính năng lưu vào bộ nhớ đệm ngữ cảnh

Phần này giả định rằng bạn đã cài đặt SDK Gemini (hoặc đã cài đặt curl) và đã đị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 cách sử dụng tệp video và hướng dẫn hệ thống được lưu vào bộ nhớ đệm.

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

# Get your API key from https://aistudio.google.com/app/apikey
# Put it in a "GOOGLE_API_KEY" environment variable.
# For more details, see
# https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb
client = genai.Client()

# Download video file
url = 'https://storage.googleapis.com/generativeai-downloads/data/Sherlock_Jr_FullMovie.mp4'
path_to_video_file = pathlib.Path('Sherlock_Jr_FullMovie.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(path=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-1.5-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)

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

Bạn không thể truy xuất hoặc xem nội dung được lưu vào 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_timeexpire_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 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ợ thay đổi bất kỳ nội dung nào khác về bộ nhớ đệm.

Ví dụ sau đây cho thấy cách cập nhật ttl của bộ nhớ đệm bằng cách sử dụ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, bạn có thể 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) đí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 thao tác xoá để xoá nội dung khỏi bộ nhớ đệm theo cách thủ công. Ví dụ sau đây cho biết cách xoá bộ nhớ đệm:

client.caches.delete(cache.name)

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

Hãy lưu ý những điều sau khi sử dụng tính năng lưu vào bộ nhớ đệm ngữ cảnh:

  • Số lượng mã thông báo đầu vào tối thiểu để lưu vào bộ nhớ đệm ngữ cảnh là 32.768 và số lượng mã thông báo đầu vào tối đa giống với số lượng mã thông báo đầu vào tối đa cho mô hình đã cho. (Để biết thêm về cách tính 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 mã thông báo được lưu vào bộ nhớ đệm và mã thông báo đầu vào thông thường. Nội dung được lưu vào bộ nhớ đệm chỉ là một tiền tố của lời nhắc.
  • Không có giới hạn về tốc độ hoặc giới hạn sử dụng đặc biệt đối với việc lưu ngữ cảnh vào bộ nhớ đệm; các giới hạn tốc độ tiêu chuẩn cho GenerateContent sẽ á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 được trả về trong usage_metadata từ các thao tác tạo, lấy và liệt kê của dịch vụ bộ nhớ đệm, cũng như trong GenerateContent khi sử dụng bộ nhớ đệm.