In un tipico flusso di lavoro di IA, potresti passare più volte gli stessi token di input a un modello. Utilizzando la funzionalità di memorizzazione nella cache del contesto dell'API Gemini, puoi passare alcuni contenuti al modello una 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 ha un costo inferiore rispetto al passaggio ripetuto dello stesso corpus di token.
Quando memorizzi nella cache un insieme di token, puoi scegliere per quanto tempo deve rimanere attiva la cache prima che i token vengano eliminati automaticamente. Questa durata della cache è chiamata durata (TTL). Se non viene impostato, il valore predefinito del TTL è 1 ora. Il costo della memorizzazione nella cache dipende dalle dimensioni del token di input e dal periodo di conservazione dei token.
La memorizzazione nella cache del contesto è supportata sia da Gemini 1.5 Pro che da Gemini 1.5 Flash.
Quando utilizzare la memorizzazione nella cache del contesto
La memorizzazione nella cache del contesto è particolarmente adatta a scenari in cui un contesto iniziale sostanziale viene fatto riferimento 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 insiemi di documenti di grandi dimensioni
- Analisi frequenti del repository di codice o correzione di bug
In che modo la memorizzazione 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:
- Numero di token della cache:il numero di token di input memorizzati nella cache, fatturati a un tariffa ridotta se inclusi nei prompt successivi.
- Durata di archiviazione:il periodo di tempo per cui i token memorizzati nella cache vengono archiviati (TTL), fatturato in base alla durata del TTL del conteggio dei token memorizzati nella cache. Non sono previsti limiti minimi o massimi per il TTL.
- Altri fattori: si applicano altri addebiti, ad esempio per i token di input e di output non memorizzati nella cache.
Per informazioni aggiornate sui prezzi, consulta la pagina dei prezzi dell'API Gemini. Per scoprire come conteggiare i token, consulta la guida ai token.
Come utilizzare la memorizzazione nella cache del contesto
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 introduttiva.
Generare contenuti utilizzando una cache
L'esempio seguente mostra come generare contenuti utilizzando un'istruzione di sistema memorizzata nella cache e un file video.
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)
Elenca le 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 della 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 elemento della cache non è supportata.
L'esempio seguente mostra come aggiornare il 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 la data e l'ora di scadenza, accetta un oggetto datetime
o una stringa data/ora nel formato ISO (dt.isoformat()
, ad esempio 2025-01-27T16:02:36.473528+00:00
). L'ora deve includere un fuso orario (datetime.utcnow()
non ne associa uno, mentre datetime.now(datetime.timezone.utc)
sì).
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)
Considerazioni aggiuntive
Tieni presenti le seguenti considerazioni quando utilizzi la memorizzazione nella cache del contesto:
- Il numero minimo di token di input per la memorizzazione nella cache del contesto è 32.768 e il valore massimo è uguale a quello 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 regolari. I contenuti memorizzati nella cache sono semplicemente un prefisso del prompt.
- Non sono previsti limiti di frequenza o di utilizzo speciali per la memorizzazione nella cache del contesto. Si applicano i limiti di frequenza standard per
GenerateContent
e i limiti di token includono i token memorizzati nella cache. - Il numero di token memorizzati nella cache viene restituito in
usage_metadata
dalle operazioni di creazione, recupero e elenco del servizio cache e anche inGenerateContent
quando si utilizza la cache.