Armazenamento em cache de contexto

Em um fluxo de trabalho típico de IA, é possível passar os mesmos tokens de entrada repetidamente um modelo. Com o recurso de armazenamento em cache de contexto da API Gemini, é possível transmitir ao modelo uma vez, armazenar em cache os tokens de entrada e consultar os tokens armazenados para as solicitações subsequentes. Em determinados volumes, o uso de tokens em cache tem um custo menor do que transmitir o mesmo conjunto de tokens repetidamente.

Quando você armazena um conjunto de tokens em cache, é possível escolher por quanto tempo quer que o cache antes da exclusão automática. A duração desse armazenamento em cache chamada Time to Live (TTL). Se ela não for definida, o TTL será definido como uma hora por padrão. A de armazenamento em cache depende do tamanho do token de entrada para que os tokens persistam.

O armazenamento em cache de contexto tem suporte ao Gemini 1.5 Pro e ao Gemini 1.5 Flash.

Quando usar o armazenamento em cache de contexto

O armazenamento em cache de contexto é particularmente adequado para cenários em que um contexto inicial substancial é referenciado repetidamente por solicitações mais curtas. Use armazenamento em cache de contexto para casos de uso como estes:

  • Chatbots com instruções detalhadas do sistema
  • Análise repetitiva de arquivos de vídeo longos
  • Consultas recorrentes em grandes conjuntos de documentos
  • Análise frequente do repositório de código ou correção de bugs

Como o armazenamento em cache reduz custos

O armazenamento em cache de contexto é um recurso pago projetado para reduzir os custos operacionais gerais. O faturamento é baseado nos seguintes fatores:

  1. Contagem de tokens de cache: o número de tokens de entrada armazenados em cache, faturados com uma taxa reduzida quando incluído nos comandos subsequentes.
  2. Duração do armazenamento:por quanto tempo os tokens em cache ficam armazenados (TTL), faturado com base na duração do TTL da contagem de tokens em cache. Não há valor mínimo ou limites máximos do TTL.
  3. Outros fatores: outras cobranças se aplicam, como tokens de entrada não armazenados em cache e tokens de saída.

Para conferir detalhes atualizados, consulte a página de preços da API Gemini . Para saber como contar tokens, consulte a documentação guia.

Como usar o armazenamento em cache de contexto

Esta seção pressupõe que você tenha instalado um SDK do Gemini e configurado uma API conforme mostrado no guia de início rápido.

Gerar conteúdo usando um cache

O exemplo a seguir mostra como gerar conteúdo usando um sistema em cache instruções e vídeo.

import os
import google.generativeai as genai
from google.generativeai import caching
import datetime
import time

# Get your API key from https://aistudio.google.com/app/apikey
# and access your API key as an environment variable.
# To authenticate from a Colab, see
# https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb
genai.configure(api_key=os.environ['API_KEY'])

# Download video file
# curl -O https://storage.googleapis.com/generativeai-downloads/data/Sherlock_Jr_FullMovie.mp4

path_to_video_file = 'Sherlock_Jr_FullMovie.mp4'

# Upload the video using the Files API
video_file = genai.upload_file(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 = genai.get_file(video_file.name)

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

# Create a cache with a 5 minute TTL
cache = caching.CachedContent.create(
    model='models/gemini-1.5-flash-001',
    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=datetime.timedelta(minutes=5),
)

# Construct a GenerativeModel which uses the created cache.
model = genai.GenerativeModel.from_cached_content(cached_content=cache)

# Query the model
response = model.generate_content([(
    'Introduce different characters in the movie by describing '
    'their personality, looks, and names. Also list the timestamps '
    'they were introduced for the first time.')])

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)

Listar caches

Não é possível recuperar ou visualizar conteúdo em cache, mas você pode recuperar armazenar metadados em cache (name, model, display_name, usage_metadata, create_time, update_time e expire_time).

Para listar os metadados de todos os caches enviados, use CachedContent.list():

for c in caching.CachedContent.list():
  print(c)

Atualizar um cache

É possível definir um novo ttl ou expire_time para um cache. Mudar qualquer outra informação sobre o cache não é suportado.

O exemplo a seguir mostra como atualizar o ttl de um cache usando CachedContent.update().

import datetime

cache.update(ttl=datetime.timedelta(hours=2))

Excluir um cache

O serviço de armazenamento em cache fornece uma operação de exclusão para remover manualmente o conteúdo do cache. O exemplo a seguir mostra como excluir um cache usando CachedContent.delete():

cache.delete()

Outras considerações

Ao usar o armazenamento em cache de contexto, tenha em mente as seguintes considerações:

  • A contagem mínima de tokens de entrada para armazenamento em cache de contexto é 32.768, e o maxim é igual ao máximo do modelo fornecido. (Para mais informações sobre contagem de tokens, consulte o guia de tokens.
  • O modelo não faz distinção entre tokens em cache e tokens tokens de entrada. O conteúdo em cache é simplesmente um prefixo do prompt.
  • Não há taxas especiais ou limites de uso no armazenamento em cache de contexto; o padrão os limites de taxa para GenerateContent são aplicados e os limites de token incluem em cache tokens.
  • O número de tokens em cache é retornado no usage_metadata da as operações create, get e list do serviço de cache, e também GenerateContent ao usar o cache.