การแคชบริบท

Python JavaScript Go REST

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

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

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

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

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

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

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

คุณดูจำนวนโทเค็นที่แคชตรงได้ในฟิลด์ 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 a test video file and save it locally
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():
    path_to_video_file.write_bytes(requests.get(url).content)

# 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':
    time.sleep(2.5)
    video_file = client.files.get(name=video_file.name)

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

model='models/gemini-3-flash-preview'

# Create a cache with a 5 minute TTL (300 seconds)
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",
    )
)

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)

print(response.text)

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

client = genai.Client()

long_context_pdf_path = "https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.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-3-flash-preview"
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],
    )
)

print(f'{cache=}')

response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

print(f'{response.usage_metadata=}')

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 ดูวิธีนับโทเค็นได้ที่คำแนะนำเกี่ยวกับโทเค็น

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

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

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