कॉन्टेक्स्ट कैश मेमोरी

Python JavaScript Go REST

एआई के सामान्य वर्कफ़्लो में, एक ही इनपुट टोकन को बार-बार किसी मॉडल को पास किया जा सकता है. Gemini API, कैश मेमोरी की सुविधा के लिए दो अलग-अलग तरीके उपलब्ध कराता है:

• इंप्लिसिट कैश मेमोरी (यह सुविधा, Gemini के ज़्यादातर मॉडल पर अपने-आप चालू हो जाती है. हालांकि, इससे लागत कम होने की कोई गारंटी नहीं है)
• एक्सप्लिसिट कैश मेमोरी (इसे ज़्यादातर मॉडल पर मैन्युअल तरीके से चालू किया जा सकता है. इससे लागत कम करने की गारंटी मिलती है)

एक्सप्लिसिट कैशिंग उन मामलों में फ़ायदेमंद होती है जहां आपको लागत में बचत की गारंटी चाहिए. हालांकि, इसके लिए डेवलपर को कुछ और काम करना पड़ता है.

इंप्लिसिट कैशिंग

डिफ़ॉल्ट रूप से, इंप्लिसिट कैश मेमोरी की सुविधा चालू होती है. यह सुविधा, Gemini के ज़्यादातर मॉडल के लिए उपलब्ध है. अगर आपका अनुरोध कैश मेमोरी से मिलता है, तो हम लागत में हुई बचत को अपने-आप लागू कर देते हैं. इसे चालू करने के लिए, आपको कुछ भी करने की ज़रूरत नहीं है. यह 8 मई, 2025 से लागू होगा. कॉन्टेक्स्ट कैश मेमोरी के लिए, हर मॉडल के हिसाब से कम से कम इनपुट टोकन की संख्या यहां दी गई है:

इंप्लिसिट कैश हिट की संभावना बढ़ाने के लिए:

• अपने प्रॉम्प्ट की शुरुआत में, बड़े और सामान्य कॉन्टेंट को शामिल करें
• कम समय में, एक जैसे प्रीफ़िक्स वाले अनुरोध भेजने की कोशिश करना

जवाब ऑब्जेक्ट के usage_metadata फ़ील्ड में, आपको उन टोकन की संख्या दिखेगी जो कैश मेमोरी में मौजूद थे.

एक्सप्लिसिट कैशिंग

Gemini API की एक्सप्लिसिट कैशिंग सुविधा का इस्तेमाल करके, मॉडल को एक बार कुछ कॉन्टेंट दिया जा सकता है. साथ ही, इनपुट टोकन को कैश मेमोरी में सेव किया जा सकता है. इसके बाद, अगले अनुरोधों के लिए कैश मेमोरी में सेव किए गए टोकन का इस्तेमाल किया जा सकता है. कुछ मामलों में, कैश किए गए टोकन का इस्तेमाल करना, टोकन के एक ही कॉर्पस को बार-बार पास करने की तुलना में कम खर्चीला होता है.

टोकन के सेट को कैश मेमोरी में सेव करते समय, यह चुना जा सकता है कि टोकन के अपने-आप मिटने से पहले, कैश मेमोरी कितने समय तक सेव रहे. कैश मेमोरी में सेव रहने की इस अवधि को टाइम टू लिव (टीटीएल) कहा जाता है. अगर इसे सेट नहीं किया जाता है, तो टीटीएल डिफ़ॉल्ट रूप से एक घंटे पर सेट होता है. कैशिंग की लागत, इनपुट टोकन के साइज़ और टोकन को सेव रखने की अवधि पर निर्भर करती है.

इस सेक्शन में यह माना गया है कि आपने Gemini SDK इंस्टॉल कर लिया है या आपके पास curl इंस्टॉल है. साथ ही, आपने एपीआई पासकोड कॉन्फ़िगर कर लिया है. ऐसा क्विकस्टार्ट में दिखाया गया है.

कैश का इस्तेमाल करके कॉन्टेंट जनरेट करना

यहां दिए गए उदाहरण में, कैश मेमोरी में सेव किए गए सिस्टम के निर्देश और वीडियो फ़ाइल का इस्तेमाल करके कॉन्टेंट जनरेट करने का तरीका बताया गया है.

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)

अगर आपको किसी एक कैश मेमोरी ऑब्जेक्ट का मेटाडेटा चाहिए और आपको उसका नाम पता है, तो get का इस्तेमाल करें:

client.caches.get(name=name)

कैश मेमोरी अपडेट करना

