In un tipico workflow di AI, potresti passare gli stessi token di input più e più volte a un modello. L'API Gemini offre due diversi meccanismi di memorizzazione nella cache:
- Memorizzazione implicita nella cache (attivata automaticamente sui modelli Gemini 2.5, senza garanzia di risparmio sui costi)
- Memorizzazione nella cache esplicita (può essere attivata manualmente sulla maggior parte dei modelli, garanzia di risparmio sui costi)
La memorizzazione nella cache esplicita è utile nei casi in cui vuoi garantire un risparmio sui costi, ma con un po' di lavoro aggiuntivo per gli sviluppatori.
Memorizzazione nella cache implicita
La memorizzazione nella cache implicita è abilitata per impostazione predefinita per tutti i modelli Gemini 2.5. Trasmettiamo automaticamente i risparmi sui costi se la tua richiesta raggiunge le cache. Non devi fare nulla per abilitare questa funzionalità. È in vigore dall'8 maggio 2025. Il numero minimo di token di input per la memorizzazione nella cache del contesto è 1024 per 2.5 Flash e 4096 per 2.5 Pro.
Per aumentare le probabilità di un successo implicito della cache:
- Prova a inserire contenuti grandi e comuni all'inizio del prompt.
- Prova a inviare richieste con prefisso simile in un breve periodo di tempo
Puoi visualizzare il numero di token che sono stati hit della cache nel campo
usage_metadata dell'oggetto risposta.
Memorizzazione nella cache esplicita
Utilizzando la funzionalità di memorizzazione nella cache esplicita dell'API Gemini, puoi passare alcuni contenuti al modello una sola volta, memorizzare nella cache i token di input e poi fare riferimento ai token memorizzati nella cache per le richieste successive. A determinati volumi, l'utilizzo di token memorizzati nella cache è meno costoso rispetto al passaggio ripetuto dello stesso corpus di token.
Quando memorizzi nella cache un insieme di token, puoi scegliere per quanto tempo vuoi che la cache esista prima che i token vengano eliminati automaticamente. Questa durata della memorizzazione nella cache è chiamata durata (TTL). Se non viene impostato, il TTL è impostato su 1 ora per impostazione predefinita. Il costo della memorizzazione nella cache dipende dalle dimensioni dei token di input e dalla durata di permanenza dei token.
Questa sezione presuppone che tu abbia installato un SDK Gemini (o che tu abbia installato curl) e che tu abbia configurato una chiave API, come mostrato nella guida rapida.
Generare contenuti utilizzando una cache
L'esempio seguente mostra come generare contenuti utilizzando un'istruzione di sistema e un file video memorizzati nella cache.
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)
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)
Elenca cache
Non è possibile recuperare o visualizzare i contenuti memorizzati nella cache, ma puoi recuperare
i metadati della cache (name, model, display_name, usage_metadata,
create_time, update_time e expire_time).
Per elencare i metadati di tutte le cache caricate, utilizza CachedContent.list():
for cache in client.caches.list():
print(cache)
Per recuperare i metadati di un oggetto cache, se ne conosci il nome, utilizza get:
client.caches.get(name=name)
Aggiornare una cache
Puoi impostare un nuovo ttl o expire_time per una cache. La modifica di qualsiasi altro aspetto
della cache non è supportata.
L'esempio seguente mostra come aggiornare ttl di una cache utilizzando
client.caches.update().
from google import genai
from google.genai import types
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
ttl='300s'
)
)
Per impostare l'ora di scadenza, accetta un oggetto datetime
o una stringa di data e ora in formato ISO (dt.isoformat(), ad esempio
2025-01-27T16:02:36.473528+00:00). L'ora deve includere un fuso orario
(datetime.utcnow() non aggiunge un fuso orario,
datetime.now(datetime.timezone.utc) aggiunge un fuso orario).
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
)
)
Eliminare una cache
Il servizio di memorizzazione nella cache fornisce un'operazione di eliminazione per rimuovere manualmente i contenuti dalla cache. L'esempio seguente mostra come eliminare una cache:
client.caches.delete(cache.name)
Memorizzazione nella cache esplicita utilizzando la libreria OpenAI
Se utilizzi una libreria OpenAI, puoi attivare
la memorizzazione nella cache esplicita utilizzando la proprietà cached_content su
extra_body.
Quando utilizzare la memorizzazione esplicita nella cache
La memorizzazione nella cache del contesto è particolarmente adatta agli scenari in cui un contesto iniziale sostanziale viene referenziato ripetutamente da richieste più brevi. Valuta la possibilità di utilizzare la memorizzazione nella cache del contesto per casi d'uso come:
- Chatbot con istruzioni di sistema dettagliate
- Analisi ripetitiva di file video di grandi dimensioni
- Query ricorrenti su grandi set di documenti
- Analisi frequente del repository di codici o correzione di bug
In che modo la memorizzazione esplicita nella cache riduce i costi
La memorizzazione nella cache del contesto è una funzionalità a pagamento progettata per ridurre i costi operativi complessivi. La fatturazione si basa sui seguenti fattori:
- Conteggio token cache:il numero di token di input memorizzati nella cache, fatturati a una tariffa ridotta se inclusi nei prompt successivi.
- Durata dell'archiviazione:il periodo di tempo in cui i token memorizzati nella cache vengono archiviati (TTL), fatturato in base alla durata TTL del conteggio dei token memorizzati nella cache. Non esistono limiti minimi o massimi per il TTL.
- Altri fattori: si applicano altri addebiti, ad esempio per i token di input non memorizzati nella cache e per i token di output.
Per i dettagli aggiornati sui prezzi, consulta la pagina dei prezzi dell'API Gemini. Per scoprire come conteggiare i token, consulta la guida ai token.
Considerazioni aggiuntive
Quando utilizzi la memorizzazione nella cache del contesto, tieni presente le seguenti considerazioni:
- Il conteggio dei token di input minimo per la memorizzazione nella cache del contesto è 1024 per 2.5 Flash e 2048 per 2.5 Pro. Il massimo è lo stesso del massimo per il modello specificato. Per saperne di più sul conteggio dei token, consulta la guida ai token.
- Il modello non fa distinzione tra token memorizzati nella cache e token di input normali. I contenuti memorizzati nella cache sono un prefisso del prompt.
- Non sono previsti limiti di utilizzo o tariffe speciali per la memorizzazione nella cache del contesto; si applicano i limiti di frequenza standard per
GenerateContente i limiti di token includono i token memorizzati nella cache. - Il numero di token memorizzati nella cache viene restituito in
usage_metadatadalle operazioni di creazione, recupero ed elenco del servizio di cache e anche inGenerateContentquando si utilizza la cache.