การแคชบริบท

ในเวิร์กโฟลว์ AI ทั่วไป คุณอาจส่งโทเค็นอินพุตเดียวกันซ้ำๆ ไปยังโมเดล Gemini API มีกลไกการแคช 2 แบบที่แตกต่างกัน ดังนี้

  • การแคชโดยนัย (เปิดใช้โดยอัตโนมัติในโมเดล Gemini 2.5 ไม่รับประกันการประหยัดค่าใช้จ่าย)
  • การแคชอย่างชัดเจน (เปิดใช้ได้ด้วยตนเองในโมเดลส่วนใหญ่ รับประกันการประหยัดค่าใช้จ่าย)

การแคชอย่างชัดเจนมีประโยชน์ในกรณีที่คุณต้องการรับประกันการประหยัดค่าใช้จ่าย แต่ต้องมีการทำงานของนักพัฒนาซอฟต์แวร์เพิ่มเติม

การแคชโดยนัย

ระบบจะเปิดใช้การแคชโดยนัยโดยค่าเริ่มต้นสำหรับโมเดล Gemini 2.5 ทั้งหมด เราจะส่งต่อส่วนลดค่าใช้จ่ายโดยอัตโนมัติ หากคำขอของคุณเข้าถึงแคช คุณไม่จำเป็นต้องดำเนินการใดๆ เพื่อเปิดใช้ฟีเจอร์นี้ โดยจะมีผลตั้งแต่วันที่ 8 พฤษภาคม 2025 จำนวนโทเค็นอินพุตขั้นต่ำสำหรับการแคชบริบทคือ 1,024 สำหรับ 2.5 Flash และ 4,096 สำหรับ 2.5 Pro

วิธีเพิ่มโอกาสในการเข้าถึงแคชโดยนัย

  • ลองวางเนื้อหาขนาดใหญ่และเนื้อหาทั่วไปไว้ที่จุดเริ่มต้นของพรอมต์
  • ลองส่งคำขอที่มีคำนำหน้าที่คล้ายกันในช่วงเวลาสั้นๆ

คุณดูจำนวนโทเค็นที่แคชตรงได้ในฟิลด์ usage_metadata ของออบเจ็กต์การตอบกลับ

การแคชที่ชัดเจน

การใช้ฟีเจอร์การแคชอย่างชัดเจนของ Gemini API ช่วยให้คุณส่งเนื้อหาบางอย่างไปยังโมเดลได้ครั้งเดียว แคชโทเค็นอินพุต แล้วอ้างอิงโทเค็นที่แคชไว้สำหรับคำขอที่ตามมา เมื่อมีปริมาณการใช้งานในระดับหนึ่ง การใช้โทเค็นที่แคชไว้จะมีต้นทุนต่ำกว่า การส่งชุดโทเค็นเดียวกันซ้ำๆ

เมื่อแคชชุดโทเค็น คุณสามารถเลือกระยะเวลาที่ต้องการให้แคช มีอยู่ก่อนที่ระบบจะลบโทเค็นโดยอัตโนมัติ ระยะเวลาการแคชนี้เรียกว่า Time to Live (TTL) หากไม่ได้ตั้งค่า ระบบจะใช้ TTL เป็นค่าเริ่มต้นที่ 1 ชั่วโมง ค่าใช้จ่ายในการแคชขึ้นอยู่กับขนาดโทเค็นอินพุตและระยะเวลาที่คุณต้องการให้โทเค็น คงอยู่

ส่วนนี้ถือว่าคุณได้ติดตั้ง Gemini SDK (หรือติดตั้ง curl) แล้ว และได้กำหนดค่าคีย์ API ตามที่แสดงในคู่มือเริ่มต้นฉบับย่อแล้ว

สร้างเนื้อหาโดยใช้แคช

ตัวอย่างต่อไปนี้แสดงวิธีสร้างเนื้อหาโดยใช้คำสั่งของระบบและไฟล์วิดีโอที่แคชไว้

วิดีโอ

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)

แสดงรายการแคช

คุณไม่สามารถดึงหรือดูเนื้อหาที่แคชไว้ได้ แต่สามารถดึงข้อมูลเมตาของแคช (name, model, display_name, usage_metadata, create_time, update_time และ expire_time) ได้

หากต้องการแสดงข้อมูลเมตาสำหรับแคชที่อัปโหลดทั้งหมด ให้ใช้ CachedContent.list()

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

หากต้องการดึงข้อมูลเมตาสำหรับออบเจ็กต์แคช 1 รายการ หากทราบชื่อ ให้ใช้ get ดังนี้

client.caches.get(name=name)

อัปเดตแคช

คุณตั้งค่า ttl หรือ expire_time ใหม่สำหรับแคชได้ ไม่รองรับการเปลี่ยนแปลงอื่นๆ เกี่ยวกับแคช