किसी कैश मेमोरी के लिए, नया ttl या expire_time सेट किया जा सकता है. कैश मेमोरी के बारे में कोई और बदलाव नहीं किया जा सकता.

यहां दिए गए उदाहरण में, client.caches.update() का इस्तेमाल करके, कैश मेमोरी के ttl को अपडेट करने का तरीका दिखाया गया है.

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 लाइब्रेरी का इस्तेमाल किया जा रहा है, तो extra_body पर cached_content प्रॉपर्टी का इस्तेमाल करके, एक्सप्लिसिट कैश मेमोरी को चालू किया जा सकता है.

एक्सप्लिसिट कैश मेमोरी का इस्तेमाल कब करना चाहिए

कॉन्टेक्स्ट को कैश मेमोरी में सेव करने की सुविधा, खास तौर पर उन स्थितियों के लिए सही है जहां शुरुआती कॉन्टेक्स्ट के बड़े हिस्से को छोटे अनुरोधों से बार-बार रेफ़र किया जाता है. इन जैसे इस्तेमाल के उदाहरणों के लिए, कॉन्टेक्स्ट कैश मेमोरी का इस्तेमाल करें:

• सिस्टम के निर्देशों के साथ चैटबॉट
• लंबी वीडियो फ़ाइलों का बार-बार विश्लेषण करना
• दस्तावेज़ों के बड़े सेट के ख़िलाफ़ बार-बार की जाने वाली क्वेरी
• कोड रिपॉज़िटरी का बार-बार विश्लेषण करना या गड़बड़ियों को ठीक करना

एक्सप्लिसिट कैशिंग से लागत कैसे कम होती है

कॉन्टेक्स्ट को कैश मेमोरी में सेव करने की सुविधा, पैसे चुकाकर इस्तेमाल की जा सकती है. इसे लागत कम करने के लिए डिज़ाइन किया गया है. बिलिंग इन बातों के आधार पर की जाती है:

1. कैश किए गए टोकन की संख्या: कैश किए गए इनपुट टोकन की संख्या. इन्हें बाद के प्रॉम्प्ट में शामिल करने पर, कम कीमत पर बिल किया जाता है.
2. स्टोरेज की अवधि: कैश मेमोरी में सेव किए गए टोकन को सेव रखने की अवधि (टीटीएल). कैश मेमोरी में सेव किए गए टोकन की संख्या के टीटीएल के आधार पर बिल भेजा जाता है. टीटीएल के लिए, कम से कम या ज़्यादा से ज़्यादा की कोई सीमा नहीं होती.
3. अन्य कारक: अन्य शुल्क लागू होते हैं. जैसे, कैश मेमोरी में सेव न किए गए इनपुट टोकन और आउटपुट टोकन के लिए शुल्क.

कीमत के बारे में अप-टू-डेट जानकारी के लिए, Gemini API के कीमत वाले पेज पर जाएं. टोकन की गिनती करने का तरीका जानने के लिए, टोकन गाइड देखें.

ज़रूरी बातें

कॉन्टेक्स्ट कैश मेमोरी का इस्तेमाल करते समय, इन बातों का ध्यान रखें:

• कॉन्टेक्स्ट कैश मेमोरी के लिए, इनपुट टोकन की कम से कम संख्या मॉडल के हिसाब से अलग-अलग होती है. ज़्यादा से ज़्यादा की वैल्यू, दिए गए मॉडल के लिए ज़्यादा से ज़्यादा वैल्यू के बराबर होती है. (टोकन की गिनती के बारे में ज़्यादा जानने के लिए, टोकन गाइड देखें).
• मॉडल, कैश किए गए टोकन और सामान्य इनपुट टोकन के बीच कोई अंतर नहीं करता है. कैश किया गया कॉन्टेंट, प्रॉम्प्ट का प्रीफ़िक्स होता है.
• कॉन्टेक्स्ट को कैश मेमोरी में सेव करने पर, इस्तेमाल की कोई सीमा या खास शुल्क नहीं लगता. GenerateContent के लिए, दर की स्टैंडर्ड सीमाएं लागू होती हैं. साथ ही, टोकन की सीमाओं में कैश मेमोरी में सेव किए गए टोकन शामिल होते हैं.
• कैश किए गए टोकन की संख्या, कैश सेवा के create, get, और list ऑपरेशनों के usage_metadata में दिखाई जाती है. साथ ही, कैश का इस्तेमाल करते समय GenerateContent में भी यह संख्या दिखती है.