ตัวอย่างต่อไปนี้แสดงวิธีอัปเดต ttl ของแคชโดยใช้ client.caches.update()

from google import genai
from google.genai import types

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

หากต้องการตั้งค่าเวลาหมดอายุ ระบบจะยอมรับทั้งdatetimeออบเจ็กต์ หรือสตริงวันที่และเวลาในรูปแบบ ISO (dt.isoformat() เช่น 2025-01-27T16:02:36.473528+00:00) เวลาของคุณต้องมีเขตเวลา (datetime.utcnow() ไม่ได้แนบเขตเวลา datetime.now(datetime.timezone.utc) แนบเขตเวลา)

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
  )
)

ลบแคช

บริการแคชมีฟังก์ชันการลบเพื่อนำเนื้อหาออกจากแคชด้วยตนเอง ตัวอย่างต่อไปนี้แสดงวิธีลบแคช

client.caches.delete(cache.name)

การแคชอย่างชัดเจนโดยใช้ไลบรารี OpenAI

หากใช้ไลบรารี OpenAI คุณจะเปิดใช้ การแคชอย่างชัดเจนได้โดยใช้พร็อพเพอร์ตี้ cached_content ใน extra_body

กรณีที่ควรใช้การแคชที่ชัดเจน

การแคชบริบทเหมาะอย่างยิ่งกับสถานการณ์ที่คำขอที่สั้นกว่าอ้างอิงบริบทเริ่มต้นที่สำคัญซ้ำๆ พิจารณาใช้ การแคชบริบทสำหรับกรณีการใช้งานต่อไปนี้

  • แชทบ็อตที่มีคำสั่งของระบบที่ครอบคลุม
  • การวิเคราะห์ไฟล์วิดีโอขนาดยาวซ้ำๆ
  • การค้นหาที่เกิดซ้ำกับชุดเอกสารขนาดใหญ่
  • การวิเคราะห์ที่เก็บโค้ดหรือการแก้ไขข้อบกพร่องบ่อยๆ

การแคชที่ชัดเจนช่วยลดค่าใช้จ่ายได้อย่างไร

การแคชบริบทเป็นฟีเจอร์แบบชำระเงินที่ออกแบบมาเพื่อลดต้นทุนในการดำเนินงานโดยรวม การเรียกเก็บเงินจะอิงตามปัจจัยต่อไปนี้

  1. จำนวนโทเค็นแคช: จำนวนโทเค็นอินพุตที่แคชไว้ ซึ่งจะเรียกเก็บเงินใน อัตราที่ลดลงเมื่อรวมไว้ในพรอมต์ที่ตามมา
  2. ระยะเวลาการจัดเก็บ: ระยะเวลาที่จัดเก็บโทเค็นที่แคชไว้ (TTL) เรียกเก็บเงินตามระยะเวลา TTL ของจำนวนโทเค็นที่แคชไว้ ไม่มีขอบเขตขั้นต่ำ หรือสูงสุดสำหรับ TTL
  3. ปัจจัยอื่นๆ: มีการเรียกเก็บเงินอื่นๆ เช่น สำหรับโทเค็นอินพุตและเอาต์พุตที่ไม่ได้แคช

ดูรายละเอียดราคาล่าสุดได้ที่หน้าการกำหนดราคาของ Gemini API ดูวิธีนับโทเค็นได้ที่คำแนะนำเกี่ยวกับโทเค็น

ข้อควรพิจารณาเพิ่มเติม

โปรดคำนึงถึงข้อควรพิจารณาต่อไปนี้เมื่อใช้การแคชบริบท

  • จำนวนโทเค็นอินพุตขั้นต่ำสำหรับการแคชบริบทคือ 1,024 สำหรับ 2.5 Flash และ 4,096 สำหรับ 2.5 Pro สูงสุดจะเท่ากับค่าสูงสุดของโมเดลที่ระบุ (ดูข้อมูลเพิ่มเติมเกี่ยวกับการนับโทเค็นได้ที่คู่มือโทเค็น)
  • โมเดลไม่ได้แยกความแตกต่างระหว่างโทเค็นที่แคชไว้กับโทเค็นอินพุตปกติ เนื้อหาที่แคชไว้จะเป็นคำนำหน้าของพรอมต์
  • ไม่มีขีดจำกัดด้านอัตราหรือการใช้งานพิเศษสำหรับการแคชบริบท โดยจะใช้ขีดจำกัดด้านอัตรามาตรฐานสำหรับ GenerateContent และขีดจำกัดโทเค็นจะรวมโทเค็นที่แคชไว้ด้วย
  • ระบบจะแสดงจำนวนโทเค็นที่แคชไว้ใน usage_metadata จากการดำเนินการสร้าง รับ และแสดงรายการของบริการแคช รวมถึงใน GenerateContent เมื่อใช้แคช